Adicionar classificação semântica às consultas no Pesquisa de IA do Azure

Nota

O Pesquisa de IA do Azure está disponível através do portal Azure, APIs REST e SDKs do Azure. Também sustenta o Foundry IQ, a camada de conhecimento gerida que transforma conteúdos empresariais em bases de conhecimento reutilizáveis e conscientes de permissões para agentes no portal Microsoft Foundry.

Pode aplicar classificação semântica a consultas de texto, consultas híbridas e consultas vetoriais se os seus documentos de pesquisa conterem campos de cadeia e a consulta vetorial tiver uma representação de texto no documento de pesquisa.

Este artigo explica como invocar o ranker semântico em consultas. Assume que estás a usar as APIs estáveis ou de pré-visualização mais recentes. Para 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 configuração semântica e conteúdo de texto enriquecido.
Familiaridade com a classificação semântica.

Nota

Legendas e respostas são extraídas literalmente do texto no documento de pesquisa. O subsistema semântico utiliza compreensão de leitura automática para reconhecer conteúdos com características de legenda ou resposta, mas não compõe novas frases ou frases exceto no caso de reescrita de consultas. Por esta razão, conteúdos que incluem explicações ou definições funcionam melhor para a classificação semântica. Se quiser interação ao estilo chat com respostas geradas, veja Recuperação Agentica ou Geração Aumentada de Recuperação (RAG).

Escolha um cliente

Pode usar qualquer uma das seguintes ferramentas e SDKs para construir uma consulta que utilize a classificação semântica:

Azure portal, usando o designer de índices 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

Evite funcionalidades que ignorem a pontuação de relevância

Algumas funcionalidades de consulta contornam a pontuação de relevância, o que as torna incompatíveis com a classificação semântica. Se a sua lógica de consulta incluir as seguintes funcionalidades, não pode classificar semanticamente os seus resultados:

Uma consulta com search=* ou uma string de pesquisa vazia, como uma consulta puramente com filtro, não funcionará porque não há nada para medir a relevância semântica e, por isso, as pontuações de pesquisa são zero. A consulta deve fornecer termos ou frases que possam ser avaliados durante o processamento e que produzam documentos de pesquisa pontuados quanto à relevância. Os resultados pontuados são entradas para o classificador semântico.
As cláusulas de ordenação (orderBy) em campos específicos têm precedência sobre as pontuações de resultados de pesquisa e a pontuação semântica. Dado que a pontuação semântica deve fornecer a classificação, adicionar uma cláusula orderby resulta num erro HTTP 400 se aplicares a classificação semântica sobre resultados ordenados.

Configurar a consulta

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

Todas as consultas semânticas, quer especificadas através de search mais queryType, ou através de semanticQuery, devem ser texto simples e não podem estar vazias. Como pode ver na tabela abaixo, o queryType-semantic parâmetro suporta um subconjunto de formatos de consulta.

Parâmetro	Pesquisa por texto simples	Sintaxe simples de pesquisa de texto	Sintaxe da pesquisa de texto completo	Pesquisa vetorial	Pesquisa Híbrida	Respostas semânticas e legendas
`queryType-semantic` ¹	✅	❌	❌	❌	✅	✅
`semanticQuery="<your plain text query>"` ²	✅	✅	✅	✅	✅	✅

¹queryType=semantic não pode suportar valores explícitos simple ou full porque queryType parâmetro está a ser usado para semantic. Os comportamentos efetivos de consulta são os valores padrão do parser simples.

² O semanticQuery parâmetro pode ser usado para todos os tipos de consulta. No entanto, não é suportado no portal Azure Explorador de Pesquisa.

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

O explorador de pesquisa inclui opções para classificação semântica. Lembra-te que não podes definir o parâmetro semanticQuery no portal Azure.

Vá ao seu serviço de pesquisa no portal Azure.
Abra um índice de pesquisa e selecione explorador de pesquisa.
Selecionar opções de consulta. Se já definiu uma configuração semântica, ela está selecionada por defeito. Se não tiveres nenhuma, cria uma configuração semântica para o teu índice.
Introduza uma consulta, como "hotel histórico com boa comida", e selecione Pesquisar.

Alternativamente, selecione a vista JSON e cole definições no editor de consultas. O portal Azure não suporta o uso de semanticQuery, por isso é necessário definir queryType para "semantic":

Exemplo JSON para definir o tipo de consulta em semântica que podes colar na vista:

{
  "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 Pesquisa de Documentos para formular o pedido.

Uma resposta inclui um @search.rerankerScore automaticamente. Se quiser legendas ou respostas na resposta, ative a classificação semântica definindo queryType como semantic ou adicionando semanticQuery legendas e respostas ao pedido.

Os exemplos seguintes nesta secção utilizam o índice de exemplos de hotéis para demonstrar a classificação semântica com respostas semânticas e legendas.

Use queryType=semântica

Se quiser definir queryType para semantic, cole o pedido seguinte num cliente web como modelo. Substitua search-service-name pelo nome do seu serviço de pesquisa e substitua hotels-sample se 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 para semantic. Isto melhora a precisão dos resultados de pesquisa ao reclassificar as 50 melhores correspondências usando um modelo de classificação treinado no Bing corpus para consultas expressas em linguagem natural em vez de palavras-chave. Se definires o tipo de consulta para semântica, também deves definir semanticConfiguration. Podes opcionalmente definir respostas se quiseres também devolver as 3 melhores respostas se a entrada da consulta foi formulada em linguagem natural ("o que é um ..."), e podes opcionalmente definir legendas para extrair passagens-chave dos documentos mais bem classificados.
Defina search para uma consulta de texto simples. Como o queryType está definido para semantic, sintaxe simples ou sintaxe Lucene completa não são suportadas. Fornecer * ou usar uma cadeia vazia resulta em que não seja aplicada uma classificação semântica à consulta.
Define semanticConfiguration para uma configuração semântica pré-definida que está embutida no teu índice.
Definido answers para especificar se as respostas semânticas estão incluídas no resultado. Os valores válidos para este parâmetro são extractive e none. Este parâmetro só é válido se o tipo de consulta for "semântico". Quando definido como "extrativo", a consulta formula e devolve respostas de passagens-chave nos documentos semanticamente mais bem classificados. O padrão é uma resposta, mas podes especificar até 10 adicionando uma contagem. Por exemplo, "answers": "extractive|count-3" devolve três respostas. Para que uma resposta seja devolvida, deve haver conteúdo literal no campo alvo que pareça uma resposta. Os modelos de linguagem usados para as respostas são treinados para reconhecer respostas, não para as gerar. Além disso, a própria consulta deve parecer uma pergunta.
Definido captions para especificar se as legendas semânticas estão incluídas no resultado. Valores válidos são "nenhum" e "extrativo". Por defeito, define-se como "nenhum". Este parâmetro só é válido se o tipo de consulta for "semântico". Quando definido como "extrativo", a consulta devolve legendas extraídas de passagens-chave nos documentos de maior classe.

Quando as legendas estão definidas como 'extrativo', o realce é ativado por defeito. Pode ser configurado adicionando o caractere pipe '|' seguido da opção highlight-<true/false>, como extractive|highlight-true. Este exemplo devolve legendas sem destaques: extractive|highlight-false.

A base para legendas e respostas são os campos referenciados na "semanticConfiguration". Estes campos estão abaixo de um limite combinado na ordem dos 2.000 tokens ou aproximadamente 20.000 caracteres. Se antecipar que um número de tokens ultrapasse esse limite, considere um passo de fragmentação de dados usando a competência Text split. Esta abordagem introduz uma dependência de um pipeline de enriquecimento de IA e indexadores.
Defina highlightPreTag e highlightPostTag se pretenderes substituir a formatação padrão dos realces aplicada às legendas.

As legendas aplicam formatação de destaque sobre trechos chave do documento que resumem a resposta. O padrão é <em>. Se quiseres especificar o tipo de formatação (por exemplo, fundo amarelo), podes definir o destaque PreTag e o destaque PostTag.
Defina select para especificar quais os campos que são devolvidos na resposta, e "count" para devolver o número de correspondências no índice. Estes parâmetros melhoram a qualidade do pedido e a legibilidade da resposta.
Envie o pedido para executar a consulta e devolva os resultados.

Utilize semanticQuery

Ao usar semanticQuery, pode aplicar explicitamente sintaxe de texto simples ou sintaxe de texto completo, o que significa que agora pode fazer pesquisa em campo, aumento de termos e pesquisa por proximidade. Também podes especificar uma consulta vetorial pura em vez de apenas híbrida.

Ajuste a sua requisição para o seguinte JSON para usar 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"
}

Define queryType para a sintaxe de pesquisa que estás a usar, seja simples ou completa.
Defina semanticQuery para a consulta de texto simples que pretende usar para a classificação semântica. Consultas vazias não são suportadas. Evite operadores ou qualquer sintaxe de consulta dentro da própria cadeia.

Use QueryType ou SemanticQuery para invocar o classificador semântico numa consulta semântica. O exemplo seguinte é da equipa 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 , em vez de definir queryType para semantic, o excerto de código de pesquisa pode ser substituído pelo seguinte excerto 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

Apenas os 50 melhores combates dos resultados iniciais podem ser classificados semanticamente. Como em 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 original de relevância e pode também incluir uma contagem, ou resultados agrupados, dependendo de como formulou o pedido.

Na classificação semântica, a resposta tem mais elementos: uma nova pontuação de relevância classificada semanticamente, uma legenda opcional em texto simples e com destaques, e uma resposta opcional. Se os seus resultados não incluírem estes elementos extra, então a sua consulta pode estar mal configurada. Como primeiro passo para resolver o problema, verifique a configuração semântica para garantir que está especificada tanto na definição do índice como na consulta.

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

A resposta para a pergunta de exemplo acima ("hotel interessante com restaurante no local e átrio acolhedor ou área partilhada") retorna três respostas ("answers": "extractive|count-e"). As legendas são devolvidas porque a propriedade "legendas" está definida, com texto simples e versões realçadas. Se uma resposta não for determinada, é omitida na resposta. Para ser breve, este exemplo mostra apenas as três respostas e os três resultados com a pontuação mais alta 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 a classificação semântica, deve esperar que um serviço de pesquisa suporte até 10 consultas simultâneas por réplica.

O serviço limita os pedidos de classificação semântica se os volumes forem demasiado elevados. Uma mensagem de erro que inclui estas frases indica que o serviço está ao limite de capacidade para classificação semântica:

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

Se antecipar requisitos consistentes de rendimento próximos, iguais ou superiores a este nível, por favor abra um pedido de suporte para que possamos providenciar a sua carga de trabalho.

Próximos passos

A classificação semântica pode ser usada em consultas híbridas que combinam pesquisa por palavras-chave e pesquisa vetorial num único pedido e numa resposta unificada.

Consulta híbrida com classificador semântico

Comentários

Esta página foi útil?

Last updated on 2026-05-12