文档首页/ 云搜索服务 CSS/ 用户指南/ Elasticsearch/ 搜索与分析/ 配置自定义词库

更新时间：2026-07-07 GMT+08:00

配置自定义词库

在日常搜索业务中，Elasticsearch的预置词库经常无法识别行业专有名词，如“云原生”会被切分为“云”、“原”、“生”，导致搜索召回率低、结果不精准；同时，“的”、“了”等无意义高频词如果未被过滤，会引入大量噪音、降低搜索效率；此外，用户搜索“开心”时会期望同时召回包含“高兴”等同义词的文档，但预置词库不具备同义词扩展能力。为此，CSS服务预置了IK分析插件（analysis-ik）和动态同义词插件（analysis-dynamic-synonym），通过配置自定义词库，让Elasticsearch精准识别业务关键词、过滤干扰词、扩展同义词，实现更智能、更贴合业务场景的搜索体验。

功能介绍

词库是指导分词器识别特殊词语的核心资源。CSS支持以下3类词库：

主词库：定义需要被识别为独立词语的特殊词（如“智能手机”、“喜大普奔”），避免被分词器按单字切分。
停词库：定义需要被过滤掉的无意义词（如“的”、“啦”），减少干扰。
同义词库：定义语义相同的词组（如“开心”=“高兴”），实现搜索扩展。

词库需要与分词器配合使用才能生效。CSS服务内置了默认分词器、IK分词器和同义词过滤器。IK分词器通过IK分析插件实现，同义词过滤器通过动态同义词插件实现。如表1所示，介绍了词库与分词器的对应关系。

表1 词库与分词器的关系
分词器名称	分词原理	词库依赖
默认分词器 Standard Analyzer	标准分析器，基于Unicode标准分词，自动转小写；中文按单字切分。示例：“华为云”切分为“华,为,云”；“Hello World”切分为“hello,world”。优势：配置简单，无需维护词库。缺点：中文分词效果一般。适用场景：西方语言索引，或对中文要求不高的场景。	无需词库
IK分词器 ik_smart	粗粒度分析器，仅生成最合理的分词结果，不穷举组合。示例：“昨夜西风吹折千林梢”切分为“昨夜西风,吹折千林梢”。优势：中文分词效果好，减少噪音，提升搜索精准度。缺点：可能会遗漏部分长尾词组合。适用场景：搜索查询阶段，用户搜索请求处理。	依赖主词库和停词库（有预置词库，也支持自定义词库）
IK分词器 ik_max_word	细粒度分析器，穷尽所有可能的词语组合，生成最细粒度的分词结果。示例：“昨夜西风吹折千林梢”切分为“昨夜西风,昨夜,西风,吹折千林梢,吹折,千林梢,千,林,折千林,千林,吹”。优势：中文分词效果好，覆盖更多词组合，提升搜索召回率。缺点：索引体积较大，写入性能略低。适用场景：数据写入阶段，全文检索的索引构建。	依赖主词库和停词库（有预置词库，也支持自定义词库）
同义词过滤器 dynamic_synonym	同义词扩展过滤器，动态加载同义词库，对分词结果进行语义扩展或纠错。示例：搜索“开心”，同时召回包含“开心”、“高兴”的文档。优势：实现同义词扩展搜索，提升搜索召回率。缺点：必须配合默认分词器或IK分词器使用。适用场景：语义扩展搜索，拼写纠错场景。	依赖同义词库（只支持自定义词库）

IK分词器主要用于中文分词，如果用于英文，仅#、&、+、-、.、@、_视为普通字符保留，其余特殊字符作为切分点将文本切分为独立词组。例如：

“access address: example@domain.com”切分为“access,address,example@domain.com”。
“set the parameter value to user|domain”切分为“set,parameter,value,user,domain”（the和to在预置的静态停词词库里，分词时会被过滤掉）。

自定义词库的工作原理

自定义词库的工作流程说明：

词库加载：用户将词库文件上传至OBS桶后，为集群配置词库，系统将词库加载至集群各节点。
主词库匹配：分词器优先按主词库中的词条进行整词切分，避免专有名词被拆散。
停词库过滤：分词结果中匹配到停词库的词条将被直接丢弃，不进入索引。
同义词扩展：分词结果经过同义词过滤器，匹配同义词库的词条会生成额外的同义Token，实现语义扩展搜索。
生效范围：词库更新后，新写入的数据自动使用新词库分词；历史索引数据不会自动重建，需手动执行_update_by_query 命令。

词库文件规范

请按以下规范准备词库文件，不满足要求将导致词库加载失败。

表2 词库文件规范
规范项	要求
文件格式	“.txt”
文件编码	UTF-8（无BOM）
内容格式	主词词库和停词词库一行一个词。示例：云计算搜索引擎同义词词库一行一组，双向同义词间以英文逗号“,”分隔，单向同义词间以“=>”分隔。示例：开心,高兴,愉快手机=>移动电话配置双向同义词时，搜索“开心”，会同时召回“开心”、“高兴”、“愉快”；配置单向同义词时，搜索“手机”，只召回“移动电话”。
英文单词	必须使用小写字母。
文件大小	单个文件不超过100MB。

约束限制

集群版本要求：2018年3月10日之前创建的集群，不支持自定义词库功能。

前提条件

目标集群处于“可用”状态，无正在进行中的任务。
确认操作账号已具备以下权限（可以在IAM服务的“权限管理 > 权限”中查看和配置）：
- 配置自定义词库的权限：
```
"css:IKThesaurus:*"
```
- 如果要更新词库，还需OBS桶及对象的读取权限：
```
obs:bucket:getBucketLocation
obs:bucket:getBucketStoragePolicy
obs:bucket:listAllMyBuckets
obs:object:getObject
```
- 如果OBS桶使用SSE-KMS加密模式时，还需KMS权限：
```
"kms:cmk:create",
"kms:dek:create",
"kms:cmk:get",
"kms:dek:decrypt",
"kms:cmk:list"
```
如果要更新词库，需要准备好符合规范的词库文件，并将词库文件上传至OBS桶。操作指导请参见上传文件。
OBS桶必须与CSS集群位于同一区域，且“存储类别”为“标准存储”。

进入自定义词库配置页面

登录云搜索服务管理控制台。
在左侧导航栏，选择“集群管理 > Elasticsearch”。
在集群列表，单击目标集群名称，进入集群详情页。
选择“集群配置 > 自定义词库”，进入自定义词库配置页面。

配置自定义词库

如果预置词库不满足业务分词需要，您可以配置自定义词库。

在自定义词库页面，根据业务需求配置自定义词库。

表3 配置自定义词库
参数名称	操作说明
OBS桶	选择词库文件所在的OBS桶。仅更新词库时才需配置。如果没有合适的OBS桶，可以单击“创建桶”跳转到OBS控制台创建OBS桶。具体操作请参见创建桶。
主词词库	自定义主词集合。初始状态为空。默认值：“不更新”，表示不配置该词库。新增/更新词库：选择“更新 > 选择”，选择OBS桶中符合规范的词库文件，单击“确定”。删除词库：单击“不使用此词库”，表示删除词库。
停词词库	自定义停词集合。初始状态为空。默认值：“不更新”，表示不配置该词库。新增/更新词库：选择“更新 > 选择”，选择OBS桶中符合规范的词库文件，单击“确定”。删除词库：单击“不使用此词库”，表示删除词库。
同义词词库	自定义同义词集合。初始状态为空。默认值：“不更新”，表示不配置该词库。新增/更新词库：选择“更新 > 选择”，选择OBS桶中符合规范的词库文件，单击“确定”。删除词库：单击“不使用此词库”，表示删除词库。

配置完成后，单击“保存”，在弹窗中单击“确定”，启动词库更新。
下方呈现词库配置信息。等待约1分钟，词库状态从“更新中”变更为“成功”，表示词库更新完成。

图1 词库状态
（可选）词库更新后，新写入数据将使用新词库分词；历史索引数据不会自动重建，如需重新分词入库，请手动执行以下命令。
```
POST /{my_index}/_update_by_query
```

更新预置词库

如需修改或禁用预置词库，您可以更新预置词库。

在自定义词库页面，打开“修改预置词库”右侧的开关。

如果界面不存在“修改预置词库”开关，则表示该集群版本不支持更新预置词库。建议升级集群版本，或者新建集群并进行数据迁移。

根据业务需求更新预置词库。

表4 更新预置词库
参数名称	操作说明
OBS桶	选择词库文件所在的OBS桶。仅更新词库时才需配置。如果没有合适的OBS桶，可以单击“创建桶”跳转到OBS控制台创建OBS桶。具体操作请参见创建桶。
静态主词词库	预置的常用主词集合。默认值：“不更新”，表示不配置该词库。更新词库：选择“更新 > 选择”，选择OBS桶中符合规范的词库文件，单击“确定”。删除词库：单击“不使用此词库”，表示删除词库。
静态停词词库	预置的常用停词集合。默认值：“不更新”，表示不配置该词库。更新词库：选择“更新 > 选择”，选择OBS桶中符合规范的词库文件，单击“确定”。删除词库：单击“不使用此词库”，表示删除词库。
Extra主词词库	预置的生僻主词集合。默认值：“不更新”，表示不配置该词库。更新词库：选择“更新 > 选择”，选择OBS桶中符合规范的词库文件，单击“确定”。删除词库：单击“不使用此词库”，表示删除词库。
Extra停词词库	预置的生僻停词集合。默认值：“不更新”，表示不配置该词库。更新词库：选择“更新 > 选择”，选择OBS桶中符合规范的词库文件，单击“确定”。删除词库：单击“不使用此词库”，表示删除词库。

配置完成后，单击“保存”，在弹窗中单击“确定”，启动词库更新。
下方呈现词库配置信息。等待约1分钟，词库状态从“更新中”变更为“需要重启”，表示词库更新完成。

图2 词库状态
词库更新完成后，单击页面右上角的“重启”，重启集群使预置词库的修改生效。操作指导请参见重启集群。
（可选）词库更新后，新写入数据将使用新词库分词；历史索引数据不会自动重建，如需重新分词入库，请手动执行以下命令。
```
POST /{my_index}/_update_by_query
```

验证主词和停词效果

主词库和停词库配置成功后，您可以通过/_analyze API测试文本的分词效果。

场景设定：主词词库中已添加“智能手机”，停词词库中已添加“是”。

在自定义词库页面，单击页面右上角的“Kibana”，登录Kibana。
在Kibana左侧导航栏选择“Dev Tools”，进入操作页面。

执行以下命令，查看ik_smart和ik_max_word的分词效果。

ik_smart（粗粒度）分词效果

请求示例：

POST /_analyze
{
  "analyzer":"ik_smart",
  "text":"智能手机是很好用"
}

预期结果：“智能手机”被识别为独立词，“是”作为停词被过滤。

{
  "tokens": [
    {
      "token": "智能手机",
      "start_offset": 0,
      "end_offset": 4,
      "type": "CN_WORD",
      "position": 0
    },
    {
      "token": "很好用",
      "start_offset": 5,
      "end_offset": 8,
      "type": "CN_WORD",
      "position": 1
    }
  ]
}

ik_max_word（细粒度）分词效果

请求示例：

POST /_analyze
{
  "analyzer":"ik_max_word",
  "text":"智能手机是很好用"
}

预期结果：“智能手机”被切分为多个词组（智能手机/智能/手机/机等），“是”作为停词被过滤。

{
  "tokens": [
    { "token": "智能手机", "start_offset": 0, "end_offset": 4, "type": "CN_WORD", "position": 0 },
    { "token": "智能", "start_offset": 0, "end_offset": 2, "type": "CN_WORD", "position": 1 },
    { "token": "智", "start_offset": 0, "end_offset": 1, "type": "CN_WORD", "position": 2 },
    { "token": "能手", "start_offset": 1, "end_offset": 3, "type": "CN_WORD", "position": 3 },
    { "token": "手机", "start_offset": 2, "end_offset": 4, "type": "CN_WORD", "position": 4 },
    { "token": "机", "start_offset": 3, "end_offset": 4, "type": "CN_WORD", "position": 5 },
    { "token": "很好用", "start_offset": 5, "end_offset": 8, "type": "CN_WORD", "position": 6 },
    { "token": "很好", "start_offset": 5, "end_offset": 7, "type": "CN_WORD", "position": 7 },
    { "token": "好用", "start_offset": 6, "end_offset": 8, "type": "CN_WORD", "position": 8 },
    { "token": "用", "start_offset": 7, "end_offset": 8, "type": "CN_WORD", "position": 9 }
  ]
}

验证同义词效果

同义词库配置成功后，您可以通过同义词搜索测试词库效果。

场景设定：同义词词库中已添加“开心,高兴”。

在自定义词库页面，单击页面右上角的“Kibana”，登录Kibana。
在Kibana左侧导航栏选择“Dev Tools”，进入操作页面。

执行以下命令，创建索引test并配置同义词过滤器。

PUT test
{
    "settings": {
        "analysis": {
            "filter": {
                "my_synonym": {
                    "type": "dynamic_synonym"
                }
            },
            "analyzer": {
                "ik_synonym": {
                    "filter": [
                        "my_synonym"
                    ],
                    "type": "custom",
                    "tokenizer": "ik_smart"
                }
            }
        }
    },
    "mappings": {
        "properties": {
            "desc": {
                "type": "text",
                "analyzer": "ik_synonym"
            }
        }
    }
}

执行以下命令，查看同义词过滤器的配置效果。

GET /test/_analyze
{
  "analyzer": "ik_synonym",
  "text": ["我很开心"]
}

预期结果：虽然文本使用的是“开心”，但通过同义词映射分词结果中还包含“高兴”。

{
  "tokens": [
    { "token": "我很", "start_offset": 0, "end_offset": 2, "type": "CN_WORD", "position": 0 },
    { "token": "开心", "start_offset": 2, "end_offset": 4, "type": "CN_WORD", "position": 1 },
    { "token": "高兴", "start_offset": 2, "end_offset": 4, "type": "SYNONYM", "position": 1 }
  ]
}

预置词库说明

为了方便用户直接使用IK分词器，CSS服务预置了4个词库，如表5所示。当这些预置的主词库和停词库已满足业务的分词需求时，则集群无需配置自定义词库即可直接实现关键词搜索。

表5 预置词库说明
预置词库名称	作用说明	下载地址
静态主词词库	常用主词集合（IK分析插件的默认主词）	https://github.com/infinilabs/analysis-ik/blob/master/config/main.dic
静态停词词库	常用停词集合（IK分析插件的默认停词）	https://github.com/infinilabs/analysis-ik/blob/master/config/stopword.dic
Extra主词词库	生僻主词集合（IK分析插件的扩展主词）	https://github.com/infinilabs/analysis-ik/blob/master/config/extra_main.dic
Extra停词词库	生僻停词集合（IK分析插件的扩展停词）	https://github.com/infinilabs/analysis-ik/blob/master/config/extra_stopword.dic

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

云宝助手提问云社区提问

配置自定义词库

功能介绍

自定义词库的工作原理

词库文件规范

约束限制

前提条件

进入自定义词库配置页面

配置自定义词库

更新预置词库

验证主词和停词效果

验证同义词效果

预置词库说明

相关文档

相关文档

意见反馈

文档内容是否对您有帮助？