README.md 3.9 KB
Edit Raw Blame History


电商搜索引擎 SaaS
多租户、可配置、可扩展的电商搜索平台（Shoplazza 等独立站场景）。

README 用于给后续开发者建立统一认知：系统框架、模块边界、设计原则、研发流程与 CI 测试入口，帮助持续迭代时避免分叉设计与冗余代码。


1) 项目目标与边界

目标：在统一架构下支持关键词检索、语义检索、分面过滤、多语言、重排、图片检索。
边界：本仓库负责搜索核心能力与服务编排；业务方通过标准 HTTP API 对接。
核心约束：


调用方稳定（API/Provider 契约优先）
配置单一来源（config/config.yaml + .env 覆盖）
扩展优先走插件化（provider/backend），避免散落式分叉实现


2) 快速开始
# 首次创建环境（默认基础依赖）
./scripts/create_venv.sh
source activate.sh

# 启动核心服务（backend/indexer/frontend）
./run.sh

# 可选：附加能力服务
START_EMBEDDING=1 START_TRANSLATOR=1 START_RERANKER=1 ./run.sh

# 查看状态
./scripts/service_ctl.sh status


核心端口：


6002 backend（/search/*, /admin/*）
6004 indexer（/indexer/*）
6003 frontend
6005 embedding（可选）
6006 translator（可选）
6007 reranker（可选）


更完整示例见 docs/QUICKSTART.md。


3) 总体架构（开发者视角）

api/：统一 API 入口（search/admin/indexer app）
search/：召回、排序、结果组织
query/：查询解析、多语言处理、改写
indexer/：MySQL 行数据 -> ES 文档的转换与索引流程
providers/：能力调用抽象（translation/embedding/rerank）
reranker/：重排服务及后端实现
embeddings/：向量服务（文本/图像）
config/：配置加载与服务配置解析


关键设计：Provider（调用方式）与 Backend（推理实现）分离，新增能力优先在协议与工厂注册，不改调用方主流程。


4) 设计原则（避免后续分叉）

单一配置源：服务地址、provider 选择、后端参数统一在 config/config.yaml，环境变量仅做覆盖。
接口契约优先：外部 API 契约与 provider 契约稳定，内部重构不影响调用方。
扩展走工厂：新增 provider/backend 必须在工厂函数中显式注册，禁止旁路分支。
可观测性优先：健康检查、关键日志、请求上下文必须可追踪。
测试优先保障契约：CI 首先保证接口契约和核心路径可用，再逐步扩展性能与业务测试。


5) 文档入口（建议阅读顺序）


步骤
文档


0. 全局规范（首读）
docs/DEVELOPER_GUIDE.md


1. 开发与配置
docs/QUICKSTART.md


2. 运行与排障
docs/Usage-Guide.md


3. API 详细说明
docs/搜索API对接指南.md


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


5. 首次环境搭建
docs/环境配置说明.md


6) 持续集成测试（推荐最小集）
本仓库提供一套轻量、稳定、易维护的 CI 测试入口，覆盖以下服务契约：


搜索接口（search API）
索引接口（indexer API）
向量服务（embedding service）
翻译服务（translator service）
重排服务（reranker service）


本地运行：
source activate.sh
python -m pytest tests/ci -q


该测试集采用 mock/stub，不依赖真实 ES/MySQL/大模型服务，适合作为 PR 级快速回归门禁。


7) 代码质量与持续继承要求

新增功能必须补最小测试（至少覆盖 1 条成功路径 + 1 条参数异常路径）
修改公共协议时必须同步更新：


docs/QUICKSTART.md
对应服务 README / API 文档
tests/ci 契约用例

禁止新增“临时分支逻辑”绕过 provider/backend 工厂
优先减少重复实现，复用现有转换链路与配置解析入口