qdrant/fastembed · 上手攻略

• 仓库：qdrant/fastembed
• 链接：https://github.com/qdrant/fastembed
• 分类：AI Infra · Embedding / 向量嵌入
• 作者：Tom
• 更新：2026-10-02

---

§1 是什么

FastEmbed 是一个轻量、快速的 Python 向量嵌入生成库，由 Qdrant 团队开发和维护。它使用 ONNX Runtime 替代 PyTorch 作为推理后端，主打「无需 GPU、不下载 GB 级 PyTorch 依赖」就能跑 State-of-the-Art 嵌入模型。

核心能力覆盖：稠密文本嵌入、稀疏嵌入（SPLADE++）、晚交互嵌入（ColBERT）、图片嵌入、图文多模态嵌入（ColPali）、以及重排序（Cross-Encoder Rerank）。

---

§2 解决什么问题

痛点：主流嵌入方案（Sentence-Transformers、Transformers）依赖 PyTorch，体积庞大（数 GB）、启动慢、不适合 Serverless 环境（AWS Lambda 等）。

FastEmbed 的解法： - 用 ONNX Runtime 替代 PyTorch，推理速度更快、依赖更少 - 默认模型为 BAAI/bge-small-en-v1.5（384 维），在 MTEB 榜单上表现优于 OpenAI Ada-002 - 支持 GPU 加速（fastembed-gpu），也支持纯 CPU 运行 - 适合：Serverless 函数、边缘设备、快速原型、批量向量生成

---

§3 快速安装

基础安装（CPU only）

pip install fastembed

GPU 支持（需 CUDA 12.x）⚠️

pip install fastembed-gpu

联合 Qdrant 向量数据库安装

pip install 'qdrant-client[fastembed]'
# 或 GPU 版本
pip install 'qdrant-client[fastembed-gpu]'

⚠️ 注意：zsh 等 Shell 需要给包含方括号的包名加引号：pip install 'qdrant-client[fastembed]'

---

§4 核心用法

4.1 基础文本嵌入（默认模型）

from fastembed import TextEmbedding

documents = [
    "This is built to be faster and lighter than other embedding libraries e.g. Transformers, Sentence-Transformers, etc.",
    "fastembed is supported by and maintained by Qdrant.",
]

# 触发模型下载 + 初始化
embedding_model = TextEmbedding()   # 默认 BAAI/bge-small-en-v1.5 (384维)
print("The model BAAI/bge-small-en-v1.5 is ready to use.")

# embed() 返回生成器，需转为 list
embeddings_generator = embedding_model.embed(documents)
embeddings_list = list(embedding_model.embed(documents))

print(len(embeddings_list[0]))   # 384

⚠️ embed() 是生成器（generator），不是列表，直接迭代或 list() 转换。

4.2 指定模型

from fastembed import TextEmbedding

model = TextEmbedding(model_name="BAAI/bge-small-en-v1.5")
embeddings = list(model.embed(documents))
# 返回: list of numpy arrays, dtype=float32, shape=(384,)

4.3 GPU 加速

from fastembed import TextEmbedding

embedding_model = TextEmbedding(
    model_name="BAAI/bge-small-en-v1.5",
    providers=["CUDAExecutionProvider"]   # 需要 fastembed-gpu + CUDA 12.x
)

4.4 稀疏文本嵌入（SPLADE++）

from fastembed import SparseTextEmbedding

model = SparseTextEmbedding(model_name="prithivida/Splade_PP_en_v1")
embeddings = list(model.embed(documents))

# 返回 SparseEmbedding(indices=[...], values=[...])

4.5 晚交互嵌入（ColBERT）

适合需要 token 级交叉交互的检索场景：

from fastembed import LateInteractionTextEmbedding

model = LateInteractionTextEmbedding(model_name="colbert-ir/colbertv2.0")
embeddings = list(model.embed(documents))
# 返回: list of arrays, shape = (seq_len, 128)

4.6 图片嵌入（CLIP）

from fastembed import ImageEmbedding

images = [
    "./path/to/image1.jpg",
    "./path/to/image2.png",
]
model = ImageEmbedding(model_name="Qdrant/clip-ViT-B-32-vision")
embeddings = list(model.embed(images))
# 返回: list of numpy arrays, dtype=float32

4.7 多模态嵌入（ColPali）—— 图文 late interaction

from fastembed import LateInteractionMultimodalEmbedding

doc_images = [
    "./path/to/qdrant_pdf_doc_1_screenshot.jpg",
    "./path/to/colpali_pdf_doc_2_screenshot.jpg",
]
query = "What is Qdrant?"

model = LateInteractionMultimodalEmbedding(model_name="Qdrant/colpali-v1.3-fp16")
doc_embeddings = list(model.embed_image(doc_images))
# shape: (2, 1030, 128) dtype=float16
query_embedding = model.embed_text(query)
# shape: (1, 20, 128) dtype=float16

4.8 重排序（Cross-Encoder Rerank）

from fastembed.rerank.cross_encoder import TextCrossEncoder

query = "Who is maintaining Qdrant?"
documents = [
    "This is built to be faster and lighter than other embedding libraries.",
    "Qdrant is supported by and maintained by Qdrant.",
]
encoder = TextCrossEncoder(model_name="Xenova/ms-marco-MiniLM-L-6-v2")
scores = list(encoder.rerank(query, documents))
# 返回相关性分数，数值越高越相关

4.9 自定义模型（扩展支持列表）

from fastembed import TextEmbedding
from fastembed.common.model_description import PoolingType, ModelSource

TextEmbedding.add_custom_model(
    model="intfloat/multilingual-e5-small",
    pooling=PoolingType.MEAN,
    normalization=True,
    sources=ModelSource(hf="intfloat/multilingual-e5-small"),
    dim=384,
    model_file="onnx/model.onnx",
)
model = TextEmbedding(model_name="intfloat/multilingual-e5-small")
embeddings = list(model.embed(documents))

4.10 与 Qdrant 向量数据库联合使用

from qdrant_client import QdrantClient, models
from fastembed import TextEmbedding

# 初始化客户端
client = QdrantClient("localhost", port=6333)  # 生产环境
# client = QdrantClient(":memory:")            # 实验用

# 生成嵌入
model = TextEmbedding(model_name="sentence-transformers/all-MiniLM-L6-v2")
documents = [
    {"document": "Qdrant has Langchain integrations", "source": "Langchain-docs"},
    {"document": "Qdrant also has Llama Index integrations", "source": "LlamaIndex-docs"},
]
payload = [{"vector": vec.tolist(), **doc} for vec, doc in zip(model.embed([d["document"] for d in documents]), documents)]

# 写入 Qdrant
client.upsert(
    collection_name="demo_collection",
    points=[
        models.PointStruct(id=idx, vector=p["vector"], payload={k: v for k, v in p.items() if k != "vector"})
        for idx, p in enumerate(payload)
    ]
)

---

§5 典型适用场景

1. Serverless 向量检索：AWS Lambda、Vercel Functions 等不适合装 PyTorch 的环境，直接 pip install fastembed 即可。
2. 大规模语料向量化：用 ONNX 加速批量文档嵌入，结合 Qdrant 或 Milvus 做向量数据库。
3. 多模态检索：用 CLIP 或 ColPali 做图文混合检索（如 PDF 截图 + 文字查询）。
4. Rerank 流水线：先 fastembed 做向量检索召回 Top-K，再用 Cross-Encoder 重排精排序。
5. 轻量级 Embedding API：作为文本嵌入微服务，比 Sentence-Transformers 镜像更小、启动更快。

---

§6 坑与注意

⚠️ 以下为已知高风险点：

1. embed() 是生成器非列表：直接打印或取长度会得到生成器对象，必须 list(embedding_model.embed(documents))。

2. GPU 版本 CUDA 兼容性：fastembed-gpu 需要 CUDA 12.x（非 11.x），且需与 ONNX Runtime GPU 版本匹配；CUDA 11 用户只能用 CPU 版本。

3. 模型下载首次慢：第一次初始化会从 HuggingFace 下载 ONNX 模型文件（约几百 MB），无代理环境可能超时。

4. 稀疏嵌入不支持 GPU：SparseTextEmbedding 暂不支持 CUDAExecutionProvider，仅 CPU 运行。

5. Serverless 冷启动：虽然比 PyTorch 轻量，但首次冷启动仍需下载模型，建议配合模型缓存（EFS、本地层）使用。

6. 默认模型是英文的：BAAI/bge-small-en-v1.5 是英文模型，中文内容请换用多语言模型如 intfloat/multilingual-e5-small 或 BAAI/bge-m3。

7. ONNX 模型路径问题：自定义模型时 model_file 路径需指向正确的 ONNX 文件，不正确会导致加载失败。

8. Python 版本：官方推荐 Python 3.10+，低于 3.9 可能存在兼容性问题（ONNX Runtime 限制）。

---

§7 与同类对比

库	体积	速度	GPU	适合场景
FastEmbed	~100MB（无 PyTorch）	快（ONNX）	可选（fastembed-gpu）	Serverless、边缘、轻量生产
Sentence-Transformers	~1-2 GB（含 PyTorch）	中等	必须	通用场景、成熟生态
Transformers (HuggingFace)	数 GB	较慢	推荐	通用模型推理、微调
OpenAI Embeddings API	无本地	依赖网络	N/A	快速原型、付费生产
** Instructor**	中等	中等	可选	任务定制嵌入

核心差异：FastEmbed 是目前最轻量的开源本地 Embedding 方案，在 Serverless 和资源受限场景下优势明显；在需要微调或最高精度场景仍推荐 Sentence-Transformers。

---

§8 一句话推荐结论

FastEmbed 是 Serverless 友好型 Embedding 库的首选——轻量、快速、无 PyTorch 依赖，适合作为向量检索 pipeline 的高效向量化前站；但需要中文模型或 GPU 微调时，建议评估 Sentence-Transformers 或商业 API。