Blame view

docs/QUICKSTART.md 19.6 KB
bc54124c   tangwang   docs
1
  # 开发与配置指南
42e3aea6   tangwang   tidy
2
  
bc54124c   tangwang   docs
3
  新人入口:环境、服务、模块、请求示例、基础配置、Provider 架构、模块扩展规范,一文档搞定。
42e3aea6   tangwang   tidy
4
  
bc54124c   tangwang   docs
5
  **建议**:首次参与开发请先阅读 [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) 建立项目全貌与协作规范,再使用本文做环境与配置速查。
701ae503   tangwang   docs
6
  
bc54124c   tangwang   docs
7
8
9
10
  ---
  
  ## 为什么这样整合
  
0e66a315   tangwang   docs
11
  以下文档已删除,其核心内容已并入本文与 [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md) §7:原 `PROVIDER_ARCHITECTURE.md`、`MODULE_EXTENSION_SPEC.md`、`基础配置指南.md`。本文保留环境、服务、基础配置、Provider 与模块扩展的速查;协议与新增后端清单见 DEVELOPER_GUIDE §7。
bc54124c   tangwang   docs
12
13
14
15
16
17
18
19
  
  关于 `docs/Usage-Guide.md`:保留为**运行/运维手册**更清晰(日志、故障排查、多环境切换、建议索引运行细节),本文只保留开发常用且高频的信息,避免一个文档同时承担“开发规范 + 运维 runbook”导致冗长和混乱。
  
  ---
  
  ## 目录
  
  1. [快速上手](#1-快速上手)
2e3670ab   tangwang   index services
20
     - [1.1 环境准备](#11-环境准备) / [1.2 服务与端口](#12-服务与端口) / [1.3 常用 API](#13-常用-api-请求示例) / [1.4 系统要求](#14-系统要求) / [1.5 Python 运行环境](#15-python-运行环境详细) / [1.6 外部服务与 .env](#16-外部服务与-env含生产凭证) / [1.7 店匠数据源](#17-店匠数据源说明) / [1.8 相关脚本](#18-相关脚本) / [1.9 配置入口总览](#19-配置入口总览)
bc54124c   tangwang   docs
21
22
23
24
25
  2. [基础配置与搜索行为](#2-基础配置与搜索行为)
  3. [Provider 架构](#3-provider-架构)
  4. [模块扩展规范(Embedding / Rerank)](#4-模块扩展规范embedding--rerank)
  5. [验证、日志与常见排障入口](#5-验证日志与常见排障入口)
  6. [相关文档](#6-相关文档)
7299bae6   tangwang   tests
26
  7. [持续集成测试(最小可维护方案)](#7-持续集成测试最小可维护方案)
bc54124c   tangwang   docs
27
28
29
30
31
32
33
34
35
  
  ---
  
  ## 1. 快速上手
  
  ### 1.1 环境准备
  
  ```bash
  source activate.sh
2e3670ab   tangwang   index services
36
  # 首次创建环境:
bc54124c   tangwang   docs
37
  ./scripts/create_venv.sh
bc54124c   tangwang   docs
38
  
07cf5a93   tangwang   START_EMBEDDING=...
39
40
  # embedding 服务独立环境(推荐)
  ./scripts/setup_embedding_venv.sh
bc54124c   tangwang   docs
41
  
07cf5a93   tangwang   START_EMBEDDING=...
42
43
  # reranker 服务独立环境(Qwen3-vLLM)
  ./scripts/setup_reranker_venv.sh
42e3aea6   tangwang   tidy
44
  
07cf5a93   tangwang   START_EMBEDDING=...
45
46
  # CN-CLIP 独立环境
  ./scripts/setup_cnclip_venv.sh
42e3aea6   tangwang   tidy
47
48
  ```
  
07cf5a93   tangwang   START_EMBEDDING=...
49
50
  依赖:Python 3.8+、Elasticsearch 8.x、MySQL、Redis(可选,缓存用途)。
  
2e3670ab   tangwang   index services
51
  更详细的系统要求、Python 环境、外部服务与生产凭证见 [1.4–1.8](#14-系统要求)
42e3aea6   tangwang   tidy
52
  
bc54124c   tangwang   docs
53
  ### 1.2 服务与端口
42e3aea6   tangwang   tidy
54
55
56
  
  | 服务 | 端口 | 默认启动 | 说明 |
  |------|-----:|:--------:|------|
bc54124c   tangwang   docs
57
58
  | backend | 6002 | ✓ | 搜索 API(`/search/*`)+ 管理接口(`/admin/*`) |
  | indexer | 6004 | ✓ | 索引 API(`/indexer/*`) |
42e3aea6   tangwang   tidy
59
  | frontend | 6003 | ✓ | 调试 UI |
bc54124c   tangwang   docs
60
61
62
63
64
  | embedding | 6005 | - | 向量服务(`/embed/text`, `/embed/image`) |
  | translator | 6006 | - | 翻译服务(`/translate`) |
  | reranker | 6007 | - | 重排服务(`/rerank`) |
  
  启动与停止:
42e3aea6   tangwang   tidy
65
66
67
  
  ```bash
  ./run.sh
bc54124c   tangwang   docs
68
  # 启动全部能力
af7ee060   tangwang   service_ctl 简化为“显...
69
70
  # 追加可选能力服务(显式指定)
  TEI_DEVICE=cuda CNCLIP_DEVICE=cuda ./scripts/service_ctl.sh start tei cnclip embedding translator reranker
07cf5a93   tangwang   START_EMBEDDING=...
71
72
  # 说明:
  # - reranker 为 GPU 强制模式(资源不足会直接启动失败)
af7ee060   tangwang   service_ctl 简化为“显...
73
  # - TEI 默认使用 GPU;当 TEI_DEVICE=cuda 且 GPU 不可用时会直接失败(不会自动降级到 CPU)
07cf5a93   tangwang   START_EMBEDDING=...
74
  # - cnclip 默认使用 cuda;若显式配置为 cuda 且 GPU 不可用会直接失败(不会自动降级到 cpu)
bc54124c   tangwang   docs
75
  
42e3aea6   tangwang   tidy
76
77
78
79
  ./scripts/service_ctl.sh status
  ./scripts/stop.sh
  ```
  
af7ee060   tangwang   service_ctl 简化为“显...
80
81
82
  服务管理方式(入口职责、默认行为、全量拉起顺序)见:
  - `docs/Usage-Guide.md` -> `服务管理总览`
  
bc54124c   tangwang   docs
83
  ### 1.3 常用 API 请求示例
42e3aea6   tangwang   tidy
84
  
bc54124c   tangwang   docs
85
  #### 搜索 API(backend 6002)
42e3aea6   tangwang   tidy
86
87
88
89
90
91
92
93
94
95
96
97
98
99
  
  ```bash
  # 文本搜索
  curl -X POST http://localhost:6002/search/ \
    -H "Content-Type: application/json" \
    -H "X-Tenant-ID: 162" \
    -d '{"query": "玩具", "size": 10}'
  
  # 图片搜索
  curl -X POST http://localhost:6002/search/image \
    -H "Content-Type: application/json" \
    -H "X-Tenant-ID: 162" \
    -d '{"image_url": "https://example.com/img.jpg", "size": 10}'
  
bc54124c   tangwang   docs
100
101
102
103
104
105
  # Suggestion
  curl "http://localhost:6002/search/suggestions?q=玩&size=5" \
    -H "X-Tenant-ID: 162"
  
  # 健康与统计
  curl http://localhost:6002/admin/health
26b910bd   tangwang   refactor service ...
106
  curl http://localhost:6002/admin/stats -H "X-Tenant-ID: 162"
42e3aea6   tangwang   tidy
107
108
  ```
  
bc54124c   tangwang   docs
109
  API 文档:`http://localhost:6002/docs`
42e3aea6   tangwang   tidy
110
  
bc54124c   tangwang   docs
111
  #### 索引 API(indexer 6004)
42e3aea6   tangwang   tidy
112
113
114
115
116
  
  ```bash
  # 创建租户索引
  ./scripts/create_tenant_index.sh 162
  
bc54124c   tangwang   docs
117
  # 全量重建(更新/写入,不删除旧索引)
42e3aea6   tangwang   tidy
118
119
120
121
  curl -X POST http://localhost:6004/indexer/reindex \
    -H "Content-Type: application/json" \
    -d '{"tenant_id": "162", "batch_size": 500}'
  
bc54124c   tangwang   docs
122
123
124
125
126
127
  # 增量索引
  curl -X POST http://localhost:6004/indexer/index \
    -H "Content-Type: application/json" \
    -d '{"tenant_id": "162", "spu_ids": ["1001", "1002"]}'
  
  # 构建文档(不写 ES)
42e3aea6   tangwang   tidy
128
129
  curl -X POST http://localhost:6004/indexer/build-docs \
    -H "Content-Type: application/json" \
bc54124c   tangwang   docs
130
    -d '{"tenant_id":"162","items":[{"spu":{},"skus":[],"options":[]}]}'
42e3aea6   tangwang   tidy
131
132
  ```
  
bc54124c   tangwang   docs
133
134
135
  API 文档:`http://localhost:6004/docs`
  
  #### Embedding 服务(6005)
42e3aea6   tangwang   tidy
136
137
  
  ```bash
07cf5a93   tangwang   START_EMBEDDING=...
138
139
  # TEI(文本向量后端,默认)
  # GPU(需 nvidia-container-toolkit)
af7ee060   tangwang   service_ctl 简化为“显...
140
  TEI_DEVICE=cuda ./scripts/start_tei_service.sh
07cf5a93   tangwang   START_EMBEDDING=...
141
142
  
  # Embedding API(会校验 TEI /health)
42e3aea6   tangwang   tidy
143
144
  ./scripts/start_embedding_service.sh
  
42e3aea6   tangwang   tidy
145
146
147
148
  curl -X POST http://localhost:6005/embed/text \
    -H "Content-Type: application/json" \
    -d '["衣服", "Bohemian Maxi Dress"]'
  
42e3aea6   tangwang   tidy
149
150
151
152
153
  curl -X POST http://localhost:6005/embed/image \
    -H "Content-Type: application/json" \
    -d '["https://example.com/img.jpg"]'
  ```
  
07cf5a93   tangwang   START_EMBEDDING=...
154
155
  说明:
  - TEI 默认镜像按 `TEI_VERSION` 组装:`cuda-<version>`(默认 `1.9`)。
af7ee060   tangwang   service_ctl 简化为“显...
156
  - `TEI_DEVICE=cuda` 时会严格校验 Docker GPU runtime;未配置会直接报错退出。
07cf5a93   tangwang   START_EMBEDDING=...
157
158
  - `/embed/image` 依赖 `cnclip`(`grpc://127.0.0.1:51000`),未启动时 embedding 服务会启动失败。
  
bc54124c   tangwang   docs
159
  #### Translator 服务(6006)
42e3aea6   tangwang   tidy
160
161
162
163
164
165
  
  ```bash
  ./scripts/start_translator.sh
  
  curl -X POST http://localhost:6006/translate \
    -H "Content-Type: application/json" \
bc54124c   tangwang   docs
166
    -d '{"text":"商品名称","target_lang":"en","source_lang":"zh"}'
42e3aea6   tangwang   tidy
167
168
  ```
  
bc54124c   tangwang   docs
169
  #### Reranker 服务(6007)
42e3aea6   tangwang   tidy
170
171
  
  ```bash
07cf5a93   tangwang   START_EMBEDDING=...
172
  # 默认后端 qwen3_vllm(Qwen3-Reranker-0.6B)
42e3aea6   tangwang   tidy
173
174
175
176
  ./scripts/start_reranker.sh
  
  curl -X POST http://localhost:6007/rerank \
    -H "Content-Type: application/json" \
bc54124c   tangwang   docs
177
178
179
    -d '{"query":"wireless mouse","docs":["logitech mx master","usb cable"]}'
  ```
  
2e3670ab   tangwang   index services
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
  ### 1.4 系统要求
  
  - **操作系统**:Linux(推荐 Ubuntu 18.04+)
  - **Python**:3.10(由 venv 提供)
  - **内存**:建议 8GB+(含模型与 ES)
  - **磁盘**:10GB+(含模型与索引)
  
  ### 1.5 Python 运行环境(详细)
  
  项目根目录的 `activate.sh` 激活 **`.venv`** 并加载当前目录 `.env`
  
  ```bash
  cd /data/saas-search
  ./scripts/create_venv.sh
  source activate.sh
  ```
  
07cf5a93   tangwang   START_EMBEDDING=...
197
  主程序 `.venv` 与模型服务环境隔离:
2e3670ab   tangwang   index services
198
  
07cf5a93   tangwang   START_EMBEDDING=...
199
200
201
202
203
  - 主程序:`.venv`(`./scripts/create_venv.sh`
  - embedding 服务:`.venv-embedding`(`./scripts/setup_embedding_venv.sh`
  - reranker 服务:`.venv-reranker`(`./scripts/setup_reranker_venv.sh`
  - cnclip:`.venv-cnclip`(`./scripts/setup_cnclip_venv.sh`
  - TEI:Docker 容器(`./scripts/start_tei_service.sh`
2e3670ab   tangwang   index services
204
205
206
207
208
209
210
211
212
213
214
  
  ### 1.6 外部服务与 .env(含生产凭证)
  
  以下为 **AI 生产环境** 统一使用的地址与凭证(Redis / ES / MySQL 均以此为准)。本地开发可将 `DB_HOST`/`ES_HOST`/`REDIS_HOST` 改为 `localhost`(服务在本机时)。
  
  | 服务 | 地址(生产) | 端口 | 说明 |
  |------|--------------|------|------|
  | **MySQL** | 10.200.16.14 / localhost | 3316 | 店匠 SPU/SKU 数据 |
  | **Redis** | 10.200.16.14 / localhost | 6479 | Embedding/翻译缓存 |
  | **Elasticsearch** | 10.200.16.14 / localhost | 9200 | 搜索索引 |
  
07cf5a93   tangwang   START_EMBEDDING=...
215
  **MySQL**(AI 生产推荐使用 root,3 个用户均可远程登录):
2e3670ab   tangwang   index services
216
  
07cf5a93   tangwang   START_EMBEDDING=...
217
218
219
220
221
  | 用户 | 密码 | 说明 |
  |------|------|------|
  | root | qY8tgodLoA&KT#yQ | AI 生产推荐 |
  | saas | 6dlpco6dVGuqzt^l | 业务用户 |
  | sa | C#HU!GPps7ck8tsM | 备用 |
2e3670ab   tangwang   index services
222
223
224
225
226
227
228
229
230
231
232
  
  创建远程用户(如尚未创建):
  
  ```sql
  mysql -uroot -p'qY8tgodLoA&KT#yQ'
  CREATE USER 'saas'@'%' IDENTIFIED BY '6dlpco6dVGuqzt^l';
  CREATE USER 'sa'@'%' IDENTIFIED BY 'C#HU!GPps7ck8tsM';
  ```
  
  **Redis**
  
07cf5a93   tangwang   START_EMBEDDING=...
233
  - 地址:`10.200.16.14:6479`
2e3670ab   tangwang   index services
234
  - 密码:`dxEkegEZ@C5SXWKv`
07cf5a93   tangwang   START_EMBEDDING=...
235
  - 远程登录示例:`redis-cli -h 10.200.16.14 -p 6479 -a 'dxEkegEZ@C5SXWKv' --no-auth-warning`
2e3670ab   tangwang   index services
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
  
  **Elasticsearch**
  
  - 用户名/密码:`saas` / `4hOaLaf41y2VuI8y`
  - 访问示例:
  
  ```bash
  curl -u 'saas:4hOaLaf41y2VuI8y' \
    -X GET 'http://localhost:9200/search_products_tenant_111/_search?pretty' \
    -H 'Content-Type: application/json' \
    -d '{
      "size": 11,
      "_source": ["title"],
      "query": {
        "bool": {
          "filter": [
            { "term": {"spu_id" : 206150} }
          ]
        }
      }
    }'
  ```
  
02c40701   tangwang   frontend proxy se...
259
260
  > 注意(Kibana 运维):应用侧 `.env` 的 `ES_USERNAME/ES_PASSWORD` 仅用于业务服务访问 ES;Kibana 不应复用该账号。Kibana 推荐在 `/etc/kibana/kibana.yml` 使用 `elasticsearch.serviceAccountToken`,否则在 `.kibana_*` 受限索引迁移阶段可能出现 `security_exception` 并导致 5601 长时间无响应。
  
c7e80cc2   tangwang   新的 .env 管理机制如下:
261
262
263
264
265
266
267
  在项目根目录创建 `.env`
  
  ```bash
  ./scripts/init_env.sh   # 从 .env.example 复制(若 .env 不存在)
  ```
  
  然后按环境修改 `.env`**含特殊字符(#、$、&、空格)的密码需加引号**,例如:
2e3670ab   tangwang   index services
268
269
  
  ```env
07cf5a93   tangwang   START_EMBEDDING=...
270
  # MySQL(AI 生产 10.200.16.14:3316,推荐 root)
2e3670ab   tangwang   index services
271
272
273
  DB_HOST=10.200.16.14
  DB_PORT=3316
  DB_DATABASE=saas
07cf5a93   tangwang   START_EMBEDDING=...
274
  DB_USERNAME=root
c7e80cc2   tangwang   新的 .env 管理机制如下:
275
  DB_PASSWORD="qY8tgodLoA&KT#yQ"
2e3670ab   tangwang   index services
276
277
278
279
  
  # Elasticsearch
  ES_HOST=http://10.200.16.14:9200
  ES_USERNAME=saas
c7e80cc2   tangwang   新的 .env 管理机制如下:
280
  ES_PASSWORD="4hOaLaf41y2VuI8y"
2e3670ab   tangwang   index services
281
282
283
284
  
  # Redis(可选)
  REDIS_HOST=10.200.16.14
  REDIS_PORT=6479
c7e80cc2   tangwang   新的 .env 管理机制如下:
285
  REDIS_PASSWORD="dxEkegEZ@C5SXWKv"
2e3670ab   tangwang   index services
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
  
  # DeepL 翻译(按需)
  DEEPL_AUTH_KEY=your-key
  
  # API
  API_HOST=0.0.0.0
  API_PORT=6002
  ```
  
  > 生产环境请妥善保管凭证;本地/测试可改用上述值或自建实例。
  
  ### 1.7 店匠数据源说明
  
  saas-search 以 MySQL 中的店匠标准表为权威数据源:
  
  - `shoplazza_product_spu`:SPU 商品主表
  - `shoplazza_product_sku`:SKU 变体表
  
  **shoplazza_product_sku 字段节选**`id`, `spu_id`, `shop_id`, `title`, `sku`, `price`, `compare_at_price`, `option1/2/3`, `inventory_quantity`, `image_src`, `tenant_id`, `create_time`, `update_time`, `deleted` 等。完整字段与 ES 对应关系见 `INDEX_FIELDS_DOCUMENTATION.md`(若有)。
  
  ### 1.8 相关脚本
  
  - **`activate.sh`**(项目根目录):激活 Python 环境并加载 `.env`,日常开发/部署以本脚本为准。
07cf5a93   tangwang   START_EMBEDDING=...
309
310
311
312
  - `scripts/create_venv.sh`:创建主程序 venv(`.venv`
  - `scripts/setup_embedding_venv.sh`:创建 embedding 服务 venv(`.venv-embedding`
  - `scripts/setup_reranker_venv.sh`:创建 reranker 服务 venv(`.venv-reranker`
  - `scripts/start_tei_service.sh`:启动 TEI 容器(文本向量后端)
2e3670ab   tangwang   index services
313
314
315
316
317
318
319
320
  - `scripts/mock_data.sh`:生成 Tenant1 Mock + Tenant2 CSV 并导入 MySQL
  - `scripts/create_tenant_index.sh <tenant_id>`:创建租户 ES 索引结构
  - `POST /indexer/reindex`:从 MySQL 全量导入到 ES
  - `run.sh` / `scripts/stop.sh`:服务启停;`scripts/service_ctl.sh`:start/stop/restart/status
  
  更多脚本与验证命令见 `docs/Usage-Guide.md`
  
  ### 1.9 配置入口总览
bc54124c   tangwang   docs
321
322
323
324
325
326
  
  - **搜索行为配置**`config/config.yaml`
  - **索引结构定义**`mappings/search_products.json`
  - **provider/服务配置**`config/config.yaml` 的 `services`
  - **环境变量**`.env`
  
0e66a315   tangwang   docs
327
  ---·
bc54124c   tangwang   docs
328
329
330
331
332
333
334
  
  ## 2. 基础配置与搜索行为
  
  ### 2.1 总体原则
  
  - **统一索引结构**:所有租户使用同一套 mapping(按租户数据分索引名 + 文档内 `tenant_id` 隔离)
  - **SPU 级索引**:每个文档是一个 SPU,包含嵌套 `skus`、`specifications`
bd96cead   tangwang   1. 动态多语言字段与统一策略配置
335
  - **配置文件驱动**:搜索权重、动态多语言字段、重排融合、provider 全在 `config/config.yaml`,不再以“硬编码配置”为主
bc54124c   tangwang   docs
336
337
338
339
340
341
342
343
  
  ### 2.2 索引结构(Mapping)
  
  文件:`mappings/search_products.json`
  
  核心字段可分为:
  
  - 标识字段:`tenant_id`, `spu_id`
bd96cead   tangwang   1. 动态多语言字段与统一策略配置
344
  - 多语言文本:`title.<lang>`, `brief.<lang>`, `description.<lang>`, `vendor.<lang>`, `category_path.<lang>`, `category_name_text.<lang>`
bc54124c   tangwang   docs
345
346
347
348
349
350
351
  - 类目过滤:`category1_name`, `category2_name`, `category3_name`
  - 规格/变体:`specifications`(nested)、`skus`(nested)
  - 价格库存:`min_price`, `max_price`, `total_inventory`
  - 向量:`title_embedding`(dense vector)、`image_embedding`(nested)
  
  ### 2.3 查询、权重、排序(`config/config.yaml`)
  
bd96cead   tangwang   1. 动态多语言字段与统一策略配置
352
353
  - `field_boosts`:字段权重(统一按字段基名配置,运行时按 `.{lang}` 动态组装)
  - `query_config.search_fields`:动态多语言检索字段(multilingual/shared/core)
bcada818   tangwang   last
354
  - `query_config.text_query_strategy`:文本召回策略参数(minimum_should_match、翻译boost、翻译失败原文兜底boost等)
bc54124c   tangwang   docs
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
  - `query_config`:语言、embedding 开关、source_fields、knn_boost、翻译提示词等
  - `ranking.expression`:融合表达式(例如 `bm25() + 0.25*text_embedding_relevance()`
  - `function_score`:ES 层加权函数
  - `rerank`:重排窗口、超时、ES/AI 融合权重
  
  ### 2.4 分面与返回字段
  
  - 分面字段通常包括:`category1_name`、`category2_name`、`category3_name`、`specifications.*`
  - `query_config.source_fields` 控制返回字段(`null`=全部,`[]`=不返回 source,列表=指定字段)
  - 多语言返回遵循请求 language 与字段回退策略
  
  ### 2.5 修改配置时怎么做
  
  | 修改项 | 操作 |
  |--------|------|
  | 索引结构(mapping) | 修改 `mappings/search_products.json` → `./scripts/create_tenant_index.sh <tenant_id>` → 重新导入 |
bd96cead   tangwang   1. 动态多语言字段与统一策略配置
371
  | 搜索字段/权重/排序/重排 | 修改 `config/config.yaml` 对应块 |
bc54124c   tangwang   docs
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
  | provider 与服务 URL | 修改 `config/config.yaml` 的 `services` 块,或用环境变量覆盖 |
  
  ---
  
  ## 3. Provider 架构
  
  目标:调用方稳定、配置可切换、单一配置源。
  
  ### 3.1 当前代码结构
  
  - 模块:`providers/`
  - 工厂:`create_translation_provider()`、`create_embedding_provider()`、`create_rerank_provider()`
  - 配置解析:`config/services_config.py`
  
  | 能力 | Provider 实现 | 调用方 |
  |------|---------------|--------|
  | translation | `providers/translation.py`(direct/http) | `query/query_parser.py`、索引链路 |
  | embedding | `providers/embedding.py`(http) | 文本/图像编码调用 |
  | rerank | `providers/rerank.py`(http) | `search/rerank_client.py` |
  
  ### 3.2 配置与覆盖
  
  统一在 `config/config.yaml`
  
  ```yaml
  services:
    translation:
      provider: "direct"
      providers:
        direct: { model: "qwen" }
        http: { base_url: "http://127.0.0.1:6006", model: "qwen", timeout_sec: 10.0 }
    embedding:
      provider: "http"
07cf5a93   tangwang   START_EMBEDDING=...
405
      backend: "tei"
bc54124c   tangwang   docs
406
407
      providers:
        http: { base_url: "http://127.0.0.1:6005" }
07cf5a93   tangwang   START_EMBEDDING=...
408
409
      backends:
        tei: { base_url: "http://127.0.0.1:8080", timeout_sec: 60, model_id: "Qwen/Qwen3-Embedding-0.6B" }
bc54124c   tangwang   docs
410
411
    rerank:
      provider: "http"
07cf5a93   tangwang   START_EMBEDDING=...
412
      backend: "qwen3_vllm"
bc54124c   tangwang   docs
413
414
415
416
417
418
419
420
421
      providers:
        http: { base_url: "http://127.0.0.1:6007", service_url: "http://127.0.0.1:6007/rerank" }
  ```
  
  环境变量覆盖(优先级更高):
  
  - `TRANSLATION_PROVIDER`
  - `TRANSLATION_SERVICE_URL`
  - `EMBEDDING_SERVICE_URL`
07cf5a93   tangwang   START_EMBEDDING=...
422
423
  - `EMBEDDING_BACKEND`
  - `TEI_BASE_URL`
bc54124c   tangwang   docs
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
  - `RERANKER_SERVICE_URL`
  - `RERANK_BACKEND`(服务内后端)
  
  ### 3.3 新增 provider 的最小步骤
  
  1.`providers/<capability>.py` 实现 provider 类
  2.`create_*_provider()` 注册
  3.`config/config.yaml` 的 `services.<capability>.providers` 新增配置
  
  ---
  
  ## 4. 模块扩展规范(Embedding / Rerank)
  
  这里重点区分两层:
  
  - **Provider 层(调用方式)**:调用方如何访问能力(http/direct)
07cf5a93   tangwang   START_EMBEDDING=...
440
  - **Backend 层(推理实现)**:服务进程内部具体模型实现(tei / local_st / qwen3_vllm / ...)
bc54124c   tangwang   docs
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
  
  ### 4.1 Rerank(重排)扩展
  
  调用链:
  
  `search/rerank_client.py` -> `create_rerank_provider()` -> `HttpRerankProvider` -> `POST /rerank`
  
  服务实现:
  
  - `reranker/server.py`
  - `reranker/backends/__init__.py`(工厂)
  - `reranker/backends/bge.py`
  - `reranker/backends/qwen3_vllm.py`
  
  后端协议(服务内):
  
  - 实现 `score_with_meta(query, docs, normalize) -> (scores, meta)`
  - 返回 `scores` 与输入 `docs` 等长且顺序一致
  
  配置位置:
  
  `config/config.yaml` -> `services.rerank.backend` + `services.rerank.backends.<name>`
  
  ### 4.2 Embedding(向量化)扩展
  
  调用链:
  
  `create_embedding_provider()` -> `POST /embed/text` / `POST /embed/image`
  
  服务实现:
  
  - `embeddings/server.py`(文本和图像可独立加载)
07cf5a93   tangwang   START_EMBEDDING=...
473
  - 文本后端默认 `TEI`(Qwen3-Embedding-0.6B)
bc54124c   tangwang   docs
474
475
476
477
478
479
480
481
  - 图像后端支持本地 CLIP 或 clip-as-service
  
  扩展建议:
  
  - 文本后端统一提供批量编码能力(与输入索引对齐)
  - 图像后端实现 `ImageEncoderProtocol`(`encode_image_urls`
  - 如后续后端增多,建议与 rerank 一样在 `services.embedding.backend(s)` 统一配置
  
950a640e   tangwang   embeddings
482
483
  选型建议(Qwen3-Embedding-0.6B):
  
07cf5a93   tangwang   START_EMBEDDING=...
484
485
  - 当前仓库默认:`TEI`(Text Embeddings Inference)
  - 生产高并发优先:`TEI` 通常比 vLLM 更贴合 embedding-only 场景
950a640e   tangwang   embeddings
486
487
  - `vLLM` 更适合生成式/重排混合场景;若仅做文本 embedding,通常不作为首选
  
bc54124c   tangwang   docs
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
  ### 4.3 新增后端检查清单(以 `qwen3_vllm` 为例)
  
  1. 实现后端协议(服务内)
  2. 在后端工厂注册(如 `get_rerank_backend`
  3. 增加 `config/config.yaml` 对应 backend 配置
  4. 提供健康检查中的 backend/model 可观测信息
  5. 保持外部 HTTP 契约不变,调用方无需改造
  
  ---
  
  ## 5. 验证、日志与常见排障入口
  
  ### 5.1 快速健康检查
  
  ```bash
  curl http://localhost:6002/health
  curl http://localhost:6002/admin/health
  curl http://localhost:6004/health
  curl http://localhost:6005/health
  curl http://localhost:6006/health
  curl http://localhost:6007/health
  ```
  
  ### 5.2 常看日志
  
28e57bb1   tangwang   日志体系优化
513
514
515
516
517
  - `logs/<service>-YYYY-MM-DD.log`(`service_ctl.sh` 按天写入的真实文件)
  - `logs/<service>.log`(指向当天文件的软链,推荐 `tail -F`
  - `logs/api.log`(backend 进程内日志,按天轮转)
  - `logs/backend_verbose.log`(backend 大对象详细日志,按天轮转)
  - `logs/indexer.log`(索引结构化 JSON 日志,按天轮转)
bc54124c   tangwang   docs
518
519
520
521
522
523
524
525
  
  ### 5.3 常用排障命令
  
  ```bash
  ./scripts/service_ctl.sh status
  curl http://localhost:9200
  lsof -i :6002
  lsof -i :6004
42e3aea6   tangwang   tidy
526
527
  ```
  
bc54124c   tangwang   docs
528
  更完整的运行排障(多环境切换、Suggestion 构建、FAQ)见 `docs/Usage-Guide.md`
42e3aea6   tangwang   tidy
529
  
bc54124c   tangwang   docs
530
  ---
42e3aea6   tangwang   tidy
531
  
bc54124c   tangwang   docs
532
  ## 6. 相关文档
42e3aea6   tangwang   tidy
533
534
535
  
  | 文档 | 用途 |
  |------|------|
bc54124c   tangwang   docs
536
537
  | `docs/DEVELOPER_GUIDE.md` | 项目全貌、规范、协作方式 |
  | `docs/Usage-Guide.md` | 运行运维手册:日志、多环境、故障排查、Suggestion 运维 |
42e3aea6   tangwang   tidy
538
539
  | `docs/搜索API速查表.md` | 搜索 API 参数速查 |
  | `docs/搜索API对接指南.md` | 搜索 API 完整说明 |
42e3aea6   tangwang   tidy
540
  | `indexer/README.md` | 索引模块职责与接口 |
bc54124c   tangwang   docs
541
  | `embeddings/README.md` | 向量化服务说明 |
bc089b43   tangwang   refactor(reranker...
542
  | `docs/TEI_SERVICE说明文档.md` | TEI 专项(安装、部署、GPU/CPU 模式、排障) |
cc11ae04   tangwang   cnclip
543
  | `docs/CNCLIP_SERVICE说明文档.md` | CN-CLIP/clip-as-service 专项(环境、GPU、运维) |
bc54124c   tangwang   docs
544
  | `reranker/README.md` | 重排服务说明 |
7299bae6   tangwang   tests
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
  
  ---
  
  ## 7. 持续集成测试(最小可维护方案)
  
  目标:让后续开发者在不依赖真实 ES/MySQL/模型服务的前提下,快速验证核心服务契约不被破坏。
  
  ### 7.1 测试范围
  
  `tests/ci/test_service_api_contracts.py` 覆盖:
  
  - 搜索接口:`/search/`、`/search/image`、`/search/suggestions`
  - 索引接口:`/indexer/reindex`、`/indexer/index`、`/indexer/build-docs`
  - 向量服务:`/embed/text`、`/embed/image`
  - 翻译服务:`/translate`、`/health`
  - 重排服务:`/rerank`、`/health`
  
  ### 7.2 运行方式
  
  ```bash
  source activate.sh
  python -m pytest tests/ci -q
  ```
  
  ### 7.3 设计取舍
  
  - 使用 mock/stub 注入依赖,确保测试快且稳定
  - 重点测“接口契约与参数行为”,而不是底层模型质量
  - 作为 PR 级门禁;真实环境联调放在运维/预发布流程