QUICKSTART.md 12 KB
Edit Raw Blame History


开发与配置指南
新人入口：环境、服务、模块、请求示例、基础配置、Provider 架构、模块扩展规范，一文档搞定。

建议：首次参与开发请先阅读 DEVELOPER_GUIDE.md 建立项目全貌与协作规范，再使用本文做环境与配置速查。


为什么这样整合
本文已合并并替代以下文档中的核心内容：


docs/PROVIDER_ARCHITECTURE.md
docs/MODULE_EXTENSION_SPEC.md
docs/基础配置指南.md
原 docs/QUICKSTART.md


关于 docs/Usage-Guide.md：保留为运行/运维手册更清晰（日志、故障排查、多环境切换、建议索引运行细节），本文只保留开发常用且高频的信息，避免一个文档同时承担“开发规范 + 运维 runbook”导致冗长和混乱。


目录

快速上手
基础配置与搜索行为
Provider 架构
模块扩展规范（Embedding / Rerank）
验证、日志与常见排障入口
相关文档
持续集成测试（最小可维护方案）


1. 快速上手
1.1 环境准备
source activate.sh
# 首次推荐：
./scripts/create_venv.sh
# 或使用 conda：
# conda env create -f environment.yml


依赖：Python 3.8+、Elasticsearch 8.x、MySQL、Redis（可选，缓存用途）。

如果需要本地运行 embedding 模型（torch/transformers 等重依赖）：
INSTALL_ML=1 ./scripts/create_venv.sh
source activate.sh


详细环境说明见 docs/环境配置说明.md。
1.2 服务与端口


服务
端口
默认启动
说明


backend
6002
✓
搜索 API（/search/*）+ 管理接口（/admin/*）


indexer
6004
✓
索引 API（/indexer/*）


frontend
6003
✓
调试 UI


embedding
6005
-
向量服务（/embed/text, /embed/image）


translator
6006
-
翻译服务（/translate）


reranker
6007
-
重排服务（/rerank）


启动与停止：
./run.sh
# 启动全部能力
START_EMBEDDING=1 START_TRANSLATOR=1 START_RERANKER=1 ./run.sh

./scripts/service_ctl.sh status
./scripts/stop.sh

1.3 常用 API 请求示例
搜索 API（backend 6002）
# 文本搜索
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}'

# Suggestion
curl "http://localhost:6002/search/suggestions?q=玩&size=5" \
  -H "X-Tenant-ID: 162"

# 健康与统计
curl http://localhost:6002/admin/health
curl http://localhost:6002/admin/stats


API 文档：http://localhost:6002/docs
索引 API（indexer 6004）
# 创建租户索引
./scripts/create_tenant_index.sh 162

# 全量重建（更新/写入，不删除旧索引）
curl -X POST http://localhost:6004/indexer/reindex \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "162", "batch_size": 500}'

# 增量索引
curl -X POST http://localhost:6004/indexer/index \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "162", "spu_ids": ["1001", "1002"]}'

# 构建文档（不写 ES）
curl -X POST http://localhost:6004/indexer/build-docs \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"162","items":[{"spu":{},"skus":[],"options":[]}]}'


API 文档：http://localhost:6004/docs
Embedding 服务（6005）
./scripts/start_embedding_service.sh

curl -X POST http://localhost:6005/embed/text \
  -H "Content-Type: application/json" \
  -d '["衣服", "Bohemian Maxi Dress"]'

curl -X POST http://localhost:6005/embed/image \
  -H "Content-Type: application/json" \
  -d '["https://example.com/img.jpg"]'

Translator 服务（6006）
./scripts/start_translator.sh

curl -X POST http://localhost:6006/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"商品名称","target_lang":"en","source_lang":"zh"}'

Reranker 服务（6007）
./scripts/start_reranker.sh

curl -X POST http://localhost:6007/rerank \
  -H "Content-Type: application/json" \
  -d '{"query":"wireless mouse","docs":["logitech mx master","usb cable"]}'

1.4 配置入口总览

搜索行为配置：config/config.yaml
索引结构定义：mappings/search_products.json
provider/服务配置：config/config.yaml 的 services 块
环境变量：.env


2. 基础配置与搜索行为
2.1 总体原则

统一索引结构：所有租户使用同一套 mapping（按租户数据分索引名 + 文档内 tenant_id 隔离）
SPU 级索引：每个文档是一个 SPU，包含嵌套 skus、specifications
配置文件驱动：搜索权重、搜索域、重排融合、provider 全在 config/config.yaml，不再以“硬编码配置”为主

2.2 索引结构（Mapping）
文件：mappings/search_products.json

核心字段可分为：


标识字段：tenant_id, spu_id
多语言文本：title.zh/en, brief.zh/en, description.zh/en, vendor.zh/en, category_path.zh/en, category_name_text.zh/en
类目过滤：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）

field_boosts：字段权重（如标题、品牌、类目）
indexes：搜索域（default/title/vendor/category/tags）
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> → 重新导入


搜索域/权重/排序/重排
修改 config/config.yaml 对应块


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：
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"
    providers:
      http: { base_url: "http://127.0.0.1:6005" }
  rerank:
    provider: "http"
    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
RERANKER_SERVICE_URL
RERANK_BACKEND（服务内后端）

3.3 新增 provider 的最小步骤

在 providers/<capability>.py 实现 provider 类
在 create_*_provider() 注册
在 config/config.yaml 的 services.<capability>.providers 新增配置


4. 模块扩展规范（Embedding / Rerank）
这里重点区分两层：


Provider 层（调用方式）：调用方如何访问能力（http/direct）
Backend 层（推理实现）：服务进程内部具体模型实现（bge / qwen3_vllm / ...）

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（文本和图像可独立加载）
文本后端现用 BGE
图像后端支持本地 CLIP 或 clip-as-service


扩展建议：


文本后端统一提供批量编码能力（与输入索引对齐）
图像后端实现 ImageEncoderProtocol（encode_image_urls）
如后续后端增多，建议与 rerank 一样在 services.embedding.backend(s) 统一配置

4.3 新增后端检查清单（以 qwen3_vllm 为例）

实现后端协议（服务内）
在后端工厂注册（如 get_rerank_backend）
增加 config/config.yaml 对应 backend 配置
提供健康检查中的 backend/model 可观测信息
保持外部 HTTP 契约不变，调用方无需改造


5. 验证、日志与常见排障入口
5.1 快速健康检查
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 常看日志

logs/backend.log
logs/indexer.log
logs/frontend.log
logs/embedding.log
logs/translator.log
logs/reranker.log
logs/search_engine.log
logs/errors.log

5.3 常用排障命令
./scripts/service_ctl.sh status
curl http://localhost:9200
lsof -i :6002
lsof -i :6004


更完整的运行排障（多环境切换、Suggestion 构建、FAQ）见 docs/Usage-Guide.md。


6. 相关文档


文档
用途


docs/DEVELOPER_GUIDE.md
项目全貌、规范、协作方式


docs/Usage-Guide.md
运行运维手册：日志、多环境、故障排查、Suggestion 运维


docs/搜索API速查表.md
搜索 API 参数速查


docs/搜索API对接指南.md
搜索 API 完整说明


indexer/README.md
索引模块职责与接口


embeddings/README.md
向量化服务说明


reranker/README.md
重排服务说明


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 运行方式
source activate.sh
python -m pytest tests/ci -q

7.3 设计取舍

使用 mock/stub 注入依赖，确保测试快且稳定
重点测“接口契约与参数行为”，而不是底层模型质量
作为 PR 级门禁；真实环境联调放在运维/预发布流程