bc089b43
 tangwang
refactor(reranker...
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
# 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_USE_GPU=1 ./scripts/start_tei_service.sh
```
预期输出包含：
- `Image: ghcr.io/huggingface/text-embeddings-inference:cuda-...`
- `Mode: gpu`
- `TEI is ready: http://127.0.0.1:8080`
### 5.2 CPU 模式启动（显式）
```bash
TEI_USE_GPU=0 ./scripts/start_tei_service.sh
```
预期输出包含：
- `Image: ghcr.io/huggingface/text-embeddings-inference:1.9`（非 `cuda-`）
- `Mode: cpu`
- `TEI is ready: 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?"]}'
```
返回应为二维数组（每条输入对应一个向量）。
### 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 维向量数组。
## 7. 配置项（环境变量）
`scripts/start_tei_service.sh` 支持下列变量：
- `TEI_USE_GPU`：`1/0`（或 `true/false`），默认 `1`
- `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`：默认 `2048`
- `TEI_MAX_CLIENT_BATCH_SIZE`：默认 `8`
- `HF_CACHE_DIR`：HF 缓存目录，默认 `$HOME/.cache/huggingface`
- `HF_TOKEN`：可选，避免匿名限速
## 8. service_ctl 使用方式
启动全套（含 TEI）：
```bash
START_EMBEDDING=1 START_TRANSLATOR=1 START_RERANKER=1 START_TEI=1 TEI_USE_GPU=1 ./scripts/service_ctl.sh start
```
仅启动 TEI：
```bash
./scripts/service_ctl.sh start tei
```
查看状态：
```bash
./scripts/service_ctl.sh status tei
```
## 9. 常见问题与排障
### 9.1 `ERROR: TEI_USE_GPU=1 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_USE_GPU=0 ./scripts/start_tei_service.sh # 或改为 1
```
### 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`）
## 10. 相关文档
- 开发总览：`docs/QUICKSTART.md`
- 体系规范：`docs/DEVELOPER_GUIDE.md`
- embedding 模块：`embeddings/README.md`
- CN-CLIP 专项：`docs/CNCLIP_SERVICE说明文档.md`
|