Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FlagAutoModel
✓ from FlagEmbedding import FlagAutoModel
Recommended high-level class for unified embedding model inference.
FlagReranker
✓ from FlagEmbedding import FlagReranker
For loading and using reranker models.
FlagModel
✓ from FlagEmbedding import FlagModel
✗ from FlagEmbedding.FlagModel import FlagModel
While functional, `FlagAutoModel` is often preferred for its unified interface. Older examples or specific use cases might directly use `FlagModel`.
This quickstart demonstrates how to load an embedding model using `FlagAutoModel.from_pretrained()` and generate embeddings for queries and passages. It then shows how to compute similarity scores. Additionally, it provides an example of using `FlagReranker` to compute scores for query-passage pairs. Remember to replace placeholder model names with actual Hugging Face model IDs.
import os
from FlagEmbedding import FlagAutoModel
# You can replace 'BAAI/bge-base-en-v1.5' with other BGE models like 'BAAI/bge-m3'
# Consider setting query_instruction_for_retrieval for optimal performance in retrieval tasks.
# Use use_fp16=True for faster inference on compatible hardware.
# Example for embedding queries and passages
model = FlagAutoModel.from_pretrained(
'BAAI/bge-base-en-v1.5',
query_instruction_for_retrieval="Represent this sentence for searching relevant passages:",
use_fp16=True
)
queries = ["What is FlagEmbedding?", "How to use embedding models?"]
passages = [
"FlagEmbedding maps text to low-dimensional dense vectors for tasks like retrieval.",
"Embedding models can be used to generate vector representations of text.",
"The BGE models are state-of-the-art embedding models."
]
# Encode queries and passages
query_embeddings = model.encode_queries(queries)
passage_embeddings = model.encode_corpus(passages)
print(f"Query embeddings shape: {query_embeddings.shape}")
print(f"Passage embeddings shape: {passage_embeddings.shape}")
# Compute similarity scores (e.g., dot product)
scores = query_embeddings @ passage_embeddings.T
print("Similarity scores:")
print(scores)
# Example for reranking using FlagReranker
from FlagEmbedding import FlagReranker
# Replace with a reranker model like 'BAAI/bge-reranker-base'
reranker = FlagReranker('BAAI/bge-reranker-base', use_fp16=True)
query_passage_pairs = [
['What is AI?', 'Artificial intelligence (AI) is intelligence demonstrated by machines.'],
['What is AI?', 'The quick brown fox jumps over the lazy dog.']
]
ranks = reranker.compute_score(query_passage_pairs)
print("Reranker scores:")
print(ranks)
Debug
Known issues
gotchaFor BGE v1.5 models, using `query_instruction_for_retrieval` is generally recommended for short queries in retrieval tasks for optimal performance. For other tasks (e.g., semantic similarity of short texts), instructions might not be needed or could even degrade performance. While v1.5 models are improved to work without instructions with only slight degradation, explicit instruction is often best practice for retrieval.fixExperiment with `query_instruction_for_retrieval` parameter. For retrieval tasks with short queries, pass a descriptive instruction like `Represent this sentence for searching relevant passages:` to `from_pretrained` or `__init__`. For other tasks, omit or use an empty string.
affects: >=1.1.0 (specifically BGE v1.5 models)
gotchaSimilarity scores from BGE models, especially those prior to v1.5, are often concentrated in a narrow range (e.g., [0.6, 1]). An absolute score greater than 0.5 does not necessarily indicate strong similarity. For downstream tasks like retrieval, the *relative order* of scores is usually more important than their absolute values. If filtering by threshold, determine an appropriate threshold (e.g., 0.8-0.9) based on your specific data's similarity distribution.fixFocus on the ranking of similarity scores rather than absolute values. If filtering is required, empirically determine a suitable threshold for your dataset.
affects: <1.5 (less severe for >=1.5 due to alleviation)
breakingUsers upgrading from FlagEmbedding v1.2.x to v1.3.x have reported significant inference performance regressions (up to 100% slower) for BGE-M3 models and FlagReranker. This degradation can occur in subsequent calls to `model.encode` or `compute_score`.fixInvestigate GitHub issues for potential workarounds or official fixes. Consider pinning to a 1.2.x version if inference speed is critical and you're encountering this issue. The issue points to `self.model.to(device)` and `self.model.eval()` being invoked multiple times in `encode_single_device`.
affects: 1.3.x
gotchaDependency conflicts, particularly with `transformers` and `accelerate`, have been reported. For instance, `transformers==4.44.2` has caused conflicts when other packages require a newer version (e.g., `transformers<5.0.0,>=4.45.2`). This can lead to installation failures or runtime issues.fixUse a dedicated virtual environment. If conflicts arise, try explicitly installing a compatible version of `transformers` or `accelerate` that satisfies all your dependencies, or install `FlagEmbedding` in isolation.
affects: All versions, depending on other installed packages
Upgrade
Version history
1.4.0latest on PyPI · released Apr 22, 2026
Audit
Dependencies
torchrequiredCore deep learning framework
transformersrequiredHandles model loading and tokenization
datasetsrequiredUsed in data handling, especially for fine-tuning
acceleraterequiredDistributed training and inference utility
sentence_transformersrequiredIntegration for Sentence-BERT models
peftrequiredParameter-Efficient Fine-Tuning
ir-datasetsrequiredInformation retrieval datasets
sentencepiecerequiredTokenizer dependency
protobufrequiredData serialization format
air-benchmarkrequiredBenchmarking tools
deepspeedoptionalUsed for efficient distributed fine-tuning
flash-attnoptionalOptimized attention mechanism for fine-tuning