# 配置自定义词库 在日常搜索业务中，OpenSearch的预置词库经常无法识别行业专有名词，如"云原生"会被切分为"云"、"原"、"生"，导致搜索召回率低、结果不精准；同时，"的"、"了"等无意义高频词如果未被过滤，会引入大量噪音、降低搜索效率；此外，用户搜索"开心"时会期望同时召回包含"高兴"等同义词的文档，但预置词库不具备同义词扩展能力。为此，CSS服务预置了IK分析插件（analysis-ik）和动态同义词插件（analysis-dynamic-synonym），通过配置自定义词库，让OpenSearch精准识别业务关键词、过滤干扰词、扩展同义词，实现更智能、更贴合业务场景的搜索体验。 #### 功能介绍 词库是指导分词器识别特殊词语的核心资源。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分词器使用。 - 适用场景：语义扩展搜索，拼写纠错场景。 | 依赖同义词库（只支持自定义词库） | ![](https://support.huaweicloud.com/usermanual-css/public_sys-resources/caution_3.0-zh-cn.png) 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在预置的静态停词词库里，分词时会被过滤掉）。 #### 自定义词库的工作原理 自定义词库的工作流程说明： 1. 词库加载：用户将词库文件上传至OBS桶后，为集群配置词库，系统将词库加载至集群各节点。 2. 主词库匹配：分词器优先按主词库中的词条进行整词切分，避免专有名词被拆散。 3. 停词库过滤：分词结果中匹配到停词库的词条将被直接丢弃，不进入索引。 4. 同义词扩展：分词结果经过同义词过滤器，匹配同义词库的词条会生成额外的同义Token，实现语义扩展搜索。 5. 生效范围：词库更新后，新写入的数据自动使用新词库分词；历史索引数据不会自动重建，需手动执行_update_by_query 命令。 #### 词库文件规范 请按以下规范准备词库文件，不满足要求将导致词库加载失败。 表2词库文件规范 | 规范项 | 要求 | |:---|:---| | 文件格式 | ".txt" | | 文件编码 | UTF-8（无BOM） | | 内容格式 | - 主词词库和停词词库一行一个词。示例： ``` 云计算 搜索引擎 ``` - 同义词词库一行一组，双向同义词间以英文逗号","分隔，单向同义词间以"=\>"分隔。示例： ``` 开心,高兴,愉快 手机=>移动电话 ``` 配置双向同义词时，搜索"开心"，会同时召回"开心"、"高兴"、"愉快"；配置单向同义词时，搜索"手机"，只召回"移动电话"。 | | 英文单词 | 必须使用小写字母。 | | 文件大小 | 单个文件不超过100MB。 | #### 前提条件 - 目标集群处于"可用"状态，无正在进行中的任务。 - 确认操作账号已具备以下权限（可以在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桶。操作指导请参见[上传文件](https://support.huaweicloud.com/usermanual-obs/zh-cn_topic_0045829661.html)。 OBS桶必须与CSS集群位于同一区域，且"存储类别"为"标准存储"。 #### 进入自定义词库配置页面 1. 登录[云搜索服务管理控制台](https://console.huaweicloud.com/elasticsearch/)。 2. 在左侧导航栏，选择"集群管理 \> OpenSearch"。 3. 在集群列表，单击目标集群名称，进入集群详情页。 4. 选择"集群配置 \> 自定义词库"，进入自定义词库配置页面。 #### 配置自定义词库 如果预置词库不满足业务分词需要，您可以配置自定义词库。 1. 在自定义词库页面，根据业务需求配置自定义词库。 表3配置自定义词库 | 参数名称 | 操作说明 | |:---|:---| | OBS桶 | 选择词库文件所在的OBS桶。仅更新词库时才需配置。 如果没有合适的OBS桶，可以单击"创建桶"跳转到OBS控制台创建OBS桶。具体操作请参见[创建桶](https://support.huaweicloud.com/usermanual-obs/zh-cn_topic_0045829088.html)。 | | 主词词库 | 自定义主词集合。初始状态为空。 - 默认值："不更新"，表示不配置该词库。 - 新增/更新词库：选择"更新 \> 选择"，选择OBS桶中符合规范的词库文件，单击"确定"。 - 删除词库：单击"不使用此词库"，表示删除词库。 | | 停词词库 | 自定义停词集合。初始状态为空。 - 默认值："不更新"，表示不配置该词库。 - 新增/更新词库：选择"更新 \> 选择"，选择OBS桶中符合规范的词库文件，单击"确定"。 - 删除词库：单击"不使用此词库"，表示删除词库。 | | 同义词词库 | 自定义同义词集合。初始状态为空。 - 默认值："不更新"，表示不配置该词库。 - 新增/更新词库：选择"更新 \> 选择"，选择OBS桶中符合规范的词库文件，单击"确定"。 - 删除词库：单击"不使用此词库"，表示删除词库。 | 2. 配置完成后，单击"保存"，在弹窗中单击"确定"，启动词库更新。 下方呈现词库配置信息。等待约1分钟，词库状态从"更新中"变更为"成功"，表示词库更新完成。 图1词库状态 ![](https://support.huaweicloud.com/usermanual-css/figure/zh-cn_image_0000002660218499.png) 3. （可选）词库更新后，新写入数据将使用新词库分词；历史索引数据不会自动重建，如需重新分词入库，请手动执行以下命令。 ``` POST /{my_index}/_update_by_query ``` #### 更新预置词库 如需修改或禁用预置词库，您可以更新预置词库。 1. 在自定义词库页面，打开"修改预置词库"右侧的开关。 ![](https://support.huaweicloud.com/usermanual-css/public_sys-resources/caution_3.0-zh-cn.png) 如果界面不存在"修改预置词库"开关，则表示该集群版本不支持更新预置词库。建议升级集群版本，或者新建集群并进行数据迁移。 2. 根据业务需求更新预置词库。 表4更新预置词库 | 参数名称 | 操作说明 | |:---|:---| | OBS桶 | 选择词库文件所在的OBS桶。仅更新词库时才需配置。 如果没有合适的OBS桶，可以单击"创建桶"跳转到OBS控制台创建OBS桶。具体操作请参见[创建桶](https://support.huaweicloud.com/usermanual-obs/zh-cn_topic_0045829088.html)。 | | 静态主词词库 | 预置的常用主词集合。 - 默认值："不更新"，表示不配置该词库。 - 更新词库：选择"更新 \> 选择"，选择OBS桶中符合规范的词库文件，单击"确定"。 - 删除词库：单击"不使用此词库"，表示删除词库。 | | 静态停词词库 | 预置的常用停词集合。 - 默认值："不更新"，表示不配置该词库。 - 更新词库：选择"更新 \> 选择"，选择OBS桶中符合规范的词库文件，单击"确定"。 - 删除词库：单击"不使用此词库"，表示删除词库。 | | Extra主词词库 | 预置的生僻主词集合。 - 默认值："不更新"，表示不配置该词库。 - 更新词库：选择"更新 \> 选择"，选择OBS桶中符合规范的词库文件，单击"确定"。 - 删除词库：单击"不使用此词库"，表示删除词库。 | | Extra停词词库 | 预置的生僻停词集合。 - 默认值："不更新"，表示不配置该词库。 - 更新词库：选择"更新 \> 选择"，选择OBS桶中符合规范的词库文件，单击"确定"。 - 删除词库：单击"不使用此词库"，表示删除词库。 | 3. 配置完成后，单击"保存"，在弹窗中单击"确定"，启动词库更新。 下方呈现词库配置信息。等待约1分钟，词库状态从"更新中"变更为"需要重启"，表示词库更新完成。 图2词库状态 ![](https://support.huaweicloud.com/usermanual-css/figure/zh-cn_image_0000002660218501.png) 4. 词库更新完成后，单击页面右上角的"重启"，重启集群使预置词库的修改生效。操作指导请参见[重启集群](https://support.huaweicloud.com/usermanual-css/css_01_0014.html)。 5. （可选）词库更新后，新写入数据将使用新词库分词；历史索引数据不会自动重建，如需重新分词入库，请手动执行以下命令。 ``` POST /{my_index}/_update_by_query ``` #### 验证主词和停词效果 主词库和停词库配置成功后，您可以通过/_analyze API测试文本的分词效果。 场景设定：主词词库中已添加"智能手机"，停词词库中已添加"是"。 1. 在自定义词库页面，单击页面右上角的"Dashboards"，登录OpenSearch Dashboards。 2. 在Dashboards左侧导航栏选择"Dev Tools"，进入操作页面。 3. 执行以下命令，查看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 } ] } ``` #### 验证同义词效果 同义词库配置成功后，您可以通过同义词搜索测试词库效果。 场景设定：同义词词库中已添加"开心,高兴"。 1. 在自定义词库页面，单击页面右上角的"Dashboards"，登录OpenSearch Dashboards。 2. 在Dashboards左侧导航栏选择"Dev Tools"，进入操作页面。 3. 执行以下命令，创建索引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" } } } } ``` 4. 执行以下命令，查看同义词过滤器的配置效果。 ``` 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分析插件的默认主词） | | | 静态停词词库 | 常用停词集合（IK分析插件的默认停词） | | | Extra主词词库 | 生僻主词集合（IK分析插件的扩展主词） | | | Extra停词词库 | 生僻停词集合（IK分析插件的扩展停词） | | #### 相关文档 - [通过IK分词器与自定义词库实现精准关键词搜索](https://support.huaweicloud.com/bestpractice-css/css_07_0013.html)：通过IK分词器结合自定义主词词库和停词词库，让专有词语被完整保留、无意义干扰词被过滤，实现精准的关键词搜索。 - [通过同义词过滤器与自定义词库实现语义扩展搜索](https://support.huaweicloud.com/bestpractice-css/css_07_0014.html)：通过配置自定义同义词词库，并利用dynamic_synonym同义词过滤器，可在查询和写入阶段自动扩展同义词，从而实现跨词语的语义级搜索。