Compartilhar via

Criar uma consulta híbrida na IA do Azure Search

A pesquisa híbrida combina texto (palavra-chave) e consultas de vetor em uma única solicitação de pesquisa. Ambas as consultas são executadas em paralelo. Os resultados são mesclados e reordenados por novas pontuações de busca, utilizando a Fusão de Rank Recíproco (RRF) para retornar um conjunto de resultados unificado. Em muitos casos, por testes de parâmetros de comparação, as consultas híbridas com classificação semântica retornam os resultados mais relevantes.

Neste artigo, aprenda a:

  • Configurar uma solicitação híbrida básica
  • Adicionar parâmetros e filtros
  • Melhorar a relevância usando pesos de vetor ou classificação semântica
  • Otimizar comportamentos de consulta controlando entradas (maxTextRecallSize)

Pré-requisitos

Escolha uma API ou ferramenta

  • O Gerenciador de Pesquisa no portal do Azure (dá suporte à sintaxe de pesquisa de API estável e de versão prévia) tem uma exibição JSON que permite colar em uma solicitação híbrida.

  • Pacotes estáveis ou de visualização mais recentes dos SDKs do Azure (confira os logs de alterações para suporte a recursos do SDK).

  • APIs REST estáveis ou uma versão da API de visualização recente se você estiver usando recursos de visualização, como maxTextRecallSize e countAndFacetMode(versão prévia).

    Para legibilidade, usamos exemplos REST para explicar como as APIs funcionam. Você pode usar um cliente REST como o Visual Studio Code com a extensão REST para criar consultas híbridas. Você também pode usar os SDKs do Azure. Para obter mais informações, consulte Início Rápido: Pesquisa de vetor.

Configurar uma consulta híbrida

Esta seção explica a estrutura básica de uma consulta híbrida e como configurar uma no Gerenciador de Pesquisa ou para execução em um cliente REST.

Os resultados são retornados em texto sem formatação, incluindo os vetores nos campos marcados como retrievable. Como os vetores numéricos não são úteis nos resultados da pesquisa, escolha outros campos no índice como um proxy para a correspondência de vetor. Por exemplo, se um índice tiver campos "descriptionVector" e "descriptionText", a consulta poderá corresponder em "descriptionVector", mas o resultado da pesquisa poderá mostrar "descriptionText". Use o parâmetro select para especificar apenas campos legíveis por humanos nos resultados.

  1. Entre no portal do Azure e localize seu serviço de pesquisa.

  2. EmÍndices de > de pesquisa, selecione um índice que tenha vetores e conteúdo não vetor. Gerenciador de Pesquisa é a primeira guia.

  3. Em Modo de Exibição, alterne para o modo de exibição JSON para que você possa colar em uma consulta de vetor.

  4. Substitua o modelo de consulta padrão por uma consulta híbrida. Uma consulta híbrida básica tem uma consulta de texto especificada e uma consulta de vetor especificada em searchvectorQueries.vector. A consulta de texto e a consulta de vetor podem ser equivalentes ou divergentes, mas é comum que elas compartilhem a mesma intenção.

    Este exemplo é do início rápido de vetores, que tem conteúdo vetorial e não vetorial e vários exemplos de consulta. Para fins de brevidade, o vetor está truncado neste artigo.

    {
    "search": "historic hotel walk to restaurants and shopping",
    "vectorQueries": [
        {
            "vector": [0.01944167, 0.0040178085, -0.007816401 ... <remaining values omitted> ], 
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

  5. Selecione Pesquisar.

    Dica

    Os resultados da pesquisa são mais fáceis de ler se você ocultar os vetores. Em Opções de Consulta, ative Ocultar valores de vetor nos resultados da pesquisa.

  6. Aqui está outra versão da consulta. Este adiciona um count para o número de correspondências encontradas, um select parâmetro para escolher campos específicos e um top parâmetro para retornar os sete principais resultados.

     {
     "count": true,
     "search": "historic hotel walk to restaurants and shopping",
     "select": "HotelId, HotelName, Category, Tags, Description",
     "top": 7,
     "vectorQueries": [
         {
             "vector": [0.01944167, 0.0040178085, -0.007816401 ... <remaining values omitted> ], 
             "k": 7,
             "fields": "DescriptionVector",
             "kind": "vector",
             "exhaustive": true
         }
     ]
 }

Definir maxTextRecallSize e countAndFacetMode

Observação

Esse recurso está atualmente em visualização pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para utilização em produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Uma consulta híbrida pode ser ajustada para controlar quanto de cada subconsulta contribui para os resultados combinados. A configuração maxTextRecallSize especifica quantos resultados classificados em BM25 são passados para o modelo de classificação híbrida.

Se você usar maxTextRecallSize, talvez você também queira definir CountAndFacetMode. Esse parâmetro determina se o count e facets deve incluir todos os documentos que corresponderam à consulta de pesquisa ou apenas os documentos recuperados dentro da maxTextRecallSize janela. O valor padrão é "countAllResults".

Recomendamos a visualização mais recente da API REST para configurar essas opções.

Dica

Outra abordagem para ajuste de consulta híbrida é a ponderação de vetor, usada para aumentar a importância das consultas vetoriais na solicitação.

  1. Use Pesquisa – POST (versão prévia) ou Pesquisa – GET (versão prévia) para especificar parâmetros de visualização.

  2. Adicione um objeto de parâmetro de consulta hybridSearch para definir o número máximo de documentos recuperados por meio dos resultados classificados como BM25 de uma consulta híbrida. Tem duas propriedades:

    • maxTextRecallSize especifica o número de resultados classificados pelo BM25 a serem fornecidos ao classificador de Fusão de Rank Recíproco (RRF) utilizado em consultas híbridas. O padrão é 1.000. O máximo é 10.000.

    • countAndFacetMode informa as contagens dos resultados classificados pelo BM25 (e das facetas, se você as estiver usando). O padrão são todos os documentos que correspondem à consulta. Opcionalmente, você pode incluir o escopo "contagem" em maxTextRecallSize.

  3. Definir maxTextRecallSize:

    • Diminuir maxTextRecallSize se a pesquisa de similaridade vetorial estiver superando o lado de texto da consulta híbrida.

    • Aumentar maxTextRecallSize se você tiver um índice grande e o padrão não estiver capturando um número suficiente de resultados. Com um conjunto maior de resultados com classificação BM25, você também pode definir top, skip e next para recuperar partes desses resultados.

Os exemplos REST a seguir mostram dois casos de uso para a definição de maxTextRecallSize.

O primeiro exemplo reduz maxTextRecallSize para 100, limitando o lado do texto da consulta híbrida a apenas 100 documentos. Ele também define countAndFacetMode para incluir somente os resultados de maxTextRecallSize.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview 

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_vector_field", 
          "k": 10 
        } 
      ], 
      "search": "hello world", 
      "hybridSearch": { 
        "maxTextRecallSize": 100, 
        "countAndFacetMode": "countRetrievableResults" 
      } 
    }

O segundo exemplo aumenta maxTextRecallSize para 5.000. Ele também usa top, skip e next para extrair resultados de grandes conjuntos de resultados. Nesse caso, a solicitação extrai os resultados classificados pela metodologia BM25, desde a posição 1.500 até 2.000, como contribuição da consulta de texto para o conjunto de resultados do método RRF.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview 

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_vector_field", 
          "k": 10 
        } 
      ], 
      "search": "hello world",
      "top": 500,
      "skip": 1500,
      "next": 500,
      "hybridSearch": { 
        "maxTextRecallSize": 5000, 
        "countAndFacetMode": "countRetrievableResults" 
      } 
    }

Exemplos de consultas híbridas

Esta seção tem vários exemplos de consulta que ilustram padrões de consulta híbrida.

Exemplo: pesquisa híbrida com filtro

Este exemplo adiciona um filtro que é aplicado aos campos filterable não-vetores do índice de pesquisa.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "vectorFilterMode": "preFilter",
    "filter": "ParkingIncluded",
    "top": "10"
}

Pontos principais:

  • Os filtros são aplicados ao conteúdo de campos filtrados. Neste exemplo, o campo ParkingIncluded é um booliano e está marcado como filterable no esquema de índice.

  • Em consultas híbridas, os filtros podem ser aplicados antes da execução da consulta para reduzir a superfície de consulta ou após a execução da consulta para cortar os resultados. "preFilter" é o padrão. Para usar postFilter ou strictPostFilter (versão prévia), defina o modo de processamento de filtro, conforme mostrado nesse exemplo.

  • Ao pós-filtrar os resultados da consulta, o número de resultados pode ser menor que os n principais.

Exemplo: pesquisa híbrida com filtros direcionados a subconsultas de vetor (versão prévia)

Usando a visualização da API REST mais recente, você pode substituir um filtro global na solicitação de pesquisa aplicando um filtro secundário direcionado apenas às subconsultas de vetor em uma solicitação híbrida.

Esse recurso fornece controle refinado, garantindo que os filtros influenciam apenas os resultados da busca em vetores, deixando os resultados da pesquisa baseados em palavra-chave não afetados.

O filtro de destino substitui totalmente o filtro global, incluindo todos os filtros usados para corte de segurança ou pesquisa geoespacial. Nos casos em que sejam necessários filtros globais, como o ajuste de segurança, você deve incluir explicitamente esses filtros tanto no filtro no nível mais alto quanto em cada filtro de nível de vetor, para garantir que a segurança e outras restrições sejam aplicadas de forma consistente.

Para aplicar filtros vetoriais direcionados:

Aqui está um exemplo de consulta híbrida que adiciona uma substituição de filtro. O filtro global "Classificação maior que 3" é substituído em tempo de execução pelo filterOverride.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-08-01-preview

{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true,
            "filterOverride": "Address/City eq 'Seattle'",
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Address/City, Rating",
    "filter": "Rating gt 3"
    "debug": "vector",
    "top": 10
}

Supondo que você tenha um classificador semântico e sua definição de índice inclua uma configuração semântica, você pode formular uma consulta que inclui pesquisa de vetor e pesquisa de palavra-chave, com classificação semântica sobre o conjunto de resultados mesclado. Opcionalmente, você pode adicionar legendas e respostas.

Sempre que você usar a classificação semântica com vetores, verifique se k está definido como 50. O classificador semântico usa até 50 correspondências como entrada. Especificar menos de 50 priva os modelos de classificação semântica de entradas necessárias.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 50
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Tags",
    "queryType": "semantic",
    "semanticConfiguration": "my-semantic-config",
    "captions": "extractive",
    "answers": "extractive",
    "top": "50"
}

Pontos principais:

  • O classificador semântico aceita até 50 resultados da resposta mesclada.

  • "queryType" e "semanticConfiguration" são necessários.

  • As legendas e as respostas são opcionais. Os valores são extraídos do texto literal nos resultados. Uma resposta só será retornada se os resultados incluírem conteúdo com as características de uma resposta para a consulta.

Exemplo: pesquisa híbrida semântica com filtro

Esta é a última consulta na coleção. É a mesma consulta semântica híbrida do exemplo anterior, mas com um filtro.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 50
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Tags",
    "queryType": "semantic",
    "semanticConfiguration": "my-semantic-config",
    "captions": "extractive",
    "answers": "extractive",
    "filter": "ParkingIsIncluded'",
    "vectorFilterMode": "preFilter",
    "top": "50"
}

Pontos principais:

  • O modo de filtro pode afetar o número de resultados disponíveis para o reclassificador semântico. Como prática recomendada, é inteligente dar ao classificador semântico o número máximo de documentos (50). Se os pré-filtros ou os pós-filtros forem muito seletivos, você poderá estar prejudicando o classificador semântico, dando-lhe menos de 50 documentos para trabalhar.

  • preFilter é aplicado antes da execução da consulta. Se o pré-filtro reduzir a área de pesquisa para 100 documentos, a consulta de vetor será executada no campo DescriptionVector desses 100 documentos, retornando as melhores correspondências k=50. Esses 50 documentos correspondentes passam para o RRF para obter resultados mesclados e, em seguida, para o classificador semântico.

  • postFilter é aplicado após a execução da consulta. Se k=50 retornar 50 correspondências no lado da consulta vetor, seguido por um pós-filtro aplicado às 50 correspondências, seus resultados serão reduzidos pelo número de documentos que atendem aos critérios de filtro. Isso deixa você com menos de 50 documentos para passar para o classificador semântico. Tenha isso em mente se você estiver usando a classificação semântica. O classificador semântico funciona melhor se tiver 50 documentos como entrada.

  • strictPostFilter (versão prévia) é aplicado nos resultados k superiores não filtrados após a execução da consulta. Ele sempre retorna menos ou igual a k documentos. Se o k=50 não filtrado retornar 50 resultados não filtrados e o filtro corresponder a 30 documentos, apenas 30 documentos serão retornados no conjunto de resultados, mesmo que o índice tenha mais de 30 documentos que correspondam ao filtro. Como esse modo tem a maior redução no recall, não recomendamos que você o use com o classificador semântico.

Configurar uma resposta de consulta

Ao configurar a consulta híbrida, pense na estrutura de resposta. O mecanismo de pesquisa classifica os documentos correspondentes e retorna os resultados mais relevantes. A resposta é um conjunto de linhas bidimensional. Os parâmetros na consulta determinam quais campos estão em cada linha e quantas linhas estão na resposta.

Campos em uma resposta

Os resultados da pesquisa são compostos por campos retrievable do seu índice de pesquisa. Um resultado pode ter:

  • Todos os campos retrievable (um padrão da API REST).
  • Campos explicitamente listados em um select parâmetro na consulta.

Os exemplos neste artigo usaram uma select instrução para especificar campos de texto (não vetor) na resposta.

Observação

Os vetores não são submetidos a engenharia reversa em texto legível por humanos, portanto, evite retorná-los na resposta. Em vez disso, escolha campos não vetoriais que sejam representativos do documento de pesquisa. Por exemplo, se a consulta tiver como alvo um campo "DescriptionVector", retorne um campo de texto equivalente, se você tiver um ("Description") na resposta.

Número de resultados

Uma consulta pode corresponder a qualquer número de documentos, até mesmo a todos eles, se os critérios de pesquisa forem fracos (por exemplo, "search=*" para uma consulta nula). Como nem sempre é prático retornar resultados não associados, você deve especificar um máximo para a resposta geral:

  • "top": n resultados para consultas somente palavra-chave (sem vetor)
  • "k": n resultados de consultas somente de vetores
  • "top": n resultados de consultas híbridas (com ou sem semântica) que incluem um parâmetro "search"

k e top são opcionais. Não especificado, 50 é o número padrão de resultados em uma resposta. Você pode definir top e skip para navegar por mais resultados ou alterar o padrão.

Observação

Se você estiver usando a pesquisa híbrida na API 2024-05-01-preview, poderá controlar o número de resultados da consulta de palavra-chave usando maxTextRecallSize. Combine isso com uma configuração de k para controlar a representação de cada subsistema de pesquisa (palavra-chave e vetor).

Resultados do classificador semântico

Observação

O classificador semântico pode levar até 50 resultados.

Se você estiver usando o classificador semântico na versão 2024-05-01-preview ou posterior, é uma prática recomendada definir a soma total de k e maxTextRecallSize para pelo menos 50. Em seguida, você pode restringir os resultados retornados ao usuário com o top parâmetro.

Se você estiver usando o classificador semântico em APIs anteriores, faça o seguinte:

  • Para pesquisa somente de palavra-chave (sem vetores) definida top como 50
  • Para a pesquisa híbrida definida k como 50, para garantir que o classificador semântico obtenha pelo menos 50 resultados.

Classificação

Vários conjuntos são criados para consultas híbridas, com ou sem a reclassificação semântica opcional. A classificação dos resultados é calculada pela Fusão de Ranking Recíproco (RRF).

Nesta seção, compare as respostas entre a busca em vetores única e a pesquisa híbrida simples para obter o melhor resultado. Os diferentes algoritmos de classificação, a métrica de similaridade do HNSW e a RRF, respectivamente, produzem pontuações que têm magnitudes diferentes. Este é o comportamento padrão. As pontuações da RRF podem parecer bem baixas, mesmo com uma correspondência de alta similaridade. Pontuações mais baixas são uma característica do algoritmo da RRF. Em uma consulta híbrida com a RRF, mais da recíproca dos documentos classificados são incluídos nos resultados, dada a pontuação relativamente menor dos documentos classificados pela RRF, em vez da busca em vetores tão somente.

Pesquisa de Vetor Único: @search.score para resultados ordenados por similaridade de cosseno (função padrão de distância de similaridade de vetor).

{
    "@search.score": 0.8399121,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
    "Category": "Luxury",
    "Address": {
    "City": "Arlington"
    }
}

Pesquisa Híbrida: @search.score para resultados híbridos classificados usando a Fusão de Classificação Recíproca.

{
    "@search.score": 0.032786883413791656,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
    "Category": "Luxury",
    "Address": {
    "City": "Arlington"
    }
}

Próxima etapa

Recomendamos examinar o código de demonstração de vetor para Python, C# ou JavaScript.

  • Last updated on