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

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.

Portal do Azure

O explorador de pesquisa inclui opções para classificação semântica.

1. Inicie sessão no portal do Azure.

2. Abra um índice de pesquisa e selecione Explorador de pesquisa.

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

   

4. Insira uma consulta, como "hotel histórico com boa comida", e selecione Pesquisar.

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

   

   Aqui está um texto JSON que você pode colar na exibição:

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

API REST

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.

1. Cole a seguinte solicitação em um cliente da Web como um modelo. Substitua o nome do serviço e o nome do índice por valores válidos.

   POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01      
   {
       "queryType": "semantic",
       "search": "newer hotel near the water with a great restaurant",
       "semanticConfiguration": "my-semantic-config",
       "answers": "extractive|count-3",
       "captions": "extractive|highlight-true",
       "highlightPreTag": "<strong>",
       "highlightPostTag": "</strong>",
       "select": "HotelId,HotelName,Description,Category",
       "count": true
   }
   

2. Defina "queryType" como "semântica".

3. 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": "*").

4. Defina "semanticConfiguration" para uma configuração semântica predefinida incorporada no seu índice.

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

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

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

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

9. Envie a solicitação para executar a consulta e retornar os resultados.

SDK do .NET

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>(
    "Is there any hotel located on the main commercial artery of the city in the heart of New York?",
    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 retorna a seguinte correspondência como a opção principal. As legendas são retornadas porque a propriedade "captions" está definida, com texto sem formatação e versões realçadas. As respostas são omitidas do exemplo porque não foi possível determinar uma para esta consulta e corpus em particular.

"@odata.count": 35,
"@search.answers": [],
"value": [
    {
        "@search.score": 1.8810667,
        "@search.rerankerScore": 1.1446577133610845,
        "@search.captions": [
            {
                "text": "Oceanside Resort. Luxury. New Luxury Hotel. Be the first to stay. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
                "highlights": "<strong>Oceanside Resort.</strong> Luxury. New Luxury Hotel. Be the first to stay.<strong> Bay</strong> views from every room, location near the pier, rooftop pool, waterfront dining & more."
            }
        ],
        "HotelName": "Oceanside Resort",
        "Description": "New Luxury Hotel. Be the first to stay. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
        "Category": "Luxury"
    },
  ...
]

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