跳到主要内容
版本：Cloud 开发指南

最佳实践：如何选择合适的 Analyzer
公测版

📘说明

本指南侧重于 Analyzer 选择的实际决策方法。关于 Analyzer 组件的技术细节以及如何添加 Analyzer 参数，请参考 Analyzer 概述。

快速了解 Analyzer​

在 Zilliz Cloud 中，Analyzer 会处理存储在字段中的文本，使其可用于 Full Text Search（BM25）、Phrase Match 或 Text Match。可以将它视作一个文本处理器，把原始内容转化为可搜索的 token。一个 Analyzer 的工作分为两个阶段：

HZhjw5hTuhfOIebOsnOcmy8Hnuf

  1. 分词 (Tokenization, 必需)：通过 tokenizer 将连续的文本拆分为独立且有意义的 token。不同语言和内容类型的分词方式差异很大。

  2. Token 过滤 (可选)：在分词后应用过滤器，用于修改、删除或优化 token。例如，将所有 token 转换为小写、去掉常见停用词，或将单词还原为词根。

示例：

输入: "Hello World!" 
       1. 分词 → ["Hello", "World", "!"]
       2. 小写与标点过滤 → ["hello", "world"]

为什么选择合适的 Analyzer 很重要​

选择不当的 Analyzer 可能导致相关文档无法被搜索到，或返回无关结果。

下表总结了因错误选择 Analyzer 而导致的常见问题，并提供了可操作的解决方案：

问题

症状

示例

错误原因

解决方案

过度分词

技术术语、标识符或 URL 搜索不到

  • "user_id" → ['user','id']

  • "C++" → ['c']

standard Analyzer

使用 whitespace tokenizer 并结合 alphanumonly 过滤器

分词不足

多词短语的一部分无法匹配完整短语

"state-of-the-art" → ['state-of-the-art']

使用 whitespace tokenizer

使用 standard tokenizer，并配合 regex 过滤器

语言不匹配

特定语言搜索无效或结果异常

"机器学习" → ['机器学习']

使用 english Analyzer

使用特定语言的 Analyzer，如 Chinese

第一步：你是否需要选择 Analyzer？​

如果未指定 Analyzer，在使用全文检索等功能时，Zilliz Cloud 会自动应用 **standard** Analyzer。

它会：

  • 按空格和标点分词

  • 将所有 token 转为小写

  • 移除内置的常见英文停用词和大多数标点

示例：

输入:  "The Milvus vector database is built for scale!"
输出: ['the', 'milvus', 'vector', 'database', 'is', 'built', 'scale']

第二步：判断 Standard Analyzer 是否满足业务需求​

使用下表快速判断默认的 Standard Analyzer 是否满足你的需求。如果不满足，你需要通过不同路径选择其他 Analyzer。

内容

standard Analyzer 是否合适？

原因

需要什么

英文博客

✅ 是

默认即可

使用默认

中文文档

❌ 否

中文无空格，整段视作单 token

使用内置 chinese Analyzer

技术文档

❌ 否

符号丢失，如 C++ → C

使用 whitespace tokenizer + alphanumonly filter

法语/西班牙语

⚠️ 可能

café 与 cafe 不匹配

使用 asciifolding filter

多语言或未知语言

❌ 否

standard 无法处理不同字符集

使用 icu tokenizer 或多语言方案

第三步：通过不同路径选择 Analyzer​

如果默认的标准分析器无法满足需求，请选择以下两种路径之一：

  • 路径 A：使用内置 Analyzer（开箱即用的语言专用 Analyzer）

  • 路径 B：创建自定义 Analyzer（手动定义 Tokenizer 和一组 Filter）

路径 A：使用内置 Analyzer​

内置 Analyzer 是预配置方案，适合常见语言。

可选内置 Analyzer​

Analyzer

语言支持

组件

说明

standard

英语/法语/西班牙语等

  • Tokenizer: standard

  • Filters: lowercase

通用方案

english

英语

  • Tokenizer: standard

  • Filters: lowercase, stemmer, stop

英语专用，推荐

chinese

中文

  • Tokenizer: jieba

  • Filters: cnalphanumonly

默认简体字典

示例​

# Using built-in English analyzer
analyzer_params = {
    "type": "english"
}

# Applying analyzer config to target VARCHAR field in your collection schema
schema.add_field(
    field_name='text',
    datatype=DataType.VARCHAR,
    max_length=200,
    enable_analyzer=True,
    # highlight-next-line
    analyzer_params=analyzer_params,
)

路径 B：创建自定义 Analyzer​

当内置选项不足时，可以通过 tokenizer + filter 自由组合。

步骤 1：选择 tokenizer​

根据语言选择合适的 tokenizer：

西方语言​

对于通过空格分隔的语言，有以下选择：

Tokenizer

工作原理

适用场景

示例

standard

基于空格和标点拆分文本

通用文本，包含混合标点的内容

  • 输入: "Hello, world! Visit example.com"

  • 输出: ['Hello', 'world', 'Visit', 'example', 'com']

whitespace

仅基于空格字符拆分

已预处理的内容，用户自定义格式的文本

  • 输入: "user_id = get_user_data()"

  • 输出: ['user_id', '=', 'get_user_data()']

东亚语言​

基于词典的语言需要专用的 tokenizer 才能进行正确的分词：

中文​

Tokenizer

工作原理

适用场景

示例

jieba

基于中文词典的分词，结合智能算法

推荐用于中文内容——结合词典与智能算法，专为中文设计

  • 输入: "机器学习是人工智能的一个分支"

  • 输出: ['机器', '学习', '是', '人工', '智能', '人工智能', '的', '一个', '分支']

lindera

纯词典驱动的中文形态学分析（使用 cc-cedict 词典）

为日韩分词设计，也可用于分词中文，但性能不如 jieba

  • 输入: "机器学习算法"

  • 输出: ["机器", "学习", "算法"]

日语和韩语​

Tokenizer

工作原理

适用场景

示例

Examples

Japanese

lindera

ipadic (通用), ipadic-neologd (现代词汇), unidic (学术)

形态学分析，支持专有名词处理

  • 输入: "東京都渋谷区"

  • 输出: ["東京", "都", "渋谷", "区"]

Korean

lindera

ko-dic

韩语形态学分析

  • 输入: "안녕하세요"

  • 输出: ["안녕", "하", "세요"]

多语言或未知语言​

适用于文档中语言不可预测或混合的情况：

Tokenizer

工作原理

适用场景

示例

Examples

icu

基于 Unicode 的分词（ICU - International Components for Unicode）

混合文字、未知语言，或只需简单分词时

  • 输入: "Hello 世界 مرحبا"

  • 输出: ['Hello', ' ', '世界', ' ', 'مرحبا']

icu 的使用场景：

  • 内容包含混合语言，且语言识别不可行。

  • 不希望使用多语言 Analyzer 或 language identifier 带来的额外开销。

  • 文本以某一主语言为主，夹杂少量外语单词，这些外语对整体语义影响不大（如英文文本中偶尔出现日语/法语品牌名或技术术语）。

替代方案：如果需要更精确地处理多语言内容，建议使用 多语言 Analyzer 或 Language Identifier。

步骤 2：添加过滤器以提高精度​

在选择好 tokenizer 之后，根据你的具体搜索需求和内容特性应用过滤器。

常用过滤器​

这些过滤器在大多数以空格分隔的语言（英语、法语、德语、西班牙语等）中至关重要，并能显著提升搜索质量：

Filter

工作原理

使用场景

示例

lowercase

将所有 token 转换为小写

通用——适用于所有区分大小写的语言

  • 输入: ["Apple", "iPhone"]

  • 输出: [['apple'], ['iphone']]

stemmer

将单词还原为词根

适用于有词形变化的语言（英语、法语、德语等）

英语示例：

  • 输入: ["running", "runs", "ran"]

  • 输出: [['run'], ['run'], ['ran']]

stop

移除常见的无意义词（停用词）

大多数语言，尤其是空格分隔的语言

  • 输入: ["the", "quick", "brown", "fox"]

  • 输出: [[], ['quick'], ['brown'], ['fox']]

📘说明

对于东亚语言（中文、日语、韩语等），请重点使用语言特定的过滤器。这些语言的文本处理方式不同，通常不需要或无法从词干提取中获益。

文本规范化过滤器​

这些过滤器用于标准化文本差异，提高匹配一致性：

Filter

工作原理

使用场景

示例

asciifolding

将带重音符的字符转换为 ASCII 等效字符

国际化内容、用户生成内容

  • 输入: ["café", "naïve", "résumé"]

  • 输出: [['cafe'], ['naive'], ['resume']]

Token 过滤​

这些过滤器控制哪些 token 会被保留，通常基于字符类型或长度：

Filter

工作原理

使用场景

示例

removepunct

移除单独存在的标点 token

清理 jieba、lindera、icu 输出中的单独标点

  • 输入: ["Hello", "!", "world"]

  • 输出: [['Hello'], ['world']]

alphanumonly

仅保留字母和数字

技术类内容、干净的文本处理

  • 输入: ["user123", "test@email.com"]

  • 输出: [['user123'], ['test', 'email', 'com']]

length

移除超出指定长度范围的 token

过滤噪声（如过长的 token）

  • 输入: ["a", "very", "extraordinarily"]

  • 输出: [['a'], ['very'], []] (if max=10)

regex

基于自定义模式的过滤

特定领域的 token 需求

  • 输入: ["test123", "prod456"]

  • 输出: [[], ['prod456']] (if expr="^prod")

语言特定过滤器​

Filter

Language

How It Works

Examples

decompounder

德语

将复合词拆分为可搜索的组成部分

  • 输入: ["dampfschifffahrt"]

  • 输出: [['dampf', 'schiff', 'fahrt']]

cnalphanumonly

中文

保留中文字符 + 字母数字

  • 输入: ["Hello", "世界", "123", "!@#"]

  • 输出: [['Hello'], ['世界'], ['123'], []]

cncharonly

中文

仅保留中文字符

  • 输入: ["Hello", "世界", "123"]

  • 输出: [[], ['世界'], []]

步骤 3：组合并实现​

要创建自定义 Analyzer，需要在 analyzer_params 字典中定义 tokenizer 和过滤器列表。 这些过滤器会按照定义的顺序依次应用。

# Example: A custom analyzer for technical content
analyzer_params = {
    "tokenizer": "whitespace",
    "filter": ["lowercase", "alphanumonly"]
}

# Applying analyzer config to target VARCHAR field in your collection schema
schema.add_field(
    field_name='text',
    datatype=DataType.VARCHAR,
    max_length=200,
    enable_analyzer=True,
    # highlight-next-line
    analyzer_params=analyzer_params,
)

最终步骤：使用 run_analyzer 进行测试​

在将配置应用到 Collection 之前，务必先验证：

# Sample text to analyze
sample_text = "The Milvus vector database is built for scale!"

# Run analyzer with the defined configuration
result = client.run_analyzer(sample_text, analyzer_params)
print("Analyzer output:", result)

需要检查的常见问题

  • 过度分词：技术术语被错误拆分

  • 分词不足：短语未被正确拆分

  • token 丢失：重要词被过滤掉

更多用法请参考 run_analyzer。

本节为在 Zilliz Cloud 中使用 Analyzer 时的常见场景，提供推荐的 tokenizer 与 filter 组合。请选择最适合你内容类型和搜索需求的配置。

📘说明

在将 Analyzer 应用到 Collection 前，建议先使用 run_analyzer 来测试和验证文本分析效果。

英文​

analyzer_params = {
    "tokenizer": "standard",
    "filter": [
        "lowercase",
        {
            "type": "stemmer",
            "language": "english"
        },
        {
            "type": "stop",
            "stop_words": [
                "_english_"
            ]
        }
    ]
}

中文​

{
    "tokenizer": "jieba",
    "filter": ["cnalphanumonly"]
}

阿拉伯语​

{
    "tokenizer": "standard",
    "filter": [
        "lowercase",
        {
            "type": "stemmer",
            "language": "arabig"
        }
    ]
}

孟加拉语​

{
    "tokenizer": "icu",
    "filter": ["lowercase", {
        "type": "stop",
        "stop_words": [<put stop words list here>]
    }]
}

法语​

{
    "tokenizer": "standard",
    "filter": [
        "lowercase",
        {
            "type": "stemmer",
            "language": "french"
        },
        {
            "type": "stop",
            "stop_words": [
                "_french_"
            ]
        }
    ]
}

德语​

{
    "tokenizer": {
        "type": "lindera",
        "dict_kind": "ipadic"
    },
    "filter": [
        "removepunct"
    ]
}

印度语​

{
    "tokenizer": "icu",
    "filter": ["lowercase", {
        "type": "stop",
        "stop_words": [<put stop words list here>]
    }]
}

日语​

{
    "tokenizer": {
        "type": "lindera",
        "dict_kind": "ipadic"
    },
    "filter": [
        "removepunct"
    ]
}

葡萄牙语​

{
    "tokenizer": "standard",
    "filter": [
        "lowercase",
        {
            "type": "stemmer",
            "language": "portuguese"
        },
        {
            "type": "stop",
            "stop_words": [
                "_portuguese_"
            ]
        }
    ]
}

俄语​

{
    "tokenizer": "standard",
    "filter": [
        "lowercase",
        {
            "type": "stemmer",
            "language": "russian"
        },
        {
            "type": "stop",
            "stop_words": [
                "_russian_"
            ]
        }
    ]
}

西班牙语​

{
    "tokenizer": "standard",
    "filter": [
        "lowercase",
        {
            "type": "stemmer",
            "language": "spanish"
        },
        {
            "type": "stop",
            "stop_words": [
                "_spanish_"
            ]
        }
    ]
}

斯瓦希里语​

{
    "tokenizer": "standard",
    "filter": ["lowercase", {
        "type": "stop",
        "stop_words": [<put stop words list here>]
    }]
}

土耳其语​

{
    "tokenizer": "standard",
    "filter": [
        "lowercase",
        {
            "type": "stemmer",
            "language": "turkish"
        }
    ]
}

乌尔都语​

{
    "tokenizer": "icu",
    "filter": ["lowercase", {
        "type": "stop",
        "stop_words": [<put stop words list here>]
    }]
}

混合或多语言内容​

当处理跨多种语言或文字体系不可预测的内容时，建议使用 icu analyzer。 该 Analyzer 具备 Unicode 识别能力，能有效处理混合文字和符号。

基础多语言配置（不包含词干提取）：

analyzer_params = {
    "tokenizer": "icu",
    "filter": ["lowercase", "asciifolding"]
}

高级多语言处理：

在 Zilliz Cloud 配置和预览 Analyzer​

你可以直接在 Zilliz Cloud 控制台中配置和测试 Analyzer，而无需编写代码。具体可参考如下演示。