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

## 1. 文档目标

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

- 多语言检索路由（`detector` / `translator` / `indexed` 的关系）
- 统一文本召回表达式（无布尔 AST 分支）
- 解析层与检索表达式层的职责边界
- 重排融合打分与调试字段
- 典型场景下实际生成的 ES 查询结构

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

## 2. 核心流程

查询链路（文本相关）：

1. `QueryParser.parse()`  
   负责产出解析事实：`query_normalized`、`rewritten_query`、`detected_language`、`translations`、`query_vector`、`query_tokens`。
2. `Searcher.search()`  
   负责读取租户 `index_languages`，并将其传给 `QueryParser` 作为 `target_languages`（控制翻译目标语种）；`ESQueryBuilder` 仅根据 `detected_language` 与各条译文构建子句字段，不再接收 `index_languages`。
2. `ESQueryBuilder._build_advanced_text_query()`  
   基于 `rewritten_query + detected_language + translations + index_languages` 构建 `base_query` 与 `base_query_trans_*`；并按语言动态拼接 `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. 若翻译部分失败或全部失败：  
   当前实现不会再额外生成“原文打到其他语种字段”的兜底子句；系统保留 `base_query` 并继续执行，可观测性由 `translations` / warning / 命名子句分数提供。

### 3.2 翻译与向量：并发提交与共享超时

`QueryParser.parse()` 内对翻译与向量采用线程池提交 + **一次** `concurrent.futures.wait`：

- **翻译**：对调用方传入的 `target_languages` 中、除 `detected_language` 外的每个目标语种各提交一个 `translator.translate` 任务（多目标时并发执行）。
- **查询向量**：若开启 `enable_text_embedding`，再提交一个 `text_encoder.encode` 任务。
- 上述任务进入**同一** future 集合；例如租户索引为 `[zh, en]` 且检测语种**不在**索引内时，常为 **2 路翻译 + 1 路向量，共 3 个任务并发**，共用超时。

**等待预算（毫秒）**由 `detected_language` 是否属于调用方传入的 `target_languages` 决定（`query_config`）：

- **在索引内**：`translation_embedding_wait_budget_ms_source_in_index`（默认较短，如 80ms）— 主召回已能打在源语种字段，翻译/向量稍慢可容忍。
- **不在索引内**：`translation_embedding_wait_budget_ms_source_not_in_index`（默认较长，如 200ms）— 翻译对可检索文本更关键，给足时间。

超时未完成的任务会被丢弃并记 warning，解析继续（可能无部分译文或无数向量）。

## 4. 统一文本召回表达式

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

```json
{
  "multi_match": {
    "_name": "base_query|base_query_trans_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. 关键配置项（文本策略）

`query_config` 下与解析等待相关的项：

- `translation_embedding_wait_budget_ms_source_in_index`
- `translation_embedding_wait_budget_ms_source_not_in_index`

位于 `config/config.yaml -> query_config.text_query_strategy`：

- `base_minimum_should_match`
- `translation_minimum_should_match`
- `translation_boost`（所有 `base_query_trans_*` 共用）
- `tie_breaker_base_query`

说明：

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

## 6. 典型场景与实际 DSL

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

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

- `detected_language=de`
- `index_languages=[de,en]`
- `rewritten_query="herren schuhe"`
- `translations={en:"men shoes"}`

策略结果：

- `base_query`：德语字段，**不写** `multi_match.boost`
- `base_query_trans_en`：英语字段，`boost=translation_boost`（默认 0.4）

### 场景 B：源语种不在索引语言中，部分翻译缺失

- `detected_language=de`
- `index_languages=[en,zh]`
- 只翻译出 `en`，`zh` 失败

策略结果：

- `base_query`（德语字段）：**不写** `multi_match.boost`（默认 1.0）
- `base_query_trans_en`（英文字段）：`boost=translation_boost`（如 0.4）
- 不会生成额外中文兜底子句

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

- `detected_language=de`
- `index_languages=[en,zh]`
- `translations={}`

策略结果：

- `base_query`（德语字段，**无** `boost` 字段）
- 不会生成 `base_query_trans_*`

这意味着当前实现优先保证职责清晰与可解释性，而不是继续在 Builder 内部隐式制造“跨语种原文兜底”。

## 7. QueryParser 与 Searcher / ESBuilder 的职责分工

- `QueryParser` 负责“解析事实”：
  - `query_normalized`
  - `rewritten_query`
  - `detected_language`
  - `translations`
  - `query_vector`
  - `query_tokens`
- `Searcher` 负责“租户语境”：
  - `index_languages`
  - 将其传给 parser 作为 `target_languages`
- `ESQueryBuilder` 负责“表达式展开”：
  - 动态字段组装
  - 子句权重分配
  - `base_query` / `base_query_trans_*` 子句拼接
  - 跳过“与 base_query 文本和语言完全相同”的重复翻译子句

这种分层让 parser 不再返回 ES 专用的“语言计划字段”，职责边界更清晰。

## 8. 融合打分（Rerank + Text + KNN）

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

### 8.1 文本相关性大分

文本大分由两部分组成：

- `base_query`
- `base_query_trans_*`

聚合方式：

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

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

### 8.2 最终融合公式

```python
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_primary_score`
- `text_support_score`
- `knn_score`
- `fused_score`
- `matched_queries`

`debug_info.query_analysis` 还会暴露：

- `translations`
- `detected_language`
- `rewritten_query`

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

## 9. 兼容与注意事项

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

## 10. 评估与复现

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

```bash
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. 源语种不在索引语言，翻译部分失败（验证仅保留 `base_query` + 成功翻译子句）  
3. 源语种不在索引语言，翻译全部失败（验证无 `base_query_trans_*` 时仍可正常执行）  
4. 非 `zh/en` 语种字段动态拼接（如 `de/fr/es`）


# 搜索pipeline
**整体图**
这个 pipeline 现在可以理解成一条“先广召回，再逐层收窄、逐层加贵信号”的漏斗：

1. Query 解析
2. ES 召回
3. 粗排：只用 ES 内部文本/KNN 信号
4. 款式 SKU 选择 + title suffix
5. 精排：轻量 reranker + 文本/KNN 融合
6. 最终 rerank：重 reranker + fine score + 文本/KNN 融合
7. 分页、补全字段、格式化返回

主控代码在 [searcher.py](/data/saas-search/search/searcher.py)，打分与 rerank 细节在 [rerank_client.py](/data/saas-search/search/rerank_client.py)，配置定义在 [schema.py](/data/saas-search/config/schema.py) 和 [config.yaml](/data/saas-search/config/config.yaml)。

**先看入口怎么决定走哪条路**
在 [searcher.py:348](/data/saas-search/search/searcher.py#L348) 开始，`search()` 先读租户语言、开关、窗口大小。
关键判断在 [searcher.py:364](/data/saas-search/search/searcher.py#L364) 到 [searcher.py:372](/data/saas-search/search/searcher.py#L372)：

- `rerank_window` 现在是 80，见 [config.yaml:256](/data/saas-search/config/config.yaml#L256)
- `coarse_rank.input_window` 是 700，`output_window` 是 240，见 [config.yaml:231](/data/saas-search/config/config.yaml#L231)
- `fine_rank.input_window` 是 240，`output_window` 是 80，见 [config.yaml:245](/data/saas-search/config/config.yaml#L245)

所以如果请求满足 `from_ + size <= rerank_window`，就进入完整漏斗：
- ES 实际取前 `700`
- 粗排后留 `240`
- 精排后留 `80`
- 最终 rerank 也只处理这 `80`
- 最后再做分页切片

如果请求页超出 80，就不走后面的多阶段漏斗，直接按 ES 原逻辑返回。

这点非常重要，因为它决定了“贵模型只服务头部结果”。

**Step 1：Query 解析阶段**
在 [searcher.py:432](/data/saas-search/search/searcher.py#L432) 到 [searcher.py:469](/data/saas-search/search/searcher.py#L469)：
`query_parser.parse()` 做几件事：

- 规范化 query
- 检测语言
- 可能做 rewrite
- 生成文本向量
- 如果有图搜，还会带图片向量
- 生成翻译结果
- 识别 style intent

这一步的结果存在 `parsed_query` 里，后面 ES 查询、style SKU 选择、fine/final rerank 全都依赖它。

**Step 2：ES Query 构建**
ES DSL 在 [searcher.py:471](/data/saas-search/search/searcher.py#L471) 开始，通过 [es_query_builder.py:181](/data/saas-search/search/es_query_builder.py#L181) 的 `build_query()` 生成。

这里的核心结构是：
- 文本召回 clause
- 文本向量 KNN clause
- 图片向量 KNN clause
- 它们一起放进 `bool.should`
- 过滤条件放进 `filter`
- facet 的多选条件走 `post_filter`

KNN 部分在 [es_query_builder.py:250](/data/saas-search/search/es_query_builder.py#L250) 之后：
- 文本向量 clause 名字固定叫 `knn_query`
- 图片向量 clause 名字固定叫 `image_knn_query`

而文本召回那边，后续 fusion 代码约定会去读：
- 原始 query 的 named query：`base_query`
- 翻译 query 的 named query：`base_query_trans_*`

也就是说，后面的粗排/精排/最终 rerank，并不是重新理解 ES score，而是从 `matched_queries` 里把这些命名子信号拆出来自己重算。

**Step 3：ES 召回**
在 [searcher.py:579](/data/saas-search/search/searcher.py#L579) 到 [searcher.py:627](/data/saas-search/search/searcher.py#L627)。

这里有个很关键的工程优化：
如果在 rerank window 内，第一次 ES 拉取时会把 `_source` 关掉，只取排序必需信号，见 [searcher.py:517](/data/saas-search/search/searcher.py#L517) 到 [searcher.py:523](/data/saas-search/search/searcher.py#L523)。

原因是：
- 粗排先只需要 `_score` 和 `matched_queries`
- 不需要一上来把 700 条完整商品详情都拉回来
- 等粗排收窄后，再补 fine/final rerank 需要的字段

这是现在这条 pipeline 很核心的性能设计点。

**Step 4：粗排**
粗排入口在 [searcher.py:638](/data/saas-search/search/searcher.py#L638)，真正的打分在 [rerank_client.py:348](/data/saas-search/search/rerank_client.py#L348) 的 `coarse_resort_hits()`。

粗排只看两类信号：
- `text_score`
- `knn_score`

它们先都从统一 helper `_build_hit_signal_bundle()` 里拿，见 [rerank_client.py:246](/data/saas-search/search/rerank_client.py#L246)。

文本分怎么来，见 [rerank_client.py:200](/data/saas-search/search/rerank_client.py#L200)：
- `source_score = matched_queries["base_query"]`
- `translation_score = max(base_query_trans_*)`
- `weighted_translation = 0.8 * translation_score`
- `primary_text = max(source, weighted_translation)`
- `support_text = 另一路`
- `text_score = primary_text + 0.25 * support_text`

这就是一个 text dismax 思路：
原 query 是主路，翻译 query 是辅助路，但不是简单相加。

向量分怎么来，见 [rerank_client.py:156](/data/saas-search/search/rerank_client.py#L156)：
- `text_knn_score`
- `image_knn_score`
- 分别乘自己的 weight
- 取强的一路做主路
- 弱的一路按 `knn_tie_breaker` 做辅助

然后粗排融合公式在 [rerank_client.py:334](/data/saas-search/search/rerank_client.py#L334)：
- `coarse_score = (text_score + text_bias)^text_exponent * (knn_score + knn_bias)^knn_exponent`

配置定义在 [schema.py:124](/data/saas-search/config/schema.py#L124) 和 [config.yaml:231](/data/saas-search/config/config.yaml#L231)。

算完后：
- 写入 `hit["_coarse_score"]`
- 按 `_coarse_score` 排序
- 留前 240，见 [searcher.py:645](/data/saas-search/search/searcher.py#L645)

**Step 5：粗排后补字段 + SKU 选择**
粗排完以后，`searcher` 会按 doc template 反推 fine/final rerank 需要哪些 `_source` 字段，然后只补这些字段，见 [searcher.py:669](/data/saas-search/search/searcher.py#L669)。

之后才做 style SKU 选择，见 [searcher.py:696](/data/saas-search/search/searcher.py#L696)。

为什么放这里？
因为现在 fine rank 也是 reranker，它也要吃 title suffix。
而 suffix 是 SKU 选择之后写到 hit 上的 `_style_rerank_suffix`。
真正把 suffix 拼进 doc 文本的地方在 [rerank_client.py:65](/data/saas-search/search/rerank_client.py#L65) 到 [rerank_client.py:74](/data/saas-search/search/rerank_client.py#L74)。

所以顺序必须是：
- 先粗排
- 再选 SKU
- 再用带 suffix 的 title 去跑 fine/final rerank

**Step 6：精排**
入口在 [searcher.py:711](/data/saas-search/search/searcher.py#L711)，实现是 [rerank_client.py:603](/data/saas-search/search/rerank_client.py#L603) 的 `run_lightweight_rerank()`。

它会做三件事：

1. 用 `build_docs_from_hits()` 把每条商品变成 reranker 输入文本
2. 用 `service_profile="fine"` 调轻量服务
3. 不再只按 `fine_score` 排，而是按融合后的 `_fine_fused_score` 排

精排融合公式现在是：
- `fine_stage_score = fine_factor * text_factor * knn_factor * style_boost`

具体公共计算在 [rerank_client.py:286](/data/saas-search/search/rerank_client.py#L286) 的 `_compute_multiplicative_fusion()`：
- `fine_factor = (fine_score + fine_bias)^fine_exponent`
- `text_factor = (text_score + text_bias)^text_exponent`
- `knn_factor = (knn_score + knn_bias)^knn_exponent`
- 如果命中了 selected SKU，再乘 style boost

写回 hit 的字段见 [rerank_client.py:655](/data/saas-search/search/rerank_client.py#L655)：
- `_fine_score`
- `_fine_fused_score`
- `_text_score`
- `_knn_score`

排序逻辑在 [rerank_client.py:683](/data/saas-search/search/rerank_client.py#L683)：
按 `_fine_fused_score` 降序排，然后留前 80，见 [searcher.py:727](/data/saas-search/search/searcher.py#L727)。

这就是你这次特别关心的点：现在 fine rank 已经不是“模型裸分排序”，而是“模型分 + ES 文本/KNN 信号融合后排序”。

**Step 7：最终 rerank**
入口在 [searcher.py:767](/data/saas-search/search/searcher.py#L767)，实现是 [rerank_client.py:538](/data/saas-search/search/rerank_client.py#L538) 的 `run_rerank()`。

它和 fine rank 很像，但多了一个更重的模型分 `rerank_score`。
最终公式是：

- `final_score = rerank_factor * fine_factor * text_factor * knn_factor * style_boost`

也就是：
- fine rank 产生的 `fine_score` 不会丢
- 到最终 rerank 时，它会继续作为一个乘法项参与最终融合

这个逻辑在 [rerank_client.py:468](/data/saas-search/search/rerank_client.py#L468) 到 [rerank_client.py:476](/data/saas-search/search/rerank_client.py#L476)。

算完后写入：
- `_rerank_score`
- `_fused_score`

然后按 `_fused_score` 排序，见 [rerank_client.py:531](/data/saas-search/search/rerank_client.py#L531)。

这里你可以把它理解成：
- fine rank 负责“轻量快速筛一遍，把 240 缩成 80”
- 最终 rerank 负责“用更贵模型做最终拍板”
- 但最终拍板时，不会忽略 fine rank 结果，而是把 fine score 当成一个先验信号保留进去

**Step 8：分页与字段补全**
多阶段排序只在头部窗口内完成。
真正返回给用户前，在 [searcher.py:828](/data/saas-search/search/searcher.py#L828) 之后还会做两件事：

- 先按 `from_:from_+size` 对最终 80 条切片
- 再按用户原始 `_source` 需求补回页面真正要显示的字段，见 [searcher.py:859](/data/saas-search/search/searcher.py#L859)

所以这条链路是“三次不同目的的数据访问”：

- 第一次 ES：只要排序信号
- 第二次按 id 回填：只要 fine/final rerank 需要字段
- 第三次按页面 ids 回填：只要最终页面显示字段

这也是为什么它性能上比“一次全量拉 700 条完整文档”更合理。

**Step 9：结果格式化与 debug funnel**
最后在 [searcher.py:906](/data/saas-search/search/searcher.py#L906) 进入结果处理。
这里会把每个商品的阶段信息组装成 `ranking_funnel`，见 [searcher.py:1068](/data/saas-search/search/searcher.py#L1068)：

- `es_recall`
- `coarse_rank`
- `fine_rank`
- `rerank`
- `final_page`

其中：
- coarse stage 主要保留 text/translation/knn 的拆分信号
- fine/rerank stage 现在都保留 `fusion_inputs`、`fusion_factors`、`fusion_summary`
- `fusion_summary` 来自真实计算过程本身，见 [rerank_client.py:265](/data/saas-search/search/rerank_client.py#L265)

这点很重要，因为现在“实际排序逻辑”和“debug 展示逻辑”是同源的，不是两套各写一份。

**一句话总结这条 pipeline**
这条 pipeline 的本质是：

- ES 负责便宜的大范围召回
- 粗排负责只靠 ES 内置信号先做一次结构化筛选
- style SKU 选择负责把商品文本改造成更适合 reranker 理解的输入
- fine rank 负责用轻模型把候选进一步压缩
- final rerank 负责用重模型做最终判定
- 每一层都尽量复用前一层信号，而不是推翻重来

如果你愿意，我下一步可以继续按“一个具体 query 的真实流转样例”来讲，比如假设用户搜 `black dress`，我把它从 `parsed_query`、ES named queries、coarse/fine/final 的每个分数怎么出来，完整手推一遍。



## reranker方面：
BAAI/bge-reranker-v2-m3的一个严重badcase：
q=黑色中长半身裙

Rerank score: 0.0785
title.zh: 2026款韩版高腰显瘦雪尼尔包臀裙灯芯绒开叉中长款咖啡色半身裙女
title.en: 2026 Korean-style High-waisted Slimming Corduroy Skirt with Slit, Mid-Length Coffee-colored Skirt for Women

Rerank score: 0.9643
title.en: Black Half-high Collar Base Shirt Women's Autumn and Winter fleece-lined Contrast Color Pure Desire Design Sense Horn Sleeve Ruffled Inner Top
title.zh: 黑色高领半高领女士秋冬内搭加绒拼色纯欲设计荷叶边袖内衬上衣



qwen3-0.6b的严重badcase：
q=牛仔裤

Rerank score: 0.0002
title.en: Wrangler Womens Cowboy Cut Slim Fit Jean Bleach
title.zh: Wrangler 女士牛仔裤 牛仔剪裁 紧身版型 漂白色

Rerank score: 0.0168
title.en: Fleece Lined Tights Sheer Women - Fake Translucent Warm Pantyhose Leggings Sheer Thick Tights for Winter
title.zh: 加绒透肤女士连裤袜 - 仿透视保暖长筒袜 冬季厚款透肤连裤袜

Rerank score: 0.1366
title.en: Dockers Men's Classic Fit Workday Khaki Smart 360 FLEX Pants (Standard and Big & Tall)
title.zh: Dockers 男士经典版型工作日卡其色智能360度弹力裤（标准码与加大码）

Rerank score: 0.0981
title.en: Lazy One Pajama Shorts for Men, Men's Pajama Bottoms, Sleepwear
title.zh: 懒人男士睡裤，男式家居裤，睡眠服饰