Configurar o classificador semântico e retornar legendas nos resultados da pesquisa

A classificação semântica itera sobre um conjunto inicial de resultados, aplicando uma metodologia de classificação L2 que promove os resultados mais semanticamente relevantes ao 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 a reclassificação semântica.

Pré-requisitos

• Pesquisa de IA do Azure  em qualquer região que forneça classificação semântica.

• Um índice de pesquisa existente com conteúdo de rich text. A classificação semântica aplica-se a campos de cadeias de caracteres (não vetores) e funciona melhor em conteúdo informativo ou descritivo.

• Permissão para criar e usar objetos no Pesquisa de IA do Azure . Recomendamos o acesso baseado em função, mas você pode usar chaves de API se uma atribuição de função não for viável. Para obter mais informações, consulte Conectar-se a um serviço de pesquisa.

• A versão 2026-08-01-preview da API REST do Serviço de Pesquisa.

Escolher um cliente

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

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

Adicionar uma configuração semântica

Algumas cargas de trabalho criam uma configuração semântica automaticamente. Se você estiver usando agentic retrieval e uma fonte knowledge que indexa conteúdo em Pesquisa de IA do Azure , seu índice gerado já tem uma configuração semântica que funciona para seu conteúdo.

Para outras cargas de trabalho, você pode configurar uma configuração semântica por conta própria. Uma configuração semântica é uma seção em seu índice que estabelece as entradas de campo usadas para classificação semântica. Você pode adicionar ou atualizar uma configuração semântica a qualquer momento, sem necessidade de recompilaçã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:

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

Em todas as propriedades de configuração semântica, os campos que você atribuir devem ser:

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

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")
                }
            })
        }
    }
};

Aceitar modelos de classificação semântica de pré-lançamento (versão prévia)

Usando APIs REST de visualização e SDKs do Azure de visualização que fornecem a propriedade, você pode configurar opcionalmente um índice para usar modelos de classificação semântica de pré-lançamento, caso algum deles esteja implantado em sua região. Não há mecanismo para saber se um pré-lançamento está disponível ou se foi usado em uma consulta específica. 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 de configuração é "flightingOptIn": truee está 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 true em uma solicitação de criação ou atualização a qualquer momento e isso afeta as consultas semânticas que avançam, supondo que a consulta estipula uma configuração semântica que inclua a propriedade.

PUT https://myservice.search.windows.net/indexes('hotels')?allowIndexDowntime=False&api-version=2026-08-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óximas etapas

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