Adicionar classificação semântica a consultas em Pesquisa de IA do Azure

Nota

Pesquisa de IA do Azure está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Você pode aplicar classificação semântica a consultas de texto, consultas híbridas e consultas de vetor se os documentos de pesquisa contiverem campos de cadeia de caracteres e a consulta de vetor tiver uma representação de texto no documento de pesquisa.

Este artigo explica como invocar o classificador semântico em consultas. Ele pressupõe que você esteja usando as APIs estáveis ou de visualização mais recentes. Para obter ajuda com versões mais antigas, consulte Migrar código de classificaçã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 uma configuração semântica e conteúdo de rich text.
Familiaridade com a classificação semântica.

Nota

Legendas e respostas são extraídas verbatim do texto no documento de pesquisa. O subsistema semântico usa a compreensão de leitura por máquina para reconhecer conteúdo com características de legenda ou resposta, mas não compõe novas sentenças nem frases, exceto no caso de reescrita de consulta (versão prévia). Por esse motivo, o conteúdo que inclui explicações ou definições funciona melhor para classificação semântica. Se você quiser uma interação no estilo de chat com respostas geradas, confira Recuperação Agentic ou Geração Aumentada por Recuperação (RAG).

Escolher um cliente

Você pode usar qualquer uma das seguintes ferramentas e SDKs para criar uma consulta que usa classificação semântica:

Azure portal, usando o designer de índice para adicionar uma configuração semântica.
Visual Studio Code com um cliente REST
SDK do Azure para .NET
SDK do Azure para Python
SDK do Azure para Java
SDK do Azure para JavaScript

Evitar recursos que ignoram a pontuação de relevância

Alguns recursos de consulta ignoram a pontuação de relevância, o que os torna incompatíveis com a classificação semântica. Se a lógica de consulta incluir os seguintes recursos, você não poderá classificar semanticamente seus resultados:

Uma consulta com search=* ou uma cadeia de caracteres de busca vazia, como uma consulta apenas com filtro puro, não funcionará porque não há nada para medir a relevância semântica e, portanto, as pontuações de busca resultam em zero. A consulta deve fornecer termos ou frases que possam ser avaliados durante o processamento e que produzam documentos de pesquisa que são pontuados para relevância. Os resultados pontuados são entradas para o classificador semântico.
A classificação (cláusulas orderBy) em campos específicos substitui pontuações de pesquisa e uma pontuação semântica. Considerando que a pontuação semântica deve fornecer a classificação, adicionar uma cláusula orderby resultará em um erro HTTP 400 se você aplicar a classificação semântica sobre os resultados ordenados.

Configurar a consulta

Por padrão, as consultas não usam classificação semântica. Para usar a classificação semântica, dois parâmetros diferentes podem ser usados. Cada parâmetro dá suporte a um conjunto diferente de formatos de consulta.

Todas as consultas semânticas, especificadas por meio search de mais queryTypeou por meio semanticQuery, devem ser texto sem formatação e não podem estar vazias. Como você pode ver na tabela abaixo, o parâmetro dá suporte a um subconjunto queryType-semantic de formatos de consulta.

Parâmetro	Pesquisa de texto sem formatação	Sintaxe de pesquisa de texto simples	Sintaxe de pesquisa de texto completo	Pesquisa de vetor	Pesquisa híbrida	Respostas semânticas e legendas
`queryType-semantic` ¹	✅	❌	❌	❌	✅	✅
`semanticQuery="<your plain text query>"` ²	✅	✅	✅	✅	✅	✅

¹queryType=semantic não pode dar suporte a simple ou full valores explícitos porque o parâmetro queryType está sendo usado para semantic. Os comportamentos de consulta eficaz são os padrões do analisador simples.

² O semanticQuery parâmetro pode ser usado para todos os tipos de consulta. No entanto, não há suporte no portal Azure Search Explorer.

Independentemente do parâmetro escolhido, o índice deve conter campos de texto com conteúdo semântico avançado e uma configuração semântica.

O Gerenciador de Pesquisa inclui opções de classificação semântica. Lembre-se de que você não pode definir o parâmetro semanticQuery no portal do Azure.

Acesse o serviço de pesquisa no Azure portal.
Abra um índice de pesquisa e selecione o Gerenciador de Pesquisa.
Selecione opções de consulta. Se você já definiu uma configuração semântica, ela será selecionada por padrão. Se você não tiver uma, crie uma configuração semântica para o índice.
Insira uma consulta, como "hotel histórico com boa comida" e selecione Pesquisar.

Como alternativa, selecione a exibição JSON e cole as definições no editor de consultas. O portal Azure não dá suporte ao uso de semanticQuery, portanto, é necessário definir queryType para "semantic":

Exemplo JSON para definir o tipo de consulta como semântico que você pode colar na exibição:

{
  "search": "funky or interesting hotel with good food on site",
  "count": true,
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "captions": "extractive|highlight-true",
  "answers": "extractive|count-3",
  "highlightPreTag": "<strong>",
  "highlightPostTag": "</strong>",
  "select": "HotelId,HotelName,Description,Category"
}

Use Documentos de Pesquisa para formular a solicitação.

A resposta inclui uma @search.rerankerScore automaticamente. Se você quiser legendas ou respostas na resposta, habilite a classificação semântica definindo queryTypesemantic ou definindo semanticQuery e adicionando legendas e respostas à solicitação.

Os exemplos a seguir nesta seção usam o índice de exemplo de hotéis para demonstrar classificação semântica com respostas semânticas e legendas.

Usar queryType=semantic

Se você quiser definir queryType para semantic, cole a seguinte solicitação em um cliente web como modelo. Substitua search-service-name pelo nome do serviço de pesquisa e substitua hotels-sample se você tiver um nome de índice diferente.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
      "search": "interesting hotel with restaurant on site and cozy lobby or shared area",
      "count": true,
      "queryType": "semantic",
      "semanticConfiguration": "semantic-config",
      "captions": "extractive|highlight-true",
      "answers": "extractive|count-3",
      "highlightPreTag": "<strong>",
      "highlightPostTag": "</strong>",
      "select": "HotelId,HotelName,Description,Category"
}

Definir queryType como semantic. Isso melhora a precisão dos resultados da pesquisa, reclassizando as 50 principais correspondências usando um modelo de classificação treinado no corpus do Bing para consultas expressas em linguagem natural em vez de palavras-chave. Se você definir o tipo de consulta como semântico, também deverá definir semanticConfiguration. Opcionalmente, você pode definir respostas se quiser retornar também as três principais respostas se a entrada da consulta tiver sido formulada em linguagem natural ("o que é ...) e, opcionalmente, você pode definir legendas para extrair as principais passagens dos documentos mais bem classificados.
Defina search como uma consulta simples de texto sem formatação. Desde que o queryType está configurado para semantic, a sintaxe simples ou a sintaxe lucene completa não são suportadas. Fornecer * ou uma cadeia de caracteres vazia não resulta em nenhuma classificação semântica sendo aplicada à consulta.
Defina semanticConfiguration como uma configuração semântica predefinida inserida no índice.
Defina answers para especificar se as respostas semânticas são incluídas no resultado. Os valores válidos para esse parâmetro são extractive e none. Esse parâmetro só será válido se o tipo de consulta for "semântico". Quando definido como "extrativo", a consulta formula e retorna respostas de passagens-chave nos documentos com classificação semanticamente mais altas. O padrão é uma resposta, mas você pode especificar até 10 adicionando uma contagem. Por exemplo, "answers": "extractive|count-3" retorna três respostas. Para que uma resposta seja retornada, deve haver conteúdo verbatim no campo de destino que pareça uma resposta. Os modelos de linguagem usados para respostas são treinados para reconhecer respostas, não gerá-las. Além disso, a consulta em si deve parecer uma pergunta.
Defina captions para especificar se as legendas semânticas estão incluídas no resultado. Os valores válidos são "none" e "extractive". O padrão é "none". Esse parâmetro só será válido se o tipo de consulta for "semântico". Quando definida como "extrativa", a consulta retorna legendas extraídas de passagens-chave nos documentos mais bem classificados.

Quando as legendas são definidas como 'extrativas', o realce é habilitado por padrão e pode ser configurado acrescentando o caractere de pipe '|' seguido pela opção highlight-<true/false> , como extractive|highlight-true. Este exemplo retorna legendas sem realces: extractive|highlight-false.

A base para legendas e respostas são os campos referenciados na "semanticConfiguration". Esses campos estão em um limite combinado no intervalo de 2.000 tokens ou aproximadamente 20.000 caracteres. Se você prever uma contagem de tokens que exceda esse limite, considere uma etapa de agrupamento de dados usando a habilidade de divisão de texto. Essa abordagem introduz uma dependência de um pipeline de enriquecimento de IA e indexadores.
Defina highlightPreTag e highlightPostTag se você quiser substituir a formatação de realce padrão que é aplicada a legendas.

As legendas aplicam a formatação de realce sobre as passagens de chave no documento que resumem a resposta. O padrão é <em>. Se você quiser especificar o tipo de formatação (por exemplo, plano de fundo amarelo), poderá definir o highlightPreTag e o highlightPostTag.
Defina selecionar para especificar quais campos são retornados na resposta e "contagem" para retornar o número de correspondências no índice. Esses parâmetros melhoram a qualidade da solicitação e da legibilidade da resposta.
Envie a solicitação para executar a consulta e retornar os resultados.

Use a função semanticQuery

Ao usar semanticQuery, você pode aplicar explicitamente a sintaxe de texto simples ou a sintaxe de texto completo, o que permite que você realize pesquisa por campo, impulsionamento de termos e pesquisa por proximidade. Você também pode especificar uma consulta de vetor puro em vez de apenas híbrida.

Ajuste sua solicitação para usar o seguinte JSON semanticQuery.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
    "search": "Description:breakfast",
    "semanticQuery": "interesting hotel with restaurant on site and cozy lobby or shared area",
    "count": true,
    "queryType": "full",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive|count-3",
    "highlightPreTag": "<strong>",
    "highlightPostTag": "</strong>",
    "select": "HotelId,HotelName,Description,Category"
}

Defina queryType como a sintaxe de pesquisa que você está usando, simples ou completa.
Defina semanticQuery como a consulta de texto simples sem formatação que você deseja usar para classificação semântica. Não há suporte para consultas vazias. Evite operadores ou qualquer sintaxe de consulta dentro da própria cadeia de caracteres.

Utilize QueryType ou SemanticQuery para invocar o classificador semântico em uma consulta semântica. O exemplo a seguir é da equipe do SDK do Azure.

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "interesting hotel with restaurant on site and cozy lobby or shared area",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive)
        },
        QueryType = SearchQueryType.Semantic
    });

int count = 0;
Console.WriteLine($"Semantic Search Results:");

Console.WriteLine($"\nQuery Answer:");
foreach (QueryAnswerResult result in response.SemanticSearch.Answers)
{
    Console.WriteLine($"Answer Highlights: {result.Highlights}");
    Console.WriteLine($"Answer Text: {result.Text}");
}

await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    count++;
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.HotelId}: {doc.HotelName}");

    if (result.SemanticSearch.Captions != null)
    {
        var caption = result.SemanticSearch.Captions.FirstOrDefault();
        if (caption.Highlights != null && caption.Highlights != "")
        {
            Console.WriteLine($"Caption Highlights: {caption.Highlights}");
        }
        else
        {
            Console.WriteLine($"Caption Text: {caption.Text}");
        }
    }
}
Console.WriteLine($"Total number of search results:{count}");

Para usar semanticQuery e não definir queryType como semantic, pode-se substituir o trecho de código de pesquisa pelo seguinte trecho de código:

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "Luxury hotel",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive),
            SemanticQuery = "Is there any hotel located on the main commercial artery of the city in the heart of New York?"
        }
    });

Avaliar a resposta

Somente as 50 primeiras correspondências dos resultados iniciais podem ser classificadas semanticamente. Assim como acontece com todas as consultas, uma resposta é composta por todos os campos marcados como recuperáveis ou apenas os campos listados no select parâmetro. Uma resposta inclui a pontuação de relevância original e também pode incluir uma contagem ou resultados em lote, dependendo de como você formulou a solicitação.

Na classificação semântica, a resposta tem mais elementos: uma nova pontuação de relevância semanticamente classificada, uma legenda opcional em texto sem formatação e com realces e uma resposta opcional. Se os resultados não incluirem esses elementos extras, a consulta poderá ser configurada incorretamente. Como uma primeira etapa para solucionar o problema, verifique a configuração semântica para garantir que ela seja especificada tanto na definição de índice quanto na consulta.

Em um aplicativo cliente, você pode estruturar a página de pesquisa para incluir uma legenda como a descrição da correspondência, em vez de todo o conteúdo de um campo específico. Essa abordagem é útil quando campos individuais são muito densos para a página de resultados da pesquisa.

A resposta para a consulta de exemplo acima ("hotel interessante com restaurante no local e lobby aconchegante ou área compartilhada") retorna três respostas ("answers": "extractive|count-e"). As legendas são retornadas porque a propriedade "captions" está definida, com texto sem formatação e versões realçadas. Se uma resposta não puder ser determinada, ela será omitida da resposta. Para fins de brevidade, este exemplo mostra apenas as três respostas e os três resultados de maior pontuação da consulta.

{
  "@odata.count": 29,
  "@search.answers": [
    {
      "key": "24",
      "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "score": 0.9340000152587891
    },
    {
      "key": "40",
      "text": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
      "highlights": "Only 8 miles from Downtown. <strong>On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, </strong>All non-smoking<strong> hotel.</strong> Only 15 miles from airport.",
      "score": 0.9210000038146973
    },
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our<strong> shared living space </strong>to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "score": 0.9200000166893005
    }
  ],
  "value": [
    {
      "@search.score": 3.2328331,
      "@search.rerankerScore": 2.575303316116333,
      "@search.captions": [
        {
          "text": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
          "highlights": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our<strong> penthouse </strong>suites offer views for miles and the rooftop<strong> plaza </strong>is open to all guests from sunset to 10 p.m. Enjoy a<strong> complimentary continental breakfast in the lobby, </strong>and free Wi-Fi<strong> throughout </strong>the hotel."
        }
      ],
      "HotelId": "50",
      "HotelName": "Head Wind Resort",
      "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
      "Category": "Suite"
    },
    {
      "@search.score": 0.632956,
      "@search.rerankerScore": 2.5425150394439697,
      "@search.captions": [
        {
          "text": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
          "highlights": "Every stay starts with a warm cookie. Amenities like the<strong> Counting Sheep sleep experience, </strong>our<strong> Wake-up glorious breakfast buffet and spacious workout facilities </strong>await."
        }
      ],
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Description": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
      "Category": "Budget"
    },
    {
      "@search.score": 3.7076726,
      "@search.rerankerScore": 2.4554927349090576,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
          "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "Category": "Suite"
    },
   . . .
  ]
}

Cargas de trabalho esperadas

Para classificação semântica, você deve esperar que um serviço de pesquisa dê suporte a até 10 consultas simultâneas por réplica.

O serviço limita as solicitações de classificação semântica se os volumes forem muito altos. Uma mensagem de erro que inclui essas frases indica que o serviço está em capacidade para classificação semântica:

Error in search query: Operation returned an invalid status 'Partial Content'`
@search.semanticPartialResponseReason`
CapacityOverloaded

Se você prever requisitos de desempenho consistentes próximos, iguais ou superiores a esse nível, registre um tíquete de suporte para que possamos atender sua carga de trabalho.

Próximas etapas

A classificação semântica pode ser usada em consultas híbridas que combinam pesquisa de palavra-chave e pesquisa de vetor em uma única solicitação e uma resposta unificada.

Consulta híbrida com rankeador semântico

Comentários

Esta página foi útil?

Last updated on 2026-05-12