diff --git a/docs/系统设计文档.md b/docs/系统设计文档.md index 7169eff..639dd15 100644 --- a/docs/系统设计文档.md +++ b/docs/系统设计文档.md @@ -20,10 +20,10 @@ ### 1.2 索引结构(SPU维度) -**统一索引架构**: -- 所有客户共享同一个Elasticsearch索引:`search_products` +**索引架构**: +- 每个租户使用独立的 Elasticsearch 索引(索引名称由 `get_tenant_index_name(tenant_id)` 动态生成) - 索引粒度:SPU级别(每个文档代表一个SPU) -- 数据隔离:通过`tenant_id`字段实现租户隔离 +- 数据隔离:通过“分索引 + `tenant_id` 字段”双重隔离(索引级 + 文档级) - 嵌套结构:每个SPU文档包含嵌套的`skus`数组 **索引文档结构**: @@ -87,10 +87,10 @@ ### 1.3 索引结构简化方案 **简化原则**: -- **硬编码映射**:ES mapping 结构直接定义在 JSON 文件中(`mappings/search_products.json`) -- **统一索引结构**:所有租户共享相同的索引结构,通过 `tenant_id` 隔离数据 +- **硬编码映射**:ES mapping 结构直接定义在 JSON 文件中(`mappings/search_products.json`),所有租户索引共享相同结构 +- **分索引 + 公共结构**:每个租户拥有独立索引,但索引结构一致 - **数据源统一**:所有租户使用相同的 MySQL 表结构(店匠标准表) -- **查询配置硬编码**:查询相关配置(字段 boost、查询域等)硬编码在 `search/query_config.py` +- **查询配置集中**:查询相关配置(字段 boost、查询域等)集中在配置文件中管理 **索引结构特点**: 1. **多语言字段**:所有文本字段支持中英文(`title.zh/en`, `brief.zh/en`, `description.zh/en`, `vendor.zh/en`, `category_path.zh/en`, `category_name_text.zh/en`) @@ -114,8 +114,8 @@ **实现方式**: - ES mapping 直接定义在 `mappings/search_products.json` 文件中 -- 所有租户共享相同的索引结构 -- 查询配置硬编码在 `search/query_config.py` +- 所有租户索引共享相同的 mapping 结构 +- 查询配置集中在配置系统中(如 `config/config.yaml` 等) **索引字段结构**: @@ -371,28 +371,27 @@ query_config: **实现情况**: -#### 配置方式 +#### 配置方式(示意) +翻译能力通过统一的 provider 配置管理,支持多种后端实现(如本地服务或外部 API): ```yaml query_config: supported_languages: - "zh" - "en" - - "ru" - default_language: "zh" - translation_service: "deepl" - translation_api_key: null # 通过环境变量设置 + default_language: "en" + # 实际翻译 provider 与模型在通用 services 配置中定义 ``` +实际代码中,通过通用的 translation provider 抽象来选择具体后端和模型,文档不固定绑定某一个具体翻译服务或模型名称,以保持可配置性。 + #### 功能特性 1. **语言检测**:自动检测查询语言 2. **智能翻译**: - - 如果查询是中文,翻译为英文、俄文 - - 如果查询是英文,翻译为中文、俄文 - - 如果查询是其他语言,翻译为所有支持的语言 + - 将源语言 query 翻译到当前租户配置的索引语言集合 3. **域感知翻译**: - 如果域有 `language_field_mapping`,只翻译到映射中存在的语言 - 避免不必要的翻译,提高效率 -4. **翻译缓存**:缓存翻译结果,避免重复调用 API +4. **翻译缓存**:缓存翻译结果,避免重复调用翻译后端 #### 工作流程 ``` @@ -401,7 +400,7 @@ query_config: #### 实现模块 - `query/language_detector.py` - 语言检测器 -- `query/translator.py` - 翻译器(DeepL API) +- `query/translator.py` - 翻译 provider 抽象与调用 - `query/query_parser.py` - 查询解析器(集成翻译功能) ### 4.3 文本向量化(Text Embedding) @@ -420,11 +419,11 @@ query_config: 1. **条件生成**: - 仅当 `enable_text_embedding=true` 时生成向量 - 仅对 `default` 域查询生成向量 -2. **向量模型**:Qwen3-Embedding-0.6B(1024维向量) +2. **向量模型**:使用可配置的文本向量模型(例如 1024 维通用语义 embedding),具体模型通过配置与 embedding 服务选择,不在文档中固定写死 3. **用途**:用于语义搜索(KNN 检索) #### 实现模块 -- `embeddings/text_encoder.py` + `embeddings/server.py` - 文本向量服务客户端与服务端实现 +- `embeddings/text_encoder.py` + `embeddings/server.py` - 文本向量服务客户端与服务端实现(支持可配置的模型后端) - `query/query_parser.py` - 查询解析器(集成向量生成) --- @@ -611,10 +610,10 @@ ranking: - ✅ 嵌套字段(skus, specifications, image_embedding) - ✅ 规格字段(specifications)支持过滤和分面 - ✅ 扁平化字段(价格、库存等)用于过滤和排序 -- ✅ 统一索引(search_products) -- ✅ 租户隔离(tenant_id) +- ✅ 按租户分索引(索引名通过 `get_tenant_index_name` 生成),各租户索引结构一致 +- ✅ 文档内仍包含 `tenant_id` 字段,可用于额外校验或跨索引场景 - ✅ 硬编码映射(mappings/search_products.json) -- ✅ 硬编码查询配置(search/query_config.py) +- ✅ 集中查询配置(config/config.yaml 等) --- @@ -623,8 +622,8 @@ ranking: - **后端**:Python 3.6+ - **搜索引擎**:Elasticsearch - **数据库**:MySQL(Shoplazza) -- **向量模型**:Qwen3-Embedding-0.6B(文本)、CN-CLIP(图片) -- **翻译服务**:DeepL API +- **向量服务**:可配置的文本/图像向量模型(通过 embedding 服务与配置选择具体模型) +- **翻译服务**:可配置的翻译 provider(通过 translation 服务与配置选择具体后端与模型) - **API 框架**:FastAPI - **前端**:HTML + JavaScript -- libgit2 0.21.2