Sintassi di query semplice in Ricerca di intelligenza artificiale di Azure

  • Articolo

Per gli scenari di ricerca full-text, Ricerca di intelligenza artificiale di Azure implementa due linguaggi di query basati su Lucene, ognuno allineato a un parser di query. Il parser di query semplice è l'impostazione predefinita. Illustra i casi d'uso comuni e tenta di interpretare una richiesta anche se non è perfettamente composta. L'altro parser è Lucene Query Parser e supporta costruzioni di query più avanzate.

Questo articolo è il riferimento alla sintassi di query per il parser di query semplice.

La sintassi delle query per entrambi i parser si applica alle espressioni di query passate nel search parametro di una richiesta di query, non da confondere con la sintassi OData, con la sintassi e le regole filter per e orderby le espressioni nella stessa richiesta.

Anche se il parser semplice è basato sulla classe Parser di query semplici Apache Lucene, la sua implementazione in Ricerca di intelligenza artificiale di Azure esclude la ricerca fuzzy. Se è necessaria una ricerca fuzzy, prendere in considerazione la sintassi di query Lucene completa alternativa.

Esempio (sintassi semplice)

In questo esempio viene illustrata una query semplice, distinta per "queryType": "simple" e sintassi valida. Anche se il tipo di query è impostato di seguito, è l'impostazione predefinita e può essere omesso a meno che non si stia ripristinando da un tipo alternativo. L'esempio seguente è una ricerca su termini indipendenti, con un requisito che tutti i documenti corrispondenti includano "pool".

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2020-06-30
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

Il parametro searchMode è rilevante in questo esempio. Ogni volta che gli operatori booleani si trovano nella query, è consigliabile impostare searchMode=all in genere per assicurarsi che tutti i criteri siano corrispondenti. In caso contrario, è possibile usare il valore predefinito searchMode=any che favorisce il richiamo rispetto alla precisione.

Per altri esempi, vedere Esempi di sintassi di query semplici. Per informazioni dettagliate sulla richiesta di query e sui parametri, vedere Cercare documenti (API REST).

Ricerca di parole chiave in termini e frasi

Le stringhe passate al search parametro possono includere termini o frasi in qualsiasi linguaggio supportato, operatori booleani, operatori di precedenza, caratteri jolly o caratteri di prefisso per query "inizia con", caratteri di escape e caratteri di codifica URL. search è facoltativo. Non specificato, la ricerca (search=* o search=" ") restituisce i primi 50 documenti in ordine arbitrario (non classificato).

  • Una ricerca di termini è una query di uno o più termini, in cui uno dei termini viene considerato una corrispondenza.

  • Una ricerca di frasi è una frase esatta racchiusa tra virgolette " ". Ad esempio, mentre Roach Motel (senza virgolette) cercherebbe documenti contenenti Roach e/o Motel ovunque in qualsiasi ordine, "Roach Motel" (con virgolette) corrisponderà solo ai documenti che contengono l'intera frase insieme e in tale ordine (l'analisi lessicale è ancora applicabile).

A seconda del client di ricerca, potrebbe essere necessario eseguire l'escape delle virgolette in una ricerca di frasi. In una richiesta POST, ad esempio, una ricerca "Roach Motel" di frasi nel corpo della richiesta potrebbe essere specificata come "\"Roach Motel\"". Se si usano gli SDK di Azure, il client di ricerca esegue l'escape delle virgolette quando serializza il testo di ricerca. La frase di ricerca può essere inviata come "Roach Motel".

Per impostazione predefinita, tutte le stringhe passate nel search parametro vengono sottoposte a analisi lessicali. Assicurarsi di comprendere il comportamento di tokenizzazione dell'analizzatore in uso. Spesso, quando i risultati delle query sono imprevisti, è possibile tracciare il motivo per cui i termini vengono tokenizzati in fase di query. È possibile testare la tokenizzazione in stringhe specifiche per confermare l'output.

Qualsiasi input di testo con uno o più termini è considerato un punto di partenza valido per l'esecuzione di query. Ricerca di intelligenza artificiale di Azure corrisponderà ai documenti contenenti uno o tutti i termini, incluse eventuali variazioni rilevate durante l'analisi del testo.

Come sembra semplice, c'è un aspetto dell'esecuzione di query in Ricerca di intelligenza artificiale di Azure che potrebbe produrre risultati imprevisti, aumentando invece di diminuire i risultati della ricerca man mano che vengono aggiunti più termini e operatori alla stringa di input. L'effettiva esecuzione di questa espansione dipende dall'inclusione di un operatore NOT, combinata con un'impostazione searchMode di parametro che determina come NOT viene interpretato in termini di AND comportamenti o OR . Per altre informazioni, vedere l'operatore NOT in Operatori booleani.

Operatori booleani

È possibile incorporare operatori booleani in una stringa di query per migliorare la precisione di una corrispondenza. Nella sintassi semplice gli operatori booleani sono basati su caratteri. Gli operatori di testo, ad esempio la parola AND, non sono supportati.

Carattere Esempio Utilizzo
+ pool + ocean Operazione AND . Ad esempio, pool + ocean stabilisce che un documento deve contenere entrambi i termini.
| pool | ocean Un'operazione OR trova una corrispondenza quando viene trovato uno dei due termini. Nell'esempio il motore di query restituirà una corrispondenza nei documenti contenenti pool o ocean entrambi. Poiché OR è l'operatore di congiunzione predefinito, è anche possibile estrarlo, in modo che pool ocean sia l'equivalente di pool | ocean.
- pool – ocean Un'operazione NOT restituisce corrispondenze nei documenti che escludono il termine.

Il searchMode parametro in una richiesta di query controlla se un termine con l'operatore NOT è ANDed o ORed con altri termini nella query (presupponendo che non siano presenti operatori booleani negli altri termini). I valori validi sono any o all.

searchMode=any aumenta il richiamo delle query includendo più risultati e per impostazione predefinita - verrà interpretato come "OR NOT". Ad esempio, pool - ocean corrisponderà ai documenti che contengono il termine o quelli che non contengono il termine poolocean.

searchMode=all aumenta la precisione delle query includendo un minor numero di risultati e per impostazione predefinita - verrà interpretato come "AND NOT". Ad esempio, con searchMode=any, la query pool - ocean corrisponderà ai documenti che contengono il termine "pool" e tutti i documenti che non contengono il termine "oceano". Si tratta di un comportamento verosimilmente più intuitivo per l'operatore -. Pertanto, è consigliabile usare searchMode=all invece di searchMode=any se si desidera ottimizzare le ricerche di precisione anziché richiamo e gli utenti usano spesso l'operatore - nelle ricerche.

Quando si decide un'impostazione searchMode , prendere in considerazione i modelli di interazione utente per le query in varie applicazioni. È più probabile che gli utenti che cercano informazioni includano un operatore in una query, anziché siti di e-commerce con strutture di navigazione predefinite.

Query di prefisso

Per le query "inizia con", aggiungere un operatore suffisso (*) come segnaposto per il resto di un termine. Una query di prefisso deve iniziare con almeno un carattere alfanumerico prima di poter aggiungere l'operatore di suffisso.

Carattere Esempio Utilizzo
* lingui* corrisponderà a "linguistico" o "linguini" L'asterisco (*) rappresenta uno o più caratteri di lunghezza arbitraria, ignorando la distinzione tra maiuscole e minuscole.

Analogamente ai filtri, una query di prefisso cerca una corrispondenza esatta. Di conseguenza, non esiste alcun punteggio di pertinenza (tutti i risultati ricevono un punteggio di ricerca pari a 1,0). Tenere presente che le query di prefisso possono essere lente, soprattutto se l'indice è grande e il prefisso è costituito da un numero ridotto di caratteri. Una metodologia alternativa, ad esempio la tokenizzazione edge n-gram, potrebbe essere più veloce. I termini che usano la ricerca con prefisso non possono superare i 1000 caratteri.

La sintassi semplice supporta solo la corrispondenza dei prefissi. Per la corrispondenza del suffisso o del prefisso rispetto alla fine o alla metà di un termine, usare la sintassi Lucene completa per la ricerca con caratteri jolly.

Escape degli operatori di ricerca

Nella sintassi semplice gli operatori di ricerca includono questi caratteri: + | " ( ) ' \

Se uno di questi caratteri fa parte di un token nell'indice, eseguirne l'escape anteponendolo a una singola barra rovesciata (\) nella query. Si supponga, ad esempio, di aver usato un analizzatore personalizzato per la tokenizzazione di termini interi e che l'indice contenga la stringa "Luxury+Hotel". Per ottenere una corrispondenza esatta su questo token, inserire un carattere di escape: search=luxury\+hotel.

Per semplificare i casi più tipici, esistono due eccezioni a questa regola in cui l'escape non è necessario:

  • L'operatore - NOT deve essere preceduto da un carattere di escape solo se è il primo carattere dopo uno spazio vuoto. Se l'oggetto - viene visualizzato al centro (ad esempio, in 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), è possibile ignorare l'escape.

  • L'operatore * suffisso deve essere preceduto da un carattere di escape solo se è l'ultimo carattere prima di uno spazio vuoto. Se l'oggetto * viene visualizzato al centro (ad esempio, in 4*4=16), non è necessario eseguire alcuna escape.

Nota

Per impostazione predefinita, l'analizzatore standard eliminerà e interromperà le parole su trattini, spazi vuoti, e commerciale e altri caratteri durante l'analisi lessicale. Se sono necessari caratteri speciali per rimanere nella stringa di query, potrebbe essere necessario un analizzatore che li conserva nell'indice. Alcune scelte includono analizzatori del linguaggio naturale Microsoft, che conserva le parole sillabate o un analizzatore personalizzato per modelli più complessi. Per altre informazioni, vedere Termini, modelli e caratteri speciali parziali.

Codifica dei caratteri riservati e non sicuri negli URL

Verificare che tutti i caratteri non sicuri e riservati siano codificati in un URL. Ad esempio, '#' è un carattere non sicuro perché è un identificatore di frammento/ancoraggio in un URL. Il carattere deve essere codificato al %23, se usato in un URL. '&' e '=' sono esempi di caratteri riservati mentre delimitano i parametri e specificano i valori in Ricerca di intelligenza artificiale di Azure. Per altre informazioni, vedere RFC1738: Url (Uniform Resource Locators).

I caratteri non sicuri sono " ` < > # % { } | \ ^ ~ [ ]. I caratteri riservati sono ; / ? : @ = + &.

Caratteri speciali

I caratteri speciali possono variare da simboli di valuta come '$' o '€', a emoji. Molti analizzatori, incluso l'analizzatore standard predefinito, escluderanno i caratteri speciali durante l'indicizzazione, il che significa che non verranno rappresentati nell'indice.

Se è necessaria una rappresentazione di caratteri speciale, è possibile assegnare un analizzatore che li mantiene:

  • L'analizzatore di spazi vuoti considera qualsiasi sequenza di caratteri separata da spazi vuoti come token ( quindi l'emoji '❤' verrebbe considerata un token).

  • Un analizzatore del linguaggio, ad esempio Microsoft English Analyzer (en.microsoft), accetta la stringa '$' o '€' come token.

Per confermare, è possibile testare un analizzatore per vedere quali token vengono generati per una determinata stringa. Come si potrebbe prevedere, potrebbe non essere possibile ottenere la tokenizzazione completa da un singolo analizzatore. Una soluzione alternativa consiste nel creare più campi che contengono lo stesso contenuto, ma con assegnazioni di analizzatori diverse , ad esempio , description_endescription_fre così via per gli analizzatori del linguaggio.

Quando si usano caratteri Unicode, assicurarsi che i simboli siano preceduti correttamente da un carattere di escape nell'URL della query ( ad esempio per '❤' userebbe la sequenza di %E2%9D%A4+escape ). Alcuni client Web eseguono automaticamente questa traduzione.

Precedenza (raggruppamento)

È possibile usare le parentesi per creare sottoquery, inclusi gli operatori nell'istruzione tra parentesi. Ad esempio, motel+(wifi|luxury) cercherà i documenti contenenti i termini "motel" e "wifi" o "luxury" (oppure entrambi).

Limiti delle dimensioni delle query

Se l'applicazione genera query di ricerca a livello di codice, è consigliabile progettarla in modo che non generi query di dimensioni non associate.

  • Per GET, la lunghezza dell'URL non può superare 8 KB.

  • Per POST (e qualsiasi altra richiesta), dove il corpo della richiesta include search e altri parametri, ad filter esempio e orderby, la dimensione massima è 16 MB. I limiti aggiuntivi includono:

    • La lunghezza massima della clausola di ricerca è di 100.000 caratteri.
    • Il numero massimo di clausole in search (espressioni separate da AND o OR) è 1024.
    • La dimensione massima del termine di ricerca è di 1000 caratteri per la ricerca del prefisso.
    • Esiste anche un limite di circa 32 KB per le dimensioni di qualsiasi singolo termine in una query.

Per altre informazioni sui limiti delle query, vedere Limiti delle richieste API.

Passaggi successivi

Se si creeranno query a livello di codice, vedere Ricerca full-text in Ricerca di intelligenza artificiale di Azure per comprendere le fasi dell'elaborazione delle query e le implicazioni dell'analisi del testo.

Per altre informazioni sulla costruzione di query, vedere gli articoli seguenti: