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

Artigo
02/28/2024

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

Parâmetro	Description
[nome do serviço]	Obrigatório. Defina-o como o nome exclusivo definido pelo utilizador do seu serviço de pesquisa.
[nome do índice]/docs	Obrigatório. Especifica a coleção de documentos de um índice com nome.
api-version	Obrigatório. Veja Versões da API para obter uma lista de versões suportadas. Para consultas, a versão da API é 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 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.

Campos Description

Content-Type Obrigatório. Defina esta opção como application/json

api-key Opcional se estiver a utilizar funções do Azure e for fornecido um token de portador no pedido, caso contrário, é necessária uma chave. Os pedidos de consulta na docs coleção podem especificar uma chave de administrador ou uma chave de consulta como .api-key A chave de consulta é utilizada para operações só de leitura numa coleção de documentos de índice. Veja Connect to Azure AI Search using key authentication (Ligar à Pesquisa de IA do Azure com a autenticação de chaves ) para obter detalhes.

Campos	Description
Content-Type	Obrigatório. Defina esta opção como `application/json`
api-key	Opcional se estiver a utilizar funções do Azure e for fornecido um token de portador no pedido, caso contrário, é necessária uma chave. Os pedidos de consulta na `docs` coleção podem especificar uma chave de administrador ou uma chave de consulta como .`api-key` A chave de consulta é utilizada para operações só de leitura numa coleção de documentos de índice. Veja Connect to Azure AI Search using key authentication (Ligar à Pesquisa de IA do Azure com a autenticação de chaves ) para obter detalhes.

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.

Nome	Tipo	Description
api-version	string	Obrigatório. Versão da API REST utilizada para o pedido. Para obter uma lista das versões suportadas, veja Controlo de versões da API. Para esta operação, a versão da API é especificada como um parâmetro URI, independentemente de chamar Conclusão Automática com GET ou POST.
autocompleteMode	string	Opcional. A predefinição é oneTerm. Os valores válidos são oneTerm, twoTerms, oneTermWithContext. oneTerm devolve um único termo. Se a consulta tiver dois termos, apenas 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 expressões 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 devolvidos porque a preferência é dada a expressões de dois termos que correspondem. oneTermWithContext conclui o último termo numa consulta com dois ou mais termos, em que os dois últimos termos são uma expressão 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. As expressões de filtro "search.ismatch" e "search.ismatchscoring*" não são suportadas na API de Conclusão Automática. Apenas os campos filtráveis podem ser utilizados num filtro. Quando chamado com POST, este parâmetro tem o nome filter em vez de $filter. Veja Sintaxe da Expressão OData para a Pesquisa de IA do Azure para obter detalhes sobre o subconjunto da gramática da expressão OData suportada pelo Azure AI Search.
difuso	boolean	Opcional. O valor predefinido é falso. Quando definida como verdadeira, esta API encontra sugestões mesmo que exista um caráter substituído ou em falta no texto de pesquisa ⁽¹⁾. Isto proporciona uma melhor experiência em alguns cenários, mas tem um custo de desempenho, uma vez que as pesquisas de sugestões difusas são mais lentas e consomem mais recursos.
highlightPostTag	string	Opcional. A predefinição é uma cadeia vazia. Uma etiqueta de cadeia que acrescenta ao termo realçado. Tem de ser definido com highlightPreTag. Os carateres reservados no URL têm de estar codificados por percentagem (por exemplo, %23 em vez de #). Quando chamados com GET, os carateres reservados no URL têm de estar codificados por percentagem (por exemplo, %23 em vez de #).
highlightPreTag	string	Opcional. A predefinição é uma cadeia vazia. Uma etiqueta de cadeia que se prepara para o termo realçado. Tem de ser definido com highlightPostTag. Quando chamados com GET, os carateres reservados no URL têm de estar codificados por percentagem (por exemplo, %23 em vez de #).
minimumCoverage	número inteiro	Opcional. A predefinição é 80. Um número entre 0 e 100 que indica a percentagem do índice que tem de estar disponível para servir a consulta antes de poder ser reportado como um êxito. A predefinição reflete uma tendência para a velocidade e eficiência em relação à cobertura total. A redução da cobertura restringe a expansão das consultas, permitindo que os resultados voltem mais rapidamente. Também permite que a consulta tenha êxito na disponibilidade parcial do índice, mesmo que uma partição horizontal seja lenta a responder ou indisponível devido a problemas de estado de funcionamento do serviço ou manutenção do índice. Qualquer que seja o valor de minimumCoverage, essa percentagem do índice tem de estar disponível ou a conclusão automática devolve o código de estado HTTP 503. Se a Conclusão Automática for concluída com êxito ao nível mínimo de Recuperação, devolve HTTP 200 e inclui um @search.coverage valor na resposta que indica a percentagem do índice que estava disponível ao servir a consulta. A redução deste valor poderá ser útil se estiverem a ocorrer erros 503. Caso contrário, poderá considerar aumentar o valor se a resposta fornecer correspondências insuficientes.
pesquisar	string	Obrigatório. O texto a procurar. O texto de pesquisa a concluir. Tem de ter, pelo menos, 1 caráter e não ter mais de 100 carateres. Não pode conter operadores, sintaxe de consulta ou expressões citadas.
campos de pesquisa	string	Opcional. A lista de nomes de campos separados por vírgulas para procurar o texto de pesquisa especificado. Os campos de destino têm de estar listados na definição Suggesters no índice.
suggesterName	string	Obrigatório. O nome do sugeridor, conforme especificado na coleção Suggesters que faz parte da definição do índice. Um sugeridor determina que campos são analisados para termos de consulta sugeridos.
$top	número inteiro	Opcional. A predefinição é 5. O número de sugestões de conclusão automática a obter. O valor tem de ser um número entre 1 e 100. Quando chamado com POST, este parâmetro tem o nome top em vez de $top.

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

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

{  
  "@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.

Partilhar via