相关性检索优化说明（当前实现）

1. 文档目标

本文描述当前线上代码的文本检索策略，重点覆盖：

• 多语言检索路由（detector / translator / indexed 的关系）
• 统一文本召回表达式（无布尔 AST 分支）
• 翻译缺失时的兜底策略
• 典型场景下实际生成的 ES 查询结构

说明：向量召回（KNN）是另一维度，本篇仅简要提及，不展开。

2. 核心流程

查询链路（文本相关）：

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 枝路。

3. 能力矩阵（Detector / Translator / Indexed）

三类能力的职责边界：

• Detector：识别 query 源语言（detected_language）
• Indexed：租户可检索语言集合（tenant_config.*.index_languages）
• Translator：源语言到目标语言的可翻译能力及实时成功率

3.1 决策规则

1. 若 detected_language in index_languages：
   源语言字段做主召回；其他语言走翻译补召回（低权重）。
2. 若 detected_language not in index_languages：
   翻译到 index_languages 是主路径；源语言字段仅作弱召回。
3. 若第 2 步翻译部分失败或全部失败：
   对缺失翻译的 index_languages 字段，追加“原文低权重兜底”子句，避免完全丢失这些语种索引面的召回机会。

3.2 翻译等待策略

QueryParser.parse() 中：

• 当源语种不在 index_languages：使用 translate_multi_async(...) 并等待 futures 收敛
• 当源语种在 index_languages：使用 translate_multi(..., async_mode=True)，优先缓存命中，未命中可后台补齐

这保证了“必须翻译才能检索”的场景不会直接空跑。

4. 统一文本召回表达式

每个语言子句的基础形态：

{
  "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": "<按策略决定，可省略>"
  }
}

最终按 bool.should 组合，minimum_should_match: 1。

5. 关键配置项（文本策略）

位于 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

新增项说明：

• original_query_fallback_boost_when_translation_missing：
  当源语种不在索引语言且翻译缺失时，原文打到缺失目标语字段的低权重系数，默认 0.2。

6. 典型场景与实际 DSL

以下示例来自当前 ESQueryBuilder 生成结果（已按当前代码验证）。

场景 A：源语种已在索引语言中，且翻译成功

• detected_language=de
• index_languages=[de,en]
• query_text_by_lang={de:"herren schuhe", en:"men shoes"}

策略结果：

• base_query：德语字段，正常权重
• base_query_trans_en：英语字段，boost=translation_boost（默认 0.4）

场景 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）

场景 C：源语种不在索引语言中，翻译全部失败

• detected_language=de
• index_languages=[en,zh]
• query_text_by_lang 仅有 de

策略结果：

• base_query（德语字段，低权重）
• fallback_original_query_en（英文字段原文兜底）
• fallback_original_query_zh（中文字段原文兜底）

这能避免“只有源语种字段查询，且该语种字段在商家索引中稀疏/为空”导致的弱召回问题。

7. QueryParser 与 ESBuilder 的职责分工

• QueryParser 负责“语言计划”与“可用文本”：
  • search_langs
  • query_text_by_lang
  • source_in_index_languages
  • index_languages
• ESQueryBuilder 负责“表达式展开”：
  • 动态字段组装
  • 子句权重分配
  • 翻译缺失兜底子句拼接

这种分层让策略调优主要落在配置和 Builder，不破坏 Parser 的职责边界。

8. 兼容与注意事项

1. 当前文本主链路已移除布尔 AST 分支。
   
2. 文档中的旧描述（如 operator: AND 固定开启）不再适用，当前实现未强制设置该参数。
   
3. HanLP 为可选依赖；不可用时退化到轻量分词，不影响主链路可用性。
   
4. 若后续扩展到更多语种，请确保：
   • mapping 中存在对应 .<lang> 字段
   • index_languages 配置在支持列表内
   • 翻译 provider 对目标语种可用

9. 建议测试清单

建议在 tests/ 增加文本策略用例：

1. 源语种在索引语言，翻译命中缓存
   
2. 源语种不在索引语言，翻译部分失败（验证 fallback 子句）
   
3. 源语种不在索引语言，翻译全部失败（验证多目标 fallback）
   
4. 自定义 original_query_fallback_boost_when_translation_missing 生效
   
5. 非 zh/en 语种字段动态拼接（如 de/fr/es）