# 相关性检索优化说明
  
  ## 概述
  
  本次优化将相关性检索从简单的 `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 (e.g. animals playing with water)",
            "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）
  - 使用 `type: "phrase"` 进行精确短语匹配
  - 支持 slop（允许词序调整）
  
  #### 3.4 关键词查询（keywords_query）
  - 使用 HanLP 提取的名词进行查询
  - 仅在关键词长度合理时启用（避免关键词占查询比例过高）
  - 使用较低的 boost（0.1）作为补充
  
  #### 3.5 长查询优化（long_query）
  - 当前已禁用（参考实现中也是 False）
  - 未来可根据需要启用
  
  ### 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"短查询: {parsed_query.is_short_query}")
  print(f"长查询: {parsed_query.is_long_query}")
  ```
  
  ## 性能考虑
  
  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 查询文档