Guida introduttiva: Ricerca vettoriale con REST

Articolo
01/08/2025

Informazioni su come usare le API REST di ricerca per creare, caricare ed eseguire query sui vettori in Ricerca di intelligenza artificiale di Azure.

In Ricerca di intelligenza artificiale di Azure un archivio vettoriale ha uno schema di indice che definisce i campi vettoriali e non di filtro, una configurazione di ricerca vettoriale per gli algoritmi che creano lo spazio di incorporamento e le impostazioni sulle definizioni di campo vettoriale valutate in fase di query. L'API REST Crea indice crea l'archivio vettoriale.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Nota

Questo argomento della Guida introduttiva omette il passaggio di vettorizzazione e fornisce incorporamenti in documenti di esempio. Se si desidera aggiungere la suddivisione in blocchi e la vettorizzazione dei dati predefiniti del contenuto, eseguire la procedura guidata di importazione e vettorizzazione dei dati che illustra i passaggi necessari.

Prerequisiti

Visual Studio Code con un client REST.
Azure AI Search, in qualsiasi area e a qualsiasi livello di servizio. Creare o trovare una risorsa di Azure AI Search esistente nella sottoscrizione corrente.
- È possibile usare il livello Gratuito per la maggior parte di questa guida introduttiva, ma è consigliabile usare Basic o versione successiva per i file di dati di dimensioni maggiori.
- Per eseguire l'esempio di query che richiama il reranking semantico, il servizio di ricerca deve essere il livello Basic o superiore, con il ranker semantico abilitato.

Recuperare le informazioni sulle risorse

Le richieste all'endpoint di ricerca devono essere autenticate e autorizzate. È possibile usare chiavi API o ruoli per questa attività. È consigliabile usare una connessione senza chiave tramite Microsoft Entra ID.

Selezionare la scheda corrispondente al metodo di autenticazione preferito. Usare lo stesso metodo per tutte le richieste in questo argomento di avvio rapido.

Microsoft Entra ID
Chiave API

Accedere al portale di Azure e trovare il servizio di ricerca.
Nella home page Panoramica trovare l'URL. Un endpoint di esempio potrebbe essere simile a https://mydemo.search.windows.net.
Seguire i passaggi della guida introduttiva senza chiave per ottenere il token Microsoft Entra.

Il token viene ottenuto quando si esegue il az account get-access-token comando nel passaggio 3 dell'avvio rapido precedente.
```
az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
```

Accedere al portale di Azure e trovare il servizio di ricerca.
Nella home page Panoramica trovare l'URL. Un endpoint di esempio potrebbe essere simile a https://mydemo.search.windows.net.
Selezionare Impostazioni>Chiavi. Le chiavi API o Entrambe devono essere abilitate. Le chiavi API di amministrazione vengono usate per aggiungere, modificare ed eliminare oggetti. Sono disponibili due chiavi amministratore intercambiabili. Copiarne una.

Creare o scaricare il file di codice

Si usa uno o .http un .rest file per eseguire tutte le richieste in questa guida introduttiva. È possibile scaricare il file REST contenente il codice per questa guida introduttiva oppure creare un nuovo file in Visual Studio Code e copiarvi il codice.

In Visual Studio Code creare un nuovo file con un'estensione .rest o .http . Ad esempio: az-search-vector-quickstart.rest. Copiare e incollare il contenuto non elaborato del file Azure-Samples/azure-search-rest-samples/blob/main/Quickstart-vectors/az-search-vector-quickstart.rest in questo nuovo file.
Nella parte superiore del file sostituire il valore segnaposto per @baseUrl con l'URL del servizio di ricerca. Per istruzioni su come trovare l'URL del servizio di ricerca, vedere la sezione Recuperare le informazioni sulle risorse.
```
@baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
```
Nella parte superiore del file sostituire il valore segnaposto per l'autenticazione. Vedere la sezione Recuperare informazioni sulle risorse per istruzioni su come ottenere il token o la chiave API di Microsoft Entra.

Per l'autenticazione senza chiave consigliata tramite Microsoft Entra ID, è necessario sostituire @apiKey con la @token variabile .
```
@token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
```
Se si preferisce usare una chiave API, sostituire @apiKey con la chiave copiata dal portale di Azure.
```
@apiKey = PUT-YOUR-ADMIN-KEY-HERE
```
Per l'autenticazione senza chiave consigliata tramite Microsoft Entra ID, è necessario sostituire api-key: {{apiKey}} con Authorization: Bearer {{token}} nelle intestazioni della richiesta. Sostituire tutte le istanze di api-key: {{apiKey}} che si trovano nel file.

Creare un indice vettoriale

Usare l'API REST Crea indice per creare un indice vettoriale e configurare le strutture di dati fisiche nel servizio di ricerca.

Lo schema dell'indice in questo esempio è organizzato intorno al contenuto dell'hotel. I dati di esempio sono costituiti da nomi vettoriali e non di operatori e descrizioni di hotel fittizi. Questo schema include configurazioni per l'indicizzazione vettoriale e le query e per la classificazione semantica.

In Visual Studio Code aprire il az-search-vector-quickstart.rest file creato in precedenza.

Trovare il blocco di ### Create a new index codice nel file. Questo blocco contiene la richiesta di creare l'indice nel hotels-vector-quickstart servizio di ricerca.

### Create a new index
POST  {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "name": "hotels-vector-quickstart",
    "fields": [
        {
            "name": "HotelId", 
            "type": "Edm.String",
            "searchable": false, 
            "filterable": true, 
            "retrievable": true, 
            "sortable": false, 
            "facetable": false,
            "key": true
        },
        {
            "name": "HotelName", 
            "type": "Edm.String",
            "searchable": true, 
            "filterable": false, 
            "retrievable": true, 
            "sortable": true, 
            "facetable": false
        },
        {
            "name": "HotelNameVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-vector-profile"
        },
        {
            "name": "Description", 
            "type": "Edm.String",
            "searchable": true, 
            "filterable": false, 
            "retrievable": true, 
            "sortable": false, 
            "facetable": false
        },
        {
            "name": "DescriptionVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-vector-profile"
        },
                {
            "name": "Description_fr", 
            "type": "Edm.String",
            "searchable": true, 
            "filterable": false, 
            "retrievable": true, 
            "sortable": false, 
            "facetable": false,
            "analyzer": "en.microsoft"
        },
        {
            "name": "Description_frvector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-vector-profile"
        },
        {
            "name": "Category", 
            "type": "Edm.String",
            "searchable": true, 
            "filterable": true, 
            "retrievable": true, 
            "sortable": true, 
            "facetable": true
        },
        {
            "name": "Tags",
            "type": "Collection(Edm.String)",
            "searchable": true,
            "filterable": true,
            "retrievable": true,
            "sortable": false,
            "facetable": true
        },
                {
            "name": "ParkingIncluded",
            "type": "Edm.Boolean",
            "searchable": false,
            "filterable": true,
            "retrievable": true,
            "sortable": true,
            "facetable": true
        },
        {
            "name": "LastRenovationDate",
            "type": "Edm.DateTimeOffset",
            "searchable": false,
            "filterable": true,
            "retrievable": true,
            "sortable": true,
            "facetable": true
        },
        {
            "name": "Rating",
            "type": "Edm.Double",
            "searchable": false,
            "filterable": true,
            "retrievable": true,
            "sortable": true,
            "facetable": true
        },
        {
            "name": "Address", 
            "type": "Edm.ComplexType",
            "fields": [
                {
                    "name": "StreetAddress", "type": "Edm.String",
                    "searchable": true, "filterable": false, "retrievable": true, "sortable": false, "facetable": false
                },
                {
                    "name": "City", "type": "Edm.String",
                    "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true
                },
                {
                    "name": "StateProvince", "type": "Edm.String",
                    "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true
                },
                {
                    "name": "PostalCode", "type": "Edm.String",
                    "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true
                },
                {
                    "name": "Country", "type": "Edm.String",
                    "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true
                }
            ]
        },
        {
            "name": "Location",
            "type": "Edm.GeographyPoint",
            "searchable": false, 
            "filterable": true, 
            "retrievable": true, 
            "sortable": true, 
            "facetable": false
        }
    ],
    "vectorSearch": {
        "algorithms": [
            {
                "name": "my-hnsw-vector-config-1",
                "kind": "hnsw",
                "hnswParameters": 
                {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            },
            {
                "name": "my-hnsw-vector-config-2",
                "kind": "hnsw",
                "hnswParameters": 
                {
                    "m": 4,
                    "metric": "euclidean"
                }
            },
            {
                "name": "my-eknn-vector-config",
                "kind": "exhaustiveKnn",
                "exhaustiveKnnParameters": 
                {
                    "metric": "cosine"
                }
            }
        ],
        "profiles": [      
            {
                "name": "my-vector-profile",
                "algorithm": "my-hnsw-vector-config-1"
            }
      ]
    },
    "semantic": {
        "configurations": [
            {
                "name": "my-semantic-config",
                "prioritizedFields": {
                    "titleField": {
                        "fieldName": "HotelName"
                    },
                    "prioritizedContentFields": [
                        { "fieldName": "Description" }
                    ],
                    "prioritizedKeywordsFields": [
                        { "fieldName": "Category" }
                    ]
                }
            }
        ]
    }
}

Selezionare Invia richiesta. Si dovrebbe avere una risposta HTTP/1.1 201 Created.

Il corpo della risposta deve includere la rappresentazione JSON dello schema dell'indice.

{
    "@odata.context": "https://my-demo-search.search.windows.net/$metadata#indexes/$entity",
    "@odata.etag": "\"0x8DD2E70E6C36D8E\"",
    "name": "hotels-vector-quickstart",
    "defaultScoringProfile": null,
    "fields": [
    {
        "name": "HotelId",
        "type": "Edm.String",
        "searchable": false,
        "filterable": true,
        "retrievable": true,
        "sortable": false,
        "facetable": false,
        "key": true,
        "indexAnalyzer": null,
        "searchAnalyzer": null,
        "analyzer": null,
        "dimensions": null,
        "vectorSearchProfile": null,
        "synonymMaps": []
    },
    [MORE FIELD DEFINITIONS OMITTED FOR BREVITY]
    ],
    "scoringProfiles": [],
    "corsOptions": null,
    "suggesters": [],
    "analyzers": [],
    "tokenizers": [],
    "tokenFilters": [],
    "charFilters": [],
    "encryptionKey": null,
    "similarity": {
    "@odata.type": "#Microsoft.Azure.Search.BM25Similarity",
    "k1": null,
    "b": null
    },
    "vectorSearch": {
    "algorithms": [
        {
        "name": "my-hnsw-vector-config-1",
        "kind": "hnsw",
        "hnswParameters": {
            "metric": "cosine",
            "m": 4,
            "efConstruction": 400,
            "efSearch": 500
        },
        "exhaustiveKnnParameters": null
        },
        {
        "name": "my-hnsw-vector-config-2",
        "kind": "hnsw",
        "hnswParameters": {
            "metric": "euclidean",
            "m": 4,
            "efConstruction": 400,
            "efSearch": 500
        },
        "exhaustiveKnnParameters": null
        },
        {
        "name": "my-eknn-vector-config",
        "kind": "exhaustiveKnn",
        "hnswParameters": null,
        "exhaustiveKnnParameters": {
            "metric": "cosine"
        }
        }
    ],
    "profiles": [
        {
        "name": "my-vector-profile",
        "algorithm": "my-hnsw-vector-config-1"
        }
    ]
    },
    "semantic": {
    "defaultConfiguration": null,
    "configurations": [
        {
        "name": "my-semantic-config",
        "prioritizedFields": {
            "titleField": {
            "fieldName": "HotelName"
            },
            "prioritizedContentFields": [
            {
                "fieldName": "Description"
            }
            ],
            "prioritizedKeywordsFields": [
            {
                "fieldName": "Category"
            }
            ]
        }
        }
    ]
    }
}

Considerazioni chiave sull'API REST Di creazione dell'indice:

La raccolta fields include un campo chiave obbligatorio e campi di testo e vettore (ad esempio Description e DescriptionVector) per la ricerca di testo e vettore. Il colocating di campi vettoriali e non vettoriali nello stesso indice consente query ibride. Ad esempio, è possibile combinare filtri, ricerca di testo con classificazione semantica e vettori in una singola operazione di query.
I campi vettoriali devono essere type: Collection(Edm.Single) con proprietà dimensions e vectorSearchProfile.
La sezione vectorSearch è una matrice di configurazioni e profili approssimativi dell'algoritmo adiacente più vicino. Gli algoritmi supportati includono piccoli mondi navigabili gerarchici e vicini più prossimi k esaustivi. Per altre informazioni, vedere Assegnazione dei punteggi per pertinenza nella ricerca vettoriale.
La configurazione (facoltativa) semantic consente di riesezionare i risultati della ricerca. È possibile eseguire il reranking dei risultati nelle query di tipo semantic per i campi stringa specificati nella configurazione. Per altre informazioni, vedere Panoramica della classificazione semantica.

Carica documenti

La creazione e il caricamento dell'indice sono passaggi separati. Lo schema dell'indice è stato creato nel passaggio precedente. È ora necessario caricare i documenti nell'indice.

In Ricerca di intelligenza artificiale di Azure l'indice contiene tutti i dati e le query ricercabili eseguiti nel servizio di ricerca. Per le chiamate REST, i dati vengono forniti come documenti JSON. Usare l'API REST Documents- Index per questa attività. L'URI viene esteso per includere la raccolta docs e l'operazione index.

In Visual Studio Code aprire il az-search-vector-quickstart.rest file creato in precedenza.

Trovare il blocco di ### Upload documents codice nel file. Questo blocco contiene la richiesta di caricare documenti nell'indice nel hotels-vector-quickstart servizio di ricerca.

### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart-vectors/docs/index?api-version=2023-11-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "HotelName": "Stay-Kay City Hotel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "The hotel is ideally located on the main commercial artery of the city 
                in the heart of New York.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Boutique",
            "Tags": [
                "pool",
                "air conditioning",
                "concierge"
            ],
        },
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "2",
            "HotelName": "Old Century Hotel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "The hotel is situated in a  nineteenth century plaza, which has been 
                expanded and renovated to the highest architectural standards to create a modern, 
                functional and first-class hotel in which art and unique historical elements 
                coexist with the most modern comforts.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Boutique",
            "Tags": [
                "pool",
                "air conditioning",
                "free wifi",
                "concierge"
            ]
        },
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "3",
            "HotelName": "Gastronomic Landscape Hotel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "The Hotel stands out for its gastronomic excellence under the management of 
                William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Resort and Spa",
            "Tags": [
                "air conditioning",
                "bar",
                "continental breakfast"
            ]
        }
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "4",
            "HotelName": "Sublime Palace Hotel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "Sublime Palace Hotel is located in the heart of the historic center of 
                Sublime in an extremely vibrant and lively area within short walking distance to 
                the sites and landmarks of the city and is surrounded by the extraordinary beauty 
                of churches, buildings, shops and monuments. 
                Sublime Palace is part of a lovingly restored 1800 palace.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Boutique",
            "Tags": [
                "concierge",
                "view",
                "24-hour front desk service"
            ]
        },
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "13",
            "HotelName": "Luxury Lion Resort",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury 
                accommodations. Moments from the stadium, we feature the best in comfort",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Resort and Spa",
            "Tags": [
                "view",
                "free wifi",
                "pool"
            ]
        },
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "48",
            "HotelName": "Nordick's Valley Motel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "Only 90 miles (about 2 hours) from the nation's capital and nearby 
                most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring 
                the caverns?  It's all nearby and we have specially priced packages to help make 
                our B&B your home base for fun while visiting the valley.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Boutique",
            "Tags": [
                "continental breakfast",
                "air conditioning",
                "free wifi"
            ],
        },
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "49",
            "HotelName": "Swirling Currents Hotel",
            "HotelNameVector": [VECTOR ARRAY OMITTED],
            "Description": 
                "Spacious rooms, glamorous suites and residences, rooftop pool, walking 
                access to shopping, dining, entertainment and the city center.",
            "DescriptionVector": [VECTOR ARRAY OMITTED],
            "Category": "Luxury",
            "Tags": [
                "air conditioning",
                "laundry service",
                "24-hour front desk service"
            ]
        }
    ]
}

Importante

Il codice in questo esempio non è eseguibile. Diversi caratteri o righe vengono rimossi per brevità. Usare il codice nel az-search-vector-quickstart.rest file per eseguire la richiesta.

Selezionare Invia richiesta. Si dovrebbe avere una risposta HTTP/1.1 200 OK. Il corpo della risposta deve includere la rappresentazione JSON dei documenti di ricerca.

Considerazioni chiave sulla richiesta dell'API REST Documents - Index:

I documenti nel payload sono costituiti da campi definiti nello schema dell'indice.
I campi vettoriali contengono valori a virgola mobile. L'attributo dimensions ha un minimo di 2 e un massimo di 3.072 valori a virgola mobile ciascuno. Questo argomento di avvio rapido imposta l'attributo dimensions su 1.536 perché è la dimensione degli incorporamenti generati dal modello text-embedding-ada-002 di Azure OpenAI.

Esegui query

Ora che i documenti vengono caricati, è possibile eseguire query vettoriali su di esse usando Documenti - Post di ricerca (REST).

Nelle sezioni successive vengono eseguite query sull'indice hotels-vector-quickstart . Le query includono:

Ricerca a vettore singolo
Ricerca a vettore singolo con filtro
Ricerca ibrida
Ricerca semantica ibrida con filtro

Le query vettoriali di esempio si basano su due stringhe:

Stringa di ricerca: historic hotel walk to restaurants and shopping
Stringa di query vettoriale (vettorializzata in una rappresentazione matematica): classic lodging near running trails, eateries, retail

La stringa di query vettoriale è semanticamente simile alla stringa di ricerca, ma include termini che non esistono nell'indice di ricerca. Se si esegue una ricerca di parole chiave per classic lodging near running trails, eateries, retail, i risultati sono zero. Questo esempio viene usato per mostrare come ottenere risultati pertinenti anche se non sono presenti termini corrispondenti.

Ricerca a vettore singolo

In Visual Studio Code aprire il az-search-vector-quickstart.rest file creato in precedenza.
Trovare il blocco di ### Run a single vector query codice nel file. Questo blocco contiene la richiesta di eseguire query sull'indice di ricerca.
```
### Run a single vector query
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{token}}

    {
        "count": true,
        "select": "HotelId, HotelName, Description, Category",
        "vectorQueries": [
            {
                "vector"": [0.01944167, 0.0040178085
                    . . .  TRIMMED FOR BREVITY
                    010858015, -0.017496133],
                "k": 7,
                "fields": "DescriptionVector",
                "kind": "vector",
                "exhaustive": true
            }
        ]
    }
```
Questa query vettoriale viene abbreviata per motivi di brevità. Il vectorQueries.vector contiene il testo vettorializzato dell'input della query, fields determina quali campi vettoriali vengono ricercati e k specifica il numero di vicini più prossimi da restituire.

La stringa di query vettoriale è classic lodging near running trails, eateries, retail, che viene vettorializzata in 1.536 incorporamenti per questa query.

Importante

Il codice in questo esempio non è eseguibile. Diversi caratteri o righe vengono rimossi per brevità. Usare il codice nel az-search-vector-quickstart.rest file per eseguire la richiesta.
Selezionare Invia richiesta. Si dovrebbe avere una risposta HTTP/1.1 200 OK. Il corpo della risposta deve includere la rappresentazione JSON dei risultati della ricerca.

La risposta per l'equivalente vettore di classic lodging near running trails, eateries, retail include sette risultati. Ogni risultato fornisce un punteggio di ricerca e i campi elencati in select. In una ricerca di somiglianza, la risposta include sempre risultati k ordinati in base al punteggio di somiglianza del valore.

{
  "@odata.context": "https://my-demo-search.search.windows.net/indexes('hotels-vector-quickstart')/$metadata#docs(*)",
  "@odata.count": 7,
  "value": [
    {
      "@search.score": 0.85773647,
      "HotelId": "48",
      "HotelName": "Nordick's Motel",
      "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring the caverns?  It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
      "Category": "Boutique"
    },
    {
      "@search.score": 0.8399132,
      "HotelId": "49",
      "HotelName": "Old Carrabelle Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
      "Category": "Luxury"
    },
    {
      "@search.score": 0.83839583,
      "HotelId": "13",
      "HotelName": "Historic Lion Resort",
      "Description": "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort",
      "Category": "Resort and Spa"
    },
    {
      "@search.score": 0.82543474,
      "HotelId": "4",
      "HotelName": "Sublime Cliff Hotel",
      "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.",
      "Category": "Boutique"
    },
    {
      "@search.score": 0.82380104,
      "HotelId": "1",
      "HotelName": "Secret Point Hotel",
      "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
      "Category": "Boutique"
    },
    {
      "@search.score": 0.8151413,
      "HotelId": "2",
      "HotelName": "Twin Dome Hotel",
      "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
      "Category": "Boutique"
    },
    {
      "@search.score": 0.8133767,
      "HotelId": "3",
      "HotelName": "Triple Landscape Hotel",
      "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel\u2019s restaurant services.",
      "Category": "Resort and Spa"
    }
  ]
}

Ricerca a vettore singolo con filtro

È possibile aggiungere filtri, ma i filtri vengono applicati al contenuto non di filtro nell'indice. In questo esempio, il filtro si applica al campo Tags per filtrare tutti gli hotel che non forniscono il Wi-Fi gratuito.

In Visual Studio Code aprire il az-search-vector-quickstart.rest file creato in precedenza.

Trovare il blocco di ### Run a vector query with a filter codice nel file. Questo blocco contiene la richiesta di eseguire query sull'indice di ricerca.

### Run a vector query with a filter
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{token}}

    {
        "count": true,
        "select": "HotelId, HotelName, Category, Tags, Description",
        "filter": "Tags/any(tag: tag eq 'free wifi')",
        "vectorFilterMode": "postFilter",
        "vectorQueries": [
        {
            "vector": [ VECTOR OMITTED ],
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        },
    ]
}

Importante

Il codice in questo esempio non è eseguibile. Diversi caratteri o righe vengono rimossi per brevità. Usare il codice nel az-search-vector-quickstart.rest file per eseguire la richiesta.

Selezionare Invia richiesta. Si dovrebbe avere una risposta HTTP/1.1 200 OK. Il corpo della risposta deve includere la rappresentazione JSON dei risultati della ricerca.

La query è la stessa dell'esempio di ricerca a vettore singolo precedente, ma include un filtro di esclusione post-elaborazione e restituisce solo i tre hotel che dispongono di Wi-Fi gratuito.

{
  "@odata.context": "https://my-demo-search.search.windows.net/indexes('hotels-vector-quickstart')/$metadata#docs(*)",
  "@odata.count": 3,
  "value": [
    {
      "@search.score": 0.85773647,
      "HotelId": "48",
      "HotelName": "Nordick's Motel",
      "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring the caverns?  It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
      "Category": "Boutique",
      "Tags": [
        "continental breakfast",
        "air conditioning",
        "free wifi"
      ]
    },
    {
      "@search.score": 0.83839583,
      "HotelId": "13",
      "HotelName": "Historic Lion Resort",
      "Description": "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort",
      "Category": "Resort and Spa",
      "Tags": [
        "view",
        "free wifi",
        "pool"
      ]
    },
    {
      "@search.score": 0.8151413,
      "HotelId": "2",
      "HotelName": "Twin Dome Hotel",
      "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
      "Category": "Boutique",
      "Tags": [
        "pool",
        "free wifi",
        "air conditioning",
        "concierge"
      ]
    }
  ]
}

Ricerca ibrida

La ricerca ibrida è costituita da query con parole chiave e query vettoriali in una singola richiesta di ricerca. Questo esempio esegue simultaneamente la query vettoriale e la ricerca full-text:

Stringa di ricerca: historic hotel walk to restaurants and shopping
Stringa di query vettoriale (vettorializzata in una rappresentazione matematica): classic lodging near running trails, eateries, retail

In Visual Studio Code aprire il az-search-vector-quickstart.rest file creato in precedenza.

Trovare il blocco di ### Run a hybrid query codice nel file. Questo blocco contiene la richiesta di eseguire query sull'indice di ricerca.

### Run a hybrid query
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{token}}

{
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description",
    "top": 7,
    "vectorQueries": [
        {
            "vector": [ VECTOR OMITTED],
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

Importante

Il codice in questo esempio non è eseguibile. Diversi caratteri o righe vengono rimossi per brevità. Usare il codice nel az-search-vector-quickstart.rest file per eseguire la richiesta.

Selezionare Invia richiesta. Si dovrebbe avere una risposta HTTP/1.1 200 OK. Il corpo della risposta deve includere la rappresentazione JSON dei risultati della ricerca.

Poiché si tratta di una query ibrida, i risultati vengono classificati in base al valore RRF (Reciprocal Rank Fusion). RRF valuta i punteggi di ricerca di più risultati di ricerca, accetta l'inverso e quindi unisce e ordina i risultati combinati. Viene restituito il numero top di risultati.

Esaminare la risposta:

{
    "@odata.count": 7,
    "value": [
        {
            "@search.score": 0.03279569745063782,
            "HotelName": "Luxury Lion Resort",
            "Description": "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort"
        },
        {
            "@search.score": 0.03226646035909653,
            "HotelName": "Sublime Palace Hotel",
            "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace."
        },
        {
            "@search.score": 0.03226646035909653,
            "HotelName": "Swirling Currents Hotel",
            "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center."
        },
        {
            "@search.score": 0.03205128386616707,
            "HotelName": "Nordick's Valley Motel",
            "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring the caverns?  It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley."
        },
        {
            "@search.score": 0.03128054738044739,
            "HotelName": "Gastronomic Landscape Hotel",
            "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services."
        },
        {
            "@search.score": 0.03100961446762085,
            "HotelName": "Old Century Hotel",
            "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts."
        },
        {
            "@search.score": 0.03077651560306549,
            "HotelName": "Stay-Kay City Hotel",
            "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York."
        }
    ]
}

Poiché RRF unisce i risultati, consente di esaminare gli input. I risultati seguenti provengono solo dalla query full-text. I primi due risultati sono Sublime Palace Hotel e History Lion Resort. Il Sublime Palace Hotel ha un punteggio di pertinenza BM25 più forte.

{
    "@search.score": 2.2626662,
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace."
},
{
    "@search.score": 0.86421645,
    "HotelName": "Luxury Lion Resort",
    "Description": "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort"
},

Nella query di solo vettore, che usa HNSW per trovare corrispondenze, sublime Palace Hotel scende alla quarta posizione. Historic Lion, secondo nella ricerca full-text e terzo nella ricerca vettoriale, non riscontra lo stesso intervallo di fluttuazione, quindi appare come una corrispondenza principale in un set di risultati omogeneizzato.

"value": [
    {
        "@search.score": 0.857736,
        "HotelId": "48",
        "HotelName": "Nordick's Valley Motel",
        "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring the caverns?  It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
        "Category": "Boutique"
    },
    {
        "@search.score": 0.8399129,
        "HotelId": "49",
        "HotelName": "Swirling Currents Hotel",
        "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
        "Category": "Luxury"
    },
    {
        "@search.score": 0.8383954,
        "HotelId": "13",
        "HotelName": "Luxury Lion Resort",
        "Description": "Unmatched Luxury.  Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium, we feature the best in comfort",
        "Category": "Resort and Spa"
    },
    {
        "@search.score": 0.8254346,
        "HotelId": "4",
        "HotelName": "Sublime Palace Hotel",
        "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.",
        "Category": "Boutique"
    },
    {
        "@search.score": 0.82380056,
        "HotelId": "1",
        "HotelName": "Stay-Kay City Hotel",
        "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
        "Category": "Boutique"
    },
    {
        "@search.score": 0.81514084,
        "HotelId": "2",
        "HotelName": "Old Century Hotel",
        "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
        "Category": "Boutique"
    },
    {
        "@search.score": 0.8133763,
        "HotelId": "3",
        "HotelName": "Gastronomic Landscape Hotel",
        "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
        "Category": "Resort and Spa"
    }
]

Ricerca semantica ibrida con un filtro

Ecco l'ultima query della raccolta. Questa query ibrida con classificazione semantica viene filtrata per visualizzare solo gli hotel entro un raggio di 500 chilometri di Washington D.C. È possibile impostare vectorFilterMode su Null, che equivale al valore predefinito (preFilter per gli indici più recenti e postFilter per quelli meno recenti).

In Visual Studio Code aprire il az-search-vector-quickstart.rest file creato in precedenza.

Trovare il blocco di ### Run a hybrid query with semantic reranking codice nel file. Questo blocco contiene la richiesta di eseguire query sull'indice di ricerca.

### Run a hybrid query with semantic reranking
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{token}}

{
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelId, HotelName, Category, Description,Address/City, Address/StateProvince",
    "filter": "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 500",
    "vectorFilterMode": null,
    "facets": [ "Address/StateProvince"],
    "top": 7,
    "queryType": "semantic",
    "answers": "extractive|count-3",
    "captions": "extractive|highlight-true",
    "semanticConfiguration": "my-semantic-config",
    "vectorQueries": [
        {
            "vector": [ VECTOR OMITTED ],
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

Importante

Il codice in questo esempio non è eseguibile. Diversi caratteri o righe vengono rimossi per brevità. Usare il codice nel az-search-vector-quickstart.rest file per eseguire la richiesta.

Selezionare Invia richiesta. Si dovrebbe avere una risposta HTTP/1.1 200 OK. Il corpo della risposta deve includere la rappresentazione JSON dei risultati della ricerca.

Rivedere la risposta. La risposta è costituita da tre hotel, filtrati in base alla posizione e facet in base a StateProvince, e classificati in modo semantico per alzare di livello i risultati più vicini alla query della stringa di ricerca (historic hotel walk to restaurants and shopping).

L'Hotel Swirling Currents ora si sposta nella parte superiore. Senza classifica semantica, Il Motel della Valle di Nordick è il numero uno. Con la classificazione semantica, i modelli di comprensione della macchina riconoscono che historic si applica a "hotel, a pochi passi da ristoranti e negozi".

{
  "@odata.context": "https://my-demo-search.search.windows.net/indexes('hotels-vector-quickstart')/$metadata#docs(*)",
  "@odata.count": 2,
  "@search.facets": {
    "Address/StateProvince": [
      {
        "count": 1,
        "value": "VA"
      }
    ]
  },
  "@search.answers": [],
  "value": [
    {
      "@search.score": 0.03306011110544205,
      "@search.rerankerScore": 2.8773112297058105,
      "HotelId": "49",
      "HotelName": "Old Carrabelle Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
      "Category": "Luxury",
      "Address": {
        "City": "Arlington",
        "StateProvince": "VA"
      }
    },
    {
      "@search.score": 0.03306011110544205,
      "@search.rerankerScore": 2.1703834533691406,
      "HotelId": "48",
      "HotelName": "Nordick's Motel",
      "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer.  Hiking? Wine Tasting? Exploring the caverns?  It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
      "Category": "Boutique",
      "Address": {
        "City": "Washington D.C.",
        "StateProvince": null
      }
    }
  ]
}

Considerazioni chiave sui documenti - API REST post-ricerca :

La ricerca vettoriale viene specificata tramite la proprietà vectors.value. La ricerca di parole chiave viene specificata tramite la proprietà search.
In una ricerca ibrida è possibile integrare la ricerca vettoriale con la ricerca full-text sulle parole chiave. I filtri, il controllo ortografico e la classificazione semantica si applicano solo ai contenuti testuali e non ai vettori. In questa query finale non esiste un answer semantico perché il sistema non ha prodotto una query sufficientemente forte.
I risultati effettivi includono più dettagli, tra cui didascalie semantiche ed evidenziazioni. I risultati sono stati modificati per la leggibilità. Per ottenere la struttura completa della risposta, eseguire la richiesta nel client REST.

Eseguire la pulizia

Quando si lavora nella propria sottoscrizione, al termine di un progetto è buona norma determinare se le risorse create sono ancora necessarie. Le risorse che rimangono in esecuzione hanno un costo. È possibile eliminare risorse singole oppure gruppi di risorse per eliminare l'intero set di risorse.

È possibile trovare e gestire le risorse nella portale di Azure usando il collegamento Tutte le risorse o Gruppi di risorse nel riquadro più a sinistra.

Se si vuole mantenere il servizio di ricerca, ma eliminare l'indice e i documenti, è possibile usare il DELETE comando nel client REST. Questo comando (alla fine del az-search-vector-quickstart.rest file) elimina l'indice hotels-vector-quickstart :

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-vector-quickstart?api-version=2023-11-01 HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{token}}

Passaggi successivi

Come passaggio successivo, è consigliabile imparare a richiamare le chiamate API REST senza chiavi API.

È anche possibile esaminare il codice demo per Python, C# o JavaScript.

Condividi tramite

Guida introduttiva: Ricerca vettoriale con REST

Prerequisiti

Recuperare le informazioni sulle risorse

Creare o scaricare il file di codice

Creare un indice vettoriale

Carica documenti

Esegui query

Ricerca a vettore singolo

Ricerca a vettore singolo con filtro

Ricerca ibrida

Ricerca semantica ibrida con un filtro

Eseguire la pulizia

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive