FoundationAgents/MetaGPT · error · ImportError

`llama-index-postprocessor-flag-embedding-reranker` package

Error message

`llama-index-postprocessor-flag-embedding-reranker` package not found, please run `pip install llama-index-postprocessor-flag-embedding-reranker`

What it means

RankerFactory._create_bge_rerank raises this ImportError when llama-index-postprocessor-flag-embedding-reranker is not installed. BGE reranking uses FlagEmbedding's FlagEmbeddingReranker, which llama-index ships as a separate optional distribution that MetaGPT never installs by default.

Source

Thrown at metagpt/rag/factories/ranker.py:68

            )
        return ColbertRerank(**config.model_dump())

    def _create_cohere_rerank(self, config: CohereRerankConfig, **kwargs) -> LLMRerank:
        try:
            from llama_index.postprocessor.cohere_rerank import CohereRerank
        except ImportError:
            raise ImportError(
                "`llama-index-postprocessor-cohere-rerank` package not found, please run `pip install llama-index-postprocessor-cohere-rerank`"
            )
        return CohereRerank(**config.model_dump())

    def _create_bge_rerank(self, config: BGERerankConfig, **kwargs) -> LLMRerank:
        try:
            from llama_index.postprocessor.flag_embedding_reranker import (
                FlagEmbeddingReranker,
            )
        except ImportError:
            raise ImportError(
                "`llama-index-postprocessor-flag-embedding-reranker` package not found, please run `pip install llama-index-postprocessor-flag-embedding-reranker`"
            )
        return FlagEmbeddingReranker(**config.model_dump())

    def _create_object_ranker(self, config: ObjectRankerConfig, **kwargs) -> LLMRerank:
        return ObjectSortPostprocessor(**config.model_dump())

    def _extract_llm(self, config: BaseRankerConfig = None, **kwargs) -> LLM:
        return self._val_from_config_or_kwargs("llm", config, **kwargs)


get_rankers = RankerFactory().get_rankers

View on GitHub (pinned to 11cdf466d0)

Solutions

pip install llama-index-postprocessor-flag-embedding-reranker
Verify FlagEmbedding itself imports (pip install FlagEmbedding) since the wrapper depends on it
If torch/model downloads are unacceptable in your env, use an API-backed ranker (cohere) or ObjectSortPostprocessor instead

Example fix

// before
rankers = get_rankers(configs=[BGERerankConfig(top_n=3, model="BAAI/bge-reranker-base")])  # ImportError

// after
// pip install llama-index-postprocessor-flag-embedding-reranker FlagEmbedding
rankers = get_rankers(configs=[BGERerankConfig(top_n=3, model="BAAI/bge-reranker-base")])

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("llama_index.postprocessor.flag_embedding_reranker") is None:
    raise SystemExit("Install first: pip install llama-index-postprocessor-flag-embedding-reranker FlagEmbedding")

Try / catch

try:
    ranker = get_rankers(configs=[bge_cfg])
except ImportError as e:
    if "flag-embedding-reranker" in str(e):
        raise RuntimeError("BGE rerank requires: pip install llama-index-postprocessor-flag-embedding-reranker") from e
    raise

Prevention

Add the flag-embedding reranker package (plus FlagEmbedding, torch) to environments using BGE rankers
Pre-download the BAAI reranker model in image build so runtime does not fetch multi-GB weights
Verify imports in a preflight check for CPU-only deployments

When it happens

Trigger: Requesting a BGERerankConfig through get_rankers or a retriever/ranker config when the flag-embedding-reranker package (and its FlagEmbedding dependency) is missing.

Common situations: Opting into BGE reranking for local/CPU pipelines on a minimal install; CI images that install metagpt without rag extras; the additional transitive FlagEmbedding model dependencies (torch, transformers) not being present.

Related errors

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/27fa46f6a19367c0. Report an issue: GitHub.