Sinônimos na IA do Azure Search

Em um serviço de pesquisa, os mapas de sinônimos são um recurso global que associa termos equivalentes, expandindo o escopo de uma consulta sem que o usuário precise realmente fornecer o termo. Por exemplo, supondo que "cachorro", "canino" e "cão" sejam sinônimos mapeados, uma consulta por "canino" encontrará uma correspondência em um documento que contém a palavra "cachorro".

Criar sinônimos

Um mapa de sinônimos é um ativo que pode ser criado uma vez e usado por vários índices. A camada de serviço determina quantos mapas de sinônimos você pode criar, com variação de três mapas de sinônimos para as camadas Gratuito e Básico, até 20 para as camadas Standard.

Você pode criar vários mapas de sinônimos para diferentes idiomas, como versões em inglês e francês, ou léxicos, se o conteúdo incluir jargão técnico, gíria ou terminologia obscura. Embora você possa criar vários mapas de sinônimos no seu serviço de pesquisa, dentro de um índice, uma definição de campo só pode ter uma atribuição de mapa de sinônimos.

Um mapa de sinônimos inclui nome, formato e regras que funcionam como entradas de mapa de sinônimos. O único formato com suporte é solr e o formato determina a construção de uma solr regra.

POST /synonymmaps?api-version=2023-11-01
{
    "name": "geo-synonyms",
    "format": "solr",
    "synonyms": "
        USA, United States, United States of America\n
        Washington, Wash., WA => WA\n"
}

Para criar um mapa de sinônimos, faça isso por meio de programação (o portal não dá suporte a definições do mapa de sinônimos):

• Criar um mapa de sinônimos (API REST). Essa referência é a mais descritiva.
• Classe SynonymMap (.NET) e Criar um mapa de sinônimos (Exemplo de SDK do Azure)
• Classe SynonymMap (Python)
• Interface SynonymMap (JavaScript)
• Classe SynonymMap (Java)

Definindo regras

Regras de mapeamento são compatíveis com a especificação de filtro de sinônimo de código aberto do Apache Solr, descrita neste documento: SynonymFilter. O formato solr dá suporte a dois tipos de regras:

• equivalência (em que os termos são substitutos por iguais na consulta)

• mapeamentos explícitos (em que os termos são mapeados por um termo explícito antes da consulta)

Cada regra deve ser delimitada por um caractere de uma nova linha (\n). É possível definir até 5.000 regras por mapa de sinônimos em um serviço gratuito e 20.000 regras em todas as outras camadas de serviço. Cada regra pode ter até 20 expansões (ou itens em alguma regra). Para mais informações, confira Limites de sinônimos.

Os analisadores de consulta automaticamente transformam em minúsculas termos em maiúsculas ou mistos, mas se você deseja preservar caracteres especiais na cadeia de caracteres, como vírgula ou traço, adicione os caracteres de escape apropriados ao criar o mapa de sinônimos.

Regras de equivalência

As regras para termos equivalentes são delimitadas por vírgulas dentro de uma mesma regra. No primeiro exemplo, uma consulta em USA expande para USA OU "United States" OU "United States of America". Observe que, se você quiser fazer correspondência entre frases, a consulta em si deverá ser uma consulta de frase entre aspas.

No caso de equivalência, uma consulta para dog expande a consulta para também incluir puppy e canine.

{
"format": "solr",
"synonyms": "
    USA, United States, United States of America\n
    dog, puppy, canine\n
    coffee, latte, cup of joe, java\n"
}

Mapeamento explícito

As regras para um mapeamento explícito são indicadas por uma seta =>. Quando especificado, uma sequência de termos de uma consulta de pesquisa que corresponda à esquerda de => é substituída com as alternativas do lado direito.

No caso explícito, uma consulta para Washington, Wash. ou WA será reescrita como WA, e o mecanismo de consulta só irá procurar correspondências no termo WA. O mapeamento explícito só é aplicável na direção especificada e não regrava a consulta WA em Washington nesse caso.

{
"format": "solr",
"synonyms": "
    Washington, Wash., WA => WA\n
    California, Calif., CA => CA\n"
}

Caracteres especiais de escape

Na pesquisa de texto completo, os sinônimos são analisados durante o processamento da consulta, assim como qualquer outro termo de consulta, o que significa que as regras em relação aos caracteres reservados e especiais se aplicam aos termos no mapa de sinônimos. A lista de caracteres que exige escape varia entre a sintaxe simples e a sintaxe completa:

• sintaxe simples+ | " ( ) ' \
• sintaxe completa+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Lembre-se de que, se você precisar preservar os caracteres que, de outra forma, seriam descartados pelo analisador padrão durante a indexação, deverá substituí-lo por um analisador que os preserve. Algumas opções incluem analisadores de idioma natural da Microsoft, que preservam palavras hifenizadas, ou um analisador personalizado para padrões mais complexos. Para obter mais informações, consulte Termos parciais, padrões e caracteres especiais.

O seguinte exemplo mostra um exemplo de como fazer o escape de um caractere com uma barra invertida:

{
    "format": "solr",
    "synonyms": "WA\, USA, WA, Washington\n"
}

Como a barra invertida é, por si só, um caractere especial em outras linguagens, como JSON e C#, você provavelmente precisará fazer uma saída dupla para ela. Por exemplo, o JSON enviado para a API REST sobre o mapa de sinônimos acima ficaria assim:

{
    "format":"solr",
    "synonyms": "WA\\, USA, WA, Washington"
}

Carregar e gerenciar mapas de sinônimos

Conforme mencionado anteriormente, você pode criar ou atualizar um mapa de sinônimos sem interromper as cargas de trabalho de consulta e de indexação. Um mapa de sinônimos é um objeto autônomo (como índices ou fontes de dados) e, desde que nenhum campo esteja utilizando, as atualizações não farão com que a indexação ou as consultas falhem. However, once you add a synonym map to a field definition, if you then delete a synonym map, any query that includes the fields in question will fail with a 404 error.No entanto, depois de adicionar um mapa de sinônimos a uma definição de campo, se você excluir um mapa de sinônimos, qualquer consulta que inclua os campos em questão apresentará erro 404.

Criar, atualizar e excluir um mapa de sinônimos é sempre uma operação de documento inteiro, o que significa que você não pode criar, atualizar nem excluir partes de um mapa de sinônimos incrementalmente. Até mesmo para uma única regra a atualização requer um recarregamento.

Atribuir sinônimos para campos

Depois de carregar um mapa de sinônimos, você pode habilitar os sinônimos em campos do tipo Edm.String ou Collection(Edm.String), em campos com "searchable":true. Como pode ser observado, uma definição de campo pode usar apenas um mapa de sinônimos.

POST /indexes?api-version=2023-11-01
{
    "name":"hotels-sample-index",
    "fields":[
        {
            "name":"description",
            "type":"Edm.String",
            "searchable":true,
            "synonymMaps":[
            "en-synonyms"
            ]
        },
        {
            "name":"description_fr",
            "type":"Edm.String",
            "searchable":true,
            "analyzer":"fr.microsoft",
            "synonymMaps":[
            "fr-synonyms"
            ]
        }
    ]
}

Consulta em campos equivalentes ou mapeados

Adicionar sinônimos não implica novas exigências na construção da consulta. Você pode emitir consultas de termo e frase da mesma forma como fazia antes da adição dos sinônimos. A única diferença é que, caso exista um termo de consulta no mapa de sinônimos, o mecanismo de consulta expandirá ou reescreverá o termo ou frase, dependendo da regra.

Como os sinônimos são usados durante a execução de uma consulta

Sinônimos são uma técnica de expansão da consulta que complementa o conteúdo de um índice com termos equivalentes, mas somente para campos que têm uma atribuição de sinônimo. Se uma consulta com escopo de campo excluir um campo habilitado para sinônimos, você não verá as correspondências do mapa de sinônimos.

Para campos habilitados para sinônimos, os sinônimos estão sujeitos à mesma análise de texto que um campo associado. Por exemplo, se um campo for analisado usando o analisador Lucene padrão, os termos de sinônimo também estarão sujeitos ao analisador Lucene padrão no momento de uma consulta. Se você quiser preservar a pontuação, como pontos ou traços, no termo sinônimo, aplique um analisador de preservação de conteúdo no campo.

O recurso de sinônimos regrava uma consulta original com sinônimos com o operador OR. Por esse motivo, os perfis de destaque e pontuação acessados tratam o termo original e os sinônimos como equivalentes.

Os sinônimos se aplicam somente a consultas de texto de forma livre e não têm suporte em filtros, facetas, preenchimento automático ou outras sugestões. O preenchimento automático e as sugestões baseiam-se apenas no termo original; correspondências de sinônimos não aparecem na resposta.

Expansões de sinônimos não se aplicam a termos de pesquisa curinga; prefixos, lógica difusa e termos de regex não são expandidos.

Se for necessário fazer uma única consulta que aplique expansão de sinônimos e curingas, regex ou pesquisas difusas, você poderá combinar as consultas usando a sintaxe OR. Por exemplo, para combinar sinônimos com curingas para uma sintaxe de consulta simples, o termo seria <query> | <query>*.

Se houver um índice em um ambiente de desenvolvimento (não produção), experimente um dicionário pequeno para ver como a adição de sinônimos altera a experiência de pesquisa, incluindo o impacto nos perfis de pontuação, o realce de acesso e as sugestões.

Próximas etapas

Criar um mapa de sinônimos (API REST)