Nastavení integrované vektorizace v Azure AI Vyhledávač pomocí REST

V tomto článku se dozvíte, jak pomocí sady dovedností vytvořit blok a vektorizovat obsah z podporovaného zdroje dat. Sada dovedností volá dovednost rozdělení textu nebo dovednost rozložení dokumentu pro rozdělení na části a dovednost vkládání, která je připojená k podporovanému vkládacímu modelu pro vektorizaci částí. Také se dozvíte, jak ukládat chunkovaný a vektorizovaný obsah do vektorového indexu.

Tento článek popisuje komplexní pracovní postup pro integrovanou vektorizaci pomocí REST. Pokyny založené na portálu najdete v tématu Quickstart: Vektorizace textu a obrázků na portálu Azure.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač. Doporučujeme úroveň Basic nebo vyšší.

• Podporovaný zdroj dat.

• Podporovaný model vkládání.

• Dokončení rychlého startu: Připojení bez klíčů a konfigurace spravované identity přiřazené systémem I když pro operace roviny dat můžete použít ověřování založené na klíčích, tento článek předpokládá role a spravované identity, které jsou bezpečnější.

• Visual Studio Code s rozšířením klienta REST.

Podporované zdroje dat

Integrovaná vektorizace funguje se všemi podporovanými zdroji dat. Tento článek se ale zaměřuje na nejčastěji používané zdroje dat, které jsou popsány v následující tabulce.

Zdroj dat	Popis
Azure Blob Storage	Tento zdroj dat funguje s objekty blob a tabulkami. Musíte použít účet standardního výkonu (pro obecné účely verze 2). Úrovně přístupu můžou být horké, chladné nebo studené.
Azure Data Lake Storage (ADLS) Gen2	Jedná se o účet Azure Storage s povoleným hierarchickým oborem názvů. Pokud chcete potvrdit, že máte Data Lake Storage, zkontrolujte kartu Properties na stránce Přehled.
Microsoft OneLake	Tento zdroj dat se připojuje k souborům a zkratkám OneLake.

Podporované modely vkládání

Pro integrovanou vektorizaci použijte jeden z následujících modelů vkládání. Pokyny k nasazení najdete v další části.

¹ Koncový bod prostředku Azure OpenAI musí mít subdoménu custom subdomain, například https://my-unique-name.openai.azure.com. Pokud jste prostředek vytvořili na portálu Azure, tato subdoména se během instalace prostředku automaticky vygenerovala.

² Azure prostředky OpenAI (s přístupem k modelům vkládání), které byly vytvořeny na portálu Microsoft Foundry Portal nejsou podporované. Na portálu Azure musíte vytvořit prostředek Azure OpenAI.

³ Pro účely fakturace musíte apojit prostředek Microsoft Foundry ke své Azure AI Vyhledávač dovednosti. Pokud k vytvoření sady dovedností nepoužíváte připojení bez klíče , musí být oba prostředky ve stejné oblasti.

⁴ Multimodální model vkládání Azure Vision je k dispozici v oblastech select regions.

Přístup na základě role

Můžete použít Microsoft Entra ID s přiřazeními rolí nebo ověřováním na základě klíčů s připojovacími řetězci s úplným přístupem. Pro Azure AI Vyhledávač připojení k jiným prostředkům doporučujeme přiřazení rolí.

Konfigurace přístupu na základě role pro integrovanou vektorizaci:

1. Ve vyhledávací službě povolte role a nakonfigurujte spravovanou identitu přiřazenou systémem.

2. Na platformě zdroje dat a poskytovateli modelu pro vložení vytvořte přiřazení rolí, která vaší vyhledávací službě umožňují přístup k datům a modelům. Viz Příprava dat a příprava modelu vkládání.

Získání informací o připojení pro Azure AI Vyhledávač

V této části načtete koncový bod a token Microsoft Entra pro službu Azure AI Vyhledávač. Obě hodnoty jsou nezbytné k navázání připojení v požadavcích REST.

1. Přejděte do vyhledávací služby na portálu Azure.

2. Pokud chcete získat koncový bod vyhledávání, zkopírujte adresu URL na stránce Přehled . Příkladem koncového bodu vyhledávání je https://my-service.search.windows.net.

3. Token Microsoft Entra získáte spuštěním následujícího příkazu v místním systému. Tento krok vyžaduje dokončení rychlého startu: Připojení bez klíčů.

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

Příprava dat

V této části připravíte data na integrovanou vektorizaci tak, že nahrajete soubory do podporovaného zdroje dat, přiřadíte role a získáte informace o připojení.

Příprava modelu vkládání

V této části připravíte prostředek Azure AI na integrovanou vektorizaci přiřazením rolí, získáním koncového bodu a nasazením modelu supported embedding model.

Nastavení proměnných

V této části zadáte informace o připojení pro službu Azure AI Vyhledávač, váš podporovaný zdroj dat a váš podporovaný model pro vkládání.

1. Do Visual Studio Code vložte následující zástupné symboly do souboru .rest nebo .http.

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

2. Nahraďte @baseUrl koncovým bodem vyhledávání a @token tokenem Microsoft Entra, který jste získali v dokumentaci Get connection information for Azure AI Vyhledávač.

3. V závislosti na zdroji dat přidejte následující proměnné.

   Zdroj dat	Proměnné	Zadejte tyto informace.
   Azure Blob Storage	@storageConnectionString a @blobContainer	Connection string a název kontejneru, který jste vytvořili v Připravení dat
   ADLS Gen2	@storageConnectionString a @blobContainer	Connection string a název kontejneru, který jste vytvořili v Připravení dat
   OneLake	@workspaceId a @lakehouseId	ID pracovního prostoru a lakehouse, které jste získali při přípravě dat.

4. V závislosti na poskytovateli modelu vložení přidejte následující proměnné.

   Poskytovatel implementace modelu	Proměnné	Zadejte tyto informace.
   Azure OpenAI	@aoaiEndpoint, @aoaiDeploymentName a @aoaiModelName	Koncový bod, název nasazení a název modelu, který jste získali v části Příprava vloženého modelu.
   Azure Vision	@AiFoundryEndpoint	Koncový bod získaný v rámci přípravy modelu vkládání.

5. Pokud chcete ověřit proměnné, odešlete následující požadavek.

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

   V sousedním podokně by se měla zobrazit odpověď. Pokud máte existující indexy, jsou uvedené. V opačném případě je seznam prázdný. Pokud je kód HTTP 200 OK, můžete pokračovat.

Připojení k datům

V této části se připojíte k podporovanému zdroji dat pro indexerové indexování. indexer v Azure AI Vyhledávač vyžaduje zdroj dat, který určuje typ, přihlašovací údaje a kontejner.

1. Pomocí příkazu Vytvořit zdroj dat definujte zdroj dat, který poskytuje informace o připojení během indexování.

   ### 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. Nastavte type na zdroj dat: azureblob nebo adlsgen2.

3. Pokud chcete vytvořit zdroj dat, vyberte Odeslat požadavek.

4. Pokud používáte OneLake, nastavte credentials.connectionString na ResourceId={{workspaceId}} hodnotu a container.name na {{lakehouseId}}hodnotu .

Vytvoření sady dovedností

V této části vytvoříte sadu dovedností , která volá integrovanou dovednost pro vytvoření bloků obsahu a vložené dovednosti pro vytváření vektorových reprezentací bloků dat. Sada dovedností se provede během indexování v další části.

Volání integrované dovednosti pro rozdělení obsahu na části

Rozdělení obsahu na bloky dat vám pomůže splnit požadavky vloženého modelu a zabránit ztrátě dat kvůli zkrácení. Další informace o vytváření bloků dat najdete v tématu Bloky velkých dokumentů pro řešení vektorového vyhledávání.

Pro integrované dělení dat na bloky nabízí Azure AI Vyhledávač dovednosti Text Split a Azure Content Understanding. Dovednost Text Split rozděluje text na věty nebo stránky o určité délce, zatímco dovednost Azure Content Understanding provádí sémantické dělení s ohledem na rozvržení, které respektuje hranice odstavců.

1. Použijte Vytvořit sadu dovedností k definování sady dovedností.

   ### 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. V poli skills volejte dovednost Text Split nebo dovednost Azure Content Understanding. Můžete vložit jednu z následujících definic.

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

Zavolejte dovednost pro embedding pro vektorizaci bloků

Aby bylo možné vektorizovat rozdělený obsah, potřebuje sada dovedností vestavbu, která odkazuje na podporovaný vestavěný model.

1. Po integrované dovednosti pro dělení na bloky v poli skills volejte dovednost Azure OpenAI Embedding nebo dovednost Azure Vision multimodal embeddings (Preview). Můžete vložit jednu z následujících definic.

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

   Poznámka

   Dovednost Azure Vision pro multimodální vkládání je momentálně v náhledu. Pokud chcete volat tuto dovednost, použijte nejnovější verzi rozhraní API ve verzi Preview.

2. Pokud používáte dovednost Azure OpenAI Embedding, nastavte dimensions na počet vkládání generovaných modelem pro vkládání.

3. Pokud používáte funkci Azure Vision pro vícemodální vkládání, připojte prostředek Microsoft Foundry za pole skills. Tato příloha je určená pro účely fakturace.

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

4. Pokud chcete vytvořit sadu dovedností, vyberte Odeslat žádost.

Vytvoření vektorového indexu

V této části nastavíte fyzické datové struktury ve službě Azure AI Vyhledávač vytvořením indexu vector. Schéma vektorového indexu vyžaduje následující:

• Jméno
• Pole klíče (řetězec)
• Jedno nebo více vektorových polí
• Konfigurace vektoru

Vektorová pole ukládají číselné reprezentace dat v blocích dat. Musí být prohledávatelné a dohledatelné, ale nemohou být filtrovatelné, fasetovatelné ani řaditelné. Nemohou mít ani analyzátory, normalizátory nebo synonymní mapování.

Kromě vektorových polí obsahuje ukázkový index v následujících krocích také nevektorová pole pro obsah čitelný lidmi. Je běžné zahrnout ekvivalenty prostého textu obsahu, který chcete vektorizovat. Další informace naleznete v tématu Vytvoření vektorového indexu.

1. Pomocí funkce Vytvořit index definujte schéma vektorového indexu.

   ### 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. Přidejte do oddílu konfiguraci vektorovéhovectorSearch vyhledávání.

       "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 určuje algoritmus použitý pro indexování a dotazování vektorových polí, zatímco vectorSearch.profiles propojení konfigurace algoritmu s profilem, který můžete přiřadit k vektorovým polím.

3. V závislosti na modelu vkládání aktualizujte vectorSearch.algorithms.metric. Platné hodnoty pro metriky vzdálenosti jsou cosine, dotproduct, euclideana hamming.

4. Přidejte položky do fields polí. Zahrňte klíčové pole pro identifikaci dokumentu, nevectorová pole pro obsah čitelný člověkem a vektorová pole pro vkládání.

       "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. V závislosti na schopnosti vkládání nastavte dimensions pro každé vektorové pole následující hodnotu.

   Dovednost vkládání	Zadejte tuto hodnotu.
   Azure OpenAI	Počet vkládání vygenerovaných modelem vkládání
   Azure Vision	1024

Přidání vektorizátoru do indexu

V této části povolíte vektorizaci v době dotazu definováním vektorizátoru v indexu. Vektorizátor používá vložený model, který indexuje data, k dekódování vyhledávacího řetězce nebo obrázku do vektoru pro vektorové vyhledávání.

1. Přidejte vektorizátor Azure OpenAI nebo vektorizátor Azure Vision (Preview) za vectorSearch.profiles. Můžete vložit jednu z následujících definic.

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

   Poznámka

   Vektorizátor Azure vision je ve verzi Preview. Pokud chcete tento vektorizátor použít, použijte nejnovější verzi Preview rozhraní API.

2. Zadejte vektorizátor v souboru vectorSearch.profiles.

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

3. Pokud chcete vytvořit vektorový index, vyberte Odeslat požadavek.

Vytvoření indexeru

V této části vytvoříte indexer , který bude řídit celý kanál vektorizace od načtení dat až po spuštění sady dovedností až po indexování. Doporučujeme spustit indexer podle plánu pro zpracování změn nebo dokumentů, které byly zmeškané kvůli omezování.

1. Pomocí create Indexer definujte indexer, který spouští kanál vektorizace.

   ### 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. Pokud chcete vytvořit indexer, vyberte Odeslat požadavek.

Spuštění vektorového dotazu pro potvrzení indexování

V této části ověříte, že se obsah úspěšně indexoval vytvořením vektorového dotazu. Vzhledem k tomu, že jste v předchozí části nakonfigurovali vektorizátor, může vyhledávací modul dekódovat prostý text nebo obrázek do vektoru pro provádění dotazů.

1. K definování dotazu vektorizovaného v době dotazu použijte dokumenty – vyhledávací příspěvek .

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

   Poznámka

   Vektorizátor Azure vision je ve verzi Preview. Pokud chcete tento vektorizátor použít, použijte nejnovější verzi Preview rozhraní API.

   Pro dotazy, které vyvolávají integrovanou vektorizaci, kind musí být nastavena na texta text musí zadat textový řetězec. Tento řetězec se předá vektorizátoru přiřazeného k poli vektoru. Další informace naleznete v tématu Dotaz s integrovanou vektorizací.

2. Pokud chcete spustit vektorový dotaz, vyberte Odeslat požadavek.

Související obsah

• Integrované vkládání vektorů do Azure AI Vyhledávač
• Quickstart: Vektorové vyhledávání na portálu Azure
• Python vzorek pro integrovanou vektorizaci