docs/TEI_SERVICE%E8%AF%B4%E6%98%8E%E6%96%87%E6%A1%A3.md

# 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`）
检查命令：
```bash
docker --version
docker info --format '{{json .Runtimes}}'
nvidia-smi
```
## 4. 安装与准备（可复现）
### 4.1 拉取代码并进入项目
```bash
cd /data/saas-search
```
### 4.2 （仅 GPU 模式）配置 Docker GPU runtime
如果 `docker info` 中没有 `nvidia` runtime，先按机器环境安装 `nvidia-container-toolkit` 并执行：
```bash
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```
再次确认：
```bash
docker info --format '{{json .Runtimes}}'
```
## 5. 启动方式
### 5.1 GPU 模式启动（默认）
```bash
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 模式启动（显式）
```bash
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 停止服务
```bash
./scripts/stop_tei_service.sh
```
## 6. 验收步骤（必须做）
### 6.1 健康检查
```bash
curl -sS http://127.0.0.1:8080/health
```
### 6.2 向量接口检查
```bash
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 服务联调
```bash
./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）：
```bash
TEI_DEVICE=cuda ./scripts/service_ctl.sh start tei cnclip embedding embedding-image translator reranker
```
仅启动 TEI：
```bash
./scripts/service_ctl.sh start tei
```
查看状态：
```bash
./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）。
- 处理：
```bash
./scripts/stop_tei_service.sh
TEI_DEVICE=cpu ./scripts/start_tei_service.sh   # 或改为 cuda
```
### 9.3 embedding 服务报 TEI 不可达
- 先检查 TEI：
```bash
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 镜像。
- 处理：
```bash
./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`