Preenchimento automático (API REST do Azure AI Search)

Artigo
02/28/2024

A API de Preenchimento Automático conclui uma entrada de consulta parcialmente tipada usando termos existentes no índice de pesquisa para uso em uma consulta secundária. Por exemplo, se a entrada de consulta for "medic", a API de Preenchimento Automático retornará "medicare", "medicaid", "medicine" se esses termos estiverem no índice. Internamente, o mecanismo de pesquisa procura termos correspondentes em campos que têm um Sugestor configurado.

HTTPS é necessário para as solicitações de serviço. A solicitação de preenchimento automático pode ser construída usando os métodos GET ou POST.

GET https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?[query parameters]
  Content-Type: application/json   
  api-key: [admin or query key]

POST https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?api-version=[api-version]
  Content-Type: application/json   
  api-key: [admin or query key]

Quando chamado com GET, o comprimento da URL de solicitação não pode exceder 8 KB. Esse comprimento geralmente é suficiente para a maioria dos aplicativos. No entanto, alguns aplicativos produzem consultas muito grandes, especificamente quando expressões de filtro OData são usadas. Para esses aplicativos, HTTP POST é uma opção melhor porque permite filtros maiores que GET.

Com o POST, o número de cláusulas em um filtro é o fator limitante, não o tamanho da cadeia de caracteres de filtro não processada, uma vez que o limite de tamanho da solicitação POST é quase 16 MB. Embora o limite de tamanho da solicitação POST seja muito grande, as expressões de filtro não podem ser arbitrariamente complexas. Para obter mais informações sobre limitações de complexidade de filtro, consulte Sintaxe de expressão OData para a Pesquisa de IA do Azure.

Parâmetros de URI

Parâmetro	Descrição
[nome do serviço]	Obrigatórios. Defina isso como o nome exclusivo definido pelo usuário do serviço de pesquisa.
[nome do índice]/docs	Obrigatórios. Especifica a coleção de documentos de um índice nomeado.
api-version	Obrigatórios. Confira Versões de API para obter uma lista de versões com suporte. Para consultas, a api-version é sempre especificada como um parâmetro de URI para GET e POST.

Recomendações de codificação de URL

Lembre-se de codificar parâmetros de consulta específicos da URL ao chamar a API REST GET diretamente. Para preenchimento automático, a codificação de URL pode ser necessária para os seguintes parâmetros de consulta:

pequisa
$filter
highlightPreTag
highlightPostTag

A codificação de URL só é recomendada para parâmetros individuais. Se você usar a codificação de URL inadvertidamente para a cadeia de caracteres de consulta inteira (tudo após o ?), as solicitações são interrompidas.

Além disso, a codificação de URL só é necessária ao se chamar a API REST diretamente usando GET. Nenhuma codificação de URL é necessária ao usar POST ou ao usar a biblioteca de clientes .NET do Azure AI Search, que manipula a codificação para você.

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionais

Campos Descrição

Tipo de conteúdo Obrigatórios. Defina-o como application/json

chave de API Opcional se você estiver usando funções do Azure e um token de portador for fornecido na solicitação, caso contrário, uma chave será necessária. As solicitações de consulta na docs coleção podem especificar admin-key ou query-key como o api-key. A chave de consulta é usada para operações somente leitura em uma coleção de documentos de índice. Confira Conectar-se ao Azure AI Search usando a autenticação de chave para obter detalhes.

Campos	Descrição
Tipo de conteúdo	Obrigatórios. Defina-o como `application/json`
chave de API	Opcional se você estiver usando funções do Azure e um token de portador for fornecido na solicitação, caso contrário, uma chave será necessária. As solicitações de consulta na `docs` coleção podem especificar admin-key ou query-key como o `api-key`. A chave de consulta é usada para operações somente leitura em uma coleção de documentos de índice. Confira Conectar-se ao Azure AI Search usando a autenticação de chave para obter detalhes.

Corpo da solicitação

Para GET: Nenhum.

Para POST:

{  
  "autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
  "filter": "odata_filter_expression",
  "fuzzy": true | false (default),  
  "highlightPreTag": "pre_tag",  
  "highlightPostTag": "post_tag",  
  "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),
  "search": "partial_search_input",  
  "searchFields": "field_name_1, field_name_2, ...",
  "suggesterName": "suggester_name",  
  "top": # (default 5)  
}

Parâmetros de consulta

Uma consulta aceita vários parâmetros na URL quando chamada com GET e como propriedades JSON no corpo da solicitação quando chamada com POST. A sintaxe para alguns parâmetros é ligeiramente diferente entre GET e POST. Essas diferenças são indicadas conforme aplicável abaixo.

Nome	Tipo	Descrição
api-version	string	Obrigatórios. Versão da API REST usada para a solicitação. Para obter uma lista de versões com suporte, consulte Controle de versão da API. Para essa operação, a api-version é especificada como um parâmetro de URI, independentemente de você chamar Preenchimento Automático com GET ou POST.
Autocompletemode	string	Opcional. O padrão é oneTerm. Os valores válidos são oneTerm, twoTerms, oneTermWithContext. oneTerm retorna um único termo. Se a consulta tiver dois termos, somente o último termo será concluído. Por exemplo, dado `"washington medic"`, a resposta pode ser qualquer um destes termos únicos: `"medicaid"`, `"medicare"`, `"medicine"`. twoTerms corresponde a frases de dois termos no índice. Por exemplo, dado `"medic"`, a resposta pode ser `"medicare coverage"`ou `"medical assistant"`. Em muitos casos, os termos `"medicare"` únicos ou `"medical"` não seriam retornados porque a preferência é dada a frases de dois termos que correspondem. oneTermWithContext conclui o último termo em uma consulta com dois ou mais termos, em que os dois últimos termos são uma frase que existe no índice. Por exemplo, dado `"washington medic"`, a resposta pode ser `"washington medicaid"`, `"washington medical"`.
$filter	string	Opcional. Uma expressão de pesquisa estruturada na sintaxe OData padrão que filtra os documentos considerados para produzir as sugestões de termo concluídas. Não há suporte para expressões de filtro "search.ismatch" e "search.ismatchscoring*" na API de preenchimento automático. Somente campos filtráveis podem ser usados em um filtro. Quando chamado com POST, esse parâmetro é nomeado filtro em vez de $filter. Consulte Sintaxe de expressão OData para a Pesquisa de IA do Azure para obter detalhes sobre o subconjunto da gramática de expressão OData compatível com o Azure AI Search.
difuso	booleano	Opcional. O padrão é false. Quando definida como true, essa API encontra sugestões mesmo se houver um caractere substituído ou ausente no texto de pesquisa ⁽¹⁾. Isso fornece uma experiência melhor em alguns cenários, mas tem um custo de desempenho, pois as pesquisas de sugestões difusas são mais lentas e consomem mais recursos.
highlightPostTag	string	Opcional. O padrão é uma cadeia de caracteres vazia. Uma marca de cadeia de caracteres que acrescenta ao termo realçado. Deve ser definido com highlightPreTag. Caracteres reservados na URL devem ser codificados por percentual (por exemplo, %23, em vez de #). Quando chamado usando GET, os caracteres reservados na URL devem ser codificados por porcentagem (por exemplo, %23 em vez de #).
highlightPreTag	string	Opcional. O padrão é uma cadeia de caracteres vazia. Uma marca de cadeia de caracteres que precede o termo realçado. Deve ser definido com highlightPostTag. Quando chamado usando GET, os caracteres reservados na URL devem ser codificados por porcentagem (por exemplo, %23 em vez de #).
minimumCoverage	inteiro	Opcional. O padrão é 80. Um número entre 0 e 100 indicando a porcentagem do índice que deve estar disponível para atender à consulta antes que ela possa ser relatada como um sucesso. O padrão reflete um desvio em relação à velocidade e à eficiência em relação à cobertura completa. A redução da cobertura restringe a expansão da consulta, permitindo que os resultados voltem mais rapidamente. Ele também permite que a consulta tenha êxito na disponibilidade parcial do índice, mesmo que um fragmento esteja lento para responder ou indisponível devido a problemas de integridade do serviço ou manutenção de índice. Seja qual for o valor de minimumCoverage, esse percentual do índice deve estar disponível ou o preenchimento automático retornará HTTP status código 503. Se o preenchimento automático for bem-sucedido no nível mínimo de Descoberta, ele retornará HTTP 200 e incluirá um @search.coverage valor na resposta indicando a porcentagem do índice que estava disponível ao atender a consulta. A redução desse valor poderá ser útil se ocorrerem erros 503. Caso contrário, você poderá considerar aumentar o valor se a resposta estiver fornecendo correspondências insuficientes.
pequisa	string	Obrigatórios. O texto a ser pesquisado. O texto de pesquisa a ser concluído. Deve ter pelo menos 1 e não mais que 100 caracteres. Ele não pode conter operadores, sintaxe de consulta ou frases entre aspas.
searchFields	string	Opcional. A lista de nomes de campos separada por vírgulas para pesquisar o texto de pesquisa especificado. Os campos de destino devem ser listados na definição sugestores no índice.
suggesterName	string	Obrigatórios. O nome do sugestor conforme especificado na coleção Suggesters que faz parte da definição de índice. Um sugestor determina quais campos são verificados quanto aos termos de consulta sugeridos.
$top	inteiro	Opcional. O padrão é 5. O número de sugestões de preenchimento automático a serem recuperadas. O valor deve ser um número entre 1 e 100. Quando chamado com POST, esse parâmetro é nomeado top em vez de $top.

(1) Limitações de difuso no preenchimento automático:

Primeiro, a distância de edição é limitada a apenas uma diferença de caracteres por token, ao contrário do parâmetro difuso na pesquisa. Limitar a distância de edição a um caractere significa que nem todas as correspondências de candidatos serão encontradas, mas o limite é necessário para garantir um nível aceitável de desempenho.

Em segundo lugar, a etapa difusa ocorre após a expansão parcial do token e somente os termos do mesmo fragmento de índice são considerados para correspondências difusas. Essa restrição aumenta o desempenho da API de Preenchimento Automático eliminando a agregação de correspondências difusas em todos os fragmentos. Essa restrição se torna menos perceptível à medida que mais termos são adicionados ao índice, resultando em distribuição de termo semelhante para cada fragmento. Como os termos são distribuídos uniformemente, as correspondências difusas dentro de um fragmento são uma boa aproximação de correspondências difusas em todo o índice. No entanto, os resultados poderão ser inferiores se o índice tiver menos termos, como em um índice de teste ou protótipo, resultando na representação desigual entre fragmentos. Para obter mais informações sobre como os índices são divididos em fragmentos, consulte combinações de partição e réplica.

Resposta

Código de status: "200 OK" é retornado para uma resposta bem-sucedida.

O conteúdo da resposta tem duas propriedades.

Propriedade	Descrição
"texto"	O termo ou frase concluído
"queryPlusText"	A entrada de consulta inicial mais o termo ou frase concluído

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [
    {
      "text": "...",
      "queryPlusText": "..."
    },
    ...  
  ]
}

Exemplos

Exemplo 1: Recupere três sugestões de preenchimento automático em que a entrada de pesquisa parcial é 'washington medic' com o modo padrão (oneTerm):

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",
  "filter": "search.in(roleId, 'admin,manager')",
  "top": 3,
  "suggesterName": "sg"  
}

Resposta:

{    
  "value": [
    {
      "text": "medicaid",
      "queryPlusText": "washington medicaid"
    },
    {
      "text": "medicare",
      "queryPlusText": "washington medicare"
    },
    {
      "text": "medicine",
      "queryPlusText": "washington medicine"
    }
  ]
}

Exemplo 2: recuperar três sugestões de preenchimento automático em que a entrada de pesquisa parcial é 'washington medic' e autocompleteMode=twoTerms:

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",  
  "autocompleteMode": "twoTerms",
  "filter": "planDuration ge 1",
  "top": 3,  
  "suggesterName": "sg"  
}

Resposta:

{    
  "value": [
    {
      "text": "medicaid insurance",
      "queryPlusText": "washington medicaid insurance"
    },
    {
      "text": "medicare plan",
      "queryPlusText": "washington medicare plan"
    },
    {
      "text": "medicine book",
      "queryPlusText": "washington medicine book"
    }
  ]
}

Observe que suggesterName é necessário em uma operação de preenchimento automático.

Compartilhar via