Adicionar classificação semântica a consultas no Azure AI Search

Artigo
09/24/2024

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

Este artigo explica como invocar o classificador semântico em consultas.

Pré-requisitos

Um serviço de pesquisa, nível Básico ou superior, com classificação semântica ativada.
Um índice de pesquisa existente com uma configuração semântica e conteúdo rich text.
Revise a classificação semântica se precisar de uma introdução ao recurso.

Nota

As legendas e as respostas são extraídas literalmente do texto no documento de pesquisa. O subsistema semântico usa a compreensão de leitura automática para reconhecer conteúdo com as características de uma legenda ou resposta, mas não compõe novas frases ou frases. Por esse motivo, o conteúdo que inclui explicações ou definições funciona melhor para a classificação semântica. Se você quiser interação no estilo de bate-papo com as respostas geradas, consulte Geração aumentada de recuperação (RAG).

Escolha um cliente

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

Portal do Azure, usando o designer de índice para adicionar uma configuração semântica.
Código do Visual Studio com um cliente REST
Azure SDK for .NET (Azure SDK para .NET)
Azure SDK for Python (Azure SDK para Python)
SDK do Azure para Java
SDK do Azure para JavaScript

Evite 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, não será possível classificar semanticamente os resultados:

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

Configurar a consulta

Nesta etapa, adicione parâmetros à solicitação de consulta. Para ser bem-sucedida, sua consulta deve ser uma pesquisa de texto completo (usando o search parâmetro para passar uma cadeia de caracteres) ou uma consulta vetorial, e 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.

Inicie sessão no portal do Azure.
Abra um índice de pesquisa e selecione Explorador 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 seu índice.
Insira uma consulta, como "hotel histórico com boa comida", e selecione Pesquisar.

Como alternativa, selecione a visualização JSON e cole as definições no editor de consultas:

Aqui está um exemplo JSON 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",
  "queryLanguage": "en-us",
  "highlightPreTag": "<strong>",
  "highlightPostTag": "</strong>",
  "select": "HotelId,HotelName,Description,Category"
}

Use Pesquisar Documentos para formular a solicitação.

Uma resposta inclui um @search.rerankerScore automaticamente. Se quiser legendas ou respostas na resposta, adicione legendas e respostas à solicitação.

O exemplo a seguir nesta seção usa o hotels-sample-index para demonstrar a classificação semântica com respostas semânticas e legendas.

Cole a seguinte solicitação em um cliente da Web como um modelo. Substitua search-service-name pelo nome do serviço de pesquisa e substitua hotels-sample-index se tiver um nome de índice diferente.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-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",
      "queryLanguage": "en-us",
      "highlightPreTag": "<strong>",
      "highlightPostTag": "</strong>",
      "select": "HotelId,HotelName,Description,Category"
}

Defina "queryType" como "semântica".
Defina "pesquisar" como uma consulta de pesquisa de texto completo. Sua cadeia de caracteres de pesquisa pode suportar a sintaxe simples ou a sintaxe Lucene completa. A classificação semântica é uma extensão da pesquisa de texto completo, portanto, embora a "pesquisa" não seja necessária, você não obterá um resultado esperado se for uma pesquisa vazia ("search": "*").
Defina "semanticConfiguration" para uma configuração semântica predefinida incorporada no seu índice.
Defina "respostas" para especificar se as respostas semânticas são incluídas no resultado. Atualmente, o único valor válido para este parâmetro é extractive. As respostas podem ser configuradas para retornar um máximo de 10. O padrão é um. Este exemplo mostra uma contagem de três respostas: extractive|count-3.

As respostas não são garantidas em todos os pedidos. Para obter uma resposta, a consulta deve parecer uma pergunta e o conteúdo deve incluir texto que se pareça com uma resposta.
Defina "legendas" para especificar se as legendas semânticas serão incluídas no resultado. Atualmente, o único valor válido para este parâmetro é extractive. As legendas podem ser configuradas para retornar resultados com ou sem destaques. O padrão é que os destaques sejam retornados. 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 abaixo de um limite combinado no intervalo de 2.000 tokens ou aproximadamente 20.000 caracteres. Se você prevê uma contagem de tokens excedendo esse limite, considere uma etapa de fragmentação 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 quiser substituir a formatação de realce padrão aplicada às legendas.

As legendas aplicam formatação de realce sobre as principais passagens do documento que resumem a resposta. A predefinição é <em>. Se quiser especificar o tipo de formatação (por exemplo, fundo amarelo), você pode definir highlightPreTag e highlightPostTag.
Defina "select" para especificar quais campos são retornados na resposta e "count" para retornar o número de correspondências no índice. Estes parâmetros melhoram a qualidade do pedido e a legibilidade da resposta.
Envie a solicitação para executar a consulta e retornar os resultados.

Use 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)
        },
        QueryLanguage = QueryLanguage.EnUs,
        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}");

Avaliar a resposta

Apenas as 50 melhores partidas dos resultados iniciais podem ser classificadas 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 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 classificada semanticamente, uma legenda opcional em texto simples e com destaques e uma resposta opcional. Se os resultados não incluírem esses elementos extras, sua consulta poderá estar configurada incorretamente. Como primeiro passo para solucionar o problema, verifique a configuração semântica para garantir que ela seja especificada na definição do índice e 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. Por uma questão de brevidade, este exemplo mostra apenas as três respostas e os três resultados de 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 classificação semântica, você deve esperar que um serviço de pesquisa ofereça 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 estas frases indica que o serviço está na capacidade de classificação semântica:

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

Se você prevê requisitos de taxa de transferência consistentes próximos, iguais ou superiores a esse nível, envie um tíquete de suporte para que possamos provisionar sua carga de trabalho.

Próximos passos

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

Consulta híbrida com classificador semântico

Partilhar via