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

Articolo
03/05/2024

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

Parametro	Descrizione
[nome servizio]	Obbligatorio. Impostarlo sul nome univoco definito dall'utente del servizio di ricerca.
[nome indice]/docs	Obbligatorio. Specifica la raccolta documenti di un indice denominato.
api-version	Obbligatorio. Per un elenco delle versioni supportate, vedere Versioni API . Per le query, la versione api viene sempre specificata come parametro URI per GET e POST.

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.

Campi Descrizione

Content-Type Obbligatorio. Impostare il valore su application/json

api-key Facoltativo se si usano i ruoli di Azure e viene fornito un token di connessione nella richiesta, in caso contrario è necessaria una chiave. Le richieste di query sulla docs raccolta possono specificare una chiave amministratore o una chiave di query come api-key. La chiave di query viene usata per le operazioni di sola lettura in una raccolta di documenti di indice. Per informazioni dettagliate, vedere Connettersi a Ricerca intelligenza artificiale di Azure usando l'autenticazione della chiave .

Campi	Descrizione
Content-Type	Obbligatorio. Impostare il valore su `application/json`
api-key	Facoltativo se si usano i ruoli di Azure e viene fornito un token di connessione nella richiesta, in caso contrario è necessaria una chiave. Le richieste di query sulla `docs` raccolta possono specificare una chiave amministratore o una chiave di query come `api-key`. La chiave di query viene usata per le operazioni di sola lettura in una raccolta di documenti di indice. Per informazioni dettagliate, vedere Connettersi a Ricerca intelligenza artificiale di Azure usando l'autenticazione della chiave .

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.

Nome	Tipo	Descrizione
api-version	string	Obbligatorio. Versione dell'API REST usata per la richiesta. Per un elenco delle versioni supportate, vedere Controllo delle versioni delle API. Per questa operazione, la versione API viene specificata come parametro URI indipendentemente dal fatto che si chiami Completamento automatico con GET o POST.
completamento automaticoMode	string	Facoltativa. Il valore predefinito è oneTerm. I valori validi sono oneTerm, twoTerms, oneTermWithContext. oneTerm restituisce un singolo termine. Se la query ha due termini, viene completato solo l'ultimo termine. Ad esempio, dato `"washington medic"`, la risposta potrebbe essere uno di questi singoli termini: `"medicaid"`, `"medicare"`, `"medicine"`. twoTerms corrisponde alle frasi a due termini nell'indice. Ad esempio, dato `"medic"`, la risposta potrebbe essere `"medicare coverage"`o `"medical assistant"`. In molti casi, i singoli termini `"medicare"` o `"medical"` non vengono restituiti perché la preferenza viene assegnata a frasi a due termini corrispondenti. oneTermWithContext completa l'ultimo termine in una query con due o più termini, dove gli ultimi due termini sono una frase presente nell'indice. Ad esempio, dato `"washington medic"`, la risposta potrebbe essere `"washington medicaid"`, `"washington medical"`.
$filter	string	Facoltativa. Espressione di ricerca strutturata nella sintassi OData standard che filtra i documenti considerati per produrre i suggerimenti di termine completati. Le espressioni di filtro "search.ismatch" e "search.ismatchscoring*" non sono supportate nell'API Completamento automatico. In un filtro è possibile usare solo campi filtrabili. Quando viene chiamato con POST, questo parametro viene denominato filter anziché $filter. Per informazioni dettagliate sul subset della grammatica dell'espressione OData supportata da Ricerca per intelligenza artificiale di Azure, vedere Sintassi delle espressioni OData per Ricerca intelligenza artificiale di Azure.
sfocato	boolean	facoltativo. Il valore predefinito è false. Se impostato su true, questa API trova suggerimenti anche se nel testo di ricerca ⁽¹⁾ è presente un carattere sostituito o mancante. Ciò offre un'esperienza migliore in alcuni scenari, ma comporta un costo delle prestazioni perché le ricerche di suggerimenti fuzzy sono più lente e usano più risorse.
highlightPostTag	string	Facoltativa. L'impostazione predefinita è una stringa vuota. Tag stringa che aggiunge al termine evidenziato. Deve essere impostato con highlightPreTag. I caratteri riservati nell'URL devono essere codificati in percentuale (ad esempio, %23 anziché #). Quando viene chiamato usando GET, i caratteri riservati nell'URL devono essere codificati in percentuale ,ad esempio %23 anziché #.
highlightPreTag	string	Facoltativa. L'impostazione predefinita è una stringa vuota. Tag stringa che antepone al termine evidenziato. Deve essere impostato con highlightPostTag. Quando viene chiamato usando GET, i caratteri riservati nell'URL devono essere codificati in percentuale ,ad esempio %23 anziché #.
minimumCoverage	numero intero	facoltativo. Il valore predefinito è 80. Numero compreso tra 0 e 100 che indica la percentuale dell'indice che deve essere disponibile per gestire la query prima che possa essere segnalata come operazione riuscita. L'impostazione predefinita riflette una distorsione verso la velocità e l'efficienza rispetto alla copertura completa. La riduzione della copertura vincola l'espansione delle query, consentendo ai risultati di tornare più velocemente. Consente inoltre alla query di avere esito positivo sulla disponibilità parziale dell'indice, anche se una partizione è lenta a rispondere o non disponibile a causa di problemi di integrità del servizio o di manutenzione dell'indice. Indipendentemente dal valore di minimumCoverage, tale percentuale dell'indice deve essere disponibile o il completamento automatico restituisce il codice di stato HTTP 503. Se il completamento automatico ha esito positivo al livello minimoCoverage, restituisce HTTP 200 e include un @search.coverage valore nella risposta che indica la percentuale dell'indice disponibile durante la manutenzione della query. L'abbassamento di questo valore potrebbe essere utile se si verificano errori 503. In caso contrario, è possibile aumentare il valore se la risposta fornisce corrispondenze insufficienti.
ricerca	string	Obbligatorio. Testo da cercare. Testo di ricerca da completare. Deve essere composto da un minimo di 1 carattere e da un massimo di 100 caratteri. Non può contenere operatori, sintassi di query o frasi tra virgolette.
searchFields	string	Facoltativa. Elenco di nomi di campo delimitati da virgole in cui cercare il testo di ricerca specificato. I campi di destinazione devono essere elencati nella definizione Dei suggerimenti nell'indice.
suggesterName	string	Obbligatorio. Nome del suggerimento specificato nell'insieme Suggesters che fa parte della definizione dell'indice. Un suggerimento determina quali campi vengono analizzati per i termini di query suggeriti.
$top	numero intero	facoltativo. Il valore predefinito è 5. Numero di suggerimenti di completamento automatico da recuperare. Il valore deve essere un numero compreso tra 1 e 100. Quando viene chiamato con POST, questo parametro viene denominato top anziché $top.

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

Proprietà	Descrizione
"text"	Termine o frase completata
"queryPlusText"	Input della query iniziale più il termine o la frase completata

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

Condividi tramite