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.

Nota

Se tem código existente que chama a pré-visualização ou versões anteriores da API, veja Migrar o código de classificação semântica para obter ajuda em como modificar o seu código.

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-05-01-preview das APIs 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.

Quando a configuração semântica é opcional

Importante

Estas funcionalidades fazem parte da API REST preview de 2026-05-01-. A 2026-05-01-preview é-lhe licenciada como parte da sua subscrição do Azure e está sujeita aos termos aplicáveis a "Previews" nos Termos dos Produtos Microsoft, na Adenda sobre a Proteção de Dados dos Produtos e Serviços Microsoft ("DPA") e nos Termos de Utilização Suplementares para as Pré-visualizações do Microsoft Azure.

A pré-visualização 2026-05-01 suporta ligações a outros serviços da Microsoft e serviços de terceiros. A utilização destes serviços está sujeita aos respetivos termos e pode resultar no processamento ou armazenamento de dados fora do limite de conformidade do Azure, bem como no fluxo de dados para o limite de conformidade do Azure.

É sua responsabilidade gerir se os seus dados irão fluir para além dos limites de conformidade e geográficos da sua organização e quaisquer implicações relacionadas, e garantir que as permissões, limites e aprovações apropriadas sejam providenciadas.

És responsável por rever e testar cuidadosamente as aplicações que constróis no contexto dos teus casos de uso específicos e por tomar todas as decisões e personalizações apropriadas. Isto inclui implementar as suas próprias mitigações de IA responsável, como metaprompts, filtros de conteúdo ou outros sistemas de segurança, e assegurar que as suas aplicações cumprem os padrões adequados de qualidade, fiabilidade, segurança e confiabilidade. Para mais informações, consulte a Nota de Transparência Pesquisa de IA do Azure.

Na API 2026-05-01-preview, os fluxos de recuperação agêntica suportados podem usar o comportamento de classificação do Pesquisa de IA do Azure sem necessitarem de uma configuração semântica explícita no índice subjacente. Este comportamento de pré-visualização ajuda as equipas a começar com a recuperação da base de conhecimento sem bloquear a autoria de configurações semânticas.

Esta alteração não remove a configuração clássica de classificação semântica. Continue a definir uma configuração semântica para consultas clássicas de pesquisa semântica, versões antigas da API e cargas de trabalho que necessitem de controlo explícito sobre os campos de título, conteúdo e palavras-chave.

Para fontes de conhecimento para índices de pesquisa, semanticConfigurationName continua a ser uma propriedade suportada. Define quando quiseres que a fonte de conhecimento use uma configuração semântica específica. Nos fluxos de recuperação agêntica suportados 2026-05-01-preview, pode omiti-lo quando quiser que o serviço utilize o comportamento de pré-visualização que não exige uma configuração semântica explícita no índice subjacente.

A configuração semântica é opcional apenas para os fluxos de recuperação de bases de conhecimento baseados em agentes suportados que utilizam a API 2026-05-01-preview. As consultas clássicas de pesquisa semântica e versões antigas da API ainda requerem uma configuração semântica quando se usa a classificação semântica. Se criares um índice sem uma configuração semântica para o fluxo de pré-visualização, não assumas que o mesmo índice pode ser usado inalterado com o GA ou APIs de classificação semântica mais antigas.

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

Propriedade	Características
Campo do título	Uma sequência curta, 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 tiveres campo adequado, deixa-o em branco.
Campos de conteúdo	Blocos mais longos de texto em forma de linguagem natural, sujeitos a limites máximos de entrada de tokens nos modelos de aprendizagem automática. Exemplos comuns incluem o corpo de um documento, descrição de um produto ou outro texto livre.
Campos de palavras-chave	Uma lista de palavras-chave, como as etiquetas num documento, ou um termo descritivo, como a categoria de um item.

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

Vá ao seu serviço de pesquisa no portal Azure.
A partir de Índices no painel de navegação à esquerda, escolha um índice.
Selecione configurações semânticas e depois selecione Adicionar configuração semântica.
Na página de Nova configuração semântica , introduza um nome de configuração semântica e selecione os campos a usar na configuração semântica. Apenas campos de string pesquisáveis e recuperáveis são elegíveis. Certifica-te de listar os campos de conteúdo e os campos de palavras-chave por ordem de prioridade.
Selecione Guardar para guardar as definições de configuração.
Selecione Guardar novamente na página do índice para guardar a configuração semântica no índice.

Formule um pedido de Criação ou Atualização de Índice .

Adicione uma configuração semântica à definição do índice, talvez depois de scoringProfiles ou suggesters. Especificar um padrão é opcional, mas útil se tiveres mais do que 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 seguinte é da amostra semântic ranking elaborada pela equipa 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")
                }
            })
        }
    }
};

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

Nota

Esta funcionalidade está atualmente em pré-visualização. Esta pré-visualização é fornecida sem um acordo de nível de serviço e não é recomendada para cargas de trabalho em produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos de Utilização Suplementares para Microsoft Azure Pré-visualizações.

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

Criar uma consulta semântica

Comentários

Esta página foi útil?

Last updated on 2026-06-03