TEI_SERVICE说明文档.md 5.59 KB
Edit Raw Blame History


TEI 服务（Qwen3-Embedding-0.6B）说明

本文是本仓库 TEI（Text Embeddings Inference）专项运行手册。目标是让新同事在一台新机器上可以独立完成环境准备、部署、验收与排障。

1. 作用与边界

TEI 提供文本向量 HTTP 服务（默认 http://127.0.0.1:8080）。
本项目中文本 embedding 服务（默认 6005）把文本向量请求转发到 TEI。
TEI 仅负责文本向量，不负责图片向量（图片向量由 cnclip 提供）。

2. 代码与脚本入口

启动脚本：scripts/start_tei_service.sh
停止脚本：scripts/stop_tei_service.sh
统一编排：scripts/service_ctl.sh
文本 embedding 服务启动脚本（会校验 TEI 健康）：scripts/start_embedding_text_service.sh

3. 前置条件
3.1 必需软件

Docker（必须）
curl（用于健康检查与接口验收）

3.2 GPU 模式额外要求（推荐生产）

NVIDIA 驱动可用（nvidia-smi 可执行）
Docker 已配置 nvidia runtime（docker info 能看到 nvidia）


检查命令：
docker --version
docker info --format '{{json .Runtimes}}'
nvidia-smi

4. 安装与准备（可复现）
4.1 拉取代码并进入项目
cd /data/saas-search

4.2 （仅 GPU 模式）配置 Docker GPU runtime
如果 docker info 中没有 nvidia runtime，先按机器环境安装 nvidia-container-toolkit 并执行：
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker


再次确认：
docker info --format '{{json .Runtimes}}'

5. 启动方式
5.1 GPU 模式启动（默认）
TEI_DEVICE=cuda ./scripts/start_tei_service.sh


预期输出包含：


Image: ghcr.io/huggingface/text-embeddings-inference:turing-... 或 cuda-...（脚本按 GPU 架构自动选择）
Mode: cuda
TEI is ready and output probe passed: http://127.0.0.1:8080


说明：


T4（compute capability 7.5）会自动使用 turing-* 镜像。
Ampere 及更新架构（compute capability >= 8）会自动使用 cuda-* 镜像。

5.2 CPU 模式启动（显式）
TEI_DEVICE=cpu ./scripts/start_tei_service.sh


预期输出包含：


Image: ghcr.io/huggingface/text-embeddings-inference:1.9（非 cuda-）
Mode: cpu
TEI is ready and output probe passed: http://127.0.0.1:8080

5.3 停止服务
./scripts/stop_tei_service.sh

6. 验收步骤（必须做）
6.1 健康检查
curl -sS http://127.0.0.1:8080/health

6.2 向量接口检查
curl -sS http://127.0.0.1:8080/embed \
  -H "Content-Type: application/json" \
  -d '{"inputs":["Instruct: Given a shopping query, rank product titles by relevance\nQuery: What is the capital of China?"]}'


返回应为二维数组（每条输入对应一个向量）。

建议再连续请求一次，确认不是“首个请求正常，后续返回 null/NaN”。
6.3 与 embedding 服务联调
./scripts/start_embedding_text_service.sh

curl -sS -X POST "http://127.0.0.1:6005/embed/text" \
  -H "Content-Type: application/json" \
  -d '["芭比娃娃 儿童玩具"]'


返回应为 1024 维向量数组。
6.4 运行建议（单服务兼顾在线与索引）

在线 query（低延迟优先）：客户端建议 batch=1~4
索引构建（吞吐优先）：客户端建议 batch=15~20

7. 配置项（环境变量）
scripts/start_tei_service.sh 支持下列变量：


TEI_DEVICE：cuda/cpu，默认 cuda
TEI_CONTAINER_NAME：容器名，默认 saas-search-tei
TEI_PORT：宿主机端口，默认 8080
TEI_MODEL_ID：默认 Qwen/Qwen3-Embedding-0.6B
TEI_VERSION：镜像版本，默认 1.9
TEI_DTYPE：默认 float16
TEI_MAX_BATCH_TOKENS：默认 4096
TEI_MAX_CLIENT_BATCH_SIZE：默认 24
HF_CACHE_DIR：HF 缓存目录，默认 $HOME/.cache/huggingface
HF_TOKEN：可选，避免匿名限速
TEI_IMAGE：可选，手动指定镜像（通常不需要，建议使用脚本自动选择）

8. service_ctl 使用方式
启动全套（含 TEI）：
TEI_DEVICE=cuda ./scripts/service_ctl.sh start tei cnclip embedding embedding-image translator reranker


仅启动 TEI：
./scripts/service_ctl.sh start tei


查看状态：
./scripts/service_ctl.sh status tei


日志文件：logs/tei.log
9. 常见问题与排障
9.1 ERROR: TEI_DEVICE=cuda but Docker nvidia runtime is not configured

原因：Docker 未配置 NVIDIA runtime。
处理：按本文 4.2 配置后重启 Docker。

9.2 mode mismatch (need GPU/CPU)

原因：已有同名容器在另一种模式运行（比如当前是 GPU 容器，但你这次要求 CPU）。
处理：

./scripts/stop_tei_service.sh
TEI_DEVICE=cpu ./scripts/start_tei_service.sh   # 或改为 cuda

9.3 embedding 服务报 TEI 不可达

先检查 TEI：

curl -sS http://127.0.0.1:8080/health


再检查 embedding 侧地址：


TEI_BASE_URL
services.embedding.backends.tei.base_url（config/config.yaml）


9.4 /embed/text 第二次请求开始出现 NaN/null

常见原因：在 T4 这类 pre-Ampere GPU 上误用了 cuda-* TEI 镜像。
处理：

./scripts/start_tei_service.sh


该脚本会自动按 GPU 架构选择镜像，并在启动后做两次输出探测；若发现 null/NaN/Inf 会直接失败并清理错误容器。
10. 相关文档

开发总览：docs/QUICKSTART.md
体系规范：docs/DEVELOPER_GUIDE.md
embedding 模块：embeddings/README.md
CN-CLIP 专项：docs/CNCLIP_SERVICE说明文档.md