Sintassi delle query Lucene in Ricerca di intelligenza artificiale di Azure

  • Articolo

Quando si creano query in Ricerca di intelligenza artificiale di Azure, è possibile scegliere la sintassi completa del parser di query Lucene per moduli di query specializzati: caratteri jolly, ricerca fuzzy, ricerca di prossimità, espressioni regolari. Gran parte della sintassi del parser di query Lucene viene implementata intatta in Ricerca di intelligenza artificiale di Azure, ad eccezione di *ricerche di intervalli, che vengono costruite tramite $filter espressioni.

Per usare la sintassi Lucene completa, impostare queryType su full e passare un'espressione di query basata su caratteri jolly, ricerca fuzzy o una delle altre forme di query supportate dalla sintassi completa. In REST le espressioni di query vengono fornite nel search parametro di una richiesta di ricerca di documenti (API REST).

Esempio (sintassi completa)

L'esempio seguente è una richiesta di ricerca costruita usando la sintassi completa. Questo particolare esempio mostra la ricerca in campo e il boosting dei termini. Cerca gli hotel in cui il campo categoria contiene il termine budget. Tutti i documenti contenenti la frase "recently renovated" vengono classificati più in alto in seguito al termine valore boost (3).

POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
  "queryType": "full",
  "search": "category:budget AND \"recently renovated\"^3",
  "searchMode": "all"
}

Anche se non è specifico di alcun tipo di query, il searchMode parametro è rilevante in questo esempio. Ogni volta che gli operatori si trovano nella query, è consigliabile impostare searchMode=all in genere per assicurarsi che tutti i criteri siano corrispondenti.

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

Nozioni fondamentali sulla sintassi

Le nozioni fondamentali seguenti sulla sintassi si applicano a tutte le query che usano la sintassi Lucene.

Valutazione degli operatori nel contesto

Il posizionamento determina se un simbolo viene interpretato come operatore o semplicemente come un altro carattere in una stringa.

Ad esempio, nella sintassi completa lucene, la tilde (~) viene usata sia per la ricerca fuzzy che per la ricerca di prossimità. Se posizionato dopo una frase tra virgolette, ~ richiama la ricerca di prossimità. Quando viene posizionato alla fine di un termine, ~ richiama la ricerca fuzzy.

All'interno di un termine, ad esempio business~analyst, il carattere non viene valutato come operatore. In questo caso, supponendo che la query sia un termine o una query di frase, la ricerca full-text con l'analisi lessicale rimuove il ~ termine e interrompe il termine business~analyst in due: business OR analyst.

L'esempio precedente è la tilde (~), ma lo stesso principio si applica a ogni operatore.

Escape dei caratteri speciali

Per usare uno degli operatori di ricerca come parte del testo di ricerca, eseguire l'escape del carattere anteponendolo a una singola barra rovesciata (\). Ad esempio, per una ricerca con caratteri jolly in https://, dove :// fa parte della stringa di query, è necessario specificare search=https\:\/\/*. Analogamente, un modello di numero di telefono preceduto da escape potrebbe essere simile al seguente \+1 \(800\) 642\-7676.

I caratteri speciali che richiedono l'escape includono quanto segue:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Nota

Anche se l'escape mantiene insieme i token, l'analisi lessicale durante l'indicizzazione può rimuoverli. Ad esempio, l'analizzatore Lucene standard interromperà le parole su trattini, spazi vuoti e altri caratteri. Se sono necessari caratteri speciali 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 come delimitano i parametri e specificano i valori in Ricerca di intelligenza artificiale di Azure. Per altri dettagli, vedere RFC1738: Url (Uniform Resource Locators).

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

Operatori booleani

È possibile incorporare operatori booleani in una stringa di query per migliorare la precisione di una corrispondenza. La sintassi completa supporta operatori di testo oltre agli operatori di caratteri. Specificare sempre gli operatori booleani di testo (AND, OR, NOT) in lettere tutte maiuscole.

Operatore di testo Carattere Esempio Utilizzo
E + wifi AND luxury Specifica i termini che una corrispondenza deve contenere. Nell'esempio il motore di query cerca i documenti contenenti sia wifi che luxury. Il carattere più (+) può anche essere usato direttamente davanti a un termine per renderlo obbligatorio. Ad esempio, +wifi +luxury stabilisce che entrambi i termini devono essere presenti nel campo di un singolo documento.
OPPURE (nessuno) 1 wifi OR luxury Trova una corrispondenza quando viene trovato uno dei due termini. Nell'esempio il motore di query restituisce la corrispondenza nei documenti contenenti wifi o luxury entrambi. Poiché OR è l'operatore di congiunzione predefinito, è anche possibile escluderlo, in modo che wifi luxury sia l'equivalente di wifi OR luxury.
NOT !, - wifi –luxury Restituisce una corrispondenza nei documenti che escludono il termine. Ad esempio, wifi –luxury cerca i documenti con il wifi termine ma non luxury.

1 Il | carattere non è supportato per le operazioni OR.

Operatore NOT Boolean

Importante

L'operatore NOT (NOT, !o ) -si comporta in modo diverso nella sintassi completa rispetto alla sintassi semplice.

  • Nella sintassi semplice, le query con negazione hanno sempre un carattere jolly aggiunto automaticamente. Ad esempio, la query -luxury viene espansa automaticamente in -luxury *.
  • Nella sintassi completa, le query con negazione non possono essere combinate con un carattere jolly. Ad esempio, le query non sono consentite -luxury * .
  • Nella sintassi completa, le query con una singola negazione non sono consentite. Ad esempio, la query -luxury non è consentita.
  • Nella sintassi completa, le negazioni si comportano come se fossero sempre ANDed nella query indipendentemente dalla modalità di ricerca.
    • Ad esempio, la query wifi -luxury di sintassi completa nella sintassi completa recupera solo i documenti che contengono il termine wifie quindi applica la negazione -luxury a tali documenti.
  • Se si desidera usare le negazioni per eseguire ricerche in tutti i documenti nell'indice, è consigliabile usare una sintassi semplice con la any modalità di ricerca.
  • Se si desidera utilizzare le negazioni per eseguire ricerche in un subset di documenti nell'indice, è consigliabile usare la sintassi completa o la sintassi semplice con tutte le modalità di ricerca.
Tipo di query Modalità di ricerca Query di esempio Comportamento
Semplice qualsiasi wifi -luxury Restituisce tutti i documenti nell'indice. I documenti con il termine "wifi" o i documenti che mancano il termine "lusso" sono classificati in alto rispetto ad altri documenti. La query viene espansa in wifi OR -luxury OR *.
Semplice tutto wifi -luxury Restituisce solo i documenti nell'indice che contengono il termine "wifi" e non contengono il termine "luxury". La query viene espansa in wifi AND -luxury AND *.
Completa qualsiasi wifi -luxury Restituisce solo i documenti nell'indice che contengono il termine "wifi", quindi i documenti che contengono il termine "lusso" vengono rimossi dai risultati.
Completa tutto wifi -luxury Restituisce solo i documenti nell'indice che contengono il termine "wifi", quindi i documenti che contengono il termine "lusso" vengono rimossi dai risultati.

Ricerca campiata

È possibile definire un'operazione di ricerca con campi con la fieldName:searchExpression sintassi, in cui l'espressione di ricerca può essere una singola parola o una frase o un'espressione più complessa tra parentesi, facoltativamente con operatori booleani. Ecco alcuni esempi:

  • genre:jazz NOT history

  • artists:("Miles Davis" "John Coltrane")

Assicurarsi di inserire più stringhe racchiuse tra virgolette se si vuole che entrambe le stringhe siano valutate come una singola entità, in questo caso per la ricerca di due artisti distinti nel campo artists.

Il campo specificato in fieldName:searchExpression deve essere un campo searchable. Per informazioni dettagliate sull'uso di attributi dell'indice nelle definizioni campo, vedere Create Index (Creare l'indice).

Nota

Quando si usano espressioni di ricerca con campi, non è necessario usare il searchFields parametro perché ogni espressione di ricerca campiata ha un nome di campo specificato in modo esplicito. Tuttavia, è comunque possibile usare il searchFields parametro se si vuole eseguire una query in cui alcune parti hanno come ambito un campo specifico e il resto può essere applicato a diversi campi. Ad esempio, la query search=genre:jazz NOT history&searchFields=description corrisponde jazz solo al genre campo , mentre corrisponde NOT history al description campo . Il nome del campo specificato in fieldName:searchExpression ha sempre la precedenza sul searchFields parametro , motivo per cui in questo esempio non è necessario includere genre nel searchFields parametro .

Ricerca fuzzy

Una ricerca fuzzy trova corrispondenze in termini con una costruzione simile, espandendo un termine fino al massimo di 50 termini che soddisfano i criteri di distanza di due o meno. Per altre informazioni, vedere Ricerca fuzzy.

Per eseguire una ricerca fuzzy, usare il simbolo tilde ~ alla fine di una singola parola con un parametro facoltativo, un numero compreso tra 0 e 2 (impostazione predefinita), che specifica la distanza di modifica. Ad esempio, blue~ o blue~1 restituirebbe blue, bluese glue.

La ricerca fuzzy può essere applicata solo ai termini, non alle frasi racchiuse tra virgolette, ma è possibile accodare la tilde a ogni termine singolarmente in un nome o frase in più parti. Ad esempio, Unviersty~ of~ Wshington~ corrisponderebbe a .University of Washington

Ricerca per prossimità

Le ricerche per prossimità vengono usate per trovare termini che si trovano vicini in un documento. Inserire un simbolo tilde ~ alla fine di una frase seguita dal numero di parole che creano il limite di prossimità. Ad esempio, "hotel airport"~5 trova i termini hotel e airport entro cinque parole l'uno dall'altro in un documento.

Ottimizzazione dei termini

Il termine boosting si riferisce alla classificazione di un documento più alto se contiene il termine con boosting, relativo ai documenti che non contengono il termine . Questo comportamento è diverso dall'assegnazione di punteggi ai profili, perché questo metodo assegna priorità ad alcuni campi, invece che a termini specifici.

L'esempio seguente illustra le differenze. Si supponga che esista un profilo di punteggio che migliora le corrispondenze in un determinato campo, ad esempio genre (genere) nell'esempio musicstoreindex. L'aumento di priorità di un termine si usa per assegnare a determinati termini di ricerca una priorità maggiore rispetto ad altri. Ad esempio, rock^2 electronic aumenta i documenti che contengono i termini di ricerca nel campo genere più alto rispetto ad altri campi ricercabili nell'indice. Inoltre, i documenti che contengono il termine di ricerca rock vengono classificati in alto rispetto all'altro termine di ricerca elettronica in seguito al termine boost value (2).

Per incrementare un termine, usare il cursore, ^, il simbolo con un fattore di boost (un numero) alla fine del termine che si sta cercando. È anche possibile aumentare la priorità delle frasi. Maggiore è il fattore di incremento, più rilevante è il termine rispetto ad altri termini di ricerca. Per impostazione predefinita, il fattore di aumento è pari a 1. Anche se il fattore di aumento di priorità deve essere positivo, può essere minore di 1 (ad esempio 0,20).

Ricerca di espressioni regolari

Una ricerca di espressioni regolari trova una corrispondenza in base ai modelli validi in Apache Lucene, come documentato nella classe RegExp. In Ricerca di intelligenza artificiale di Azure un'espressione regolare è racchiusa tra le barre /.

Ad esempio, per trovare documenti contenenti motel o hotel, specificare /[mh]otel/. Le ricerche basate su espressioni regolari vengono confrontate con parole singole.

Alcuni strumenti e linguaggi impongono requisiti aggiuntivi per i caratteri di escape oltre le regole di escape imposte da Ricerca di intelligenza artificiale di Azure. Per JSON, le stringhe che includono una barra vengono precedute da un carattere di escape con una barra all'indietro: microsoft.com/azure/ diventa search=/.*microsoft.com\/azure\/.*/ la posizione in cui search=/.* <string-placeholder>.*/ viene impostata l'espressione regolare ed microsoft.com\/azure\/ è la stringa con una barra di escape.

Due simboli comuni nelle query regex sono . e *. Un . oggetto corrisponde a qualsiasi carattere e corrisponde * al carattere precedente zero o più volte. Ad esempio, /be./ corrisponde ai termini bee e bet mentre /be*/ corrisponde bea , beee beee ma non beta . Insieme, .* è possibile associare qualsiasi serie di caratteri in modo /be.*/ che corrisponda a qualsiasi termine che inizia con be , ad esempio better.

Se si verificano errori di sintassi nell'espressione regolare, esaminare le regole di escape per i caratteri speciali. È anche possibile provare un client diverso per verificare se il problema è specifico dello strumento.

Ricerca con caratteri jolly

È possibile usare la sintassi generalmente riconosciuta per le ricerche con caratteri jolly multipli (*) o singoli (?). La sintassi Lucene completa supporta la corrispondenza di prefisso, prefisso e suffisso.

Si noti che il parser di query Lucene supporta l'utilizzo di questi simboli con un singolo termine, non una frase.

Tipo di affissi Descrizione ed esempi
prefix Il frammento di termine precede * o ?. Ad esempio, un'espressione di query di search=alpha* restituisce alphanumeric o alphabetical. La corrispondenza dei prefissi è supportata sia nella sintassi semplice che nella sintassi completa.
suffix Il frammento di termini viene dopo * o ?, con una barra per delimitare il costrutto. Ad esempio search=/.*numeric/ restituisce alphanumeric.
infisso I frammenti di termini racchiudono * o ?. Ad esempio, restituisce search=non*alnon-numerical e nonsensical.

È possibile combinare gli operatori in un'unica espressione. Ad esempio, 980?2* corrisponde a in 98072-1222 e 98052-1234, dove ? corrisponde a un singolo carattere (obbligatorio) e * corrisponde ai caratteri di una lunghezza arbitraria che segue.

La corrispondenza del suffisso richiede i delimitatori barra dell'espressione / regolare. In genere, non è possibile usare un * simbolo o ? come primo carattere di un termine, senza ./ È anche importante notare che il comportamento di * si comporta in modo diverso quando viene usato all'esterno delle query regex. All'esterno del delimitatore barra / regex, * è un carattere jolly e corrisponde a qualsiasi serie di caratteri come .* nell'espressione regolare. Ad esempio, search=/non.*al/ produce lo stesso set di risultati di search=non*al.

Nota

Come regola, la corrispondenza dei criteri è lenta, quindi è consigliabile esplorare metodi alternativi, ad esempio la tokenizzazione n-gram di arco che crea token per sequenze di caratteri in un termine. Con la tokenizzazione n-gram, l'indice sarà più grande, ma le query potrebbero essere eseguite più velocemente, a seconda della costruzione del modello e della lunghezza delle stringhe indicizzate. Per altre informazioni, vedere Ricerca e modelli di termini parziali con caratteri speciali.

Effetto di un analizzatore sulle query con caratteri jolly

Durante l'analisi delle query, le query formulate come prefisso, suffisso, carattere jolly o espressioni regolari vengono passate così com'è all'albero delle query, ignorando l'analisi lessicale. Le corrispondenze verranno trovate solo se l'indice contiene le stringhe nel formato specificato dalla query. Nella maggior parte dei casi, è necessario un analizzatore durante l'indicizzazione che mantiene l'integrità delle stringhe in modo che i criteri e i termini parziali abbiano esito positivo. Per altre informazioni, vedere Ricerca parziale dei termini nelle query di Ricerca di intelligenza artificiale di Azure.

Si consideri una situazione in cui è possibile che la query terminal* di ricerca restituisca risultati contenenti termini come terminate, terminatione terminates.

Se si usasse l'analizzatore en.lucene (inglese Lucene), si applicherebbe lo stemming aggressivo di ogni termine. Ad esempio, terminate, termination, terminates verrà tutti tokenizzati fino al token termi nell'indice. D'altra parte, i termini nelle query che usano caratteri jolly o la ricerca fuzzy non vengono analizzati affatto, quindi non ci sarebbero risultati che corrisponderebbero alla terminat* query.

D'altra parte, gli analizzatori Microsoft (in questo caso, l'analizzatore en.microsoft) sono un po 'più avanzati e usano lemmatizzazione invece di stemming. Ciò significa che tutti i token generati devono essere parole in inglese valide. Ad esempio, terminate, terminatese termination rimarranno per lo più interi nell'indice e sarebbe preferibile per gli scenari che dipendono molto dai caratteri jolly e dalla ricerca fuzzy.

Assegnazione di punteggi a query con caratteri jolly ed espressioni regolari

Ricerca di intelligenza artificiale di Azure usa il punteggio basato sulla frequenza (BM25) per le query di testo. Per le query con caratteri jolly e regex, in cui l'ambito dei termini può essere potenzialmente ampio, il fattore frequenza viene tuttavia ignorato per evitare che la classificazione privilegi le corrispondenze con termini più rari. Tutte le corrispondenze vengono trattate equamente per le ricerche con caratteri jolly e regex.

Caratteri speciali

In alcune circostanze, potresti voler cercare un carattere speciale, ad esempio un'emoji '❤' o il segno '€'. In questi casi, assicurarsi che l'analizzatore usato non filtri tali caratteri. L'analizzatore standard ignora molti caratteri speciali, esclusi dall'indice.

Gli analizzatori che tokenzzano caratteri speciali includono l'analizzatore di spazi vuoti, che prende in considerazione qualsiasi sequenza di caratteri separati da spazi vuoti come token (quindi la ❤ stringa verrebbe considerata un token). Inoltre, un analizzatore del linguaggio come Microsoft English Analyzer ("en.microsoft"), accetta la stringa "€" come token. È possibile testare un analizzatore per vedere quali token genera per una determinata query.

Quando si usano caratteri Unicode, assicurarsi che i simboli siano preceduti correttamente da un carattere di escape nell'URL della query ( ad esempio per ❤ usare la sequenza di %E2%9D%A4+escape ). Alcuni client REST 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) cerca i documenti contenenti il motel termine e wifi o luxury (o entrambi).

Il raggruppamento di campi è simile, ma definisce un singolo campo come ambito del raggruppamento. Ad esempio, hotelAmenities:(gym+(wifi|pool)) cerca nel campo hotelAmenities e gymwifi, o gym e pool.

Limiti delle dimensioni delle query

Ricerca di intelligenza artificiale di Azure impone limiti alle dimensioni e alla composizione delle query perché le query non associate possono destabilizzare il servizio di ricerca. Esistono limiti per le dimensioni e la composizione delle query (il numero di clausole). Esistono anche limiti per la lunghezza della ricerca del prefisso e per la complessità della ricerca regex e della ricerca con caratteri jolly. Se l'applicazione genera query di ricerca a livello di codice, è consigliabile progettarla in modo che non generi query di dimensioni non associate.

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

Vedi anche