Erstellen einer Vektorabfrage in Azure KI-Suche

Wenn Sie über einen vectorindex in Azure KI-Suche verfügen, wird in diesem Artikel erläutert, wie Sie:

In diesem Artikel wird REST zur Veranschaulichung verwendet. Nachdem Sie den grundlegenden Workflow verstanden haben, fahren Sie mit den Azure SDK Codebeispielen in den azure-search-vector-samples Repo fort, das End-to-End-Lösungen bereitstellt, die Vektorabfragen enthalten.

Sie können auch Search Explorer im Azure-Portal verwenden.

Voraussetzungen

Konvertieren einer Abfragezeichenfolgeneingabe in einen Vektor

Um ein Vektorfeld abzufragen, muss die Abfrage selbst ein Vektor sein.

Ein Ansatz zum Konvertieren der Textabfragezeichenfolge eines Benutzers in seine Vektordarstellung besteht darin, eine Einbettungsbibliothek oder API in Ihrem Anwendungscode aufzurufen. Verwenden Sie als bewährte Methode immer dieselben Einbettungsmodelle, die zum Generieren von Einbettungen in die Quelldokumente verwendet werden. Im Repository azure-search-vector-samples finden Sie Codebeispiele, die zeigen, wie man Einbettungen erzeugt.

Ein zweiter Ansatz besteht darin, die integrierte Vektorisierung zu nutzen, die jetzt allgemein verfügbar ist, damit Azure KI-Suche Ihre Eingaben und Ausgaben der Abfragevektorisierung verarbeitet.

Hier ist ein REST-API-Beispiel für eine Abfragezeichenfolge, die an eine Bereitstellung eines Azure OpenAI-Einbettungsmodells gesendet wird:

POST https://{{openai-service-name}}.openai.azure.com/openai/deployments/{{openai-deployment-name}}/embeddings?api-version={{openai-api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "input": "what azure services support generative AI'"
}

Die erwartete Antwort ist 202 für eine erfolgreiche Abfrage des bereitgestellten Modells.

Das embedding Feld im Textkörper der Antwort ist die Vektordarstellung der Abfragezeichenfolge input. Zu Testzwecken würden Sie den Wert des embedding Arrays vectorQueries.vector in eine Abfrageanforderung kopieren und dabei die syntax verwenden, die in den nächsten Abschnitten gezeigt wird.

Die tatsächliche Antwort auf diesen POST-Aufruf an das bereitgestellte Modell umfasst 1.536 Einbettungen. Aus Gründen der Lesbarkeit zeigt dieses Beispiel nur die ersten Vektoren an.

{
    "object": "list",
    "data": [
        {
            "object": "embedding",
            "index": 0,
            "embedding": [
                -0.009171937,
                0.018715322,
                ...
                -0.0016804502
            ]
        }
    ],
    "model": "ada",
    "usage": {
        "prompt_tokens": 7,
        "total_tokens": 7
    }
}

Bei diesem Ansatz ist Ihr Anwendungscode für die Verbindung mit einem Modell, das Generieren von Einbettungen und die Behandlung der Antwort verantwortlich.

Vektorabfrageanforderung

In diesem Abschnitt wird die grundlegende Struktur einer Vektorabfrage veranschaulicht. Sie können das Azure Portal, REST-APIs oder die Azure SDKs verwenden, um eine Vektorabfrage zu formulieren.

Wenn Sie von 2023-07-01-preview migrieren, gibt es einschneidende Änderungen. Weitere Informationen finden Sie unter Upgrade auf die neueste REST-API.

Die stabile Version unterstützt:

  • vectorQueries ist das Konstrukt für die Vektorsuche.
  • vectorQueries.kind auf vector gesetzt für ein Vektorarray oder auf text gesetzt, wenn es sich bei der Eingabe um eine Zeichenfolge handelt und wenn Sie einen Vektorizer verwenden.
  • vectorQueries.vector ist die Abfrage (eine Vektordarstellung von Text oder bild).
  • vectorQueries.exhaustive (optional) ruft vollständige KNN zur Abfragezeit auf, auch wenn das Feld für HNSW indiziert ist.
  • vectorQueries.fields (optional) zielt auf bestimmte Felder für die Abfrageausführung ab (bis zu 10 pro Abfrage).
  • vectorQueries.weight (optional) gibt die relative Gewichtung der einzelnen Vektorabfragen an, die in Suchvorgängen enthalten sind. Weitere Informationen finden Sie unter Vector Weighting.
  • vectorQueries.k ist die Anzahl der zurückzugebenden Übereinstimmungen.

Im folgenden Beispiel ist der Vektor eine Darstellung dieser Zeichenfolge: "what Azure services support full text search". Die Abfrage zielt auf das contentVector Feld ab und gibt Ergebnisse zurück k . Der tatsächliche Vektor verfügt über 1.536 Einbettungen, die in diesem Beispiel zur Lesbarkeit gekürzt werden.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2026-04-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector",
            "weight": 0.5,
            "k": 5
        }
    ]
}

Vektorabfrageantwort

In Azure KI-Suche bestehen Abfrageantworten standardmäßig aus allen retrievable Feldern. Es ist jedoch üblich, Suchergebnisse auf eine Teilmenge von retrievable Feldern zu beschränken, indem sie sie in einer select Anweisung auflisten.

Berücksichtigen Sie in einer Vektorabfrage sorgfältig, ob Sie Felder in einer Antwort vektorieren müssen. Vektorfelder sind nicht lesbar. Wenn Sie also eine Antwort auf eine Webseite pushen, sollten Sie nicht Vektorfelder auswählen, die das Ergebnis darstellen. Beispielsweise können Sie, wenn die Abfrage gegen contentVector ausgeführt wird, stattdessen content zurückgeben.

Wenn Sie Vektorfelder im Ergebnis verwenden möchten, sehen Sie hier ein Beispiel für die Antwortstruktur. contentVector ist ein Array aus Zeichenfolgen von Einbettungen, die in diesem Beispiel zur besseren Lesbarkeit gekürzt werden. Die Suchbewertung gibt die Relevanz an. Andere Nichtvectorfelder sind für den Kontext enthalten.

{
    "@odata.count": 3,
    "value": [
        {
            "@search.score": 0.80025613,
            "title": "Azure Search",
            "category": "AI + Machine Learning",
            "contentVector": [
                -0.0018343845,
                0.017952163,
                0.0025753193,
                ...
            ]
        },
        {
            "@search.score": 0.78856903,
            "title": "Azure Application Insights",
            "category": "Management + Governance",
            "contentVector": [
                -0.016821077,
                0.0037742127,
                0.016136652,
                ...
            ]
        },
        {
            "@search.score": 0.78650564,
            "title": "Azure Media Services",
            "category": "Media",
            "contentVector": [
                -0.025449317,
                0.0038463024,
                -0.02488436,
                ...
            ]
        }
    ]
}

Wichtige Punkte:

  • k bestimmt, wie viele nächste Nachbarn-Ergebnisse zurückgegeben werden, in diesem Fall drei. Vektorabfragen geben immer Ergebnisse zurück k , sofern mindestens k Dokumente vorhanden sind, auch wenn einige Dokumente eine schlechte Ähnlichkeit aufweisen. Dies liegt daran, dass der Algorithmus alle k nächsten Nachbarn des Abfragevektors findet.

  • Der Vektorsuchalgorithmus bestimmt die @search.score.

  • Felder in Suchergebnissen sind entweder alle retrievable Felder oder Felder in einer select Klausel. Bei der Ausführung von Vektorabfragen erfolgt der Abgleich allein für Vektordaten. Eine Antwort kann jedoch ein beliebiges retrievable Feld in einem Index enthalten. Da es keine Möglichkeit zum Decodieren eines Vektorfeldergebnisses gibt, ist die Einbeziehung von Nichtvektortextfeldern für ihre lesbaren Werte hilfreich.

Mehrere Vektorfelder

Sie können die vectorQueries.fields Eigenschaft auf mehrere Vektorfelder festlegen. Die Vektorabfrage wird für jedes Vektorfeld ausgeführt, das Sie in der fields Liste angeben. Sie können bis zu 10 Felder angeben.

Stellen Sie beim Abfragen mehrerer Vektorfelder sicher, dass jedes Element Einbettungen aus dem gleichen Einbettungsmodell enthält. Die Abfrage sollte auch aus dem gleichen Einbettungsmodell generiert werden.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2026-04-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector, titleVector",
            "k": 5
        }
    ]
}

Mehrere Vektorabfragen

Die Vektorsuche mit mehreren Abfragen sendet mehrere Abfragen über mehrere Vektorfelder in Ihrem Suchindex. Diese Art von Abfrage wird häufig mit Modellen wie CLIP für die multimodale Suche verwendet, wobei dasselbe Modell sowohl Text als auch Bilder vektorisieren kann.

Das folgende Abfragebeispiel sucht nach Ähnlichkeit in sowohl myImageVector als auch myTextVector, sendet jedoch zwei entsprechende Abfrageeinbettungen, die jeweils parallel ausgeführt werden. Das Ergebnis dieser Abfrage wird mithilfe der reziprokierten Rangfusion (RRF) bewertet.

  • vectorQueries stellt ein Array von Vektorabfragen bereit.
  • vector enthält die Bildvektoren und Textvektoren im Suchindex. Jede Instanz ist eine separate Abfrage.
  • fields Gibt an, welches Vektorfeld als Ziel verwendet werden soll.
  • k ist die Anzahl der Übereinstimmungen mit den nächsten Nachbarn, die in Ergebnisse eingeschlossen werden sollen.
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "myimagevector",
            "k": 5
        },
        {
            "kind": "vector"
            "vector": [
                -0.002222222,
                0.018708462,
                -0.013770515,
            . . .
            ],
            "fields": "mytextvector",
            "k": 5
        }
    ]
}

Suchindizes können keine Bilder speichern. Angenommen, Ihr Index enthält ein Feld für die Bilddatei, die Suchergebnisse enthalten eine Kombination aus Text und Bildern.

Abfrage mit integrierter Vektorisierung

Dieser Abschnitt zeigt eine Vektorabfrage, die die integrierte Vektorisierung aufruft, um eine Text- oder Bildabfrage in einen Vektor zu konvertieren. Wir empfehlen die stabile 2026-04-01 REST-API, Such-Explorer oder neuere Azure SDK Pakete für dieses Feature.

Eine Voraussetzung ist ein Suchindex, der einen Vektorisierer konfiguriert und einem Vektorfeld zugewiesen hat. Der Vektorizer stellt Verbindungsinformationen zu einem einbettenden Modell bereit, das zur Abfragezeit verwendet wird.

Der Such-Explorer unterstützt die integrierte Vektorisierung zur Abfragezeit. Wenn Ihr Index Vektorfelder enthält und über einen Vektorizer verfügt, können Sie die integrierte Text-zu-Vektor-Konvertierung verwenden.

  1. Wechseln Sie zum Suchdienst im Azure-Portal.

  2. Wählen Sie im linken Menü "Suchverwaltungsindizes>" und dann Ihren Index aus.

  3. Wählen Sie die Registerkarte " Vektorprofile " aus, um zu bestätigen, dass Sie über einen Vektorizer verfügen.

    Screenshot einer Vektorizereinstellung in einem Suchindex.

  4. Wählen Sie die Registerkarte "Such-Explorer " aus. Mithilfe der Standardabfrageansicht können Sie eine Textzeichenfolge in die Suchleiste eingeben. Der integrierte Vektorisierer konvertiert ihre Zeichenfolge in einen Vektor, führt die Suche aus und gibt Ergebnisse zurück.

    Alternativ können Sie dieJSON-Ansicht> anzeigen auswählen, um die Abfrage anzuzeigen oder zu ändern. Wenn Vektoren vorhanden sind, richtet der Such-Explorer automatisch eine Vektorabfrage ein. Mit der JSON-Ansicht können Sie Felder für die Verwendung in der Suche und Antwort auswählen, Filter hinzufügen und erweiterte Abfragen erstellen, z. B. Hybridabfragen. Um ein JSON-Beispiel anzuzeigen, wählen Sie in diesem Abschnitt die Registerkarte "REST-API" aus.

Anzahl der bewerteten Ergebnisse in einer Vektorabfrageantwort

Eine Vektorabfrage gibt den k Parameter an, der bestimmt, wie viele Übereinstimmungen in den Ergebnissen zurückgegeben werden. Die Suchmaschine gibt immer k Übereinstimmungen zurück. Wenn k größer ist als die Anzahl der Dokumente im Index, bestimmt die Anzahl der Dokumente die Obergrenze dessen, was zurückgegeben werden kann.

Wenn Sie mit der Volltextsuche vertraut sind, wissen Sie, dass Sie keine Ergebnisse erwarten, wenn der Index keinen Begriff oder Ausdruck enthält. In der Vektorsuche identifiziert der Suchvorgang jedoch die nächsten Nachbarn und gibt immer Ergebnisse zurück k , auch wenn die nächsten Nachbarn nicht so ähnlich sind. Es ist möglich, Ergebnisse für unsinnige oder offthematische Abfragen zu erhalten, insbesondere, wenn Sie keine Eingabeaufforderungen zum Festlegen von Begrenzungen verwenden. Weniger relevante Ergebnisse haben eine schlechtere Ähnlichkeitsbewertung, aber sie sind immer noch die "nächstgelegenen" Vektoren, wenn nichts näher ist. Daher kann eine Antwort ohne aussagekräftige Ergebnisse weiterhin Ergebnisse zurückgeben k , aber die Ähnlichkeitsbewertung jedes Ergebnisses wäre niedrig.

Ein Hybridansatz , der die Volltextsuche enthält, kann dieses Problem mindern. Eine weitere Lösung besteht darin, einen Mindestschwellenwert für die Suchbewertung festzulegen, aber nur, wenn es sich bei der Abfrage um eine reine Einzelvektorabfrage handelt. Hybridabfragen sind nicht für Mindestschwellenwerte geeignet, da die RRF-Bereiche wesentlich kleiner und veränderlicher sind.

Abfrageparameter, die sich auf die Ergebnisanzahl auswirken, umfassen:

  • "k": n Ergebnisse für nur Vektorabfragen.
  • "top": n Ergebnisse für Hybridabfragen, die einen search Parameter enthalten.

Beide k und top sind optional. Wenn nicht angegeben, beträgt die Standardanzahl der Ergebnisse in einer Antwort 50. Sie können top und skip festlegen, um durch mehr Ergebnisse zu blättern, oder die Standardeinstellung ändern.

Bewertungsalgorithmen, die in einer Vektorabfrage verwendet werden

Die Rangfolge der Ergebnisse wird durch eine der folgenden Methoden berechnet:

  • Die Ähnlichkeitsmetrik.
  • RRF, wenn mehrere Gruppen von Suchergebnissen vorhanden sind.

Ähnlichkeitsmetrik

Die im Indexabschnitt vectorSearch für eine Vektorabfrage angegebene Ähnlichkeitsmetrik. Gültige Werte sind cosine, euclideanund dotProduct.

Azure OpenAI-Einbettungsmodelle verwenden Kosinusgleichheit. Wenn Sie also Azure OpenAI-Einbettungsmodelle verwenden, ist cosine die empfohlene Metrik. Weitere unterstützte Bewertungsmetriken sind euclidean sowie dotProduct.

RRF

Mehrere Sätze werden erstellt, wenn die Abfrage auf mehrere Vektorfelder ausgerichtet ist, mehrere Vektorabfragen parallel ausgeführt wird oder eine Hybridlösung der Vektor- und Volltextsuche mit oder ohne semantische Rangfolge ist.

Während der Abfrageausführung kann eine Vektorabfrage nur auf einen internen Vektorindex abzielen. Für mehrere Vektorfelder und mehrere Vektorabfragen generiert die Suchmaschine mehrere Abfragen, die auf die jeweiligen Vektorindizes jedes Felds abzielen. Die Ausgabe ist eine Reihe von bewerteten Ergebnissen für jede Abfrage, die mit RRF fusioniert werden.The output is a set of ranked results for each query, which are fused using RRF. Weitere Informationen finden Sie unter Relevanzbewertung mithilfe der reziprozien Rangfusion.

Vektorgewichtung

Fügen Sie einen weight Abfrageparameter hinzu, um die relative Gewichtung der einzelnen Vektorabfragen anzugeben, die in Suchvorgängen enthalten sind. Dieser Wert wird verwendet, wenn die Ergebnisse mehrerer Bewertungslisten kombiniert werden, die von zwei oder mehr Vektorabfragen in derselben Anforderung oder aus dem Vektorteil einer Hybridabfrage erstellt werden.

Der Standardwert ist 1,0, und der Wert muss eine positive Zahl größer als 0 sein.

Gewichtungen werden beim Berechnen der RRF-Bewertungen jedes Dokuments verwendet. Die Berechnung ist ein Multiplikator des weight-Werts mit dem Bewertungsergebnis des Dokuments innerhalb des jeweiligen Ergebnissatzes.

Das folgende Beispiel ist eine Hybridabfrage mit zwei Vektorabfragezeichenfolgen und einer Textzeichenfolge. Gewichtungen werden den Vektorabfragen zugewiesen. Die erste Abfrage ist 0,5 oder die Hälfte der Gewichtung, wodurch die Wichtigkeit in der Anforderung reduziert wird. Die zweite Vektorabfrage ist doppelt so wichtig.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2026-04-01

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_first_vector_field", 
          "k": 10, 
          "weight": 0.5 
        },
        { 
          "kind": "vector", 
          "vector": [4.0, 5.0, 6.0], 
          "fields": "my_second_vector_field", 
          "k": 10, 
          "weight": 2.0
        } 
      ], 
      "search": "hello world" 
    }

Die Vektorgewichtung gilt nur für Vektoren. Die Textabfrage in diesem Beispiel "hello world"weist eine implizite neutrale Gewichtung von 1,0 auf. In einer Hybridabfrage können Sie jedoch die Bedeutung von Textfeldern erhöhen oder verringern, indem Sie "maxTextRecallSize" festlegen.

Festlegen von Schwellenwerten zum Ausschließen von Ergebnissen mit niedriger Bewertung (Vorschau)

Da die Suche nach dem nächsten Nachbarn immer die angeforderten k-Nachbarn zurückgibt, ist es möglich, dass Sie bei der Erfüllung der Anforderung an die Anzahl k der Suchergebnisse auch mehrere Treffer mit niedriger Punktzahl erhalten. Um Suchergebnisse mit niedriger Bewertung auszuschließen, können Sie einen threshold Abfrageparameter hinzufügen, der Ergebnisse basierend auf einer Mindestbewertung filtert. Filterung erfolgt vor der Verschmelzung der Ergebnisse aus verschiedenen Abrufmengen.

Dieser Parameter befindet sich in der Vorschau. Wir empfehlen die neueste Vorschauversion von Dokumenten – Search Post (REST-API).

In diesem Beispiel werden alle Übereinstimmungen, die unter 0,8 liegen, von Vektorsuchergebnissen ausgeschlossen, auch wenn die Anzahl der Ergebnisse unterschreitet k.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2026-05-01-preview 
    Content-Type: application/json 
    api-key: [admin key] 

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my-cosine-field", 
          "threshold": { 
            "kind": "vectorSimilarity", 
            "value": 0.8 
          } 
        }
      ]
    }

Nächste Schritte

Überprüfen Sie im nächsten Schritt Vektorabfragecodebeispiele in Python, C# oder JavaScript.

  • Last updated on