# 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`