配置自定义词库

功能介绍

词库是指导分词器识别特殊词语的核心资源。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在预置的静态停词词库里，分词时会被过滤掉）。

自定义词库的工作原理

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

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

词库文件规范

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

前提条件

• 目标集群处于“可用”状态，无正在进行中的任务。
• 确认操作账号已具备以下权限（可以在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集群位于同一区域，且“存储类别”为“标准存储”。

进入自定义词库配置页面

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

配置自定义词库

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

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

   表3 配置自定义词库

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

2. 配置完成后，单击“保存”，在弹窗中单击“确定”，启动词库更新。

   下方呈现词库配置信息。等待约1分钟，词库状态从“更新中”变更为“成功”，表示词库更新完成。

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

   POST /{my_index}/_update_by_query

更新预置词库

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

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

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

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

   表4 更新预置词库

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

3. 配置完成后，单击“保存”，在弹窗中单击“确定”，启动词库更新。

   下方呈现词库配置信息。等待约1分钟，词库状态从“更新中”变更为“需要重启”，表示词库更新完成。

   图2 词库状态
   
4. 词库更新完成后，单击页面右上角的“重启”，重启集群使预置词库的修改生效。操作指导请参见重启集群。
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所示。当这些预置的主词库和停词库已满足业务的分词需求时，则集群无需配置自定义词库即可直接实现关键词搜索。

相关文档

• 通过IK分词器与自定义词库实现精准关键词搜索：通过IK分词器结合自定义主词词库和停词词库，让专有词语被完整保留、无意义干扰词被过滤，实现精准的关键词搜索。
• 通过同义词过滤器与自定义词库实现语义扩展搜索：通过配置自定义同义词词库，并利用dynamic_synonym同义词过滤器，可在查询和写入阶段自动扩展同义词，从而实现跨词语的语义级搜索。