Completamento automatico (API REST di Ricerca intelligenza artificiale di Azure)

L'API completamento automatico completa un input di query parzialmente tipizzato usando i termini esistenti nell'indice di ricerca da usare in una query secondaria. Ad esempio, se l'input della query è "medic", l'API completamento automatico restituisce "medicare", , "medicaid""medicine" se tali termini si trovano nell'indice. Internamente, il motore di ricerca cerca i termini corrispondenti nei campi in cui è configurato un strumento di suggerimento .

Per le richieste del servizio, è necessario usare il protocollo HTTPS. La richiesta di completamento automatico può essere creata usando i metodi GET o 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 viene chiamato con GET, la lunghezza dell'URL della richiesta non può superare 8 KB. Questa lunghezza è in genere sufficiente per la maggior parte delle applicazioni. Tuttavia, alcune applicazioni producono query molto grandi, in particolare quando vengono usate espressioni di filtro OData. Per queste applicazioni, HTTP POST è una scelta migliore perché consente filtri più grandi rispetto a GET.

Con POST il fattore limitante è il numero di clausole in un filtro, non la dimensione della stringa di filtro non elaborata, poiché il limite delle dimensioni della richiesta per POST è di circa 16 MB. Anche se il limite di dimensioni della richiesta POST è molto elevato, le espressioni di filtro non possono essere arbitrariamente complesse. Per altre informazioni sulle limitazioni di complessità dei filtri, vedere Sintassi delle espressioni OData per Ricerca per intelligenza artificiale di Azure.

Parametri dell'URI

Raccomandazioni per la codifica URL

Ricordarsi di codificare i parametri di query specifici della codifica URL quando si chiama direttamente l'API REST GET. Per il completamento automatico, la codifica URL potrebbe essere necessaria per i parametri di query seguenti:

• ricerca
• $filter
• highlightPreTag
• highlightPostTag

La codifica URL è consigliata solo per i singoli parametri. Se inavvertitamente si codifica nell'URL l'intera stringa di query (tutto quanto segue ?), le richieste si interromperanno.

La codifica dell'URL è necessaria solo quando si chiama direttamente l'API REST con GET. Non è necessaria alcuna codifica URL quando si usa POST o quando si usa la libreria client .NET di Ricerca intelligenza artificiale di Azure, che gestisce automaticamente la codifica.

Intestazioni richiesta

La tabella seguente descrive le intestazioni della richiesta obbligatorie e facoltative.

Corpo della richiesta

Per GET: nessuno.

Per 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)  
}  

Parametri di query

Una query accetta diversi parametri nell'URL quando viene chiamato con GET e come proprietà JSON nel corpo della richiesta quando viene chiamato con POST. La sintassi per alcuni parametri è leggermente diversa tra GET e POST. Queste differenze sono indicate come applicabile di seguito.

(1) Limitazioni di fuzzy nel completamento automatico:

In primo luogo, la distanza di modifica è limitata a una sola differenza di caratteri per token a differenza del parametro fuzzy nella ricerca. Limitare la distanza di modifica a un carattere significa che non verranno trovate tutte le corrispondenze candidate, ma il limite è necessario per garantire un livello di prestazioni accettabile.

In secondo luogo, il passaggio fuzzy si verifica dopo l'espansione del token parziale e solo i termini della stessa partizione di indice vengono considerati per le corrispondenze fuzzy. Questo vincolo aumenta le prestazioni dell'API completamento automatico eliminando l'aggregazione delle corrispondenze fuzzy in tutte le partizioni. Questo vincolo diventa meno evidente man mano che vengono aggiunti più termini all'indice, con conseguente distribuzione di termini simile per ogni partizione. Poiché i termini vengono distribuiti in modo uniforme, le corrispondenze fuzzy all'interno di una partizione sono un'approssimazione delle corrispondenze fuzzy nell'intero indice. Tuttavia, i risultati potrebbero essere inferiori se l'indice ha meno termini, ad esempio in un indice di test o prototipo, con conseguente rappresentazione non uniforme tra le partizioni. Per altre informazioni sulla suddivisione degli indici in partizioni, vedere combinazioni di partizioni e repliche.

Risposta

Codice di stato: "200 OK" viene restituito per una risposta corretta.

Il payload della risposta ha due proprietà.

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

Esempio

Esempio 1: Recuperare tre suggerimenti di completamento automatico in cui l'input di ricerca parziale è 'washington medic' in modalità predefinita (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"  
}  

Risposta:

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

Esempio 2: Recuperare tre suggerimenti di completamento automatico in cui l'input di ricerca parziale è '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"  
}  

Risposta:

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

Si noti che suggesterName è obbligatorio in un'operazione di completamento automatico.

Vedi anche

• Aggiungere suggerimenti a un indice
• Aggiungere suggerimenti o completamento automatico a un'applicazione
• Codici di stato HTTP