Konfigurowanie zintegrowanej wektoryzacji w usłudze Azure AI Search przy użyciu interfejsu 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, która jest powiązana z obsługiwanym modelem osadzania, na potrzeby 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 oparte na portalu, zobacz Szybki start: wektoryzowanie tekstu i obrazów w witrynie Azure Portal.

Wymagania wstępne

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

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

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

• Obsługiwany model osadzania.

• Ukończenie Szybki start: połączenie 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 klientem 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.

Obsługiwane źródło danych	Opis
Azure Blob Storage	To źródło danych współpracuje z blobami i tabelami. Musisz użyć konta typu standardowego (ogólnego przeznaczenia v2). Poziomy dostępu mogą być gorące, chłodne lub zimne.
Azure Data Lake Storage (ADLS) Gen2	Jest to konto usługi Azure Storage z włączoną hierarchiczną przestrzenią nazw. Aby potwierdzić, że masz usługę Data Lake Storage, sprawdź kartę Właściwości na stronie Przegląd .
Microsoft OneLake	To źródło danych łączy się z plikami OneLake i skrótami.

Obsługiwane modele osadzania

W przypadku zintegrowanej wektoryzacji użyj jednego z następujących modeli osadzania na platformie Azure AI. Instrukcje dotyczące wdrażania znajdują się w późniejszej sekcji.

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

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

³ Na potrzeby rozliczeń musisz dołączyć zasób Foundry do zestawu umiejętności w usłudze Azure AI Search. Jeśli nie używasz połączenia bez klucza (wersja zapoznawcza) do utworzenia zestawu umiejętności, oba zasoby muszą znajdować się w tym samym regionie.

⁴ Model osadzania wielomodalnego usługi Azure Vision jest dostępny w wybranych regionach.

Dostęp oparty na rolach

Możesz użyć identyfikatora Entra firmy Microsoft z przypisaniami ról lub uwierzytelnianiem opartym na kluczach z parametrami połączenia pełnego dostępu. W przypadku połączeń usługi Azure AI Search 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 usługi Azure AI Search

W tej sekcji pobierzesz punkt dostępu oraz token uwierzytelniający Microsoft Entra dla usługi Azure AI Search. Obie wartości są niezbędne do nawiązywania połączeń w żądaniach REST .

1. Zaloguj się do witryny Azure Portal i wybierz usługę Azure AI Search.

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 firmy 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 sztucznej inteligencji platformy Azure 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 Azure AI Search, obsługiwanego źródła danych i obsługiwanego modelu osadzania.

1. W Visual Studio Code wklej następujące elementy 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 ciąg punktem końcowym wyszukiwania i @token tokenem Microsoft Entra uzyskanym w artykule Uzyskiwanie informacji o połączeniu dla usługi Azure AI Search.

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	Parametry połączenia i nazwa kontenera utworzonego w sekcji Przygotowywanie danych.
   ADLS Gen2	@storageConnectionString i @blobContainer	Parametry połączenia i nazwa kontenera utworzonego w sekcji Przygotowywanie danych.
   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, @aoaiDeploymentName i @aoaiModelName	Punkt końcowy, nazwa wdrożenia i nazwa modelu uzyskana w sekcji Przygotowywanie modelu osadzania.
   Azure Vision	@AiFoundryEndpoint	Punkt końcowy uzyskany w sekcji Przygotowywanie modelu osadzania.

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

   ### List existing indexes by name
   GET {{baseUrl}}/indexes?api-version=2025-09-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. Indeksator w usłudze Azure AI Search 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=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. 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}} oraz container.name na {{lakehouseId}}.

Tworzenie zestawu umiejętności

W tej sekcji utworzysz zestaw umiejętności, który wywołuje wbudowaną umiejętność do fragmentowania zawartości oraz umiejętność tworzenia osadzeń w celu utworzenia reprezentacji wektorowych fragmentów. Zestaw zdolności jest używany podczas indeksowania w późniejszej sekcji.

Wywołaj wbudowaną funkcję w celu dzielenia 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 usługa Azure AI Search oferuje umiejętności dzielenia tekstu i układu dokumentu. Umiejętność dzielenia tekstu na części rozdziela tekst na zdania lub strony o określonej długości, podczas gdy umiejętność układu dokumentu dzieli zawartość według granic akapitu.

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

   ### 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. W tablicy wywołaj umiejętność "Podział tekstu" lub umiejętność "Układu dokumentu". 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.DocumentIntelligenceLayoutSkill",
          "name": "my-document-layout-skill",
          "context": "/document",
          "outputMode": "oneToMany",
          "markdownHeaderDepth": "h3",
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "markdown_document"
           }
          ]
        }
       ]
   

   Uwaga / Notatka

   Umiejętność układu dokumentu jest dostępna w publicznej wersji zapoznawczej. Jeśli chcesz wywołać tę umiejętność, użyj interfejsu API w wersji zapoznawczej, takiego jak 2025-03-01-preview.

Wywołaj umiejętność osadzania do wektoryzacji fragmentów

Aby wektoryzować fragmentowaną zawartość, należy zastosować umiejętność tworzenia osadzeń, która wskazuje na obsługiwany model osadzania.

1. Po wbudowanej umiejętności fragmentowania w tablicy skills wywołaj umiejętność osadzania Azure OpenAI lub umiejętność Azure Vision. 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 / Notatka

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

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

3. Jeśli używasz umiejętności osadzania multimodalnego w usłudze Azure Vision, dołącz zasób Foundry po tablicy 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 Azure AI Search, tworząc indeks wektorowy. 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 odnalezienia, ale nie mogą być filtrowalne, możliwe do pogrupowania ani sortowalne. Nie mogą również mieć analizatorów, normalizatorów ani przypisywania 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=2025-09-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 tablic fields. Dołącz pole klucza do identyfikacji dokumentu, pola niewektorów dla zawartości czytelnej dla człowieka i pola wektorów do osadzania.

       "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, przypisz dla każdego pola wektorowego wartość dimensions.

   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. Przetwornik wektorowy używa modelu osadzania, który indeksuje dane, aby zdekodować ciąg wyszukiwania lub obraz do wektora, służącego wyszukiwaniu wektorowemu.

1. Dodaj wektoryzator usługi Azure OpenAI lub wektoryzator usługi Azure Vision 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 / Notatka

   Wektoryzator usługi Azure Vision jest w publicznej wersji zapoznawczej. Jeśli chcesz wywołać ten wektoryzator, użyj interfejsu API w wersji zapoznawczej, takiego jak 2025-03-01-preview.

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, aby obsłużyć cały proces 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 Create Indexer aby zdefiniować indeksator, który wykonuje potok wektoryzacji.

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

   Uwaga / Notatka

   Wektoryzator usługi Azure Vision jest w publicznej wersji zapoznawczej. Jeśli wcześniej wywołałeś ten wektoryzator, użyj interfejsu API w wersji zapoznawczej, na przykład 2025-03-01-preview.

   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.

Treści powiązane

• Wektoryzacja zintegrowana w usłudze Azure AI Search
• Szybki start: wektoryzacja tekstu i obrazów w witrynie Azure Portal
• Przykład języka Python na potrzeby zintegrowanej wektoryzacji