# 电商搜索引擎 SaaS

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

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

  ---

  ## 1) 项目目标与边界

  - **目标**：在统一架构下支持关键词检索、语义检索、分面过滤、多语言、分层排序（粗排 / 可选精排 fine rank / 重排）、图片检索。

  - **边界**：本仓库负责搜索核心能力与服务编排；业务方通过标准 HTTP API 对接。
  - **核心约束**：
    - 调用方稳定（API/Provider 契约优先）
    - 配置单一来源（`config/config.yaml` + `.env` 覆盖）
    - 扩展优先走插件化（provider/backend），避免散落式分叉实现

  ---

  ## 2) 快速开始

  
  ```bash

  # 首次创建环境（默认基础依赖）

  ./scripts/create_venv.sh

  ./scripts/init_env.sh   # 从 .env.example 生成本地 .env（若不存在）

  source activate.sh

  # 推荐：一键拉起全部服务（含监控守护）
  ./run.sh all    # 薄封装：等价于 ./scripts/service_ctl.sh up all

  # 查看状态 + 健康检查（含 monitor daemon 状态）
  ./status.sh          # 薄封装：等价于 ./scripts/service_ctl.sh status

  
  # 重启指定服务集合（示例：全部）
  ./restart.sh all    # 薄封装：等价于 ./scripts/service_ctl.sh restart all
  
  # 一键停止（含 monitor daemon）
  ./scripts/stop.sh all    # 薄封装：等价于 ./scripts/service_ctl.sh down all

  ```

  服务管理全盘说明（入口职责、默认行为、全量启停方式）见：
  - `docs/Usage-Guide.md` -> `服务管理总览`
  

  核心端口：

  - `6001` qp

  - `6002` backend（`/search/*`, `/admin/*`）

  - `6003` frontend

  - `6004` indexer（`/indexer/*`）

  - `6005` embedding-text（可选，`POST /embed/text`；常见后端为 TEI，默认 `8080`）

  - `6006` translator（可选）

  - `6007` reranker（可选，`POST /rerank`；精排可与主重排分 `service_profile`，见 `config.yaml` → `fine_rank` / `services.rerank`）

  - `6008` embedding-image（可选，`POST /embed/image` 等）
  - `6010` eval-web（搜索评估 UI，`./scripts/service_ctl.sh` 服务名 `eval-web`）

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

  ---

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

  - `api/`：统一 API 入口（search/admin/indexer app）

  - `search/`：召回、分层排序与结果组织（ES 召回 → `coarse_rank` 融合文本/KNN → 可选 `fine_rank` 轻量精排 → `rerank` 融合模型分与 ES 信号；`debug=true` 时返回各阶段 rank / fusion 调试字段）

  - `query/`：查询解析、多语言处理、改写
  - `indexer/`：MySQL 行数据 -> ES 文档的转换与索引流程

  - `providers/`：能力调用抽象（embedding/rerank）
  - `translation/`：翻译服务客户端、服务编排与后端实现

  - `reranker/`：重排服务及后端实现
  - `embeddings/`：向量服务（文本/图像）
  - `config/`：配置加载与服务配置解析

  关键设计：
  
  - embedding / rerank 继续采用 **Provider（调用方式）与 Backend（推理实现）分离**
  - translation 采用 **一个 translator service + 多个 capability backend**，业务侧统一调用 6006，不再做翻译 provider 选择

  ---

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

  - **单一配置源**：服务地址、provider 选择、后端参数统一在 `config/config.yaml`，环境变量仅做覆盖。
  - **接口契约优先**：外部 API 契约与 provider 契约稳定，内部重构不影响调用方。
  - **扩展走工厂**：新增 provider/backend 必须在工厂函数中显式注册，禁止旁路分支。

  - **简洁和规范优先**：对待异常情况，分情况而定，如果是系统启动期间、加载资源/配置等出错，可以尽早暴露问题，不要fallback走一套跟配置不符合的另外一套机制，即尽量保证逻辑清晰、简洁；但是线上的服务如果遇到异常情况可以根据最佳实践选取应对方法，比如记录错误日志并且保证服务正常运行。规范优先，尽量用一套机制满足需求，而不是兼容各种不合理的情况，对于不合理的内容优先清理、重构，而不是兼容，以保证代码是简洁的。

  - **可观测性优先**：健康检查、关键日志、请求上下文必须可追踪。
  - **测试优先保障契约**：CI 首先保证接口契约和核心路径可用，再逐步扩展性能与业务测试。

  ---

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

  | 步骤 | 文档 |
  |------|------|

  | 0. 全局规范（首读） | `docs/DEVELOPER_GUIDE.md` |
  | 1. 开发与配置 | `docs/QUICKSTART.md` |
  | 2. 运行与排障 | `docs/Usage-Guide.md` |

  | 3. 搜索 API（已拆分为多篇，从总览进入） | `docs/搜索API对接指南-00-总览与快速开始.md` |
  | 4. 快速参数速查 | `docs/搜索API对接指南-速查表.md` |

  | 5. 翻译专项 | `docs/翻译模块说明.md` |
  | 6. 首次环境搭建、生产凭证 | `docs/QUICKSTART.md` §1.4–1.8 |
  | 7. TEI 文本向量专项 | `docs/TEI_SERVICE说明文档.md` |
  | 8. CN-CLIP 图片向量专项 | `docs/CNCLIP_SERVICE说明文档.md` |

  | 9. 相关性检索与融合（含 fine rank / rerank） | `docs/相关性检索优化说明.md` |
  | 10. 调参与评估工作流 | `docs/检索调参与LTR工作流.md` |
  | 11. 微服务性能与架构摘要 | `docs/工作总结-微服务性能优化与架构.md` |
  
  **搜索 API 拆分目录**（与总览中列表一致，按需查阅）：
  
  | 分册 | 内容 |
  |------|------|
  | `搜索API对接指南-01-搜索接口.md` | `POST /search/` 请求与响应 |
  | `搜索API对接指南-02-搜索建议与即时搜索.md` | 建议 / 即时搜索 |
  | `搜索API对接指南-03-获取文档.md` | `GET /search/{doc_id}` |
  | `搜索API对接指南-05-索引接口（Indexer）.md` | 索引与 `build-docs` / `enrich-content` 等 |
  | `搜索API对接指南-06-管理接口（Admin）.md` | `/admin/*` |
  | `搜索API对接指南-07-微服务接口（Embedding-Reranker-Translation）.md` | 6005/6006/6007/6008 等直连说明 |
  | `搜索API对接指南-08-数据模型与字段速查.md` | 字段与数据模型 |
  | `搜索API对接指南-10-接口级压测脚本.md` | 压测脚本与用法 |

  ---

  ## 6) 持续集成测试（推荐最小集）

  本仓库提供一套轻量、稳定、易维护的 CI 测试入口，覆盖以下服务契约：

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

  本地运行：

  ```bash
  source activate.sh
  python -m pytest tests/ci -q

  ```
  

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

  ---

  ## 7) 代码质量与持续集成要求

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

    - 对应分册：`docs/搜索API对接指南-*.md`（及速查表）
    - 对应服务 README / 专项文档

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