TEI：Hugging Face 开源的向量与重排序推理服务引擎｜部署与使用全指南

项目仓库： https://github.com/huggingface/text-embeddings-inference

开源协议：Hugging Face TEI License（基于 Apache 2.0，附模型服务相关条款）· 交付形态：Rust 二进制 text-embeddings-router + Docker 镜像 · 主要语言：Rust / CUDA · 部署方式：Docker 一键启动或本地编译 · 默认端口：容器内 80，主机通常映射 8080 · 官方文档：github.com/huggingface/text-embeddings-inference

1 项目简介

Text Embeddings Inference（简称 TEI）是 Hugging Face 开源的专用推理服务器，用 Rust 编写，针对文本嵌入（embedding）、重排序（rerank）、序列分类与稀疏向量（SPLADE）做了专门优化。它提供 OpenAPI 风格的 HTTP 接口与 gRPC 接口，启动后把 Hugging Face Hub 上对应标签的模型加载进 GPU / CPU / Metal，对外输出向量、打分或分类结果，适合作为 RAG 流水线、语义搜索、推荐系统的向量化后端。

非官方 / 商业产品边界声明：TEI 由 Hugging Face 团队维护，官方镜像发布在 ghcr.io/huggingface/text-embeddings-inference。文中出现的 Qwen、BERT、CamemBERT、XLM-RoBERTa、Jina、Nomic、GTE 等模型名称仅用于说明兼容范围，相关模型权重按各自许可证分发；使用者须自行确认模型许可与数据合规。

1.1 核心信息一览

1.2 适用场景

• RAG 流水线里需要把文档与查询批量转成向量，希望比通用 Transformers 推理更省显存、吞吐更高。
• 语义搜索、推荐系统、去重、聚类等任务的在线向量服务后端。
• 在 RAG 检索后加一层重排序（reranker），对召回结果做精排打分。
• 需要在 Apple Silicon（M1/M2/M3/M4）上用 Metal 加速本地嵌入模型做开发调试。
• 希望通过 gRPC 接口在高吞吐内网场景里替换 HTTP 接口。

1.3 能力边界（官方口径）

• 官方 README 自述支持 Nomic、BERT、CamemBERT、XLM-RoBERTa（绝对位置）、JinaBERT 等文本嵌入模型；序列分类与重排序支持 CamemBERT、RoBERTa、XLM-RoBERTa、GTE Sequence Classification 等。
• CUDA 计算能力低于 7.5 的 GPU（V100、Titan V、GTX 1000 系列等）不被支持；NVIDIA 驱动需兼容 CUDA 12.2 或更高。
• Turing 架构（T4、RTX 2000 系列）官方 README 提示 Flash Attention 默认关闭，因为存在精度问题。
• TEI 本身不提供模型训练、微调、数据集管理能力；模型权重从 Hugging Face Hub 下载或使用本地目录。

2 功能特性

2.1 多类推理接口

• /embed：把输入文本批量编码为稠密向量，支持单条与批量。
• /embed_sparse：对支持 SPLADE 池化的模型输出稀疏向量。
• /rerank：对查询与候选文档列表打相关度分数，用于 RAG 重排。
• /predict：序列分类模型输出类别概率。
• /health / /info / /docs：健康检查、模型信息、Swagger 交互式文档。

2.2 硬件后端

• NVIDIA GPU（Turing 75、Ampere 80/86、Ada Lovelace 89、Hopper 90、Blackwell 100/120/121）专用镜像。
• CPU：x86 上可用 ONNX Runtime（ort）或 Intel MKL（mkl）后端。
• Apple Silicon：通过 Homebrew 安装预编译二进制，使用 Metal 加速。

2.3 服务化能力

• 自动批处理（continuous batching）与动态分桶，提升 GPU 利用率。
• 可配置 --api-key 做 Bearer Token 鉴权。
• 可配置 --prometheus-port 暴露 Prometheus 指标。
• 支持分布式追踪（OpenTelemetry）。
• 支持 gRPC 接口（在镜像 tag 上加 -grpc）。
• 支持私有关门模型（通过 HF_TOKEN 环境变量）与离线（air-gapped）部署。

2.4 模型与池化控制

• 通过 --model-id 指定 Hugging Face Hub 模型 ID 或本地路径。
• 通过 --pooling、--dtype、--max-batch-tokens、--auto-truncate 等参数控制编码行为。
• 支持 --served-model-name 自定义 OpenAI 兼容端点对外暴露的模型名。

3 官方界面预览

TEI 是纯 API 服务，没有图形界面；启动后访问 http://127.0.0.1:8080/docs 可看到官方自动生成的 Swagger / OpenAPI 交互式文档，这是官方提供的唯一"界面"。本文不另行配图，避免使用第三方截图。

4 官方跳转链接汇总

• 仓库地址：https://github.com/huggingface/text-embeddings-inference
• 容器镜像：ghcr.io/huggingface/text-embeddings-inference
• Hugging Face Hub（带 text-embeddings-inference 标签的模型）：huggingface.co/models?library=text-embeddings-inference
• 在线 Swagger 文档（启动后）：http://<host>:8080/docs
• Issues：https://github.com/huggingface/text-embeddings-inference/issues
• NVIDIA Container Toolkit：docs.nvidia.com/datacenter/cloud-native/container-toolkit

5 前置要求与服务器配置

5.1 软件前提

• 操作系统：Linux（推荐 Ubuntu 22.04 / 24.04）为主；macOS Apple Silicon 可用 Homebrew 版本。
• 若使用 GPU：NVIDIA 驱动兼容 CUDA 12.2 或更高，已安装 NVIDIA Container Toolkit。
• 若使用本地 cargo 编译：先安装 Rust；Linux 需 `libssl-dev` 与 `gcc`。
• 若使用 GPU 本地编译：把 CUDA 工具链加入 PATH：export PATH=$PATH:/usr/local/cuda/bin。

5.2 硬件建议

• 文本嵌入模型通常比 LLM 小，单卡 T4 / RTX 3090 / A10G 即可承载百亿以下嵌入模型；重排序模型同理。
• 离线部署需要磁盘空间保存模型权重（GB 级），通过 -v $volume:/data 挂载持久化目录避免每次重新下载。
• CPU 模式适合开发调试与低并发场景，生产建议 GPU。

5.3 端口与资源

6 方式一：Docker 一键部署（推荐）

6.1 启动 GPU 版 TEI

model=Qwen/Qwen3-Embedding-0.6B
volume=$PWD/data   # 挂载持久化目录，避免每次重新下载权重

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

6.2 测试嵌入接口

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

6.3 测试重排序接口

curl 127.0.0.1:8080/rerank \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"query":"What is Deep Learning?",
       "inputs":["Deep learning is a subset of machine learning.",
                 "The cat sits on the mat."]}'

6.4 私有关门模型（可选）

token=hf_xxx
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 <gated-model-id>

6.5 离线（air-gapped）部署

# 在有网机器上准备好本地模型目录
git lfs install
git clone https://huggingface.co/<org>/<model> /data/<model>

# 离线启动，--model-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/<model>

远程访问注意事项：生产环境建议把 8080 放在反向代理后面，配合 HTTPS 与 --api-key 鉴权；不要把带 Bearer Token 的服务直接暴露在公网。

7 方式二：源码 / 本地运行

7.1 Apple Silicon（Homebrew，最快）

brew install text-embeddings-inference

model=Qwen/Qwen3-Embedding-0.6B
text-embeddings-router --model-id $model --port 8080

7.2 CPU 本地编译

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 克隆仓库
git clone https://github.com/huggingface/text-embeddings-inference.git
cd text-embeddings-inference

# x86 ONNX 后端（推荐）
cargo install --path router -F ort

# 或 x86 Intel MKL 后端
cargo install --path router -F mkl

# 或 M1/M2 Metal 后端
cargo install --path router -F metal

# Linux 额外依赖
sudo apt-get install libssl-dev gcc -y

# 启动
model=Qwen/Qwen3-Embedding-0.6B
text-embeddings-router --model-id $model --port 8080

7.3 GPU 本地编译

# 把 CUDA 工具链加入 PATH
export PATH=$PATH:/usr/local/cuda/bin

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

# Ampere / Ada / Hopper / Blackwell
cargo install --path router -F candle-cuda

# 启动
text-embeddings-router --model-id $model --port 8080

7.4 从源码构建 Docker 镜像

git submodule update --init

# 按目标 GPU 计算能力选择 runtime_compute_cap
# Turing=75, Ampere=80/86, Ada=89, Hopper=90, Blackwell=100/120/121
runtime_compute_cap=80
docker build -f Dockerfile . --build-arg RUNTIME_COMPUTE_CAP=$runtime_compute_cap

8 配置项说明

以下参数均来自 text-embeddings-router --help 官方输出口径。

9 常用运维命令

# 查看正在运行的 TEI 容器
docker ps | grep text-embeddings-inference

# 查看日志
docker logs -f <container_id>

# 停止
docker stop <container_id>

# 更新到最新镜像
docker pull ghcr.io/huggingface/text-embeddings-inference:cuda-1.9
# 然后重新 docker run

# 健康检查
curl http://127.0.0.1:8080/health

# 查看模型信息
curl http://127.0.0.1:8080/info

# GPU 占用
nvidia-smi

# 查看帮助
docker run --rm ghcr.io/huggingface/text-embeddings-inference:cuda-1.9 \
  text-embeddings-router --help

备份：模型权重通过 -v $volume:/data 持久化在宿主机目录，备份时直接拷贝该目录即可；配置参数写在启动命令或 systemd / compose 文件里，建议一并纳管。

10 常见故障排查

• docker run 报 GPU 不可用 / could not select device driver：未安装 NVIDIA Container Toolkit 或宿主机驱动版本过低；安装后 sudo systemctl restart docker。
• 启动报 CUDA 版本不兼容：驱动需兼容 CUDA 12.2+，nvidia-smi 查看驱动对应的 CUDA 版本，必要时升级驱动。
• V100 / GTX 1080 等老 GPU 启动失败：官方明确不支持计算能力 < 7.5 的 GPU，需换 T4 / RTX 2000 及以上。
• 下载模型失败 / 401：私有关门模型需设置 HF_TOKEN；网络问题可改用本地路径挂载（air-gapped 方式）。
• 输入超长被截断报错：默认 --auto-truncate true；若设为 false 且模型最大长度超过 --max-batch-tokens，服务会拒绝启动，需调大 --max-batch-tokens。
• Turing GPU 精度异常：Turing 镜像默认关闭 Flash Attention 是官方行为，不要自行开启。
• /embed 返回空向量：检查 --pooling 与模型实际支持的池化方式是否匹配；通过 /info 查看服务加载的模型配置。
• 想在高吞吐内网用 gRPC：在镜像 tag 上加 -grpc，然后用 grpcurl 调用，例如 grpcurl -d '{"inputs":"What is Deep Learning"}' -plaintext 0.0.0.0:8080 tei.v1.Embed/Embed。

11 风险与合规说明

• TEI 采用 Hugging Face TEI License（基于 Apache 2.0 并附加模型服务相关条款），商用前请阅读仓库 LICENSE 文件确认条款。
• 通过 HF_TOKEN 下载的私有关门模型受 Hugging Face 账号与模型许可双重约束，不要把 token 提交到公开仓库或日志。
• 嵌入与重排序输出的向量会被下游用于检索、推荐、分类等场景，相关数据隐私、跨境传输与内容合规责任由使用者承担。
• 本文所有命令、镜像 tag、端口、参数均来自官方 README；后续版本（示例 tag cuda-1.9）会随官方迭代更新，使用前请以官方仓库最新说明为准。