text-embeddings-inference

TEI 嵌入服务：用 Hugging Face Text Embeddings Inference 部署向量化与重排接口

补充说明

Text Embeddings Inference（TEI）是 Hugging Face 用 Rust 实现的嵌入/重排推理服务，支持 GPU 和 CPU、动态批处理、分词和长文本截断。它把 embedding 模型包装成 HTTP 服务，提供 /embed、/rerank、/info 等端点，适合给 RAG、语义搜索和推荐系统做在线向量化。

TEI 不是完整的 RAG 应用，也不做文档切分、向量库写入和检索编排；这些由 LangChain、LlamaIndex、RAGFlow 或业务服务负责。部署时要关注模型架构支持、最大输入长度、批处理 token 上限和 GPU 显存。

常用示例

# Docker 启动 TEI（GPU）
docker run --gpus all -p 8080:80 \
  -v /models:/data \
  ghcr.io/huggingface/text-embeddings-inference:latest \
  --model-id BAAI/bge-m3 --max-batch-tokens 16384

# 生成 embedding
curl http://localhost:8080/embed \
  -H 'Content-Type: application/json' \
  -d '{"inputs":["如何排查磁盘满","Kubernetes Pod 一直重启"]}'

# 重排：给候选文档打分
curl http://localhost:8080/rerank \
  -H 'Content-Type: application/json' \
  -d '{"query":"磁盘满怎么排查","texts":["df -h 看分区","Pod 日志排查"]}'

# 查看模型信息与最大输入长度
curl http://localhost:8080/info

部分版本提供 OpenAI 兼容的 /v1/embeddings 端点，接入 OpenAI SDK 前先用 /info 和实际请求确认字段、维度和错误格式。

易错点与排错

• 模型架构不支持：TEI 只支持特定 embedding/reranker 架构（如 BERT、XLM-R、GTE、BGE、E5 等）；新模型先查支持列表，不要假设所有 sentence-transformers 模型都能加载。
• 最大输入长度被截断：长文档会被静默截断，导致召回不完整；用 /info 看 max_input_length，或在客户端先切分。
• max-batch-tokens 设置不当：太小浪费吞吐，太大导致显存溢出或请求排队；按模型大小、序列长度和并发压测。
• 向量未归一化：不同模型/接口对 normalization 的处理不同；如果业务用余弦相似度，确认输出是否已归一化，避免重复计算或口径不一致。
• GPU 显存被长文本打满：单个超长请求可能占满显存；限制单条输入长度，并在网关层做请求大小限制。
• 把 TEI 当向量数据库：它只生成向量，不负责存储、索引、过滤和多租户；向量库用 Qdrant、Milvus、pgvector 等。
• 重排接口的 TopK 与截断：/rerank 返回的排序和分数要与业务阈值匹配；不要把重排分数直接当概率。
• 容器镜像与模型版本不匹配：升级镜像后重新验证维度和输出；维度变化会让已有向量库失效。

相关命令

• infinity — 另一款高吞吐嵌入/重排服务。
• reranker — 重排模型与 RAG 召回策略。
• transformers — 模型加载与本地推理。
• huggingface-cli — 下载模型与分词器。
• vllm — 生成式模型的 OpenAI 兼容服务。

参考链接

• TEI 官方文档
• TEI GitHub
• TEI 支持的模型

读完自测

合上页面，先回答，再展开对照。

1. TEI 负责 RAG 链路中的哪一段？不负责什么？
2. 长文档召回不完整，可能是什么原因？
3. /embed 和 /rerank 的输入输出有什么不同？