Anush008/fastembed-rs · 上手攻略

仓库：Anush008/fastembed-rs
链接：https://github.com/Anush008/fastembed-rs
分类：AI 嵌入 / Rust 库
作者：Tom
更新：2026-09-13

这是什么

fastembed-rs 是 Qdrant/fastembed（Python 版）的 Rust 实现，本地生成向量嵌入（vector embeddings）和重排序（reranking）的纯 Rust 库。无需网络请求、无 Python 依赖、无 Tokio 异步运行时，所有模型在本地通过 ONNX Runtime（via @pykeio/ort）执行。

⚠️ 存疑：当前版本 v6.1.0，文档标记为 5？以 crates.io 实际版本号为准（v6.1.0）。

解决什么问题

在 Rust 项目中需要本地文本嵌入或重排序时，主流方案是调用 Python 服务或依赖外部 API。fastembed-rs 让 Rust 程序直接加载 ONNX 模型、在进程内完成向量生成，消除网络延迟和外部依赖。

典型场景： - Rust 向量数据库：与 Qdrant 等 Rust 原生数据库集成，内嵌嵌入生成 - 边缘 AI：无网络环境下本地推理，数据不出机器 - 高性能管道：避免 Python → Rust IPC 开销，单进程完成全流程

快速安装

添加依赖

cargo add fastembed

或手动编辑 Cargo.toml：

[dependencies]
fastembed = "6"

基础特征

# 默认特征（推荐）
# 包含：ONNX Runtime (native-tls)、HuggingFace 模型下载、图像模型支持

# 可选 GPU 加速
fastembed = { version = "6", features = ["cuda"] }     # NVIDIA CUDA
fastembed = { version = "6", features = ["metal"] }    # Apple Silicon
fastembed = { version = "6", features = ["directml"] } # DirectML (Windows AMD/Intel)
fastembed = { version = "6", features = ["cudnn"] }   # cuDNN（需先装 CUDA）

⚠️ 注意：GPU 加速需要对应后端的系统库（CUDA Toolkit / Metal SDK / DirectML），请确保系统已配置。

核心用法

文本嵌入（Text Embedding）

use fastembed::{TextEmbedding, TextInitOptions, EmbeddingModel};

// 默认配置（使用 BAAI/bge-small-en-v1.5）
let mut model = TextEmbedding::try_new(Default::default())?;

// 或自定义选项
let mut model = TextEmbedding::try_new(
    TextInitOptions::new(EmbeddingModel::AllMiniLML6V2)
        .with_show_download_progress(true)
        .with_intra_threads(4),
)?;

// 需要 BGE 系列中文模型
// let mut model = TextEmbedding::try_new(
//     TextInitOptions::new(EmbeddingModel::BGESmallZH15)
// )?;

let documents = vec![
    "passage: Hello, World!",
    "query: Hello, World!",
    "passage: This is an example passage.",
    "fastembed-rs is licensed under Apache 2.0"
];

let embeddings = model.embed(documents, None)?;

println!("Embeddings count: {}", embeddings.len()); // -> 4
println!("Embedding dimension: {}", embeddings[0].len()); // -> 384

⚠️ 注意：文本前缀 passage: 和 query: 对 BGE 等模型有特殊意义——建议按官方格式传入以获得最佳效果。

稀疏嵌入（Sparse Embedding / SPLADE）

use fastembed::{SparseEmbedding, SparseInitOptions, SparseModel, SparseTextEmbedding};

// 默认模型：prithivida/Splade_PP_en_v1
let mut model = SparseTextEmbedding::try_new(Default::default())?;

// 或使用 BGE-M3（支持多语言）
let mut model = SparseTextEmbedding::try_new(
    SparseInitOptions::new(SparseModel::BGEM3)
        .with_show_download_progress(true),
)?;

let documents = vec![
    "passage: Hello, World!",
    "query: Hello, World!",
    "passage: This is an example passage.",
    "fastembed-rs is licensed under Apache 2.0"
];

let sparse_embeddings = model.embed(documents, None)?;

重排序（Reranking）

use fastembed::{RerankingModel, RerankInitOptions, Reranker};

let mut reranker = Reranker::try_new(Default::default())?;
// 默认模型：BAAI/bge-reranker-base

let query = "What is fastembed?";
let documents = vec![
    "fastembed is a Rust library for embeddings.",
    "The weather is nice today.",
    "Rust is a systems programming language.",
];

let scores = reranker.rerank(query, documents, None)?;

图像嵌入（需要 `image-models` 特征）

use fastembed::{ImageEmbedding, ImageInitOptions, ImageEmbeddingModel};

let mut model = ImageEmbedding::try_new(Default::default())?;
// 默认模型：Qdrant/clip-ViT-B-32-vision

let image_paths = vec!["path/to/image1.jpg", "path/to/image2.png"];
let image_embeddings = model.embed(image_paths, None)?;

支持的模型

文本嵌入（BGE 系列常用）

模型	维度	说明
`BAAI/bge-small-en-v1.5`	384	默认，轻量快速
`BAAI/bge-base-en-v1.5`	768	平衡性能
`BAAI/bge-large-en-v1.5`	1024	高精度
`BAAI/bge-small-zh-v1.5`	512	中文轻量
`BAAI/bge-large-zh-v1.5`	1024	中文高精度
`BAAI/bge-m3`	1024	多语言（含中文）/ 稀疏+稠密混合
`sentence-transformers/all-MiniLM-L6-v2`	384	经典小模型
`Alibaba-NLP/gte-large-en-v1.5`	1024	阿里中文/英文通用
`Qwen/Qwen3-Embedding-0.6B`	⚠️ 需 `qwen3` 特征	Qwen3 小型嵌入（candle 后端）
`Qwen/Qwen3-Embedding-8B`	⚠️ 需 `qwen3` 特征	Qwen3 大型嵌入（candle 后端）

重排序模型

模型	说明
`BAAI/bge-reranker-base`	默认
`BAAI/bge-reranker-v2-m3`	多语言
`jinaai/jina-reranker-v1-turbo-en`	英文高速

⚠️ 量化模型：部分模型提供量化版本（Q 后缀），如 EmbeddingModel::BGESmallENV15Q，可减少内存占用。

典型适用场景

Rust 向量搜索管道：本地生成嵌入后直接送入 Qdrant、RovDB 等 Rust 向量数据库
隐私敏感的 AI 管道：数据完全本地处理，无需发送到任何外部 API
边缘部署：嵌入式设备或无外网环境的 AI 推理
高性能 RAG：结合 Reranker 实现本地二阶段检索（embedding → rerank）

坑与注意

问题	原因	解决
模型下载慢	默认从 HuggingFace 下载，首次需联网	配置 `HF_HUB_TOKEN` 环境变量；或手动下载后指定路径
内存占用高	大模型（bge-large 等）	使用量化版本（Q 后缀）；或选 bge-small
编译慢	ort 依赖编译大量 C++	使用 `ort-download-binaries` 特征预编译 binary；耐心等待
`qwen3` 特征编译失败	candle 后端依赖问题	⚠️ qwen3 特征为可选，如非必需可跳过
Apple Silicon 性能差	默认可能走 CPU	启用 `metal` 特征

⚠️ 模型前缀格式：BGE 等模型对 query: / passage: 前缀敏感，不加前缀可能导致精度下降。

⚠️ 无 Tokio：默认同步使用，无需引入异步运行时。如需在 async 环境使用，可自行 spawn 阻塞线程。

与同类对比

库	语言	向量生成	GPU 支持	特点
fastembed-rs	Rust	✅ 本地	CUDA/Metal/DirectML	零外部依赖，本地推理
llama.rs	Rust	✅ 本地	CUDA	LLM 推理，侧重生成
transformers.rs	Rust	✅ 本地	有限	HuggingFace 模型支持更广
Candle	Rust	✅ 本地	CUDA/Metal	最灵活的 Rust ML 框架，但需要自行实现嵌入逻辑
Python fastembed	Python	✅ 本地	CUDA	生态更成熟，模型更多

fastembed-rs 的优势在于开箱即用的嵌入生成 + Rust 的零成本抽象 + 全平台 GPU 支持。

一句话推荐

在 Rust 项目里需要本地向量嵌入？cargo add fastembed 后三行代码出结果，无需 Python、不走 API、全平台 GPU 加速。