cstr/bge-m3-GGUF

bge-m3 GGUF

GGUF format of BAAI/bge-m3 for use with CrispEmbed.

BGE-M3. Dense + sparse + ColBERT multi-vector retrieval in one model. 100+ languages, 8192 context.

Files

File	Quantization	Size
bge-m3-q4_k.gguf	Q4_K	438 MB
bge-m3-q8_0.gguf	Q8_0	583 MB
bge-m3.gguf	F32	2175 MB

Quick Start

# Download
huggingface-cli download cstr/bge-m3-GGUF bge-m3-q4_k.gguf --local-dir .

# Run with CrispEmbed
./crispembed -m bge-m3-q4_k.gguf "Hello world"

# Or with auto-download
./crispembed -m bge-m3 "Hello world"

Model Details

Property	Value
Architecture	XLM-R
Parameters	568M
Embedding Dimension	1024
Layers	24
Pooling	mean
Tokenizer	SentencePiece
Base Model	BAAI/bge-m3

Verification

Verified bit-identical to HuggingFace sentence-transformers (cosine similarity >= 0.999 on test texts).

Usage with CrispEmbed

CrispEmbed is a lightweight C/C++ text embedding inference engine using ggml. No Python runtime, no ONNX. Supports BERT, XLM-R, Qwen3, and Gemma3 architectures.

# Build CrispEmbed
git clone https://github.com/CrispStrobe/CrispEmbed
cd CrispEmbed
cmake -S . -B build && cmake --build build -j

# Encode
./build/crispembed -m bge-m3-q4_k.gguf "query text"

# Server mode
./build/crispembed-server -m bge-m3-q4_k.gguf --port 8080
curl -X POST http://localhost:8080/v1/embeddings \
    -d '{"input": ["Hello world"], "model": "bge-m3"}'

Credits

• Original model: BAAI/bge-m3
• Inference engine: CrispEmbed (ggml-based)
• Conversion: convert-bert-embed-to-gguf.py

Provenance and EU AI Act Art. 53 note

• Upstream model: BAAI/bge-m3 — published by BAAI.
• Upstream licence: mit. This repository redistributes under the same terms; it grants no rights the upstream licence does not.
• What was done here: format conversion and/or quantisation only (GGUF/GGML). No training, no fine-tuning, no merging, no distillation, no change to architecture, vocabulary or capability. Only the numeric representation of the upstream weights differs.
• Training data: documented — where it is documented at all — by the upstream provider; see the upstream model card. No training data was used, added or selected by this repository.
• Provider status: under Regulation (EU) 2024/1689 the upstream authors remain the provider of this model. Converting the serialisation format does not make this repository the provider of a new general-purpose AI model, and no such claim is made. Questions about training content, copyright policy or model capability belong upstream.

Revision 2026-11-02: GGUFs with the sparse and ColBERT heads

The earlier files in this repo (bge-m3.gguf, -q8_0, -q4_k*, -iq4_xs) were converted in the default (Ollama) layout, which drops BGE-M3's sparse_linear and colbert_linear heads, so they support dense retrieval only. They remain unchanged. The new files are converted with --crisp and keep both heads:

• bge-m3-heads-f16.gguf: F16 encoder with the heads in F32.
• bge-m3-heads-q8_0-mixed.gguf: Q8_0, with encoder blocks 0-11 in F16.

Uniform Q8_0 keeps dense and sparse output above the bar but flips a few ColBERT token vectors (per-token minimum cosine 0.61). That error comes from the weights; it does not depend on colbert_linear's precision. Keeping the first 12 blocks in F16 brings it back to 0.973. A Q4_K variant with heads did not clear the bar (ColBERT minimum 0.37-0.60) and is not published. The checks used FlagEmbedding BGEM3FlagModel (FP32) on a 77-text panel, comparing dense vectors, lexical weights and every ColBERT token. They need CrispEmbed with the matching tokenizer and sparse fixes (CRISPEMBED_SPM_COLLAPSE_SPACES and CRISPEMBED_SPARSE_KEEP_SPECIAL, both default-correct). Evidence: CrispEmbed tests/results/below-bar/.

Revision 2026-11-03: bge-m3-heads-q8_0-enc0-15-f16.gguf supersedes bge-m3-heads-q8_0-mixed.gguf

bge-m3-heads-q8_0-mixed.gguf (Q8_0, encoder blocks 0-11 in F16) clears the Q8_0 bar on CPU (ColBERT minimum token cosine 0.9726 against FlagEmbedding) but not on CUDA: on a Tesla T4 its ColBERT minimum against the CPU F16 reference is 0.9667. It is kept unchanged and marked superseded. The new file keeps encoder blocks 0-15 in F16 (the rest Q8_0, heads F32): ColBERT minimum 0.9911 against FlagEmbedding BGEM3FlagModel (FP32, 77-text panel, portable CPU build) and 0.9922 on CUDA (T4); dense and sparse stay above 0.9995. 763 MiB, against 1599 MiB for bge-m3-heads-f16.gguf. Built with crispembed-quantize q8_0 --tensor-type 'enc.N.*=f16' for N = 0..15 from a fresh --crisp F32 conversion; the bytes reproduce identically on two different hosts. Evidence: CrispEmbed tests/results/below-bar/.