Sinónimos no Azure AI Search

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 realmente fornecer o termo. Por exemplo, supondo que "cão", "canino" e "cachorro" sejam sinônimos mapeados, uma consulta sobre "canino" corresponde a um documento contendo "cão". Você pode criar vários mapas de sinônimos para idiomas diferentes, como versões em inglês e francês, ou léxicos se o seu conteúdo incluir jargão técnico, gírias ou terminologia obscura.

Alguns pontos-chave sobre mapas de sinônimos:

• Um mapa de sinônimo é um recurso de nível superior que pode ser criado uma vez e usado por muitos índices.
• Um mapa de sinônimo se aplica a campos de cadeia de caracteres.
• Você pode criar e atribuir um mapa de sinônimos a qualquer momento, sem interrupção da indexação ou consultas.
• Sua camada de serviço define os limites de quantos mapas de sinônimos 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ônimo.

Criar um mapa de sinónimos

Um mapa de sinônimo consiste em nome, formato e regras que funcionam como entradas de mapa de sinônimos. O único formato suportado é solr, e o formato determina a construção da solr regra.

Para criar um mapa de sinónimos, faça-o programaticamente. O portal não suporta definições de mapas 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"
}

Definir regras

As regras de mapeamento aderem à especificação de filtro de sinônimo de código aberto do Apache Solr, descrita neste documento: SynonymFilter. O solr formato suporta dois tipos de regras:

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

• mapeamentos explícitos (onde os termos são mapeados para um termo explícito)

Cada regra é delimitada pelo novo caractere de linha (\n). Você pode definir até 5.000 regras por mapa de sinônimo em um serviço gratuito e 20.000 regras por mapa em outras camadas. Cada regra pode ter até 20 expansões (ou itens em uma regra). Para obter mais informações, consulte Limites de sinônimos.

Os analisadores de consulta automaticamente minúsculas quaisquer termos maiúsculos ou mistos. Para 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 da mesma regra. No primeiro exemplo, uma consulta em USA expande-se para USA OR "United States" OR "United States of America". Observe que, se você quiser corresponder em uma frase, a consulta em si deve 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 corresponde ao lado esquerdo do é substituída pelas alternativas no lado direito no momento da => consulta.

No caso explícito, uma consulta para Washington, Wash. ou WA é reescrita como WA, e o mecanismo de consulta procura apenas correspondências no termo WA. O mapeamento explícito só se aplica na direção especificada e, nesse caso, não reescreve a consulta WA Washington .

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

Escapando de caracteres especiais

Os sinônimos são analisados durante o processamento da consulta 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 requer fuga varia entre a sintaxe simples e a sintaxe completa:

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

Para preservar caracteres que o analisador padrão descarta, substitua um analisador que os preserva. Algumas opções incluem analisadores de linguagem natural da Microsoft, que preserva 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 exemplo a seguir mostra um exemplo de como escapar 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 dela. Aqui está um exemplo em JSON:

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

Gerir mapas de sinónimos

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

Criar, atualizar e excluir um mapa de sinônimos é sempre uma operação de documento completo. Não é possível atualizar ou excluir partes do mapa de sinônimos incrementalmente. Atualizar até mesmo uma única regra requer uma recarga.

Atribuir sinónimos a campos

Depois de criar o mapa de sinônimos, atribua-o a um campo no índice. Para atribuir mapas de sinónimos, faça-o programaticamente. O portal não suporta 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ônimo

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

POST /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 anindex
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 existir um termo de consulta no mapa de sinônimos, o mecanismo de pesquisa expande ou reescreve o termo ou frase, dependendo da regra.

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

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

Para campos habilitados para sinônimos, os sinônimos estão sujeitos à mesma análise de texto que o campo associado. Por exemplo, se um campo é analisado usando o analisador Lucene padrão, os termos sinônimos também estã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 a consulta original com sinônimos com o operador OR. Por esse motivo, os perfis de destaque e pontuação tratam o termo original e os sinônimos como equivalentes.

Os sinónimos aplicam-se apenas a consultas de texto de forma livre e não são suportados para filtros, facetas, preenchimento automático ou sugestões. O preenchimento automático e as sugestões baseiam-se apenas no termo original; As correspondências de sinônimo não aparecem na resposta.

As expansões de sinônimo não se aplicam a termos de pesquisa curinga; Os termos prefixo, confuso e regex não são expandidos.

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

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

Próximos passos