Environment:FlagOpen FlagEmbedding Python PyTorch Environment

Knowledge Sources	FlagOpen/FlagEmbedding PyPI FlagEmbedding
Domains	Infrastructure, NLP, Deep_Learning
Last Updated	2026-02-09 21:00 GMT

Overview

Python 3.x environment with PyTorch >= 1.6.0, Transformers >= 4.44.2, and core NLP/ML dependencies for running FlagEmbedding inference and evaluation.

Description

This environment provides the base software stack required to run all FlagEmbedding workflows including embedding inference, reranker inference, and benchmark evaluation. It includes the HuggingFace ecosystem (transformers, datasets, accelerate, sentence-transformers, peft), FAISS-related retrieval libraries (ir-datasets), and tokenization support (sentencepiece, protobuf). The package is distributed as FlagEmbedding version 1.3.5 on PyPI.

Usage

Use this environment for all FlagEmbedding workflows: embedder inference, reranker inference, embedder finetuning, reranker finetuning, and benchmark evaluation. This is the mandatory base prerequisite for every implementation in the repository.

System Requirements

Category	Requirement	Notes
OS	Linux (recommended), macOS, Windows	Linux tested most extensively
Python	>= 3.8	Required by transformers >= 4.44.2
Disk	5GB+ free space	For model downloads and caching

Dependencies

System Packages

`git` (for cloning models from HuggingFace Hub)
`git-lfs` (for large model files)

Python Packages

`torch` >= 1.6.0
`transformers` >= 4.44.2
`datasets` >= 2.19.0
`accelerate` >= 0.20.1
`sentence_transformers` (any version)
`peft` (any version)
`ir-datasets` (any version)
`sentencepiece` (any version)
`protobuf` (any version)

Credentials

The following environment variables may be set for authenticated model access:

`HF_TOKEN`: HuggingFace API token for accessing gated models (e.g., Llama-based embedders). Referenced in model argument classes.
`HF_HUB_CACHE`: Custom cache directory for HuggingFace Hub downloads. Defaults to `~/.cache/huggingface/hub`.
`HF_ENDPOINT`: Custom HuggingFace endpoint URL. Defaults to `https://huggingface.co`. Used in MIRACL and MKQA evaluation data loaders.

Quick Install

# Install the base FlagEmbedding package
pip install FlagEmbedding

# Or install from source with all core dependencies
pip install torch>=1.6.0 transformers>=4.44.2 datasets>=2.19.0 accelerate>=0.20.1 sentence_transformers peft ir-datasets sentencepiece protobuf

Code Evidence

Package dependencies from `setup.py:16-26`:

install_requires=[
    'torch>=1.6.0',
    'transformers>=4.44.2',
    'datasets>=2.19.0',
    'accelerate>=0.20.1',
    'sentence_transformers',
    'peft',
    'ir-datasets',
    'sentencepiece',
    'protobuf'
],

HuggingFace token usage from `FlagEmbedding/abc/finetune/embedder/AbsArguments.py:37-39`:

token: str = field(
    default_factory=lambda: os.getenv('HF_TOKEN', None),
    metadata={"help": "The token to use when accessing the model."}
)

HuggingFace Hub cache from `FlagEmbedding/abc/evaluation/data_loader.py:36`:

os.getenv('HF_HUB_CACHE', '~/.cache/huggingface/hub')

HuggingFace endpoint override from `FlagEmbedding/evaluation/miracl/data_loader.py:100`:

os.getenv('HF_ENDPOINT', 'https://huggingface.co')

Common Errors

Error Message	Cause	Solution
`ImportError: No module named 'FlagEmbedding'`	Package not installed	`pip install FlagEmbedding`
`FileNotFoundError: cannot find file: {path}`	Training data path does not exist	Verify the training data path passed to `--train_data`
`transformers version < 4.44.2`	Outdated transformers	`pip install --upgrade transformers>=4.44.2`

Compatibility Notes

Python version: Requires Python >= 3.8 due to transformers dependency.
Tokenizers: Uses `sentencepiece` and `protobuf` for models requiring SentencePiece tokenization (e.g., XLM-R, multilingual models).
PEFT: Required for LoRA-based fine-tuning and loading LoRA adapters during inference.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment