ai-saas / saas-search

相关性检索优化说明.md 8.23 KB

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

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（新增）
  • tie_breaker_base_query

新增项说明：

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

说明：

  • phrase_query / keywords_query 已从当前实现中移除，文本相关性只由 base_query、base_query_trans_*、fallback_original_query_* 三类子句组成。

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. 融合打分（Rerank + Text + KNN）

当前融合逻辑位于 search/rerank_client.py。

8.1 文本相关性大分

文本大分由三部分组成：

  • base_query
  • base_query_trans_*
  • fallback_original_query_*

聚合方式：

  1. source_score = base_query
  2. translation_score = max(base_query_trans_*)
  3. fallback_score = max(fallback_original_query_*)
  4. 加权：
    • weighted_source = source_score
    • weighted_translation = 0.8 * translation_score
    • weighted_fallback = 0.55 * fallback_score
  5. 合成：
    • primary = max(weighted_source, weighted_translation, weighted_fallback)
    • support = weighted_source + weighted_translation + weighted_fallback - primary
    • text_score = primary + 0.25 * support

如果以上子分都缺失，则回退到 ES _score 作为 text_score，避免纯文本召回被误打成 0。

8.2 最终融合公式

fused_score = (
    (rerank_score + 0.00001) *
    (text_score + 0.1) ** 0.35 *
    (knn_score + 0.6) ** 0.2
)

设计意图：

  • rerank_score 是主导信号
  • text_score 保留乘法增益，但通过较低指数避免词法高分过度放大
  • knn_score 保持弱参与，只作为语义召回补充

8.3 调试字段

开启 debug=true 后，debug_info.per_result 会暴露：

  • es_score
  • rerank_score
  • text_score
  • text_source_score
  • text_translation_score
  • text_fallback_score
  • text_primary_score
  • text_support_score
  • knn_score
  • fused_score
  • matched_queries

debug_info.query_analysis 还会暴露：

  • query_text_by_lang
  • search_langs
  • supplemental_search_langs

这些字段用于检索效果评估与 bad case 归因。

9. 兼容与注意事项

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

10. 评估与复现

建议使用项目根目录虚拟环境：

cd /data/saas-search
source ./activate.sh
python -m pytest -q tests/test_rerank_client.py tests/test_es_query_builder.py tests/test_search_rerank_window.py tests/test_query_parser_mixed_language.py
./scripts/service_ctl.sh restart backend
sleep 3
./scripts/service_ctl.sh status backend
python ./scripts/eval_search_quality.py

评估脚本会生成：

  • artifacts/search_eval/search_eval_*.json
  • artifacts/search_eval/search_eval_*.md

可直接从 JSON 中提取 query 级和 result 级调试字段进行分析。

11. 建议测试清单

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

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