核心特性

FastEmbed 的设计目标是在保持高精度的同时实现极致的推理速度。以下是该项目的主要特性：

资料来源：README.md

架构概览

FastEmbed 采用模块化架构，不同类型的嵌入模型通过统一的接口暴露给用户。整体架构可分为以下几个核心模块：

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 序列进行平均池化处理。支持的模型包括：

资料来源：fastembed/text/pooled_embedding.py

#### PooledNormalizedEmbedding 归一化池化嵌入

对输出进行 L2 归一化处理的池化嵌入模型，适用于需要余弦相似度的场景：

from fastembed import TextEmbedding

model = TextEmbedding(model_name="BAAI/bge-base-en-v1.5")
embeddings = list(model.embed(documents))

支持的模型包括多个 BGE 变体和 Jina Embeddings 系列：

资料来源：fastembed/text/pooled_normalized_embedding.py

图像嵌入模型

FastEmbed 的图像嵌入功能通过 OnnxImageEmbedding 类实现：

资料来源：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

#### SPLADE++

SPLADE++ 是另一种稀疏嵌入模型，通过稀疏向量表示捕获词汇级别的相关性：

from fastembed import SparseTextEmbedding

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

Reranker 模型

FastEmbed 提供 Cross-Encoder 风格的重新排序功能，用于提升搜索结果的相关性：

资料来源：fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py

后处理器

#### Muvera

Muvera 是一种将多向量表示压缩为固定维度编码的算法，常用于 ColBERT 等模型的输出后处理：

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

使用流程

graph LR
    A[选择模型类型] --> B[初始化模型]
    B --> C[输入数据]
    C --> D[生成嵌入向量]
    D --> E[向量索引/相似度计算]
    E --> F[可选: Reranking]

基本使用示例

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 加速使用

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 类管理模型文件的下载来源：

ModelSource(
    hf="huggingface/model-id",      # HuggingFace Hub
    url="https://...",              # 自定义 URL
    _deprecated_tar_struct=True    # 兼容旧版 tar 结构
)

某些模型还支持从自定义 URL 加载，适用于私有存储场景：

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 向量数据库深度集成，可通过以下方式安装：

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、mkdocs.yml

许可证

FastEmbed 项目采用多种开源许可证：

使用前请查阅具体模型的许可证要求。

环境要求

系统要求

FastEmbed 支持在 Linux、macOS 和 Windows 系统上运行。建议使用 Python 3.9 或更高版本以确保最佳兼容性。

硬件加速支持

FastEmbed 基于 ONNX Runtime 构建，支持多种硬件加速 Provider：

• CPUExecutionProvider: 默认的 CPU 执行提供者
• CUDAExecutionProvider: NVIDIA GPU 加速
• CoreMLExecutionProvider: Apple Silicon (M1/M2/M3) 加速

资料来源：README.md:45-60

安装方式

基础安装

使用 pip 安装 FastEmbed 的基础版本：

pip install fastembed

此安装包含所有 CPU 相关的依赖和基础功能。

GPU 版本安装

对于需要 GPU 加速的场景，安装 GPU 专版：

pip install fastembed-gpu

资料来源：RELEASE.md:1-15

与 Qdrant 集成安装

基础集成

Qdrant Client 提供了与 FastEmbed 的深度集成支持：

pip install qdrant-client[fastembed]

资料来源：README.md:65-75

GPU 加速集成

使用 GPU 加速的 Qdrant 集成：

pip install qdrant-client[fastembed-gpu]

注意：在 zsh shell 中可能需要使用引号：

```bash

pip install 'qdrant-client[fastembed]'

```

资料来源：README.md:72-73

模型下载与缓存

缓存目录配置

FastEmbed 会自动缓存下载的模型文件。可以通过环境变量配置缓存路径：

export FASTEMBED_CACHE_PATH=/path/to/cache

默认缓存目录为系统临时目录下的 fastembed_cache 文件夹。

模型列表

FastEmbed 支持多种预训练模型，按功能分类如下：

资料来源：fastembed/text/onnx_embedding.py:100-150

使用示例

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 加速用法

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

Qdrant 集成用法

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

依赖管理

核心依赖

FastEmbed 的核心依赖包括：

• onnxruntime - ONNX 模型推理引擎
• numpy - 数值计算
• tokenizers - 文本分词
• huggingface-hub - 模型下载与管理

可选依赖

资料来源：mkdocs.yml:1-50

故障排除

常见问题

1. 模型下载失败

• 检查网络连接
• 确认 HuggingFace Hub 可访问
• 设置代理或镜像源

1. GPU 不可用

• 确认 CUDA 驱动已正确安装
• 验证 ONNX Runtime GPU 版本已安装
• 检查 GPU 设备可见性

1. 内存不足

• 选择更小的模型（如 bge-small-en）
• 使用量化模型版本
• 减少批处理大小

验证安装

运行以下代码验证安装是否成功：

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 包。发布流程如下：

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

安装

pip install fastembed

FastEmbed 默认使用 ONNX Runtime 作为推理引擎，无需额外安装 PyTorch 或 TensorFlow 依赖。

核心架构

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]

文本嵌入

基础使用

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 支持多种文本嵌入模型，按类型分类如下：

资料来源：fastembed/text/onnx_embedding.py:1-100

初始化参数

资料来源：fastembed/text/onnx_embedding.py:47-75

稀疏嵌入

SPLADE++ 使用

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, ...])

稀疏嵌入类型

资料来源：fastembed/sparse/sparse_text_embedding.py 资料来源：fastembed/sparse/bm25.py:1-50

图像嵌入

基础使用

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))

支持的图像模型

资料来源：fastembed/image/onnx_embedding.py:1-50

重排序 (Cross-Encoder)

使用示例

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)

支持的重排序模型

资料来源：fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py:1-80

多模态嵌入

Jina CLIP 模型

jinaai/jina-clip-v1 支持同时处理文本和图像：

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

常见使用模式

批量处理

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)

自定义缓存目录

import os

os.environ["FASTEMBED_CACHE_PATH"] = "/path/to/cache"

from fastembed import TextEmbedding
model = TextEmbedding()  # 模型将下载到指定目录

下一步

• 查看 支持的模型完整列表 获取更多模型信息
• 了解如何在 Qdrant 中使用生成的向量
• 探索 高级配置选项 优化性能

1. 概览

FastEmbed 是一个高性能向量嵌入库，专为快速文本和图像嵌入生成而设计。其系统架构采用分层设计，核心基于 ONNX Runtime 实现跨平台高效推理。整个系统由模型管理层、并行处理层、ONNX 模型层和嵌入模型层四部分组成，通过模块化设计实现了灵活性与性能的平衡。

FastEmbed 支持多种嵌入类型：稠密嵌入（Dense Embedding）、稀疏嵌入（Sparse Embedding）和图像嵌入（Image Embedding），并提供交叉编码器（Cross Encoder）用于重排序任务。

2. 核心架构分层

FastEmbed 的架构采用分层设计，各层职责明确，层与层之间通过抽象接口进行交互。

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

架构层级说明

3. ONNX模型层

3.1 OnnxTextModel 核心实现

OnnxTextModel 是文本嵌入模型的基础类，封装了 ONNX Runtime 的核心操作逻辑。

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[标准化嵌入向量]

核心参数定义：

3.2 输出后处理机制

OnnxTextModel 定义了灵活的输出后处理钩子，通过 _post_process_onnx_output 方法实现不同模型的输出格式化：

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 支持三种核心嵌入类型：

4.2 池化策略实现

对于需要 Mean Pooling 的模型（如 jinaai/jina-embeddings-v2-*），系统提供了 PooledEmbedding 基类：

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 支持的嵌入模型

#### 稠密嵌入模型

#### 稀疏嵌入模型

5. 并行处理层

5.1 并行处理器架构

ParallelProcessor 是 FastEmbed 实现批量处理的核心组件，支持多线程和进程级并行。

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 类的核心职责：

5.3 批处理参数

6. 模型管理

6.1 模型描述结构

@dataclass
class DenseModelDescription:
    model: str                          # HuggingFace 模型标识
    dim: int                            # 输出向量维度
    description: str                    # 模型描述
    license: str                        # 许可证类型
    size_in_GB: float                   # 模型大小（GB）
    资料来源：ModelSource                # 模型来源配置
    model_file: str                     # ONNX 文件名
    additional_files: list[str] = []    # 附加文件
    requires_idf: bool = False         # 是否需要 IDF 权重

6.2 模型来源配置

@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 模型缓存机制

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 完整嵌入生成流程

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 输入输出格式

输入字典结构：

{
    "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)  # 可选
}

输出上下文：

@dataclass
class OnnxOutputContext:
    model_output: NumpyArray           # 模型原始输出
    attention_mask: NumpyArray | None  # 注意力掩码

8. 设备与提供者配置

8.1 执行提供者支持

8.2 设备自动检测

@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 列表中添加配置：

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 方法，可以实现自定义输出处理逻辑：

class CustomEmbedding(OnnxTextEmbedding):
    def _post_process_onnx_output(
        self, output: OnnxOutputContext, **kwargs: Any
    ) -> Iterable[NumpyArray]:
        # 自定义后处理逻辑
        embeddings = output.model_output
        return custom_normalization(embeddings)

10. 架构设计原则

概述

密集文本嵌入（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 的密集文本嵌入模块采用继承和组合的设计模式，核心类层次结构如下：

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 推理和输出后处理四个阶段：

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 运行时交互。

#### 初始化参数

资料来源：fastembed/text/onnx_embedding.py:62-90

#### 核心方法

• _list_supported_models(): 返回支持的模型列表，定义在各个子类中
• _post_process_onnx_output(): 对 ONNX 模型输出进行后处理
• embed(): 主嵌入方法，处理单批或多批文档

PooledNormalizedEmbedding

PooledNormalizedEmbedding 是最常用的密集文本嵌入实现，它在平均池化后对向量进行 L2 归一化，确保输出向量具有单位长度。

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）系列是由北京人工智能研究院开发的通用文本嵌入模型。

BGE 模型在 MS-MARCO 和 BEIR 基准测试中表现优异，是当前最流行的开源嵌入模型之一。资料来源：fastembed/text/onnx_embedding.py:80-150

Jina Embeddings 系列

Jina AI 开发的多语言嵌入模型，支持长达 8192 tokens 的输入。

Jina Embeddings v2 系列的核心优势在于超长上下文窗口（8192 tokens），适合处理长文档检索任务。资料来源：fastembed/text/onnx_embedding.py:100-180

E5 系列

E5（Embeddings from bi-directional language models）系列专注于高效的文本嵌入，支持大规模多语言场景。

E5 模型需要添加查询前缀（query prefix）以获得最佳性能，这与其他模型的通用处理方式有所不同。资料来源：fastembed/text/pooled_embedding.py:60-100

Snowflake Arctic Embed 系列

Snowflake 开发的嵌入式模型，专注于企业级应用场景。

GTE 系列

GTE（General Text Embeddings）系列由 Thenlper 开发。

资料来源：fastembed/text/pooled_normalized_embedding.py:40-70

使用方法

基本用法

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))

批处理

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 支持同时使用密集嵌入和稀疏嵌入，这种混合检索方式可以结合两者的优势：

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 的嵌入：

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，这对于使用余弦相似度进行向量比较至关重要：

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 提供者，优先级从高到低：

设备自动选择

通过 Device.AUTO 配置，系统会自动选择最佳可用设备：

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])

性能优化

模型缓存

首次使用模型时会自动下载并缓存到本地目录：

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")

延迟加载

对于多模型场景，可以使用延迟加载减少初始内存占用：

model = TextEmbedding(
    model_name="BAAI/bge-base-en-v1.5",
    lazy_load=True
)

多线程配置

对于 CPU 推理，可以通过调整线程数优化性能：

model = TextEmbedding(
    model_name="BAAI/bge-base-en-v1.5",
    threads=8  # 使用 8 个线程
)

与稀疏嵌入的对比

FastEmbed 推荐在大多数场景使用 PooledNormalizedEmbedding（密集嵌入），在需要精确关键词匹配或混合检索时结合使用稀疏嵌入（如 SPLADE 或 BM25）。资料来源：fastembed/sparse/bm25.py:20-45

模型选择指南

按语言选择

按性能选择

按输入长度选择

概述

稀疏文本嵌入（Sparse Text Embedding）是FastEmbed库中处理非密集向量表示的一组模型和工具。与传统的密集嵌入（dense embedding）不同，稀疏嵌入使用高维但大部分为零的向量来表示文本，其中非零值对应于词汇表中特定词汇的重要性权重。

FastEmbed的稀疏嵌入模块主要用于：

• 关键词匹配与语义理解的结合：在保持精确关键词匹配行为的同时，解析词汇的语义含义
• BM25风格的稀疏检索：使用词频统计和逆文档频率（IDF）进行传统信息检索
• SPLADE++等现代稀疏模型：通过深度学习生成稀疏但具有语义能力的向量表示

架构设计

类层次结构

稀疏文本嵌入模块采用模块化的类层次结构设计：

SparseTextEmbeddingBase (抽象基类)
    ├── SpladePp (SPLADE++ 模型)
    ├── Bm25 (传统BM25实现)
    ├── Bm42 (BM42模型)
    └── MiniCOIL (混合稀疏模型)

核心组件

数据流图

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: 权重值列表]

支持的稀疏模型

模型对比表

模型详细说明

#### SPLADE++

SPLADE++是一种基于Transformer的稀疏嵌入模型，它通过学习为每个词汇分配权重，生成稀疏但具有语义表达能力的向量。模型的核心特点是：

• 高稀疏性：大多数维度为零，只有少数重要词汇有非零权重
• 语义能力：继承了BERT等Transformer模型的语义理解能力
• 端到端学习：通过对比学习目标函数进行训练

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 类

from fastembed import SparseTextEmbedding

model = SparseTextEmbedding(
    model_name: str,      # 模型名称
    cache_dir: str | None, # 缓存目录
    threads: int | None,   # 并行线程数
    **kwargs              # 其他参数
)

核心方法

#### embed()

def embed(
    documents: Iterable[str],
    batch_size: int = 256,
    parallel: int | None = None,
    **kwargs
) -> Iterable[SparseEmbedding]

参数说明：

返回类型：Iterable[SparseEmbedding]

SparseEmbedding 数据结构

class SparseEmbedding:
    indices: list[int]   # 非零元素的词索引
    values: list[float] # 对应的权重值

示例：

SparseEmbedding(indices=[17, 123, 919, ...], values=[0.71, 0.22, 0.39, ...])

使用示例

基本用法

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}")

使用不同模型

# 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")

批处理与并行

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兼容的稀疏向量格式：

graph LR
    A[Sentence Embedding] --> B[Vocabulary Words]
    A --> C[Out-of-Vocabulary Words]
    B --> D[Known Word Embedding<br/>4-dim component]
    C --> E[BM25 Fallback<br/>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（逆文档频率）配置：

DenseModelDescription(
    model="Qdrant/bm42-all-minilm-l6-v2-attentions",
    requires_idf=True,  # 需要IDF文件
    additional_files=["model.onnx_data"]
)

当requires_idf=True时，模型会加载语料库级别的IDF统计信息用于查询重加权。

配置与调优

模型参数

BM25参数调优

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使用示例：

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
        }
    }]
)

性能考量

内存占用

稀疏嵌入相比密集嵌入具有显著的内存优势：

计算效率

• 稀疏计算：跳过零值计算，减少FLOPs
• 批量处理：支持大批量并行推理
• ONNX优化：利用ONNX Runtime的图优化和算子融合

许可证与来源

FastEmbed稀疏嵌入模块中的模型使用多种许可证：

所有模型均可从HuggingFace Hub公开获取。

相关资源

• FastEmbed官方文档
• Qdrant向量数据库
• SPLADE论文
• BM25算法详解

概述

ColBERT（Contextualized Late Interactions over BERT）是 FastEmbed 框架中实现的一种后期交互（Late Interaction）文本嵌入技术。与传统的密集嵌入模型不同，ColBERT 采用独特的标记级嵌入（Token-level Embeddings）策略，将输入文本的每个 token 都编码为独立的向量，然后在检索阶段通过高效的晚期交互计算相关性评分。

后期交互模型的核心优势在于能够在保持检索效率的同时，捕获查询与文档之间细粒度的语义匹配关系。这种方法特别适用于需要高质量排序的搜索引擎和推荐系统场景。

核心概念

后期交互原理

传统密集嵌入模型在编码阶段就将查询和文档压缩为单一的固定维度向量，导致细粒度匹配信息的丢失。而 ColBERT 采用延迟交互策略：

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 进行独立的相似度计算。

架构设计

类继承结构

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

核心类说明

资料来源：late_interaction_embedding_base.py，colbert.py，jina_colbert.py

API 使用

基础初始化

from fastembed import LateInteractionTextEmbedding

# 使用 Jina ColBERT v2 模型
model = LateInteractionTextEmbedding(model_name="jinaai/jina-colbert-v2")

生成标记级嵌入

# 对查询生成标记嵌入
query_embeddings = list(model.query_embed("什么是向量检索"))

# 对文档生成标记嵌入
document_embeddings = list(model.embed(["这是一篇关于向量数据库的文章"]))

嵌入输出格式

每个 query_embed 和 embed 调用返回的都是 TokenEmbeddings 对象，包含每个 token 的向量表示：

# TokenEmbeddings 结构包含:
# - vectors: 每个 token 的嵌入向量 (num_tokens, dim)
# - attention_mask: 注意力掩码
# - token_ids: token ID 列表

资料来源：late_interaction_text_embedding.py

支持的模型

模型列表

资料来源：jina_colbert.py:6-13

Jina ColBERT v2 特性

Jina ColBERT v2 是当前 FastEmbed 支持的唯一后期交互模型，具有以下特性：

• 多语言支持：能够处理多种语言的文本输入
• 长上下文：支持最高 8192 个 token 的上下文长度
• 标记标记机制：使用特殊的查询标记符（[CLS] 替代）和文档标记符来区分查询和文档
• 高效交互：通过 Max-Sum 机制实现高效的晚期交互计算

配置参数

初始化参数

工作流程

检索流程

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

与密集嵌入的对比

应用场景

最佳使用场景

1. 搜索结果重排：使用 ColBERT 对候选文档进行精确排序
2. 问答系统：精确匹配查询与答案候选的相关性
3. 推荐系统：高质量的 item 排序
4. 文本相似度：细粒度的段落或句子级匹配

集成示例

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 存储独立的向量，文档的存储开销高于传统的密集嵌入

1. 查询长度：较长的查询会生成更多的 token 向量，可能影响交互计算效率

1. 模型大小：Jina ColBERT v2 模型大小约为 2.24 GB，需要确保有足够的磁盘空间用于缓存

1. 许可证约束：Jina ColBERT v2 采用 cc-by-nc-4.0 许可证，仅限非商业用途

概述

FastEmbed 的图像嵌入模块提供将图像转换为高维向量的功能，支持多模态检索、图像相似度搜索和跨模态匹配等应用场景。该模块基于 ONNX Runtime 实现高性能推理，支持从本地文件系统或 Hugging Face Hub 自动下载预训练模型。

图像嵌入系统支持以下几种模式：

• 纯图像嵌入：使用 ResNet 等模型提取图像特征
• CLIP 多模态嵌入：支持图像与文本的跨模态编码
• Jina-CLIP 多模态嵌入：支持图像和文本的统一嵌入表示

资料来源：fastembed/image/image_embedding_base.py

支持的模型

模型列表

资料来源：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

核心组件

资料来源：fastembed/image/image_embedding.py

数据流架构

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

图像预处理

转换管道

图像在输入模型前需要经过标准化转换处理：

# 典型预处理流程
ImageTransformer = Compose([
    ResizeImage(size=224),      # 调整尺寸
    ToTensor(),                 # 转为张量
    Normalize(mean, std),       # 标准化
])

资料来源：fastembed/image/transform/operators.py

支持的预处理操作

使用方法

基础用法

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 图像嵌入

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

与文本嵌入配合使用

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：

资料来源：fastembed/image/onnx_image_model.py

设备配置

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，可通过环境变量修改：

export FASTEMBED_CACHE_PATH="/custom/cache/directory"

下载源

模型可以从以下来源下载：

• Hugging Face Hub：默认源，通过 hf 参数指定
• URL 直链：通过 url 参数指定自定义下载 URL

资料来源：fastembed/image/onnx_embedding.py

API 参考

ImageEmbedding 类

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,
    ):
        """初始化图像嵌入模型"""

参数说明

资料来源：fastembed/image/onnx_embedding.py

embed 方法

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: 归一化的嵌入向量
    """

性能考量

批处理建议

延迟加载模式

# 延迟加载，不立即加载模型权重
model = ImageEmbedding(
    model_name="Qdrant/resnet50-onnx",
    lazy_load=True
)
# 模型权重在首次调用 embed 时加载

资料来源：fastembed/image/image_embedding_base.py

最佳实践

1. 图像格式支持

推荐使用以下图像格式：

• JPEG/JPG
• PNG
• BMP
• WEBP

2. 内存管理

# 处理大量图像时使用生成器
def image_generator(image_paths):
    for path in image_paths:
        yield path

embeddings = list(model.embed(image_generator(large_image_list)))

3. 多进程使用

from fastembed import ImageEmbedding

# 每个进程独立初始化模型
def process_batch(image_batch):
    model = ImageEmbedding(model_name="Qdrant/resnet50-onnx")
    return list(model.embed(image_batch))

相关文档

• 文本嵌入 - 文本向量嵌入功能
• 稀疏嵌入 - SPLADE 稀疏嵌入
• 重排序模型 - 交叉编码器重排序
• ColPali 多模态 - 后期交互多模态模型

概述

多模态后期交互（Late Interaction Multimodal）是一种先进的检索架构，它在多模态场景下实现了文档与查询之间的深度交互式匹配。这种方法与传统的单向量表示不同，它允许文档和查询各自生成多个向量表示，然后在检索阶段进行细粒度的交互计算。

在 FastEmbed 库中，多模态后期交互的实现主要通过 ColPali 和 ColModernVBERT 两个核心类完成。这些模型继承自 LateInteractionMultimodalEmbeddingBase 基类，并基于 ONNX 多模态模型架构运行。后期交互方法的核心优势在于能够在保持高效检索的同时，捕捉文档中每个 token 与查询之间的语义关联。

架构设计

类继承层次

多模态后期交互模块采用分层架构设计，各组件之间具有清晰的职责划分：

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 架构。该模型使用双向注意力机制，在检索任务中表现出更好的性能。

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 类似，但采用了不同的预训练策略和注意力机制。双向注意力使得模型能够更全面地理解输入序列中的依赖关系，从而在某些检索场景中获得更优的效果。

核心功能与接口

模型初始化

多模态后期交互模型的初始化遵循统一的接口设计，支持灵活的参数配置：

初始化参数中，cuda 参数支持自动设备检测功能，可以根据系统环境自动选择 GPU 或 CPU 进行推理。lazy_load 选项允许在需要时才加载模型权重，这对于资源受限的环境非常有价值。

嵌入生成流程

多模态后期交互模型的嵌入生成流程涉及图像和文本两种模态的处理：

graph LR
    A[图像输入] --> B[视觉编码器]
    A1[文本查询] --> C[文本编码器]
    B --> D[多向量表示]
    C --> E[多向量表示]
    D --> F[后期交互计算]
    E --> F
    F --> G[相似度分数]

模型的核心输出是多向量表示，而非单一的高维向量。每个输入（无论是图像还是文本）都会被编码为一组向量序列，这些向量序列在后续的检索阶段进行交互计算。

支持的模型列表

FastEmbed 库的多模态后期交互模块支持多种预训练模型，这些模型覆盖了不同的应用场景和性能需求：

模型选择应根据具体的应用需求进行权衡。ColPali 系列模型在文档图像检索任务中表现优异，而 ModernVBERT 在需要双向语义理解的任务中更具优势。

与其他嵌入类型的对比

FastEmbed 库提供了多种嵌入类型，理解它们之间的差异对于正确选择模型至关重要：

后期交互嵌入的核心优势在于其能够捕获细粒度的语义关联。传统密集向量嵌入将整个文档压缩为单一向量，可能丢失重要的局部语义信息；而后期交互方法保留了整个序列的表示，使得查询中的每个 term 都能与文档中的对应部分进行直接比较。

后处理扩展：MUVERA

MUVERA（Multi-Vector Reduction Aggregation）是一种与多模态后期交互配合使用的后处理技术。它的主要作用是将多向量表示压缩为单一固定维度向量，以便在不支持多向量索引的向量数据库中使用。

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。这种设计允许在保持语义信息的同时显著降低向量维度。

使用示例

基本多模态检索

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 配合使用

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 基类并实现必要的抽象方法：

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 文档
• ColPali 论文：ColPali: Efficient Document Retrieval with Vision Language Models
• ModernVBERT：HuggingFace 模型页面

概述

重排序模型（Cross-Encoder Re-ranking）是信息检索系统中提升搜索结果质量的关键组件。与基于向量相似度的双编码器（Bi-Encoder）检索方式不同，重排序模型通过同时编码查询和文档，计算查询与文档之间的交叉注意力分数，从而实现更精确的相关性评估。

FastEmbed 库中的重排序模型基于 Cross-Encoder 架构实现，位于 fastembed/rerank 模块下。该模块采用 ONNX 运行时进行模型推理，支持多种预训练的重排序模型，包括 Jina AI 的 Jina Reranker 系列、BAAI 的 BGE Reranker 以及 MS MARCO MiniLM 等模型。

架构设计

类层次结构

FastEmbed 的重排序模块采用分层架构设计，从基类到具体实现类逐层抽象：

graph TD
    A[TextCrossEncoderBase] --> B[OnnxTextCrossEncoder]
    C[OnnxCrossEncoderModel] --> B
    B --> D[实例化重排序模型]
    
    A1[TextCrossEncoderBase] -.->|定义接口| A
    C1[OnnxCrossEncoderModel] -.->|ONNX推理引擎| C

核心组件说明：

资料来源：fastembed/rerank/cross_encoder/text_cross_encoder.py:1-50

数据流

重排序模型的核心工作流程如下：

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 重排序模块预置了多个经过优化的重排序模型，涵盖英语和多语言场景。

模型配置表

资料来源：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。

#### 构造函数参数

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,
)

参数详细说明：

资料来源：fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py:50-80

核心方法

#### _list_supported_models()

返回库中支持的所有重排序模型列表。

@classmethod
def _list_supported_models(cls) -> list[BaseModelDescription]

返回值： list[BaseModelDescription] - 包含模型信息的描述对象列表

使用示例：

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

使用示例

基础用法

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)

与向量检索集成

在实际应用中，重排序通常作为两阶段检索的第二阶段：

graph LR
    A[查询] --> B[向量检索<br/>Bi-Encoder]
    B --> C[Top-K 候选文档]
    C --> D[重排序<br/>Cross-Encoder]
    D --> E[最终排序结果]

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 自动下载，存储在配置的缓存目录中：

缓存行为可通过以下方式配置：

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 执行提供者：

from fastembed.rerank.cross_encoder import OnnxTextCrossEncoder, OnnxProvider

# 强制使用 CPU
model = TextCrossEncoder(
    model_name="jinaai/jina-reranker-v1-turbo-en",
    providers=["CPUExecutionProvider"]
)

模型元数据结构

重排序模型使用 BaseModelDescription 数据结构存储模型元信息：

@dataclass
class BaseModelDescription:
    model: str                           # 模型唯一标识符
    description: str                     # 模型功能描述
    license: str                         # 许可证类型
    size_in_GB: float                    # 模型文件大小
    资料来源：ModelSource                 # 模型来源配置
    model_file: str                      # ONNX 模型文件名

资料来源：fastembed/rerank/cross_encoder/onnx_text_cross_encoder.py:20-35

性能优化建议

延迟加载

对于多模型切换场景，建议使用延迟加载：

# 预加载所有模型（占用大量内存）
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() 时才加载模型

批量处理

重排序支持批量文档处理以提高吞吐量：

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 加速可显著提升推理速度：

model = TextCrossEncoder(
    model_name="jinaai/jina-reranker-v1-turbo-en",
    cuda=True,              # 启用 CUDA
    device_ids=[0, 1]       # 使用多 GPU
)

注意事项

许可证合规

使用重排序模型时需注意许可证要求：

上下文长度限制

不同模型有不同的最大输入长度限制：

• jina-reranker-v1-tiny-en：8K tokens
• jina-reranker-v1-turbo-en：8K tokens
• jina-reranker-v2-base-multilingual：1K tokens

超过限制的输入将被自动截断，可能影响重排序准确性。

扩展阅读

• 官方文档：重排序模型
• Jina AI Reranker 系列介绍
• BGE Reranker 模型
• ONNX Runtime 文档

Pitfall Log / 踩坑日志

项目：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