last

tangwang
1 parent bd96cead
Showing 7 changed files with 398 additions and 198 deletions Show diff stats
config/config_loader.py
docs/DEVELOPER_GUIDE.md
docs/QUICKSTART.md
docs/相关性检索优化说明.md
docs/相关性检索优化说明_old1.md
search/es_query_builder.py
search/searcher.py
@@ -47,11 +47,7 @@ class QueryConfig:
     # Embedding field names
     text_embedding_field: Optional[str] = "title_embedding"
     image_embedding_field: Optional[str] = None
-    
-    # Embedding disable thresholds (disable vector search for short queries)
-    embedding_disable_chinese_char_limit: int = 4
-    embedding_disable_english_word_limit: int = 3
-    
+        
     # Source fields configuration
     source_fields: Optional[List[str]] = None
@@ -75,6 +71,7 @@ class QueryConfig:
     translation_boost: float = 0.4
     translation_boost_when_source_missing: float = 1.0
     source_boost_when_missing: float = 0.6
+    original_query_fallback_boost_when_translation_missing: float = 0.2
     keywords_boost: float = 0.1
     enable_phrase_query: bool = True
     tie_breaker_base_query: float = 0.9
@@ -249,7 +246,6 @@ class ConfigLoader:
         query_config_data = config_data.get("query_config", {})
         services_data = config_data.get("services", {}) if isinstance(config_data.get("services", {}), dict) else {}
         rewrite_dictionary = self._load_rewrite_dictionary()
-        embedding_thresholds = query_config_data.get("embedding_disable_thresholds", {})
         search_fields_cfg = query_config_data.get("search_fields", {})
         text_strategy_cfg = query_config_data.get("text_query_strategy", {})
@@ -266,8 +262,6 @@ class ConfigLoader:
             translation_prompts=query_config_data.get("translation_prompts", {}),
             text_embedding_field=query_config_data.get("text_embedding_field"),
             image_embedding_field=query_config_data.get("image_embedding_field"),
-            embedding_disable_chinese_char_limit=embedding_thresholds.get("chinese_char_limit", 4),
-            embedding_disable_english_word_limit=embedding_thresholds.get("english_word_limit", 3),
             source_fields=query_config_data.get("source_fields"),
             knn_boost=query_config_data.get("knn_boost", 0.25),
             multilingual_fields=search_fields_cfg.get(
@@ -289,6 +283,9 @@ class ConfigLoader:
                 text_strategy_cfg.get("translation_boost_when_source_missing", 1.0)
             ),
             source_boost_when_missing=float(text_strategy_cfg.get("source_boost_when_missing", 0.6)),
+            original_query_fallback_boost_when_translation_missing=float(
+                text_strategy_cfg.get("original_query_fallback_boost_when_translation_missing", 0.2)
+            ),
             keywords_boost=float(text_strategy_cfg.get("keywords_boost", 0.1)),
             enable_phrase_query=bool(text_strategy_cfg.get("enable_phrase_query", True)),
             tie_breaker_base_query=float(text_strategy_cfg.get("tie_breaker_base_query", 0.9)),
@@ -433,6 +430,7 @@ class ConfigLoader:
             "translation_boost",
             "translation_boost_when_source_missing",
             "source_boost_when_missing",
+            "original_query_fallback_boost_when_translation_missing",
             "keywords_boost",
             "tie_breaker_base_query",
             "tie_breaker_keywords",
@@ -482,10 +480,6 @@ class ConfigLoader:
             "translation_service": config.query_config.translation_service,
             "text_embedding_field": config.query_config.text_embedding_field,
             "image_embedding_field": config.query_config.image_embedding_field,
-            "embedding_disable_thresholds": {
-                "chinese_char_limit": config.query_config.embedding_disable_chinese_char_limit,
-                "english_word_limit": config.query_config.embedding_disable_english_word_limit
-            },
             "source_fields": config.query_config.source_fields,
             "search_fields": {
                 "multilingual_fields": config.query_config.multilingual_fields,
@@ -498,6 +492,9 @@ class ConfigLoader:
                 "translation_boost": config.query_config.translation_boost,
                 "translation_boost_when_source_missing": config.query_config.translation_boost_when_source_missing,
                 "source_boost_when_missing": config.query_config.source_boost_when_missing,
+                "original_query_fallback_boost_when_translation_missing": (
+                    config.query_config.original_query_fallback_boost_when_translation_missing
+                ),
                 "keywords_boost": config.query_config.keywords_boost,
                 "enable_phrase_query": config.query_config.enable_phrase_query,
                 "tie_breaker_base_query": config.query_config.tie_breaker_base_query,
@@ -241,7 +241,7 @@ docs/                # 文档（含本指南）
 ### 6.1 主配置文件
-- **config/config.yaml**：搜索行为（field_boosts、query_config.search_fields、query_config.text_query_strategy、ranking、function_score、rerank 融合参数）、SPU 配置、**services**（翻译/向量/重排的 provider 与 backends）、tenant_config 等。
+- **config/config.yaml**：搜索行为（field_boosts、query_config.search_fields、query_config.text_query_strategy，含翻译失败时的原文兜底 boost、ranking、function_score、rerank 融合参数）、SPU 配置、**services**（翻译/向量/重排的 provider 与 backends）、tenant_config 等。
 - **.env**：敏感信息与部署态变量（DB、ES、Redis、API Key、端口等）；不提交敏感值，可提供 `.env.example` 模板。
 ### 6.2 services 块结构（能力统一约定）
@@ -348,7 +348,7 @@ saas-search 以 MySQL 中的店匠标准表为权威数据源：
 - `field_boosts`：字段权重（统一按字段基名配置，运行时按 `.{lang}` 动态组装）
 - `query_config.search_fields`：动态多语言检索字段（multilingual/shared/core）
-- `query_config.text_query_strategy`：文本召回策略参数（minimum_should_match、翻译boost等）
+- `query_config.text_query_strategy`：文本召回策略参数（minimum_should_match、翻译boost、翻译失败原文兜底boost等）
 - `query_config`：语言、embedding 开关、source_fields、knn_boost、翻译提示词等
 - `ranking.expression`：融合表达式（例如 `bm25() + 0.25*text_embedding_relevance()`）
 - `function_score`：ES 层加权函数
-# 相关性检索优化说明
+# 相关性检索优化说明（当前实现）
-## 概述
+## 1. 文档目标
-本次优化将相关性检索从简单的 `must` 子句中的 `multi_match` 查询，改为使用 `should` 子句的多查询策略，参考了成熟的搜索实现，显著提升了检索效果。
+本文描述当前线上代码的文本检索策略，重点覆盖：
-## 主要改进
+- 多语言检索路由（`detector` / `translator` / `indexed` 的关系）
+- 统一文本召回表达式（无布尔 AST 分支）
+- 翻译缺失时的兜底策略
+- 典型场景下实际生成的 ES 查询结构
-## 实现方式
+> 说明：向量召回（KNN）是另一维度，本篇仅简要提及，不展开。
-本次优化采用精简实现，直接在 `QueryParser` 中集成必要的分析功能，不新增独立模块。
+## 2. 核心流程
-### 1. 查询结构优化
+查询链路（文本相关）：
-**之前的结构**（效果差）：
-```json
-{
-  "bool": {
-    "must": [
-      {
-        "multi_match": {
-          "query": "戏水动物",
-          "fields": ["title.zh^3.0", "brief.zh^1.5", ...],
-          "minimum_should_match": "67%",
-          "tie_breaker": 0.9,
-          "boost": 1,
-          "_name": "base_query"
-        }
-      }
-    ]
-  }
-}
-```
-
-**优化后的结构**（效果更好）：
-```json
-{
-  "bool": {
-    "should": [
-      {
-        "multi_match": {
-          "_name": "base_query",
-          "fields": ["title.zh^3.0", "brief.zh^1.5", ...],
-          "minimum_should_match": "75%",
-          "operator": "AND",
-          "query": "戏水动物",
-          "tie_breaker": 0.9
-        }
-      },
-      {
-        "multi_match": {
-          "_name": "base_query_trans_en",
-          "boost": 0.4,
-          "fields": ["title.en^3.0", ...],
-          "minimum_should_match": "75%",
-          "operator": "AND",
-          "query": "water sports",
-          "tie_breaker": 0.9
-        }
-      },
-      {
-        "multi_match": {
-          "query": "戏水动物",
-          "fields": ["title.zh^3.0", "brief.zh^1.5", ...],
-          "type": "phrase",
-          "slop": 2,
-          "boost": 1.0,
-          "_name": "phrase_query"
-        }
-      },
-      {
-        "multi_match": {
-          "query": "戏水 动物",
-          "fields": ["title.zh^3.0", "brief.zh^1.5", ...],
-          "operator": "AND",
-          "tie_breaker": 0.9,
-          "boost": 0.1,
-          "_name": "keywords_query"
-        }
-      }
-    ],
-    "minimum_should_match": 1
-  }
-}
-```
+1. `QueryParser.parse()`  
+   输出 `detected_language`、`query_text_by_lang`、`search_langs`、`index_languages`、`source_in_index_languages`。
+2. `ESQueryBuilder._build_advanced_text_query()`  
+   按 `search_langs` 动态拼接 `title/brief/description/vendor/category_*` 的 `.{lang}` 字段，叠加 shared 字段（`tags`、`option*_values`）。
+3. `build_query()`  
+   统一走文本策略，不再有布尔 AST 枝路。
-### 2. 集成查询分析功能
+## 3. 能力矩阵（Detector / Translator / Indexed）
-在 `QueryParser` 中直接集成必要的分析功能：
+三类能力的职责边界：
-- **关键词提取**：使用 HanLP 提取查询中的名词（长度>1），用于关键词查询（可选，HanLP 不可用时降级）
-- **查询类型判断**：区分短查询和长查询
-- **Token 计数**：用于判断查询长度
+- **Detector**：识别 query 源语言（`detected_language`）
+- **Indexed**：租户可检索语言集合（`tenant_config.*.index_languages`）
+- **Translator**：源语言到目标语言的可翻译能力及实时成功率
-### 3. 多查询策略
+### 3.1 决策规则
-#### 3.1 基础查询（base_query）
-- 使用 `operator: "AND"` 确保所有词都必须匹配
-- `minimum_should_match: "75%"` 提高匹配精度
-- 使用 `tie_breaker: 0.9` 进行分数融合
+1. 若 `detected_language in index_languages`：  
+   源语言字段做主召回；其他语言走翻译补召回（低权重）。
+2. 若 `detected_language not in index_languages`：  
+   翻译到 `index_languages` 是主路径；源语言字段仅作弱召回。
+3. 若第 2 步翻译部分失败或全部失败：  
+   对缺失翻译的 `index_languages` 字段，追加“原文低权重兜底”子句，避免完全丢失这些语种索引面的召回机会。
-#### 3.2 翻译查询（base_query_trans_zh/en）
-- 当查询语言不是中文/英文时，添加翻译查询
-- 使用较低的 boost（0.4）避免过度影响
-- 支持跨语言检索
+### 3.2 翻译等待策略
-#### 3.3 短语查询（phrase_query）
-- 针对短查询（token_count >= 2 且 is_short，由 query_tokens 推导）
-- 使用 `type: "phrase"` 进行精确短语匹配
-- 支持 slop（允许词序调整）
+`QueryParser.parse()` 中：
-#### 3.4 关键词查询（keywords_query）
-- 使用 HanLP 提取的名词进行查询
-- 仅在关键词长度合理时启用（避免关键词占查询比例过高）
-- 使用较低的 boost（0.1）作为补充
+- 当源语种不在 `index_languages`：使用 `translate_multi_async(...)` 并等待 futures 收敛
+- 当源语种在 `index_languages`：使用 `translate_multi(..., async_mode=True)`，优先缓存命中，未命中可后台补齐
-#### 3.5 长查询优化（long_query）
-- 当前已禁用（参考实现中也是 False）
-- 未来可根据需要启用
+这保证了“必须翻译才能检索”的场景不会直接空跑。
-#### 3.6 KNN 向量召回自适应策略（query_tokens）
+## 4. 统一文本召回表达式
-根据 `query_tokens`（HanLP 分词后的 token 数量）动态调整 KNN 的召回数量和权重：
+每个语言子句的基础形态：
-| 查询类型 | token_count | knn_k | num_candidates | boost 系数 |
-|---------|-------------|-------|----------------|------------|
-| 短查询  | ≤ 2         | 30    | 100            | 0.6× 默认  |
-| 中等查询| 3～4        | 50    | 200            | 1.0× 默认  |
-| 长查询  | ≥ 5         | 80    | 300            | 1.4× 默认  |
+```json
+{
+  "multi_match": {
+    "_name": "base_query|base_query_trans_xx|fallback_original_query_xx",
+    "query": "<text>",
+    "fields": ["title.xx^3.0", "brief.xx^1.5", "...", "tags", "option1_values^0.5", "..."],
+    "minimum_should_match": "75%",
+    "tie_breaker": 0.9,
+    "boost": "<按策略决定，可省略>"
+  }
+}
+```
-**策略说明**：
-- **短查询**：BM25 对精确匹配更有效，降低 KNN 召回和权重，避免语义召回干扰
-- **长查询**：语义搜索更有利，提高 KNN 召回和权重，增强语义理解能力
-- 默认 boost 由 `config.query_config.knn_boost` 配置（通常 0.25）
+最终按 `bool.should` 组合，`minimum_should_match: 1`。
-### 4. 字段映射优化
+## 5. 关键配置项（文本策略）
-新增 `_get_match_fields()` 方法，支持：
-- 根据语言动态获取匹配字段
-- 区分全部字段（all_fields）和核心字段（core_fields）
-- 核心字段用于短语查询和关键词查询，提高精度
+位于 `config/config.yaml -> query_config.text_query_strategy`：
-## 实现细节
+- `base_minimum_should_match`
+- `translation_minimum_should_match`
+- `translation_boost`
+- `translation_boost_when_source_missing`
+- `source_boost_when_missing`
+- `original_query_fallback_boost_when_translation_missing`（新增）
+- `keywords_boost`
+- `enable_phrase_query`
+- `tie_breaker_base_query`
+- `tie_breaker_keywords`
-### 文件修改清单
+新增项说明：
-1. **修改文件**：
-   - `query/query_parser.py` - 添加关键词提取、查询类型判断等功能（HanLP 可选）
-   - `search/es_query_builder.py` - 实现 should 子句的多查询策略
-   - `search/searcher.py` - 传递 parsed_query 给查询构建器
+- `original_query_fallback_boost_when_translation_missing`：  
+  当源语种不在索引语言且翻译缺失时，原文打到缺失目标语字段的低权重系数，默认 `0.2`。
-### 关键参数说明
+## 6. 典型场景与实际 DSL
-- **minimum_should_match**: 从 "67%" 提升到 "75%"，提高匹配精度
-- **operator**: 从默认改为 "AND"，确保所有词都匹配
-- **tie_breaker**: 保持 0.9，用于分数融合
-- **boost 值**：
-  - base_query: 1.0（默认）
-  - translation queries: 0.4
-  - phrase_query: 1.0
-  - keywords_query: 0.1
+以下示例来自当前 `ESQueryBuilder` 生成结果（已按当前代码验证）。
-### 依赖要求
+### 场景 A：源语种已在索引语言中，且翻译成功
-- **HanLP**（可选）：如果安装了 `hanlp` 包，会自动启用关键词提取功能
-  ```bash
-  pip install hanlp
-  ```
-  
-  如果未安装，系统会自动降级到简单分析（基于空格分词），不影响基本功能。
+- `detected_language=de`
+- `index_languages=[de,en]`
+- `query_text_by_lang={de:"herren schuhe", en:"men shoes"}`
-- **HanLP 模型**：首次运行时会自动下载
-  - Tokenizer: `CTB9_TOK_ELECTRA_BASE_CRF`
-  - POS Tagger: `CTB9_POS_ELECTRA_SMALL`
+策略结果：
-### 配置说明
+- `base_query`：德语字段，正常权重
+- `base_query_trans_en`：英语字段，`boost=translation_boost`（默认 0.4）
-- **忽略关键词**：在 `_extract_keywords()` 方法中配置
-  - 默认忽略：`['玩具']`
+### 场景 B：源语种不在索引语言中，部分翻译缺失
-## 使用示例
+- `detected_language=de`
+- `index_languages=[en,zh]`
+- 只翻译出 `en`，`zh` 失败
-### 基本使用
+策略结果：
-查询会自动使用优化后的策略，无需额外配置：
+- `base_query`（德语字段）：`boost=source_boost_when_missing`（默认 0.6）
+- `base_query_trans_en`（英文字段）：`boost=translation_boost_when_source_missing`（默认 1.0）
+- `fallback_original_query_zh`（中文字段）：原文低权重兜底（默认 0.2）
-```python
-# 在 searcher.py 中，查询会自动使用优化策略
-result = searcher.search(
-    query="戏水动物",
-    tenant_id="162",
-    size=10
-)
-```
+### 场景 C：源语种不在索引语言中，翻译全部失败
-### 查看分析结果
+- `detected_language=de`
+- `index_languages=[en,zh]`
+- `query_text_by_lang` 仅有 `de`
-可以直接从 `parsed_query` 查看分析结果：
+策略结果：
-```python
-parsed_query = query_parser.parse("戏水动物")
-print(f"关键词: {parsed_query.keywords}")
-print(f"Token数: {parsed_query.token_count}")
-print(f"query_tokens: {parsed_query.query_tokens}")
-```
+- `base_query`（德语字段，低权重）
+- `fallback_original_query_en`（英文字段原文兜底）
+- `fallback_original_query_zh`（中文字段原文兜底）
-## 性能考虑
+这能避免“只有源语种字段查询，且该语种字段在商家索引中稀疏/为空”导致的弱召回问题。
-1. **HanLP 初始化**：采用懒加载，首次使用时才初始化
-2. **错误处理**：HanLP 初始化失败或未安装时，系统会降级到简单分析（基于空格分词），不影响服务
-3. **代码精简**：所有功能直接集成在 `QueryParser` 中，无额外模块依赖
+## 7. QueryParser 与 ESBuilder 的职责分工
-## 后续优化方向
+- `QueryParser` 负责“语言计划”与“可用文本”：
+  - `search_langs`
+  - `query_text_by_lang`
+  - `source_in_index_languages`
+  - `index_languages`
+- `ESQueryBuilder` 负责“表达式展开”：
+  - 动态字段组装
+  - 子句权重分配
+  - 翻译缺失兜底子句拼接
-1. **长查询优化**：可以启用长查询的特殊处理
-2. **意图识别**：完善意图词典，提供更精准的意图识别
-3. **参数调优**：根据实际效果调整 boost 值和 minimum_should_match
-4. **A/B 测试**：对比优化前后的检索效果
+这种分层让策略调优主要落在配置和 Builder，不破坏 Parser 的职责边界。
-## 注意事项
+## 8. 兼容与注意事项
-1. **HanLP 依赖**：HanLP 是可选的，如果未安装或初始化失败，系统会自动降级到简单分析，不会影响基本功能
-2. **性能影响**：HanLP 分析会增加一定的处理时间，但采用懒加载机制
-3. **字段匹配**：确保 ES 索引中存在对应的中英文字段
-4. **代码精简**：所有功能都集成在现有模块中，保持代码结构简洁
+1. 当前文本主链路已移除布尔 AST 分支。  
+2. 文档中的旧描述（如 `operator: AND` 固定开启）不再适用，当前实现未强制设置该参数。  
+3. `HanLP` 为可选依赖；不可用时退化到轻量分词，不影响主链路可用性。  
+4. 若后续扩展到更多语种，请确保：
+   - mapping 中存在对应 `.<lang>` 字段
+   - `index_languages` 配置在支持列表内
+   - 翻译 provider 对目标语种可用
-## 参考
+## 9. 建议测试清单
-- 参考实现中的查询构建逻辑
-- HanLP 官方文档：https://hanlp.hankcs.com/
-- Elasticsearch multi_match 查询文档
+建议在 `tests/` 增加文本策略用例：
+1. 源语种在索引语言，翻译命中缓存  
+2. 源语种不在索引语言，翻译部分失败（验证 fallback 子句）  
+3. 源语种不在索引语言，翻译全部失败（验证多目标 fallback）  
+4. 自定义 `original_query_fallback_boost_when_translation_missing` 生效  
+5. 非 `zh/en` 语种字段动态拼接（如 `de/fr/es`）
@@ -0,0 +1,232 @@
+# 相关性检索优化说明
+
+## 概述
+
+本次优化将相关性检索从简单的 `must` 子句中的 `multi_match` 查询，改为使用 `should` 子句的多查询策略，参考了成熟的搜索实现，显著提升了检索效果。
+
+## 主要改进
+
+## 实现方式
+
+本次优化采用精简实现，直接在 `QueryParser` 中集成必要的分析功能，不新增独立模块。
+
+### 1. 查询结构优化
+
+**之前的结构**（效果差）：
+```json
+{
+  "bool": {
+    "must": [
+      {
+        "multi_match": {
+          "query": "戏水动物",
+          "fields": ["title.zh^3.0", "brief.zh^1.5", ...],
+          "minimum_should_match": "67%",
+          "tie_breaker": 0.9,
+          "boost": 1,
+          "_name": "base_query"
+        }
+      }
+    ]
+  }
+}
+```
+
+**优化后的结构**（效果更好）：
+```json
+{
+  "bool": {
+    "should": [
+      {
+        "multi_match": {
+          "_name": "base_query",
+          "fields": ["title.zh^3.0", "brief.zh^1.5", ...],
+          "minimum_should_match": "75%",
+          "operator": "AND",
+          "query": "戏水动物",
+          "tie_breaker": 0.9
+        }
+      },
+      {
+        "multi_match": {
+          "_name": "base_query_trans_en",
+          "boost": 0.4,
+          "fields": ["title.en^3.0", ...],
+          "minimum_should_match": "75%",
+          "operator": "AND",
+          "query": "water sports",
+          "tie_breaker": 0.9
+        }
+      },
+      {
+        "multi_match": {
+          "query": "戏水动物",
+          "fields": ["title.zh^3.0", "brief.zh^1.5", ...],
+          "type": "phrase",
+          "slop": 2,
+          "boost": 1.0,
+          "_name": "phrase_query"
+        }
+      },
+      {
+        "multi_match": {
+          "query": "戏水 动物",
+          "fields": ["title.zh^3.0", "brief.zh^1.5", ...],
+          "operator": "AND",
+          "tie_breaker": 0.9,
+          "boost": 0.1,
+          "_name": "keywords_query"
+        }
+      }
+    ],
+    "minimum_should_match": 1
+  }
+}
+```
+
+### 2. 集成查询分析功能
+
+在 `QueryParser` 中直接集成必要的分析功能：
+
+- **关键词提取**：使用 HanLP 提取查询中的名词（长度>1），用于关键词查询（可选，HanLP 不可用时降级）
+- **查询类型判断**：区分短查询和长查询
+- **Token 计数**：用于判断查询长度
+
+### 3. 多查询策略
+
+#### 3.1 基础查询（base_query）
+- 使用 `operator: "AND"` 确保所有词都必须匹配
+- `minimum_should_match: "75%"` 提高匹配精度
+- 使用 `tie_breaker: 0.9` 进行分数融合
+
+#### 3.2 翻译查询（base_query_trans_zh/en）
+- 当查询语言不是中文/英文时，添加翻译查询
+- 使用较低的 boost（0.4）避免过度影响
+- 支持跨语言检索
+
+#### 3.3 短语查询（phrase_query）
+- 针对短查询（token_count >= 2 且 is_short，由 query_tokens 推导）
+- 使用 `type: "phrase"` 进行精确短语匹配
+- 支持 slop（允许词序调整）
+
+#### 3.4 关键词查询（keywords_query）
+- 使用 HanLP 提取的名词进行查询
+- 仅在关键词长度合理时启用（避免关键词占查询比例过高）
+- 使用较低的 boost（0.1）作为补充
+
+#### 3.5 长查询优化（long_query）
+- 当前已禁用（参考实现中也是 False）
+- 未来可根据需要启用
+
+#### 3.6 KNN 向量召回自适应策略（query_tokens）
+
+根据 `query_tokens`（HanLP 分词后的 token 数量）动态调整 KNN 的召回数量和权重：
+
+| 查询类型 | token_count | knn_k | num_candidates | boost 系数 |
+|---------|-------------|-------|----------------|------------|
+| 短查询  | ≤ 2         | 30    | 100            | 0.6× 默认  |
+| 中等查询| 3～4        | 50    | 200            | 1.0× 默认  |
+| 长查询  | ≥ 5         | 80    | 300            | 1.4× 默认  |
+
+**策略说明**：
+- **短查询**：BM25 对精确匹配更有效，降低 KNN 召回和权重，避免语义召回干扰
+- **长查询**：语义搜索更有利，提高 KNN 召回和权重，增强语义理解能力
+- 默认 boost 由 `config.query_config.knn_boost` 配置（通常 0.25）
+
+### 4. 字段映射优化
+
+新增 `_get_match_fields()` 方法，支持：
+- 根据语言动态获取匹配字段
+- 区分全部字段（all_fields）和核心字段（core_fields）
+- 核心字段用于短语查询和关键词查询，提高精度
+
+## 实现细节
+
+### 文件修改清单
+
+1. **修改文件**：
+   - `query/query_parser.py` - 添加关键词提取、查询类型判断等功能（HanLP 可选）
+   - `search/es_query_builder.py` - 实现 should 子句的多查询策略
+   - `search/searcher.py` - 传递 parsed_query 给查询构建器
+
+### 关键参数说明
+
+- **minimum_should_match**: 从 "67%" 提升到 "75%"，提高匹配精度
+- **operator**: 从默认改为 "AND"，确保所有词都匹配
+- **tie_breaker**: 保持 0.9，用于分数融合
+- **boost 值**：
+  - base_query: 1.0（默认）
+  - translation queries: 0.4
+  - phrase_query: 1.0
+  - keywords_query: 0.1
+
+### 依赖要求
+
+- **HanLP**（可选）：如果安装了 `hanlp` 包，会自动启用关键词提取功能
+  ```bash
+  pip install hanlp
+  ```
+  
+  如果未安装，系统会自动降级到简单分析（基于空格分词），不影响基本功能。
+
+- **HanLP 模型**：首次运行时会自动下载
+  - Tokenizer: `CTB9_TOK_ELECTRA_BASE_CRF`
+  - POS Tagger: `CTB9_POS_ELECTRA_SMALL`
+
+### 配置说明
+
+- **忽略关键词**：在 `_extract_keywords()` 方法中配置
+  - 默认忽略：`['玩具']`
+
+## 使用示例
+
+### 基本使用
+
+查询会自动使用优化后的策略，无需额外配置：
+
+```python
+# 在 searcher.py 中，查询会自动使用优化策略
+result = searcher.search(
+    query="戏水动物",
+    tenant_id="162",
+    size=10
+)
+```
+
+### 查看分析结果
+
+可以直接从 `parsed_query` 查看分析结果：
+
+```python
+parsed_query = query_parser.parse("戏水动物")
+print(f"关键词: {parsed_query.keywords}")
+print(f"Token数: {parsed_query.token_count}")
+print(f"query_tokens: {parsed_query.query_tokens}")
+```
+
+## 性能考虑
+
+1. **HanLP 初始化**：采用懒加载，首次使用时才初始化
+2. **错误处理**：HanLP 初始化失败或未安装时，系统会降级到简单分析（基于空格分词），不影响服务
+3. **代码精简**：所有功能直接集成在 `QueryParser` 中，无额外模块依赖
+
+## 后续优化方向
+
+1. **长查询优化**：可以启用长查询的特殊处理
+2. **意图识别**：完善意图词典，提供更精准的意图识别
+3. **参数调优**：根据实际效果调整 boost 值和 minimum_should_match
+4. **A/B 测试**：对比优化前后的检索效果
+
+## 注意事项
+
+1. **HanLP 依赖**：HanLP 是可选的，如果未安装或初始化失败，系统会自动降级到简单分析，不会影响基本功能
+2. **性能影响**：HanLP 分析会增加一定的处理时间，但采用懒加载机制
+3. **字段匹配**：确保 ES 索引中存在对应的中英文字段
+4. **代码精简**：所有功能都集成在现有模块中，保持代码结构简洁
+
+## 参考
+
+- 参考实现中的查询构建逻辑
+- HanLP 官方文档：https://hanlp.hankcs.com/
+- Elasticsearch multi_match 查询文档
+
@@ -34,6 +34,7 @@ class ESQueryBuilder:
         translation_boost: float = 0.4,
         translation_boost_when_source_missing: float = 1.0,
         source_boost_when_missing: float = 0.6,
+        original_query_fallback_boost_when_translation_missing: float = 0.2,
         keywords_boost: float = 0.1,
         enable_phrase_query: bool = True,
         tie_breaker_base_query: float = 0.9,
@@ -72,6 +73,9 @@ class ESQueryBuilder:
         self.translation_boost = float(translation_boost)
         self.translation_boost_when_source_missing = float(translation_boost_when_source_missing)
         self.source_boost_when_missing = float(source_boost_when_missing)
+        self.original_query_fallback_boost_when_translation_missing = float(
+            original_query_fallback_boost_when_translation_missing
+        )
         self.keywords_boost = float(keywords_boost)
         self.enable_phrase_query = bool(enable_phrase_query)
         self.tie_breaker_base_query = float(tie_breaker_base_query)
@@ -476,6 +480,7 @@ class ESQueryBuilder:
         search_langs: List[str] = []
         source_lang = self.default_language
         source_in_index_languages = True
+        index_languages: List[str] = []
         keywords = ""
         query_tokens = []
         token_count = 0
@@ -488,6 +493,7 @@ class ESQueryBuilder:
             source_in_index_languages = bool(
                 getattr(parsed_query, "source_in_index_languages", True)
             )
+            index_languages = getattr(parsed_query, "index_languages", None) or []
             keywords = getattr(parsed_query, 'keywords', '') or ""
             query_tokens = getattr(parsed_query, 'query_tokens', None) or []
             token_count = len(query_tokens) or getattr(parsed_query, 'token_count', 0) or 0
@@ -543,6 +549,37 @@ class ESQueryBuilder:
                 "multi_match": clause["multi_match"]
             })
+        # Fallback: source language is not indexed and translation for some index languages is missing.
+        # Use original query text on missing index-language fields with a low boost.
+        if not source_in_index_languages and query_text and index_languages:
+            normalized_index_langs: List[str] = []
+            seen_langs = set()
+            for lang in index_languages:
+                norm_lang = str(lang or "").strip().lower()
+                if not norm_lang or norm_lang in seen_langs:
+                    continue
+                seen_langs.add(norm_lang)
+                normalized_index_langs.append(norm_lang)
+
+            for lang in normalized_index_langs:
+                if lang == source_lang:
+                    continue
+                if lang in query_text_by_lang:
+                    continue
+                match_fields, _ = self._get_match_fields(lang)
+                if not match_fields:
+                    continue
+                should_clauses.append({
+                    "multi_match": {
+                        "_name": f"fallback_original_query_{lang}",
+                        "query": query_text,
+                        "fields": match_fields,
+                        "minimum_should_match": self.translation_minimum_should_match,
+                        "tie_breaker": self.tie_breaker_base_query,
+                        "boost": self.original_query_fallback_boost_when_translation_missing,
+                    }
+                })
+
         # 3. Short query - add phrase query (derived from query_tokens)
         # is_short: quoted or ((token_count <= 2 or len <= 4) and no space)
         source_query_text = query_text_by_lang.get(source_lang) or query_text
@@ -122,6 +122,9 @@ class Searcher:
             translation_boost=self.config.query_config.translation_boost,
             translation_boost_when_source_missing=self.config.query_config.translation_boost_when_source_missing,
             source_boost_when_missing=self.config.query_config.source_boost_when_missing,
+            original_query_fallback_boost_when_translation_missing=(
+                self.config.query_config.original_query_fallback_boost_when_translation_missing
+            ),
             keywords_boost=self.config.query_config.keywords_boost,
             enable_phrase_query=self.config.query_config.enable_phrase_query,
             tie_breaker_base_query=self.config.query_config.tie_breaker_base_query,