Configurar classificadores semânticos e legendas de retorno nos resultados da pesquisa

2025-04-09

A classificação semântica itera sobre um conjunto de resultados inicial, aplicando uma metodologia de classificação L2 que promove os resultados semanticamente mais relevantes para o topo da lista. Você também pode obter legendas semânticas, com destaques sobre os termos e frases mais relevantes, e respostas semânticas.

Este artigo explica como configurar um índice de pesquisa para reclassificação semântica.

Nota

Se tiver código existente que chame a pré-visualização ou versões anteriores da API, veja Migrar Código de classificação semântica para obter ajuda com a modificação do código.

Pré-requisitos

Um serviço de busca num nível Básico ou superior, sujeito à disponibilidade da região.
Classificador semântico ativado no seu serviço de pesquisa.
Um índice de pesquisa existente com conteúdo rich text. A classificação semântica aplica-se a campos de cadeia de caracteres (não vetoriais) e funciona melhor em conteúdo informativo ou descritivo.

Escolha um cliente

Você pode especificar uma configuração semântica em índices novos ou existentes, usando qualquer uma das seguintes ferramentas e kits de desenvolvimento de software (SDKs) para adicionar uma configuração semântica:

Portal do Azure, usando o designer de índice para adicionar uma configuração semântica.
Visual Studio Code com o cliente REST e uma API REST de Criação ou Atualização de Índice.
Azure SDK for .NET (Azure SDK para .NET)
Azure SDK for Python (Azure SDK para Python)
SDK do Azure para Java
SDK do Azure para JavaScript

Adicionar uma configuração semântica

Uma configuração semântica é uma seção em seu índice que estabelece entradas de campo para classificação semântica. Você pode adicionar ou atualizar uma configuração semântica a qualquer momento, sem necessidade de reconstrução. Se você criar várias configurações, poderá especificar um padrão. No momento da consulta, especifique uma configuração semântica em uma solicitação de consulta ou deixe-a em branco para usar o padrão.

Você pode criar até 100 configurações semânticas em um único índice.

Uma configuração semântica tem um nome e as seguintes propriedades:

Propriedade	Características
Campo Título	Um texto curto, idealmente com menos de 25 palavras. Este campo pode ser o título de um documento, o nome de um produto ou um identificador único. Se não tiver um campo adequado, deixe-o em branco.
Campos de conteúdo	Blocos mais longos de texto em linguagem natural, sujeitos a limites máximos de entrada de token nos modelos de aprendizado de máquina. Exemplos comuns incluem o corpo de um documento, a descrição de um produto ou outro texto de forma livre.
Campos de palavras-chave	Uma lista de palavras-chave, como as tags em um documento, ou um termo descritivo, como a categoria de um item.

Você só pode especificar um campo de título, mas pode ter quantos campos de conteúdo e palavra-chave quiser. Para campos de conteúdo e palavra-chave, liste os campos em ordem de prioridade porque os campos de prioridade mais baixa podem ficar truncados.

Em todas as propriedades de configuração semântica, os campos atribuídos devem ser:

Atribuído como searchable e retrievable
Strings do tipo Edm.String, Collection(Edm.String), subcampos de strings de Edm.ComplexType

Entre no portal do Azure e navegue até um serviço de pesquisa que tenha a classificação semântica habilitada.
Em Índices no painel de navegação esquerdo, selecione um índice.
Selecione Configurações semânticas e, em seguida, selecione Adicionar configuração semântica.
Na página Nova configuração semântica, insira um nome de configuração semântica e selecione os campos a serem usados na configuração semântica. Apenas campos de string pesquisáveis e recuperáveis são elegíveis. Certifique-se de listar campos de conteúdo e campos de palavras-chave em ordem de prioridade.
Selecione Salvar para salvar as definições de configuração.
Selecione Salvar novamente na página de índice para salvar a configuração semântica no índice.

Formule uma solicitação Criar ou Atualizar Índice .

Adicione uma configuração semântica à definição de índice, talvez depois scoringProfiles ou suggesters. Especificar um padrão é opcional, mas útil se você tiver mais de uma configuração.

"semantic": {
    "defaultConfiguration": "my-semantic-config-default",
    "configurations": [
        {
            "name": "my-semantic-config-default",
            "prioritizedFields": {
                "titleField": {
                    "fieldName": "HotelName"
                },
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ],
                "prioritizedKeywordsFields": [
                    {
                        "fieldName": "Tags"
                    }
                ]
            }
        },
                    {
            "name": "my-semantic-config-desc-only",
            "prioritizedFields": {
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ]
            }
        }
    ]
}

Use a classe SemanticConfiguration no SDK do Azure para .NET.

O exemplo a seguir é do exemplo de classificação semântica criado pela equipe do SDK do Azure.

string indexName = "hotel";
SearchIndex searchIndex = new(indexName)
{
    Fields =
    {
        new SimpleField("HotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true, IsFacetable = true },
        new SearchableField("HotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("Description") { IsFilterable = true },
        new SearchableField("Category") { IsFilterable = true, IsSortable = true, IsFacetable = true },
    },
    SemanticSearch = new()
    {
        Configurations =
        {
            new SemanticConfiguration("my-semantic-config", new()
            {
                TitleField = new SemanticField("HotelName"),
                ContentFields =
                {
                    new SemanticField("Description")
                },
                KeywordsFields =
                {
                    new SemanticField("Category")
                }
            })
        }
    }
};

Optar por modelos de classificação semântica de pré-lançamento

Nota

Esta funcionalidade está atualmente em pré-visualização pública. Esta pré-visualização é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

A partir das APIs REST 2025-03-01-preview e nos SDKs do Azure que fornecem a propriedade, você pode, opcionalmente, configurar um índice para usar modelos de classificação semântica de pré-lançamento, se um for implantado em sua região. Não há nenhum mecanismo para saber se um pré-lançamento está disponível ou se foi usado em consultas específicas. Por esse motivo, recomendamos que você use essa propriedade em ambientes de teste e somente se estiver interessado em experimentar os modelos de classificação semântica mais recentes.

A propriedade configuration é "flightingOptIn": true, e é definida na seção de configuração semântica de um índice. A propriedade é nula ou falsa por padrão. Você pode defini-lo como verdadeiro em uma solicitação de criação ou atualização a qualquer momento, e isso afetará as consultas semânticas daqui em diante, desde que a consulta estipule uma configuração semântica que inclua a propriedade.

PUT https://myservice.search.windows.net/indexes('hotels')?allowIndexDowntime=False&api-version=2025-03-01-preview

{
  "name": "hotels",
  "fields": [ ],
  "scoringProfiles": [ ],
  "defaultScoringProfile": "geo",
  "suggesters": [ ],
  "analyzers": [ ],
  "corsOptions": { },
  "encryptionKey": { },
  "similarity": { },
  "semantic": {
    "configurations": [
      {
        "name": "semanticHotels",
        "prioritizedFields": {
          "titleField": {
            "fieldName": "hotelName"
          },
        "prioritizedContentFields": [
            {
              "fieldName": "description"
            },
            {
              "fieldName": "description_fr"
            }
          ],
        "prioritizedKeywordsFields": [
            {
              "fieldName": "tags"
            },
            {
              "fieldName": "category"
            }
          ],
        "flightingOptIn": true
        }
      }
    ]
  },
  "vectorSearch": {  }
}

Próximos passos

Teste sua configuração semântica executando uma consulta semântica.

Criar uma consulta semântica