Suggerimenti (API REST di Ricerca intelligenza artificiale di Azure)

  • Articolo

Una richiesta di suggerimenti è una query di ricerca come tipo che cerca i valori corrispondenti nei campi in grado di suggerire e restituisce documenti che contengono una corrispondenza. Ad esempio, se si abilitano i suggerimenti in un campo città , digitando "sea" vengono generati documenti contenenti "Seattle", "Sea Tac" e "Sea" (tutti i nomi di città effettivi) per tale campo.

La risposta è un contenuto di un documento corrispondente più la chiave del documento. A differenza del completamento automatico, che restituisce un termine o una frase completata utilizzata in una query secondaria, questa richiesta restituisce informazioni che vengono risolte in documenti effettivi. Se i termini o le frasi corrispondenti sono identici tra documenti, il contenuto corrispondente viene ripetuto. Per migliorare la struttura dei risultati, è consigliabile usare il $select filtro per restituire campi aggiuntivi che forniscono più differenziazione e contesto.

Per le richieste del servizio, è necessario usare il protocollo HTTPS. La richiesta Suggest può essere costruita usando i metodi GET o POST.

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

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

A differenza di una richiesta di ricerca documenti , è possibile associare una chiamata Suggerimenti all'input da tastiera, mentre una chiamata di ricerca potrebbe essere associata a un evento Click.

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 della dimensione della richiesta POST è molto grande, 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. La versione stabile corrente è api-version=2020-06-30. Per altre versioni, 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 le operazioni Suggestions sono inclusi i parametri 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 chiama Suggestions usando POST o quando si usa la libreria client .NET di Ricerca intelligenza artificiale di Azure gestisce automaticamente la codifica url.

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. Una chiave API è una stringa univoca generata dal sistema che autentica la richiesta al servizio di ricerca. Le richieste di query sulla raccolta di documenti possono specificare una chiave amministratore o una chiave di query come chiave API. La chiave di query viene usata per le operazioni di sola lettura sulla raccolta documenti. Per informazioni dettagliate, vedere Connettersi a Ricerca intelligenza artificiale di Azure usando l'autenticazione della chiave .

Corpo della richiesta

Per GET: nessuno.

Per POST:

{  
      "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),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "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 Versioni api. Per questa operazione, la versione api viene specificata come parametro di query nell'URL indipendentemente dal fatto che si chiami l'API con GET o POST.
$filter string Facoltativa. Espressione che filtra i documenti considerati per i suggerimenti. In un filtro è possibile usare solo campi filtrabili. Le espressioni di filtro "search.ismatch" e "search.ismatchscoring*" non sono supportate nell'API Completamento automatico. 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. La distanza di modifica è 1 per stringa di query. Se la stringa di query è composta da più termini, può essere presente un solo carattere mancante, aggiuntivo, sostituito o trasposto nell'intera stringa. L'abilitazione della corrispondenza fuzzy può essere un'esperienza migliore in alcuni scenari, a un costo delle prestazioni, poiché le ricerche di suggerimenti fuzzy sono più lente e utilizzano 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é #.
$orderby string Facoltativa. Elenco di espressioni delimitate da virgole in base alle quali ordinare i risultati. Ogni espressione può essere un nome campo o una chiamata alla funzione geo.distance() . Ogni espressione può essere seguita da "asc" (crescente) o "desc" (decrescente). Per impostazione predefinita, l'ordinamento è crescente. Esiste un limite di 32 clausole per $orderby. Quando viene chiamato con POST, questo parametro viene denominato order anziché $orderby.
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 oppure i suggerimenti restituiscono il codice di stato HTTP 503. Se i suggerimenti hanno 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 della ricerca da usare per i suggerimenti per le query. 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.
$select string Facoltativa. Elenco di campi delimitati da virgole da recuperare. Se non specificato, vengono restituiti solo la chiave del documento e il testo del suggerimento. È possibile richiedere in modo esplicito tutti i campi impostando questo parametro su *. Quando si chiama con POST, questo parametro viene denominato select anziché $select.
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 si chiama con POST, questo parametro viene denominato top anziché $top.

Risposta

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

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

Se per recuperare i campi viene usata l'opzione di proiezione, tali campi vengono inclusi in ogni elemento della matrice:

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}

Esempio

Recuperare 5 suggerimenti per cui l'input di ricerca parziale è "lux":

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30 

POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }

Si noti che suggesterName è obbligatorio in un'operazione Suggestions.

Vedi anche