docs

tangwang
1 parent 22ae00c7
Showing 1 changed file with 24 additions and 25 deletions Show diff stats
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