# Suggestion 模块说明

  `suggestion/` 目录负责搜索框自动补全能力，当前实现只关注 suggestion 本身：离线构建建议词索引，在线根据输入前缀返回建议词列表。

  这份 README 以当前代码实现为准，重点说明模块现状、关键设计、索引结构、构建发布方式，以及在线检索和排序细节。

  ## 1. 当前能力边界

  - 对外接口：`GET /search/suggestions`
  - 输入参数：`q`、`size`、`language`
  - Header：`X-Tenant-ID`
  - 返回内容：建议词列表 `suggestions[]`
  - 不做商品结果拼接，也不走二次商品查询链路
  
  当前模块由三部分组成：
  
  1. 离线构建：从商品索引和搜索日志构建 suggestion 文档
  2. 索引发布：写入版本化索引，并通过 alias 原子切换
  3. 在线查询：优先走 completion，必要时再走 `search_as_you_type` 兜底召回
  
  ## 2. 目录与关键代码
  
  - [builder.py](/data/saas-search/suggestion/builder.py)：离线构建、增量更新、alias 发布、meta 状态维护
  - [mapping.py](/data/saas-search/suggestion/mapping.py)：suggestion 索引 settings 和 mappings 生成
  - [service.py](/data/saas-search/suggestion/service.py)：在线查询服务，负责语言归一化、双路召回、去重和最终排序
  - [RUNBOOK.md](/data/saas-search/suggestion/RUNBOOK.md)：构建、发布、验证操作说明
  - [TROUBLESHOOTING.md](/data/saas-search/suggestion/TROUBLESHOOTING.md)：常见问题排查
  
  命令入口在 [main.py](/data/saas-search/main.py) 中的 `build-suggestions` 子命令。
  
  ## 3. 整体架构
  
  在线路径：
  
  `Client -> /search/suggestions -> SuggestionService -> Elasticsearch suggestion alias`
  
  离线路径：
  
  `商品索引 + 搜索日志 -> SuggestionIndexBuilder -> 版本化 suggestion index -> alias publish`
  
  设计上有几个核心点：
  
  - suggestion 独立建索引，不依赖在线商品检索
  - 每个租户单独维护 suggestion alias，避免租户间相互影响
  - 全量构建写新索引，切换 alias 时零停机
  - 增量更新只处理 query log 增量，减少重建成本
  
  ## 4. 索引组织与发布
  
  索引命名在 [builder.py](/data/saas-search/suggestion/builder.py) 中统一定义：
  
  - 读别名：`{ES_INDEX_NAMESPACE}search_suggestions_tenant_{tenant_id}_current`
  - 版本索引：`{ES_INDEX_NAMESPACE}search_suggestions_tenant_{tenant_id}_v<timestamp>`
  - 元信息索引：`{ES_INDEX_NAMESPACE}search_suggestions_meta`
  
  当前实现是“每租户一个 suggestion alias + 多个版本索引”的模式，而不是环境级共享大索引。
  
  全量构建时的发布流程：
  
  1. 创建新的版本化索引
  2. 写入本次构建出的 suggestion 文档
  3. 校验新索引可分配、可读
  4. alias 原子切换到新索引
  5. 清理旧版本索引，只保留最近若干份
  6. 更新 `search_suggestions_meta`
  
  元信息索引里记录：
  
  - `active_alias`
  - `active_index`
  - `last_full_build_at`
  - `last_incremental_build_at`
  - `last_incremental_watermark`
  
  这些信息主要服务于增量更新和排障。
  
  ## 5. Mapping 与索引字段
  
  [mapping.py](/data/saas-search/suggestion/mapping.py) 会根据租户的 `index_languages` 动态生成字段。
  
  ### 5.1 索引设置
  
  - `number_of_shards = 1`
  - `number_of_replicas = 0`
  - `refresh_interval = 30s`
  
  中文使用自定义 analyzer：
  
  - `index_ik`：`ik_max_word + lowercase + asciifolding`
  - `query_ik`：`ik_smart + lowercase + asciifolding`
  
  其他语言优先使用 Elasticsearch 内置 analyzer，例如 `english`、`arabic`、`french`、`german` 等；未覆盖语言回退到 `standard`。
  
  ### 5.2 核心字段
  
  - `tenant_id`：租户隔离
  - `lang`：建议词所属语言
  - `text`：原始展示文本
  - `text_norm`：归一化文本，用于唯一键和去重
  - `sources`：来源集合，可能包含 `title`、`qanchor`、`tag`、`query_log`
  - `title_doc_count` / `qanchor_doc_count` / `tag_doc_count`：该词被多少商品字段支撑
  - `query_count_7d` / `query_count_30d`：近 7/30 天搜索热度
  - `rank_score`：离线预计算排序分
  - `lang_confidence` / `lang_source` / `lang_conflict`：语言识别与冲突信息
  - `status`：当前是否有效
  - `updated_at`：最近更新时间
  
  ### 5.3 两类检索字段
  
  1. `completion.<lang>`
  2. `sat.<lang>`
  
  `completion.<lang>` 用于极速前缀补全，是短 query 下的主召回通道。
  
  `sat.<lang>` 使用 `search_as_you_type`，用于多词前缀和 completion 未补足时的兜底召回。
  
  也就是说，当前线上不是只靠一种召回方式，而是 completion 优先、SAT 补全。
  
  ## 6. 候选词从哪里来
  
  [builder.py](/data/saas-search/suggestion/builder.py) 在全量构建中会聚合两大类数据源。
  
  ### 6.1 商品侧
  
  从租户商品索引中流式读取：
  
  - `title`
  - `qanchors`
  - `enriched_tags`
  
  处理方式：
  
  - `title.<lang>`：经 `_prepare_title_for_suggest()` 裁剪后作为候选词
  - `qanchors.<lang>`：按分隔符拆分后作为候选词
  - `enriched_tags`：支持多语言对象或普通列表，必要时做语言识别
  
  商品扫描不是一次性全量拉入内存，而是通过 `search_after` 分批读取，这一点在 [_iter_products()](/data/saas-search/suggestion/builder.py#L363) 已实现。
  
  ### 6.2 搜索日志侧
  
  从 MySQL `shoplazza_search_log` 中按时间窗口流式读取：
  
  - `query`
  - `language`
  - `request_params`
  - `create_time`
  
  读取方式使用 `stream_results=True + fetchmany()`，避免 `fetchall()` 带来的内存风险，这也是当前实现相对旧方案的重要改进。
  
  搜索日志主要用于补充：
  
  - 用户真实搜索词
  - 近 7/30 天热度
  - 语言归属信息
  
  ## 7. 文本清洗与语言策略
  
  ### 7.1 文本归一化
  
  在 [_normalize_text()](/data/saas-search/suggestion/builder.py#L176) 中，当前实现会做：
  
  - Unicode `NFKC` 归一化
  - 去首尾空白
  - 转小写
  - 多空白折叠为单空格
  
  这份 `text_norm` 是 suggestion 文档的稳定键的一部分，文档 `_id` 形式为：
  
  `{tenant_id}|{lang}|{text_norm}`
  
  这保证了同租户、同语言、同一归一化词面只会保留一份文档。
  
  ### 7.2 噪声过滤
  
  在 [_looks_noise()](/data/saas-search/suggestion/builder.py#L264) 中，以下内容会被过滤：
  
  - 空文本
  - 长度超过 120
  - 全部由符号组成的文本

  ### 7.3 语言判定优先级

  日志 query 的语言归属由 [_resolve_query_language()](/data/saas-search/suggestion/builder.py#L299) 负责，优先级是：

  1. `shoplazza_search_log.language`
  2. `request_params.language`
  3. `detect_text_language_for_suggestions()`
  4. 租户 `primary_language`
  
  同时会记录：
  
  - `lang_source`：语言来自哪里
  - `lang_confidence`：识别置信度
  - `lang_conflict`：日志语言与请求语言是否冲突
  
  在线查询侧在 [_resolve_language()](/data/saas-search/suggestion/service.py#L24) 也会做一次语言归一化，确保查询只打到租户允许的 `index_languages`。
  
  ## 8. 排序与 rank 细节
  
  当前排序分成两层：离线 `rank_score`，以及在线最终排序。
  
  ### 8.1 离线 `rank_score`
  
  在 [_compute_rank_score()](/data/saas-search/suggestion/builder.py#L338) 中，当前公式是：
  
  ```text
  rank_score =
    1.8 * log1p(query_count_30d)
    + 1.2 * log1p(query_count_7d)
    + 1.0 * log1p(qanchor_doc_count)
    + 0.85 * log1p(tag_doc_count)
    + 0.6 * log1p(title_doc_count)
  ```
  
  含义上是：
  
  - 搜索日志热度权重大于商品静态字段
  - 30 天热度权重大于 7 天热度，但 7 天热度也会强化近期趋势
  - `qanchor` 比普通标题更像“可搜索表达”，所以权重更高
  - `tag` 次之
  - `title` 提供基础覆盖，但权重相对更低
  
  这个分数会被写入：
  
  - 文档字段 `rank_score`
  - `completion.<lang>.weight`
  
  因此它同时影响 completion 通道和 SAT 通道。
  
  ### 8.2 在线召回排序
  
  [service.py](/data/saas-search/suggestion/service.py) 中的在线策略如下：
  
  1. 先查 `completion.<lang>`
  2. 若 query 长度大于 2 且 completion 结果不足，再查 `sat.<lang>`
  3. 按 `text` 归一化结果去重
  4. 最终排序后截断
  
  completion 通道本身依赖 ES completion 的 `_score`；SAT 通道则用 `function_score + field_value_factor(rank_score)`。
  
  最终排序由 [_finalize_suggestion_list()](/data/saas-search/suggestion/service.py#L155) 负责，排序 key 为：
  
  1. `score * 长度惩罚系数`
  2. `rank_score`
  
  长度惩罚定义在 [_suggestion_length_factor()](/data/saas-search/suggestion/service.py#L16)：
  
  ```text
  length_factor = 1 / sqrt(token_len)
  ```
  
  这意味着在分数相近时，较短、较直接的 suggestion 会更容易排在前面，避免长尾长句把前缀补全结果“顶掉”。
  
  ## 9. 在线查询细节
  
  [SuggestionService.search()](/data/saas-search/suggestion/service.py#L110) 的行为可以概括为：
  
  - 如果 alias 不存在，直接返回空数组，不抛 500
  - 短 query 优先走 completion 快速返回
  - 对于更长 query，再补一次 `bool_prefix`
  - 查询时始终带 `routing=tenant_id`
  
  这里的 `routing` 很重要，它保证 suggestion 查询尽量只落在目标租户对应的分片路由上，减少无效 fan-out。
  
  SAT 查询部分还有两个显式过滤条件：
  
  - `lang == resolved_language`
  - `status == 1`
  
  这能保证召回结果只来自当前语言、当前有效文档。
  
  ## 10. 全量构建与增量更新
  
  ### 10.1 全量构建
  
  入口在 [main.py](/data/saas-search/main.py#L104) 的 `build-suggestions --mode full`。
  
  行为是：
  
  1. 读取租户配置中的 `index_languages` 和 `primary_language`
  2. 创建新版本索引并等待 ready
  3. 聚合商品数据和搜索日志，构造候选词
  4. 计算 `rank_score`
  5. bulk 写入新索引
  6. refresh
  7. 发布 alias
  8. 更新 meta 信息
  
  ### 10.2 增量更新
  
  入口在 [main.py](/data/saas-search/main.py#L104) 的 `build-suggestions --mode incremental`。
  
  当前增量只处理 query log，不回扫商品数据。它依赖 meta 中的 watermark：
  
  - `last_incremental_watermark`
  - 不存在时回退到 `last_full_build_at`
  - 再不行就使用 `fallback_days`
  
  为了避免边界时间漏数，会额外减去 `overlap_minutes`，形成一个带重叠窗口的增量区间。
  
  增量写入不是整文档重建，而是通过 `scripted_upsert` 做原地累加：
  
  - 增加 `query_count_30d`
  - 增加 `query_count_7d`
  - 更新 `lang_confidence` / `lang_source` / `lang_conflict`
  - 重新计算 `rank_score`
  - 更新 `completion` 和 `sat`
  
  对应逻辑在 [_build_incremental_update_script()](/data/saas-search/suggestion/builder.py#L834)。
  
  如果 alias 尚不存在，而 `bootstrap_if_missing=True`，增量任务会先自动做一次全量构建作为初始化。
  
  ## 11. 当前实现的一些取舍
  
  ### 11.1 优点
  
  - 在线链路很短，没有 suggestion 后再查商品的放大成本
  - 构建和发布流程清晰，支持零停机切换
  - 商品侧和日志侧都采用流式处理，能控制内存占用
  - completion + SAT 双路召回兼顾低延迟和补全能力
  - 语言、热度、来源信息都保存在索引中，便于后续优化
  
  ### 11.2 现阶段边界
  
  - 增量更新目前只增量处理 query log，商品标题、qanchor、tag 变更仍依赖全量构建刷新
  - `rank_score` 目前只使用热度和商品字段覆盖度，没有接入点击、转化等行为质量信号
  - 文本归一化目前以 `NFKC + lower + whitespace fold` 为主，尚未做更激进的跨语种归并策略
  - `number_of_replicas=0` 更偏开发或成本优先配置，生产是否需要副本要结合集群策略评估
  
  ## 12. 常用命令
  
  全量构建：

  
  ```bash

  ./scripts/build_suggestions.sh <tenant_id> --mode full

  ```
  

  增量构建：

  
  ```bash

  ./scripts/build_suggestions.sh <tenant_id> --mode incremental

  ```
  

  一键重建并验证：

  ```bash
  ./scripts/rebuild_suggestions.sh <tenant_id>
  ```

  接口示例：

  
  ```bash

  curl "http://localhost:6002/search/suggestions?q=shi&size=10&language=en" \
    -H "X-Tenant-ID: 162"

  ```

  
  更多操作细节见 [RUNBOOK.md](/data/saas-search/suggestion/RUNBOOK.md)，故障排查看 [TROUBLESHOOTING.md](/data/saas-search/suggestion/TROUBLESHOOTING.md)。