Configurar classificação semântica e devolver legendas nos resultados de pesquisa

A classificação semântica itera sobre um conjunto inicial de resultados, aplicando uma metodologia de classificação L2 que destaca os resultados semanticamente mais relevantes no topo da lista. Também pode obter legendas semânticas, com destaques sobre os termos e expressões mais relevantes, e respostas semânticas.

Este artigo explica como configurar um índice de pesquisa para 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 texto enriquecido. A classificação semântica aplica-se a campos de cadeias (não vetoriais) e funciona melhor em conteúdos informativos ou descritivos.

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

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

Escolha um cliente

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:

• Azure portal, usando o designer de índices para adicionar uma configuração semântica.
• Visual Studio Code com o cliente REST e uma API Create or Update Index (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 automaticamente uma configuração semântica. Se estiveres a usar agentic retrieval e uma fonte knowledge que indexa conteúdo no Pesquisa de IA do Azure, o teu índice gerado já tem uma configuração semântica que funciona para o teu conteúdo.

Para outras cargas de trabalho, podes configurar uma configuração semântica tu próprio. Uma configuração semântica é uma secção no seu índice que estabelece as entradas de campo usadas para a classificação semântica. Podes adicionar ou atualizar uma configuração semântica a qualquer momento, sem necessidade de reconstrução. Se criares várias configurações, podes especificar um padrão. No momento da consulta, especifique uma configuração semântica num pedido de consulta, ou deixe-a em branco para usar o predefinido.

Pode criar até 100 configurações semânticas num único índice.

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

Só podes especificar um campo de título, mas podes ter quantos campos de conteúdo e palavras-chave quiseres. Para campos de conteúdo e palavras-chave, liste os campos por 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 atribui devem ser:

• Atribuídos como searchable e retrievable
• Cadeias do tipo Edm.String, Collection(Edm.String), subcampos de cadeias 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")
                }
            })
        }
    }
};

Aderir a modelos de classificação semântica de pré-lançamento (versão preliminar)

Usando APIs REST de pré-visualização e SDKs do Azure em pré-visualização que disponibilizam essa propriedade, pode, opcionalmente, configurar um índice para usar modelos de classificação semântica em pré-lançamento, caso exista algum implementado na sua região. Não existe um mecanismo para saber se um pré-lançamento está disponível, ou se foi usado numa consulta específica. Por esta razão, recomendamos que utilize esta propriedade em ambientes de teste, e apenas se estiver interessado em experimentar os modelos de classificação semântica mais recentes.

A propriedade de configuração é "flightingOptIn": true, e está definida na secção de configuração semântica de um índice. A propriedade é nula ou falsa por defeito. Pode defini-lo verdadeiro num pedido de criação ou atualização a qualquer momento, e isso afeta as consultas semânticas no futuro, assumindo 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óximos passos

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