Adicionar sinônimos à Pesquisa de IA do Azure

Em um serviço de pesquisa, um mapa de sinônimos associa termos equivalentes, expandindo o escopo de uma consulta sem que o usuário precise fornecer o termo. Por exemplo, supondo que cão, cachorro e cachorrinho sejam sinônimos mapeados, uma consulta de cachorro irá corresponder a um documento que contenha cão. 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.

Alguns pontos-chave sobre mapas de sinônimos:

• Um mapa de sinônimos é um recurso de nível superior que pode ser criado uma vez e usado por muitos índices.
• Um mapa de sinônimos se aplica a campos de cadeia de caracteres.
• Você pode criar e atribuir um mapa de sinônimos a qualquer momento sem interrupções na indexação ou consultas.
• Sua camada de serviço define os limites de quantos mapas de sinônimo você pode criar.
• Seu serviço de pesquisa pode ter vários mapas de sinônimos, mas dentro de um índice, uma definição de campo só pode ter uma atribuição de mapa de sinônimos.

Criar um 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 solr determina a construção de uma regra.

Para criar um mapa de sinônimos, faça isso programaticamente. O portal não dá suporte a definições de mapa de sinônimos.

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

Definindo regras

As regras de mapeamento aderem à especificação de filtro de sinônimos de código aberto do Apache Solr, descritos nesse documento: SynonymGraphFilter. 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 para um termo explícito)

Cada regra é delimitada pelo novo caractere de 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 uma regra. Para mais informações, confira Limites de sinônimos.

Analisadores de consulta reduzem automaticamente os termos de maiúsculas ou minúsculas. Para preservar caracteres especiais na cadeia de caracteres, como uma 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 nos EUA se expande para EUA OU "Estados Unidos" OU "Estados Unidos da América". Observe que, se você quiser fazer correspondência entre frases, a consulta em si deverá ser uma consulta de frase entre aspas.

No caso da equivalência, uma consulta de cão expande a consulta para também incluir cachorrinho e cachorro.

{
"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 de Washington, Wash. ou WA é reescrita como WA (abreviatura do estado de Washington) e o mecanismo de consulta procura apenas correspondências do termo WA. O mapeamento explícito aplica-se somente na direção especificada e não reescreve a consulta WA como Washington nesse caso.

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

Caracteres especiais de escape

Sinônimos são analisados durante o processamento de consulta, assim como qualquer outro termo de consulta, o que significa que as regras para caracteres reservados e especiais se aplicam aos termos em seu mapa de sinônimos. A lista de caracteres que requerem escape varia entre a sintaxe simples e a sintaxe completa:

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

Para preservar os caracteres descartados pelo analisador padrão, substitua 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 é em si um caractere especial em outras linguagens, como JSON e C#, você provavelmente precisa escapar duas vezes. Este é um exemplo em JSON:

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

Gerenciar mapas de sinônimos

Você pode atualizar um mapa de sinônimos sem interromper cargas de trabalho de consulta e indexação. No entanto, após adicionar um mapa de sinônimos a um campo, se você a seguir excluir um mapa de sinônimos, qualquer consulta que inclua os campos em questão irá falhar com um erro 404.

Criar, atualizar e excluir um mapa de sinônimos é sempre uma operação de documento inteiro. Você não pode atualizar ou excluir partes do mapa de sinônimos de forma incremental. Até mesmo para uma única regra a atualização requer um recarregamento.

Atribuir sinônimos para campos

Depois de criar o mapa de sinônimos, atribua-o a um campo em seu índice. Para atribuir mapas de sinônimos, faça isso programaticamente. O portal não dá suporte a associações de campo de mapa de sinônimos.

• Um campo deve ser do tipo Edm.String ou Collection(Edm.String)
• Um campo deve ter "searchable":true
• Um campo pode ter apenas um mapa de sinônimos

Se o mapa de sinônimos existir no serviço de pesquisa, ele será usado na próxima consulta, sem necessidade de reindexação ou recompilação.

PUT /indexes?api-version=2024-07-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"
            ]
        }
    ]
}

// Update an index
string indexName = "hotels";
SearchIndex index = new SearchIndex(indexName)
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("descriptionFr") { AnalyzerName = LexicalAnalyzerName.FrLucene }
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { SynonymMapNames = new[] { synonymMapName }, IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    }
};

await indexClient.CreateIndexAsync(index);

Consulta em campos equivalentes ou mapeados

Uma atribuição de campo de sinônimo não altera a forma como você escreve consultas. Após a atribuição do mapa de sinônimos, a única diferença é que, se houver um termo de consulta no mapa de sinônimos, o mecanismo de pesquisa expandirá ou reescreverá o termo ou a 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 da 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.

Internamente, o recurso de sinônimos reescreve uma consulta original com sinônimos usando o operador OR (OU). 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.

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.

Pesquisas com curinga

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>*.

Próxima etapa