Konfigurowanie zintegrowanej wektoryzacji w Wyszukiwanie AI platformy Azure przy użyciu architektury REST

Z tego artykułu dowiesz się, jak za pomocą zestawu umiejętności fragmentować i wektoryzować zawartość z obsługiwanego źródła danych. Zestaw umiejętności wywołuje umiejętność dzielenia tekstu lub umiejętność układu dokumentu do fragmentowania oraz umiejętność osadzania dołączoną do obsługiwanego modelu osadzania do wektoryzacji fragmentów. Dowiesz się również, jak przechowywać fragmentowaną i wektoryzowaną zawartość w indeksie wektorowym.

W tym artykule opisano pełny przepływ pracy na potrzeby zintegrowanej wektoryzacji przy użyciu architektury REST. Aby uzyskać instrukcje dotyczące korzystania z portalu, zobacz Szybki start: Wektoryzuj tekst i obrazy w portalu Azure.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz bezpłatne konto.

• Usługa Wyszukiwanie AI platformy Azure. Zalecamy warstwę Podstawowa lub nowszą.

• Obsługiwane źródło danych.

• Obsługiwany model osadzania.

• Ukończenie przewodnika Szybki start: nawiązywanie połączenia bez kluczy i konfigurowanie tożsamości zarządzanej przypisanej przez system. Chociaż w przypadku operacji płaszczyzny danych można używać uwierzytelniania opartego na kluczach, w tym artykule przyjęto role i tożsamości zarządzane, które są bezpieczniejsze.

• Visual Studio Code z rozszerzeniem klienta REST.

Obsługiwane źródła danych

Zintegrowana wektoryzacja współpracuje ze wszystkimi obsługiwanymi źródłami danych. Jednak ten artykuł koncentruje się na najczęściej używanych źródłach danych, które opisano w poniższej tabeli.

Źródło danych	Opis
Azure Blob Storage	Źródło danych działa z blobami i tabelami. Musisz użyć konta o standardowej wydajności (wersja ogólnego przeznaczenia v2). Warstwy dostępu mogą być gorące, zimne lub chłodne.
Azure Data Lake Storage (ADLS) Gen2	Jest to konto Azure Storage z włączoną hierarchiczną przestrzenią nazw. Aby potwierdzić, że masz Data Lake Storage, sprawdź stronę Properties na karcie Overview.
Microsoft OneLake	To źródło danych łączy się z plikami OneLake i skrótami.

Obsługiwane modele osadzania

Użyj jednego z następujących modeli osadzania na potrzeby zintegrowanej wektoryzacji. Instrukcje dotyczące wdrażania znajdują się w późniejszej sekcji.

¹ Punkt końcowy zasobu Azure OpenAI musi mieć poddomenę custom, taką jak https://my-unique-name.openai.azure.com. Jeśli zasób został utworzony w portalu Azure, ta poddomena została automatycznie wygenerowana podczas konfigurowania zasobów.

² zasoby Azure OpenAI (z dostępem do modeli osadzania), które zostały utworzone w portalu Microsoft Foundry, nie są obsługiwane. Musisz utworzyć zasób Azure OpenAI w portalu Azure.

3 W celu rozliczeń musisz dołączyć zasób Microsoft Foundry do skilli Wyszukiwanie AI platformy Azure. Jeśli nie używasz połączenia bez klucza do utworzenia zestawu umiejętności, oba zasoby muszą znajdować się w tym samym regionie.

⁴ Wielomodalny model osadzania Azure Vision jest dostępny w wybranych regionach.

Dostęp oparty na rolach

Można użyć Microsoft Entra ID z przypisaniami ról lub uwierzytelnianiem opartym na kluczach z parametrami połączenia pełnego dostępu. W przypadku Wyszukiwanie AI platformy Azure połączeń z innymi zasobami zalecamy przypisania ról.

Aby skonfigurować dostęp oparty na rolach na potrzeby zintegrowanej wektoryzacji:

1. W usłudze wyszukiwania włącz role i skonfiguruj tożsamość zarządzaną przypisaną przez system.

2. Na platformie źródła danych i dostawcy modelu osadzania utwórz przypisania ról, które umożliwiają usłudze wyszukiwania dostęp do danych i modeli. Zobacz Przygotowywanie danych i Przygotowywanie modelu osadzania.

Uzyskiwanie informacji o połączeniu dla Wyszukiwanie AI platformy Azure

W tej sekcji pobierzesz punkt końcowy i token Microsoft Entra dla usługi Wyszukiwanie AI platformy Azure. Obie wartości są niezbędne do nawiązania połączeń w żądaniach REST.

1. Przejdź do usługi wyszukiwania w portalu Azure.

2. Aby uzyskać punkt końcowy wyszukiwania, skopiuj adres URL na stronie Przegląd . Przykładowy punkt końcowy wyszukiwania to https://my-service.search.windows.net.

3. Aby uzyskać token Microsoft Entra, uruchom następujące polecenie w systemie lokalnym. Ten krok wymaga ukończenia przewodnika Szybki start: nawiązywanie połączenia bez kluczy.

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

Przygotowywanie danych

W tej sekcji przygotujesz dane do zintegrowanej wektoryzacji, przekazując pliki do obsługiwanego źródła danych, przypisując role i uzyskując informacje o połączeniu.

Przygotowywanie modelu osadzania

W tej sekcji przygotujesz zasób Azure sztucznej inteligencji do zintegrowanej wektoryzacji, przypisując role, uzyskując punkt końcowy i wdrażając obsługiwany model osadzania.

Ustawianie zmiennych

W tej sekcji określisz informacje o połączeniu dla usługi Wyszukiwanie AI platformy Azure, obsługiwane źródło danych oraz obsługiwany model osadzania.

1. W Visual Studio Code wklej następujące symbole zastępcze do pliku .rest lub .http.

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

2. Zastąp @baseUrl punktem końcowym wyszukiwania i @token tokenem Microsoft Entra uzyskanym w Pobierz informacje o połączeniu dla Wyszukiwanie AI platformy Azure.

3. W zależności od źródła danych dodaj następujące zmienne.

   Źródło danych	Zmienne	Wprowadź te informacje
   Azure Blob Storage	@storageConnectionString i @blobContainer	Connection string i nazwę kontenera, który utworzyłeś w Przygotuj dane.
   ADLS Gen2	@storageConnectionString i @blobContainer	Connection string i nazwę kontenera, który utworzyłeś w Przygotuj dane.
   OneLake	@workspaceId i @lakehouseId	Identyfikatory obszarów roboczych i lakehouse uzyskane w sekcji Przygotowywanie danych.

4. W zależności od dostawcy modelu osadzania dodaj następujące zmienne.

   Dostawca modelu osadzania	Zmienne	Wprowadź te informacje
   Azure OpenAI	@aoaiEndpoint, @aoaiDeploymentNamei @aoaiModelName	Punkt końcowy, nazwa wdrożenia oraz nazwa modelu uzyskane w sekcji Przygotowanie modelu osadzającego.
   Azure Vision	@AiFoundryEndpoint	Punkt końcowy, który uzyskałeś w Przygotowywaniu modelu osadzającego.

5. Aby zweryfikować zmienne, wyślij następujące żądanie.

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

   Odpowiedź powinna pojawić się w sąsiednim okienku. Jeśli masz istniejące indeksy, są one wyświetlane. W przeciwnym razie lista jest pusta. Jeśli kod HTTP to 200 OK, możesz kontynuować.

Połącz się z danymi

W tej sekcji nawiąż połączenie z obsługiwanym źródłem danych na potrzeby indeksowania opartego na indeksatorze. Obiekt indexer w Wyszukiwanie AI platformy Azure wymaga źródła danych określającego typ, poświadczenia i kontener.

1. Użyj opcji Utwórz źródło danych , aby zdefiniować źródło danych, które udostępnia informacje o połączeniu podczas indeksowania.

   ### Create a data source
   POST {{baseUrl}}/datasources?api-version=2026-04-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. Ustaw type jako źródło danych: azureblob lub adlsgen2.

3. Aby utworzyć źródło danych, wybierz pozycję Wyślij żądanie.

4. Jeśli używasz usługi OneLake, ustaw credentials.connectionString na ResourceId={{workspaceId}} i container.name na {{lakehouseId}}.

Tworzenie zestawu umiejętności

W tej sekcji utworzysz zestaw umiejętności, który wywołuje wbudowaną umiejętność dzielenia zawartości na fragmenty oraz umiejętność osadzania w celu utworzenia reprezentacji wektorowych fragmentów. Zestaw umiejętności jest wykonywany podczas indeksowania w późniejszej sekcji.

Wywołaj wbudowaną umiejętność do fragmentowania zawartości

Partycjonowanie zawartości na fragmenty pomaga spełnić wymagania modelu osadzania i zapobiega utracie danych z powodu obcinania. Aby uzyskać więcej informacji na temat fragmentowania, zobacz Fragmentowanie dużych dokumentów dla rozwiązań wyszukiwania wektorów.

W przypadku wbudowanych fragmentów danych Wyszukiwanie AI platformy Azure oferuje umiejętności Text Split i Azure Content Understanding. Funkcja Text Split dzieli tekst na zdania lub strony o określonej długości, natomiast funkcja Azure Content Understanding wykonuje semantyczne dzielenie na fragmenty z uwzględnieniem układu i z zachowaniem granic akapitów.

1. Utwórz zestaw umiejętności , aby zdefiniować zestaw umiejętności.

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

2. W tablicy skills użyj umiejętności Podział tekstu lub umiejętności Azure Content Understanding. Możesz wkleić jedną z poniższych definicji.

       "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.ContentUnderstandingSkill",
          "name": "my-content-understanding-skill",
          "context": "/document",
          "chunkingProperties": {
            "method": "semantic",
            "unit": "tokens",
            "maximumLength": 500
          },
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "text_sections",
             "targetName": "text_sections"
           }
          ]
        }
       ]
   

Uruchom funkcję osadzania, aby zwektoryzować fragmenty

Aby przekształcać na wektory fragmentowaną zawartość, zestaw umiejętności wymaga umiejętności osadzającej wskazującej na obsługiwany model osadzania.

1. Po użyciu wbudowanej umiejętności dzielenia na fragmenty w tablicy skills wywołaj umiejętność osadzania Azure OpenAI lub umiejętność wielomodalnych osadzeń Azure Vision (wersja zapoznawcza). Możesz wkleić jedną z poniższych definicji.

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

   Uwaga

   Umiejętność osadzania wielomodalnego Azure Vision jest dostępna w wersji zapoznawczej. Jeśli chcesz wywołać tę umiejętność, użyj najnowszej wersji interfejsu API w wersji zapoznawczej.

2. Jeśli używasz umiejętności osadzania w Azure OpenAI, ustaw dimensions na liczbę osadzeń wygenerowanych przez twój model osadzania.

3. Jeśli używasz umiejętności wielomodalnych osadzeń Azure Vision, przyłącz zasób Microsoft Foundry za tablicą skills. Ten załącznik służy do celów rozliczeniowych.

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

4. Aby utworzyć zestaw umiejętności, wybierz pozycję Wyślij żądanie.

Tworzenie indeksu wektorowego

W tej sekcji skonfigurujesz fizyczne struktury danych w usłudze Wyszukiwanie AI platformy Azure, tworząc indeks vector. Schemat indeksu wektorowego wymaga następujących elementów:

• Nazwa
• Pole klucza (ciąg)
• Jedno lub więcej pól wektorów
• Konfiguracja wektora

Pola wektorowe przechowują reprezentacje liczbowe fragmentowanych danych. Muszą one być przeszukiwalne i możliwe do pobrania, ale nie mogą być filtrowalne, fasetowalne ani sortowalne. Nie mogą również mieć analizatorów, normalizatorów ani przypisań map synonimów.

Oprócz pól wektorowych przykładowy indeks w poniższych krokach zawiera pola niewektorowe dla zawartości czytelnej dla człowieka. Często dołączane są odpowiedniki zwykłego tekstu zawartości, którą chcesz wektoryzować. Aby uzyskać więcej informacji, zobacz Tworzenie indeksu wektorów.

1. Użyj polecenia Create Index (Utwórz indeks ), aby zdefiniować schemat indeksu wektorowego.

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

2. Dodaj konfigurację wyszukiwania wektorowegovectorSearch do sekcji.

       "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 Określa algorytm używany do indeksowania i wykonywania zapytań dotyczących pól wektorów, podczas gdy vectorSearch.profiles łączy konfigurację algorytmu z profilem, który można przypisać do pól wektorowych.

3. W zależności od modelu osadzania zaktualizuj wartość vectorSearch.algorithms.metric. Prawidłowe wartości metryk odległości to cosine, dotproduct, euclideani hamming.

4. Dodaj pola do fields tablic. Dołącz pole kluczowe do identyfikacji dokumentu, pola niewektorowe dla zawartości czytelnej dla człowieka i pola wektorowe do embeddingów.

       "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. W zależności od umiejętności osadzania, ustaw dla każdego pola wektora dimensions na następującą wartość.

   Umiejętność osadzania	Wprowadź tę wartość
   Azure OpenAI	Liczba osadzonych elementów wygenerowanych przez model osadzania.
   Azure Vision	1024

Dodawanie wektoryzatora do indeksu

W tej sekcji włączysz wektoryzację w czasie wykonywania zapytania, definiując wektoryzator w indeksie. Wektoryzator używa modelu osadzania, który indeksuje Twoje dane, aby przekonwertować ciąg wyszukiwania lub obraz na wektor do wyszukiwania wektorowego.

1. Dodaj wektoryzator Azure OpenAI lub wektorizer Azure Vision (wersja zapoznawcza) po vectorSearch.profiles. Możesz wkleić jedną z poniższych definicji.

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

   Uwaga

   Wektoryzator Azure Vision jest w wersji zapoznawczej. Jeśli chcesz wywołać ten wektoryzator, użyj najnowszej wersji interfejsu API w wersji zapoznawczej.

2. Określ wektoryzator w pliku vectorSearch.profiles.

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

3. Aby utworzyć indeks wektora, wybierz pozycję Wyślij żądanie.

Tworzenie indeksatora

W tej sekcji utworzysz indeksator do obsługi całego procesu wektoryzacji, od pobierania danych, przez wykonywanie zestawu umiejętności, aż po indeksowanie. Zalecamy uruchomienie indeksatora zgodnie z harmonogramem w celu przetworzenia zmian lub nieodebranych dokumentów z powodu ograniczania przepustowości.

1. Użyj opcji Utwórz indeksator, aby zdefiniować indeksator, który wykonuje potok wektoryzacji.

   ### Create an indexer
   POST {{baseUrl}}/indexers?api-version=2026-04-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. Aby utworzyć indeksator, wybierz pozycję Wyślij żądanie.

Uruchamianie zapytania wektorowego w celu potwierdzenia indeksowania

W tej sekcji sprawdzisz, czy zawartość została pomyślnie zindeksowana, tworząc zapytanie wektorowe. Ponieważ w poprzedniej sekcji skonfigurowano wektoryzator, aparat wyszukiwania może dekodować zwykły tekst lub obraz do wektora na potrzeby wykonywania zapytań.

1. Użyj funkcji Dokumenty — post wyszukiwania , aby zdefiniować zapytanie, które jest wektoryzowane w czasie zapytania.

   ### Run a vector query
   POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2026-04-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"
           }
       ]
     }
   

   Uwaga

   Wektoryzator Azure Vision jest w wersji zapoznawczej. Jeśli chcesz wywołać ten wektoryzator, użyj najnowszej wersji interfejsu API w wersji zapoznawczej.

   W przypadku zapytań, które wywołują wektoryzację zintegrowaną, kind należy ustawić wartość texti text musi określać ciąg tekstowy. Ten ciąg jest przekazywany do wektoryzatora przypisanego do pola wektora. Aby uzyskać więcej informacji, zobacz Zapytanie ze zintegrowaną wektoryzacją.

2. Aby uruchomić zapytanie wektorowe, wybierz pozycję Wyślij żądanie.

Powiązana zawartość

• Zintegrowane osadzanie wektorów w Wyszukiwanie AI platformy Azure
• Szybki start: wyszukiwanie wektorów w witrynie Azure Portal
• przykład Python na potrzeby wektoryzacji zintegrowanej