text-embeddings-inference — Hugging Face 出品的高性能向量服务

# Text Embeddings Inference 一个用于文本嵌入模型的极速推理解决方案。 在 NVIDIA A10 GPU 上，序列长度为 512 个 token 时，对 [BAAI/bge-base-en-v1.5](https://huggingface.co/BAAI/bge-base-en-v1.5) 模型的基准测试：

目录

• 快速开始
  • 支持的模型
  • Docker
  • Docker 镜像
  • API 文档
  • 使用私有或需认证的模型
  • 离线部署
  • 使用重排序模型
  • 使用序列分类模型
  • 使用 SPLADE 池化
  • 分布式追踪
  • gRPC
• 本地安装
  • Apple Silicon (Homebrew)
• Docker 构建
  • Apple M1/M2 Arm
• 示例

Text Embeddings Inference (TEI) 是一个用于部署和提供开源文本嵌入及序列分类模型的工具包。TEI 为最流行的模型（包括 FlagEmbedding、Ember、GTE 和 E5）实现了高性能的特征提取。TEI 具备以下特性：

• 无需模型图编译步骤
• 支持在 Mac 上使用 Metal 进行本地执行
• 小巧的 Docker 镜像和极快的启动时间，为真正的无服务器部署做好准备！
• 基于 Token 的动态批处理
• 使用 Flash Attention、Candle 和 cuBLASLt 优化的推理代码
• 支持 Safetensors 权重加载
• 支持 ONNX 权重加载
• 生产就绪（支持 Open Telemetry 分布式追踪、Prometheus 指标）

快速开始

支持的模型

文本嵌入

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

以下是一些当前支持的模型示例：

要探索性能最佳的文本嵌入模型列表，请访问 大规模文本嵌入基准 (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'

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

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

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

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

Options:
--model-id
Hugging Face 模型 ID，可以是任何在 https://huggingface.co/models 上标有 text-embeddings-inference 标签的模型（意味着它与 Text Embeddings Inference 兼容）。

      或者，指定的 ID 也可以是包含由 Transformers 或 Sentence Transformers 的 `save_pretrained(...)` 方法保存的必要模型文件的本地目录路径。

      [env: MODEL_ID=]

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

      [env: REVISION=]

  --tokenization-workers <TOKENIZATION_WORKERS>
      可选地控制用于负载分词、验证和截断的分词器工作线程数。默认为机器上的 CPU 核心数

      [env: TOKENIZATION_WORKERS=]

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

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

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

      [env: SERVED_MODEL_NAME=]

  --pooling <POOLING>
      可选地控制嵌入模型的池化方法。

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

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

      [env: POOLING=]

      Possible values:
      - cls:        选择 CLS token 作为嵌入
      - mean:       对模型嵌入应用平均池化
      - splade:     对模型嵌入应用 SPLADE（稀疏词法和扩展）。仅当加载的模型是 `ForMaskedLM` Transformer 模型时，此选项才可用
      - last-token: 选择最后一个 token 作为嵌入

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

      [env: MAX_CONCURRENT_REQUESTS=]
      [default: 512]

  --max-batch-tokens <MAX_BATCH_TOKENS>
      **重要** 这是允许最大限度利用可用硬件的一个关键控制参数。

      这表示一个批次内潜在 token 的总数。

      对于 `max_batch_tokens=1000`，您可以容纳 `10` 个 `total_tokens=100` 的查询，或者一个 `1000` 个 token 的查询。

      总的来说，这个数字应该尽可能大，直到模型受计算限制。由于实际的内存开销取决于模型实现，text-embeddings-inference 无法自动推断此数字。

      [env: MAX_BATCH_TOKENS=]
      [default: 16384]

  --max-batch-requests <MAX_BATCH_REQUESTS>
      可选地控制批次中单个请求的最大数量

      [env: MAX_BATCH_REQUESTS=]

  --max-client-batch-size <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 <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?"，因为提示词文本将在任何要编码的文本之前被添加。

      参数 '--default-prompt-name <DEFAULT_PROMPT_NAME>' 不能与 '--default-prompt <DEFAULT_PROMPT>' 一起使用

      [env: DEFAULT_PROMPT_NAME=]

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

      例如，如果 `default_prompt` 是 "query: "，那么句子 "What is the capital of France?" 将被编码为 "query: What is the capital of France?"，因为提示词文本将在任何要编码的文本之前被添加。

      参数 '--default-prompt <DEFAULT_PROMPT>' 不能与 '--default-prompt-name <DEFAULT_PROMPT_NAME>' 一起使用

      [env: DEFAULT_PROMPT=]

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

      一些嵌入模型需要一个额外的 `Dense` 模块，其中包含一个线性层和一个激活函数。默认情况下，这些 `Dense` 模块存储在 `2_Dense` 目录下，但可能存在提供不同 `Dense` 模块的情况，用于将池化后的嵌入转换为不同的维度，例如 `2_Dense_<dims>`，例如 https://huggingface.co/NovaSearch/stella_en_400M_v5。

      请注意，此参数是可选的，仅在运行 `candle` 后端时，当没有 `modules.json` 文件或当您想要覆盖单个 Dense 模块路径时才需要设置。

      [env: DENSE_PATH=]

  --hf-token <HF_TOKEN>
      您的 Hugging Face Hub 令牌。如果既未设置 `--hf-token` 也未设置 `HF_TOKEN` 环境变量，将从 `$HF_HOME/token` 路径读取令牌（如果存在）。这确保了可以访问私有或需认证的模型，并允许更宽松的速率限制

      [env: HF_TOKEN=]

  --hostname <HOSTNAME>
      监听的 IP 地址

      [env: HOSTNAME=]
      [default: 0.0.0.0]

  -p, --port <PORT>
      监听的端口

      [env: PORT=]
      [default: 3000]

  --uds-path <UDS_PATH>
      text-embeddings-inference 后端在内部通过 gRPC 通信时将使用的 Unix 套接字名称

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

  --huggingface-hub-cache <HUGGINGFACE_HUB_CACHE>
      huggingface hub 缓存的位置。用于覆盖位置，例如，如果您想提供一个挂载的磁盘

      [env: HUGGINGFACE_HUB_CACHE=]

  --payload-limit <PAYLOAD_LIMIT>
      负载大小限制（字节）

      默认为 2MB

      [env: PAYLOAD_LIMIT=]
      [default: 2000000]

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

      默认情况下，服务器响应每个请求。设置 API 密钥后，请求必须设置 Authorization