多值字段词向量高亮模式配置

配置项作用 #

search.highlight.term_vector_multi_value 配置项用于控制多值字段的离散高亮处理模式。

当设置为 true（默认值）时，启用离散多值高亮模式，将每个值独立处理；当设置为 false 时，将所有值合并为一个连续的字符串进行处理。

配置项属性 #

• 配置路径: search.highlight.term_vector_multi_value
• 数据类型: Boolean（布尔值）
• 默认值: true
• 是否可选: 是
• 作用域: NodeScope（节点级别）
• 动态更新: 是（可以动态更新，无需重启）

配置项详解 #

工作机制 #

多值字段高亮处理

数据示例:
{
  "tags": ["java", "python", "javascript"],
  "content": ["Hello world", "Foo bar"]
}


term_vector_multi_value: true (默认，离散模式):

tags 字段高亮:
├── 值 1: "java"
│   └── 高亮: <em>java</em> ✅
│
├── 值 2: "python"
│   └── 高亮: <em>python</em> ✅
│
└── 值 3: "javascript"
    └── 高亮: <em>javascript</em> ✅


特点:
├── 每个值独立处理
├── 高亮不跨越值边界
├── 保持值的语义完整性
└── 精确控制高亮位置


term_vector_multi_value: false (连续模式):

tags 字段处理:
├── 合并: "java python javascript"
├── 使用分隔符连接 (空格)
├── 整体作为字符串高亮
└── 高亮可能跨越原值边界


特点:
├── 值合并为连续字符串
├── 高亮可以跨越边界
├── 可能产生不精确的高亮
└── 丢失值的独立性

字段要求 #

启用词向量高亮的条件

字段映射要求:
{
  "mappings": {
    "properties": {
      "content": {
        "type": "text",
        "term_vector": "with_positions_offsets"  ✅ 必需
      }
    }
  }
}


必需条件:
├── 1. term_vector: 必须启用
│   ├── with_positions_offsets ✅
│   ├── with_positions_offsets_payloads ✅
│   └── 其他模式 ❌
│
├── 2. 索引词向量信息
│   ├── 位置信息 (positions)
│   └── 偏移信息 (offsets)
│
└── 3. 使用 FastVectorHighlighter
    ├── 不适用于 standard highlighter
    ├── 不适用于 unified highlighter
    └── 专用于 FVH

高亮效果对比 #

实际效果对比

文档数据:
{
  "descriptions": [
    "Elasticsearch is a search engine",
    "built on Lucene",
    "for distributed search"
  ]
}


查询: highlight on "search"


term_vector_multi_value: true:

结果:
{
  "descriptions": [
    "Elasticsearch is a <em>search</em> engine",  ✅
    "built on Lucene",                                    ✅
    "for distributed <em>search</em>"              ✅
  ]
}


特点:
├── 只高亮匹配的值
├── 不匹配的值保持原样
├── 保持值的独立性
└── 结果清晰准确


term_vector_multi_value: false:

结果 (可能的输出):
{
  "descriptions": [
    "Elasticsearch is a <em>search</em> engine built on Lucene for distributed <em>search</em>"
  ]
}


特点:
├── 值被合并
├── 丢失原始结构
├── 高亮可能不准确
└── 不推荐使用

实现原理 #

FastVectorHighlighter 实现

高亮处理流程:

1. 读取词向量数据
   ├── 获取位置信息
   ├── 获取偏移信息
   └── 分析字段结构


2. 应用离散模式设置
   ├── term_vector_multi_value: true
   │   ├── 调用 discreteMultiValueHighlighting()
   │   ├── 处理每个值独立高亮
   │   └── 保持值边界
   │
   └── term_vector_multi_value: false
       ├── 跳过离散模式
       ├── 合并所有值
       └── 整体高亮


3. 生成高亮片段
   ├── 创建 FragmentsBuilder
   ├── 设置离散模式标志
   └── 构建高亮结果


代码位置:
├── FastVectorHighlighter 类
├── SETTING_TV_HIGHLIGHT_MULTI_VALUE
├── fragmentsBuilderSupplier 方法
└── builder.setDiscreteMultiValueHighlighting()

配置建议 #

生产环境（默认推荐） #

search:
  highlight:
    term_vector_multi_value: true  # 离散模式（默认）

建议: 大多数场景使用默认值，保持高亮准确性。

特殊场景（连续模式） #

search:
  highlight:
    term_vector_multi_value: false  # 连续模式

建议: 仅在需要合并多值处理的特殊场景使用。

动态更新 #

PUT /_cluster/settings
{
  "transient": {
    "search.highlight.term_vector_multi_value": false
  }
}

代码示例 #

基础配置 #

search:
  highlight:
    term_vector_multi_value: true

完整高亮配置 #

search:
  highlight:
    term_vector_multi_value: true
    max_analyzed_offset: 1000000

字段映射配置 #

PUT /test_index
{
  "mappings": {
    "properties": {
      "tags": {
        "type": "text",
        "term_vector": "with_positions_offsets"
      },
      "content": {
        "type": "text",
        "term_vector": "with_positions_offsets"
      }
    }
  }
}

查询示例 #

GET /test_index/_search
{
  "query": {
    "match": { "tags": "java" }
  },
  "highlight": {
    "fields": {
      "tags": {
        "type": "fvh",
        "order": "score"
      }
    }
  }
}

多字段高亮 #

GET /test_index/_search
{
  "query": {
    "multi_match": {
      "query": "search engine",
      "fields": ["title", "tags", "content"]
    }
  },
  "highlight": {
    "fields": {
      "title": { "type": "fvh" },
      "tags": { "type": "fvh" },
      "content": { "type": "fvh" }
    }
  }
}

相关配置 #

注意事项 #

1. 默认值: 默认值为 true，推荐使用。

2. 动态更新: 支持动态更新，无需重启。

3. 字段要求: 必须使用 with_positions_offsets 的 term_vector。

4. 仅限 FVH: 只对 FastVectorHighlighter 有效。

5. 性能影响: 离散模式需要额外计算，但结果更准确。

6. 数据结构: true 模式保持原始数据结构，false 模式可能改变。

7. 结果准确性: 离散模式提供更准确的高亮结果。

8. 测试验证: 切换模式后应验证高亮结果。

9. 多语言支持: 配置不影响多语言文本的处理。

10. 最佳实践: 大多数场景保持默认值 true。

使用场景 #

场景选择指南

标签/关键词数组:
├── 推荐模式: true (离散)
├── 数据: ["java", "python", "javascript"]
├── 需求: 每个标签独立高亮
└-- 原因: 保持标签语义完整性


内容片段数组:
├── 推荐模式: true (离散)
├── 数据: ["段落1", "段落2", "段落3"]
├── 需求: 独立高亮每个段落
└-- 原因: 保持内容结构


短文本数组:
├── 推荐模式: true (离散)
├── 数据: ["标题1", "标题2", "标题3"]
├── 需求: 精确高亮匹配项
└-- 原因: 准确性优先


特殊合并需求 (罕见):
├── 可用模式: false (连续)
├── 场景: 需要将数组视为整体
├── 风险: 高亮可能不准确
└-- 慎重使用 ⚠️

故障排查 #

高亮问题排查

问题: 多值字段没有高亮

排查:
├── 检查字段映射
│   ├── term_vector 是否设置
│   ├── 是否为 with_positions_offsets
│   └── 字段类型是否正确
│
├── 检查 highlighter 类型
│   ├── 是否使用 fvh
│   └── type: "fvh"
│
├── 检查查询字段
│   ├── 是否查询了正确的字段
│   └── 字段名是否匹配
│
└── 检查配置
    ├── term_vector_multi_value 设置
    └── 节点配置是否生效


解决:
├── 设置正确的 term_vector
├── 使用 type: "fvh"
├── 验证字段映射
└-- 检查配置值


问题: 高亮结果不准确

排查:
├── term_vector_multi_value 值
├── 是否误设为 false
└-- 数据结构是否符合预期


解决:
├── 恢复为 true (推荐)
├-- 重新索引数据
└-- 验证结果

最佳实践 #

多值高亮最佳实践

1. 字段映射
   ├── 使用 with_positions_offsets
   ├── 确保正确索引
   └-- 定期验证映射


2. 保持默认配置
   ├── term_vector_multi_value: true
   ├── 提供最佳结果
   ├── 保持数据完整性
   └-- 避免意外问题


3. 使用 FVH
   ├── type: "fvh"
   ├── 配合 term_vector
   ├── 性能优秀
   └-- 结果准确


4. 测试验证
   ├── 测试多值字段
   ├── 验证高亮结果
   ├── 检查边界情况
   └-- 性能测试


5. 监控性能
   ├── 监控高亮查询耗时
   ├── 分析资源使用
   ├── 优化慢查询
   └-- 定期审查配置