ghcr.io/huggingface/text-embeddings-inference:latest-grpc

Text Embeddings Inference

一个用于文本嵌入模型的极速推理解决方案。

在 NVIDIA A10 上使用序列长度为 512 个 token 的 BAAI/bge-base-en-v1.5 基准测试：

目录

• 快速开始
• 支持的模型
• Docker
• Docker 镜像
• API 文档
• 使用私有或 gated 模型
• 离线部署
• 使用重排序模型
• 使用序列分类模型
• 使用 SPLADE 池化
• 分布式追踪
• gRPC
• 本地安装
• Apple Silicon（Homebrew）
• Docker 构建
• ARM64 / aarch64
• AMD Instinct GPU（ROCm）
• 示例

Text Embeddings Inference (TEI) 是一个用于部署和服务开源文本嵌入及序列分类模型的工具包。TEI 支持对最流行的模型进行高性能提取，包括 FlagEmbedding、Ember、GTE 和 E5。TEI 实现了许多功能，例如：

• 无需模型图编译步骤
• 支持 Metal 以在 Mac 上本地执行
• 体积小巧的 Docker 镜像和快速启动时间，为真正的无服务器架构做好准备！
• 基于 token 的动态批处理
• 使用 https://github.com/HazyResearch/flash-attention%E3%80%81https://github.com/huggingface/candle 和 cuBLASLt 优化的推理 transformers 代码
• https://github.com/huggingface/safetensors 权重加载
• https://github.com/onnx/onnx 权重加载
• 生产就绪（支持 Open Telemetry 分布式追踪、Prometheus 指标）

快速开始

支持的模型

文本嵌入

Text Embeddings Inference 当前支持具有绝对位置编码的 Nomic、BERT、CamemBERT、XLM-RoBERTa 模型，具有 Alibi 位置编码的 JinaBERT 模型，以及具有 Rope 位置编码的 Mistral、Alibaba GTE、Qwen2 模型，还有 MPNet、ModernBERT、Qwen3 和 Gemma3。

以下是当前支持的部分模型示例：

要查看性能最佳的文本嵌入模型列表，请访问 Massive Text Embedding Benchmark (MTEB) 排行榜。

序列分类和重排序

Text Embeddings Inference 当前支持具有绝对位置编码的 CamemBERT 和 XLM-RoBERTa 序列分类模型。

以下是当前支持的部分模型示例：

Docker

model=Qwen/Qwen3-Embedding-0.6B
volume=$PWD/data # 与 Docker 容器共享卷以避免每次运行都下载权重

docker run --gpus all -p 8080:80 -v $volume:/data --pull always ghcr.io/huggingface/text-embeddings-inference:cuda-1.9 --model-id $model

然后您可以像这样发送请求：

curl 127.0.0.1:8080/embed \
-X POST \
-d '{"inputs":"What is Deep Learning?"}' \
-H 'Content-Type: application/json'

[!NOTE] 要使用 GPU，您需要安装 NVIDIA Container Toolkit。您机器上的 NVIDIA 驱动程序需要与 CUDA 12.2 或更高版本兼容。

要查看服务模型的所有选项：

$ text-embeddings-router --help
Text Embedding Webserver

Usage: text-embeddings-router [OPTIONS] --model-id

选项：

--model-id
Hugging Face 模型 ID，可以是任何带有 text-embeddings-inference 标签的模型（表示其与 Text Embeddings Inference 兼容）。

也可以指定为本地目录路径，该目录包含通过 Transformers 或 Sentence Transformers 的 save_pretrained(...) 方法保存的必要模型文件。

[env: MODEL_ID=]

--revision
如果引用的是 Hub 上的模型，则指模型的实际修订版本。可以使用特定提交 ID 或分支，如 refs/pr/2

[env: REVISION=]

--tokenization-workers
可选，控制用于 payload 分词、验证和截断的分词器工作进程数。默认为机器上的 CPU 核心数

[env: TOKENIZATION_WORKERS=]

--dtype
强制模型使用的数据类型

[env: DTYPE=]
[possible values: float16, float32]

--served-model-name
正在提供服务的模型名称。如果未指定，默认为 --model-id。仅用于通过 HTTP 的 OpenAI 兼容端点

[env: SERVED_MODEL_NAME=]

--pooling
可选，控制嵌入模型的池化方法。

如果未设置 pooling，将从模型的 1_Pooling/config.json 配置中解析池化配置。

如果设置了 pooling，将覆盖模型的池化配置

[env: POOLING=]

可能的取值：

• cls：选择 CLS 令牌作为嵌入
• mean：对模型嵌入应用均值池化
• splade：对模型嵌入应用 SPLADE（稀疏词汇与扩展）。此选项仅在加载的模型是 ForMaskedLM Transformer 模型时可用
• last-token：选择最后一个令牌作为嵌入

--max-concurrent-requests
特定部署的最大并发请求数。设置较低的限制会拒绝客户端请求，而不是让它们等待过长时间，通常有助于正确处理背压

[env: MAX_CONCURRENT_REQUESTS=]
[default: 512]

--max-batch-tokens

[!IMPORTANT] 这是允许最大程度利用可用硬件的关键控制项。

表示一个批次内的潜在令牌总数。

例如，max_batch_tokens=1000 时，可以容纳 10 个总令牌数为 100 的查询，或 1 个令牌数为 1000 的查询。

总体而言，此数值应尽可能大，直到模型受计算限制。由于实际内存开销取决于模型实现，text-embeddings-inference 无法自动推断此数值。

[env: MAX_BATCH_TOKENS=]
[default: ***]

--max-batch-requests
可选，控制一个批次中的最大独立请求数

[env: MAX_BATCH_REQUESTS=]

--max-client-batch-size
控制客户端在单个请求中可发送的最大输入数

[env: MAX_CLIENT_BATCH_SIZE=]
[default: 32]

--auto-truncate
控制对超过模型最大支持大小的输入进行自动截断。默认为 true（启用截断）。设置为 false 可禁用截断；禁用时，如果模型的最大输入长度超过 --max-batch-tokens，服务器将启动失败并报错，而非静默截断序列。

gRPC 服务器不使用此选项

[env: AUTO_TRUNCATE=]

--default-prompt-name
默认用于编码的提示名称。如果未设置，则不应用任何提示。

必须是 sentence-transformers 配置中 prompts 字典的键。

例如，如果 default_prompt_name 为 "query"，且 prompts 为 {"query": "query: ", ...}，则句子 "What is the capital of France?" 将被编码为 "query: What is the capital of France?"，因为提示文本会 prepend 到任何待编码文本之前。

参数“--default-prompt-name”不能与“--default-prompt”一起使用

[env: DEFAULT_PROMPT_NAME=]

--default-prompt
默认用于编码的提示文本。如果未设置，则不应用任何提示。

例如，如果 default_prompt 为 "query: "，则句子 "What is the capital of France?" 将被编码为 "query: What is the capital of France?"，因为提示文本会 prepend 到任何待编码文本之前。

参数“--default-prompt”不能与“--default-prompt-name”一起使用

[env: DEFAULT_PROMPT=]

--dense-path
可选，定义某些嵌入模型所需的 Dense 模块路径。

部分嵌入模型需要额外的 Dense 模块，该模块包含单个线性层和激活函数。默认情况下，这些 Dense 模块存储在 2_Dense 目录下，但在某些情况下可能提供不同的 Dense 模块（例如用于将池化嵌入转换为不同维度），命名格式为 2_Dense_<dimension>，例如 [***]

注意，此参数为可选，仅在以下情况需要设置：没有 modules.json 文件时，或当使用 candle 后端运行且需要覆盖单个 Dense 模块路径时。

[env: DENSE_PATH=]

--hf-token
Hugging Face Hub 令牌。如果未设置 --hf-token 或 HF_TOKEN，将从 $HF_HOME/token 路径读取令牌（如果存在）。这确保能够访问私有或 gated 模型，并允许更宽松的速率限制

[env: HF_TOKEN=]

--hostname
监听的 IP 地址

[env: HOSTNAME=]
[default: 0.0.0.0]

-p, --port
监听的端口

[env: PORT=]
[default: 3000]

--uds-path
某些 text-embeddings-inference 后端通过 gRPC 进行内部通信时使用的 Unix 套接字名称

[env: UDS_PATH=]
[default: /tmp/text-embeddings-inference-server]

--huggingface-hub-cache
Hugging Face Hub 缓存的位置。用于覆盖默认位置（例如提供挂载磁盘时）

[env: HUGGINGFACE_HUB_CACHE=]

--payload-limit
Payload 大小限制（字节）

默认值为 2MB

[env: PAYLOAD_LIMIT=]
[default: 2000000]

--api-key
设置用于请求授权的 API 密钥。

默认情况下，服务器响应所有请求。设置 API 密钥后，请求必须设置 Authorization 头，并将 API 密钥作为 Bearer 令牌。

[env: API_KEY=]

--json-output
以 JSON 格式输出日志（对遥测有用）

[env: JSON_OUTPUT=]

--disable-spans
是否通过 spans 包含日志跟踪

[env: DISABLE_SPANS=]

--otlp-endpoint
OpenTelemetry 的 gRPC 端点。遥测数据通过 gRPC 以 OTLP 格式发送到此端点。例如 http://localhost:4317

[env: OTLP_ENDPOINT=]

--otlp-service-name
OpenTelemetry 的服务名称。例如 text-embeddings-inference.server

[env: OTLP_SERVICE_NAME=]
[default: text-embeddings-inference.server]

--prometheus-port
Prometheus 监听端口

[env: PROMETHEUS_PORT=]
[default: 9000]

--cors-allow-origin
gRPC 服务器不使用此选项

[env: CORS_ALLOW_ORIGIN=]

-h, --help
打印帮助信息（使用 '-h' 查看摘要）

-V, --version
打印版本号

使用私有或 gated 模型

您可以选择使用 HF_TOKEN 环境变量来配置 text-embeddings-inference 所使用的令牌。这使您能够访问受保护的资源。

例如：

1. 访问 [***]
2. 复制您的 CLI READ 令牌
3. 导出 HF_TOKEN=

或使用 Docker：

model=
volume=$PWD/data # 与 Docker 容器共享卷以避免每次运行都下载权重
token=

docker run --gpus all -e HF_TOKEN=$token -p 8080:80 -v $volume:/data --pull always ghcr.io/huggingface/text-embeddings-inference:cuda-1.9 --model-id $model

隔离环境部署

要在隔离环境（air-gapped）中部署 Text Embeddings Inference，需先下载权重，然后通过卷将其挂载到容器内。

例如：

#（可选）创建 `models` 目录
mkdir models
cd models

# 确保已安装 git-lfs（https://git-lfs.com）
git lfs install
git clone https://huggingface.co/Qwen/Qwen3-Embedding-0.6B

# 将 models 目录设置为卷路径
volume=$PWD

# 通过卷将 models 目录挂载到容器内，并设置模型 ID
docker run --gpus all -p 8080:80 -v $volume:/data --pull always ghcr.io/huggingface/text-embeddings-inference:cuda-1.9 --model-id /data/Qwen3-Embedding-0.6B

然后运行：

# 在 x86 架构上使用 ONNX 后端（推荐）
cargo install --path router -F ort
# 在 x86 架构上使用 Intel 后端
cargo install --path router -F mkl
# 在 M1 或 M2 芯片上
cargo install --path router -F metal

现在可以通过以下命令在 CPU 上启动 Text Embeddings Inference：

model=Qwen/Qwen3-Embedding-0.6B

text-embeddings-router --model-id $model --port 8080

[!NOTE] 在部分机器上，您可能还需要安装 OpenSSL 库和 gcc。在 Linux 机器上，运行：

> sudo apt-get install libssl-dev gcc -y
>

CUDA

不支持 CUDA 计算能力 < 7.5 的 GPU（V100、Titan V、GTX 1000 系列等）。

确保已安装 CUDA 和 NVIDIA 驱动程序。设备上的 NVIDIA 驱动程序需要与 CUDA 12.2 或更高版本兼容。您还需要将 NVIDIA 二进制文件添加到路径中：

export PATH=$PATH:/usr/local/cuda/bin

然后运行以下命令（可能需要一段时间，因为需要编译 CUDA 内核）：

# 在 Turing GPU 上（T4、RTX 2000 系列等）
cargo install --path router -F candle-cuda-turing

# 在 Ampere、Ada Lovelace、Hopper 和 Blackwell GPU 上
cargo install --path router -F candle-cuda

现在可以通过以下命令在 GPU 上启动 Text Embeddings Inference：

model=Qwen/Qwen3-Embedding-0.6B

text-embeddings-router --model-id $model --port 8080

Docker

您可以通过以下命令使用 Docker 构建 CPU 容器：

docker build -f Dockerfile .

要构建 CUDA 容器，您需要知道运行时将使用的 GPU 的计算能力，以便相应地构建镜像：

# 获取子模块依赖
git submodule update --init

# Turing 示例（T4、RTX 2000 系列等）
runtime_compute_cap=75

# Ampere 示例（A100 等）
runtime_compute_cap=80

# Ampere 示例（A10 等）
runtime_compute_cap=86

# Ada Lovelace 示例（RTX 4000 系列等）
runtime_compute_cap=89

# Hopper 示例（H100 等）
runtime_compute_cap=90

# Blackwell 示例（B200、GB200 等）
runtime_compute_cap=100

# Blackwell 示例（GeForce RTX 50X0、RTX PRO 6000 等）
runtime_compute_cap=120

# Blackwell GB10 示例（DGX Spark）
runtime_compute_cap=121

docker build . -f Dockerfile-cuda --build-arg CUDA_COMPUTE_CAP=$runtime_compute_cap

ARM64 / aarch64

仅 CPU（Apple Silicon、Ampere、Graviton）

对于没有 NVIDIA GPU 的 ARM64 主机，请使用 CPU Dockerfile。推理仅在 CPU 核心上运行（不通过 Docker 支持 Metal/MPS）。

docker build . -f Dockerfile-arm64 --platform=linux/arm64

ARM64 上的 CUDA（DGX Spark、Jetson）

对于配备 NVIDIA GPU 的 ARM64 主机，请使用适当的计算能力和 --platform linux/arm64 构建 Dockerfile-cuda：

# DGX Spark（GB10，sm_121）
docker build . -f Dockerfile-cuda \
--build-arg CUDA_COMPUTE_CAP=121 \
--platform linux/arm64

# 未来的 ARM64 + Blackwell 设备（sm_120）
docker build . -f Dockerfile-cuda \
--build-arg CUDA_COMPUTE_CAP=120 \
--platform linux/arm64

AMD Instinct GPU（ROCm）——实验性

TEI 通过 ROCm 对 AMD Instinct GPU（MI200、MI300 系列）提供实验性支持。您可以使用 rocm/pytorch:latest Docker 镜像或裸机 ROCm 安装。TEI 会在启动时自动检测 GPU。

有关完整的设置说明，请参阅 **https://huggingface.github.io/text-embeddings-inference/amd_gpu**%E3%80%82

示例

• 使用 TEI 设置推理端点
• https://github.com/plaggy/rag-containers