# 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_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 web search query, retrieve relevant passages that answer the query\nQuery: What is the capital of China?"]}'
  ```
  
  返回应为二维数组（每条输入对应一个向量）。
  

  建议再连续请求一次，确认不是“首个请求正常，后续返回 null/NaN”。
  

  ### 6.3 与 embedding 服务联调
  
  ```bash
  ./scripts/start_embedding_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 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`