bge-m3-lite

CPU inference for BAAI/bge-m3 with onnxruntime as the only dependency. All three BGE-M3 outputs are supported and match the official PyTorch implementation (FlagEmbedding) to fp32 precision:

Everything except the transformer forward pass is implemented in this package from scratch: the XLM-RoBERTa tokenizer (SentencePiece unigram model, the nmt_nfkc precompiled charsmap, Unicode grapheme segmentation), the torch-free loader for the sparse / ColBERT heads, the model downloader and the pooling.

Platforms: Apple Silicon, Linux ARM64, Linux x86_64 (Python 3.11+).

Install

uv add bge-m3-lite        # or: pip install bge-m3-lite

Use

from bge_m3_lite import BGEM3Embedder

embedder = BGEM3Embedder()  # first call downloads ~2.3 GB into ~/.cache/bge-m3-lite
out = embedder.encode(
    ["What is BGE M3?", "BGE M3 是一個多語言嵌入模型。"],
    return_dense=True,
    return_sparse=True,
    return_colbert_vecs=True,
)
out["dense_vecs"].shape  # (2, 1024)
out["lexical_weights"][0]  # {'4865': 0.08, '83': 0.08, ...}
out["colbert_vecs"][0].shape  # (7, 1024)

embedder.convert_id_to_token(out["lexical_weights"][0])
embedder.compute_lexical_matching_score(lw_query, lw_passage)
embedder.colbert_score(q_vecs, p_vecs)

Passing a single string returns unwrapped values, like FlagEmbedding. BGEM3Embedder(precision="int8") loads a 4× smaller quantised backbone (see docs/quantization.md for the accuracy trade-off).

CLI

bge-m3-lite download                     # pre-fetch the model files
bge-m3-lite info                         # cache state
echo "hello" | bge-m3-lite encode --sparse --colbert --tokens

Environment variables

Model files are pinned to a specific Hugging Face revision and verified by SHA-256 after download.

Development

See AGENTS.md and docs/ (architecture, tokenizer, verification, development).

Status

v0.0.2: fp32 with exact parity with FlagEmbedding, plus an opt-in int8 backbone.