ai-saas / saas-search

Commit f201859ee7d3ee235fc66099443acf1f81efc94b

Authored by tangwang
1 parent 22ae00c7

docs

Showing 1 changed file with 24 additions and 25 deletions   Show diff stats
Inline Side-by-side
docs/系统设计文档.md
  Show/Hide comments   View file @f201859
@@ -20,10 +20,10 @@ @@ -20,10 +20,10 @@
20 20
21 ### 1.2 索引结构（SPU维度） 21 ### 1.2 索引结构（SPU维度）
22 22
23 -**统一索引架构**：  
24 -- 所有客户共享同一个Elasticsearch索引：`search_products` 23 +**索引架构**：
  24 +- 每个租户使用独立的 Elasticsearch 索引（索引名称由 `get_tenant_index_name(tenant_id)` 动态生成）
25 - 索引粒度：SPU级别（每个文档代表一个SPU） 25 - 索引粒度：SPU级别（每个文档代表一个SPU）
26 -- 数据隔离：通过`tenant_id`字段实现租户隔离 26 +- 数据隔离：通过“分索引 + `tenant_id` 字段”双重隔离（索引级 + 文档级）
27 - 嵌套结构：每个SPU文档包含嵌套的`skus`数组 27 - 嵌套结构：每个SPU文档包含嵌套的`skus`数组
28 28
29 **索引文档结构**： 29 **索引文档结构**：
@@ -87,10 +87,10 @@ @@ -87,10 +87,10 @@
87 ### 1.3 索引结构简化方案 87 ### 1.3 索引结构简化方案
88 88
89 **简化原则**： 89 **简化原则**：
90 -- **硬编码映射**：ES mapping 结构直接定义在 JSON 文件中（`mappings/search_products.json`）  
91 -- **统一索引结构**：所有租户共享相同的索引结构，通过 `tenant_id` 隔离数据 90 +- **硬编码映射**：ES mapping 结构直接定义在 JSON 文件中（`mappings/search_products.json`），所有租户索引共享相同结构
  91 +- **分索引 + 公共结构**：每个租户拥有独立索引，但索引结构一致
92 - **数据源统一**：所有租户使用相同的 MySQL 表结构（店匠标准表） 92 - **数据源统一**：所有租户使用相同的 MySQL 表结构（店匠标准表）
93 -- **查询配置硬编码**：查询相关配置（字段 boost、查询域等）硬编码在 `search/query_config.py` 93 +- **查询配置集中**：查询相关配置（字段 boost、查询域等）集中在配置文件中管理
94 94
95 **索引结构特点**： 95 **索引结构特点**：
96 1. **多语言字段**：所有文本字段支持中英文（`title.zh/en`, `brief.zh/en`, `description.zh/en`, `vendor.zh/en`, `category_path.zh/en`, `category_name_text.zh/en`） 96 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 @@ @@ -114,8 +114,8 @@
114 114
115 **实现方式**： 115 **实现方式**：
116 - ES mapping 直接定义在 `mappings/search_products.json` 文件中 116 - ES mapping 直接定义在 `mappings/search_products.json` 文件中
117 -- 所有租户共享相同的索引结构  
118 -- 查询配置硬编码在 `search/query_config.py` 117 +- 所有租户索引共享相同的 mapping 结构
  118 +- 查询配置集中在配置系统中（如 `config/config.yaml` 等）
119 119
120 **索引字段结构**： 120 **索引字段结构**：
121 121
@@ -371,28 +371,27 @@ query_config: @@ -371,28 +371,27 @@ query_config:
371 371
372 **实现情况**： 372 **实现情况**：
373 373
374 -#### 配置方式 374 +#### 配置方式（示意）
  375 +翻译能力通过统一的 provider 配置管理，支持多种后端实现（如本地服务或外部 API）：
375 ```yaml 376 ```yaml
376 query_config: 377 query_config:
377 supported_languages: 378 supported_languages:
378 - "zh" 379 - "zh"
379 - "en" 380 - "en"
380 - - "ru"  
381 - default_language: "zh"  
382 - translation_service: "deepl"  
383 - translation_api_key: null # 通过环境变量设置 381 + default_language: "en"
  382 + # 实际翻译 provider 与模型在通用 services 配置中定义
384 ``` 383 ```
385 384
  385 +实际代码中，通过通用的 translation provider 抽象来选择具体后端和模型，文档不固定绑定某一个具体翻译服务或模型名称，以保持可配置性。
  386 +
386 #### 功能特性 387 #### 功能特性
387 1. **语言检测**：自动检测查询语言 388 1. **语言检测**：自动检测查询语言
388 2. **智能翻译**： 389 2. **智能翻译**：
389 - - 如果查询是中文，翻译为英文、俄文  
390 - - 如果查询是英文，翻译为中文、俄文  
391 - - 如果查询是其他语言，翻译为所有支持的语言 390 + - 将源语言 query 翻译到当前租户配置的索引语言集合
392 3. **域感知翻译**： 391 3. **域感知翻译**：
393 - 如果域有 `language_field_mapping`，只翻译到映射中存在的语言 392 - 如果域有 `language_field_mapping`，只翻译到映射中存在的语言
394 - 避免不必要的翻译，提高效率 393 - 避免不必要的翻译，提高效率
395 -4. **翻译缓存**：缓存翻译结果，避免重复调用 API 394 +4. **翻译缓存**：缓存翻译结果，避免重复调用翻译后端
396 395
397 #### 工作流程 396 #### 工作流程
398 ``` 397 ```
@@ -401,7 +400,7 @@ query_config: @@ -401,7 +400,7 @@ query_config:
401 400
402 #### 实现模块 401 #### 实现模块
403 - `query/language_detector.py` - 语言检测器 402 - `query/language_detector.py` - 语言检测器
404 -- `query/translator.py` - 翻译器（DeepL API） 403 +- `query/translator.py` - 翻译 provider 抽象与调用
405 - `query/query_parser.py` - 查询解析器（集成翻译功能） 404 - `query/query_parser.py` - 查询解析器（集成翻译功能）
406 405
407 ### 4.3 文本向量化（Text Embedding） 406 ### 4.3 文本向量化（Text Embedding）
@@ -420,11 +419,11 @@ query_config: @@ -420,11 +419,11 @@ query_config:
420 1. **条件生成**： 419 1. **条件生成**：
421 - 仅当 `enable_text_embedding=true` 时生成向量 420 - 仅当 `enable_text_embedding=true` 时生成向量
422 - 仅对 `default` 域查询生成向量 421 - 仅对 `default` 域查询生成向量
423 -2. **向量模型**：Qwen3-Embedding-0.6B（1024维向量） 422 +2. **向量模型**：使用可配置的文本向量模型（例如 1024 维通用语义 embedding），具体模型通过配置与 embedding 服务选择，不在文档中固定写死
424 3. **用途**：用于语义搜索（KNN 检索） 423 3. **用途**：用于语义搜索（KNN 检索）
425 424
426 #### 实现模块 425 #### 实现模块
427 -- `embeddings/text_encoder.py` + `embeddings/server.py` - 文本向量服务客户端与服务端实现 426 +- `embeddings/text_encoder.py` + `embeddings/server.py` - 文本向量服务客户端与服务端实现（支持可配置的模型后端）
428 - `query/query_parser.py` - 查询解析器（集成向量生成） 427 - `query/query_parser.py` - 查询解析器（集成向量生成）
429 428
430 --- 429 ---
@@ -611,10 +610,10 @@ ranking: @@ -611,10 +610,10 @@ ranking:
611 - ✅ 嵌套字段（skus, specifications, image_embedding） 610 - ✅ 嵌套字段（skus, specifications, image_embedding）
612 - ✅ 规格字段（specifications）支持过滤和分面 611 - ✅ 规格字段（specifications）支持过滤和分面
613 - ✅ 扁平化字段（价格、库存等）用于过滤和排序 612 - ✅ 扁平化字段（价格、库存等）用于过滤和排序
614 -- ✅ 统一索引（search_products）  
615 -- ✅ 租户隔离（tenant_id） 613 +- ✅ 按租户分索引（索引名通过 `get_tenant_index_name` 生成），各租户索引结构一致
  614 +- ✅ 文档内仍包含 `tenant_id` 字段，可用于额外校验或跨索引场景
616 - ✅ 硬编码映射（mappings/search_products.json） 615 - ✅ 硬编码映射（mappings/search_products.json）
617 -- ✅ 硬编码查询配置（search/query_config.py） 616 +- ✅ 集中查询配置（config/config.yaml 等）
618 617
619 --- 618 ---
620 619
@@ -623,8 +622,8 @@ ranking: @@ -623,8 +622,8 @@ ranking:
623 - **后端**：Python 3.6+ 622 - **后端**：Python 3.6+
624 - **搜索引擎**：Elasticsearch 623 - **搜索引擎**：Elasticsearch
625 - **数据库**：MySQL（Shoplazza） 624 - **数据库**：MySQL（Shoplazza）
626 -- **向量模型**：Qwen3-Embedding-0.6B（文本）、CN-CLIP（图片）  
627 -- **翻译服务**：DeepL API 625 +- **向量服务**：可配置的文本/图像向量模型（通过 embedding 服务与配置选择具体模型）
  626 +- **翻译服务**：可配置的翻译 provider（通过 translation 服务与配置选择具体后端与模型）
628 - **API 框架**：FastAPI 627 - **API 框架**：FastAPI
629 - **前端**：HTML + JavaScript 628 - **前端**：HTML + JavaScript
630 629