Conclusão automática (API REST da Pesquisa de IA do Azure)

A API de Conclusão Automática termina uma entrada de consulta parcialmente digitada com termos existentes no índice de pesquisa para utilização numa consulta secundária. Por exemplo, se a entrada da consulta for "medic", a API de Conclusão Automática devolve "medicare", , "medicaid""medicine" se esses termos estiverem no índice. Internamente, o motor de busca procura termos correspondentes em campos que tenham um Suggester configurado.

É necessário HTTPS para pedidos de serviço. O pedido de Conclusão Automática pode ser construído com 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 do URL do pedido não pode exceder os 8 KB. Normalmente, este comprimento é suficiente para a maioria das aplicações. No entanto, algumas aplicações produzem consultas muito grandes, especificamente quando são utilizadas expressões de filtro OData. Para estas aplicações, HTTP POST é uma escolha melhor porque permite filtros maiores do que GET.

Com POST, o número de cláusulas num filtro é o fator limitativo, não o tamanho da cadeia de filtro não processado, uma vez que o limite de tamanho do pedido para POST é de aproximadamente 16 MB. Embora o limite de tamanho do pedido POST seja muito grande, as expressões de filtro não podem ser arbitrariamente complexas. Para obter mais informações sobre as limitações de complexidade do filtro, veja Sintaxe de Expressão OData para a Pesquisa de IA do Azure.

Parâmetros do URI

Recomendações de codificação de URL

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

• pesquisar
• $filter
• highlightPreTag
• highlightPostTag

A codificação de URL só é recomendada para parâmetros individuais. Se codificar inadvertidamente a cadeia de consulta inteira (tudo depois do ), os ?pedidos serão interrompidos.

Além disso, a codificação de URL só é necessária ao chamar a API REST diretamente com GET. Não é necessária codificação de URL ao utilizar POST ou ao utilizar a biblioteca de cliente .NET do Azure AI Search, que processa a codificação por si.

Cabeçalhos de Pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Corpo do Pedido

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 no URL quando é chamada com GET e como propriedades JSON no corpo do pedido quando chamada com POST. A sintaxe de alguns parâmetros é ligeiramente diferente entre GET e POST. Estas diferenças são indicadas conforme aplicável abaixo.

(1) Limitações de difusão na Conclusão Automática:

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

Em segundo lugar, o passo difuso ocorre após a expansão parcial do token e apenas os termos da mesma partição horizontal de índice são considerados para correspondências difusas. Esta restrição aumenta o desempenho da API de Conclusão Automática ao eliminar a agregação de correspondências difusas em todas as partições horizontais. Esta restrição torna-se menos percetível à medida que são adicionados mais termos ao índice, o que resulta numa distribuição de termos semelhante para cada partição horizontal. À medida que os termos são distribuídos uniformemente, as correspondências difusas dentro de uma partição horizontal são uma boa aproximação de correspondências difusas em todo o índice. No entanto, os resultados podem ser inferiores se o índice tiver menos termos, como num índice de teste ou protótipo, o que resulta na representação desigual entre partições horizontais. Para obter mais informações sobre como os índices são divididos em partições horizontais, veja combinações de partições e réplicas.

Resposta

Código de Estado: "200 OK" é devolvido para obter uma resposta bem-sucedida.

O payload de resposta tem duas propriedades.

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

Exemplos

Exemplo 1: Obtenha três sugestões de conclusão automática em que a entrada de pesquisa parcial está 'washington medic' com o modo predefinido (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: obtenha três sugestões de conclusão automática 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"
    }
  ]
}  

Repare que suggesterName é necessário numa operação de conclusão automática.

Ver também

• Adicionar sugestões a um índice
• Adicionar sugestões ou preenchimento automático a uma aplicação
• Códigos de estado HTTP