Aggiungere profili di punteggio per incrementare i punteggi di ricerca
In questo articolo si apprenderà come definire un profilo di punteggio. Un profilo di punteggio è un criterio per aumentare il punteggio di ricerca in base ai parametri specificati. Ad esempio, è possibile che le corrispondenze trovate in un campo "tags" siano più pertinenti rispetto alla stessa corrispondenza trovata in "descrizioni". I criteri possono consistere in un campo ponderato (come nell'esempio di "tag") o una funzione.
I profili di punteggio sono definiti in un indice di ricerca e richiamati su campi non vettoriali nelle richieste di query. È possibile creare più profili e quindi modificare la logica di query per scegliere quella usata.
Nota
Non si ha familiarità con i concetti di pertinenza? Il seguente segmento di video su YouTube passa direttamente al funzionamento dei profili di assegnazione dei punteggi in Azure AI Search. Per altre informazioni, vedere Pertinenza e assegnazione di punteggi in Azure AI Search.
Definizione del profilo di punteggio
Un profilo di punteggio è denominato oggetto definito in uno schema di indice. Un profilo può essere composto da campi, funzioni e parametri ponderati.
La definizione seguente mostra un profilo semplice denominato "geo". In questo esempio viene aumentato il punteggio di pertinenA dei i risultati con il termine di ricerca nel campo hotelName. Usa anche la funzione distance per assegnare una preferenza maggiore ai risultati che si trovano entro 10 chilometri dalla posizione attuale. Se si cerca il termine "inn" e "inn" fa parte del nome di un hotel, i documenti che includono gli hotel con "inn" in un raggio di 10 km dalla posizione corrente verranno visualizzati più in alto nei risultati della ricerca.
"scoringProfiles": [
{
"name":"geo",
"text": {
"weights": {
"hotelName": 5
}
},
"functions": [
{
"type": "distance",
"boost": 5,
"fieldName": "location",
"interpolation": "logarithmic",
"distance": {
"referencePointParameter": "currentLocation",
"boostingDistance": 10
}
}
]
}
]
Per usare questo profilo di punteggio, la query viene formulata in modo da specificare il parametro scoringProfile nella richiesta. Se si usa l'API REST, le query vengono specificate tramite richieste GET e POST. Nell'esempio seguente, "currentLocation" ha un delimitatore di un singolo trattino (-). È seguito da coordinate di longitudine e latitudine, dove la longitudine è un valore negativo.
GET /indexes/hotels/docs?search+inn&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&api-version=2024-07-01
Quando si usa POST, notare le differenze di sintassi. In POST, "scoringParameters" è plurale ed è una matrice.
POST /indexes/hotels/docs&api-version=2024-07-01
{
"search": "inn",
"scoringProfile": "geo",
"scoringParameters": ["currentLocation--122.123,44.77233"]
}
Questa query cerca il termine “inn” e passa la posizione attuale. Si noti che questa query include altri parametri, ad esempio scoringParameter. I parametri di query, incluso "scoringParameter", sono descritti in Cerca documenti (API REST).
Vedere l'Esempio esteso per più dettagli sul profilo di punteggio.
Calcolo dei punteggi
I punteggi vengono calcolati per le query di ricerca a tutto testo. Le corrispondenze vengono segnate in base al livello di pertinenza della corrispondenza e le corrispondenze con livello più alto vengono restituite nella risposta della query. Il punteggio complessivo per ogni documento è un'aggregazione dei singoli punteggi per ogni campo, in cui il punteggio individuale di ogni campo viene calcolato in base alla frequenza dei termini e alla frequenza di documento dei termini ricercati all'interno di tale campo (noto come TF-IDF o frequenza inversa dei termini).
È possibile usare il parametro featuresMode (anteprima) per richiedere dettagli di punteggio aggiuntivi assieme ai risultati della ricerca (inclusi i punteggi a livello di campo).
Quando aggiungere la logica di assegnazione dei punteggi
È consigliabile creare uno o più profili di punteggio quando il comportamento di classificazione predefinito non permette di raggiungere gli obiettivi aziendali stabiliti. È ad esempio possibile che si voglia assegnare una rilevanza di ricerca maggiore agli elementi aggiunti di recente. Analogamente, è possibile che sia presente un campo che include i margini di profitto o un altro campo che indica il potenziale di ricavi. Aumentare la pertinenza dei risultati più significativi per gli utenti o l'azienda è spesso il fattore decisivo nell'adozione dei profili di punteggio.
L'ordinamento basato sulla pertinenza in una pagina di ricerca viene implementato anche tramite profili di punteggio. È consigliabile esaminare le pagine di risultati della ricerca usate in precedenza e che permettevano di ordinare i risultati in base a prezzo, data, classificazione o rilevanza. In Azure AI Search è possibile usare i profili di punteggio per guidare l'opzione "pertinenza". La definizione di pertinenza è definita dall'utente, basata sugli obiettivi aziendali e sul tipo di esperienza di ricerca che si vuole offrire.
Passaggi per l'aggiunta di un profilo di punteggio
Per implementare un comportamento predefinito per l'assegnazione di punteggio, aggiungere un profilo di punteggio allo schema che definisce l'indice. È possibile avere fino a 100 profili di punteggio all'interno di un indice (vedere Limiti dei servizi ), ma è possibile specificare solo un profilo alla volta in ogni query.
Iniziare con una definizione di indice. È possibile aggiungere e aggiornare profili di punteggio in un indice esistente senza doverlo ricompilare. Usare una richiesta Aggiorna indice per pubblicare la revisione.
Incollare il Modello fornito in questo articolo.
Specificare un nome. I profili di punteggio sono facoltativi, ma quando se ne aggiunge uno è necessario specificare un nome. Assicurarsi di seguire la convenzioni di denominazione per i campi di Azure AI Search (iniziare con una lettera, evitare caratteri speciali e parole riservate).
Specificare i criteri di boosting. Un singolo profilo può contenere campi ponderati, funzioni o entrambi.
È consigliabile lavorare in modo iterativo, usando un set di dati che consenta di dimostrare o confutare l'efficacia di un determinato profilo.
I profili di punteggio possono essere definiti nel portale di Azure, come illustrato nello screenshot seguente, oppure a livello di codice tramite API REST o in Azure SDK, come la classe ScoringProfile in Azure SDK per .NET.
Uso di campi ponderati
Usare campi ponderati quando il contesto del campo risulta importante e le query sono di ricerca a tutto campo. Ad esempio, se una query include il termine "aeroporto", si potrebbe desiderare che “aeroporto” nel campo Descrizione abbia più peso rispetto che in HotalName.
I campi ponderati sono costituiti da un campo ricercabile e da un numero positivo utilizzato come moltiplicatore. Se il punteggio del campo originale di HotelName è 3, il punteggio con boosting per tale campo diventa 6, contribuendo a un punteggio complessivo superiore per il documento padre stesso.
"scoringProfiles": [
{
"name": "boostKeywords",
"text": {
"weights": {
"HotelName": 2,
"Description": 5
}
}
}
]
Uso delle funzioni
Usare le funzioni quando i pesi relativi semplici sono insufficienti o non applicabili, come nel caso della distanza e della freschezza, che sono calcoli su dati numerici. È possibile specificare più funzioni per profilo di punteggio. Per altre informazioni sui tipi di dati EDM usati in Azure AI Search, vedere Tipi di dati supportati.
| Funzione | Descrizione |
|---|---|
| "freshness" | Aumenta il livello di pertinenza in base ai valori in un campo datetime (Edm.DateTimeOffset). Questa funzione ha un attributo "boostingDuration" in modo da poter specificare un valore che rappresenta un intervallo di tempo durante il quale si verifica l’aumento della pertinenza. |
| "magnitude" | Aumenta la pertinenza in base al livello (alto o basso) di un valore numerico. Gli scenari che richiedono questa funzione includono l'aumento della priorità in base a margine di profitto, prezzo massimo, prezzo minimo o conteggio di download. Questa funzione può essere usata solo con campi Edm.Double e Edm.Int. Per la funzione “magnitude” è possibile invertire l'intervallo, dal livello più alto al più basso, se si preferisce il modello inverso (ad esempio, per aumentare il livello di priorità degli articoli più economici rispetto a quelli più costosi). Dato un intervallo di prezzi da $100 a $1, impostare "boostingRangeStart" su 100 e "boostingRangeEnd" a 1 per aumentare il livello di priorità di articoli con prezzo inferiore. |
| "distance" | Aumenta la pertinenza in base alla prossimità o alla posizione geografica. Questa funzione può essere usata solo con campi Edm.GeographyPoint . |
| "tag" | Aumenta la pertinenza in base ai tag comuni sia ai documenti di ricerca che alle stringhe di query. I tag vengono forniti in un "tagsParameter". Questa funzione può essere usata solo con i campi di ricerca di tipo Edm.String e Collection(Edm.String). |
Regole per l'uso delle funzioni
- Le funzioni possono essere applicate solo ai campi attribuiti come filtrabili.
- Il tipo di funzione (freshness, magnitude, distance, tag) deve essere scritto in lettere minuscole.
- Le funzioni non possono includere valori Null o vuoti.
Modello
Questa sezione illustra la sintassi e il modello per i profili di punteggio. Per descrizioni degli attributi del profilo di punteggio, fare riferimento a Informazioni di riferimento sulle proprietà.
"scoringProfiles": [
{
"name": "name of scoring profile",
"text": (optional, only applies to searchable fields) {
"weights": {
"searchable_field_name": relative_weight_value (positive #'s),
...
}
},
"functions": (optional) [
{
"type": "magnitude | freshness | distance | tag",
"boost": # (positive number used as multiplier for raw score != 1),
"fieldName": "(...)",
"interpolation": "constant | linear (default) | quadratic | logarithmic",
"magnitude": {
"boostingRangeStart": #,
"boostingRangeEnd": #,
"constantBoostBeyondRange": true | false (default)
}
// ( - or -)
"freshness": {
"boostingDuration": "..." (value representing timespan over which boosting occurs)
}
// ( - or -)
"distance": {
"referencePointParameter": "...", (parameter to be passed in queries to use as reference location)
"boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)
}
// ( - or -)
"tag": {
"tagsParameter": "..."(parameter to be passed in queries to specify a list of tags to compare against target field)
}
}
],
"functionAggregation": (optional, applies only when functions are specified) "sum (default) | average | minimum | maximum | firstMatching"
}
],
"defaultScoringProfile": (optional) "...",
Informazioni di riferimento sulle proprietà
| Attributo | Descrizione |
|---|---|
| name | Obbligatorio. Nome del profilo di punteggio. Segue le stesse convenzioni di denominazione di un campo. Deve iniziare con una lettera, non può contenere punti, punti e virgole o simboli @ e non può iniziare con la frase "azureSearch" (fa distinzione tra maiuscole e minuscole applicata). |
| Testo | Contiene la proprietà Weights. |
| weights | Facoltativo. Coppie nome-valore che specificano un campo ricercabile e un numero intero positivo o a virgola mobile in base al quale incrementare la pertinenza di un campo. Il numero intero positivo o numero diventa un moltiplicatore per il punteggio del campo originale generato dall'algoritmo di classificazione. Ad esempio, se un punteggio di campo è 2 e il valore del peso è 3, il punteggio incrementato per il campo diventa 6. I punteggi dei singoli campi vengono quindi aggregati per creare un punteggio di campo del documento, che viene quindi usato per classificare il documento nel set di risultati. |
| functions | Facoltativo. La funzione di assegnazione del punteggio può essere applicata solo ai campi filtrabili. |
| funzioni > type | Obbligatorio per le funzioni di assegnazione di punteggio. Indica il tipo di funzione da usare. I valori validi includono magnitude, freshness, distance e tag. È possibile includere più funzioni in ogni profilo di punteggio. Il nome della funzione deve essere scritto in lettere minuscole. |
| funzioni > boost | Obbligatorio per le funzioni di assegnazione di punteggio. Numero positivo usato come moltiplicatore per un punteggio non elaborato. Non può essere uguale a 1. |
| funzioni > fieldname | Obbligatorio per le funzioni di assegnazione di punteggio. Una funzione di assegnazione di punteggio può essere applicata solo a campi che fanno parte della raccolta di campi dell'indice e che sono filtrabili. Ogni tipo di funzione introduce inoltre restrizioni aggiuntive (il valore freshness viene usato con campi datetime, il valore magnitude con campi di tipo Integer o Double e il valore distance con campi location). È possibile specificare solo un campo per ogni definizione di funzione. Ad esempio, per usare il valore magnitude due volte nello stesso profilo, sarà necessario includere due definizioni di magnitude, una per ogni campo. |
| funzioni > interpolation | Obbligatorio per le funzioni di assegnazione di punteggio. Definisce il coefficiente angolare in base al quale viene incrementato l'aumento di priorità del punteggio dall'inizio alla fine dell'intervallo. I valori validi includono Linear (predefinito), Constant, Quadratic e Logarithmic. Per informazioni dettagliate, vedere Impostare le interpolazioni . |
| funzioni > magnitude | La funzione di assegnazione di punteggio in base al valore magnitude viene usata per modificare le classificazioni in base all'intervallo di valori per un campo numerico. Di seguito sono riportati alcuni degli esempi di utilizzo più comuni: "Valutazione in stelle": modificare l'assegnazione dei punteggi in base al valore all'interno del campo "Valutazione in stelle". Quando due elementi sono rilevanti, viene visualizzato per primo l'elemento con la classificazione superiore. “Margine”: quando due documenti sono rilevanti, è possibile che un rivenditore voglia aumentare la pertinenza dei documenti che presentano il margine più alto. “Conteggio di clic”: per le applicazioni che tengono traccia dei click a prodotti o pagine, è possibile usare il valore magnitude per aumentare la pertinenza degli elementi che tendono a ottenere il traffico maggiore. “Conteggio di download”: per le applicazioni che tengono traccia dei download, la funzione magnitude permette di aumentare la pertinenza degli elementi più scaricati. |
| funzioni > magnitude > boostingRangeStart | Imposta il valore iniziale dell'intervallo su cui è basato il calcolo della funzione magnitude. Il valore deve essere un numero intero o a virgola mobile. Per le classificazioni a stelle da 1 a 4, corrisponde a 1. Per i margini superiori al 50%, corrisponde a 50. |
| funzioni > magnitude > boostingRangeEnd | Imposta il valore finale dell'intervallo su cui è basato il calcolo della funzione magnitude. Il valore deve essere un numero intero o a virgola mobile. Per le classificazioni a stelle da 1 a 4, corrisponde a 4. |
| funzioni > magnitude > constantBoostBeyondRange | I valori validi sono true o false (predefinito). Se impostato su true, l'aumento completo della priorità continuerà a essere applicato a documenti che includono un valore per il campo di destinazione maggiore rispetto al limite superiore dell'intervallo. Se false, l'aumento di priorità di questa funzione non verrà applicato ai documenti che includono un valore per il campo di destinazione che non rientra nell'intervallo. |
| funzioni > freshness | La funzione freshness per l'assegnazione di punteggio viene usata per modificare i punteggi di classificazione per gli elementi in base ai valori dei campi DateTimeOffset fields. Ad esempio, un elemento con una data più recente può essere classificato con una priorità maggiore rispetto agli elementi meno recenti. È anche possibile classificare gli elementi come eventi di calendario con date future in modo che gli elementi più vicini possano essere classificati in un livello superiore rispetto agli elementi più lontani nel futuro. Nella versione attuale del servizio, un'estremità dell'intervallo sarà fissata all'ora attuale. L'altro è un’orario situato nel passato, basato su boostingDuration. Per aumentare la priorità per un intervallo di tempo nel futuro, usare un valore negativo di boostingDuration. La frequenza della modifica della di priorità tra un intervallo massimo e minimo viene determinata dall'interpolazione applicata al profilo di punteggio (vedere la figura seguente). Per invertire il fattore di aumento di priorità applicato, scegliere un fattore di aumento di priorità inferiore a 1. |
| funzioni > freshness > boostingDuration | Imposta un periodo di scadenza, dopo il quale l'aumento di priorità non verrà più applicato a un determinato documento. Per informazioni sulla sintassi ed esempi, vedere Impostare boostingDuration nella sezione seguente. |
| funzioni > distance | La funzione distance per l'assegnazione di punteggio viene usata per influire sul punteggio di documenti in base alla vicinanza o lontananza rispetto a una posizione geografica di riferimento. La posizione di riferimento viene specificata come parte della query in un parametro (usando il parametro di query ScoringParameter) sotto forma di argomento lon,lat. |
| funzioni > distance > referencePointParameter | Parametro che deve essere passato nelle query per essere usato come posizione di riferimento (usando il paramentro di query scoringParameter). |
| funzioni > distance > boostingDistance | Numero che indica la distanza, in chilometri, dalla posizione di riferimento in cui termina l'intervallo di aumento della priorità. |
| funzioni > tag | La funzione per l'assegnazione di punteggio viene usata per influire sul punteggio di documenti in base ai tag nei documenti e nelle query di ricerca. La priorità di documenti con tag in comune con la query di ricerca verrà aumentata. I tag per la query di ricerca vengono specificati come parametro di assegnazione dei punteggi in ogni richiesta di ricerca (usando il parametro di query scoringParameter). |
| funzioni > tag > tagParameter | Parametro che deve essere passato nelle query per specificare le categorie per una richiesta specifica (usando il parametro di query scoringParameter). Il parametro è costituito da un elenco delimitato da virgole di termini interi. Se un tag specificato all'interno dell'elenco è un elenco delimitato da virgole, è possibile usare un normalizzatore di testo nel campo per rimuovere le virgole in fase di query (eseguire il mapping del carattere virgola a uno spazio). Questo approccio "renderà flat" l'elenco in modo che tutti i termini siano una singola stringa lunga di termini delimitati da virgole. |
| functionAggregation | Facoltativo. Applicabile solo se vengono specificate funzioni. I valori validi includono: sum (default), average, minimum, maximum e firstMatching. Un punteggio di ricerca è un singolo valore calcolato da più variabili, incluse le funzioni multiple. Questo attributo indica il modo in cui gli aumenti di priorità di tutte le funzioni vengono combinati in un singolo aumento aggregato della priorità, che viene quindi applicato al punteggio di base del documento. Il punteggio di base dipende dal valore tf-idf calcolato dal documento e dalla query di ricerca. |
| defaultScoringProfile | Quando si esegue una richiesta di ricerca, se non viene specificato alcun profilo di punteggio, verrà usato il punteggio predefinito (solo tf-idf). È possibile eseguire l'override del valore predefinito sostituendo un profilo personalizzato come quello da usare quando non viene specificato alcun profilo specifico nella richiesta di ricerca. |
Impostare le interpolazioni
Le interpolazioni consentono di impostare la forma dell'inclinazione usata per il punteggio. Poiché il punteggio è indicato dal valore più alto al valore più basso, l'inclinazione diminuisce sempre, ma l'interpolazione determina la curva dell'inclinazione verso il basso. È possibile usare le interpolazioni seguenti:
| Interpolazione | Descrizione |
|---|---|
linear |
Per gli elementi inclusi nell'intervallo max e min, l'aumento di priorità applicato all'elemento corrisponderà a un importo costantemente decrescente. L'interpolazione predefinita per un profilo di punteggio è lineare. |
constant |
Per gli elementi inclusi nell'intervallo di inizio e di fine, ai risultati della classificazione verrà applicato un aumento di priorità costante. |
quadratic |
Rispetto all'interpolazione lineare che prevede un aumento di priorità costantemente decrescente, l'interpolazione quadratica presenterà una riduzione iniziale a ritmo più ridotto e una riduzione di intervallo molto più elevato in prossimità della fine. Questa opzione di interpolazione non è consentita nelle funzioni di assegnazione di punteggio in base a tag. |
logarithmic |
Rispetto all'interpolazione lineare che prevede un aumento di priorità costantemente decrescente, l'interpolazione logaritmica presenterà una riduzione iniziale a ritmo più elevato e una riduzione di intervallo molto più ridotto in prossimità della fine. Questa opzione di interpolazione non è consentita nelle funzioni di assegnazione di punteggio in base a tag. |
Impostare boostingDuration
boostingDuration è un attributo della funzione freshness. Consente di impostare un periodo di scadenza, dopo il quale l'aumento di priorità non verrà più applicato a un determinato documento. Ad esempio, per aumentare la priorità di una linea di prodotti o una marca per un periodo promozionale di 10 giorni, è necessario specificare tale periodo come "P10D" per questi documenti.
boostingDuration deve essere formattato come valore XSD "dayTimeDuration" (un subset limitato di un valore di durata ISO 8601). Il modello è: "P(nD)(T(nH)(nM](nS))".
La tabella seguente fornisce alcuni esempi.
| Durata | boostingDuration |
|---|---|
| 1 giorno | "P1D" |
| 2 giorni e 12 ore | "P2DT12H" |
| 15 minuti | "PT15M" |
| 30 giorni, 5 ore, 10 minuti e 6334 secondi | "P30DT5H10M6.334S" |
Per altri esempi, vedere il sito Web relativo ai tipi di dati dello schema XML (W3.org).
Esempio esteso
Il seguente esempio illustra lo schema di un indice con due profili di punteggio (boostGenre, newAndHighlyRated). Qualsiasi query eseguita in questo indice e che include uno dei profili come parametro di query userà il profilo per assegnare un punteggio al set di risultati.
Il profilo boostGenre usa campi di testo ponderati, corrispondenze di boosting trovate nei campi albumTitle, genre e artistName. La priorità dei campi viene incrementata rispettivamente di 1,5, 5 e 2. Al campo genre viene assegnata una priorità molto più alta rispetto agli altri, Se la ricerca viene eseguita su dati abbastanza omogenei (come nel caso di "genre" in musicstoreindex), potrebbe essere necessaria una varianza maggiore nei pesi relativi. Ad esempio, nel musicstoreindex "rock" viene visualizzato sia come genere che nelle descrizioni di genere che usano lo stesso termine. Se si vuole assegnare una priorità maggiore al genere rispetto alla descrizione del genere, il campo genre dovrà avere un peso relativo decisamente maggiore.
{
"name": "musicstoreindex",
"fields": [
{ "name": "key", "type": "Edm.String", "key": true },
{ "name": "albumTitle", "type": "Edm.String" },
{ "name": "albumUrl", "type": "Edm.String", "filterable": false },
{ "name": "genre", "type": "Edm.String" },
{ "name": "genreDescription", "type": "Edm.String", "filterable": false },
{ "name": "artistName", "type": "Edm.String" },
{ "name": "orderableOnline", "type": "Edm.Boolean" },
{ "name": "rating", "type": "Edm.Int32" },
{ "name": "tags", "type": "Collection(Edm.String)" },
{ "name": "price", "type": "Edm.Double", "filterable": false },
{ "name": "margin", "type": "Edm.Int32", "retrievable": false },
{ "name": "inventory", "type": "Edm.Int32" },
{ "name": "lastUpdated", "type": "Edm.DateTimeOffset" }
],
"scoringProfiles": [
{
"name": "boostGenre",
"text": {
"weights": {
"albumTitle": 1.5,
"genre": 5,
"artistName": 2
}
}
},
{
"name": "newAndHighlyRated",
"functions": [
{
"type": "freshness",
"fieldName": "lastUpdated",
"boost": 10,
"interpolation": "quadratic",
"freshness": {
"boostingDuration": "P365D"
}
},
{
"type": "magnitude",
"fieldName": "rating",
"boost": 10,
"interpolation": "linear",
"magnitude": {
"boostingRangeStart": 1,
"boostingRangeEnd": 5,
"constantBoostBeyondRange": false
}
}
]
}
],
"suggesters": [
{
"name": "sg",
"searchMode": "analyzingInfixMatching",
"sourceFields": [ "albumTitle", "artistName" ]
}
]
}