ES 8.13.4 如何配置 IK 分词同义词库（附完整实战代码）-程序员充电站

这是一篇为您定制的技术博客，完全基于您提供的Jieba分词配置逻辑，并将其转换为适用于 Elasticsearch 8.13.4 和 IK分词器的实现方案。

在使用 Elasticsearch 进行中文搜索时，IK 分词器几乎是标配。但在实际业务中（如电商、内容搜索），用户输入的词和文档中的词往往不完全一致。例如用户搜“番茄”，但文档里写的是“西红柿”或“圣女果”。如果不能识别这些同义词，搜索体验会大打折扣。

本文将基于Elasticsearch 8.13.4，手把手教你如何配置 IK 分词器结合同义词库，实现搜索效果的质的飞跃。

1. 环境准备

Elasticsearch: 8.13.4

IK Analysis Plugin: 需提前安装

如果你还没安装，进入 ES 安装目录执行：

./bin/elasticsearch-plugininstallhttps://github.com/medcl/elasticsearch-analysis-ik/releases/download/v8.13.4/elasticsearch-analysis-ik-8.13.4.zip

安装后重启 ES。

2. 创建同义词库文件

首先，我们需要告诉 ES 哪些词是同义的。

进入 Elasticsearch 的安装目录，找到config文件夹。
在config目录下创建一个新的文件夹，命名为ik_synonyms（名字自取，方便识别即可）。
在config/ik_synonyms目录下创建一个文本文件，例如my_synonyms.txt。

文件内容格式（非常重要）：
每一行代表一组同义词，词与词之间用英文逗号,隔开。第一个词通常作为主词。

番茄,西红柿,圣女果 土豆,马铃薯,洋芋 计算机,电脑,pc

注意：ES 8.x 对文件路径的检查比较严格，建议使用classpath:路径或者绝对路径，但在config目录下通常可以直接通过文件名引用（视具体版本配置而定，为了保险，下文配置中会使用classpath方式的变体，实际上在 config 下创建文件夹后，直接写文件名通常也能被加载）。

3. 配置索引 Mapping 与 Analyzer

这是核心步骤。我们需要创建一个索引，在其中定义一个新的 Analyzer（分析器），该分析器使用 IK 分词器，并在其后叠加一个同义词过滤器（Synonym Token Filter）。

在 Kibana Dev Tools 中执行以下命令：

PUT/product_index{"settings":{"analysis":{"filter":{"my_synonym_filter":{"type":"synonym","synonyms_path":"ik_synonyms/my_synonyms.txt"}},"analyzer":{"ik_synonym_analyzer":{"type":"custom","tokenizer":"ik_max_word","filter":["my_synonym_filter"]},"ik_synonym_search_analyzer":{"type":"custom","tokenizer":"ik_max_word","filter":["my_synonym_filter"]}}}},"mappings":{"properties":{"name":{"type":"text","analyzer":"ik_synonym_analyzer","search_analyzer":"ik_synonym_search_analyzer"}}}}

配置解析：

filter部分：
- 定义了一个名为my_synonym_filter的过滤器。
- 类型为synonym，并指定了刚才创建的同义词文件路径ik_synonyms/my_synonyms.txt。
analyzer部分：
- 我们自定义了一个ik_synonym_analyzer。
- tokenizer: “ik_max_word”：使用 IK 分词的细粒度模式（也可以用ik_smart粗粒度）。
- filter: 将 IK 分词后的结果，传入我们的同义词过滤器。这意味着如果 IK 分出了“番茄”，过滤器会把它扩展成“番茄”、“西红柿”、“圣女果”三个 Token。
mappings部分：
- 将字段name的分析器设置为我们刚定义的ik_synonym_analyzer。

4. 插入测试数据

为了验证效果，我们插入几条包含同义词的数据：

POST/product_index/_doc/1{"name":"圣女果"}POST/product_index/_doc/2{"name":"番茄"}POST/product_index/_doc/3{"name":"番茄酱"}POST/product_index/_doc/4{"name":"西红柿炒鸡蛋"}POST/product_index/_doc/5{"name":"土豆丝"}

5. 实战搜索效果对比

现在到了见证奇迹的时刻。我们来搜索“番茄”，看看能不能把“圣女果”和“西红柿”都搜出来。

场景一：使用配置了同义词的索引搜索

GET/product_index/_search{"query":{"match":{"name":"番茄"}}}

预期结果：
你会发现文档 1（圣女果）、文档 2（番茄）、文档 3（番茄酱）、文档 4（西红柿炒鸡蛋）全部被命中。

原理分析：

搜索词“番茄”进入ik_synonym_search_analyzer。
IK 分词器将其分为["番茄"]。
同义词过滤器发现“番茄”在词库中，扩展为["番茄", "西红柿", "圣女果"]。
ES 去倒排索引中匹配这三个词，因此所有包含这三个词中任意一个的文档都被找出来了。

场景二：搜索“土豆”

GET/product_index/_search{"query":{"match":{"name":"土豆"}}}

结果：只命中文档 5（土豆丝）。
注：如果你希望“马铃薯”也能被搜到，记得在同义词文件里加一行土豆,马铃薯。

6. 进阶：同义词的扩展格式

IK 分词配合同义词过滤器非常强大，它支持 Solr 的同义词格式。

1. 显式映射（推荐）：
如果你只想让“番茄”能搜到“西红柿”，但不想让“西红柿”搜到“番茄”（单向），可以使用=>：

番茄 => 西红柿, 圣女果

2. 别名（Aliases）：
如果你希望“番茄”和“西红柿”完全等价，互搜互得，用逗号即可（如上文配置）。

3. 保持原词并扩展（默认）：
默认情况下，synonymfilter 会保留输入词。例如搜“番茄”，实际查询的是(番茄 | 西红柿 | 圣女果)。

7. 常见坑点排查

分词器不生效？
- 检查elasticsearch.yml中是否允许动态修改 analyzer（默认允许）。
- 使用_analyzeAPI 调试：
```
GET/product_index/_analyze{"analyzer":"ik_synonym_analyzer","text":"我要买番茄"}
```
  查看返回的 tokens 是否包含了同义词。
文件找不到报错？
- ES 8.x 对资源文件的隔离较严格。确保my_synonyms.txt在ES_HOME/config/ik_synonyms/下。
- 如果在 Docker 中运行，需要通过 Volume 挂载该文件到容器内的/usr/share/elasticsearch/config/ik_synonyms/。
重启问题：
- 修改同义词文件后，不需要重启 ES，但需要关闭并重新打开索引（Close/Open Index），或者重新创建索引，因为同义词规则是在索引创建时加载到倒排索引中的。