Einrichten der integrierten Vektorisierung in Azure AI Search mithilfe von REST

In diesem Artikel erfahren Sie, wie Sie mithilfe eines Skillsets Inhalte aus einer unterstützten Datenquelle aufschlüsseln und vektorieren können. Das Skillset ruft den Text Split Skill oder den Document Layout Skill für das Chunking und einen Einbettenskill auf, der einem unterstützten Einbettungsmodell für die Chunk-Vektorisierung zugeordnet ist. Außerdem erfahren Sie, wie Sie den geblockten und vektorisierten Inhalt in einem Vektorindex speichern.

In diesem Artikel wird der End-to-End-Workflow für die integrierte Vektorisierung mithilfe von REST beschrieben. Portalbasierte Anweisungen finden Sie in der Schnellstartanleitung: Vektorisieren von Text und Bildern im Azure-Portal.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Kostenlos ein Konto erstellen.

• Ein Azure AI Search-Dienst. Wir empfehlen den Tarif „Basic“ oder höher.

• Eine unterstützte Datenquelle.

• Ein unterstütztes Einbettungsmodell.

• Abschluss der Schnellstartanleitung: Verbinden ohne Schlüssel und Konfigurieren einer vom System zugewiesenen verwalteten Identität. Obwohl Sie die schlüsselbasierte Authentifizierung für Datenebenenvorgänge verwenden können, übernimmt dieser Artikel Rollen und verwaltete Identitäten, die sicherer sind.

• Visual Studio Code mit einem REST-Client.

Unterstützte Datenquellen

Die integrierte Vektorisierung funktioniert mit allen unterstützten Datenquellen. Dieser Artikel konzentriert sich jedoch auf die am häufigsten verwendeten Datenquellen, die in der folgenden Tabelle beschrieben werden.

Unterstützte Datenquelle	BESCHREIBUNG
Azure Blob Storage	Diese Datenquelle funktioniert mit Blobs und Tabellen. Sie müssen ein Standardleistungskonto (general-purpose v2) verwenden. Zugriffsebenen können heiß, kühl oder kalt sein.
Azure Data Lake Storage (ADLS) Gen2	Dies ist ein Azure Storage-Konto mit aktiviertem hierarchischen Namespace. Um zu bestätigen, dass Sie über Data Lake Storage verfügen, aktivieren Sie die Registerkarte "Eigenschaften " auf der Seite "Übersicht ".
Microsoft OneLake	Diese Datenquelle stellt eine Verbindung mit OneLake-Dateien und -Verknüpfungen her.

Unterstützte Einbettungsmodelle

Verwenden Sie für die integrierte Vektorisierung eines der folgenden Einbettungsmodelle auf einer Azure AI-Plattform. Bereitstellungsanweisungen werden in einem späteren Abschnitt bereitgestellt.

¹ Der Endpunkt Ihrer Azure OpenAI-Ressource muss über eine benutzerdefinierte Unterdomäne verfügen, wie https://my-unique-name.openai.azure.com. Wenn Sie Ihre Ressource im Azure-Portal erstellt haben, wurde diese Unterdomäne während der Ressourceneinrichtung automatisch generiert.

² Azure OpenAI-Ressourcen (mit Zugriff auf Einbettungsmodelle), die im Foundry-Portal erstellt wurden, werden nicht unterstützt. Sie müssen eine Azure OpenAI-Ressource im Azure-Portal erstellen.

³ Für Abrechnungszwecke müssen Sie Ihre Findry-Ressource an das Skillset in Ihrem Azure AI Search-Dienst anfügen. Sofern Sie keine schlüssellose Verbindung (Vorschau) zum Erstellen des Skillsets verwenden, müssen sich beide Ressourcen in derselben Region befinden.

⁴ Das modell für die multimodale Einbettung von Azure Vision steht in ausgewählten Regionen zur Verfügung.

Rollenbasierter Zugriff

Sie können Microsoft Entra-ID mit Rollenzuweisungen oder schlüsselbasierter Authentifizierung mit Vollzugriffsverbindungszeichenfolgen verwenden. Für Azure AI Search-Verbindungen mit anderen Ressourcen empfehlen wir Rollenzuweisungen.

So konfigurieren Sie den rollenbasierten Zugriff für die integrierte Vektorisierung:

1. Aktivieren Sie in Ihrem Suchdienst Rollen, und konfigurieren Sie eine vom System zugewiesene verwaltete Identität.

2. Erstellen Sie auf Ihrer Datenquellenplattform und beim Einbetten von Modellanbietern Rollenzuweisungen, mit denen Ihr Suchdienst auf Daten und Modelle zugreifen kann. Weitere Informationen finden Sie unter "Vorbereiten Ihrer Daten " und "Vorbereiten des Einbettungsmodells".

Abrufen von Verbindungsinformationen für Azure AI Search

In diesem Abschnitt rufen Sie den Endpunkt und das Microsoft Entra-Token für Ihren Azure AI Search-Dienst ab. Beide Werte sind erforderlich, um Verbindungen in REST-Anforderungen herzustellen.

1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Azure AI Search-Dienst aus.

2. Um Ihren Suchendpunkt abzurufen, kopieren Sie die URL auf der Seite "Übersicht" . Ein Beispiel für einen Suchendpunkt ist https://my-service.search.windows.net.

3. Um Ihr Microsoft Entra-Token abzurufen, führen Sie den folgenden Befehl auf Ihrem lokalen System aus. Dieser Schritt erfordert den Abschluss der Schnellstartanleitung: Verbinden ohne Schlüssel.

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

Bereiten Sie die Daten vor.

In diesem Abschnitt bereiten Sie Ihre Daten für die integrierte Vektorisierung vor, indem Sie Dateien in eine unterstützte Datenquelle hochladen, Rollen zuweisen und Verbindungsinformationen abrufen.

Bereiten Sie Ihr Einbettungsmodell vor

In diesem Abschnitt bereiten Sie Ihre Azure AI-Ressource für die integrierte Vektorisierung vor, indem Sie Rollen zuweisen, einen Endpunkt abrufen und ein unterstütztes Einbettungsmodell bereitstellen.

Festlegen von Variablen

In diesem Abschnitt geben Sie die Verbindungsinformationen für Ihren Azure AI Search-Dienst, Ihre unterstützte Datenquelle und Ihr unterstütztes Einbettungsmodell an.

1. Fügen Sie in Visual Studio Code die folgenden Platzhalter in Ihre .rest- oder .http-Datei ein.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
   @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
   

2. Ersetzen Sie @baseUrl durch den Suchendpunkt und @token durch das Microsoft Entra-Token, das Sie in Verbindungsinformationen für Azure AI Search abrufen erhalten haben.

3. Fügen Sie je nach Datenquelle die folgenden Variablen hinzu.

   Datenquelle	Variablen	Geben Sie diese Informationen ein.
   Azure Blob Storage (Speicherdienst von Azure für unstrukturierte Daten)	@storageConnectionString und @blobContainer	Die Verbindungszeichenfolge und der Name des Containers, den Sie in " Vorbereiten Ihrer Daten" erstellt haben.
   ADLS Gen2	@storageConnectionString und @blobContainer	Die Verbindungszeichenfolge und der Name des Containers, den Sie in " Vorbereiten Ihrer Daten" erstellt haben.
   OneLake	@workspaceId und @lakehouseId	Die Arbeitsbereichs- und Lakehouse-IDs, die Sie in Vorbereiten Ihrer Daten erhalten haben.

4. Fügen Sie abhängig vom Anbieter des Einbettungsmodells die folgenden Variablen hinzu.

   Anbieter des Einbettungsmodells	Variablen	Geben Sie diese Informationen ein.
   Azure OpenAI	@aoaiEndpoint, @aoaiDeploymentName und @aoaiModelName	Der Endpunkt, der Bereitstellungsname und der Modellname, den Sie in Vorbereiten des Einbettungsmodells erhalten haben.
   Azure Vision	@AiFoundryEndpoint	Der Endpunkt, den Sie in "Vorbereiten des Einbettungsmodells" abgerufen haben.

5. Um die Variablen zu überprüfen, senden Sie die folgende Anforderung.

   ### List existing indexes by name
   GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   

   Im angrenzenden Bereich sollte eine Antwort angezeigt werden. Sind Indizes vorhanden, werden diese aufgelistet. Andernfalls ist die Liste leer. Wenn der HTTP-Code lautet 200 OK, können Sie fortfahren.

Herstellen einer Verbindung mit Ihren Daten

In diesem Abschnitt stellen Sie eine Verbindung mit einer unterstützten Datenquelle für die indexerbasierte Indizierung her. Ein Indexer in Azure AI Search erfordert eine Datenquelle, die den Typ, die Anmeldeinformationen und den Container angibt.

1. Verwenden Sie "Datenquelle erstellen", um eine Datenquelle zu definieren, die während der Indizierung Verbindungsinformationen bereitstellt.

   ### Create a data source
   POST {{baseUrl}}/datasources?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-data-source",
       "type": "azureblob",
       "subtype": null,
       "credentials": {
           "connectionString": "{{storageConnectionString}}"
       },
       "container": {
           "name": "{{blobContainer}}",
           "query": null
       },
       "dataChangeDetectionPolicy": null,
       "dataDeletionDetectionPolicy": null
     }
   

2. Stellen Sie type auf Ihre Datenquelle ein: azureblob oder adlsgen2.

3. Um die Datenquelle zu erstellen, wählen Sie "Anforderung senden" aus.

4. Wenn Sie OneLake verwenden, setzen Sie credentials.connectionString auf ResourceId={{workspaceId}} und container.name auf {{lakehouseId}}.

Erstellen eines Skillsets

In diesem Abschnitt erstellen Sie ein Skillset, das eine eingebaute Fähigkeit aufruft, um Ihre Inhalte zu unterteilen, und eine Einbettungsfunktion, um Vektordarstellungen der Abschnitte zu erstellen. Das Skillset wird während der Indizierung in einem späteren Abschnitt ausgeführt.

Aufrufen einer integrierten Fähigkeit zum Blöcken Ihrer Inhalte

Wenn Sie Ihre Inhalte in Blöcke aufteilen, können Sie die Anforderungen Ihres Einbettungsmodells erfüllen und Datenverluste aufgrund von Kürzungen vermeiden. Weitere Informationen über das Chunking finden Sie unter "Große Dokumente in Abschnitte teilen" für Vektorsuchlösungen.

Für integriertes Daten-Chunking bietet Azure AI Search die Text-Split-Funktion und die Dokumentlayout-Funktion. Das Können "Textteilung" teilt Text in Sätze oder Seiten einer vorgegebenen Länge auf, während das Dokumentlayout Inhalte nach Absatzgrenzen aufteilt.

1. Verwenden Sie create Skillset , um ein Skillset zu definieren.

   ### Create a skillset
   POST {{baseUrl}}/skillsets?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-skillset",
       "skills": []
     }
   

2. Rufen Sie im skills Array die Funktion "Textsplit" oder "Dokumentenlayout" auf. Sie können eine der folgenden Definitionen einfügen.

       "skills": [
        {
          "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
          "name": "my-text-split-skill",
          "textSplitMode": "pages",
          "maximumPageLength": 2000,
          "pageOverlapLength": 500,
          "maximumPagesToTake": 0,
          "unit": "characters",
          "defaultLanguageCode": "en",
          "inputs": [
           {
             "name": "text",
             "source": "/document/text",
             "inputs": []
           }
          ],
          "outputs": [
           {
             "name": "textItems"
           }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill",
          "name": "my-document-layout-skill",
          "context": "/document",
          "outputMode": "oneToMany",
          "markdownHeaderDepth": "h3",
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "markdown_document"
           }
          ]
        }
       ]
   

   Hinweis

   Der Dokumentlayout-Skill befindet sich in der öffentlichen Vorschau. Wenn Sie diese Fähigkeit aufrufen möchten, verwenden Sie eine Vorschau-API, z.B. 2025-03-01-preview.

Einbettungsfunktion zum Vektorisieren der Blöcke aufrufen

Um Ihre gestückelten Inhalte zu vektorisieren, benötigt das Skillset eine Einbettungsfunktion, die auf ein unterstütztes Einbettungsmodell verweist.

1. Rufen Sie nach der integrierten Chunking-Funktion im skills Array den Azure OpenAI Embedding-Skill oder den Azure Vision-Skill auf. Sie können eine der folgenden Definitionen einfügen.

        {
          "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
          "resourceUri": "{{aoaiEndpoint}}",
          "deploymentId": "{{aoaiDeploymentName}}",
          "modelName": "{{aoaiModelName}}",
          "dimensions": 1536,
          "inputs": [
            {
              "name": "text",
              "source": "/document/text"
            }
          ],
          "outputs": [
            {
              "name": "embedding"
            }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Vision.VectorizeSkill",
          "context": "/document",
          "modelVersion": "2023-04-15", 
          "inputs": [
            {
              "name": "url",
              "source": "/document/metadata_storage_path"
            },
            {
              "name": "queryString",
              "source": "/document/metadata_storage_sas_token"
            }
          ],
          "outputs": [
            {
              "name": "vector"
            }
          ]
        }
   

   Hinweis

   Die Azure Vision Multimodal-Embedding-Funktion befindet sich in der öffentlichen Vorschau. Wenn Sie diese Fähigkeit aufrufen möchten, verwenden Sie die neueste Vorschau-API.

2. Wenn Sie die Azure OpenAI Embedding-Fähigkeit verwenden, legen Sie die Anzahl der Einbettungen fest dimensions , die von Ihrem Einbettungsmodell generiert werden.

3. Wenn Sie den Azure Vision multimodalen Einbettungs-Skill verwenden, fügen Sie Ihre Foundry-Ressource nach dem skills Array an. Diese Anlage dient zu Abrechnungszwecken.

       "skills": [ ... ],
       "cognitiveServices": {
         "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
         "subdomainUrl": "{{AiFoundryEndpoint}}"
        }
   

4. Um das Skillset zu erstellen, wählen Sie "Anforderung senden" aus.

Erstellen eines Vektorindexes

In diesem Abschnitt richten Sie physische Datenstrukturen für Ihren Azure AI Search-Dienst ein, indem Sie einen Vektorindex erstellen. Das Schema eines Vektorindex erfordert Folgendes:

• Name
• Schlüsselfeld (Zeichenfolge)
• Mindestens ein Vektorfeld
• Vektorkonfiguration

Vektorfelder speichern numerische Darstellungen Ihrer datenblöcke. Sie müssen durchsuchbar und abrufbar sein, können aber nicht gefiltert, facetable oder sortierbar sein. Sie können auch keine Analyse- oder Normalisierungsfunktionen oder Synonymzuordnungen haben.

Zusätzlich zu Vektorfeldern enthält der Beispielindex in den folgenden Schritten nicht Vektorfelder für lesbaren Inhalt. Es ist üblich, Nur-Text-Entsprechungen für den Inhalt einzuschließen, den Sie vektorisieren möchten. Weitere Informationen finden Sie unter Erstellen eines Vektorindex.

1. Verwenden Sie "Index erstellen ", um das Schema eines Vektorindexes zu definieren.

   ### Create a vector index
   POST {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-vector-index",
       "fields": [],
       "vectorSearch": []
     }
   

2. Fügen Sie dem Abschnitt eine vectorSearch hinzu.

       "vectorSearch": {
         "algorithms": [
           {
             "name": "hnsw-algorithm",
             "kind": "hnsw",
             "hnswParameters": {
               "m": 4,
               "efConstruction": 400,
               "efSearch": 100,
               "metric": "cosine"
             }
           }
         ],
         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
           }
         ]
       }
   

   vectorSearch.algorithms Gibt den Algorithmus an, der für die Indizierung und Abfrage von Vektorfeldern verwendet wird, während vectorSearch.profiles die Algorithmuskonfiguration mit einem Profil verknüpft wird, das Sie Vektorfeldern zuweisen können.

3. Aktualisieren Sie vectorSearch.algorithms.metricabhängig vom Einbettungsmodell. Gültige Werte für Entfernungsmetriken sind cosine, , dotproduct, euclideanund hamming.

4. Fügen Sie felder zu den fields Arrays hinzu. Schließen Sie ein Schlüsselfeld für die Dokumentidentifikation, nicht-Vektorfelder für menschenlesbare Inhalte, und Vektorfelder für Einbettungen ein.

       "fields": [
         {
           "name": "id",
           "type": "Edm.String",
           "key": true,
           "filterable": true
         },
         {
           "name": "title",
           "type": "Edm.String",
            "searchable": true,
            "filterable": true,
            "sortable": true,
            "retrievable": true
         },
         {
           "name": "titleVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         },
         {
           "name": "content",
           "type": "Edm.String",
            "searchable": true,
            "retrievable": true
         },
         {
           "name": "contentVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": false,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         }
       ]
   

5. Je nach Ihrer Einbettungskompetenz legen Sie dimensions für jedes Vektorfeld auf den folgenden Wert fest.

   Einbettungsskill	Geben Sie diesen Wert ein
   Azure OpenAI	Die Anzahl der Einbettungen, die von Ihrem Einbettungsmodell generiert werden.
   Azure Vision	1024

Hinzufügen eines Vektorizers zum Index

In diesem Abschnitt aktivieren Sie die Vektorisierung zur Abfragezeit, indem Sie einen Vektorizer in Ihrem Index definieren. Der Vektorizer verwendet das Einbettungsmodell, das Ihre Daten indiziert, um eine Suchzeichenfolge oder ein Bild in einen Vektor für die Vektorsuche zu decodieren.

1. Fügen Sie den Azure OpenAI-Vektorizer oder den Azure Vision-Vektorizer nach vectorSearch.profiles. Sie können eine der folgenden Definitionen einfügen.

         "profiles": [ ... ],
         "vectorizers": [
           {
             "name": "my-openai-vectorizer",
             "kind": "azureOpenAI",
             "azureOpenAIParameters": {
               "resourceUri": "{{aoaiEndpoint}}",
               "deploymentId": "{{aoaiDeploymentName}}",
               "modelName": "{{aoaiModelName}}"
             }
           },
           {
             "name": "my-ai-services-vision-vectorizer",
             "kind": "aiServicesVision",
             "aiServicesVisionParameters": {
               "resourceUri": "{{AiFoundryEndpoint}}",
               "modelVersion": "2023-04-15"
             }
           }
         ]
   

   Hinweis

   Der Azure Vision-Vektorizer befindet sich in der öffentlichen Vorschau. Wenn Sie diesen Vektorizer aufrufen möchten, verwenden Sie eine Vorschau-API wie z. B. 2025-03-01-preview.

2. Geben Sie ihren Vektorizer in vectorSearch.profilesan.

         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
             "vectorizer": "my-openai-vectorizer"
           }
         ]
   

3. Um den Vektorindex zu erstellen, wählen Sie "Anforderung senden" aus.

Erstellen eines Indexers

In diesem Abschnitt erstellen Sie einen Indexer , um die gesamte Vektorisierungspipeline zu steuern, von datenabrufen bis hin zur Ausführung von Skillset bis hin zur Indizierung. Es wird empfohlen, den Indexer planmäßig auszuführen, um Änderungen oder Dokumente zu verarbeiten, die aufgrund der Drosselung verpasst wurden.

1. Verwenden Sie "Indexer erstellen", um einen Indexer zu definieren, der die Vektorisierungspipeline ausführt.

   ### Create an indexer
   POST {{baseUrl}}/indexers?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-indexer",
       "dataSourceName": "my-data-source",
       "targetIndexName": "my-vector-index",
       "skillsetName": "my-skillset",
       "schedule": {
         "interval": "PT2H"
       },
       "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null
       }
     }
   

2. Um den Indexer zu erstellen, wählen Sie "Anforderung senden" aus.

Ausführen einer Vektorabfrage zum Bestätigen der Indizierung

In diesem Abschnitt überprüfen Sie, ob Ihre Inhalte erfolgreich indiziert wurden, indem Sie eine Vektorabfrage erstellen. Da Sie einen Vektorisierer in einem vorherigen Abschnitt konfiguriert haben, kann die Suchmaschine Nur-Text oder ein Bild in einen Vektor für die Abfrageausführung decodieren.

1. Verwenden Sie Dokumente – Suchbeitrag , um eine Abfrage zu definieren, die zur Abfragezeit vektorisiert ist.

   ### Run a vector query
   POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "count": true,
       "select": "title, content",
       "vectorQueries": [
           {
             "kind": "text",
             "text": "a sample text string for integrated vectorization",
             "fields": "titleVector, contentVector",
             "k": "3"
           }
       ]
     }
   

   Hinweis

   Der Azure Vision-Vektorizer befindet sich in der öffentlichen Vorschau. Wenn Sie diesen Vektorizer zuvor aufgerufen haben, verwenden Sie eine Vorschau-API wie etwa 2025-03-01-preview.

   Für Abfragen, die die integrierte Vektorisierung aufrufen, muss kind auf text gesetzt werden und text muss eine Textzeichenfolge angeben. Diese Zeichenfolge wird an den Vektorizer übergeben, der dem Vektorfeld zugewiesen ist. Weitere Informationen finden Sie unter Abfrage mit integrierter Vektorisierung.

2. Um die Vektorabfrage auszuführen, wählen Sie "Anforderung senden" aus.

Verwandte Inhalte

• Integrierte Vektorisierung in Azure AI Search
• Schnellstart: Vektorisieren von Text und Bildern im Azure-Portal
• Python-Beispiel für integrierte Vektorisierung