# https://github.com/qdrant/fastembed 项目说明书
生成时间：2026-05-21 04:13:34 UTC
## 目录
- [FastEmbed 概述](#page-overview)
- [安装指南](#page-installation)
- [快速开始](#page-quickstart)
- [系统架构](#page-architecture)
- [密集文本嵌入](#page-dense-embedding)
- [稀疏文本嵌入](#page-sparse-embedding)
- [后期交互模型 (ColBERT)](#page-late-interaction)
- [图像嵌入](#page-image-embedding)
- [多模态后期交互 (ColPali)](#page-multimodal)
- [重排序模型](#page-reranker)
## FastEmbed 概述
### 相关页面
相关主题：[安装指南](#page-installation), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/qdrant/fastembed/blob/main/README.md)
- [fastembed/image/onnx_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/image/onnx_embedding.py)
- [fastembed/text/pooled_normalized_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/pooled_normalized_embedding.py)
- [fastembed/text/pooled_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/pooled_embedding.py)
- [fastembed/text/onnx_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/onnx_embedding.py)
- [fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py](https://github.com/qdrant/fastembed/blob/main/fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py)
- [fastembed/sparse/bm25.py](https://github.com/qdrant/fastembed/blob/main/fastembed/sparse/bm25.py)
- [fastembed/postprocess/muvera.py](https://github.com/qdrant/fastembed/blob/main/fastembed/postprocess/muvera.py)
- [RELEASE.md](https://github.com/qdrant/fastembed/blob/main/RELEASE.md)
- [mkdocs.yml](https://github.com/qdrant/fastembed/blob/main/mkdocs.yml)
# FastEmbed 概述
FastEmbed 是一个由 Qdrant 团队开发和维护的高性能向量嵌入库，专注于快速、轻量级的文本和图像嵌入生成。该项目采用 Apache-2.0 和 MIT 许可证，完全开源，旨在为搜索引擎和向量数据库提供高效的嵌入解决方案。
## 核心特性
FastEmbed 的设计目标是在保持高精度的同时实现极致的推理速度。以下是该项目的主要特性：
| 特性 | 描述 |
|------|------|
| **ONNX 运行时支持** | 使用 ONNX 运行时进行跨平台推理，支持 CPU 和 GPU 加速 |
| **多模态支持** | 同时支持文本嵌入和图像嵌入 |
| **稀疏嵌入** | 支持 BM25 和 SPLADE++ 等稀疏嵌入模型 |
| **Reranking** | 提供 Cross-Encoder 风格的重新排序功能 |
| **后处理支持** | 集成 Muvera 等后期处理算法 |
| **量化模型** | 提供量化版本的模型以减少内存占用 |
资料来源：[README.md](https://github.com/qdrant/fastembed/blob/main/README.md)
## 架构概览
FastEmbed 采用模块化架构，不同类型的嵌入模型通过统一的接口暴露给用户。整体架构可分为以下几个核心模块：
```mermaid
graph TD
A[FastEmbed 核心接口] --> B[TextEmbedding 文本嵌入]
A --> C[ImageEmbedding 图像嵌入]
A --> D[SparseTextEmbedding 稀疏嵌入]
A --> E[TextCrossEncoder Reranker]
B --> B1[PooledEmbedding]
B --> B2[PooledNormalizedEmbedding]
C --> C1[OnnxImageModel]
D --> D1[Bm25]
D --> D2[SPLADE++]
E --> E1[OnnxCrossEncoderModel]
A --> F[PostProcessors 后处理器]
F --> F1[Muvera]
```
### 文本嵌入模型
FastEmbed 支持多种文本嵌入模型，按处理方式可分为两类：
#### PooledEmbedding 池化嵌入
基础的池化嵌入模型，对 token 序列进行平均池化处理。支持的模型包括：
| 模型名称 | 维度 | 语言支持 | 最大输入长度 | 来源 |
|---------|------|---------|-------------|------|
| sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 | 384 | 多语言(~50种) | 512 tokens | xenova/paraphrase-multilingual-MiniLM-L12-v2-onnx-Q |
| intfloat/multilingual-e5-large | 1024 | 多语言(~100种) | 512 tokens | qdrant/multilingual-e5-large-onnx |
| nomic-ai/nomic-embed-text-v1 | 768 | 英文 | 8192 tokens | nomic-ai/nomic-embed-text-v1 |
资料来源：[fastembed/text/pooled_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/pooled_embedding.py)
#### PooledNormalizedEmbedding 归一化池化嵌入
对输出进行 L2 归一化处理的池化嵌入模型，适用于需要余弦相似度的场景：
```python
from fastembed import TextEmbedding
model = TextEmbedding(model_name="BAAI/bge-base-en-v1.5")
embeddings = list(model.embed(documents))
```
支持的模型包括多个 BGE 变体和 Jina Embeddings 系列：
| 模型名称 | 维度 | 许可证 | 大小 |
|---------|------|-------|------|
| BAAI/bge-base-en-v1.5 | 768 | MIT | 0.21 GB |
| BAAI/bge-large-en-v1.5 | 1024 | MIT | 1.20 GB |
| jinaai/jina-embeddings-v2-base-en | 768 | Apache-2.0 | 0.52 GB |
资料来源：[fastembed/text/pooled_normalized_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/pooled_normalized_embedding.py)
### 图像嵌入模型
FastEmbed 的图像嵌入功能通过 `OnnxImageEmbedding` 类实现：
| 模型名称 | 维度 | 描述 | 大小 |
|---------|------|------|------|
| Qdrant/resnet50-onnx | 2048 | ResNet50 图像嵌入 | - |
| Qdrant/Unicom-ViT-B-16 | 768 | 图像嵌入，多模态(text&image) | 0.82 GB |
| Qdrant/Unicom-ViT-B-32 | 512 | 图像嵌入，多模态(text&image) | 0.48 GB |
| jinaai/jina-clip-v1 | 768 | 多模态(text&image)嵌入 | 0.34 GB |
资料来源：[fastembed/image/onnx_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/image/onnx_embedding.py)
### 稀疏嵌入模型
#### BM25
BM25 是一种传统的稀疏嵌入实现，用于文档相关性评分。公式如下：
```
score(q, d) = Σ IDF(q_i) * (f(q_i, d) * (k + 1)) / (f(q_i, d) + k * (1 - b + b * (|d| / avg_len)))
```
其中 `k` 和 `b` 是可配置的饱和参数。使用时需要在 Qdrant 侧配合 `modifier="idf"` 使用。
资料来源：[fastembed/sparse/bm25.py](https://github.com/qdrant/fastembed/blob/main/fastembed/sparse/bm25.py)
#### SPLADE++
SPLADE++ 是另一种稀疏嵌入模型，通过稀疏向量表示捕获词汇级别的相关性：
```python
from fastembed import SparseTextEmbedding
model = SparseTextEmbedding(model_name="prithivida/Splade_PP_en_v1")
embeddings = list(model.embed(documents))
```
### Reranker 模型
FastEmbed 提供 Cross-Encoder 风格的重新排序功能，用于提升搜索结果的相关性：
| 模型名称 | 描述 | 大小 |
|---------|------|------|
| Xenova/ms-marco-MiniLM-L-12-v2 | MS MARCO 问答重排序 | 0.12 GB |
| BAAI/bge-reranker-base | BGE 重排序基础模型 | 1.04 GB |
| jinaai/jina-reranker-v1-tiny-en | 轻量级重排序，8K 上下文 | 0.13 GB |
| jinaai/jina-reranker-v1-turbo-en | 高速重排序，8K 上下文 | 0.15 GB |
| jinaai/jina-reranker-v2-base-multilingual | 多语言重排序，1K 滑动窗口 | 1.11 GB |
资料来源：[fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py](https://github.com/qdrant/fastembed/blob/main/fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py)
### 后处理器
#### Muvera
Muvera 是一种将多向量表示压缩为固定维度编码的算法，常用于 ColBERT 等模型的输出后处理：
```python
from fastembed import LateInteractionTextEmbedding
from fastembed.postprocess import Muvera
model = LateInteractionTextEmbedding(model_name="colbert-ir/colbertv2.0")
muvera = Muvera.from_multivector_model(
model=model,
k_sim=6,
dim_proj=32
)
```
输出维度计算公式：`r_reps * 2^k_sim * dim_proj`
资料来源：[fastembed/postprocess/muvera.py](https://github.com/qdrant/fastembed/blob/main/fastembed/postprocess/muvera.py)
## 使用流程
```mermaid
graph LR
A[选择模型类型] --> B[初始化模型]
B --> C[输入数据]
C --> D[生成嵌入向量]
D --> E[向量索引/相似度计算]
E --> F[可选: Reranking]
```
### 基本使用示例
```python
from fastembed import TextEmbedding
from qdrant_client import QdrantClient, models
# 初始化客户端
client = QdrantClient("localhost", port=6333)
# 选择模型
model_name = "sentence-transformers/all-MiniLM-L6-v2"
# 准备文档
payload = [
{"document": "Qdrant has Langchain integrations", "source": "Langchain-docs"},
{"document": "Qdrant also has Llama Index integrations", "source": "LlamaIndex-docs"}
]
docs = [models.Document(text=data["document"], model=model_name) for data in payload]
# 创建集合
client.create_collection(
"demo_collection",
vectors_config=models.VectorParams(
size=client.get_embedding_size(model_name),
distance=models.Distance.COSINE
)
)
# 上传文档
client.upload_collection(
collection_name="demo_collection",
vectors=docs,
payload=payload,
)
```
### GPU 加速使用
```python
from fastembed import TextEmbedding
model = TextEmbedding(
model_name="BAAI/bge-small-en-v1.5",
providers=["CUDAExecutionProvider"]
)
print("The model BAAI/bge-small-en-v1.5 is ready to use on a GPU.")
```
## 模型来源配置
FastEmbed 使用 `ModelSource` 类管理模型文件的下载来源：
```python
ModelSource(
hf="huggingface/model-id", # HuggingFace Hub
url="https://...", # 自定义 URL
_deprecated_tar_struct=True # 兼容旧版 tar 结构
)
```
某些模型还支持从自定义 URL 加载，适用于私有存储场景：
```python
model = TextEmbedding(
model_name="intfloat/multilingual-e5-small",
sources=ModelSource(
hf="intfloat/multilingual-e5-small",
url="https://storage.googleapis.com/qdrant-fastembed/..."
)
)
```
## Qdrant 集成
FastEmbed 与 Qdrant 向量数据库深度集成，可通过以下方式安装：
```bash
pip install qdrant-client[fastembed]
# 或
pip install qdrant-client[fastembed-gpu]
```
集成后可直接使用 `models.Document` 类自动处理嵌入生成和向量存储。
## 文档与发布
FastEmbed 使用 MkDocs 进行文档管理，主题采用 Material for MkDocs。发布流程遵循以下步骤：
1. 在 `main` 分支累积变更
2. 更新 `pyproject.toml` 中的版本号
3. 将 `gpu` 分支 rebase 到 `main`
4. 起草发布说明
5. 创建 Git 标签
6. 推送标签触发 PyPI 发布
7. 验证 PyPI 上的包发布成功
资料来源：[RELEASE.md](https://github.com/qdrant/fastembed/blob/main/RELEASE.md)、[mkdocs.yml](https://github.com/qdrant/fastembed/blob/main/mkdocs.yml)
## 许可证
FastEmbed 项目采用多种开源许可证：
| 许可证类型 | 适用范围 |
|-----------|---------|
| Apache-2.0 | 大多数模型和核心代码 |
| MIT | BGE 系列模型 |
使用前请查阅具体模型的许可证要求。
---
## 安装指南
### 相关页面
相关主题：[快速开始](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/qdrant/fastembed/blob/main/README.md)
- [RELEASE.md](https://github.com/qdrant/fastembed/blob/main/RELEASE.md)
- [pyproject.toml](https://github.com/qdrant/fastembed/blob/main/pyproject.toml)
- [mkdocs.yml](https://github.com/qdrant/fastembed/blob/main/mkdocs.yml)
- [fastembed/image/onnx_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/image/onnx_embedding.py)
- [fastembed/text/onnx_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/onnx_embedding.py)
# 安装指南
FastEmbed 是一个高性能的嵌入向量生成库，由 Qdrant 团队维护。本指南将详细介绍 FastEmbed 的安装方式、环境配置以及与 Qdrant 的集成方法。
## 环境要求
### 系统要求
FastEmbed 支持在 Linux、macOS 和 Windows 系统上运行。建议使用 Python 3.9 或更高版本以确保最佳兼容性。
| 组件 | 最低要求 | 推荐配置 |
|------|----------|----------|
| Python | 3.9 | 3.10+ |
| 内存 | 2GB | 8GB+ |
| 磁盘空间 | 1GB | 根据模型大小 |
| CUDA (GPU) | 11.0+ | 12.0+ |
### 硬件加速支持
FastEmbed 基于 ONNX Runtime 构建，支持多种硬件加速 Provider：
- **CPUExecutionProvider**: 默认的 CPU 执行提供者
- **CUDAExecutionProvider**: NVIDIA GPU 加速
- **CoreMLExecutionProvider**: Apple Silicon (M1/M2/M3) 加速
资料来源：[README.md:45-60](https://github.com/qdrant/fastembed/blob/main/README.md)
## 安装方式
### 基础安装
使用 pip 安装 FastEmbed 的基础版本：
```bash
pip install fastembed
```
此安装包含所有 CPU 相关的依赖和基础功能。
### GPU 版本安装
对于需要 GPU 加速的场景，安装 GPU 专版：
```bash
pip install fastembed-gpu
```
资料来源：[RELEASE.md:1-15](https://github.com/qdrant/fastembed/blob/main/RELEASE.md)
## 与 Qdrant 集成安装
### 基础集成
Qdrant Client 提供了与 FastEmbed 的深度集成支持：
```bash
pip install qdrant-client[fastembed]
```
资料来源：[README.md:65-75](https://github.com/qdrant/fastembed/blob/main/README.md)
### GPU 加速集成
使用 GPU 加速的 Qdrant 集成：
```bash
pip install qdrant-client[fastembed-gpu]
```
> 注意：在 zsh shell 中可能需要使用引号：
> ```bash
> pip install 'qdrant-client[fastembed]'
> ```
资料来源：[README.md:72-73](https://github.com/qdrant/fastembed/blob/main/README.md)
## 模型下载与缓存
### 缓存目录配置
FastEmbed 会自动缓存下载的模型文件。可以通过环境变量配置缓存路径：
```bash
export FASTEMBED_CACHE_PATH=/path/to/cache
```
默认缓存目录为系统临时目录下的 `fastembed_cache` 文件夹。
### 模型列表
FastEmbed 支持多种预训练模型，按功能分类如下：
| 模型类型 | 代表模型 | 向量维度 | 许可证 |
|----------|----------|----------|--------|
| 英文文本嵌入 | BAAI/bge-small-en-v1.5 | 384 | MIT |
| 中文文本嵌入 | jinaai/jina-embeddings-v2-base-zh | 768 | Apache-2.0 |
| 多语言嵌入 | sentence-transformers/paraphrase-multilingual-mpnet-base-v2 | 768 | Apache-2.0 |
| 图像嵌入 | Qdrant/Unicom-ViT-B-16 | 768 | Apache-2.0 |
| 重排序模型 | jinaai/jina-reranker-v1-turbo-en | - | Apache-2.0 |
资料来源：[fastembed/text/onnx_embedding.py:100-150](https://github.com/qdrant/fastembed/blob/main/fastembed/text/onnx_embedding.py)
## 使用示例
### Python 基础用法
```python
from fastembed import TextEmbedding
# 列出支持的模型
print(TextEmbedding.list_supported_models())
# 初始化模型（默认使用 CPU）
model = TextEmbedding(model_name="BAAI/bge-small-en-v1.5")
# 生成嵌入向量
embeddings = list(model.embed(["Hello, world!"]))
```
### GPU 加速用法
```python
from fastembed import TextEmbedding
# 使用 CUDA Provider 进行 GPU 加速
model = TextEmbedding(
model_name="BAAI/bge-small-en-v1.5",
providers=["CUDAExecutionProvider"]
)
print("The model BAAI/bge-small-en-v1.5 is ready to use on a GPU.")
# 生成嵌入向量
embeddings = list(model.embed(["Hello, world!"]))
```
资料来源：[README.md:30-55](https://github.com/qdrant/fastembed/blob/main/README.md)
### Qdrant 集成用法
```python
from qdrant_client import QdrantClient, models
# 初始化客户端
client = QdrantClient("localhost", port=6333)
model_name = "sentence-transformers/all-MiniLM-L6-v2"
payload = [
{"document": "Qdrant has Langchain integrations", "source": "Langchain-docs"},
{"document": "Qdrant also has Llama Index integrations", "source": "LlamaIndex-docs"}
]
docs = [models.Document(text=data["document"], model=model_name) for data in payload]
ids = [42, 2]
# 创建 Collection
client.create_collection(
"demo_collection",
vectors_config=models.VectorParams(
size=client.get_embedding_size(model_name),
distance=models.Distance.COSINE
)
)
# 上传文档
client.upload_collection(
collection_name="demo_collection",
vectors=docs,
ids=ids,
payload=payload,
)
# 搜索
search_result = client.query_points(
collection_name="demo_collection",
query=docs
)
```
资料来源：[README.md:80-120](https://github.com/qdrant/fastembed/blob/main/README.md)
## 依赖管理
### 核心依赖
FastEmbed 的核心依赖包括：
- `onnxruntime` - ONNX 模型推理引擎
- `numpy` - 数值计算
- `tokenizers` - 文本分词
- `huggingface-hub` - 模型下载与管理
### 可选依赖
| 功能 | 依赖包 | 安装命令 |
|------|--------|----------|
| GPU 加速 | `onnxruntime-gpu` | `pip install fastembed-gpu` |
| 文档构建 | `mkdocs-material` | 参见 mkdocs.yml |
| 测试 | `pytest` | `pip install pytest` |
资料来源：[mkdocs.yml:1-50](https://github.com/qdrant/fastembed/blob/main/mkdocs.yml)
## 故障排除
### 常见问题
1. **模型下载失败**
- 检查网络连接
- 确认 HuggingFace Hub 可访问
- 设置代理或镜像源
2. **GPU 不可用**
- 确认 CUDA 驱动已正确安装
- 验证 ONNX Runtime GPU 版本已安装
- 检查 GPU 设备可见性
3. **内存不足**
- 选择更小的模型（如 bge-small-en）
- 使用量化模型版本
- 减少批处理大小
### 验证安装
运行以下代码验证安装是否成功：
```python
import fastembed
print(f"FastEmbed version: {fastembed.__version__}")
from fastembed import TextEmbedding
model = TextEmbedding.list_supported_models()
print(f"Supported models: {len(model)}")
```
## 发布管理
FastEmbed 和 fastembed-gpu 是两个独立的 PyPI 包。发布流程如下：
```mermaid
graph TD
A[main 分支累积变更] --> B[更新 pyproject.toml 版本号]
B --> C[ Rebase gpu 分支到 main]
C --> D[草拟发布说明]
D --> E[创建 main 分支标签]
E --> F[创建 gpu 分支标签]
F --> G[推送标签到远程]
G --> H[验证 PyPI 发布成功]
H --> I[创建 GitHub Release]
```
资料来源：[RELEASE.md:1-40](https://github.com/qdrant/fastembed/blob/main/RELEASE.md)
---
## 快速开始
### 相关页面
相关主题：[密集文本嵌入](#page-dense-embedding), [稀疏文本嵌入](#page-sparse-embedding), [图像嵌入](#page-image-embedding), [重排序模型](#page-reranker)
相关源码文件
以下源码文件用于生成本页说明：
- [fastembed/text/text_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/text_embedding.py)
- [fastembed/sparse/sparse_text_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/sparse/sparse_text_embedding.py)
- [fastembed/image/image_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/image/image_embedding.py)
- [fastembed/rerank/cross_encoder/text_cross_encoder.py](https://github.com/qdrant/fastembed/blob/main/fastembed/rerank/cross_encoder/text_cross_encoder.py)
- [fastembed/text/onnx_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/onnx_embedding.py)
- [fastembed/text/pooled_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/pooled_embedding.py)
# 快速开始
FastEmbed 是一个高性能的向量嵌入生成库，支持文本嵌入、稀疏嵌入、图像嵌入以及重排序功能。本页面将帮助你在几分钟内开始使用 FastEmbed。
## 安装
```bash
pip install fastembed
```
FastEmbed 默认使用 ONNX Runtime 作为推理引擎，无需额外安装 PyTorch 或 TensorFlow 依赖。
## 核心架构
```mermaid
graph TD
A[FastEmbed] --> B[TextEmbedding 文本嵌入]
A --> C[SparseTextEmbedding 稀疏嵌入]
A --> D[ImageEmbedding 图像嵌入]
A --> E[TextCrossEncoder 重排序]
B --> B1[OnnxTextEmbedding]
B --> B2[PooledEmbedding]
B --> B3[PooledNormalizedEmbedding]
C --> C1[SPLADE++]
C --> C2[BM25]
C --> C3[MiniCOIL]
```
## 文本嵌入
### 基础使用
```python
from fastembed import TextEmbedding
# 使用默认模型 BAAI/bge-small-en-v1.5
model = TextEmbedding(model_name="BAAI/bge-small-en-v1.5")
documents = [
"FastEmbed is a fast embedding library",
"It supports multiple embedding types",
"Vectors can be used with Qdrant or other databases"
]
# 生成嵌入向量
embeddings = list(model.embed(documents))
```
### 支持的模型列表
FastEmbed 支持多种文本嵌入模型，按类型分类如下：
| 模型名称 | 维度 | 类型 | 许可证 | 模型来源 |
|---------|------|------|--------|----------|
| `BAAI/bge-small-en-v1.5` | 384 | 英文 | MIT | HuggingFace |
| `BAAI/bge-base-en-v1.5` | 768 | 英文 | MIT | HuggingFace |
| `BAAI/bge-large-en-v1.5` | 1024 | 英文 | MIT | HuggingFace |
| `jinaai/jina-embeddings-v2-base-en` | 768 | 英文 | Apache 2.0 | HuggingFace |
| `jinaai/jina-embeddings-v2-small-en` | 512 | 英文 | Apache 2.0 | HuggingFace |
| `snowflake/snowflake-arctic-embed-xs` | 384 | 英文 | Apache 2.0 | HuggingFace |
| `snowflake/snowflake-arctic-embed-s` | 384 | 英文 | Apache 2.0 | HuggingFace |
| `snowflake/snowflake-arctic-embed-m` | 768 | 英文 | Apache 2.0 | HuggingFace |
| `snowflake/snowflake-arctic-embed-l` | 1024 | 英文 | Apache 2.0 | HuggingFace |
| `intfloat/multilingual-e5-small` | 384 | 多语言 | MIT | HuggingFace |
| `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` | 384 | 多语言 | Apache 2.0 | HuggingFace |
资料来源：[fastembed/text/onnx_embedding.py:1-100]()
### 初始化参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model_name` | `str` | `"BAAI/bge-small-en-v1.5"` | 模型名称 |
| `cache_dir` | `str \| None` | `None` | 缓存目录 |
| `threads` | `int \| None` | `None` | 线程数 |
| `providers` | `Sequence[OnnxProvider] \| None` | `None` | ONNX 执行提供者 |
| `cuda` | `bool \| Device` | `Device.AUTO` | CUDA 设备支持 |
| `lazy_load` | `bool` | `False` | 延迟加载模式 |
资料来源：[fastembed/text/onnx_embedding.py:47-75]()
## 稀疏嵌入
### SPLADE++ 使用
```python
from fastembed import SparseTextEmbedding
model = SparseTextEmbedding(model_name="prithivida/Splade_PP_en_v1")
documents = [
"FastEmbed is a fast embedding library",
"It supports sparse vectors"
]
embeddings = list(model.embed(documents))
# 返回: SparseEmbedding(indices=[17, 123, 919, ...], values=[0.71, 0.22, 0.39, ...])
```
### 稀疏嵌入类型
| 类型 | 模型 | 特点 |
|------|------|------|
| SPLADE++ | `prithivida/Splade_PP_en_v1` | 结合语义与关键词匹配 |
| BM25 | `Qdrant/bm25` | 传统排序算法 |
| MiniCOIL | `Qdrant/minicoil-v1` | 词汇与语义混合 |
资料来源：[fastembed/sparse/sparse_text_embedding.py]()
资料来源：[fastembed/sparse/bm25.py:1-50]()
## 图像嵌入
### 基础使用
```python
from fastembed import ImageEmbedding
model = ImageEmbedding(model_name="Qdrant/resnet50-onnx")
images = [
"./image1.jpg",
"./image2.jpg",
"https://example.com/image.jpg"
]
embeddings = list(model.embed(images))
```
### 支持的图像模型
| 模型名称 | 维度 | 类型 | 许可证 |
|---------|------|------|--------|
| `Qdrant/resnet50-onnx` | 2048 | 图像 | Apache 2.0 |
| `Qdrant/Unicom-ViT-B-16` | 768 | 多模态 (文本+图像) | Apache 2.0 |
| `Qdrant/Unicom-ViT-B-32` | 512 | 多模态 (文本+图像) | Apache 2.0 |
| `jinaai/jina-clip-v1` | 768 | 多模态 (文本+图像) | Apache 2.0 |
资料来源：[fastembed/image/onnx_embedding.py:1-50]()
## 重排序 (Cross-Encoder)
### 使用示例
```python
from fastembed import TextCrossEncoder
model = TextCrossEncoder(model_name="jinaai/jina-reranker-v1-turbo-en")
query = "What is FastEmbed?"
documents = [
"FastEmbed is a fast embedding library",
"PyTorch is a deep learning framework",
"FastEmbed uses ONNX for inference"
]
scores = model.rerank(query, documents)
```
### 支持的重排序模型
| 模型名称 | 上下文长度 | 许可证 | 说明 |
|---------|-----------|--------|------|
| `jinaai/jina-reranker-v1-turbo-en` | 512 | Apache 2.0 | 英文重排序 |
| `jinaai/jina-reranker-v2-base-multilingual` | 1024 | CC BY-NC 4.0 | 多语言重排序 |
资料来源：[fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py:1-80]()
## 多模态嵌入
### Jina CLIP 模型
`jinaai/jina-clip-v1` 支持同时处理文本和图像：
```python
from fastembed import TextEmbedding, ImageEmbedding
text_model = TextEmbedding(model_name="jinaai/jina-clip-v1")
image_model = ImageEmbedding(model_name="jinaai/jina-clip-v1")
text_emb = list(text_model.embed(["a cat"]))
image_emb = list(image_model.embed(["cat.jpg"]))
```
资料来源：[fastembed/image/onnx_embedding.py:40-50]()
## 常见使用模式
### 批量处理
```python
from fastembed import TextEmbedding
model = TextEmbedding(model_name="BAAI/bge-base-en-v1.5")
# 批量处理大批量文档
batch_size = 32
all_embeddings = []
for i in range(0, len(documents), batch_size):
batch = documents[i:i + batch_size]
embeddings = list(model.embed(batch))
all_embeddings.extend(embeddings)
```
### 自定义缓存目录
```python
import os
os.environ["FASTEMBED_CACHE_PATH"] = "/path/to/cache"
from fastembed import TextEmbedding
model = TextEmbedding() # 模型将下载到指定目录
```
## 下一步
- 查看 [支持的模型完整列表](https://github.com/qdrant/fastembed) 获取更多模型信息
- 了解如何在 [Qdrant](https://qdrant.tech/) 中使用生成的向量
- 探索 [高级配置选项](https://qdrant.github.io/fastembed/) 优化性能
---
## 系统架构
### 相关页面
相关主题：[FastEmbed 概述](#page-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [fastembed/common/onnx_model.py](https://github.com/qdrant/fastembed/blob/main/fastembed/common/onnx_model.py)
- [fastembed/parallel_processor.py](https://github.com/qdrant/fastembed/blob/main/fastembed/parallel_processor.py)
- [fastembed/common/model_management.py](https://github.com/qdrant/fastembed/blob/main/fastembed/common/model_management.py)
- [fastembed/common/types.py](https://github.com/qdrant/fastembed/blob/main/fastembed/common/types.py)
# 系统架构
## 1. 概览
FastEmbed 是一个高性能向量嵌入库，专为快速文本和图像嵌入生成而设计。其系统架构采用分层设计，核心基于 ONNX Runtime 实现跨平台高效推理。整个系统由模型管理层、并行处理层、ONNX 模型层和嵌入模型层四部分组成，通过模块化设计实现了灵活性与性能的平衡。
FastEmbed 支持多种嵌入类型：稠密嵌入（Dense Embedding）、稀疏嵌入（Sparse Embedding）和图像嵌入（Image Embedding），并提供交叉编码器（Cross Encoder）用于重排序任务。
## 2. 核心架构分层
FastEmbed 的架构采用分层设计，各层职责明确，层与层之间通过抽象接口进行交互。
```mermaid
graph TD
subgraph "表现层"
A[TextEmbedding]
B[SparseTextEmbedding]
C[ImageEmbedding]
D[TextCrossEncoder]
end
subgraph "嵌入模型层"
A --> E[OnnxTextEmbedding]
B --> F[MiniCOIL / Splade]
C --> G[OnnxImageEmbedding]
D --> H[OnnxTextCrossEncoder]
end
subgraph "ONNX模型层"
E --> I[OnnxTextModel]
G --> J[OnnxImageModel]
H --> K[OnnxCrossEncoderModel]
end
subgraph "运行时层"
I --> L[ONNX Runtime]
J --> L
K --> L
end
subgraph "支撑模块"
L --> M[ModelManagement]
M --> N[ParallelProcessor]
end
```
### 架构层级说明
| 层级 | 组件 | 职责 |
|------|------|------|
| 表现层 | TextEmbedding, SparseTextEmbedding 等 | 提供面向用户的 API |
| 嵌入模型层 | OnnxTextEmbedding, PooledEmbedding 等 | 实现具体嵌入逻辑 |
| ONNX模型层 | OnnxTextModel, OnnxImageModel | 模型加载与推理 |
| 运行时层 | ONNX Runtime | 底层张量计算 |
| 支撑模块 | ModelManagement, ParallelProcessor | 模型管理与并行处理 |
## 3. ONNX模型层
### 3.1 OnnxTextModel 核心实现
`OnnxTextModel` 是文本嵌入模型的基础类，封装了 ONNX Runtime 的核心操作逻辑。
```mermaid
graph TD
A[文本输入] --> B[Tokenization]
B --> C[ONNX Input Dict]
C --> D[session.run]
D --> E[ONNX Output]
E --> F[_post_process_onnx_output]
F --> G[标准化嵌入向量]
```
核心参数定义：
| 参数 | 类型 | 说明 |
|------|------|------|
| `model_name` | str | 模型名称，标识要加载的具体模型 |
| `cache_dir` | str \| None | 模型缓存目录路径 |
| `threads` | int \| None | 推理线程数 |
| `providers` | Sequence[OnnxProvider] \| None | ONNX 执行提供者（CPU/CUDA/ROCm）|
| `cuda` | bool \| Device | CUDA 设备配置 |
| `device_ids` | list[int] \| None | 多 GPU 设备 ID 列表 |
| `lazy_load` | bool | 是否延迟加载模型 |
### 3.2 输出后处理机制
`OnnxTextModel` 定义了灵活的输出后处理钩子，通过 `_post_process_onnx_output` 方法实现不同模型的输出格式化：
```python
def _post_process_onnx_output(
self, output: OnnxOutputContext, **kwargs: Any
) -> Iterable[NumpyArray]:
embeddings = output.model_output
if embeddings.ndim == 3: # (batch_size, seq_len, embedding_dim)
processed_embeddings = embeddings[:, 0]
elif embeddings.ndim == 2: # (batch_size, embedding_dim)
processed_embeddings = embeddings
else:
raise ValueError(f"Unsupported embedding shape: {embeddings.shape}")
return normalize(processed_embeddings)
```
资料来源：[fastembed/text/onnx_embedding.py:220-234]()
输出维度处理策略：
- **3D 输出** `(batch, seq_len, dim)`：取第一个 token 的输出（如 CLS token）
- **2D 输出** `(batch, dim)`：直接使用
## 4. 嵌入模型层
### 4.1 模型类型分类
FastEmbed 支持三种核心嵌入类型：
| 模型类型 | 基类 | 输出维度 | 典型应用 |
|----------|------|----------|----------|
| OnnxTextEmbedding | TextEmbeddingBase | 384-1024 | 文本向量化 |
| PooledEmbedding | PooledEmbedding | 768-1024 | 需要平均池化的模型 |
| SparseTextEmbedding | SparseTextEmbeddingBase | 可变 | 稀疏/SPLADE 嵌入 |
| OnnxImageEmbedding | ImageEmbeddingBase | 512-768 | 图像向量化 |
### 4.2 池化策略实现
对于需要 Mean Pooling 的模型（如 `jinaai/jina-embeddings-v2-*`），系统提供了 `PooledEmbedding` 基类：
```python
class PooledNormalizedEmbedding(PooledEmbedding):
def _post_process_onnx_output(
self, output: OnnxOutputContext, **kwargs: Any
) -> Iterable[NumpyArray]:
if output.attention_mask is None:
raise ValueError("attention_mask must be provided for document post-processing")
embeddings = output.model_output
attn_mask = output.attention_mask
return normalize(self.mean_pooling(embeddings, attn_mask))
```
资料来源：[fastembed/text/pooled_normalized_embedding.py:95-106]()
Mean Pooling 计算公式：
$$v_{pooled} = \frac{\sum_{i=1}^{n} v_i \cdot m_i}{\sum_{i=1}^{n} m_i}$$
其中 $v_i$ 是 token 嵌入，$m_i$ 是注意力掩码。
### 4.3 支持的嵌入模型
#### 稠密嵌入模型
| 模型名称 | 维度 | 输入限制 | 语言 | 池化方式 |
|----------|------|----------|------|----------|
| BAAI/bge-small-en-v1.5 | 384 | 512 tokens | 英语 | CLS |
| BAAI/bge-base-en-v1.5 | 768 | 512 tokens | 英语 | CLS |
| BAAI/bge-large-en-v1.5 | 1024 | 512 tokens | 英语 | CLS |
| jinaai/jina-embeddings-v2-base-en | 768 | 8192 tokens | 英语 | Mean |
| jinaai/jina-embeddings-v2-base-zh | 768 | 8192 tokens | 中英混合 | Mean |
| snowflake/snowflake-arctic-embed-m | 768 | 512 tokens | 英语 | Mean |
| thenlper/gte-large | 1024 | 512 tokens | 英语 | Mean |
#### 稀疏嵌入模型
| 模型名称 | 特点 | 适用场景 |
|----------|------|----------|
| prithivida/Splade_PP_en_v1 | 词汇稀疏+语义 | 关键词增强检索 |
| Qdrant/minicoil-v1 | BM25 风格 | 混合语义+精确匹配 |
## 5. 并行处理层
### 5.1 并行处理器架构
`ParallelProcessor` 是 FastEmbed 实现批量处理的核心组件，支持多线程和进程级并行。
```mermaid
graph TD
A[批量文档输入] --> B[ParallelProcessor]
B --> C{lazy_load 模式}
C -->|False| D[预初始化 Worker]
C -->|True| E[按需初始化 Worker]
D --> F[Worker Pool]
E --> F
F --> G[Thread/Process 1]
F --> H[Thread/Process 2]
F --> I[Thread/Process N]
G --> J[结果收集]
H --> J
I --> J
J --> K[Iterator 输出]
```
### 5.2 Worker 类层次结构
```
OnnxTextEmbeddingWorker
├── PooledNormalizedEmbeddingWorker
├── CLIPEmbeddingWorker
└── TextEmbeddingWorker
```
Worker 类的核心职责：
| 方法 | 职责 |
|------|------|
| `init_embedding` | 初始化嵌入模型实例 |
| `init_process` | 设置进程级资源 |
| `embed` | 执行单批次嵌入生成 |
### 5.3 批处理参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `batch_size` | 每批处理文档数 | 32 |
| `parallel` | 并行 worker 数量 | None（自动检测）|
## 6. 模型管理
### 6.1 模型描述结构
```python
@dataclass
class DenseModelDescription:
model: str # HuggingFace 模型标识
dim: int # 输出向量维度
description: str # 模型描述
license: str # 许可证类型
size_in_GB: float # 模型大小（GB）
sources: ModelSource # 模型来源配置
model_file: str # ONNX 文件名
additional_files: list[str] = [] # 附加文件
requires_idf: bool = False # 是否需要 IDF 权重
```
### 6.2 模型来源配置
```python
@dataclass
class ModelSource:
hf: str # HuggingFace Hub 标识
url: str | None = None # 备用 URL（私有存储）
_deprecated_tar_struct: bool = False # 是否使用旧版 tar 结构
```
模型加载优先级：
1. 本地缓存目录（`cache_dir`）
2. HuggingFace Hub
3. 备用 URL（如果配置）
### 6.3 模型缓存机制
```mermaid
graph LR
A[模型请求] --> B{本地缓存存在?}
B -->|是| C[使用缓存模型]
B -->|否| D{HuggingFace Hub}
D -->|存在| E[下载并缓存]
D -->|不存在| F{备用URL}
F -->|存在| G[下载并缓存]
F -->|不存在| H[抛出异常]
C --> I[加载ONNX模型]
E --> I
G --> I
I --> J[创建InferenceSession]
```
## 7. 数据流与处理管道
### 7.1 完整嵌入生成流程
```mermaid
sequenceDiagram
participant U as 用户
participant TE as TextEmbedding
participant PP as ParallelProcessor
participant W as Worker
participant ONNX as OnnxTextModel
participant RT as ONNX Runtime
U->>TE: embed(documents, batch_size=32)
TE->>PP: process(documents, batch_size)
PP->>W: init_embedding()
loop 批次循环
PP->>W: embed_batch(batch)
W->>ONNX: 预处理输入
ONNX->>RT: session.run()
RT-->>ONNX: 原始输出
ONNX-->>W: 后处理输出
W-->>PP: 归一化嵌入向量
end
PP-->>TE: Iterator[Embeddings]
TE-->>U: 返回结果
```
### 7.2 ONNX 输入输出格式
输入字典结构：
```python
{
"input_ids": NumpyArray(shape=(batch, seq_len), dtype=int64),
"attention_mask": NumpyArray(shape=(batch, seq_len), dtype=int64),
"token_type_ids": NumpyArray(shape=(batch, seq_len), dtype=int64) # 可选
}
```
输出上下文：
```python
@dataclass
class OnnxOutputContext:
model_output: NumpyArray # 模型原始输出
attention_mask: NumpyArray | None # 注意力掩码
```
## 8. 设备与提供者配置
### 8.1 执行提供者支持
| 提供者 | 标识符 | 说明 |
|--------|--------|------|
| CPU | CPUExecutionProvider | 默认，通用设备 |
| CUDA | CUDAExecutionProvider | NVIDIA GPU 加速 |
| ROCm | ROCmExecutionProvider | AMD GPU 加速 |
### 8.2 设备自动检测
```python
@dataclass
class Device(Enum):
AUTO = "auto" # 自动选择可用设备
CPU = "cpu" # 强制使用 CPU
CUDA = "cuda" # 强制使用 CUDA
```
设备选择逻辑：
- `cuda=True/auto`：优先使用 CUDA，不可用时回退 CPU
- `cuda=False`：强制使用 CPU
- `device_id`：指定特定 GPU 设备
## 9. 扩展性设计
### 9.1 模型注册机制
新增模型只需在 `supported_onnx_models` 列表中添加配置：
```python
DenseModelDescription(
model="custom/model-name",
dim=768,
description="Custom model description",
license="apache-2.0",
size_in_GB=0.5,
sources=ModelSource(hf="custom/model-name"),
model_file="onnx/model.onnx",
)
```
### 9.2 自定义后处理
通过继承 `OnnxTextModel` 并重写 `_post_process_onnx_output` 方法，可以实现自定义输出处理逻辑：
```python
class CustomEmbedding(OnnxTextEmbedding):
def _post_process_onnx_output(
self, output: OnnxOutputContext, **kwargs: Any
) -> Iterable[NumpyArray]:
# 自定义后处理逻辑
embeddings = output.model_output
return custom_normalization(embeddings)
```
## 10. 架构设计原则
| 原则 | 实现方式 |
|------|----------|
| 模块化 | 分层架构，层间通过抽象接口交互 |
| 可扩展性 | 模型描述符注册机制支持新模型 |
| 性能优先 | ONNX Runtime + 并行处理 |
| 跨平台 | 支持 CPU/CUDA/ROCm 多设备 |
| 懒加载 | `lazy_load` 选项延迟模型加载 |
| 缓存友好 | 模型缓存机制减少重复下载 |
---
## 密集文本嵌入
### 相关页面
相关主题：[快速开始](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [fastembed/text/onnx_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/onnx_embedding.py)
- [fastembed/text/pooled_normalized_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/pooled_normalized_embedding.py)
- [fastembed/text/pooled_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/pooled_embedding.py)
- [fastembed/text/text_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/text_embedding.py)
- [fastembed/text/text_embedding_base.py](https://github.com/qdrant/fastembed/blob/main/fastembed/text/text_embedding_base.py)
- [fastembed/sparse/bm25.py](https://github.com/qdrant/fastembed/blob/main/fastembed/sparse/bm25.py)
# 密集文本嵌入
## 概述
密集文本嵌入（Dense Text Embedding）是 FastEmbed 库的核心功能之一，用于将文本转换为高维稠密向量表示。与稀疏向量不同，密集向量将文本的语义信息压缩到连续的向量空间中，使得语义相似的文本在向量空间中具有较近的距离。
FastEmbed 的密集文本嵌入基于 ONNX（Open Neural Network Exchange）运行时实现，支持多种预训练模型，包括 BGE、GTE、Jina Embeddings、E5、Arctic Embed 等系列模型。这些模型经过优化，可在不同硬件平台上高效运行，包括 CPU、CUDA GPU 和 Apple Silicon 等设备。资料来源：[fastembed/text/onnx_embedding.py:1-50]()
## 架构设计
### 类层次结构
FastEmbed 的密集文本嵌入模块采用继承和组合的设计模式，核心类层次结构如下：
```mermaid
graph TD
A[TextEmbeddingBase] --> B[OnnxTextEmbedding]
B --> C[PooledEmbedding]
C --> D[PooledNormalizedEmbedding]
B --> E[CLIPOnnxEmbedding]
F[OnnxTextEmbeddingWorker] --> G[PooledEmbeddingWorker]
G --> H[PooledNormalizedEmbeddingWorker]
F --> I[CLIPEmbeddingWorker]
J[OnnxTextModel] -.->|组合| B
K[NumpyArray] -.->|类型参数| B
```
所有密集文本嵌入类都继承自 `OnnxTextEmbedding`，该类同时继承 `TextEmbeddingBase` 和 `OnnxTextModel[NumpyArray]`，实现了 ONNX 运行时与文本嵌入逻辑的结合。资料来源：[fastembed/text/onnx_embedding.py:60-70]()
### 工作流程
密集文本嵌入的处理流程包括模型加载、输入预处理、ONNX 推理和输出后处理四个阶段：
```mermaid
graph LR
A[输入文本] --> B[tokenize]
B --> C[ONNX 模型推理]
C --> D[attention_mask]
D --> E[mean_pooling]
E --> F[normalize]
F --> G[密集向量输出]
```
对于标准的 `OnnxTextEmbedding`，处理流程使用平均池化（Mean Pooling）结合注意力掩码来聚合 token 级别的嵌入表示。`PooledNormalizedEmbedding` 进一步对结果进行 L2 归一化，确保输出向量的模长为 1，这对于余弦相似度计算尤为重要。资料来源：[fastembed/text/pooled_normalized_embedding.py:75-85]()
## 核心类详解
### OnnxTextEmbedding
`OnnxTextEmbedding` 是所有密集文本嵌入实现的基础类，负责模型管理和 ONNX 运行时交互。
#### 初始化参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model_name` | `str` | `"BAAI/bge-small-en-v1.5"` | 模型名称，默认为 BGE 小型英文模型 |
| `cache_dir` | `str \| None` | `None` | 模型缓存目录，可通过 `FASTEMBED_CACHE_PATH` 环境变量设置 |
| `threads` | `int \| None` | `None` | ONNX Runtime 线程数 |
| `providers` | `Sequence[OnnxProvider] \| None` | `None` | ONNX 推理提供者列表 |
| `cuda` | `bool \| Device` | `Device.AUTO` | CUDA 加速配置 |
| `device_ids` | `list[int] \| None` | `None` | 多 GPU 设备 ID 列表 |
| `lazy_load` | `bool` | `False` | 是否延迟加载模型 |
| `device_id` | `int \| None` | `None` | 指定设备 ID |
| `specific_model_path` | `str \| None` | `None` | 特定模型路径 |
资料来源：[fastembed/text/onnx_embedding.py:62-90]()
#### 核心方法
- `_list_supported_models()`: 返回支持的模型列表，定义在各个子类中
- `_post_process_onnx_output()`: 对 ONNX 模型输出进行后处理
- `embed()`: 主嵌入方法，处理单批或多批文档
### PooledNormalizedEmbedding
`PooledNormalizedEmbedding` 是最常用的密集文本嵌入实现，它在平均池化后对向量进行 L2 归一化，确保输出向量具有单位长度。
```python
def _post_process_onnx_output(
self, output: OnnxOutputContext, **kwargs: Any
) -> Iterable[NumpyArray]:
if output.attention_mask is None:
raise ValueError("attention_mask must be provided for document post-processing")
embeddings = output.model_output
attn_mask = output.attention_mask
return normalize(self.mean_pooling(embeddings, attn_mask))
```
该类使用 `mean_pooling` 方法对 token 嵌入进行聚合，并通过 `normalize` 函数（使用 L2 范数）对结果进行归一化处理。资料来源：[fastembed/text/pooled_normalized_embedding.py:76-85]()
## 支持的模型
FastEmbed 支持多种密集文本嵌入模型，按功能和应用场景分类如下：
### BGE 系列
BGE（BAAI General Embedding）系列是由北京人工智能研究院开发的通用文本嵌入模型。
| 模型名称 | 维度 | 输入截断 | 许可证 | 大小 |
|----------|------|----------|--------|------|
| `BAAI/bge-small-en-v1.5` | 384 | 512 tokens | MIT | 0.067 GB |
| `BAAI/bge-base-en-v1.5` | 768 | 512 tokens | MIT | 0.22 GB |
| `BAAI/bge-large-en-v1.5` | 1024 | 512 tokens | MIT | 1.20 GB |
| `BAAI/bge-small-zh-v1.5` | 512 | 512 tokens | MIT | 0.09 GB |
BGE 模型在 MS-MARCO 和 BEIR 基准测试中表现优异，是当前最流行的开源嵌入模型之一。资料来源：[fastembed/text/onnx_embedding.py:80-150]()
### Jina Embeddings 系列
Jina AI 开发的多语言嵌入模型，支持长达 8192 tokens 的输入。
| 模型名称 | 维度 | 语言 | 许可证 | 大小 |
|----------|------|------|--------|------|
| `jinaai/jina-embeddings-v2-base-en` | 768 | 英文 | Apache-2.0 | 0.52 GB |
| `jinaai/jina-embeddings-v2-small-en` | 512 | 英文 | Apache-2.0 | 0.12 GB |
| `jinaai/jina-embeddings-v2-base-de` | 768 | 德文/英文 | Apache-2.0 | 0.64 GB |
| `jinaai/jina-embeddings-v2-base-es` | 768 | 西班牙文/英文 | Apache-2.0 | 0.64 GB |
| `jinaai/jina-embeddings-v2-base-zh` | 768 | 中文/英文 | Apache-2.0 | 0.64 GB |
Jina Embeddings v2 系列的核心优势在于超长上下文窗口（8192 tokens），适合处理长文档检索任务。资料来源：[fastembed/text/onnx_embedding.py:100-180]()
### E5 系列
E5（Embeddings from bi-directional language models）系列专注于高效的文本嵌入，支持大规模多语言场景。
| 模型名称 | 维度 | 语言 | 输入截断 | 许可证 | 大小 |
|----------|------|------|----------|--------|------|
| `intfloat/e5-small-v2` | 384 | 多语言 | 512 tokens | MIT | 0.13 GB |
| `intfloat/e5-base-v2` | 768 | 多语言 | 512 tokens | MIT | 0.43 GB |
| `intfloat/multilingual-e5-small` | 384 | ~100 种语言 | 512 tokens | MIT | 0.22 GB |
| `intfloat/multilingual-e5-large` | 1024 | ~100 种语言 | 512 tokens | MIT | 2.24 GB |
E5 模型需要添加查询前缀（query prefix）以获得最佳性能，这与其他模型的通用处理方式有所不同。资料来源：[fastembed/text/pooled_embedding.py:60-100]()
### Snowflake Arctic Embed 系列
Snowflake 开发的嵌入式模型，专注于企业级应用场景。
| 模型名称 | 维度 | 输入截断 | 许可证 | 大小 |
|----------|------|----------|--------|------|
| `snowflake/snowflake-arctic-embed-xs` | 384 | 512 tokens | Apache-2.0 | 0.09 GB |
| `snowflake/snowflake-arctic-embed-s` | 384 | 512 tokens | Apache-2.0 | 0.13 GB |
| `snowflake/snowflake-arctic-embed-m` | 768 | 512 tokens | Apache-2.0 | 0.43 GB |
| `snowflake/snowflake-arctic-embed-m-long` | 768 | 2048 tokens | Apache-2.0 | 0.54 GB |
| `snowflake/snowflake-arctic-embed-l` | 1024 | 512 tokens | Apache-2.0 | 1.02 GB |
### GTE 系列
GTE（General Text Embeddings）系列由 Thenlper 开发。
| 模型名称 | 维度 | 语言 | 输入截断 | 许可证 | 大小 |
|----------|------|------|----------|--------|------|
| `thenlper/gte-base` | 768 | 英文 | 512 tokens | MIT | 0.44 GB |
| `thenlper/gte-large` | 1024 | 英文 | 512 tokens | MIT | 1.20 GB |
资料来源：[fastembed/text/pooled_normalized_embedding.py:40-70]()
## 使用方法
### 基本用法
```python
from fastembed import TextEmbedding
# 初始化模型（默认使用 BAAI/bge-small-en-v1.5）
model = TextEmbedding(model_name="BAAI/bge-base-en-v1.5")
# 单文档嵌入
query_embedding = next(model.embed(["What is FastEmbed?"]))
# 多文档嵌入
documents = [
"FastEmbed is a fast embedding library",
"It supports multiple embedding models",
"Based on ONNX runtime for efficiency"
]
embeddings = list(model.embed(documents))
```
### 批处理
```python
from fastembed import TextEmbedding
model = TextEmbedding(model_name="BAAI/bge-large-en-v1.5")
# 批处理文档
batch_documents = [
["Document 1 paragraph 1", "Document 1 paragraph 2"],
["Document 2 paragraph 1", "Document 2 paragraph 2"]
]
for batch in model.embed(batch_documents, batch_size=32):
# 处理每个批次
pass
```
### 与稀疏嵌入结合
FastEmbed 支持同时使用密集嵌入和稀疏嵌入，这种混合检索方式可以结合两者的优势：
```python
from fastembed import TextEmbedding, SparseTextEmbedding
dense_model = TextEmbedding(model_name="BAAI/bge-base-en-v1.5")
sparse_model = SparseTextEmbedding(model_name="prithivida/Splade_PP_en_v1")
# 获取密集向量
dense_embeddings = list(dense_model.embed(documents))
# 获取稀疏向量
sparse_embeddings = list(sparse_model.embed(documents))
```
资料来源：[fastembed/sparse/bm25.py:1-30]()
## 后处理机制
### 平均池化（Mean Pooling）
平均池化是密集文本嵌入中最常用的聚合策略，它根据 attention_mask 加权平均所有 token 的嵌入：
```python
def mean_pooling(self, embedding_output: NumpyArray, attention_mask: NumpyArray) -> NumpyArray:
# 将 padding 位置的嵌入置零
input_mask_expanded = np.broadcast_to(
np.expand_dims(attention_mask, -1), embedding_output.shape
)
sum_embeddings = np.sum(embedding_output * input_mask_expanded, axis=1)
sum_mask = np.clip(np.sum(attention_mask, axis=1, keepdims=True), a_min=1e-9, a_max=None)
return sum_embeddings / sum_mask
```
### L2 归一化
归一化处理确保输出向量的 L2 范数为 1，这对于使用余弦相似度进行向量比较至关重要：
```python
def normalize(embeddings: NumpyArray) -> NumpyArray:
norms = np.linalg.norm(embeddings, axis=1, keepdims=True)
return embeddings / norms
```
归一化后的向量使得点积运算等价于余弦相似度计算，可以显著提升检索效率。资料来源：[fastembed/text/pooled_normalized_embedding.py:78-85]()
## ONNX 运行时配置
### 提供者配置
FastEmbed 支持多种 ONNX Runtime 提供者，优先级从高到低：
| 提供者 | 设备 | 优先级 |
|--------|------|--------|
| `CUDAExecutionProvider` | GPU (NVIDIA) | 最高 |
| `CPUExecutionProvider` | CPU | 默认 |
### 设备自动选择
通过 `Device.AUTO` 配置，系统会自动选择最佳可用设备：
```python
from fastembed import TextEmbedding, Device
# 自动检测最佳设备
model = TextEmbedding(model_name="BAAI/bge-base-en-v1.5", cuda=True)
# 强制使用 CPU
model = TextEmbedding(model_name="BAAI/bge-base-en-v1.5", cuda=False)
# 指定特定 GPU 设备
model = TextEmbedding(model_name="BAAI/bge-base-en-v1.5", device_ids=[0, 1])
```
## 性能优化
### 模型缓存
首次使用模型时会自动下载并缓存到本地目录：
```python
import os
# 设置自定义缓存目录
os.environ["FASTEMBED_CACHE_PATH"] = "/path/to/cache"
# 或在初始化时指定
model = TextEmbedding(model_name="BAAI/bge-large-en-v1.5", cache_dir="/path/to/cache")
```
### 延迟加载
对于多模型场景，可以使用延迟加载减少初始内存占用：
```python
model = TextEmbedding(
model_name="BAAI/bge-base-en-v1.5",
lazy_load=True
)
```
### 多线程配置
对于 CPU 推理，可以通过调整线程数优化性能：
```python
model = TextEmbedding(
model_name="BAAI/bge-base-en-v1.5",
threads=8 # 使用 8 个线程
)
```
## 与稀疏嵌入的对比
| 特性 | 密集嵌入 | 稀疏嵌入 |
|------|----------|----------|
| 向量表示 | 连续高维向量 | 离散稀疏向量 |
| 语义捕获 | 强 | 弱（依赖关键词） |
| 精确匹配 | 弱 | 强 |
| 计算效率 | 高（向量维度固定） | 低（需遍历非零元素） |
| 适用场景 | 语义检索、相似度匹配 | 关键词匹配、混合检索 |
| 代表模型 | BGE, Jina, E5 | SPLADE, BM25 |
FastEmbed 推荐在大多数场景使用 `PooledNormalizedEmbedding`（密集嵌入），在需要精确关键词匹配或混合检索时结合使用稀疏嵌入（如 SPLADE 或 BM25）。资料来源：[fastembed/sparse/bm25.py:20-45]()
## 模型选择指南
### 按语言选择
| 语言 | 推荐模型 |
|------|----------|
| 仅英文 | `BAAI/bge-base-en-v1.5`, `jinaai/jina-embeddings-v2-base-en` |
| 中文 | `BAAI/bge-small-zh-v1.5`, `jinaai/jina-embeddings-v2-base-zh` |
| 多语言（少量） | `sentence-transformers/paraphrase-multilingual-mpnet-base-v2` |
| 多语言（100+） | `intfloat/multilingual-e5-small`, `jinaai/jina-embeddings-v2-base-zh` |
### 按性能选择
| 性能需求 | 推荐模型 |
|----------|----------|
| 最高精度 | `BAAI/bge-large-en-v1.5`, `intfloat/multilingual-e5-large` |
| 性价比（精度/速度） | `BAAI/bge-base-en-v1.5`, `thenlper/gte-base` |
| 最快速度 | `BAAI/bge-small-en-v1.5`, `snowflake/snowflake-arctic-embed-xs` |
### 按输入长度选择
| 最大输入长度 | 推荐模型 |
|--------------|----------|
| 512 tokens | `BAAI/bge-*`, `thenlper/gte-*`, `snowflake/snowflake-arctic-embed-*` |
| 2048 tokens | `snowflake/snowflake-arctic-embed-m-long` |
| 8192 tokens | `jinaai/jina-embeddings-v2-*` |
---
## 稀疏文本嵌入
### 相关页面
相关主题：[快速开始](#page-quickstart), [密集文本嵌入](#page-dense-embedding)
相关源码文件
以下源码文件用于生成本页说明：
- [fastembed/sparse/sparse_text_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/sparse/sparse_text_embedding.py)
- [fastembed/sparse/sparse_embedding_base.py](https://github.com/qdrant/fastembed/blob/main/fastembed/sparse/sparse_embedding_base.py)
- [fastembed/sparse/splade_pp.py](https://github.com/qdrant/fastembed/blob/main/fastembed/sparse/splade_pp.py)
- [fastembed/sparse/bm42.py](https://github.com/qdrant/fastembed/blob/main/fastembed/sparse/bm42.py)
- [fastembed/sparse/bm25.py](https://github.com/qdrant/fastembed/blob/main/fastembed/sparse/bm25.py)
- [fastembed/sparse/minicoil.py](https://github.com/qdrant/fastembed/blob/main/fastembed/sparse/minicoil.py)
# 稀疏文本嵌入
## 概述
稀疏文本嵌入（Sparse Text Embedding）是FastEmbed库中处理非密集向量表示的一组模型和工具。与传统的密集嵌入（dense embedding）不同，稀疏嵌入使用高维但大部分为零的向量来表示文本，其中非零值对应于词汇表中特定词汇的重要性权重。
FastEmbed的稀疏嵌入模块主要用于：
- **关键词匹配与语义理解的结合**：在保持精确关键词匹配行为的同时，解析词汇的语义含义
- **BM25风格的稀疏检索**：使用词频统计和逆文档频率（IDF）进行传统信息检索
- **SPLADE++等现代稀疏模型**：通过深度学习生成稀疏但具有语义能力的向量表示
## 架构设计
### 类层次结构
稀疏文本嵌入模块采用模块化的类层次结构设计：
```
SparseTextEmbeddingBase (抽象基类)
├── SpladePp (SPLADE++ 模型)
├── Bm25 (传统BM25实现)
├── Bm42 (BM42模型)
└── MiniCOIL (混合稀疏模型)
```
### 核心组件
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| `SparseTextEmbeddingBase` | `fastembed/sparse/sparse_embedding_base.py` | 定义稀疏嵌入的通用接口和基础实现 |
| `SparseTextEmbedding` | `fastembed/sparse/sparse_text_embedding.py` | 统一的稀疏嵌入使用入口 |
| `SpladePp` | `fastembed/sparse/splade_pp.py` | SPLADE++稀疏嵌入模型实现 |
| `Bm25` | `fastembed/sparse/bm25.py` | BM25传统检索算法实现 |
| `Bm42` | `fastembed/sparse/bm42.py` | BM42稀疏嵌入模型 |
| `MiniCOIL` | `fastembed/sparse/minicoil.py` | MiniCOIL混合稀疏模型 |
### 数据流图
```mermaid
graph TD
A[输入文本] --> B[文本预处理]
B --> C{模型类型选择}
C -->|SPLADE++| D[SpladePp 模型]
C -->|BM25| E[Bm25 模型]
C -->|BM42| F[Bm42 模型]
C -->|MiniCOIL| G[MiniCOIL 模型]
D --> H[SparseEmbedding 输出]
E --> H
F --> H
G --> H
H --> I[indices: 词索引列表]
H --> J[values: 权重值列表]
```
## 支持的稀疏模型
### 模型对比表
| 模型名称 | 维度 | 语言支持 | 许可证 | 模型大小 | 特殊要求 |
|----------|------|----------|--------|----------|----------|
| `prithivida/Splade_PP_en_v1` | 30522 | 英文 | apache-2.0 | ~0.09GB | - |
| `prithivida/Splade_PP_en_v1.5` | 30522 | 英文 | apache-2.0 | ~0.12GB | - |
| `Qdrant/bm42-all-minilm-l6-v2-attentions` | 可变 | 多语言 | apache-2.0 | ~0.09GB | 需要IDF |
| `Qdrant/bm25` | 词汇表大小 | 多语言 | apache-2.0 | ~0.01GB | 需要IDF |
| `Qdrant/minicoil-v1` | 词汇表×4 | 英文 | apache-2.0 | ~0.09GB | 需要IDF |
### 模型详细说明
#### SPLADE++
SPLADE++是一种基于Transformer的稀疏嵌入模型，它通过学习为每个词汇分配权重，生成稀疏但具有语义表达能力的向量。模型的核心特点是：
- **高稀疏性**：大多数维度为零，只有少数重要词汇有非零权重
- **语义能力**：继承了BERT等Transformer模型的语义理解能力
- **端到端学习**：通过对比学习目标函数进行训练
```python
from fastembed import SparseTextEmbedding
model = SparseTextEmbedding(model_name="prithivida/Splade_PP_en_v1")
embeddings = list(model.embed(documents))
```
#### BM25
BM25（Best Matching 25）是一种经典的概率信息检索模型，被实现为稀疏嵌入形式以兼容Qdrant等向量数据库的查询接口。
**BM25公式**：
```
score(q, d) = Σ[ IDF(q_i) * (f(q_i, d) * (k + 1)) / (f(q_i, d) + k * (1 - b + b * (|d| / avg_len))) ]
```
其中：
- `IDF(q_i)`：词项q_i的逆文档频率
- `f(q_i, d)`：词项q_i在文档d中的词频
- `k`、`b`：可调超参数（默认k=1.5, b=0.75）
- `|d|`：文档长度
- `avg_len`：语料库平均文档长度
资料来源：[fastembed/sparse/bm25.py:21-44]()
#### BM42
BM42是一种结合了注意力机制与BM25优点的稀疏嵌入模型。它使用预训练模型的注意力权重来初始化稀疏表示，结合了深度学习的语义能力与传统BM25的可解释性。
#### MiniCOIL
MiniCOIL是一种混合稀疏嵌入模型，结合了语义理解与精确关键词匹配：
- **语义解析**：解析词汇的语义含义
- **关键词保留**：保持精确关键词匹配行为
- **基于词频加权**：每个词汇标记转换为4维稀疏向量分量
每个词汇标记转换为4维分量，根据词频在语料库中进行加权。如果词汇不在词汇表中，处理方式与BM25完全相同。
## API参考
### SparseTextEmbedding 类
```python
from fastembed import SparseTextEmbedding
model = SparseTextEmbedding(
model_name: str, # 模型名称
cache_dir: str | None, # 缓存目录
threads: int | None, # 并行线程数
**kwargs # 其他参数
)
```
### 核心方法
#### `embed()`
```python
def embed(
documents: Iterable[str],
batch_size: int = 256,
parallel: int | None = None,
**kwargs
) -> Iterable[SparseEmbedding]
```
**参数说明**：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `documents` | `Iterable[str]` | - | 输入文本列表 |
| `batch_size` | `int` | 256 | 批处理大小 |
| `parallel` | `int \| None` | None | 并行处理数 |
**返回类型**：`Iterable[SparseEmbedding]`
### SparseEmbedding 数据结构
```python
class SparseEmbedding:
indices: list[int] # 非零元素的词索引
values: list[float] # 对应的权重值
```
**示例**：
```
SparseEmbedding(indices=[17, 123, 919, ...], values=[0.71, 0.22, 0.39, ...])
```
## 使用示例
### 基本用法
```python
from fastembed import SparseTextEmbedding
# 初始化模型
model = SparseTextEmbedding(model_name="prithivida/Splade_PP_en_v1")
# 输入文档
documents = [
"What is the capital of France?",
"Paris is the capital of France.",
"Berlin is the capital of Germany."
]
# 生成稀疏嵌入
embeddings = list(model.embed(documents))
# 访问结果
for doc_embedding in embeddings:
print(f"Indices: {doc_embedding.indices}")
print(f"Values: {doc_embedding.values}")
```
### 使用不同模型
```python
# BM25模型
bm25_model = SparseTextEmbedding(model_name="Qdrant/bm25")
# BM42模型
bm42_model = SparseTextEmbedding(model_name="Qdrant/bm42-all-minilm-l6-v2-attentions")
# SPLADE++模型
splade_model = SparseTextEmbedding(model_name="prithivida/Splade_PP_en_v1.5")
```
### 批处理与并行
```python
from fastembed import SparseTextEmbedding
model = SparseTextEmbedding(model_name="prithivida/Splade_PP_en_v1")
# 大规模文档处理
large_corpus = ["文档内容..." for _ in range(10000)]
# 使用批处理
embeddings = list(model.embed(
documents=large_corpus,
batch_size=512,
parallel=4 # 使用4个并行worker
))
```
## 内部实现机制
### MiniCOIL向量转换
MiniCOIL模型使用特殊的向量转换机制将句子嵌入转换为Qdrant兼容的稀疏向量格式：
```mermaid
graph LR
A[Sentence Embedding] --> B[Vocabulary Words]
A --> C[Out-of-Vocabulary Words]
B --> D[Known Word Embedding
4-dim component]
C --> E[BM25 Fallback
count=1, word_id=-1]
D --> F[Combined Sparse Vector]
E --> F
```
关键参数：
- `vocab_size`：词汇表大小
- `embedding_size`：每个词的嵌入维度（固定为4）
- `GAP`：桶大小（固定为32000）
- `unknown_words_shift`：OOV词起始ID偏移
资料来源：[fastembed/sparse/utils/sparse_vectors_converter.py:21-48]()
### ONNX运行时
所有稀疏模型都基于ONNX（Open Neural Network Exchange）运行时执行：
1. **模型加载**：从HuggingFace Hub或本地缓存加载ONNX模型
2. **推理执行**：使用ONNX Runtime执行模型推理
3. **后处理**：将模型输出转换为标准SparseEmbedding格式
### 特殊配置
某些稀疏模型需要额外的IDF（逆文档频率）配置：
```python
DenseModelDescription(
model="Qdrant/bm42-all-minilm-l6-v2-attentions",
requires_idf=True, # 需要IDF文件
additional_files=["model.onnx_data"]
)
```
当`requires_idf=True`时，模型会加载语料库级别的IDF统计信息用于查询重加权。
## 配置与调优
### 模型参数
| 参数 | 适用模型 | 说明 |
|------|----------|------|
| `cache_dir` | 全部 | 模型缓存目录 |
| `threads` | 全部 | ONNX Runtime线程数 |
| `batch_size` | 全部 | 推理批处理大小 |
| `k` | BM25 | BM25词频饱和参数（默认1.5） |
| `b` | BM25 | BM25文档长度归一化参数（默认0.75） |
### BM25参数调优
```python
from fastembed import SparseTextEmbedding
model = SparseTextEmbedding(
model_name="Qdrant/bm25",
k=1.5, # 词频饱和参数
b=0.75 # 文档长度归一化参数
)
```
## 与Qdrant集成
FastEmbed的稀疏嵌入与Qdrant向量数据库深度集成：
1. **稀疏向量存储**：Qdrant支持原生稀疏向量索引
2. **IDF修饰符**：使用`modifier="idf"`在Qdrant端计算IDF权重
3. **混合检索**：结合密集嵌入和稀疏嵌入进行混合搜索
**Qdrant使用示例**：
```python
from qdrant_client import QdrantClient
from fastembed import SparseTextEmbedding
# 生成稀疏嵌入
model = SparseTextEmbedding(model_name="prithivida/Splade_PP_en_v1")
embedding = next(model.embed(["example document"]))
# 上传到Qdrant
client = QdrantClient("localhost", port=6333)
client.upload_points(
collection_name="sparse_collection",
points=[{
"id": 1,
"vector": {
"indices": embedding.indices,
"values": embedding.values
}
}]
)
```
## 性能考量
### 内存占用
稀疏嵌入相比密集嵌入具有显著的内存优势：
| 模型类型 | 典型维度 | 非零比例 | 内存效率 |
|----------|----------|----------|----------|
| 密集嵌入 | 768-1024 | ~100% | 较低 |
| SPLADE++ | 30522 | ~1-5% | 高 |
| BM25 | 词汇表大小 | ~0.1% | 极高 |
### 计算效率
- **稀疏计算**：跳过零值计算，减少FLOPs
- **批量处理**：支持大批量并行推理
- **ONNX优化**：利用ONNX Runtime的图优化和算子融合
## 许可证与来源
FastEmbed稀疏嵌入模块中的模型使用多种许可证：
| 模型 | 许可证 |
|------|--------|
| SPLADE++ | apache-2.0 |
| BM42 | apache-2.0 |
| BM25 | apache-2.0 |
| MiniCOIL | apache-2.0 |
所有模型均可从HuggingFace Hub公开获取。
## 相关资源
- [FastEmbed官方文档](https://qdrant.github.io/fastembed/)
- [Qdrant向量数据库](https://qdrant.tech/)
- [SPLADE论文](https://arxiv.org/abs/2109.08133)
- [BM25算法详解](https://en.wikipedia.org/wiki/Okapi_BM25)
---
## 后期交互模型 (ColBERT)
### 相关页面
相关主题：[快速开始](#page-quickstart), [多模态后期交互 (ColPali)](#page-multimodal)
相关源码文件
以下源码文件用于生成本页说明：
- [fastembed/late_interaction/colbert.py](https://github.com/qdrant/fastembed/blob/main/fastembed/late_interaction/colbert.py)
- [fastembed/late_interaction/jina_colbert.py](https://github.com/qdrant/fastembed/blob/main/fastembed/late_interaction/jina_colbert.py)
- [fastembed/late_interaction/late_interaction_text_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/late_interaction/late_interaction_text_embedding.py)
- [fastembed/late_interaction/late_interaction_embedding_base.py](https://github.com/qdrant/fastembed/blob/main/fastembed/late_interaction/late_interaction_embedding_base.py)
- [fastembed/late_interaction/token_embeddings.py](https://github.com/qdrant/fastembed/blob/main/fastembed/late_interaction/token_embeddings.py)
# 后期交互模型 (ColBERT)
## 概述
ColBERT（Contextualized Late Interactions over BERT）是 FastEmbed 框架中实现的一种**后期交互（Late Interaction）**文本嵌入技术。与传统的密集嵌入模型不同，ColBERT 采用独特的**标记级嵌入（Token-level Embeddings）**策略，将输入文本的每个 token 都编码为独立的向量，然后在检索阶段通过高效的晚期交互计算相关性评分。
后期交互模型的核心优势在于能够在保持检索效率的同时，捕获查询与文档之间细粒度的语义匹配关系。这种方法特别适用于需要高质量排序的搜索引擎和推荐系统场景。
## 核心概念
### 后期交互原理
传统密集嵌入模型在编码阶段就将查询和文档压缩为单一的固定维度向量，导致细粒度匹配信息的丢失。而 ColBERT 采用**延迟交互**策略：
```mermaid
graph TD
A[查询 Query] -->|独立编码| B[查询 token 向量集合]
C[文档 Document] -->|独立编码| D[文档 token 向量集合]
B --> E[Max-Sum 交互]
D --> E
E --> F[相关性评分]
style B fill:#e1f5fe
style D fill:#e8f5e8
style E fill:#fff3e0
```
### 标记嵌入机制
在 FastEmbed 的实现中，每个 token 都被编码为独立的向量，存储在 `TokenEmbeddings` 数据结构中。这种设计允许在检索时对查询和文档的每个 token 进行独立的相似度计算。
## 架构设计
### 类继承结构
```mermaid
graph TD
A[TextEmbeddingBase] --> B[LateInteractionEmbeddingBase]
B --> C[LateInteractionTextEmbedding]
C --> D[Colbert]
D --> E[JinaColbert]
B --> F[ColbertEmbeddingWorker]
F --> G[JinaColbertEmbeddingWorker]
style A fill:#f3e5f5
style B fill:#e8eaf6
style C fill:#e3f2fd
style D fill:#e8f5e8
style E fill:#fff3e0
```
### 核心类说明
| 类名 | 文件位置 | 职责 |
|------|----------|------|
| `LateInteractionEmbeddingBase` | `late_interaction_embedding_base.py` | 定义后期交互嵌入的抽象基类和通用接口 |
| `LateInteractionTextEmbedding` | `late_interaction_text_embedding.py` | 实现后期交互文本嵌入的公共逻辑 |
| `Colbert` | `colbert.py` | 基础 ColBERT 模型实现 |
| `JinaColbert` | `jina_colbert.py` | Jina AI 提供的 ColBERT v2 模型 |
| `TokenEmbeddings` | `token_embeddings.py` | 管理 token 级别的嵌入向量 |
资料来源：[late_interaction_embedding_base.py]()，[colbert.py]()，[jina_colbert.py]()
## API 使用
### 基础初始化
```python
from fastembed import LateInteractionTextEmbedding
# 使用 Jina ColBERT v2 模型
model = LateInteractionTextEmbedding(model_name="jinaai/jina-colbert-v2")
```
### 生成标记级嵌入
```python
# 对查询生成标记嵌入
query_embeddings = list(model.query_embed("什么是向量检索"))
# 对文档生成标记嵌入
document_embeddings = list(model.embed(["这是一篇关于向量数据库的文章"]))
```
### 嵌入输出格式
每个 `query_embed` 和 `embed` 调用返回的都是 `TokenEmbeddings` 对象，包含每个 token 的向量表示：
```python
# TokenEmbeddings 结构包含:
# - vectors: 每个 token 的嵌入向量 (num_tokens, dim)
# - attention_mask: 注意力掩码
# - token_ids: token ID 列表
```
资料来源：[late_interaction_text_embedding.py]()
## 支持的模型
### 模型列表
| 模型名称 | 维度 | 上下文长度 | 语言 | 许可证 | 模型文件 |
|----------|------|------------|------|--------|----------|
| `jinaai/jina-colbert-v2` | 128 | 8192 | 多语言 | cc-by-nc-4.0 | onnx/model.onnx |
资料来源：[jina_colbert.py:6-13]()
### Jina ColBERT v2 特性
Jina ColBERT v2 是当前 FastEmbed 支持的唯一后期交互模型，具有以下特性：
- **多语言支持**：能够处理多种语言的文本输入
- **长上下文**：支持最高 8192 个 token 的上下文长度
- **标记标记机制**：使用特殊的查询标记符（`[CLS]` 替代）和文档标记符来区分查询和文档
- **高效交互**：通过 Max-Sum 机制实现高效的晚期交互计算
## 配置参数
### 初始化参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model_name` | `str` | `"jinaai/jina-colbert-v2"` | 模型名称 |
| `cache_dir` | `str \| None` | `None` | 模型缓存目录 |
| `threads` | `int \| None` | `None` | 线程数限制 |
| `providers` | `Sequence[OnnxProvider] \| None` | `None` | ONNX 推理提供者 |
| `cuda` | `bool \| Device` | `Device.AUTO` | CUDA 设备配置 |
| `device_ids` | `list[int] \| None` | `None` | 指定设备 ID |
| `lazy_load` | `bool` | `False` | 是否延迟加载模型 |
## 工作流程
### 检索流程
```mermaid
graph TD
A[输入查询] --> B[Query 编码]
A1[输入文档] --> C[Document 编码]
B --> D[生成 Query Token 向量]
C --> E[生成 Doc Token 向量]
D --> F[Max-Sum 交互计算]
E --> F
F --> G[计算相关性评分]
G --> H[排序输出结果]
style F fill:#fff3e0
style G fill:#ffecb3
```
### Max-Sum 交互机制
ColBERT 采用 Max-Sum 策略计算查询与文档之间的相似度：
1. 对于查询中的每个 token，找出与文档所有 token 向量中相似度最高的一个
2. 将所有 token 的最大相似度值求和
3. 得到最终的相关性评分
这种方法能够在保持亚线性检索效率的同时，捕获查询和文档之间细粒度的语义对应关系。
资料来源：[colbert.py]()
## 与密集嵌入的对比
| 特性 | 密集嵌入 | ColBERT 后期交互 |
|------|----------|------------------|
| 嵌入维度 | 768-1024 | 128 |
| 查询编码 | 单次前向传播 | 单次前向传播 |
| 文档编码 | 单次前向传播 | 单次前向传播 |
| 交互计算 | 无（早期压缩） | Max-Sum 晚期交互 |
| 检索精度 | 较高 | 最高 |
| 存储需求 | 较高 | 中等（文档需存储 token 向量） |
| 适用场景 | 近似最近邻检索 | 高精度排序重排 |
## 应用场景
### 最佳使用场景
1. **搜索结果重排**：使用 ColBERT 对候选文档进行精确排序
2. **问答系统**：精确匹配查询与答案候选的相关性
3. **推荐系统**：高质量的 item 排序
4. **文本相似度**：细粒度的段落或句子级匹配
### 集成示例
```python
from fastembed import LateInteractionTextEmbedding
from qdrant_client import QdrantClient
# 初始化模型
colbert = LateInteractionTextEmbedding(model_name="jinaai/jina-colbert-v2")
# 生成文档嵌入
documents = ["文档内容1", "文档内容2"]
doc_embeddings = list(colbert.embed(documents))
# 生成查询嵌入
query = "查询内容"
query_embeddings = list(colbert.query_embed(query))
```
## 技术细节
### 标记处理
ColBERT 模型使用特殊的标记处理机制：
- **查询标记符**：在查询开头添加特殊 `[CLS]` 标记符
- **文档标记符**：在文档开头添加文档类型标记符
- **最小长度限制**：查询最小长度为 31 个 token（实际为 32，代码中会额外添加一个特殊 token）
资料来源：[jina_colbert.py:18-20]()
### ONNX 推理支持
所有后期交互模型都通过 ONNX Runtime 进行推理，确保跨平台兼容性和高效的推理性能。模型加载支持多种 ONNX 提供者，包括 CPU 和 CUDA 后端。
## 注意事项
1. **存储成本**：由于 ColBERT 为每个 token 存储独立的向量，文档的存储开销高于传统的密集嵌入
2. **查询长度**：较长的查询会生成更多的 token 向量，可能影响交互计算效率
3. **模型大小**：Jina ColBERT v2 模型大小约为 2.24 GB，需要确保有足够的磁盘空间用于缓存
4. **许可证约束**：Jina ColBERT v2 采用 cc-by-nc-4.0 许可证，仅限非商业用途
---
## 图像嵌入
### 相关页面
相关主题：[快速开始](#page-quickstart), [多模态后期交互 (ColPali)](#page-multimodal)
相关源码文件
以下源码文件用于生成本页说明：
- [fastembed/image/onnx_image_model.py](https://github.com/qdrant/fastembed/blob/main/fastembed/image/onnx_image_model.py)
- [fastembed/image/image_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/image/image_embedding.py)
- [fastembed/image/image_embedding_base.py](https://github.com/qdrant/fastembed/blob/main/fastembed/image/image_embedding_base.py)
- [fastembed/image/onnx_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/image/onnx_embedding.py)
- [fastembed/image/transform/operators.py](https://github.com/qdrant/fastembed/blob/main/fastembed/image/transform/operators.py)
# 图像嵌入
## 概述
FastEmbed 的图像嵌入模块提供将图像转换为高维向量的功能，支持多模态检索、图像相似度搜索和跨模态匹配等应用场景。该模块基于 ONNX Runtime 实现高性能推理，支持从本地文件系统或 Hugging Face Hub 自动下载预训练模型。
图像嵌入系统支持以下几种模式：
- **纯图像嵌入**：使用 ResNet 等模型提取图像特征
- **CLIP 多模态嵌入**：支持图像与文本的跨模态编码
- **Jina-CLIP 多模态嵌入**：支持图像和文本的统一嵌入表示
资料来源：[fastembed/image/image_embedding_base.py]()
## 支持的模型
### 模型列表
| 模型标识 | 维度 | 许可证 | 模型大小 | 描述 |
|---------|------|--------|----------|------|
| `Qdrant/resnet50-onnx` | 2048 | apache-2.0 | 0.24 GB | ResNet50 图像嵌入，2019年 |
| `Qdrant/Unicom-ViT-B-16` | 768 | apache-2.0 | 0.82 GB | ViT-B-16 图像嵌入（比 Unicom-ViT-B-32 更精细），多模态，2023年 |
| `Qdrant/Unicom-ViT-B-32` | 512 | apache-2.0 | 0.48 GB | ViT-B-32 图像嵌入，多模态，2023年 |
| `jinaai/jina-clip-v1` | 768 | apache-2.0 | 0.34 GB | Jina CLIP v1 图像嵌入，多模态（文本&图像），2024年 |
资料来源：[fastembed/image/onnx_embedding.py]()
### 模型选择指南
- **高性能图像特征提取**：使用 `Qdrant/resnet50-onnx`，提供 2048 维特征向量
- **图像-文本跨模态检索**：使用 `jinaai/jina-clip-v1` 或 `Qdrant/Unicom-ViT-B-16`
- **资源受限场景**：使用 `Qdrant/Unicom-ViT-B-32`，模型体积较小
## 架构设计
### 类层次结构
```
ImageEmbeddingBase (抽象基类)
│
├── OnnxImageEmbedding (ONNX 图像嵌入实现)
│ │
│ └── 继承自 OnnxImageModel[NumpyArray]
│
└── CLIPOnnxEmbedding (CLIP 图像嵌入)
│
└── 继承自 OnnxTextEmbedding
```
资料来源：[fastembed/image/image_embedding_base.py]()
### 核心组件
| 组件 | 文件 | 职责 |
|------|------|------|
| `ImageEmbeddingBase` | image_embedding_base.py | 定义图像嵌入抽象接口 |
| `OnnxImageEmbedding` | onnx_embedding.py | ONNX Runtime 图像嵌入实现 |
| `OnnxImageModel` | onnx_image_model.py | ONNX 图像模型封装 |
| `ImageTransformer` | transform/operators.py | 图像预处理转换 |
资料来源：[fastembed/image/image_embedding.py]()
### 数据流架构
```mermaid
graph TD
A[输入图像] --> B[ImageTransformer 预处理]
B --> C[图像张量]
C --> D[OnnxImageModel 推理]
D --> E[ONNX Runtime]
E --> F[原始嵌入向量]
F --> G[后处理]
G --> H[归一化向量]
I[CLIP/多模态模式] --> D
J[文本查询] --> K[跨模态编码]
K --> L[相似度计算]
H --> L
```
## 图像预处理
### 转换管道
图像在输入模型前需要经过标准化转换处理：
```python
# 典型预处理流程
ImageTransformer = Compose([
ResizeImage(size=224), # 调整尺寸
ToTensor(), # 转为张量
Normalize(mean, std), # 标准化
])
```
资料来源：[fastembed/image/transform/operators.py]()
### 支持的预处理操作
| 操作 | 说明 | 参数 |
|------|------|------|
| `ResizeImage` | 调整图像尺寸 | `size`: 目标尺寸 |
| `ToTensor` | 将 PIL Image 转为张量 | - |
| `Normalize` | 标准化处理 | `mean`, `std` |
| `CenterCrop` | 中心裁剪 | `size` |
## 使用方法
### 基础用法
```python
from fastembed import ImageEmbedding
# 初始化模型
model = ImageEmbedding(model_name="Qdrant/resnet50-onnx")
# 单张图像嵌入
embedding = list(model.embed(["/path/to/image.jpg"]))
# 批量嵌入
images = [
"/path/to/image1.jpg",
"/path/to/image2.jpg",
"https://example.com/image.jpg" # 支持 URL
]
embeddings = list(model.embed(images))
```
### 多模态 CLIP 图像嵌入
```python
from fastembed import ImageEmbedding
# 使用 CLIP 模型获取图像嵌入
model = ImageEmbedding(model_name="Qdrant/clip-ViT-B-32")
# 嵌入图像
image_embedding = list(model.embed(["/path/to/image.jpg"]))
```
资料来源：[fastembed/image/image_embedding.py]()
### 与文本嵌入配合使用
```python
from fastembed import ImageEmbedding, TextEmbedding
# 初始化图像和文本嵌入模型
image_model = ImageEmbedding(model_name="jinaai/jina-clip-v1")
text_model = TextEmbedding(model_name="jinaai/jina-clip-v1")
# 获取图像和文本的嵌入向量
image_emb = list(image_model.embed(["/path/to/image.jpg"]))
text_emb = list(text_model.embed(["a cat sitting on a sofa"]))
# 计算相似度
from numpy import dot
similarity = dot(image_emb[0], text_emb[0])
```
## ONNX 运行时配置
### 可用 providers
图像嵌入模型支持多种 ONNX 推理 providers：
| Provider | 说明 | 优先级 |
|----------|------|--------|
| `CUDAExecutionProvider` | NVIDIA GPU 加速 | 最高 |
| `CPUExecutionProvider` | CPU 推理 | 回退 |
资料来源：[fastembed/image/onnx_image_model.py]()
### 设备配置
```python
from fastembed import ImageEmbedding
from fastembed.common import Device
# 自动选择最佳设备
model = ImageEmbedding(
model_name="Qdrant/Unicom-ViT-B-16",
cuda=True # 或 Device.AUTO
)
# 指定设备 ID
model = ImageEmbedding(
model_name="Qdrant/Unicom-ViT-B-16",
device_ids=[0]
)
```
## 模型下载与缓存
### 缓存目录
模型默认缓存到 `~/.cache/fastembed`，可通过环境变量修改：
```bash
export FASTEMBED_CACHE_PATH="/custom/cache/directory"
```
### 下载源
模型可以从以下来源下载：
- **Hugging Face Hub**：默认源，通过 `hf` 参数指定
- **URL 直链**：通过 `url` 参数指定自定义下载 URL
资料来源：[fastembed/image/onnx_embedding.py]()
## API 参考
### ImageEmbedding 类
```python
class ImageEmbedding:
@classmethod
def _list_supported_models(cls) -> list[DenseModelDescription]:
"""列出所有支持的图像嵌入模型"""
def __init__(
self,
model_name: str = "Qdrant/resnet50-onnx",
cache_dir: str | None = None,
threads: int | None = None,
providers: Sequence[OnnxProvider] | None = None,
cuda: bool | Device = Device.AUTO,
device_ids: list[int] | None = None,
lazy_load: bool = False,
device_id: int | None = None,
specific_model_path: str | None = None,
**kwargs: Any,
):
"""初始化图像嵌入模型"""
```
### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model_name` | str | `"Qdrant/resnet50-onnx"` | 模型名称 |
| `cache_dir` | str \| None | None | 缓存目录路径 |
| `threads` | int \| None | None | 线程数 |
| `providers` | Sequence[OnnxProvider] \| None | None | ONNX providers |
| `cuda` | bool \| Device | Device.AUTO | CUDA 加速启用 |
| `device_ids` | list[int] \| None | None | GPU 设备 ID 列表 |
| `lazy_load` | bool | False | 延迟加载模式 |
资料来源：[fastembed/image/onnx_embedding.py]()
### embed 方法
```python
def embed(
self,
images: Iterable[str | Path],
batch_size: int = 32,
parallel: int | None = None,
prefetch: int | None = None,
) -> Iterable[NumpyArray]:
"""
生成图像嵌入向量
Args:
images: 图像路径或 URL 迭代器
batch_size: 批处理大小
parallel: 并行处理数
prefetch: 预取数量
Yields:
NumpyArray: 归一化的嵌入向量
"""
```
## 性能考量
### 批处理建议
| 场景 | 推荐 batch_size | 说明 |
|------|-----------------|------|
| GPU 推理 | 64-256 | 充分利用 GPU 并行能力 |
| CPU 推理 | 8-32 | 避免内存溢出 |
| 大图像 | 较小值 | 降低显存占用 |
### 延迟加载模式
```python
# 延迟加载，不立即加载模型权重
model = ImageEmbedding(
model_name="Qdrant/resnet50-onnx",
lazy_load=True
)
# 模型权重在首次调用 embed 时加载
```
资料来源：[fastembed/image/image_embedding_base.py]()
## 最佳实践
### 1. 图像格式支持
推荐使用以下图像格式：
- JPEG/JPG
- PNG
- BMP
- WEBP
### 2. 内存管理
```python
# 处理大量图像时使用生成器
def image_generator(image_paths):
for path in image_paths:
yield path
embeddings = list(model.embed(image_generator(large_image_list)))
```
### 3. 多进程使用
```python
from fastembed import ImageEmbedding
# 每个进程独立初始化模型
def process_batch(image_batch):
model = ImageEmbedding(model_name="Qdrant/resnet50-onnx")
return list(model.embed(image_batch))
```
## 相关文档
- [文本嵌入](./text_embedding.md) - 文本向量嵌入功能
- [稀疏嵌入](./sparse_embedding.md) - SPLADE 稀疏嵌入
- [重排序模型](./reranking.md) - 交叉编码器重排序
- [ColPali 多模态](./colpali.md) - 后期交互多模态模型
---
## 多模态后期交互 (ColPali)
### 相关页面
相关主题：[图像嵌入](#page-image-embedding), [后期交互模型 (ColBERT)](#page-late-interaction)
相关源码文件
以下源码文件用于生成本页说明：
- [fastembed/late_interaction_multimodal/colpali.py](https://github.com/qdrant/fastembed/blob/main/fastembed/late_interaction_multimodal/colpali.py)
- [fastembed/late_interaction_multimodal/colmodernvbert.py](https://github.com/qdrant/fastembed/blob/main/fastembed/late_interaction_multimodal/colmodernvbert.py)
- [fastembed/late_interaction_multimodal/late_interaction_multimodal_embedding.py](https://github.com/qdrant/fastembed/blob/main/fastembed/late_interaction_multimodal/late_interaction_multimodal_embedding.py)
- [fastembed/late_interaction_multimodal/onnx_multimodal_model.py](https://github.com/qdrant/fastembed/blob/main/fastembed/late_interaction_multimodal/onnx_multimodal_model.py)
# 多模态后期交互 (ColPali)
## 概述
多模态后期交互（Late Interaction Multimodal）是一种先进的检索架构，它在多模态场景下实现了文档与查询之间的深度交互式匹配。这种方法与传统的单向量表示不同，它允许文档和查询各自生成多个向量表示，然后在检索阶段进行细粒度的交互计算。
在 FastEmbed 库中，多模态后期交互的实现主要通过 `ColPali` 和 `ColModernVBERT` 两个核心类完成。这些模型继承自 `LateInteractionMultimodalEmbeddingBase` 基类，并基于 ONNX 多模态模型架构运行。后期交互方法的核心优势在于能够在保持高效检索的同时，捕捉文档中每个 token 与查询之间的语义关联。
## 架构设计
### 类继承层次
多模态后期交互模块采用分层架构设计，各组件之间具有清晰的职责划分：
```mermaid
graph TD
A[LateInteractionMultimodalEmbeddingBase] --> B[ColPali]
A --> C[ColModernVBERT]
B --> D[OnnxMultimodalModel]
C --> D
A --> E[OnnxTextModel]
D --> F[OnnxModelBase]
E --> F
G[ImageEmbeddingBase] --> H[OnnxImageModel]
H --> F
```
`LateInteractionMultimodalEmbeddingBase` 作为所有多模态后期交互嵌入的抽象基类，定义了模型的核心接口和行为规范。`ColPali` 和 `ColModernVBERT` 分别实现了针对不同多模态架构的具体逻辑，它们共享相同的基础设施但在模型处理细节上有所差异。
### ColPali 模型实现
`ColPali` 类是 ColPali 算法的核心实现，它继承自 `LateInteractionMultimodalEmbeddingBase` 和 `OnnxMultimodalModel`。该模型使用视觉语言架构来处理文档图像和查询文本，通过后期交互机制实现高效的语义匹配。
在 `colpali.py` 中，模型定义了 `QUERY_AUGMENTATION_TOKEN` 和 `VISUAL_PROMPT_PREFIX` 两个关键的提示前缀，用于指导视觉语言模型的查询处理流程。这些前缀确保模型能够正确理解多模态输入的语义结构。
### ColModernVBERT 模型实现
`ColModernVBERT` 是另一种晚交互多模态嵌入的实现，它基于 ModernVBERT/colmodernvbert 架构。该模型使用双向注意力机制，在检索任务中表现出更好的性能。
```python
class ColModernVBERT(LateInteractionMultimodalEmbeddingBase, OnnxMultimodalModel[NumpyArray]):
"""
The ModernVBERT/colmodernvbert model implementation. This model uses
bidirectional attention, which proves to work better for retrieval.
See: https://huggingface.co/ModernVBERT/colmodernvbert
"""
```
ColModernVBERT 的设计理念与 ColPali 类似，但采用了不同的预训练策略和注意力机制。双向注意力使得模型能够更全面地理解输入序列中的依赖关系，从而在某些检索场景中获得更优的效果。
## 核心功能与接口
### 模型初始化
多模态后期交互模型的初始化遵循统一的接口设计，支持灵活的参数配置：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| model_name | str | 必需 | 模型的标识名称 |
| cache_dir | str \| None | None | 模型缓存目录路径 |
| threads | int \| None | None | ONNX Runtime 线程数 |
| providers | Sequence[OnnxProvider] \| None | None | ONNX 推理提供者 |
| cuda | bool \| Device | Device.AUTO | CUDA 加速启用状态 |
| device_ids | list[int] \| None | None | 目标设备 ID 列表 |
| lazy_load | bool | False | 是否延迟加载模型 |
| device_id | int \| None | None | 指定设备 ID |
| specific_model_path | str \| None | None | 特定模型文件路径 |
初始化参数中，`cuda` 参数支持自动设备检测功能，可以根据系统环境自动选择 GPU 或 CPU 进行推理。`lazy_load` 选项允许在需要时才加载模型权重，这对于资源受限的环境非常有价值。
### 嵌入生成流程
多模态后期交互模型的嵌入生成流程涉及图像和文本两种模态的处理：
```mermaid
graph LR
A[图像输入] --> B[视觉编码器]
A1[文本查询] --> C[文本编码器]
B --> D[多向量表示]
C --> E[多向量表示]
D --> F[后期交互计算]
E --> F
F --> G[相似度分数]
```
模型的核心输出是多向量表示，而非单一的高维向量。每个输入（无论是图像还是文本）都会被编码为一组向量序列，这些向量序列在后续的检索阶段进行交互计算。
## 支持的模型列表
FastEmbed 库的多模态后期交互模块支持多种预训练模型，这些模型覆盖了不同的应用场景和性能需求：
| 模型标识 | 维度 | 模态支持 | 许可证 | 适用场景 |
|----------|------|----------|--------|----------|
| vidore/colpali | 128 | 文本+图像 | apache-2.0 | 通用多模态检索 |
| vidore/colqwen2 | 128 | 文本+图像 | apache-2.0 | 高精度文档检索 |
| ModernVBERT/colmodernvbert | 768 | 文本+图像 | apache-2.0 | 双向注意力检索 |
模型选择应根据具体的应用需求进行权衡。ColPali 系列模型在文档图像检索任务中表现优异，而 ModernVBERT 在需要双向语义理解的任务中更具优势。
## 与其他嵌入类型的对比
FastEmbed 库提供了多种嵌入类型，理解它们之间的差异对于正确选择模型至关重要：
| 嵌入类型 | 向量数量 | 交互方式 | 典型应用 |
|----------|----------|----------|----------|
| 密集向量嵌入 | 单一向量 | 早期交互 | 语义搜索、聚类 |
| 池化归一化嵌入 | 单一归一化向量 | 早期交互 | 高效相似度搜索 |
| 稀疏嵌入 | 多个非零维度 | 词汇匹配 | 关键词检索 |
| 后期交互嵌入 | 多向量序列 | 后期交互 | 文档检索、多模态检索 |
后期交互嵌入的核心优势在于其能够捕获细粒度的语义关联。传统密集向量嵌入将整个文档压缩为单一向量，可能丢失重要的局部语义信息；而后期交互方法保留了整个序列的表示，使得查询中的每个 term 都能与文档中的对应部分进行直接比较。
## 后处理扩展：MUVERA
MUVERA（Multi-Vector Reduction Aggregation）是一种与多模态后期交互配合使用的后处理技术。它的主要作用是将多向量表示压缩为单一固定维度向量，以便在不支持多向量索引的向量数据库中使用。
```python
class Muvera:
def __init__(
self,
dim: int,
k_sim: int,
dim_proj: int,
r_reps: int,
random_seed: int,
):
"""
MUVERA 算法实现
参数:
dim: 原始嵌入维度
k_sim: 分区参数，控制分区数量为 2^k_sim
dim_proj: 投影维度
r_reps: 重复次数
random_seed: 随机种子，确保可复现性
"""
```
MUVERA 算法的输出维度计算公式为：`r_reps * num_partitions * dim_proj`，其中 `num_partitions = 2**k_sim`。这种设计允许在保持语义信息的同时显著降低向量维度。
## 使用示例
### 基本多模态检索
```python
from fastembed import LateInteractionMultimodalEmbedding
# 初始化多模态后期交互模型
model = LateInteractionMultimodalEmbedding(
model_name="vidore/colpali",
lazy_load=False
)
# 对图像和文本进行编码
image_embeddings = list(model.embed_images(image_paths))
query_embedding = list(model.embed(["示例查询文本"]))
# 图像检索
results = model.retrieve(query_embedding, image_embeddings, top_k=5)
```
### 与 MUVERA 配合使用
```python
from fastembed import LateInteractionMultimodalEmbedding
from fastembed.postprocess.muvera import Muvera
# 加载后期交互模型
model = LateInteractionMultimodalEmbedding(model_name="vidore/colpali")
# 创建 MUVERA 后处理器
muvera = Muvera.from_multivector_model(
model=model,
k_sim=6,
dim_proj=32,
r_reps=4
)
# 生成多向量嵌入
embeddings = list(model.embed(["示例文档"]))
# 压缩为固定维度向量
compressed = muvera.process_document(embeddings[0])
```
## 性能优化建议
### 推理优化
在使用多模态后期交互模型时，以下策略可以帮助提升推理性能：
1. **批量处理**：将多个图像或文本请求批量处理，可以充分利用硬件并行能力，显著提升吞吐量
2. **设备选择**：GPU 环境下启用 CUDA 加速可获得数倍性能提升；对于小批量场景，CPU 推理可能更为经济
3. **延迟加载**：在不需要立即使用模型的场景下启用 `lazy_load=True`，可以加快应用启动时间
### 内存管理
多模态后期交互模型由于输出多向量表示，相比单向量模型需要更大的内存空间。建议在生产环境中监控内存使用情况，并根据可用资源调整批处理大小。
## 扩展机制
### 自定义模型支持
FastEmbed 的多模态后期交互模块支持通过配置扩展新的模型。开发者可以参考现有实现，继承 `LateInteractionMultimodalEmbeddingBase` 基类并实现必要的抽象方法：
```python
class CustomLateInteractionModel(LateInteractionMultimodalEmbeddingBase, OnnxMultimodalModel[NumpyArray]):
@classmethod
def _list_supported_models(cls) -> list[BaseModelDescription]:
# 返回自定义模型描述列表
pass
@classmethod
def _get_worker_class(cls) -> Type[OnnxTextEmbeddingWorker]:
# 返回对应的 Worker 类
pass
```
### 后处理器集成
MUVERA 等后处理器提供了与多模态后期交互模型的标准集成接口。通过 `from_multivector_model` 工厂方法，可以从已有的多模态模型自动初始化兼容的后处理器。
## 技术规格
多模态后期交互模块的技术规格如下：
- **依赖框架**：ONNX Runtime（用于模型推理）
- **输入格式**：图像（支持常见格式）、文本（UTF-8 编码）
- **输出格式**：NumpyArray 类型的多维数组
- **线程安全**：模型实例可在多线程环境中共享
- **模型格式**：ONNX 格式（跨平台部署友好）
## 相关资源
- 官方文档：[FastEmbed 文档](https://qdrant.github.io/fastembed/)
- ColPali 论文：[ColPali: Efficient Document Retrieval with Vision Language Models](https://arxiv.org/abs/2408.14521)
- ModernVBERT：[HuggingFace 模型页面](https://huggingface.co/ModernVBERT/colmodernvbert)
---
## 重排序模型
### 相关页面
相关主题：[快速开始](#page-quickstart), [密集文本嵌入](#page-dense-embedding)
相关源码文件
以下源码文件用于生成本页说明：
- [fastembed/rerank/cross_encoder/text_cross_encoder.py](https://github.com/qdrant/fastembed/blob/main/fastembed/rerank/cross_encoder/text_cross_encoder.py)
- [fastembed/rerank/cross_encoder/text_cross_encoder_base.py](https://github.com/qdrant/fastembed/blob/main/fastembed/rerank/cross_encoder/text_cross_encoder_base.py)
- [fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py](https://github.com/qdrant/fastembed/blob/main/fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py)
- [fastembed/rerank/cross_encoder/onnx_text_model.py](https://github.com/qdrant/fastembed/blob/main/fastembed/rerank/cross_encoder/onnx_text_model.py)
# 重排序模型
## 概述
重排序模型（Cross-Encoder Re-ranking）是信息检索系统中提升搜索结果质量的关键组件。与基于向量相似度的双编码器（Bi-Encoder）检索方式不同，重排序模型通过同时编码查询和文档，计算查询与文档之间的交叉注意力分数，从而实现更精确的相关性评估。
FastEmbed 库中的重排序模型基于 Cross-Encoder 架构实现，位于 `fastembed/rerank` 模块下。该模块采用 ONNX 运行时进行模型推理，支持多种预训练的重排序模型，包括 Jina AI 的 Jina Reranker 系列、BAAI 的 BGE Reranker 以及 MS MARCO MiniLM 等模型。
## 架构设计
### 类层次结构
FastEmbed 的重排序模块采用分层架构设计，从基类到具体实现类逐层抽象：
```mermaid
graph TD
A[TextCrossEncoderBase] --> B[OnnxTextCrossEncoder]
C[OnnxCrossEncoderModel] --> B
B --> D[实例化重排序模型]
A1[TextCrossEncoderBase] -.->|定义接口| A
C1[OnnxCrossEncoderModel] -.->|ONNX推理引擎| C
```
**核心组件说明：**
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| `TextCrossEncoderBase` | `fastembed/rerank/cross_encoder/text_cross_encoder_base.py` | 定义重排序模型的基础接口和公共方法 |
| `OnnxCrossEncoderModel` | `fastembed/rerank/cross_encoder/onnx_text_model.py` | 实现 ONNX 运行时加载和推理逻辑 |
| `OnnxTextCrossEncoder` | `fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py` | 整合基类和 ONNX 模型，提供具体实现 |
资料来源：[fastembed/rerank/cross_encoder/text_cross_encoder.py:1-50]()
### 数据流
重排序模型的核心工作流程如下：
```mermaid
sequenceDiagram
participant User as 用户
participant Model as OnnxTextCrossEncoder
participant ONNX as ONNX Runtime
participant Result as 相关性分数
User->>Model: encode(query, documents)
Model->>Model: 预处理输入文本
Model->>ONNX: 加载/推理 ONNX 模型
ONNX-->>Model: 返回 logits 输出
Model->>Model: 后处理计算相关性分数
Model-->>User: 返回排序后的文档列表
```
## 支持的模型列表
FastEmbed 重排序模块预置了多个经过优化的重排序模型，涵盖英语和多语言场景。
### 模型配置表
| 模型标识 | 描述 | 许可证 | 模型大小 | 上下文长度 | HuggingFace 源 |
|----------|------|--------|----------|------------|----------------|
| `jinaai/jina-reranker-v1-tiny-en` | 轻量级高速重排序模型，8K 上下文 | apache-2.0 | 0.13 GB | 8K | `jinaai/jina-reranker-v1-tiny-en` |
| `jinaai/jina-reranker-v1-turbo-en` | 高速重排序模型，8K 上下文 | apache-2.0 | 0.15 GB | 8K | `jinaai/jina-reranker-v1-turbo-en` |
| `jinaai/jina-reranker-v2-base-multilingual` | 多语言重排序模型，滑动窗口，1K 上下文 | cc-by-nc-4.0 | 1.11 GB | 1K | `jinaai/jina-reranker-v2-base-multilingual` |
| `BAAI/bge-reranker-base` | BGE 基础重排序模型 | mit | 1.04 GB | - | `BAAI/bge-reranker-base` |
| `Xenova/ms-marco-MiniLM-L-12-v2` | MS MARCO 蒸馏重排序模型 | apache-2.0 | 0.12 GB | - | `Xenova/ms-marco-MiniLM-L-12-v2` |
资料来源：[fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py:1-60]()
### 模型选择指南
**英语单语场景：**
- 追求极致速度：`jinaai/jina-reranker-v1-tiny-en`
- 平衡速度与精度：`jinaai/jina-reranker-v1-turbo-en`
- 高精度需求：标准 `jina-reranker-v1` 系列
**多语言场景：**
- 跨语言重排序：使用 `jinaai/jina-reranker-v2-base-multilingual`
- 支持约 100 种语言的查询-文档匹配
## API 参考
### OnnxTextCrossEncoder 类
`OnnxTextCrossEncoder` 是重排序模块的主要实现类，继承自 `TextCrossEncoderBase` 和 `OnnxCrossEncoderModel`。
#### 构造函数参数
```python
def __init__(
self,
model_name: str,
cache_dir: str | None = None,
threads: int | None = None,
providers: Sequence[OnnxProvider] | None = None,
cuda: bool | Device = Device.AUTO,
device_ids: list[int] | None = None,
lazy_load: bool = False,
device_id: int | None = None,
specific_model_path: str | None = None,
**kwargs: Any,
)
```
**参数详细说明：**
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `model_name` | `str` | 必需 | 重排序模型名称，参见支持模型列表 |
| `cache_dir` | `str \| None` | `None` | 模型缓存目录，可通过 `FASTEMBED_CACHE_PATH` 环境变量设置 |
| `threads` | `int \| None` | `None` | CPU 推理线程数，`None` 表示使用所有可用线程 |
| `providers` | `Sequence[OnnxProvider] \| None` | `None` | ONNX 执行 providers，如 `['CPUExecutionProvider']` |
| `cuda` | `bool \| Device` | `Device.AUTO` | CUDA 设备配置，`True` 启用，`False` 禁用，`AUTO` 自动检测 |
| `device_ids` | `list[int] \| None` | `None` | 多 GPU 配置下的设备 ID 列表 |
| `lazy_load` | `bool` | `False` | 是否延迟加载模型到内存 |
| `device_id` | `int \| None` | `None` | 指定单个设备 ID |
| `specific_model_path` | `str \| None` | `None` | 指定自定义模型路径 |
资料来源：[fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py:50-80]()
### 核心方法
#### _list_supported_models()
返回库中支持的所有重排序模型列表。
```python
@classmethod
def _list_supported_models(cls) -> list[BaseModelDescription]
```
**返回值：** `list[BaseModelDescription]` - 包含模型信息的描述对象列表
**使用示例：**
```python
from fastembed.rerank.cross_encoder import OnnxTextCrossEncoder
supported = OnnxTextCrossEncoder._list_supported_models()
for model in supported:
print(f"{model.model}: {model.description}")
```
资料来源：[fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py:30-40]()
## 使用示例
### 基础用法
```python
from fastembed import TextCrossEncoder
# 初始化重排序模型
model = TextCrossEncoder(model_name="jinaai/jina-reranker-v1-turbo-en")
# 准备查询和候选文档
query = "What is machine learning?"
documents = [
"Machine learning is a subset of artificial intelligence.",
"Deep learning uses neural networks with multiple layers.",
"The weather today is sunny and warm.",
"Python is a programming language popular in data science."
]
# 执行重排序
scores = model.encode(query=query, documents=documents)
# 按相关性分数排序
ranked_results = sorted(zip(documents, scores), key=lambda x: x[1], reverse=True)
print(ranked_results)
```
### 与向量检索集成
在实际应用中，重排序通常作为两阶段检索的第二阶段：
```mermaid
graph LR
A[查询] --> B[向量检索
Bi-Encoder]
B --> C[Top-K 候选文档]
C --> D[重排序
Cross-Encoder]
D --> E[最终排序结果]
```
```python
from fastembed import TextEmbedding, TextCrossEncoder
# 第一阶段：向量检索
embedding_model = TextEmbedding(model_name="BAAI/bge-small-en-v1.5")
query_embedding = list(embedding_model.embed([query]))[0]
# 向量数据库检索获取 Top-100 候选
candidates = vector_db.search(query_embedding, top_k=100)
# 第二阶段：重排序
reranker = TextCrossEncoder(model_name="jinaai/jina-reranker-v1-turbo-en")
reranked = reranker.encode(query=query, documents=candidates)
# 输出最终结果
final_results = sorted(zip(candidates, reranked), key=lambda x: x[1], reverse=True)[:10]
```
## ONNX 模型加载机制
### 模型下载与缓存
重排序模型通过 HuggingFace Hub 自动下载，存储在配置的缓存目录中：
| 平台 | 默认缓存路径 |
|------|--------------|
| Linux | `~/.cache/huggingface/modules/fastembed_cache/` |
| macOS | `~/Library/Caches/fastembed_cache/` |
| Windows | `%LOCALAPPDATA%\fastembed_cache\` |
缓存行为可通过以下方式配置：
```python
import os
# 方式一：环境变量
os.environ["FASTEMBED_CACHE_PATH"] = "/path/to/custom/cache"
# 方式二：构造函数参数
model = TextCrossEncoder(
model_name="jinaai/jina-reranker-v1-turbo-en",
cache_dir="/path/to/custom/cache"
)
```
### ONNX 执行 Providers
FastEmbed 支持多种 ONNX Runtime 执行提供者：
| Provider | 说明 | 优先级 |
|----------|------|--------|
| `CUDAExecutionProvider` | NVIDIA GPU 加速 | 最高（如可用） |
| `CPUExecutionProvider` | CPU 执行 | 默认 |
```python
from fastembed.rerank.cross_encoder import OnnxTextCrossEncoder, OnnxProvider
# 强制使用 CPU
model = TextCrossEncoder(
model_name="jinaai/jina-reranker-v1-turbo-en",
providers=["CPUExecutionProvider"]
)
```
## 模型元数据结构
重排序模型使用 `BaseModelDescription` 数据结构存储模型元信息：
```python
@dataclass
class BaseModelDescription:
model: str # 模型唯一标识符
description: str # 模型功能描述
license: str # 许可证类型
size_in_GB: float # 模型文件大小
sources: ModelSource # 模型来源配置
model_file: str # ONNX 模型文件名
```
资料来源：[fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py:20-35]()
## 性能优化建议
### 延迟加载
对于多模型切换场景，建议使用延迟加载：
```python
# 预加载所有模型（占用大量内存）
model_a = TextCrossEncoder("jinaai/jina-reranker-v1-tiny-en")
model_b = TextCrossEncoder("jinaai/jina-reranker-v1-turbo-en")
# 延迟加载（按需加载）
model = TextCrossEncoder(
"jinaai/jina-reranker-v1-tiny-en",
lazy_load=True
)
# 首次调用 encode() 时才加载模型
```
### 批量处理
重排序支持批量文档处理以提高吞吐量：
```python
queries = ["query1", "query2", "query3"]
documents = [
["doc1 for query1", "doc2 for query1"],
["doc1 for query2"],
["doc1 for query3", "doc2 for query3", "doc3 for query3"]
]
# 批量重排序
results = model.encode(queries=queries, documents=documents)
```
### GPU 加速
启用 CUDA 加速可显著提升推理速度：
```python
model = TextCrossEncoder(
model_name="jinaai/jina-reranker-v1-turbo-en",
cuda=True, # 启用 CUDA
device_ids=[0, 1] # 使用多 GPU
)
```
## 注意事项
### 许可证合规
使用重排序模型时需注意许可证要求：
| 模型 | 许可证 | 商业使用 |
|------|--------|----------|
| jina-reranker-v1-tiny-en | apache-2.0 | ✅ 可商用 |
| jina-reranker-v1-turbo-en | apache-2.0 | ✅ 可商用 |
| jina-reranker-v2-base-multilingual | cc-by-nc-4.0 | ⚠️ 仅非商业用途 |
| bge-reranker-base | mit | ✅ 可商用 |
### 上下文长度限制
不同模型有不同的最大输入长度限制：
- `jina-reranker-v1-tiny-en`：8K tokens
- `jina-reranker-v1-turbo-en`：8K tokens
- `jina-reranker-v2-base-multilingual`：1K tokens
超过限制的输入将被自动截断，可能影响重排序准确性。
## 扩展阅读
- [官方文档：重排序模型](https://qdrant.github.io/fastembed/examples/FRR/)
- [Jina AI Reranker 系列介绍](https://jina.ai/reranker/)
- [BGE Reranker 模型](https://huggingface.co/BAAI/bge-reranker-base)
- [ONNX Runtime 文档](https://onnxruntime.ai/docs/)
---
## 社区证据
### Stored Community Evidence
- [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2 | https://github.com/qdrant/fastembed/issues/618 | [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2 ### What happened? When running on **Python 3.14.2 (Linux)**, initializing `SparseTextEmbedding` causes a **Segmentation Fault (Exit Code 139)**. Additionally, when used via `qdrant-client`, it triggers an `AssertionError` in the [is_installed](file:///home/zaori-dev/projetos/
- [Bug]: No timeout on model download — requests.get() can hang indefinitely | https://github.com/qdrant/fastembed/issues/627 | [Bug]: No timeout on model download — requests.get() can hang indefinitely ## Summary The `download_file_from_gcs` method calls `requests.get()` with no `timeout` parameter. The Python `requests` library has no default timeout, so a stalled connection will block indefinitely. This is directly in the model initialization path, meaning any application calling
- [Bug]: license error in pypi metadata | https://github.com/qdrant/fastembed/issues/620 | [Bug]: license error in pypi metadata ### What happened? On pypi.org the license for fastembed is listed as **Other/Proprietary License (Apache License)** when it should be **Apache-2.0**. This could be because the `license` field in the `pyproject.toml` file expects a valid SPDX identifier, which in this case would be **Apache-2.0**, as opposed to **Apache
- [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14 | https://github.com/qdrant/fastembed/issues/630 | [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14 ### What happened? Code Crashes with 'Segmentation fault: 11'. Any suggestions on how to debug this? ``` from fastembed import SparseTextEmbedding documents = [ "You should stay, study and sprint.", "History can only prepare us to be surprised yet again.", ] model = SparseTextEmbedding(model_name="Qdran
- [Bug]: Loading models with additional files fails with onnxruntime 1.24.1 | https://github.com/qdrant/fastembed/issues/603 | [Bug]: Loading models with additional files fails with onnxruntime 1.24.1 ### What happened? Loading either `intfloat/multilingual-e5-large` or `jinaai/jina-embeddings-v3` fails with `onnxruntime==1.24.1`. To reproduce create an instance of the model, e.g. `TextEmbedding(model_name="jinaai/jina-embeddings-v3")`. The results in `FAIL : External data path vali
- The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment. | https://github.com/qdrant/fastembed/issues/466 | The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment. I'm currently using Python 3.13, and when I use version 0.4.1, I find that the ONNX build speed is very slow. I later found in this [issue](https://github.com/onnx/onnx/issues/6594#issuecomment-2568829620) that the problem is related to ONNX's support for Python 3.13. I late
- [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory | https://github.com/qdrant/fastembed/issues/626 | [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory ## Summary The `decompress_to_cache` method uses `tarfile.extractall()` without sanitizing member paths, making it vulnerable to **Zip Slip / Tar Slip** (CVE-2007-4559 class). A malicious tar archive can write files to arbitrary locations outside `cache
- v0.8.0 | https://github.com/qdrant/fastembed/releases/tag/v0.8.0 | v0.8.0 # Changelog ## Features 🏎️ * #537 - use cuda if available, instead of requiring explicit `cuda=True` * #588 - add colmodernvbert by @kacperlukawski @joein ## Fixes 🔧 * #534 - update colbert description by @joein * #611 - fix onnxruntime and pillow versions for better 3.14 support and avoiding security issues caused by pillow * #614 - respect HF_HUB_OF
- v0.7.4 | https://github.com/qdrant/fastembed/releases/tag/v0.7.4 | v0.7.4 # Changelog ## Features 🏎️ * #577 - don't do any network calls if model is loaded from cache @joein * #578 - expose `enable_cpu_mem_arena` onnx session option to handle onnxruntime memory allocation by @joein * #582 - unlock hf hub and pillow versions by @joein * #583 - add a new `token_count` method to text models by @joein @dancixx ## Fixes 🕸️ * #58
- v0.7.2 | https://github.com/qdrant/fastembed/releases/tag/v0.7.2 | v0.7.2 # Changelog ## Features 🏎️ * #542 - add MUVERA post processing module by @kacperlukawski @joein ## Fixes 🕸️ * #547 - avoid adding padding token embeddings to the result in batched inference in late interaction models by @generall Thanks to everyone who contributed to this release @kacperlukawski @generall @joein
- v0.7.1 | https://github.com/qdrant/fastembed/releases/tag/v0.7.1 | v0.7.1 # Changelog ## Features 🏎️ * #532 - improved warnings for the recently changed models by @joein * #522 - raise exceptions in case of incorrect pooling in custom models by @joein * #521 - add property `embedding_size` and cls method `get_embedding_size` for easier access to the model dim by @joein ## Fixes 🕸️ * #524 - fix propagation of `specific_model
- v0.7.0 | https://github.com/qdrant/fastembed/releases/tag/v0.7.0 | v0.7.0 # Changelog ## Features 🏎️ * #513 - New sparse embeddings model with semantic understanding: MiniCOIL (`Qdrant/minicoil-v1`) by @generall ## Fixes 🕸️ * #506 - fix list of supported languages in bm25 by @joein
- v0.6.1 | https://github.com/qdrant/fastembed/releases/tag/v0.6.1 | v0.6.1 # Changelog ## Features 🏎️ * #490 - deprecate old archive struct when loading from custom urls in favour of `model_name.tar.gz` to ease adding custom models by @joein * #492 - preserve embeddings in a type set by their model to allow lower precision outputs by @joein * #496 - custom rerankers support by @I8dNLo ## Fixes 🕸️ * #499 - fix splade hf sourc
### Top Community Issues (by engagement)
- #107: "Support BAAI/bge-m3" (0 reactions, 18 comments)
Requesting support for BAAI/bge-m3. Thanks.
- #559: "Add EmbeddingGemma" (0 reactions, 1 comments)
https://developers.googleblog.com/en/introducing-embeddinggemma/
- #348: "[Model Request]: Support for BGE-M3 embedding model" (0 reactions, 6 comments)
### What happened?
I would really appreciate it if the BGE-M3 model is supported including dense sparse and colbert vectors.
### What Python version are you on? e.g. python --version
Python 3.11
### Version
0.2.7 (Latest)
### What os are you seeing the problem on?
Linux
### Relevant stack...
- #606: "Release 0.7.5 to unblock pillow 12.x (CVE-2026-25990)" (0 reactions, 4 comments)
## Summary
The pillow constraint on `main` has already been relaxed to `>=10.3.0,<13.0.0`, but the latest PyPI release (v0.7.4) still pins `pillow<12.0`. This forces downstream consumers onto Pillow 11.x, which is affected by CVE-2026-25990 (heap-based buffer overflow in PSD loading).
Could you...
- #123: "intfloat/multilingual-e5-small request" (0 reactions, 6 comments)
Request of intfloat/multilingual-e5-small. That would be nice :)
### Latest Release: v0.8.0
# Changelog
## Features 🏎️
* #537 - use cuda if available, instead of requiring explicit `cuda=True`
* #588 - add colmodernvbert by @kacperlukawski @joein
## Fixes 🔧
* #534 - update colbert description by @joein
* #611 - fix onnxruntime and pillow versions for better 3.14 support and avoiding security issues caused by pillow
* #614 - respect HF_HUB_OFFLINE env by @amasolov
##...
---
## Doramagic 踩坑日志
项目：qdrant/fastembed
摘要：发现 31 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2。
## 1. 安装坑 · 来源证据：[Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_201d4035515846df8830ca0dad6960c5 | https://github.com/qdrant/fastembed/issues/618 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：[Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8147621574b345d7955e79ad98f4ba6f | https://github.com/qdrant/fastembed/issues/630 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 安全/权限坑 · 失败模式：security_permissions: [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside ca...
- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory
- 对用户的影响：Developers may expose sensitive permissions or credentials: [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory. Context: Observed when using python
- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/qdrant/fastembed/issues/626
- 证据：failure_mode_cluster:github_issue | fmev_d3890c2b3360ccb937839f70fd4aa584 | https://github.com/qdrant/fastembed/issues/626 | [Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory
## 4. 安装坑 · 失败模式：installation: The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.
- 对用户的影响：Developers may fail before the first successful local run: The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.. Context: Observed when using python, docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_16e50a8626aff1576adeb1c0baab4785 | https://github.com/qdrant/fastembed/issues/466 | The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.
## 5. 安装坑 · 失败模式：installation: [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2
- 对用户的影响：Developers may fail before the first successful local run: [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2. Context: Observed when using python, windows, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_04529bc774f1c961d4adeb7190edecd7 | https://github.com/qdrant/fastembed/issues/618 | [Bug]: Segmentation Fault or AssertionError during initialization on Python 3.14.2
## 6. 安装坑 · 失败模式：installation: [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14
- 对用户的影响：Developers may fail before the first successful local run: [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14. Context: Observed when using python, macos, cuda
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_79a43347d96beb6d05eb6bfec2503fb5 | https://github.com/qdrant/fastembed/issues/630 | [Bug]: Unable to load 'Qdrant/bm25' on macOS python3.14
## 7. 安装坑 · 失败模式：installation: v0.5.1
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.5.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.5.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.5.1. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_8b37c58c613005c0182d0325aaf032f7 | https://github.com/qdrant/fastembed/releases/tag/v0.5.1 | v0.5.1
## 8. 安装坑 · 来源证据：The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：The dependency `py-rust-stemmers` cannot be downloaded in a pure Python environment.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0f507b37e33e456ea259e82966cecdc5 | https://github.com/qdrant/fastembed/issues/466 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 9. 安装坑 · 来源证据：[Model]: LateOn
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Model]: LateOn
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a9b99af798634ad59ae636ce4944af12 | https://github.com/qdrant/fastembed/issues/641 | 来源类型 github_issue 暴露的待验证使用条件。
## 10. 配置坑 · 来源证据：[Bug]: No timeout on model download — requests.get() can hang indefinitely
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: No timeout on model download — requests.get() can hang indefinitely
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6d570ba91cfd414f970a3a8da522be04 | https://github.com/qdrant/fastembed/issues/627 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 11. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:666260877 | https://github.com/qdrant/fastembed | README/documentation is current enough for a first validation pass.
## 12. 运行坑 · 失败模式：runtime: [Bug]: Loading models with additional files fails with onnxruntime 1.24.1
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: [Bug]: Loading models with additional files fails with onnxruntime 1.24.1
- 对用户的影响：Developers may hit a documented source-backed failure mode: [Bug]: Loading models with additional files fails with onnxruntime 1.24.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Loading models with additional files fails with onnxruntime 1.24.1. Context: Observed when using python, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_17b849ae47ffaf5d18cabbd577f373ca | https://github.com/qdrant/fastembed/issues/603 | [Bug]: Loading models with additional files fails with onnxruntime 1.24.1
## 13. 运行坑 · 失败模式：runtime: v0.4.2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: v0.4.2
- 对用户的影响：Upgrade or migration may change expected behavior: v0.4.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.4.2. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_607c8ff157108b2b5fb78f55129b60f6 | https://github.com/qdrant/fastembed/releases/tag/v0.4.2 | v0.4.2
## 14. 运行坑 · 失败模式：runtime: v0.7.1
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: v0.7.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.7.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.7.1. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_07583dafa20e640a1720d7a77188475e | https://github.com/qdrant/fastembed/releases/tag/v0.7.1 | v0.7.1
## 15. 运行坑 · 失败模式：runtime: v0.8.0
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: v0.8.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.8.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.8.0. Context: Observed when using python, cuda
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_054bae0c9c1667cf5568de7ecb7087c9 | https://github.com/qdrant/fastembed/releases/tag/v0.8.0 | v0.8.0
## 16. 维护坑 · 来源证据：[Bug]: license error in pypi metadata
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Bug]: license error in pypi metadata
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_017eda744ea84e679aeb5d77d41f7541 | https://github.com/qdrant/fastembed/issues/620 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 17. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:666260877 | https://github.com/qdrant/fastembed | last_activity_observed missing
## 18. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:666260877 | https://github.com/qdrant/fastembed | no_demo; severity=medium
## 19. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:666260877 | https://github.com/qdrant/fastembed | no_demo; severity=medium
## 20. 安全/权限坑 · 来源证据：Release 0.7.5 to unblock pillow 12.x (CVE-2026-25990)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release 0.7.5 to unblock pillow 12.x (CVE-2026-25990)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_49a21b32bb9c48618afce73b7cfdaa3f | https://github.com/qdrant/fastembed/issues/606 | 来源类型 github_issue 暴露的待验证使用条件。
## 21. 安全/权限坑 · 来源证据：[Bug]: Loading models with additional files fails with onnxruntime 1.24.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Loading models with additional files fails with onnxruntime 1.24.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cfcd79475b1344a0bba508ac4346edf4 | https://github.com/qdrant/fastembed/issues/603 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 22. 安全/权限坑 · 来源证据：[Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Tar path traversal (Zip Slip) in decompress_to_cache — arbitrary file write outside cache directory
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7603e6da390349c9aff6eed6cc5072a9 | https://github.com/qdrant/fastembed/issues/626 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 23. 能力坑 · 失败模式：capability: [Bug]: license error in pypi metadata
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: [Bug]: license error in pypi metadata
- 对用户的影响：Developers may hit a documented source-backed failure mode: [Bug]: license error in pypi metadata
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: license error in pypi metadata. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_9e209e0c78e000b92930bccb67db1440 | https://github.com/qdrant/fastembed/issues/620 | [Bug]: license error in pypi metadata
## 24. 运行坑 · 失败模式：performance: [Bug]: No timeout on model download — requests.get() can hang indefinitely
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: [Bug]: No timeout on model download — requests.get() can hang indefinitely
- 对用户的影响：Developers may hit a documented source-backed failure mode: [Bug]: No timeout on model download — requests.get() can hang indefinitely
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: No timeout on model download — requests.get() can hang indefinitely. Context: Observed when using python, docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_69d0e997d6514a5d87d46c30a69795b3 | https://github.com/qdrant/fastembed/issues/627 | [Bug]: No timeout on model download — requests.get() can hang indefinitely
## 25. 运行坑 · 失败模式：performance: v0.7.4
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v0.7.4
- 对用户的影响：Upgrade or migration may change expected behavior: v0.7.4
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.7.4. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_df69e175afaf53788c9f212e22680b87 | https://github.com/qdrant/fastembed/releases/tag/v0.7.4 | v0.7.4
## 26. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:666260877 | https://github.com/qdrant/fastembed | issue_or_pr_quality=unknown
## 27. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:666260877 | https://github.com/qdrant/fastembed | release_recency=unknown
## 28. 维护坑 · 失败模式：maintenance: v0.6.0
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.6.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.6.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.6.0. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_abc84a0766f60148974f2e932e8dc4f4 | https://github.com/qdrant/fastembed/releases/tag/v0.6.0 | v0.6.0
## 29. 维护坑 · 失败模式：maintenance: v0.6.1
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.6.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.6.1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.6.1. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_e909fbcb26efacd532e8194ede2ff4f0 | https://github.com/qdrant/fastembed/releases/tag/v0.6.1 | v0.6.1
## 30. 维护坑 · 失败模式：maintenance: v0.7.0
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.7.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.7.0. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_0ccd78cc792f8d6a79212fc6cfa512e4 | https://github.com/qdrant/fastembed/releases/tag/v0.7.0 | v0.7.0
## 31. 维护坑 · 失败模式：maintenance: v0.7.2
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v0.7.2
- 对用户的影响：Upgrade or migration may change expected behavior: v0.7.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.7.2. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_28a8ed6e38ab5a351c6a64532998a7df | https://github.com/qdrant/fastembed/releases/tag/v0.7.2 | v0.7.2