对于面向全球或特定语言市场的搜索业务，精准的语言处理是提升搜索质量的关键。TongSearch 默认的 standard 分词器对于英语等屈折变化较少的语言表现尚可，但面对乌克兰语这种具有丰富词形变化的斯拉夫语言时，往往显得力不从心。本文将从实战角度出发，指导 正确使用 analysis-ukrainian 插件，以显著提升乌克兰语的搜索召回率。

---

插件功能介绍

简要介绍插件的作用

analysis-ukrainian 是 TongSearch 官方提供的一个社区贡献插件，旨在为乌克兰语提供专业的文本分析支持。它集成了专门针对乌克兰语的 Tokenizer（分词器）、Token Filter（词元过滤器）和 Stemmer（词干提取器）。

分词插件解决了什么问题

乌克兰语是一种高度屈折的语言，一个词可以通过改变词尾来表示不同的格、数、性或时态。例如，名词 "книга" (书) 在不同的语境下可以变为 "книги", "книзі", "книгу", "книгою" 等。

如果使用默认的 standard 分词器，这些不同的词形会被视为完全不同的词元（Token）。用户搜索 "книга" 时，将无法召回包含 "книги" 的文档，导致搜索召回率极低，用户体验差。

analysis-ukrainian 插件的核心价值在于其内置的 词干提取器 (Stemmer)。它能识别并移除词语的屈折词尾，将它们还原为统一的词根形式。

下面这张图直观地展示了标准分词器与乌克兰语分词器处理同一文本时的区别：

通过将不同的词形还原为相同的词根，插件确保了无论用户输入何种变体，都能匹配到相关的文档。

支持的主要分词模式

安装插件后，TongSearch 会新增一个开箱即用的内置分析器：

• ukrainian analyzer: 一个预配置好的分析器，包含标准的 tokenizer、lowercase filter（转小写）、stop filter（停用词过滤，移除如 "і", "в", "на" 等无意义高频词）以及核心的 ukrainian stemmer。

通常情况下，直接使用这个内置的 ukrainian analyzer 即可满足绝大多数需求。

---

使用场景

适合使用的场景

• 纯乌克兰语内容索引: 当你的索引字段明确存储的是乌克兰语文本时，这是最直接的使用场景。例如，乌克兰电商网站的商品标题和描述、乌克兰语新闻门户的文章内容等。

• 多语言站点的特定语言字段: 如果你的文档结构中对不同语言有明确的字段划分（例如 title_en, title_uk），应在 title_uk 字段上应用此分析器。

不适合或需要谨慎使用的场景

• 语言混合且未做语种识别的字段: 如果一个字段中可能混杂着英文、俄文和乌克兰文，直接强制使用 ukrainian 分析器可能会导致对其他语言的错误处理（例如过度词干提取），反而降低搜索质量。这种情况下，建议先在应用层进行语种识别，再存入对应的语言字段。

• 对精确匹配要求极高的场景: 词干提取在提高召回率的同时，不可避免地会降低一定的精确度。在某些特定领域（如法律、医学中的专有名词查询），如果需要严格区分词的不同形态，可能需要谨慎使用或配合不使用词干提取的字段进行多字段查询（multi-field query）。

---

插件安装

安装方式

推荐使用官方提供的 tongsearch-plugin 命令行工具进行安装。

方式一：命令行直接安装

./bin/tongsearch-plugin install file:///tmp/analysis-ukrainian-{version}.zip
注：请将 {version} 替换为实际的 TongSearch 版本号。

方式二：本地文件安装

先下载对应版本的 ZIP 包并上传至服务器，然后执行安装：

# 假设 ZIP 包在 /tmp/ 目录下
unzip /tmp/analysis-ukrainian-{version}.zip

多节点集群中的注意事项与重启

在集群环境中，必须在所有节点都完成插件安装后，才能进行重启操作。

为了保障线上服务的稳定性，应采用 滚动重启 (Rolling Restart) 的策略：

1. 停止一个非 Master 节点。

2. 启动该节点，观察日志确保启动成功并重新加入集群，集群状态变回 Green 或 Yellow。

3. 重复上述步骤，逐个重启剩余的 Data 节点。

4. 最后逐个重启 Master 候选节点。

安装完成后的验证方式

任意节点重启完成后，可以通过以下 API 验证插件是否加载成功：

curl -X GET "localhost:9200/_cat/plugins?v"

如果输出中包含 analysis-ukrainian，则表示安装成功。

name    component           version
node-1  analysis-ukrainian  

---

具体实践

一个简单的查询示例，说明分词在搜索中的效果

为了验证效果，我们不需要立即创建索引。可以使用强大的 _analyze API 来测试分词器是如何处理文本的。

假设我们有一段文本 "特价出售旧书" (乌克兰语: "Розпродаж старих книг")。我们将重点关注 "旧的" (старих) 和 "书" (книг) 这两个词。

执行以下命令：

curl -X POST "localhost:9200/_analyze?pretty" -H 'Content-Type: application/json' -d'
{
  "analyzer": "ukrainian",
  "text": "Розпродаж старих книг"
}
'

预期输出:

{
  "tokens" : [
    {
      "token" : "розпродаж",
      "start_offset" : 0,
      "end_offset" : 9,
      "type" : "<ALPHANUM>",
      "position" : 0
    },
    {
      "token" : "стар",  <-- 注意这里，"старих" 被还原成了词根 "стар"
      "start_offset" : 10,
      "end_offset" : 16,
      "type" : "<ALPHANUM>",
      "position" : 1
    },
    {
      "token" : "книг", <-- 注意这里，"книг" 被还原成了词根 "книг"
      "start_offset" : 17,
      "end_offset" : 21,
      "type" : "<ALPHANUM>",
      "position" : 2
    }
  ]
}

可以看到，分析器成功提取了词根。这意味着，如果用户稍后搜索 "стара книга" (单数形式)，分词器同样会将其处理为 ["стар", "книг"]，从而成功匹配到包含 "старих книг" 的文档。

---

注意事项

自定义词典的管理与更新

虽然内置的词典能覆盖大部分通用场景，但对于特定行业的专业术语，可能仍会出现分词不准确或过度词干提取的情况。

analysis-ukrainian 允许用户通过配置自定义的停用词表 (stopwords) 或词干例外表 (stem_exclusion) 来微调分词行为。这些配置文件通常需要放置在每个节点的 config 目录下。

注意: 更新自定义词典文件后，必须重启受影响的节点才能使更改生效。这增加了运维的复杂性，因此在引入自定义词典前应充分评估必要性。

小结

analysis-ukrainian 插件是 TongSearch 处理乌克兰语内容的必备利器。它通过专业的词干提取技术，有效解决了乌克兰语丰富词形变化带来的搜索召回率低的问题。