Creare o aggiornare l'indice (API REST di anteprima)
Si applica a: 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview
Importante
2023-07-01-Preview aggiunge la ricerca vettoriale.
- Oggetto "vectorSearch", una configurazione delle impostazioni di ricerca vettoriale. Si applica solo agli algoritmi di ricerca vettoriale.
- Tipo di dati "Collection(Edm.Single)", obbligatorio per un campo vettoriale. Rappresenta un numero a virgola mobile e precisione singola come tipo primitivo.
- Proprietà "dimensions", obbligatoria per un campo vettoriale. Rappresenta la dimensionalità degli incorporamenti vettoriali.
- Proprietà "vectorSearchConfiguration", obbligatoria per un campo vettoriale. Seleziona la configurazione dell'algoritmo per questo campo.
2021-04-30-Preview aggiunge:
- "semanticConfiguration" usato per definire l'ambito della classificazione semantica in campi specifici.
- "identity", in "encryptionKey", usato per recuperare una chiave di crittografia gestita dal cliente da Azure Key Vault usando un'identità gestita assegnata dall'utente.
2020-06-30-Preview aggiunge:
- "normalizer", usato per l'insensibilità tra maiuscole e minuscole su ordinamenti e filtri.
Un indice specifica lo schema dell'indice, inclusa la raccolta di campi (nomi di campo, tipi di dati e attributi), ma anche altri costrutti (suggerimenti, profili di punteggio e configurazione CORS) che definiscono altri comportamenti di ricerca.
È possibile usare POST o PUT in una richiesta di creazione. Per entrambi, il corpo della richiesta fornisce la definizione dell'oggetto.
POST https://[servicename].search.windows.net/indexes?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Per le richieste di aggiornamento, usare PUT e specificare il nome dell'indice nell'URI.
PUT https://[servicename].search.windows.net/indexes/[index name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Per tutte le richieste del servizio, è necessario usare il protocollo HTTPS. Se l'indice non esiste, viene creato. Se esiste già, viene aggiornato alla nuova definizione.
La creazione di un indice stabilisce lo schema e i metadati. Il popolamento dell'indice è un'operazione separata. Per questo passaggio, è possibile usare un indicizzatore (vedere Operazioni dell'indicizzatore, disponibili per le origini dati supportate) oppure Aggiungere, aggiornare o eliminare documenti. Il numero massimo di indici che è possibile creare varia in base al piano tariffario. All'interno di ogni indice sono previsti limiti per i singoli elementi. Per altre informazioni, vedere Limiti dei servizi per Ricerca intelligenza artificiale di Azure.
L'aggiornamento di un indice esistente deve includere la definizione completa dello schema, incluse le definizioni originali che si desidera mantenere. In generale, il modello migliore per gli aggiornamenti consiste nel recuperare la definizione dell'indice con get, modificarla e quindi aggiornarla con PUT.
Poiché un indice esistente contiene contenuto, molte modifiche all'indice richiedono un'eliminazione e la ricompilazione dell'indice. Le modifiche dello schema seguenti sono un'eccezione a questa regola:
Aggiunta di nuovi campi
Aggiunta o modifica dei profili di punteggio
Aggiunta o modifica di configurazioni semantiche
Modifica delle opzioni CORS
Modifica dei campi esistenti con una delle tre modifiche seguenti:
- Visualizzare o nascondere i campi (
retrievable: true | false) - Modificare l'analizzatore usato in fase di query (
searchAnalyzer) - Aggiungere o modificare il synonymMap usato in fase di query (
synonymMaps)
- Visualizzare o nascondere i campi (
Per apportare una delle modifiche dello schema precedenti a un indice esistente, specificare il nome dell'indice nell'URI della richiesta e quindi includere una definizione di indice completamente specificata con gli elementi nuovi o modificati.
Quando viene aggiunto un nuovo campo, tutti i documenti esistenti nell'indice hanno automaticamente un valore Null per tale campo. Non viene utilizzato spazio di archiviazione aggiuntivo fino a quando non si verifica uno dei due elementi seguenti: viene fornito un valore per il nuovo campo (tramite merge) o vengono aggiunti nuovi documenti.
Aggiornamenti a un suggester oggetto hanno vincoli simili: è possibile aggiungere nuovi campi a un suggester oggetto contemporaneamente, ma i campi esistenti non possono essere rimossi né aggiunti a suggesters senza una ricompilazione dell'indice.
Aggiornamenti a un analizzatore, a un tokenizer, a un filtro di token o a un filtro char non sono consentiti. È possibile crearne di nuovi con le modifiche desiderate, ma è necessario portare l'indice offline quando si aggiungono le nuove definizioni dell'analizzatore. L'impostazione del allowIndexDowntime flag su true nella richiesta di aggiornamento dell'indice porta offline l'indice:
PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true
Questa operazione porta offline l'indice per almeno alcuni secondi, il che significa che l'indicizzazione e le richieste di query hanno esito negativo fino a quando l'indice non torna online e pronto per gestire le richieste.
Parametri dell'URI
| Parametro | Descrizione |
|---|---|
| nome servizio | Obbligatorio. Impostare questo valore sul nome univoco definito dall'utente del servizio di ricerca. |
| nome indice | Obbligatorio nell'URI se si usa PUT. Il nome deve essere minuscolo, iniziare con una lettera o un numero, non avere barre o punti e contenere meno di 128 caratteri. I trattini non possono essere consecutivi. |
| api-version | Obbligatorio. La versione di anteprima corrente è 2023-07-23-preview. Per altre versioni, vedere Versioni API . |
| allowIndexDowntime | facoltativo. False per impostazione predefinita. Impostare su true per determinati aggiornamenti, ad esempio l'aggiunta o la modifica di un analizzatore, un tokenizer, un filtro token, un filtro char o una proprietà di somiglianza. L'indice viene portato offline durante l'aggiornamento, in genere non più di diversi secondi. |
Intestazioni richiesta
La tabella seguente descrive le intestazioni della richiesta obbligatorie e facoltative.
| Campi | Descrizione |
|---|---|
| Content-Type | Obbligatorio. Impostare questo 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 creazione devono includere un'intestazione api-key impostata sulla chiave amministratore anziché su una chiave di query. Per informazioni dettagliate, vedere Connettersi a Ricerca intelligenza artificiale di Azure usando l'autenticazione della chiave . |
Corpo della richiesta
Il corpo della richiesta contiene una definizione dello schema, che include l'elenco di campi dati all'interno di documenti inseriti in questo indice.
Il codice JSON seguente è una rappresentazione generale di uno schema che supporta la ricerca vettoriale. Uno schema richiede un campo chiave e tale campo chiave può essere ricercabile, filtrabile, ordinabile e facetable.
Un campo di ricerca vettoriale è di tipo Collection(Edm.Single). Poiché i campi vettoriali non sono testuali, non è possibile usare un campo vettoriale come chiave e non accetta analizzatori, normalizzatori, suggerimenti o sinonimi. Deve avere una proprietà "dimensions" e una proprietà "vectorSearchConfiguration".
Uno schema che supporta la ricerca vettoriale può supportare anche la ricerca di parole chiave. Altri campi non di operatore nell'indice possono usare qualsiasi analizzatore, sinonimi e profili di punteggio inclusi nell'indice.
{
"name": (optional on PUT; required on POST) "Name of the index",
"description": (optional) "Description of the index",
"fields": [
{
"name": "name_of_field",
"type": "Edm.String | Edm.Int32 | Edm.Int64 | Edm.Double | Edm.Boolean | Edm.DateTimeOffset | Edm.GeographyPoint | Edm.ComplexType | Collection(Edm.String) | Collection(Edm.Int32) | Collection(Edm.Int64) | Collection(Edm.Single) | Collection(Edm.Double) | Collection(Edm.Boolean) | Collection(Edm.DateTimeOffset) | Collection(Edm.GeographyPoint) | Collection(Edm.ComplexType)",
"key": true | false (default, only Edm.String fields can be keys, enable on one field only),
"searchable": true (default where applicable) | false (only Edm.String and Collection(Edm.String) fields can be searchable),
"filterable": true (default) | false,
"sortable": true (default where applicable) | false (Collection(Edm.String) fields cannot be sortable),
"facetable": true (default where applicable) | false (Edm.GeographyPoint fields cannot be facetable),
"retrievable": true (default) | false,
"analyzer": "name_of_analyzer_for_search_and_indexing", (only if 'searchAnalyzer' and 'indexAnalyzer' are not set)
"searchAnalyzer": "name_of_search_analyzer", (only if 'indexAnalyzer' is set and 'analyzer' is not set)
"indexAnalyzer": "name_of_indexing_analyzer", (only if 'searchAnalyzer' is set and 'analyzer' is not set)
"normalizer": "name_of_normalizer", (optional, applies only to filterable, facetable, or sortable Edm.String and Collection(Edm.String) fields.)
"synonymMaps": [ "name_of_synonym_map" ], (optional, only one synonym map per field is currently supported),
"fields" : [ ... ], (optional, a list of sub-fields if this is a field of type Edm.ComplexType or Collection(Edm.ComplexType). Must be null or empty for simple fields.)
"dimensions": 1234, (required for vector field definitions. Prohibited for non-vector fields. Integer specifying the dimensionality of the embeddings generated by a machine learning model)
"vectorSearchConfiguration": "name_of_algorithm_config" (required for vector field definitions. Prohibited for non-vector fields. This should reference an algorithm configuration.)
}
],
"similarity": (optional) { },
"suggesters": (optional) [ ... ],
"scoringProfiles": (optional) [ ... ],
"semantic": (optional) { },
"vectorSearch": (optional) {
"algorithmConfigurations": [
{
"name": "name_of_algorithm_config",
"kind": "hnsw" (algorithm type. Only "hnsw" is supported currently.),
"hnswParameters": {
"m": 4,
"efConstruction": 400,
"efSearch": 500,
"metric": "cosine"
}
}
]},
"normalizers":(optional) [ ... ],
"analyzers":(optional) [ ... ],
"charFilters":(optional) [ ... ],
"tokenizers":(optional) [ ... ],
"tokenFilters":(optional) [ ... ],
"defaultScoringProfile": (optional) "Name of a custom scoring profile to use as the default",
"corsOptions": (optional) { },
"encryptionKey":(optional) { }
}
La richiesta contiene le proprietà seguenti:
| Proprietà | Descrizione |
|---|---|
| name | Obbligatorio. Nome dell'indice. Un nome di indice deve contenere solo lettere minuscole, cifre o trattini, non può iniziare o terminare con trattini ed è limitato a 128 caratteri. |
| description | Descrizione facoltativa. |
| campi | Raccolta di campi per questo indice, in cui ogni campo ha un nome, un tipo di dati supportato conforme al modello EDM (Entity Data Model) e attributi che definiscono azioni consentite su tale campo. L'insieme fields deve avere un campo di tipo Edm.String con "key" impostato su "true". Questo campo rappresenta l'identificatore univoco, talvolta denominato ID documento, per ogni documento archiviato con l'indice. L'insieme fields ora accetta campi vettoriali. |
| Somiglianza | facoltativo. Per i servizi creati prima del 15 luglio 2020, impostare questa proprietà per acconsentire esplicitamente all'algoritmo di classificazione BM25. |
| suggerimenti | Specifica un costrutto che archivia i prefissi per la corrispondenza nelle query parziali, ad esempio il completamento automatico e i suggerimenti. |
| scoringProfiles | facoltativo. Usato per l'ottimizzazione della pertinenza per le query full-text. |
| Semantica | facoltativo. Definisce i parametri di un indice di ricerca che influiscono sulle funzionalità di ricerca semantica. Per le query semantiche è necessaria una configurazione semantica. Per altre informazioni, vedere Creare una query semantica. |
| vectorSearch | facoltativo. Configura varie impostazioni di ricerca vettoriale. È possibile configurare solo gli algoritmi di ricerca vettoriale. |
| normalizzatori | facoltativo. Normalizza l'ordinamento lessicografico delle stringhe, generando un ordinamento senza distinzione tra maiuscole e minuscole e filtrando l'output. |
| analizzatori, charFilters, tokenizer, tokenFilters | facoltativo. Specificare queste sezioni dell'indice se si definiscono analizzatori personalizzati. Per impostazione predefinita, queste sezioni sono Null. |
| defaultScoringProfile | Nome di un profilo di assegnazione dei punteggi personalizzato che sovrascrive i comportamenti di assegnazione dei punteggi predefiniti. |
| corsOptions | facoltativo. Usato per le query tra le origini nell'indice. |
| encryptionKey | facoltativo. Usato per la crittografia aggiuntiva dell'indice, tramite chiavi di crittografia gestite dal cliente in Azure Key Vault. Disponibile per i servizi di ricerca fatturabili creati in o dopo il 2019-01-01. |
Risposta
Per una richiesta di creazione riuscita, verrà visualizzato il codice di stato "201 Created". Per impostazione predefinita, il corpo della risposta contiene il codice JSON per la definizione di indice creata. Tuttavia, se l'intestazione Prefer request è impostata su return=minimal, il corpo della risposta è vuoto e il codice di stato dell'operazione riuscita è "204 No Content" anziché "201 Created". Questo vale indipendentemente dal fatto che sia stato usato il metodo PUT o POST per creare l'indice.
Per una richiesta di aggiornamento riuscita, verrà visualizzato "204 Nessun contenuto". Per impostazione predefinita, il corpo della risposta è vuoto. Tuttavia, se l'intestazione della Prefer richiesta è impostata su return=representation, il corpo della risposta contiene il codice JSON per la definizione dell'indice aggiornata. In questo caso, il codice di stato dell'operazione riuscita è "200 OK".
Esempio
Esempio: Vettore
La ricerca vettoriale viene implementata a livello di campo. Questa definizione pone lo stato attivo sui campi vettoriali. I campi vettoriali devono essere di tipo Collection(Edm.Single) utilizzato per archiviare valori a virgola mobile a precisione singola. I campi vettoriali hanno una proprietà "dimensions" che contiene il numero di dimensioni di output supportate dal modello di Machine Learning usato per generare incorporamenti. Ad esempio, se si usa text-embedding-ada-002, il numero massimo di dimensioni di output è 1536 per questo documento. "algorithmConfiguration" è impostato sul nome della configurazione "vectorSearch" nell'indice. È possibile definire più nell'indice e quindi specificarne uno per campo.
Molti attributi si applicano solo ai campi non di ctor. Gli attributi come "filtrabili", "ordinabili", "facetable", "analyzer", "normalizer" e "synonymMaps" vengono ignorati per i campi vettoriali. Analogamente, se si impostano proprietà solo vettoriali come "dimensions" o "vectorSearchConfiguration" nel campo contenente contenuto alfanumerici, tali attributi vengono ignorati.
{
"name": "{{index-name}}",
"fields": [
{
"name": "id",
"type": "Edm.String",
"key": true,
"searchable": true,
"retrievable": true,
"filterable": true
},
{
"name": "titleVector",
"type": "Collection(Edm.Single)",
"key": false,
"searchable": true,
"retrievable": true,
"filterable": false,
"sortable": false,
"facetable": false,
"analyzer": "",
"searchAnalyzer": "",
"indexAnalyzer": "",
"normalizer": "",
"synonymMaps": "",
"dimensions": 1536,
"vectorSearchConfiguration": "my-vector-config"
},
{
"name": "contentVector",
"type": "Collection(Edm.Single)",
"key": false,
"searchable": true,
"retrievable": true,
"filterable": false,
"sortable": false,
"facetable": false,
"analyzer": "",
"searchAnalyzer": "",
"indexAnalyzer": "",
"normalizer": "",
"synonymMaps": "",
"dimensions": 1536,
"vectorSearchConfiguration": "my-vector-config"
}
],
"vectorSearch": {
"algorithmConfigurations": [
{
"name": "my-vector-config",
"kind": "hnsw",
"hnswParameters": {
"m": 4,
"efConstruction": 400,
"efSearch": 500,
"metric": "cosine"
}
}
]
}
}
Esempio: Raccolte di campi con campi vettoriali e non vettoriali
La ricerca vettoriale viene implementata a livello di campo. Per supportare scenari di query ibride, creare coppie di campi per le query vettoriali e non trici. I campi "title", "titleVector", "content", "contentVector" seguono questa convenzione. Se si vuole anche usare la ricerca semantica, è necessario disporre di campi di testo non di filtro per tali comportamenti.
{
"name": "{{index-name}}",
"fields": [
{
"name": "id",
"type": "Edm.String",
"key": true,
"filterable": true
},
{
"name": "title",
"type": "Edm.String",
"searchable": true,
"retrievable": true
},
{
"name": "content",
"type": "Edm.String",
"searchable": true,
"retrievable": true
},
{
"name": "category",
"type": "Edm.String",
"filterable": true,
"searchable": true,
"retrievable": true
},
{
"name": "titleVector",
"type": "Collection(Edm.Single)",
"searchable": true,
"retrievable": true,
"dimensions": 1536,
"vectorSearchConfiguration": "my-vector-config"
},
{
"name": "contentVector",
"type": "Collection(Edm.Single)",
"searchable": true,
"retrievable": true,
"dimensions": 1536,
"vectorSearchConfiguration": "my-vector-config"
}
],
"corsOptions": {
"allowedOrigins": [
"*"
],
"maxAgeInSeconds": 60
},
"vectorSearch": {
"algorithmConfigurations": [
{
"name": "my-vector-config",
"kind": "hnsw",
"hnswParameters": {
"m": 4,
"efConstruction": 400,
"efSearch": 500,
"metric": "cosine"
}
}
]
},
"semantic": {
"configurations": [
{
"name": "my-semantic-config",
"prioritizedFields": {
"titleField": {
"fieldName": "title"
},
"prioritizedContentFields": [
{
"fieldName": "content"
}
],
"prioritizedKeywordsFields": [
{
"fieldName": "category"
}
]
}
}
]
}
}
Esempio: schema di indice con campi semplici e complessi
Il primo esempio mostra uno schema di indice completo con campi semplici e complessi. Almeno un campo stringa deve avere "key" impostato su true.
{
"name": "hotels",
"fields": [
{ "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
{ "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
{ "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
{ "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
{ "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" },
{ "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
{ "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
{ "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
{ "name": "Address", "type": "Edm.ComplexType",
"fields": [
{ "name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
{ "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true, "normalizer": "lowercase" },
{ "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true }
]
},
{ "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
{ "name": "Rooms", "type": "Collection(Edm.ComplexType)",
"fields": [
{ "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
{ "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
{ "name": "Type", "type": "Edm.String", "searchable": true },
{ "name": "BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
{ "name": "BedOptions", "type": "Edm.String", "searchable": true },
{ "name": "SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
{ "name": "SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
{ "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" }
]
}
],
"suggesters": [ ],
"analyzers": [ ],
"normalizers": [ ],
"encryptionKey": [ ]
}
Esempio: Suggerimenti
Una definizione del suggerimento deve specificare i campi stringa "ricercabili" e "recuperabili" (nelle API REST tutti i campi semplici sono "retrievable": true per impostazione predefinita). Dopo aver definito un suggerimento, è possibile farvi riferimento per nome nelle richieste di query che usano l'API Suggerimenti o l'API completamento automatico, a seconda che si voglia restituire una corrispondenza o il resto di un termine di query.
{
"name": "hotels",
"fields": [
{ "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
{ "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
{ "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
{ "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
{ "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" },
{ "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
],
"suggesters": [
{
"name": "sg",
"searchMode": "analyzingInfixMatching",
"sourceFields": ["HotelName", "Category", "Tags"]
}
]
}
Esempio: Analizzatori e normalizzatori
Gli analizzatori e i normalizzatori vengono a cui viene fatto riferimento nelle definizioni dei campi e possono essere predefiniti o personalizzati. Se si usano analizzatori o normalizzatori personalizzati, specificarli nell'indice nelle sezioni "analizzatori" e "normalizzatori".
Nell'esempio seguente vengono illustrati analizzatori personalizzati e normalizzatori per "Tags". Illustra inoltre un normalizzatore predefinito (standard) e un analizzatore (en.microsoft) rispettivamente per "HotelName" e "Description".
{
"name": "hotels",
"fields": [
{ "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
{ "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false, "normalizer": standard },
{ "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft"},
{ "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
{ "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" },
{ "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
],
"analyzers": [
{
"@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
"name": "tagsAnalyzer",
"charFilters": [ "html_strip" ],
"tokenizer": "standard_v2"
}
],
"normalizers": [
{
"@odata.type": "#Microsoft.Azure.Search.CustomNormalizer",
"name": "tagsNormalizer",
"tokenFilters": [ "asciifolding", "lowercase" ]
}
]
}
Esempio: somiglianza per pertinenza della ricerca
Questa proprietà imposta l'algoritmo di classificazione usato per creare un punteggio di pertinenza nei risultati della ricerca di una query di ricerca full-text. Nei servizi creati dopo il 15 luglio 2020 questa proprietà viene ignorata perché l'algoritmo di somiglianza è sempre BM25. Per i servizi esistenti creati prima del 15 luglio 2020, è possibile acconsentire esplicitamente a BM25 impostando questo costrutto come segue:
"similarity": {
"@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
}
Esempio: Opzioni CORS
JavaScript sul lato client non può chiamare api per impostazione predefinita perché il browser impedisce tutte le richieste tra le origini. Per consentire query tra origini all'indice, abilitare CORS (Condivisione di risorse tra le origini (Wikipedia)) impostando l'attributo corsOptions . Per motivi di sicurezza, solo le API di query supportano CORS.
{
"name": "hotels",
"fields": [ omitted for brevity ],
"suggesters": [ omitted for brevity ],
"analyzers": [ omitted for brevity ],
"corsOptions": (optional) {
"allowedOrigins": ["*"] | ["https://docs.microsoft.com:80", "https://azure.microsoft.com:80", ...],
"maxAgeInSeconds": (optional) max_age_in_seconds (non-negative integer)
}
}
Esempio: Chiavi di crittografia con credenziali di accesso
Le chiavi di crittografia sono chiavi gestite dal cliente usate per la crittografia aggiuntiva. Per altre informazioni, vedere Crittografia con chiavi gestite dal cliente in Azure Key Vault.
{
"name": "hotels",
"fields": [ omitted for brevity ],
"suggesters": [ omitted for brevity ],
"analyzers": [ omitted for brevity ],
"encryptionKey": (optional) {
"keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
"keyVaultKeyVersion": "Version of the Azure Key Vault key",
"keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
"accessCredentials": (optional, only if not using managed system identity) {
"applicationId": "AAD Application ID that was granted access permissions to your specified Azure Key Vault",
"applicationSecret": "Authentication key of the specified AAD application)"
}
}
}
Esempio: Chiavi di crittografia con identità gestita
È possibile eseguire l'autenticazione in Azure Key Vault usando un'identità gestita assegnata dal sistema o assegnata dall'utente (anteprima). In questo caso, omettere le credenziali di accesso o impostare su Null. L'esempio seguente mostra un'identità gestita assegnata dall'utente. Per usare un'identità gestita assegnata dal sistema, omettere le credenziali di accesso e l'identità. Se l'identità di sistema del servizio di ricerca dispone delle autorizzazioni in Azure Key Vault, la richiesta di connessione deve avere esito positivo.
{
"name": "hotels",
"fields": [ omitted for brevity ],
"suggesters": [ omitted for brevity ],
"analyzers": [ omitted for brevity ],
"encryptionKey": (optional) {
"keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
"keyVaultKeyVersion": "Version of the Azure Key Vault key",
"keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
"accessCredentials": null,
"identity" : {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity" : "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"
}
}
}
Esempio: Profili di punteggio
Un profilo di punteggio è una sezione dello schema che definisce i comportamenti di assegnazione dei punteggi personalizzati che consentono di influenzare i documenti visualizzati più in alto nei risultati della ricerca. I profili di punteggio sono costituiti da funzioni e campi ponderati. Per utilizzarli, è necessario specificare il nome di un profilo nella stringa di query. Per altre informazioni, vedere Aggiungere profili di punteggio a un indice di ricerca (API REST di Ricerca intelligenza artificiale di Azure) per informazioni dettagliate.
{
"name": "hotels",
"fields": [ omitted for brevity ],
"suggesters": [ omitted for brevity ],
"analyzers": [ omitted for brevity ],
"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)
},
"freshness": {
"boostingDuration": "..." (value representing timespan leading to now over which boosting occurs)
},
"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)
},
"tag": {
"tagsParameter": "..." (parameter to be passed in queries to specify a list of tags to compare against target fields)
}
}
],
"functionAggregation": (optional, applies only when functions are specified)
"sum (default) | average | minimum | maximum | firstMatching"
}
]
}
Esempio: Configurazioni semantiche
Una configurazione semantica fa parte di una definizione di indice usata per configurare i campi utilizzati dalla ricerca semantica per la classificazione, le didascalie, le evidenziazioni e le risposte. Per usare la ricerca semantica, è necessario specificare il nome di una configurazione semantica in fase di query. Per altre informazioni, vedere Creare una query semantica.
{
"name": "hotels",
"fields": [ omitted for brevity ],
"suggesters": [ omitted for brevity ],
"analyzers": [ omitted for brevity ],
"semantic": {
"configurations": [
{
"name": "my-semantic-config",
"prioritizedFields": {
"titleField": {
"fieldName": "hotelName"
},
"prioritizedContentFields": [
{
"fieldName": "description"
},
{
"fieldName": "description_fr"
}
],
"prioritizedKeywordsFields": [
{
"fieldName": "tags"
},
{
"fieldName": "category"
}
]
}
}
]
}
}
Definizioni
| Collegamento | Descrizione |
|---|---|
| corsOptions | Elenca i domini o le origini concessi all'indice. |
| defaultScoringProfile | Nome di un profilo di assegnazione dei punteggi personalizzato che sovrascrive i comportamenti di assegnazione dei punteggi predefiniti. |
| EncryptionKey | Configura una connessione ad Azure Key Vault per la crittografia gestita dal cliente. |
| campi | Imposta definizioni e attributi di un campo in un indice di ricerca. |
| normalizzatori | Configura un normalizzatore personalizzato. Normalizza l'ordinamento lexicografico delle stringhe, generando l'ordinamento senza distinzione tra maiuscole e minuscole, il faceting e l'output di filtro. |
| Semantica | Configura i campi usati dalla ricerca semantica per classificazioni, didascalie, evidenziazioni e risposte. |
| assegnazione dei punteggiProfile | Usato per l'ottimizzazione della pertinenza per le query full-text. |
| Somiglianza | |
| suggeritori | Configura l'archiviazione del prefisso interno per la corrispondenza nelle query parziali, ad esempio il completamento automatico e i suggerimenti. |
| vectorSearch | Configura l'algoritmo usato per i campi vettoriali. |
corsOptions
JavaScript lato client non può chiamare alcuna API per impostazione predefinita perché il browser impedisce tutte le richieste tra origini. Per consentire query tra origini all'indice, abilitare CORS (Cross-Origin Resource Sharing) impostando l'attributo "corsOptions". Per motivi di sicurezza, solo le API di query supportano CORS.
| Attributo | Descrizione |
|---|---|
| allowedOrigins | Obbligatorio. Elenco delimitato da virgole di origini concesse all'indice, in cui ogni origine è in genere del modulo protocol://< ly-qualified-domain-name>:<port> (anche se la <porta> viene spesso omessa). Ciò significa che qualsiasi codice JavaScript servito da tali origini è consentito eseguire query all'indice (presupponendo che fornisca una chiave API valida). Se si vuole consentire l'accesso a tutte le origini, specificare * come singolo elemento nella matrice "allowOrigins". Non è consigliabile per la produzione, ma potrebbe essere utile per lo sviluppo o il debug. |
| maxAgeInSeconds | facoltativo. I browser usano questo valore per determinare la durata (in secondi) di memorizzazione nella cache delle risposte preliminari CORS. Questo valore deve essere un intero non negativo. Le prestazioni migliorano se questo valore è maggiore, ma questi guadagni sono compensati dalla quantità di tempo necessaria per le modifiche dei criteri CORS per l'effetto. Se non è impostato, viene usata una durata predefinita di 5 minuti. |
defaultScoringProfile
facoltativo. Stringa che corrisponde al nome di un profilo di assegnazione dei punteggi personalizzato definito nell'indice. Viene richiamato un profilo predefinito ogni volta che un profilo personalizzato non viene specificato in modo esplicito nella stringa di query. Per altre informazioni, vedere Aggiungere profili di assegnazione dei punteggi a un indice di ricerca.
EncryptionKey
Configura una connessione ad Azure Key Vault per chiavi di crittografia gestite dal cliente aggiuntive (CMK). Disponibile per i servizi di ricerca fatturabili creati o dopo il 1° gennaio 2019.
È necessario autenticare una connessione all'insieme di credenziali delle chiavi. È possibile usare "accessCredentials" o un'identità gestita per questo scopo.
Le identità gestite possono essere assegnate dal sistema o dall'utente (anteprima). Se il servizio di ricerca ha sia un'identità gestita assegnata dal sistema che un'assegnazione di ruolo che concede l'accesso in lettura all'insieme di credenziali delle chiavi, è possibile omettere "identity" e "accessCredentials" e la richiesta eseguirà l'autenticazione usando l'identità gestita. Se il servizio di ricerca ha un'assegnazione di identità e ruolo assegnata dall'utente, impostare la proprietà "identity" sull'ID risorsa di tale identità.
| Attributo | Descrizione |
|---|---|
| keyVaultKeyName | Obbligatorio. Nome della chiave di Key Vault di Azure usata per la crittografia. |
| keyVaultKeyVersion | Obbligatorio. Versione della chiave di Key Vault di Azure. |
| keyVaultUri | Obbligatorio. URI di Azure Key Vault (noto anche come nome DNS) che fornisce la chiave. Un URI di esempio potrebbe essere https://my-keyvault-name.vault.azure.net |
| accessCredentials | facoltativo. Omettere questa proprietà se si usa un'identità gestita. In caso contrario, le proprietà di "accessCredentials" includono: "applicationId" (ID applicazione di Azure Active Directory con autorizzazioni di accesso per l'Key Vault di Azure specificato). "applicationSecret" (chiave di autenticazione dell'applicazione Azure AD specificata). |
| identity | Facoltativo, a meno che non si usi un'identità gestita assegnata dall'utente per la connessione al servizio di ricerca in Azure Key Vault. Il formato è "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]". |
fields
Contiene informazioni sugli attributi in una definizione di campo.
| Attributo | Descrizione |
|---|---|
| name | Obbligatorio. Imposta il nome del campo, che deve essere univoco all'interno dell'insieme campi del campo indice o padre. |
| tipo | Obbligatorio. Imposta il tipo di dati per il campo. I campi possono essere semplici o complessi. I campi semplici sono di tipi primitivi, ad esempio Edm.String per il testo o Edm.Int32 per gli interi. I campi complessi possono avere campi secondari che si trovano in sé semplici o complessi. Ciò consente di modellare oggetti e matrici di oggetti, che a sua volta consentono di caricare la maggior parte delle strutture di oggetti JSON nell'indice. Collection(Edm.Single) ospita valori a virgola mobile a precisione singola. Viene usato solo per i campi vettoriali ed è obbligatorio. Per l'elenco completo dei tipi supportati, vedere Tipi di dati supportati . |
| Key | Obbligatorio. Impostare questo attributo su true per designare che i valori di un campo identificano in modo univoco i documenti nell'indice. La lunghezza massima dei valori in un campo chiave è di 1024 caratteri. È necessario scegliere esattamente un campo di primo livello in ogni indice come campo chiave e deve essere di tipo Edm.String. Il valore predefinito è false per i campi semplici e null per i campi complessi. I campi chiave possono essere usati per cercare i documenti direttamente ed aggiornare o eliminare documenti specifici. I valori dei campi chiave vengono gestiti in modo distinzione tra maiuscole e minuscole durante la ricerca o l'indicizzazione dei documenti. Per informazioni dettagliate, vedere Ricerca documento e aggiunta, aggiornamento o eliminazione di documenti . |
| retrievable | Indica se il campo può essere restituito in un risultato di ricerca. Impostare questo attributo su false se si vuole usare un campo (ad esempio, margine) come filtro, ordinamento o meccanismo di assegnazione dei punteggi, ma non si vuole che il campo sia visibile all'utente finale. Questo attributo deve essere per i campi chiave e deve essere truenull per campi complessi. Questo attributo può essere modificato nei campi esistenti. L'impostazione di recuperabile su true non causa un aumento dei requisiti di archiviazione dell'indice. Il valore predefinito è true per i campi semplici e null per i campi complessi. |
| searchable | Indica se il campo è ricercabile full-text e può essere fatto riferimento nelle query di ricerca. Ciò significa che subisce un'analisi lexicale , ad esempio l'interruzione delle parole durante l'indicizzazione. Se si imposta un campo ricercabile su un valore come "Sunny day", viene normalizzato internamente nei singoli token "sunny" e "day". È così possibile eseguire ricerche full-text di questi termini. I campi di tipo Edm.String o Collection(Edm.String) sono ricercabili per impostazione predefinita. Questo attributo deve essere false per i campi semplici di altri tipi di dati nonstring e deve essere null per campi complessi. Un campo ricercabile usa spazio aggiuntivo nell'indice poiché Ricerca intelligenza artificiale di Azure elabora il contenuto di tali campi e li organizza in strutture di dati ausiliarie per la ricerca efficiente. Se si vuole risparmiare spazio nell'indice e non è necessario includere un campo nelle ricerche, impostare ricercabile su false. Per informazioni dettagliate, vedere Funzionamento della ricerca full-text in Ricerca intelligenza artificiale di Azure . |
| filterable | Indica se abilitare il campo a cui fare riferimento nelle $filter query. Il filtro è diverso dal modo in cui vengono gestite le stringhe. I campi di tipo Edm.String o Collection(Edm.String) che sono filtrabili non subiscono analisi lessicali, quindi i confronti sono solo per corrispondenze esatte. Ad esempio, se si imposta un campo di questo tipo f su "Sunny day", non trova corrispondenze, $filter=f eq 'sunny' ma $filter=f eq 'Sunny day' lo farà. Questo attributo deve essere null per campi complessi. Il valore predefinito è true per i campi semplici e null per i campi complessi. Per ridurre le dimensioni dell'indice, impostare questo attributo su false su campi in cui non verrà eseguito il filtro. |
| sortable | Indica se abilitare il campo a cui fare riferimento nelle $orderby espressioni. Per impostazione predefinita, Ricerca intelligenza artificiale di Azure ordina i risultati per punteggio, ma in molte esperienze gli utenti vogliono ordinare in base ai campi nei documenti. Un campo semplice può essere ordinabile solo se è a valore singolo (ha un singolo valore nell'ambito del documento padre). I campi di raccolta semplici non possono essere ordinabili, poiché sono multivalore. I sottocampi semplici delle raccolte complesse sono anche multivalore e pertanto non possono essere ordinabili. Questo è vero se si tratta di un campo padre immediato o di un campo predecessore, ovvero la raccolta complessa. I campi complessi non possono essere ordinabili e l'attributo ordinabile deve essere null per tali campi. Il valore predefinito per l'ordinamento è true per i campi semplici con valore singolo, false per i campi semplici con più valori e null per i campi complessi. |
| facetable | Indica se abilitare il campo a cui fare riferimento nelle query facet. In genere usato in una presentazione dei risultati della ricerca che includono il numero di hit per categoria (ad esempio, cercare fotocamere digitali e vedere le hit per marchio, da megalie, per prezzo e così via). Questo attributo deve essere null per campi complessi. I campi di tipo Edm.GeographyPoint o Collection(Edm.GeographyPoint) non possono essere visibili. Il valore predefinito è true per tutti gli altri campi semplici. Per ridurre le dimensioni dell'indice, impostare questo attributo su false su campi in cui non verrà eseguito il facet. |
| Analyzer | Imposta l'analizzatore lessicale per l'indicizzazione delle stringhe durante le operazioni di indicizzazione e query. I valori validi per questa proprietà includono analizzatori del linguaggio, analizzatori predefiniti e analizzatoripersonalizzati. Il valore predefinito è standard.lucene. Questo attributo può essere usato solo con campi ricercabili e non può essere impostato insieme a searchAnalyzer o indexAnalyzer. Dopo aver scelto l'analizzatore e il campo viene creato nell'indice, non può essere modificato per il campo. Deve essere null per campi complessi. |
| searchAnalyzer | Impostare questa proprietà insieme a indexAnalyzer per specificare diversi analizzatori lessicali per l'indicizzazione e le query. Se si usa questa proprietà, impostare analizzatore su null e assicurarsi che indexAnalyzer sia impostato su un valore consentito. I valori validi per questa proprietà includono analizzatori predefiniti e analizzatori personalizzati. Questo attributo può essere usato solo con campi ricercabili. L'analizzatore di ricerca può essere aggiornato in un campo esistente perché viene usato solo in fase di query. Deve essere null per campi complessi. |
| indexAnalyzer | Impostare questa proprietà insieme a searchAnalyzer per specificare diversi analizzatori lessicali per l'indicizzazione e le query. Se si usa questa proprietà, impostare analizzatore su null e assicurarsi che searchAnalyzer sia impostato su un valore consentito. I valori validi per questa proprietà includono analizzatori predefiniti e analizzatori personalizzati. Questo attributo può essere usato solo con campi ricercabili. Dopo aver scelto l'analizzatore di indici, non può essere modificato per il campo. Deve essere null per campi complessi. |
| Normalizzatore | Imposta il normalizzatore per le operazioni di filtro, ordinamento e faceting. Può essere il nome di un normalizzatore predefinito o di un normalizzatore personalizzato definito all'interno dell'indice. Il valore predefinito è null, che comporta una corrispondenza esatta sul testo dettagliato, non analizzato. Questo attributo può essere usato solo con Edm.String e Collection(Edm.String) campi con almeno uno dei valori filtrabili, ordinabili o visobili impostati su true. Un normalizzatore può essere impostato solo sul campo quando aggiunto all'indice e non può essere modificato in un secondo momento. Deve essere null per campi complessi. I valori validi per un normalizzatore predefinito includono: - standardLettere minuscole il testo seguito dalla asciifolding. lowercase- Trasforma i caratteri in lettere minuscole. uppercase - Trasforma i caratteri in maiuscolo. asciifolding - Trasforma i caratteri che non si trovano nel blocco Unicode latino di base nell'equivalente ASCII, se presente. Ad esempio, la modifica di "à" in "a". elision- Rimuove l'elisione dall'inizio dei token. |
| sinonimoMaps | Elenco dei nomi delle mappe sinonimi da associare a questo campo. Questo attributo può essere usato solo con campi ricercabili. Attualmente è supportata solo una mappa sinonimo per campo. L'assegnazione di un mapping sinonimo a un campo garantisce che i termini di query destinati al campo vengano espansi in fase di query usando le regole nella mappa sinonimia. Questo attributo può essere modificato nei campi esistenti. Deve essere null o una raccolta vuota per campi complessi. |
| fields | Elenco di campi secondari se si tratta di un campo di tipo Edm.ComplexType o Collection(Edm.ComplexType). Deve essere null o vuoto per i campi semplici. Vedere Come modellare tipi di dati complessi in Ricerca intelligenza artificiale di Azure per altre informazioni su come e quando usare i campi secondari. |
| dimensions | Integer. Obbligatorio per i campi vettoriali. **Deve corrispondere alle dimensioni di incorporamento dell'output del modello di incorporamento. Ad esempio, per un modello text-embedding-ada-002OpenAI di Azure popolare, le dimensioni di output sono 1536, quindi si tratta delle dimensioni da impostare per tale campo vettore. L'attributo dimensioni ha un minimo di 2 e un massimo di 2048 valori a virgola mobile ogni. |
| vectorSearchConfiguration | Obbligatorio per le definizioni dei campi vettoriali. Specifica il nome della configurazione dell'algoritmo "vectorSearch" utilizzata dal campo vettore. Dopo aver creato il campo, non è possibile modificare il nome di vectorSearchConfiguration, ma è possibile modificare le proprietà della configurazione dell'algoritmo nell'indice. Ciò consente di apportare modifiche al tipo di algoritmo e ai parametri. |
Nota
I campi di tipo Edm.String filtrabili, ordinabili o visobili possono essere al massimo 32 kilobyte di lunghezza. Questo è dovuto al fatto che i valori di tali campi vengono considerati come un singolo termine di ricerca e la lunghezza massima di un termine in Ricerca intelligenza artificiale di Azure è di 32 kilobyte. Se è necessario archiviare più testo di questo in un singolo campo stringa, è necessario impostare in modo esplicito filtrabili, ordinabili e visobili false nella definizione dell'indice.
L'impostazione di un campo come ricercabile, filtrabile, ordinabile o facetable ha un impatto sulle dimensioni dell'indice e sulle prestazioni delle query. Non impostare tali attributi nei campi a cui non si intende fare riferimento nelle espressioni di query.
Se un campo non è impostato per essere ricercabile, filtrabile, ordinabile o facetable, il campo non può essere fatto riferimento in alcuna espressione di query. Ciò è utile per i campi che non vengono usati nelle query, ma sono necessari nei risultati della ricerca.
normalizzatori
Definisce un normalizzatore personalizzato con una combinazione definita dall'utente di filtri di caratteri e filtri token. Dopo aver definito un normalizzatore personalizzato nell'indice, è possibile specificarlo in base al nome in una definizione di campo.
| Attributo | Descrizione |
|---|---|
| name | Obbligatorio. Campo stringa che specifica un normalizzatore personalizzato definito dall'utente. |
| charFilters | Usato in un normalizzatore personalizzato. Può essere uno o più filtri di caratteri disponibili supportati per l'uso in un normalizzatore personalizzato: mapping pattern_replace |
| tokenFilters | Usato in un normalizzatore personalizzato. Può essere uno o più deipuntatori del token disponibili supportati per l'uso in un normalizzatore personalizzato: arabic_normalization cjk_width cjk_widtheligerman_normalization sione hindi_normalization indic_normalization persian_normalization scandinavian_normalization scandinavian_folding sorani_normalization maiuscolo minuscolo |
assegnazione dei punteggiProfile
I profili di assegnazione dei punteggi si applicano alla ricerca full-text. Un profilo viene definito in un indice e specifica la logica personalizzata che può assegnare punteggi di ricerca più elevati ai documenti corrispondenti che soddisfano i criteri definiti nel profilo. È possibile creare più profili di assegnazione dei punteggi e quindi assegnare quello che si vuole eseguire una query.
Se si crea un profilo personalizzato, è possibile impostarlo defaultScoringProfileper impostazione predefinita. Per altre informazioni, vedere Aggiungere profili di assegnazione dei punteggi a un indice di ricerca.
Semantica
Una configurazione semantica fa parte di una definizione di indice usata per configurare i campi utilizzati dalla ricerca semantica per classificazioni, didascalie, evidenziazioni e risposte. Le configurazioni semantiche sono costituite da un campo titolo, campi contenuto con priorità e campi parole chiave con priorità. È necessario specificare almeno un campo per ognuna delle tre sotto proprietà (titleField, prioritizedKeywordsFields e prioritizedContentFields). Qualsiasi campo di tipo Edm.String o Collection(Edm.String) può essere usato come parte di una configurazione semantica.
Per usare la ricerca semantica, è necessario specificare il nome di una configurazione semantica in fase di query. Per altre informazioni, vedere Creare una query semantica.
{
"name": "hotels",
"fields": [ omitted for brevity ],
"suggesters": [ omitted for brevity ],
"analyzers": [ omitted for brevity ],
"semantic": {
"configurations": [
{
"name": "name of the semantic configuration",
"prioritizedFields": {
"titleField": {
"fieldName": "..."
},
"prioritizedContentFields": [
{
"fieldName": "..."
},
{
"fieldName": "..."
}
],
"prioritizedKeywordsFields": [
{
"fieldName": "..."
},
{
"fieldName": "..."
}
]
}
}
]
}
}
| Attributo | Descrizione |
|---|---|
| name | Obbligatorio. Nome della configurazione semantica. |
| prioritizedFields | Obbligatorio. Descrive i campi titolo, contenuto e parola chiave da usare per classificazione semantica, didascalie, evidenziazioni e risposte. È necessario impostare almeno una delle tre sotto proprietà (titleField, prioritizedKeywordsFields e prioritizedContentFields). |
| prioritizedFields.titleField | Definisce il campo titolo da usare per la classificazione semantica, le didascalie, le evidenziazioni e le risposte. Se non si dispone di un campo titolo nell'indice, lasciare vuoto questo campo. |
| prioritizedFields.prioritizedContentFields | Definisce i campi di contenuto da usare per classificazione semantica, didascalie, evidenziazioni e risposte. Per ottenere il risultato migliore, i campi selezionati devono contenere testo nel formato del linguaggio naturale. L'ordine dei campi nella matrice rappresenta la priorità. I campi con priorità inferiore possono essere troncati se il contenuto è lungo. |
| prioritizedFields.prioritizedKeywordsFields | Definisce i campi delle parole chiave da usare per la classificazione semantica, le didascalie, le evidenziazioni e le risposte. Per il risultato migliore, i campi selezionati devono contenere un elenco di parole chiave. L'ordine dei campi nella matrice rappresenta la priorità. I campi con priorità inferiore possono essere troncati se il contenuto è lungo. |
somiglianza
Proprietà facoltativa che si applica ai servizi creati prima del 15 luglio 2020. Per tali servizi, è possibile impostare questa proprietà per usare l'algoritmo di classificazione BM25 introdotto nel luglio 2020. I valori validi includono "#Microsoft.Azure.Search.ClassicSimilarity" (il valore predefinito precedente) o "#Microsoft.Azure.Search.BM25Similarity".
Per tutti i servizi creati dopo luglio 2020, l'impostazione di questa proprietà non ha alcun effetto. Tutti i servizi più recenti usano BM25 come algoritmo di classificazione unica per la ricerca full-text. Per altre informazioni, vedere Classificazione degli algoritmi in Ricerca intelligenza artificiale di Azure.
suggeritori
Specifica un costrutto che archivia i prefissi per la corrispondenza nelle query parziali, ad esempio il completamento automatico e i suggerimenti.
| Attributo | Descrizione |
|---|---|
| name | Obbligatorio. Nome dello strumento suggerimenti. |
| sourceFields | Obbligatorio. Uno o più campi stringa per i quali si abilita il completamento automatico o i risultati suggeriti. |
| searchMode | Obbligatorio e sempre impostato su analyzingInfixMatching. Specifica che la corrispondenza si verifica in qualsiasi termine nella stringa di query. |
vectorSearch
L'oggetto vectorSearch consente la configurazione delle proprietà di ricerca vettore. È attualmente possibile configurare solo le configurazioni degli algoritmi. Ciò consente la configurazione dei parametri del tipo di algoritmo e dell'algoritmo usati per i campi vettoriali. È possibile avere più configurazioni. Le configurazioni a cui fa riferimento un campo vettore non possono essere modificate né eliminate. Le configurazioni a cui non si fa riferimento possono essere modificate o eliminate. Una definizione di campo vettore (nell'insieme campi) deve specificare quale configurazione dell'algoritmo di ricerca vettore (tramite la vectorSearchConfiguration proprietà) che il campo usa.
"vectorSearch": {
"algorithmConfigurations": [
{
"name": "my-vector-config",
"kind": "hnsw",
"hnswParameters": {
"m": 4,
"efConstruction": 400,
"efSearch": 500,
"metric": "cosine"
}
}
]
}
| Attributo | Descrizione |
|---|---|
| name | Obbligatorio. Nome della configurazione dell'algoritmo. |
| kind | Tipo di algoritmo da usare. È supportato solo '"hnsw"', ovvero l'algoritmo HNSW (Gerarchico Navigable Small World). |
| hnswParameters | facoltativo. Parametri per l'algoritmo "hnsw". Se questo oggetto viene omesso, vengono usati i valori predefiniti. |
hnswParameters
Questo oggetto contiene le personalizzazioni per hnsw i parametri dell'algoritmo. Tutte le proprietà sono facoltative e i valori predefiniti vengono usati se vengono omessi.
| Attributo | Descrizione |
|---|---|
| Metrica | Stringa. Metrica di somiglianza da usare per i confronti vettoriali. Per hnsw, i valori consentiti sono "cosine", "euclidean" e "dotProduct". Il valore predefinito è "cosine". |
| m | Integer. Numero di collegamenti bidirezionali creati per ogni nuovo elemento durante la costruzione. Il valore predefinito è 4. L'intervallo consentito è da 4 a 10. I valori più grandi portano a grafici più densi, migliorando le prestazioni delle query, ma richiedono una maggiore memoria e calcolo. |
| efConstruction | Integer. Dimensioni dell'elenco dinamico per i vicini più vicini usati durante l'indicizzazione. Il valore predefinito è 400. L'intervallo consentito è compreso tra 100 e 1000.Valori più grandi comportano una migliore qualità dell'indice, ma richiedono una maggiore memoria e calcolo. |
| efSearch | Integer. Dimensioni dell'elenco dinamico contenente i vicini più vicini, usati durante il periodo di ricerca. Il valore predefinito è 500. L'intervallo consentito è compreso tra 100 e 1000. L'aumento di questo parametro può migliorare i risultati della ricerca, ma rallenta le prestazioni delle query. |
Poiché efSearch è un parametro in fase di query, questo valore può essere aggiornato anche se un campo esistente usa una configurazione dell'algoritmo.