Freigeben über

Schnellstart: Vektorsuche mit REST-APIs

  • Artikel

Erfahren Sie, wie Sie die Search-REST-APIs zum Erstellen, Laden und Abfragen von Vektoren in Azure AI Search verwenden.

In der Azure KI-Suche verfügt ein Vektorspeicher über ein Indexschema, das Vektor- und Nichtvektorfelder definiert, eine Vektorsuchkonfiguration für Algorithmen, die den Einbettungsraum erstellen, und Einstellungen für Vektorfelddefinitionen, die in Abfrageanforderungen verwendet werden. Die REST-API zum Erstellen eines Index erstellt den Vektorspeicher.

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

Hinweis

In diesem Schnellstart wird der Vektorisierungsschritt weggelassen, und Einbettungen werden in Beispieldokumenten bereitgestellt. Wenn Sie die integrierte Datensegmentierung und Vektorisierung für Ihren eigenen Inhalt hinzufügen möchten, testen Sie den Assistenten zum Importieren und Vektorisieren von Daten für eine exemplarische End-to-End-Vorgehensweise.

Voraussetzungen

Abrufen von Ressourceninformationen

Anforderungen an den Suchendpunkt müssen authentifiziert und autorisiert werden. Sie können für diese Aufgabe API-Schlüssel oder Rollen verwenden. Wir empfehlen, eine schlüssellose Verbindung über Microsoft Entra ID zu verwenden.

Wählen Sie die Registerkarte aus, die Ihrer bevorzugten Authentifizierungsmethode entspricht. Verwenden Sie dieselbe Methode für alle Anforderungen in dieser Schnellstartanleitung.

  1. Melden Sie sich beim Azure-Portal an, und finden Sie Ihren Suchdienst.

  2. Sie finden die URL auf der Startseite Übersicht. Ein Beispiel für einen Endpunkt ist https://mydemo.search.windows.net.

    Screenshot der URL-Eigenschaft auf der Übersichtsseite

  3. Führen Sie die Schritte im Schnellstart zum Herstellen einer Verbindung ohne Schlüssel aus, um Ihr Microsoft Entra-Token zu erhalten.

    Sie erhalten das Token, wenn Sie den Befehl az account get-access-token in Schritt 3 der vorherigen Schnellstartanleitung ausführen.

    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

Erstellen oder Herunterladen der Codedatei

Sie verwenden eine .rest- oder .http-Datei, um alle Anforderungen in dieser Schnellstartanleitung auszuführen. Sie können die REST-Datei herunterladen, die den Code für diese Schnellstartanleitung enthält, oder Sie können eine neue Datei in Visual Studio Code erstellen und den Code hineinkopieren.

  1. Erstellen Sie in Visual Studio Code eine neue Datei mit der Erweiterung .rest oder .http. Beispiel: az-search-vector-quickstart.rest. Kopieren Sie den unformatierten Inhalt der Datei Azure-Samples/azure-search-rest-samples/blob/main/Quickstart-vectors/az-search-vector-quickstart.rest in diese neue Datei.

  2. Ersetzen Sie oben in der Datei den Platzhalterwert für @baseUrl durch Ihre Suchdienst-URL. Anweisungen zum Suchen Ihrer Suchdienst-URL finden Sie im Abschnitt Abrufen von Ressourceninformationen.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE

  3. Ersetzen Sie oben in der Datei den Platzhalterwert für die Authentifizierung. Anweisungen zum Abrufen Ihres Microsoft Entra-Tokens oder API-Schlüssels finden Sie im Abschnitt Abrufen von Ressourceninformationen.

    Für die empfohlene schlüssellose Authentifizierung mit Microsoft Entra ID müssen Sie @apiKey durch die @token-Variable ersetzen.

    @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE

    Wenn Sie lieber einen API-Schlüssel verwenden möchten, ersetzen Sie @apiKey durch den Schlüssel, den Sie aus dem Azure-Portal kopiert haben.

    @apiKey = PUT-YOUR-ADMIN-KEY-HERE

  4. Für die empfohlene schlüssellose Authentifizierung mit Microsoft Entra ID müssen Sie api-key: {{apiKey}} durch Authorization: Bearer {{token}} in den Anforderungsheadern ersetzen. Ersetzen Sie alle Instanzen von api-key: {{apiKey}}, die Sie in der Datei finden.

Erstellen eines Vektorindexes

Sie verwenden die REST-API Create Index, um einen Vektorindex zu erstellen und die physischen Datenstrukturen in Ihrem Suchdienst einzurichten.

Das Indexschema in diesem Beispiel ist den Hotelinhalten entsprechend organisiert. Die Beispieldaten bestehen aus Vektor- und Nichtvektornamen und Beschreibungen von fiktiven Hotels. Dieses Schema enthält Konfigurationen für die Vektorindizierung und Abfragen sowie für die semantische Rangfolge.

  1. Öffnen Sie in Visual Studio Code die az-search-vector-quickstart.rest-Datei, die Sie zuvor erstellt haben.

  2. Suchen Sie den ### Create a new index-Codeblock in der Datei. Dieser Block enthält die Anforderung zum Erstellen des hotels-vector-quickstart-Index für Ihren Suchdienst.

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

  3. Klicken Sie auf Anforderung senden. Sie sollten eine HTTP/1.1 201 Created-Antwort erhalten.

Der Antworttext sollte die JSON-Darstellung des Indexschemas enthalten.

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

Wichtige Punkte zur Create Index-REST-API:

  • Die Sammlung fields enthält ein erforderliches Schlüsselfeld sowie Text und Vektorfelder (z. B. Description und DescriptionVector) für die Text- und Vektorsuche. Die gemeinsame Zuordnung von Vektorfeldern und Nicht-Vektorfeldern in demselben Index ermöglicht Hybridabfragen. Beispielsweise können Sie Filter, Stichwortsuche mit semantischer Rangfolge und Vektoren in einem einzelnen Abfragevorgang kombinieren.

  • Vektorfelder müssen type: Collection(Edm.Single) mit den Eigenschaften dimensions und vectorSearchProfile sein.

  • Der Abschnitt vectorSearch umfasst ein Array von ANN-Algorithmuskonfigurationen (Approximate Nearest Neighbors) und Profilen. Zu den unterstützten Algorithmen gehören der HNSW- (Hierarchical Navigable Small World) und der erschöpfende k-nächste-Nachbarn-Algorithmus (k-NN). Weitere Informationen finden Sie unter Relevanzbewertung in der Vektorsuche.

  • Die (optionale) semantic-Konfiguration ermöglicht die Neubewertung der Rangfolge von Suchergebnissen. Sie können eine Neubewertung der Rangfolge für Ergebnisse in Abfragen vom Typ semantic für Zeichenfolgenfelder durchführen, die in der Konfiguration angegeben sind. Weitere Informationen finden Sie unter Übersicht über die semantischen Bewertung.

Hochladen von Dokumenten

Das Erstellen und das Laden des Index erfolgt in zwei separaten Schritten. Sie haben das Indexschema im vorherigen Schritt erstellt. Jetzt müssen Sie Dokumente in den Index laden.

In Azure KI-Suche enthält der Index alle durchsuchbaren Daten und Abfragen, die im Suchdienst ausgeführt werden. Für REST-Aufrufe werden die Daten als JSON-Dokumente bereitgestellt. Verwenden Sie für diese Aufgabe die REST-API Dokumente – Index. Der URI wird um die docs-Sammlung und den index-Vorgang erweitert.

  1. Öffnen Sie in Visual Studio Code die az-search-vector-quickstart.rest-Datei, die Sie zuvor erstellt haben.

  2. Suchen Sie den ### Upload documents-Codeblock in der Datei. Dieser Block enthält die Anforderung zum Hochladen von Dokumenten in den hotels-vector-quickstart-Index in Ihrem Suchdienst.

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

    Wichtig

    Der Code in diesem Beispiel kann nicht ausgeführt werden. Mehrere Zeichen oder Zeilen werden aus Platzgründen entfernt. Verwenden Sie den Code in Ihrer az-search-vector-quickstart.rest-Datei, um die Anforderung auszuführen.

  3. Klicken Sie auf Anforderung senden. Sie sollten eine HTTP/1.1 200 OK-Antwort erhalten. Der Antworttext sollte die JSON-Darstellung der Suchdokumente enthalten.

Wichtige Punkte zur Anforderung Documents - Index REST API:

  • Dokumente in der Nutzlast bestehen aus Feldern, die im Indexschema definiert sind.

  • Vektorfelder enthalten Gleitkommawerte. Das dimensions-Attribut weist mindestens 2 und höchstens 3.072 Gleitkommawerte auf. In dieser Schnellstartanleitung wird das Dimensionsattribut auf 1.536 festgelegt, weil dies die Größe der Einbettungen ist, die vom Azure OpenAI-Modell text-embedding-ada-002 generiert werden.

Ausführen von Abfragen

Nachdem Dokumente geladen worden sind, können Sie Vektorabfragen mithilfe von POST-REST-API für die Dokumentsuche ausstellen.

In den nächsten Abschnitten führen wir Abfragen für den hotels-vector-quickstart-Index aus. Zu den Abfragen gehören:

Die Beispielvektorabfragen basieren auf zwei Zeichenfolgen:

  • Suchzeichenfolge: historic hotel walk to restaurants and shopping
  • Vektorabfrage-Zeichenfolge (in eine mathematische Darstellung vektorisiert): classic lodging near running trails, eateries, retail

Die Vektorabfrage-Zeichenfolge ähnelt semantisch der Suchzeichenfolge, enthält jedoch Begriffe, die nicht im Suchindex enthalten sind. Wenn Sie eine Schlüsselwortsuche nach classic lodging near running trails, eateries, retail durchführen, erhalten Sie das Ergebnis null. Wir verwenden dieses Beispiel, um zu zeigen, wie Sie auch dann relevante Ergebnisse erhalten können, wenn keine übereinstimmenden Begriffe vorhanden sind.

  1. Öffnen Sie in Visual Studio Code die az-search-vector-quickstart.rest-Datei, die Sie zuvor erstellt haben.

  2. Suchen Sie den ### Run a single vector query-Codeblock in der Datei. Dieser Block enthält die Anforderung zum Abfragen des Suchindexes.

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

    Diese Vektorabfrage wird aus Platzgründen gekürzt. vectorQueries.vector enthält den vektorisierten Text der Abfrageeingabe, fields bestimmt, welche Vektorfelder durchsucht werden, und k gibt die Anzahl der nächsten Nachbarelemente an, die zurückgegeben werden sollen.

    Die Vektorabfragezeichenfolge lautet classic lodging near running trails, eateries, retail und wird für diese Abfrage in 1.536 Einbettungen vektorisiert.

    Wichtig

    Der Code in diesem Beispiel kann nicht ausgeführt werden. Mehrere Zeichen oder Zeilen werden aus Platzgründen entfernt. Verwenden Sie den Code in Ihrer az-search-vector-quickstart.rest-Datei, um die Anforderung auszuführen.

  3. Klicken Sie auf Anforderung senden. Sie sollten eine HTTP/1.1 200 OK-Antwort erhalten. Der Antworttext sollte die JSON-Darstellung der Suchergebnisse enthalten.

Die Antwort für das Vektoräquivalent von classic lodging near running trails, eateries, retail enthält sieben Ergebnisse. Jedes Ergebnis stellt einen Suchscore und die in select aufgeführten Felder bereit. Bei einer Ähnlichkeitssuche enthält die Antwort immer k Ergebnisse, die nach der Wertähnlichkeitsscore sortiert sind.

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

Einzelvektorsuche mit Filter

Sie können Filter hinzufügen, aber die Filter werden auf die Nicht-Vektorinhalte in Ihrem Index angewendet. In diesem Beispiel gilt der Filter für das Feld Tags und filtert alle Hotels heraus, die kein kostenloses WLAN bereitstellen.

  1. Öffnen Sie in Visual Studio Code die az-search-vector-quickstart.rest-Datei, die Sie zuvor erstellt haben.

  2. Suchen Sie den ### Run a vector query with a filter-Codeblock in der Datei. Dieser Block enthält die Anforderung zum Abfragen des Suchindexes.

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

    Wichtig

    Der Code in diesem Beispiel kann nicht ausgeführt werden. Mehrere Zeichen oder Zeilen werden aus Platzgründen entfernt. Verwenden Sie den Code in Ihrer az-search-vector-quickstart.rest-Datei, um die Anforderung auszuführen.

  3. Klicken Sie auf Anforderung senden. Sie sollten eine HTTP/1.1 200 OK-Antwort erhalten. Der Antworttext sollte die JSON-Darstellung der Suchergebnisse enthalten.

Die Abfrage ist dieselbe wie im vorigen Beispiel für die Einzelvektorsuche, enthält jedoch einen Ausschlussfilter für die Nachbearbeitung und gibt nur die drei Hotels zurück, die über kostenloses WLAN verfügen.

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

Die Hybridsuche besteht aus Stichwortabfragen und Vektorabfragen in einer einzelnen Suchanforderung. In diesem Beispiel werden die Vektorabfrage und die Volltextsuche gleichzeitig ausgeführt:

  • Suchzeichenfolge: historic hotel walk to restaurants and shopping
  • Vektorabfrage-Zeichenfolge (in eine mathematische Darstellung vektorisiert): classic lodging near running trails, eateries, retail

  1. Öffnen Sie in Visual Studio Code die az-search-vector-quickstart.rest-Datei, die Sie zuvor erstellt haben.

  2. Suchen Sie den ### Run a hybrid query-Codeblock in der Datei. Dieser Block enthält die Anforderung zum Abfragen des Suchindexes.

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

    Wichtig

    Der Code in diesem Beispiel kann nicht ausgeführt werden. Mehrere Zeichen oder Zeilen werden aus Platzgründen entfernt. Verwenden Sie den Code in Ihrer az-search-vector-quickstart.rest-Datei, um die Anforderung auszuführen.

  3. Klicken Sie auf Anforderung senden. Sie sollten eine HTTP/1.1 200 OK-Antwort erhalten. Der Antworttext sollte die JSON-Darstellung der Suchergebnisse enthalten.

Da es sich um eine Hybridabfrage handelt, werden die Ergebnisse nach der Methode Reciprocal Rank Fusion (RRF) bewertet. RRF wertet Suchscores aus verschiedenen Suchergebnissen aus, nimmt die Umkehrung vor und führt dann die kombinierten Ergebnisse zusammen und sortiert sie. Die top-Anzahl der Ergebnisse wird zurückgegeben.

Überprüfen Sie die Antwort:

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

Da RRF Ergebnisse zusammenführt, können die Eingaben leichter überprüft werden. Die folgenden Ergebnisse stammen nur aus der Volltextabfrage. Die beiden besten Ergebnisse lauten „Sublime Palace Hotel“ und „History Lion Resort“. Das Sublime Palace Hotel hat eine höhere BM25-Relevanzbewertung.

{
    "@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 der reinen Vektorabfrage, in der HNSW für die Suche nach Übereinstimmungen verwendet wird, fällt das Sublime Palace Hotel auf die vierte Position zurück. Das Historic Lion Resort, das bei der Volltextsuche auf Platz zwei und bei der Vektorsuche auf Platz drei lag, weist nicht dieselbe Schwankungsbreite auf und erscheint daher in einem homogenisierten Resultset als Spitzenreiter.

"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 Hybridsuche mit einem Filter

Dies ist die letzte Abfrage in der Sammlung. Diese Hybridabfrage mit semantischer Bewertung wird gefiltert, um nur die Hotels innerhalb eines Radius von 500 Kilometern von Washington D.C anzuzeigen. Sie können vectorFilterMode auf NULL festlegen, was der Standardeinstellung entspricht (preFilter für neuere Indizes und postFilter für ältere).

  1. Öffnen Sie in Visual Studio Code die az-search-vector-quickstart.rest-Datei, die Sie zuvor erstellt haben.

  2. Suchen Sie den ### Run a hybrid query with semantic reranking-Codeblock in der Datei. Dieser Block enthält die Anforderung zum Abfragen des Suchindexes.

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

    Wichtig

    Der Code in diesem Beispiel kann nicht ausgeführt werden. Mehrere Zeichen oder Zeilen werden aus Platzgründen entfernt. Verwenden Sie den Code in Ihrer az-search-vector-quickstart.rest-Datei, um die Anforderung auszuführen.

  3. Klicken Sie auf Anforderung senden. Sie sollten eine HTTP/1.1 200 OK-Antwort erhalten. Der Antworttext sollte die JSON-Darstellung der Suchergebnisse enthalten.

Überprüfen Sie die Antwort. Die Antwort enthält drei Hotels, die nach Standort gefiltert, nachStateProvince facettiert und semantisch neu bewertet werden, um Ergebnisse höherzustufen, die der Suchzeichenfolgenabfrage (historic hotel walk to restaurants and shopping) am nächsten kommen.

Das Swirling Currents Hotel ist jetzt an der Spitze. Ohne semantische Rangfolge ist Nordick‘s Valley Motel die Nummer eins. Durch die semantische Bewertung erkennen die Maschinenverständnismodelle, dass historic für „Hotel, in fußläufiger Entfernung zu Restaurants und Einkaufsmöglichkeiten" gilt.

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

Wichtige Punkte zur Documents - Search Post-REST-API:

  • Die Vektorsuche wird durch die Eigenschaft vectors.value angegeben. Die Schlüsselwortsuche wird durch die Eigenschaft search angegeben.

  • Bei einer Hybridsuche können Sie die Vektorsuche über Stichwörter in die Volltextsuche integrieren. Filter, Rechtschreibprüfung und semantische Rangfolge betreffen nur Textinhalte, nicht Vektoren. In dieser abschließenden Abfrage gibt es keinen semantischen Wert für answer, weil das System keinen ausreichend starken generiert hat.

  • Die eigentlichen Ergebnisse umfassen weitere Details, einschließlich semantischer Beschriftungen und Hervorhebungen. Die Ergebnisse wurden zur besseren Lesbarkeit abgeändert. Führen Sie die Anforderung im REST-Client aus, um die vollständige Struktur der Antwort zu erhalten.

Bereinigen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, sollten Sie sich am Ende eines Projekts überlegen, ob Sie die erstellten Ressourcen noch benötigen. Ressourcen, die weiterhin ausgeführt werden, können Sie Geld kosten. Sie können einzelne Ressourcen oder die gesamte Ressourcengruppe mit allen darin enthaltenen Ressourcen löschen.

Ressourcen können im Azure-Portal über den Link Alle Ressourcen oder Ressourcengruppen im linken Navigationsbereich gesucht und verwaltet werden.

Wenn Sie den Suchdienst beibehalten, aber den Index und die Dokumente löschen möchten, können Sie den Befehl DELETE im REST-Client verwenden. Mit diesem Befehl (am Ende der az-search-vector-quickstart.rest-Datei) wird der hotels-vector-quickstart-Index gelöscht:

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

Nächste Schritte

Als nächsten Schritt empfehlen wir Ihnen, sich mit dem Aufrufen von REST-API-Aufrufen ohne API-Schlüssel vertraut zu machen.

Sie sollten sich auch den Democode für Python, C# oder JavaScript genauer ansehen.