⚡️ 什么是 FastEmbed？

FastEmbed 是一个轻量级、快速的 Python 库，专为生成嵌入向量而设计。我们支持流行的文本模型。如果您希望我们添加新的模型，请在 GitHub 上提交一个问题。

默认的文本嵌入（TextEmbedding）模型是 Flag Embedding，该模型在 MTEB 排行榜上有所展示。它支持对输入文本使用“query”和“passage”前缀。以下是关于检索嵌入生成以及如何将FastEmbed 与 Qdrant 配合使用的示例。

📈 为什么选择 FastEmbed？

1. 轻量：FastEmbed 是一个轻量级库，外部依赖较少。我们不需要 GPU，也不需要下载 GB 级别的 PyTorch 依赖项，而是使用 ONNX Runtime。这使得它非常适合无服务器运行时，例如 AWS Lambda。

2. 快速：FastEmbed 专为速度而设计。我们使用 ONNX Runtime，其速度比 PyTorch 更快。此外，我们还利用数据并行性来编码大型数据集。

3. 准确：FastEmbed 的性能优于 OpenAI Ada-002。我们还支持不断扩展的模型集合，其中包括一些多语言模型。

🚀 安装

安装 FastEmbed 库时，推荐使用 pip。您可以选择安装支持 GPU 的版本或不带 GPU 支持的版本：

pip install fastembed

# 或者安装支持 GPU 的版本

pip install fastembed-gpu

📖 快速入门

from fastembed import TextEmbedding


# 示例文档列表
documents: list[str] = [
    "这个库的设计目标是比其他嵌入库（如 Transformers、Sentence-Transformers 等）更快、更轻。",
    "fastembed 由 Qdrant 提供支持并维护。",
]

# 这将触发模型的下载和初始化
embedding_model = TextEmbedding()
print("模型 BAAI/bge-small-en-v1.5 已准备就绪。")

embeddings_generator = embedding_model.embed(documents)  # 提醒一下，这是一个生成器
embeddings_list = list(embedding_model.embed(documents))
  # 您也可以将生成器转换为列表，再将其转换为 numpy 数组
len(embeddings_list[0]) # 向量维度为 384

Fastembed 支持多种用于不同任务和模态的模型。 所有可用模型的列表可以在这里找到：这里

🎒 密集文本嵌入

from fastembed import TextEmbedding

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

# [
#   array([-0.1115,  0.0097,  0.0052,  0.0195, ...], dtype=float32),
#   array([-0.1019,  0.0635, -0.0332,  0.0522, ...], dtype=float32)
# ]

密集文本嵌入还可以通过不在支持模型列表中的模型进行扩展。

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

TextEmbedding.add_custom_model(
    model="intfloat/multilingual-e5-small",
    pooling=PoolingType.MEAN,
    normalization=True，
    sources=ModelSource(hf="intfloat/multilingual-e5-small")，  # 可以使用 `url` 从私有存储加载文件
    dim=384，
    model_file="onnx/model.onnx"，  # 可以用来加载已经支持的模型，并应用其他优化或量化，例如 onnx/model_O4.onnx
)
model = TextEmbedding(model_name="intfloat/multilingual-e5-small")
embeddings = list(model.embed(documents))

🔱 稀疏文本嵌入

• SPLADE++

from fastembed import SparseTextEmbedding

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

# [
#   SparseEmbedding(indices=[ 17, 123, 919, ... ], values=[0.71, 0.22, 0.39, ...]),
#   SparseEmbedding(indices=[ 38,  12,  91, ... ], values=[0.11, 0.22, 0.39, ...])
# ]

🦥 晚期交互模型（又称 ColBERT）

from fastembed import LateInteractionTextEmbedding

model = LateInteractionTextEmbedding(model_name="colbert-ir/colbertv2.0")
embeddings = list(model.embed(documents))

# [
#   array([
#       [-0.1115,  0.0097,  0.0052,  0.0195, ...],
#       [-0.1019,  0.0635, -0.0332,  0.0522, ...],
#   ]),
#   array([
#       [-0.9019,  0.0335, -0.0032,  0.0991, ...],
#       [-0.2115,  0.8097,  0.1052,  0.0195, ...],
#   ]),  
# ]

🖼️ 图像嵌入

from fastembed import ImageEmbedding

images = [
    "./path/to/image1.jpg",
    "./path/to/image2.jpg",
]

model = ImageEmbedding(model_name="Qdrant/clip-ViT-B-32-vision")
embeddings = list(model.embed(images))

# [
#   array([-0.1115,  0.0097,  0.0052,  0.0195, ...], dtype=float32),
#   array([-0.1019,  0.0635, -0.0332,  0.0522, ...], dtype=float32)
# ]

晚期交互多模态模型（ColPali）

from fastembed import LateInteractionMultimodalEmbedding

doc_images = [
    "./path/to/qdrant_pdf_doc_1_screenshot.jpg",
    "./path/to/colpali_pdf_doc_2_screenshot.jpg",
]

query = "What is Qdrant?"

model = LateInteractionMultimodalEmbedding(model_name="Qdrant/colpali-v1.3-fp16")
doc_images_embeddings = list(model.embed_image(doc_images))
# 形状 (2, 1030, 128)
# [array([[-0.03353882, -0.02090454, ..., -0.15576172, -0.07678223]], dtype=float32)]
query_embedding = model.embed_text(query)
# 形状 (1, 20, 128)
# [array([[-0.00218201,  0.14758301, ...,  -0.02207947,  0.16833496]], dtype=float32)]

🔄 重排序器

from fastembed.rerank.cross_encoder import TextCrossEncoder

query = "Who is maintaining Qdrant?"
documents: list[str] = [
    "This is built to be faster and lighter than other embedding libraries e.g. Transformers, Sentence-Transformers, etc.",
    "fastembed is supported by and maintained by Qdrant.",
]
encoder = TextCrossEncoder(model_name="Xenova/ms-marco-MiniLM-L-6-v2")
scores = list(encoder.rerank(query, documents))

# [-11.48061752319336, 5.472434997558594]

文本交叉编码器也可以通过不在支持模型列表中的模型进行扩展。

from fastembed.rerank.cross_encoder import TextCrossEncoder 
from fastembed.common.model_description import ModelSource

TextCrossEncoder.add_custom_model(
    model="Xenova/ms-marco-MiniLM-L-4-v2",
    model_file="onnx/model.onnx",
    sources=ModelSource(hf="Xenova/ms-marco-MiniLM-L-4-v2"),
)
model = TextCrossEncoder(model_name="Xenova/ms-marco-MiniLM-L-4-v2")
scores = list(model.rerank_pairs(
    [("什么是AI？", "人工智能是……"), ("什么是ML？", "机器学习是……"),]
))

⚡️ FastEmbed 在 GPU 上

FastEmbed 支持在 GPU 设备上运行。 这需要安装 fastembed-gpu 包。

pip install fastembed-gpu

请查看我们的示例以获取详细说明、CUDA 12.x 支持以及常见问题的故障排除方法。

from fastembed import TextEmbedding

embedding_model = TextEmbedding(
    model_name="BAAI/bge-small-en-v1.5", 
    providers=["CUDAExecutionProvider"]
)
print("模型 BAAI/bge-small-en-v1.5 已准备好在 GPU 上使用。")

与 Qdrant 的使用

在 Python 中使用 Qdrant 客户端安装：

pip install qdrant-client[fastembed]

或者

pip install qdrant-client[fastembed-gpu]

在 zsh 中，你可能需要使用引号：pip install 'qdrant-client[fastembed]'。

from qdrant_client import QdrantClient, models

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

model_name = "sentence-transformers/all-MiniLM-L6-v2"
payload = [
    {"document": "Qdrant 具有 Langchain 集成", "source": "Langchain 文档"},
    {"document": "Qdrant 同样具有 Llama Index 集成", "source": "LlamaIndex 文档"},
]
docs = [models.Document(text=data["document"], model=model_name) for data in payload]
ids = [42, 2]

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=models.Document(text="这是一份查询文档", model=model_name)
).points
print(search_result)

FastEmbed 快速上手指南

FastEmbed 是一个轻量级、高性能的 Python 嵌入生成库，专为服务器less 环境（如 AWS Lambda）和大规模数据处理设计。它基于 ONNX Runtime，无需 GPU 即可运行，且精度优于 OpenAI Ada-002。

环境准备

• 系统要求：支持 Linux、macOS 和 Windows。
• Python 版本：建议 Python 3.8 及以上。
• 前置依赖：无需额外安装 PyTorch 或 TensorFlow，库会自动处理 ONNX Runtime 依赖。
• 网络要求：首次运行时会自动下载模型文件（托管于 Hugging Face），请确保网络畅通。若国内访问受限，建议配置 Hugging Face 镜像环境变量：

  export HF_ENDPOINT=https://hf-mirror.com
  

安装步骤

使用 pip 进行安装。根据是否需要 GPU 加速选择以下命令之一：

1. CPU 版本（推荐，轻量通用）

pip install fastembed

2. GPU 版本（需 NVIDIA GPU 及 CUDA 环境）

pip install fastembed-gpu

基本使用

1. 生成稠密文本向量 (Dense Text Embeddings)

这是最常用的功能，默认使用 BAAI/bge-small-en-v1.5 模型。

from fastembed import TextEmbedding

# 示例文档列表
documents: list[str] = [
    "This is built to be faster and lighter than other embedding libraries e.g. Transformers, Sentence-Transformers, etc.",
    "fastembed is supported by and maintained by Qdrant.",
]

# 初始化模型（首次运行会自动下载模型）
embedding_model = TextEmbedding()

# 生成嵌入向量（返回的是生成器，可转为列表）
embeddings_list = list(embedding_model.embed(documents))

# 查看结果维度
print(f"Vector dimensions: {len(embeddings_list[0])}") 
# 输出：Vector dimensions: 384

2. 指定其他模型

你可以从支持的模型列表中指定任意模型：

from fastembed import TextEmbedding

# 指定特定模型
model = TextEmbedding(model_name="BAAI/bge-small-en-v1.5")
embeddings = list(model.embed(documents))

3. 高级功能示例

FastEmbed 还支持稀疏向量、多模态图像向量及重排序模型：

稀疏文本向量 (Sparse Text Embeddings)

from fastembed import SparseTextEmbedding

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

图像向量 (Image Embeddings)

from fastembed import ImageEmbedding

images = ["./path/to/image1.jpg", "./path/to/image2.jpg"]
model = ImageEmbedding(model_name="Qdrant/clip-ViT-B-32-vision")
image_embeddings = list(model.embed(images))

文本重排序 (Rerankers)

from fastembed.rerank.cross_encoder import TextCrossEncoder

query = "Who is maintaining Qdrant?"
encoder = TextCrossEncoder(model_name="Xenova/ms-marco-MiniLM-L-6-v2")
scores = list(encoder.rerank(query, documents))

4. GPU 加速使用

如果你安装了 fastembed-gpu，可以通过指定 providers 启用 GPU：

from fastembed import TextEmbedding

embedding_model = TextEmbedding(
    model_name="BAAI/bge-small-en-v1.5", 
    providers=["CUDAExecutionProvider"]
)
embeddings = list(embedding_model.embed(documents))