Escolha o analisador certo para o seu caso de utilização

Compreender os analisadores em 2 minutos

No Milvus, um analisador processa o texto armazenado neste campo para torná-lo pesquisável para recursos como pesquisa de texto completo (BM25), correspondência de frase ou correspondência de texto. Pense nele como um processador de texto que transforma o seu conteúdo em bruto em tokens pesquisáveis.

Um analisador funciona num pipeline simples de duas fases:

Fluxo de trabalho do analisador

1. Tokenização (obrigatório): Este estágio inicial aplica um tokenizador para quebrar uma cadeia contínua de texto em unidades discretas e significativas chamadas tokens. O método de tokenização pode variar significativamente, dependendo do idioma e do tipo de conteúdo.

2. Filtragem de tokens (opcional): Após a tokenização, são aplicados filtros para modificar, remover ou refinar os tokens. Estas operações podem incluir a conversão de todos os tokens para minúsculas, a remoção de palavras comuns sem significado (como stopwords) ou a redução de palavras à sua forma de raiz (stemming).

Exemplo:

Input: "Hello World!" 
       1. Tokenization → ["Hello", "World", "!"]
       2. Lowercase & Punctuation Filtering → ["hello", "world"]

Porque é que a escolha do analisador é importante

A escolha do analisador errado pode fazer com que os documentos relevantes não possam ser pesquisados ou devolver resultados irrelevantes.

A tabela seguinte resume os problemas comuns causados pela seleção incorrecta do analisador e fornece soluções acionáveis para diagnosticar problemas de pesquisa.

Problema	Sintoma	Exemplo (entrada e saída)	Causa (analisador ruim)	Solução (analisador bom)
Excesso de tokenização	As consultas de texto para termos técnicos, identificadores ou URLs não conseguem encontrar documentos relevantes.	"user_id" → ['user', 'id'] "C++" → ['c']	standard analisador	Utilizar um whitespace tokenizador; combine com um alphanumonly filtro.
Sub-tokenização	A pesquisa de um componente de uma frase com várias palavras não devolve documentos que contenham a frase completa.	"state-of-the-art" → ['state-of-the-art']	Analisador com um whitespace tokenizador	Utilizar um standard para dividir a pontuação e os espaços; utilize um filtro regex personalizado.
Incompatibilidades de idioma	Os resultados da pesquisa para um idioma específico são absurdos ou inexistentes.	Texto em chinês: "机器学习" → ['机器学习'] (um token)	english analisador	Utilize um analisador específico da língua, como chinese.

Primeira pergunta: É necessário escolher um analisador?

Para muitos casos de utilização, não é necessário fazer nada de especial. Vamos determinar se você é um deles.

Comportamento padrão: analisador standard

Se não especificar um analisador quando utilizar funcionalidades de recuperação de texto como a pesquisa de texto integral, o Milvus utiliza automaticamente o analisador standard analisador.

O analisador standard:

• Divide o texto em espaços e pontuação

• Converte todos os tokens para minúsculas

• Remove um conjunto integrado de palavras de paragem comuns em inglês e a maior parte da pontuação

Exemplo de transformação:

Input:  "The Milvus vector database is built for scale!"
Output: ['the', 'milvus', 'vector', 'database', 'is', 'built', 'scale']

Critérios de decisão: Uma verificação rápida

Utilize esta tabela para determinar rapidamente se o analisador standard predefinido satisfaz as suas necessidades. Se não corresponder, terá de escolher um caminho diferente.

O seu conteúdo	Analisador padrão OK?	Sim	O que você precisa
Posts de blogue em inglês	Sim	O comportamento predefinido é suficiente.	Utilize a predefinição (não é necessária qualquer configuração).
Documentos em chinês	Não	As palavras chinesas não têm espaços e serão tratadas como um token.	Use um analisador chinese incorporado.
Documentação técnica	Não	A pontuação é removida de termos como C++.	Crie um analisador personalizado com um whitespace tokenizador e um alphanumonly filtro.
Línguas separadas por espaços, como o texto francês/espanhol	⚠️ Talvez	Os caracteres acentuados (café vs. cafe) podem não corresponder.	Um analisador personalizado com o asciifolding é recomendado para obter melhores resultados.
Línguas multilingues ou desconhecidas	Não	O analisador standard não possui a lógica específica do idioma necessária para lidar com diferentes conjuntos de caracteres e regras de tokenização.	Use um analisador personalizado com o icu para a tokenização com reconhecimento de unicode. Como alternativa, considere a configuração de analisadores multilíngues ou um identificador de idioma para um tratamento mais preciso do conteúdo multilíngue.

Se o analisador predefinido standard não puder satisfazer os seus requisitos, terá de implementar um diferente. Existem dois caminhos:

• Utilizar um analisador incorporado ou

• Criar um personalizado

Caminho A: Usar analisadores incorporados

Os analisadores incorporados são soluções pré-configuradas para linguagens comuns. Eles são a maneira mais fácil de começar quando o analisador padrão não se encaixa perfeitamente.

Analisadores incorporados disponíveis

Analisador	Suporte a idiomas	Componentes	Notas
standard	A maioria das línguas separadas por espaços (inglês, francês, alemão, espanhol, etc.)	Tokenizador: standard Filtros: lowercase	Analisador de uso geral para processamento inicial de texto. Para cenários monolingues, os analisadores específicos da língua (como english) proporcionam um melhor desempenho.
english	Dedicado ao inglês, que aplica o stemming e a remoção de palavras de paragem para uma melhor correspondência semântica em inglês	Tokenizador: standard Filtros: lowercase, stemmer, stop	Recomendado para conteúdo apenas em inglês acima de standard.
chinese	Chinês	Tokenizador: jieba Filtros: cnalphanumonly	Atualmente usa o dicionário chinês simplificado por defeito.

Exemplo de implementação

Para utilizar um analisador incorporado, basta especificar o seu tipo em analyzer_params quando definir o seu esquema de campo.

# 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,
    analyzer_params=analyzer_params,
)

Caminho B: Criar um analisador personalizado

Quando as opções incorporadas não satisfazem as suas necessidades, pode criar um analisador personalizado, combinando um tokenizador com um conjunto de filtros. Isto dá-lhe controlo total sobre o pipeline de processamento de texto.

Passo 1: Selecionar o tokenizador com base no idioma

Escolha o seu tokenizador com base no idioma principal do seu conteúdo:

Línguas ocidentais

Para idiomas separados por espaço, tem estas opções:

Tokenizador	Como funciona	Melhor para	Exemplos
standard	Divide o texto com base em espaços e sinais de pontuação	Texto geral, pontuação mista	Entrada: "Hello, world! Visit example.com" Saída: ['Hello', 'world', 'Visit', 'example', 'com']
whitespace	Divide apenas em caracteres de espaço em branco	Conteúdo pré-processado, texto formatado pelo utilizador	Entrada: "user_id = get_user_data()" Saída: ['user_id', '=', 'get_user_data()']

Línguas do Leste Asiático

As línguas baseadas em dicionário requerem tokenizadores especializados para a segmentação correta das palavras:

Chinês

Tokenizador	Como funciona	Melhor para	Exemplos
jieba	Segmentação baseada em dicionário chinês com algoritmo inteligente	Recomendado para conteúdo chinês - combina dicionário com algoritmos inteligentes, especificamente concebidos para chinês	Entrada: "机器学习是人工智能的一个分支" Saída: ['机器', '学习', '是', '人工', '智能', '人工智能', '的', '一个', '分支']
lindera	Análise morfológica baseada em dicionário puro com dicionário chinês(cc-cedict)	Em comparação com jieba, processa o texto chinês de uma forma mais genérica	Entrada: "机器学习算法" Saída: ["机器", "学习", "算法"]

Japonês e coreano

Língua	Tokenizador	Opções de dicionário	Melhor para	Exemplos
Japonês	lindera	ipadic (uso geral), ipadic-neologd (termos modernos), unidic (académico)	Análise morfológica com tratamento de substantivos próprios	Entrada: "東京都渋谷区" Saída: ["東京", "都", "渋谷", "区"]
Coreano	lindera	ko-dic	Análise morfológica do coreano	Entrada: "안녕하세요" Saída: ["안녕", "하", "세요"]

Línguas multilingues ou desconhecidas

Para conteúdos em que as línguas são imprevisíveis ou misturadas nos documentos:

Tokenizador	Como funciona	Melhor para	Exemplos
icu	Tokenização com reconhecimento de Unicode (Componentes internacionais para Unicode)	Scripts mistos, idiomas desconhecidos ou quando a tokenização simples é suficiente	Entrada: "Hello 世界 مرحبا" Saída: ['Hello', ' ', '世界', ' ', 'مرحبا']

Quando usar icu:

• Idiomas mistos onde a identificação do idioma é impraticável.

• Não quer a sobrecarga de analisadores multilíngues ou o identificador de idioma.

• O conteúdo tem uma língua principal com palavras estrangeiras ocasionais que contribuem pouco para o significado geral (por exemplo, texto em inglês com nomes de marcas esporádicos ou termos técnicos em japonês ou francês).

Abordagens alternativas: Para um tratamento mais preciso do conteúdo multilingue, considere utilizar analisadores multilingues ou o identificador de idioma. Para obter detalhes, consulte Analisadores multilíngues ou Identificador de idioma.

Etapa 2: Adicionar filtros para obter precisão

Depois de selecionar o seu tokenizador, aplique filtros com base nos seus requisitos de pesquisa específicos e caraterísticas de conteúdo.

Filtros comumente usados

Estes filtros são essenciais para a maioria das configurações de idioma separadas por espaço (inglês, francês, alemão, espanhol, etc.) e melhoram significativamente a qualidade da pesquisa:

Filtro	Como funciona	Quando utilizar	Exemplos
lowercase	Converter todos os tokens em minúsculas	Universal - aplica-se a todas as línguas com distinção de maiúsculas e minúsculas	Entrada: ["Apple", "iPhone"] Saída: [['apple'], ['iphone']]
stemmer	Reduzir as palavras à sua forma de raiz	Línguas com inflexões de palavras (inglês, francês, alemão, etc.)	Para inglês: Input: ["running", "runs", "ran"] Saída: [['run'], ['run'], ['ran']]
stop	Remover palavras comuns sem significado	A maioria das línguas - particularmente eficaz para línguas separadas por espaços	Entrada: ["the", "quick", "brown", "fox"] Saída: [[], ['quick'], ['brown'], ['fox']]

Filtros de normalização de texto

Estes filtros normalizam as variações de texto para melhorar a consistência da correspondência:

Filtro	Como funciona	Quando usar	Exemplos
asciifolding	Converter caracteres acentuados em equivalentes ASCII	Conteúdo internacional, conteúdo gerado pelo utilizador	Entrada: ["café", "naïve", "résumé"] Saída: [['cafe'], ['naive'], ['resume']]

Filtragem de tokens

Controle quais tokens são preservados com base no conteúdo ou comprimento do caractere:

Filtro	Como funciona	Quando usar	Exemplos
removepunct	Remover tokens de pontuação independentes	Limpe a saída dos tokenizadores jieba, lindera, icu, que retornarão pontuações como tokens únicos	Entrada: ["Hello", "!", "world"] Saída: [['Hello'], ['world']]
alphanumonly	Manter apenas letras e números	Conteúdo técnico, processamento de texto limpo	Entrada: ["user123", "test@email.com"] Saída: [['user123'], ['test', 'email', 'com']]
length	Remover tokens fora do intervalo de comprimento especificado	Filtrar ruído (tokens excessivamente longos)	Entrada: ["a", "very", "extraordinarily"] Saída: [['a'], ['very'], []] (se max=10)
regex	Filtragem personalizada baseada em padrões	Requisitos de token específicos do domínio	Entrada: ["test123", "prod456"] Saída: [[], ['prod456']] (se expr="^prod")

Filtros específicos do idioma

Estes filtros tratam de caraterísticas específicas da língua:

Filtro	Idioma	Como funciona	Exemplos
decompounder	Alemão	Divide palavras compostas em componentes pesquisáveis	Entrada: ["dampfschifffahrt"] Saída: [['dampf', 'schiff', 'fahrt']]
cnalphanumonly	Chinês	Mantém caracteres chineses + alfanuméricos	Entrada: ["Hello", "世界", "123", "!@#"] Saída: [['Hello'], ['世界'], ['123'], []]
cncharonly	Chinês	Mantém apenas os caracteres chineses	Entrada: ["Hello", "世界", "123"] Saída: [[], ['世界'], []]

Etapa 3: Combinar e implementar

Para criar seu analisador personalizado, você define o tokenizador e uma lista de filtros no dicionário analyzer_params. Os filtros são aplicados na ordem em que são listados.

# 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,
    analyzer_params=analyzer_params,
)

Final: Teste com run_analyzer

Valide sempre a sua configuração antes de a aplicar a uma coleção:

# 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)

Problemas comuns a serem verificados:

• Excesso de tokenização: Termos técnicos sendo divididos incorretamente

• Sub-tokenização: As frases não estão a ser separadas corretamente

• Tokens em falta: Termos importantes sendo filtrados

Para uma utilização detalhada, consulte run_analyzer.

Configurações recomendadas por caso de uso

Esta secção fornece configurações recomendadas de tokenizador e filtro para casos de uso comuns ao trabalhar com analisadores no Milvus. Escolha a combinação que melhor corresponda ao seu tipo de conteúdo e requisitos de pesquisa.

Línguas com acentos (francês, espanhol, alemão, etc.)

Utilize um tokenizador standard com conversão em minúsculas, stemming específico do idioma e remoção de stopwords. Esta configuração também funciona para outros idiomas europeus, modificando os parâmetros language e stop_words.

# French example
analyzer_params = {
    "tokenizer": "standard",
    "filter": [
        "lowercase", 
        "asciifolding",  # Handle accent marks
        {
            "type": "stemmer",
            "language": "french"
        },
        {
            "type": "stop",
            "stop_words": ["_french_"]
        }
    ]
}

# For other languages, modify the language parameter:
# "language": "spanish" for Spanish
# "language": "german" for German
# "stop_words": ["_spanish_"] or ["_german_"] accordingly

Conteúdo em inglês

Para processamento de texto em inglês com filtragem abrangente. Também pode utilizar o analisador english analisador integrado:

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

# Equivalent built-in shortcut:
analyzer_params = {
    "type": "english"
}

Conteúdo em chinês

Utilize o tokenizador jieba e aplique um filtro de caracteres para reter apenas caracteres chineses, letras latinas e dígitos.

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

# Equivalent built-in shortcut:
analyzer_params = {
    "type": "chinese"
}

Conteúdo japonês

Utilize o tokenizador lindera com o dicionário japonês e filtros para limpar a pontuação e controlar o comprimento dos tokens:

analyzer_params = {
    "tokenizer": {
        "type": "lindera",
        "dict": "ipadic"  # Options: ipadic, ipadic-neologd, unidic
    },
    "filter": [
        "removepunct",  # Remove standalone punctuation
        {
            "type": "length",
            "min": 1,
            "max": 20
        }
    ]
}

Conteúdo coreano

Semelhante ao japonês, utilizando o tokenizador lindera com o dicionário coreano:

analyzer_params = {
    "tokenizer": {
        "type": "lindera",
        "dict": "ko-dic"
    },
    "filter": [
        "removepunct",
        {
            "type": "length",
            "min": 1,
            "max": 20
        }
    ]
}

Conteúdo misto ou multilingue

Ao trabalhar com conteúdo que abrange vários idiomas ou utiliza scripts de forma imprevisível, comece com o analisador icu. Este analisador com reconhecimento de Unicode lida eficazmente com scripts e símbolos mistos.

Configuração multilingue básica (sem stemming):

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

Processamento multilingue avançado:

Para um melhor controlo sobre o comportamento dos símbolos em diferentes idiomas:

• Utilize uma configuração de analisador multilingue. Para obter detalhes, consulte Analisadores multilíngues.

• Implemente um identificador de idioma no seu conteúdo. Para obter detalhes, consulte Identificador de idioma.

Integrar com recursos de recuperação de texto

Depois de selecionar o seu analisador, pode integrá-lo com as funcionalidades de recuperação de texto fornecidas pelo Milvus.

• Pesquisa de texto integral

  Os analisadores têm um impacto direto na pesquisa de texto completo baseada em BM25 através da geração de vectores esparsos. Utilize o mesmo analisador para indexação e consulta para garantir uma tokenização consistente. Os analisadores específicos de idioma geralmente fornecem melhor pontuação BM25 do que os genéricos. Para obter detalhes de implementação, consulte Pesquisa de texto completo.

• Correspondência de texto

  As operações de correspondência de texto efectuam a correspondência exacta de tokens entre consultas e conteúdo indexado com base na saída do analisador. Para obter detalhes de implementação, consulte Correspondência de texto.

• Correspondência de frases

  A correspondência de frases requer uma tokenização consistente em expressões com várias palavras para manter os limites e o significado das frases. Para obter detalhes de implementação, consulte Correspondência de frases.