Quickstart: Vector search by using REST

Artikel
01/08/2025

Meer informatie over het gebruik van de SEARCH REST API's voor het maken, laden en opvragen van vectoren in Azure AI Search.

In Azure AI Search heeft een vectorarchief een indexschema dat vectorvelden en niet-vectorvelden definieert, een vectorzoekconfiguratie voor algoritmen die de insluitruimte maken en instellingen voor vectorvelddefinities die tijdens de query worden geëvalueerd. Met de CREATE Index REST API wordt het vectorarchief gemaakt.

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

Notitie

In deze quickstart wordt de vectorisatiestap weggelaten en worden ingesloten in voorbeelddocumenten. Als u ingebouwde gegevenssegmentering en vectorisatie wilt toevoegen aan uw eigen inhoud, kunt u de wizard Gegevens importeren en vectoriseren voor een end-to-end-overzicht.

Vereisten

Visual Studio Code met een REST-client.
Azure AI Search, in elke regio en op elke laag. Maak of zoek een bestaande Azure AI Search-resource onder uw huidige abonnement.
- U kunt de gratis laag voor de meeste van deze quickstart gebruiken, maar Basic of hoger wordt aanbevolen voor grotere gegevensbestanden.
- Als u het queryvoorbeeld wilt uitvoeren dat semantische herrankering aanroept, moet uw zoekservice de Basic-laag of hoger zijn, waarbij semantische rangschikking is ingeschakeld.

Resourcegegevens ophalen

Aanvragen voor het zoekeindpunt moeten worden geverifieerd en geautoriseerd. U kunt API-sleutels of -rollen voor deze taak gebruiken. U wordt aangeraden een sleutelloze verbinding te gebruiken via Microsoft Entra ID.

Selecteer het tabblad dat overeenkomt met de verificatiemethode van uw voorkeur. Gebruik dezelfde methode voor alle aanvragen in deze quickstart.

Microsoft Entra ID
API-sleutel

Meld u aan bij Azure Portal en zoek uw zoekservice.
Zoek op de startpagina Overzicht de URL. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.
Volg de stappen in de quickstart zonder sleutel om uw Microsoft Entra-token op te halen.

U krijgt het token wanneer u de az account get-access-token opdracht uitvoert in stap 3 van de vorige quickstart.
```
az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
```

Meld u aan bij Azure Portal en zoek uw zoekservice.
Zoek op de startpagina Overzicht de URL. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.
Selecteer Instellingensleutels>. API-sleutelsof Beide moeten zijn ingeschakeld. Beheerders-API-sleutels worden gebruikt om objecten toe te voegen, te wijzigen en te verwijderen. Er zijn twee uitwisselbare beheerderssleutels. Kopieer een van beide.

Het codebestand maken of downloaden

U gebruikt een .rest of .http bestand om alle aanvragen in deze quickstart uit te voeren. U kunt het REST-bestand met de code voor deze quickstart downloaden of u kunt een nieuw bestand maken in Visual Studio Code en de code ernaar kopiëren.

Maak in Visual Studio Code een nieuw bestand met een .rest of .http bestandsextensie. Bijvoorbeeld: az-search-vector-quickstart.rest. Kopieer en plak de onbewerkte inhoud van het bestand Azure-Samples/azure-search-rest-samples/blob/main/Quickstart-vectors/az-search-vector-quickstart.rest in dit nieuwe bestand.
Vervang boven aan het bestand de tijdelijke aanduidingswaarde voor @baseUrl de URL van uw zoekservice. Zie de sectie Resourcegegevens ophalen voor instructies over het vinden van de URL van uw zoekservice.
```
@baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
```
Vervang boven aan het bestand de tijdelijke aanduidingswaarde voor verificatie. Zie de sectie Resourcegegevens ophalen voor instructies over het ophalen van uw Microsoft Entra-token of API-sleutel.

Voor de aanbevolen sleutelloze verificatie via Microsoft Entra ID moet u vervangen door @apiKey de @token variabele.
```
@token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
```
Als u liever een API-sleutel gebruikt, vervangt u deze door @apiKey de sleutel die u hebt gekopieerd uit Azure Portal.
```
@apiKey = PUT-YOUR-ADMIN-KEY-HERE
```
Voor de aanbevolen sleutelloze verificatie via Microsoft Entra-id moet u vervangen door api-key: {{apiKey}}Authorization: Bearer {{token}} in de aanvraagheaders. Vervang alle exemplaren die api-key: {{apiKey}} u in het bestand vindt.

Een vectorindex maken

U gebruikt de REST API voor index maken om een vectorindex te maken en de fysieke gegevensstructuren in uw zoekservice in te stellen.

Het indexschema in dit voorbeeld is georganiseerd rond hotelinhoud. Voorbeeldgegevens bestaan uit vector- en niet-vectornamen en beschrijvingen van fictieve hotels. Dit schema bevat configuraties voor vectorindexering en query's en voor semantische classificatie.

Open in Visual Studio Code het az-search-vector-quickstart.rest bestand dat u eerder hebt gemaakt.

Zoek het ### Create a new index codeblok in het bestand. Dit blok bevat de aanvraag voor het maken van de hotels-vector-quickstart index in uw zoekservice.

### 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" }
                    ]
                }
            }
        ]
    }
}

Selecteer Verzoek verzenden. U moet een HTTP/1.1 201 Created antwoord hebben.

De hoofdtekst van het antwoord moet de JSON-weergave van het indexschema bevatten.

{
    "@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"
            }
            ]
        }
        }
    ]
    }
}

Belangrijke punten over de CREATE Index REST API:

De fields verzameling bevat een vereist sleutelveld en tekst- en vectorvelden (zoals Description en DescriptionVector) voor tekst- en vectorzoekopdrachten. Door vectorvelden en niet-vectorvelden in dezelfde index samen te stellen, kunnen hybride query's worden uitgevoerd. U kunt bijvoorbeeld filters, tekstzoekopdrachten combineren met semantische rangschikking en vectoren in één querybewerking.
Vectorvelden moeten met dimensions en vectorSearchProfile eigenschappen zijntype: Collection(Edm.Single).
De vectorSearch sectie is een matrix met configuraties en profielen van het dichtstbijzijnde buuralgoritmen. Ondersteunde algoritmen omvatten hiërarchische bevaarbare kleine wereld en uitgebreide k-dichtstbijzijnde buren. Zie Relevantiescore in vectorzoekopdrachten voor meer informatie.
Met de (optionele) semantic configuratie kunnen zoekresultaten opnieuw worden gerankt. U kunt resultaten opnieuw rangverkennen in query's van het type semantic voor tekenreeksvelden die zijn opgegeven in de configuratie. Zie het overzicht van Semantische classificaties voor meer informatie.

Documenten uploaden

Het maken en laden van de index zijn afzonderlijke stappen. U hebt het indexschema in de vorige stap gemaakt. Nu moet u documenten in de index laden.

In Azure AI Search bevat de index alle doorzoekbare gegevens en query's die worden uitgevoerd op de zoekservice. Voor REST-aanroepen worden de gegevens verstrekt als JSON-documenten. Gebruik Documenten- INDEX REST API voor deze taak. De URI wordt uitgebreid om de docs verzameling en de index bewerking op te nemen.

Open in Visual Studio Code het az-search-vector-quickstart.rest bestand dat u eerder hebt gemaakt.

Zoek het ### Upload documents codeblok in het bestand. Dit blok bevat de aanvraag voor het uploaden van documenten naar de hotels-vector-quickstart index in uw zoekservice.

### 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"
            ]
        }
    ]
}

Belangrijk

De code in dit voorbeeld kan niet worden uitgevoerd. Er worden verschillende tekens of regels verwijderd om kortheid te krijgen. Gebruik de code in het az-search-vector-quickstart.rest bestand om de aanvraag uit te voeren.

Selecteer Verzoek verzenden. U moet een HTTP/1.1 200 OK antwoord hebben. De hoofdtekst van het antwoord moet de JSON-weergave van de zoekdocumenten bevatten.

Belangrijke punten over de documenten - INDEX REST API-aanvraag :

Documenten in de nettolading bestaan uit velden die zijn gedefinieerd in het indexschema.
Vectorvelden bevatten drijvendekommawaarden. Het kenmerk Dimensies heeft minimaal 2 en een maximum van 3072 drijvendekommawaarden. In deze quickstart wordt het dimensiekenmerk ingesteld op 1536, omdat dit de grootte is van insluitingen die worden gegenereerd door het Azure OpenAI-model voor tekst-insluiten-ada-002 .

Query's uitvoeren

Nu documenten zijn geladen, kunt u vectorquery's voor deze query's uitgeven met behulp van Documenten - Zoekpost (REST).

In de volgende secties voeren we query's uit op de hotels-vector-quickstart index. De query's zijn onder andere:

Zoeken met één vector
Zoeken met één vector met filter
Hybride zoekopdracht
Semantische hybride zoekopdracht met filter

De voorbeeldvectorquery's zijn gebaseerd op twee tekenreeksen:

Zoekreeks: historic hotel walk to restaurants and shopping
Vectorquerytekenreeks (gevectoriseerd in een wiskundige weergave): classic lodging near running trails, eateries, retail

De vectorquerytekenreeks is semantisch vergelijkbaar met de zoekreeks, maar bevat termen die niet bestaan in de zoekindex. Als u een trefwoord zoekt classic lodging near running trails, eateries, retail, zijn de resultaten nul. We gebruiken dit voorbeeld om te laten zien hoe u relevante resultaten kunt krijgen, zelfs als er geen overeenkomende termen zijn.

Zoeken met één vector

Open in Visual Studio Code het az-search-vector-quickstart.rest bestand dat u eerder hebt gemaakt.
Zoek het ### Run a single vector query codeblok in het bestand. Dit blok bevat de aanvraag om een query uit te voeren op de zoekindex.
```
### 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
            }
        ]
    }
```
Deze vectorquery wordt ingekort voor kortheid. De vectorQueries.vector bevat de vectortekst van de query-invoer, fields bepaalt welke vectorvelden worden doorzocht en k geeft het aantal dichtstbijzijnde buren op dat moet worden geretourneerd.

De vectorquerytekenreeks is classic lodging near running trails, eateries, retail, die wordt gevectoriseerd in 1536 insluitingen voor deze query.

Belangrijk

De code in dit voorbeeld kan niet worden uitgevoerd. Er worden verschillende tekens of regels verwijderd om kortheid te krijgen. Gebruik de code in het az-search-vector-quickstart.rest bestand om de aanvraag uit te voeren.
Selecteer Verzoek verzenden. U moet een HTTP/1.1 200 OK antwoord hebben. De hoofdtekst van het antwoord moet de JSON-weergave van de zoekresultaten bevatten.

Het antwoord voor het vectorequivalent van classic lodging near running trails, eateries, retail bevat zeven resultaten. Elk resultaat bevat een zoekscore en de velden die worden vermeld in select. In een zoekopdracht naar overeenkomsten bevat k het antwoord altijd resultaten die zijn gerangschikt op de waarde-overeenkomstscore.

{
  "@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"
    }
  ]
}

Zoeken met één vector met filter

U kunt filters toevoegen, maar de filters worden toegepast op de niet-ctorinhoud in uw index. In dit voorbeeld is het filter van toepassing op het Tags veld om alle hotels te filteren die geen gratis Wi-Fi bieden.

Open in Visual Studio Code het az-search-vector-quickstart.rest bestand dat u eerder hebt gemaakt.

Zoek het ### Run a vector query with a filter codeblok in het bestand. Dit blok bevat de aanvraag om een query uit te voeren op de zoekindex.

### 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
        },
    ]
}

Belangrijk

Selecteer Verzoek verzenden. U moet een HTTP/1.1 200 OK antwoord hebben. De hoofdtekst van het antwoord moet de JSON-weergave van de zoekresultaten bevatten.

De query was hetzelfde als het vorige voorbeeld van een enkele vectorzoekopdracht, maar het bevat een uitsluitingsfilter na verwerking en retourneert alleen de drie hotels met gratis Wi-Fi.

{
  "@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"
      ]
    }
  ]
}

Hybride zoekopdracht

Hybride zoekopdrachten bestaan uit trefwoordquery's en vectorquery's in één zoekaanvraag. In dit voorbeeld wordt de vectorquery en de zoekopdracht in volledige tekst gelijktijdig uitgevoerd:

Zoekreeks: historic hotel walk to restaurants and shopping
Vectorquerytekenreeks (gevectoriseerd in een wiskundige weergave): classic lodging near running trails, eateries, retail

Open in Visual Studio Code het az-search-vector-quickstart.rest bestand dat u eerder hebt gemaakt.

Zoek het ### Run a hybrid query codeblok in het bestand. Dit blok bevat de aanvraag om een query uit te voeren op de zoekindex.

### 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
        }
    ]
}

Belangrijk

Selecteer Verzoek verzenden. U moet een HTTP/1.1 200 OK antwoord hebben. De hoofdtekst van het antwoord moet de JSON-weergave van de zoekresultaten bevatten.

Omdat dit een hybride query is, worden de resultaten gerangschikt op Wederzijdse Rank Fusion (RRF). RRF evalueert zoekscores van meerdere zoekresultaten, neemt de inverse en voegt vervolgens de gecombineerde resultaten samen en sorteert deze. Het top aantal resultaten wordt geretourneerd.

Bekijk het antwoord:

{
    "@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."
        }
    ]
}

Omdat RRF resultaten samenvoegt, helpt het om de invoer te controleren. De volgende resultaten zijn alleen afkomstig van de volledige-tekstquery. De top twee resultaten zijn Subliem Palace Hotel en History Lion Resort. Het Sublieme Palace Hotel heeft een sterkere BM25 relevantie score.

{
    "@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"
},

In de vectorquery, die gebruikmaakt van HNSW voor het vinden van overeenkomsten, daalt het Sublieme Palace Hotel naar de vierde positie. Historic Lion, die tweede was in de zoekopdracht in volledige tekst en derde in de vectorzoekopdracht, ondervindt niet hetzelfde fluctuatiebereik, dus het lijkt een topmatch in een gehomogeniseerde resultatenset.

"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"
    }
]

Semantische hybride zoekopdracht met een filter

Dit is de laatste query in de verzameling. Deze hybride query met semantische classificatie wordt gefilterd om alleen de hotels binnen een straal van 500 kilometer van Washington D.C weer te geven. U kunt instellen vectorFilterMode op null, wat gelijk is aan de standaardwaarde (preFilter voor nieuwere indexen en postFilter voor oudere indexen).

Open in Visual Studio Code het az-search-vector-quickstart.rest bestand dat u eerder hebt gemaakt.

Zoek het ### Run a hybrid query with semantic reranking codeblok in het bestand. Dit blok bevat de aanvraag om een query uit te voeren op de zoekindex.

### 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
        }
    ]
}

Belangrijk

Selecteer Verzoek verzenden. U moet een HTTP/1.1 200 OK antwoord hebben. De hoofdtekst van het antwoord moet de JSON-weergave van de zoekresultaten bevatten.

Bekijk het antwoord. Het antwoord is drie hotels, die worden gefilterd op locatie en gefaceteerd door StateProvince en semantisch opnieuw zijn gerangschikt om resultaten te promoten die het dichtst bij de zoektekenreeksquery (historic hotel walk to restaurants and shopping) liggen.

Het Swirling Currents Hotel gaat nu naar de bovenste plek. Zonder semantische rangschikking is Nordick's Valley Motel nummer één. Met semantische rangschikking herkennen de machinebegripmodellen die historic van toepassing zijn op "hotel, op loopafstand van dineren (restaurants) en winkelen."

{
  "@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
      }
    }
  ]
}

Belangrijke punten over documenten - Zoekpost REST API:

Vectorzoekopdrachten worden opgegeven via de vectors.value eigenschap. Trefwoorden zoeken wordt opgegeven via de search eigenschap.
In een hybride zoekopdracht kunt u vectorzoekopdrachten integreren met zoeken in volledige tekst over trefwoorden. Filters, spellingcontrole en semantische classificatie zijn alleen van toepassing op tekstuele inhoud en niet op vectoren. In deze laatste query is er geen semantisch answer omdat het systeem er geen heeft geproduceerd die voldoende sterk was.
Werkelijke resultaten bevatten meer details, inclusief semantische bijschriften en markeringen. De resultaten zijn gewijzigd voor leesbaarheid. Als u de volledige structuur van het antwoord wilt ophalen, voert u de aanvraag uit in de REST-client.

Opschonen

Wanneer u in uw eigen abonnement werkt, is het een goed idee om aan het einde van een project te bepalen of u de gemaakte resources nog nodig hebt. Resources die actief blijven, kunnen u geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

U kunt resources vinden en beheren in Azure Portal met behulp van de koppeling Alle resources of resourcegroepen in het meest linkse deelvenster.

Als u de zoekservice wilt behouden, maar de index en documenten wilt verwijderen, kunt u de DELETE opdracht in de REST-client gebruiken. Met deze opdracht (aan het einde van het az-search-vector-quickstart.rest bestand) wordt de hotels-vector-quickstart index verwijderd:

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

Volgende stappen

Als volgende stap raden we u aan om te leren hoe u REST API-aanroepen zonder API-sleutels kunt aanroepen.

Mogelijk wilt u ook de democode voor Python, C# of JavaScript bekijken.

Delen via

Quickstart: Vector search by using REST

Vereisten

Resourcegegevens ophalen

Het codebestand maken of downloaden

Een vectorindex maken

Documenten uploaden

Query's uitvoeren

Zoeken met één vector

Zoeken met één vector met filter

Hybride zoekopdracht

Semantische hybride zoekopdracht met een filter

Opschonen

Volgende stappen

Feedback

Aanvullende resources