开发者快速上手

新人入口文档：环境、服务、模块、请求示例一页搞定。

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

1. 环境

source activate.sh
# 首次：./scripts/create_venv.sh 或 conda env create -f environment.yml

依赖：Python 3.8+、Elasticsearch 8.x、MySQL、Redis（可选）。详见 docs/环境配置说明.md。

2. 服务与端口

服务	端口	默认启动	说明
backend	6002	✓	搜索 API
indexer	6004	✓	索引 API
frontend	6003	✓	调试 UI
embedding	6005	-	向量服务
translator	6006	-	翻译服务
reranker	6007	-	重排服务

./run.sh
# 全功能：START_EMBEDDING=1 START_TRANSLATOR=1 START_RERANKER=1 ./run.sh
./scripts/service_ctl.sh status
./scripts/stop.sh

3. 模块与请求

3.1 搜索 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}'

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

API 文档：http://localhost:6002/docs

3.2 索引 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}'

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

3.3 向量服务（embedding 6005）

./scripts/start_embedding_service.sh

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

# 图片向量（URL 列表）
curl -X POST http://localhost:6005/embed/image \
  -H "Content-Type: application/json" \
  -d '["https://example.com/img.jpg"]'

3.4 翻译服务（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"}'

3.5 重排服务（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"]}'

4. 配置

• 主配置：config/config.yaml（搜索行为、字段权重、分面等）
• 服务 provider：config/config.yaml 的 services 块（翻译/向量/重排的 provider 与 URL）
• 环境变量：.env（DB、ES、Redis、API Key 等）

5. 延伸阅读

文档	用途
docs/Usage-Guide.md	运维：日志、多环境、故障排查
docs/搜索API速查表.md	搜索 API 参数速查
docs/搜索API对接指南.md	搜索 API 完整说明
docs/PROVIDER_ARCHITECTURE.md	翻译/向量/重排 provider 扩展
indexer/README.md	索引模块职责与接口