在 Azure AI 搜尋服務 中使用 REST 設定整合向量化功能

在本文中，您將學習如何使用一套技能，將 內容從支援的資料來源中分割並向量化。 技能組中會呼叫「 Text Split 」技能或 「文件佈局 」來進行區塊化，並有一個嵌入技能，該技能會附加到 支援的嵌入模型 ，用於區塊向量化。 你也會學會如何將分塊和向量化的內容存入 向量索引中。

本文描述使用 REST 進行 整合向量化 的端到端工作流程。 關於入口網站的說明，請參見 快速入門：在Azure入口網站中向量化文字與圖片。

先決條件

• 一個有有效訂閱的 Azure 帳號。 免費註冊帳號。

• 一個Azure AI 搜尋服務服務。 我們建議基本層級或更高層級。

• 一個支援的數據來源。

• 一個支援的嵌入模型。

• 快速 啟動完成：無需金鑰連接 並 設定系統指派的管理身份。 雖然你可以使用基於金鑰的認證來進行資料平面操作，但本文假設角色 與受管理身份，這些更為安全。

• Visual Studio Code 搭配 REST 用戶端擴充套件。

支援的資料來源

整合向量化 適用於所有支援的資料來源。 然而，本文著重於最常用的資料來源，如下表所述。

資料來源	描述
Azure Blob 儲存體	這個資料來源適用於 Blob 和表格。 你必須使用標準效能（一般用途 v2）帳號。 存取層級可分為熱、冷或寒冷。
Azure Data Lake Storage（ADLS）第二代	這是一個啟用階層命名空間的 Azure 儲存體 帳號。 要確認你有Data Lake Storage，請檢查Overview頁面上的Properties標籤。
Microsoft OneLake	此資料來源可連結至 OneLake 檔案與捷徑。

支援的嵌入模型

請使用以下其中一種嵌入模型進行整合向量化。 部署說明會在 後面章節提供。

¹ 你的 Azure OpenAI 資源的端點必須有一個 custom 子網域，例如 https://my-unique-name.openai.azure.com。 如果你在 Azure 入口網站建立資源，這個子網域會在資源設定時自動產生。

² Azure 在 Microsoft Foundry 入口網站 建立的 OpenAI 資源（可存取嵌入模型）不被支援。 你必須在 Azure 入口網站建立一個 Azure OpenAI 資源。

³ 為了計費，您必須將您的 Microsoft Foundry 資源附加到您的 Azure AI 搜尋服務 技能集中。 除非您使用 無索引鍵連線 來建立技能集，否則這兩個資源都必須位於相同的區域中。

⁴ Azure Vision 多模態嵌入模型可在 select regions 提供。

基於角色的存取

您可以搭配使用 Microsoft Entra ID 和角色指派，或是金鑰型驗證搭配完整存取連線字串。 對於 Azure AI 搜尋服務 與其他資源的連結，我們建議角色分配。

要配置基於角色的存取以進行整合向量化：

1. 在你的搜尋服務中， 啟用角色 並 設定系統指派的管理身份。

2. 在您的資料來源平台與嵌入模型提供者中，建立角色分配，讓您的搜尋服務能存取資料與模型。 請參閱 「準備你的資料 」和 「準備你的嵌入模型」。

取得 Azure AI 搜尋服務 的連線資訊

在此區塊中，您可以取得 Azure AI 搜尋服務 服務的端點與 Microsoft Entra 令牌。 這兩個值都是建立 REST 請求連接所必需的。

1. 在Azure 入口網站中，進入您的搜尋服務。

2. 要取得您的搜尋端點，請複製概 覽 頁面上的網址。 一個搜尋端點的範例為 https://my-service.search.windows.net。

3. 要取得您的 Microsoft Entra 令牌，請在您的本地系統執行以下指令。 此步驟需完成 快速啟動：無鑰匙連接。

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

準備好你的資料

在本節中，你將透過上傳檔案至 支援的資料來源、分配角色並取得連線資訊，為整合向量化做準備。

準備你的嵌入模型

在本節中，你將透過分配角色、取得端點，並部署一個支援的嵌入模型，來準備你的Azure AI 資源進行整合向量化。

設定變數

在本節中，你指定你的Azure AI 搜尋服務服務的連線資訊、支援的資料來源，以及你的支援的嵌入模型。

1. 在Visual Studio Code中，將以下佔位符貼到你的 .rest 或 .http 檔案中。

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

2. 將 @baseUrl 替換成搜尋端點，將 @token 替換成你在 取得 Azure AI 搜尋服務 的連線資訊 中獲得的 Microsoft Entra token。

3. 根據你的資料來源，加入以下變數。

   資料來源	變數	輸入此資訊
   Azure Blob 儲存體	@storageConnectionString 以及 @blobContainer	在Prepare your data中建立的容器名稱和連接字串。
   ADLS Gen2	@storageConnectionString 以及 @blobContainer	在Prepare your data中建立的容器名稱和連接字串。
   OneLake	@workspaceId 以及 @lakehouseId	您在準備資料中取得的工作區和資料湖存放庫識別碼。

4. 根據你的嵌入模型提供者，加入以下變數。

   嵌入模型提供者	變數	輸入此資訊
   Azure OpenAI	@aoaiEndpoint、、 @aoaiDeploymentName和 @aoaiModelName	你在 準備你的嵌入模型時取得的端點名稱、部署名稱和模型名稱。
   Azure Vision	@AiFoundryEndpoint	你在 準備嵌入模型時所取得的端點。

5. 要驗證變數，請發送以下請求。

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

   回應應該會出現在相鄰的窗格。 如果您有現有索引，系統會列出這些索引。 否則，清單就是空白。 如果 HTTP 程式碼是 200 OK，你就可以繼續了。

連線至資料

在本節中，您會連線到支援的資料來源，以進行索引子型編製索引。 索引器 在 Azure AI 搜尋服務 中需要一個資料來源，該來源需指定資料類型、憑證與容器。

1. 使用 Create Data Source 定義一個在索引過程中提供連線資訊的資料來源。

   ### 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. 設定 type 為你的資料來源： azureblob 或 adlsgen2。

3. 要建立資料來源，請選擇 「發送請求」。

4. 如果你用 OneLake，請設 credentials.connectionString 為 ResourceId={{workspaceId}} 和 container.name 為 {{lakehouseId}}。

建立一套技能集

在這個區塊中，你會 創建一套技能 組，需要一個內建技能來分割內容，並有一個嵌入技能來建立區塊的向量表示。 技能會在 後續章節進行索引時執行。

呼叫內建技能來分割內容

將內容分割成區塊有助於滿足嵌入模型的要求，並防止因截斷而遺失資料。 若要進一步瞭解分塊，請參閱向量搜尋解決方案的大型文件分塊。

對於內建的資料分塊，Azure AI 搜尋服務 提供 文字分割技能 和 Azure Content Understanding 技能。 Text Split 技能會將文字依特定長度拆分為句子或頁面，而 Azure 內容理解技能則會執行考量版面配置的語意分塊，並保留段落邊界。

1. 使用 Create Skillset 來定義技能組。

   ### 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. 在skills陣列中，呼叫文字分割技能或Azure內容理解技能。 你可以貼上以下其中一個定義。

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

呼叫一個嵌入技能來向量化區塊

若要向量化您的區塊化內容，技能集需要指向支援內嵌模型的內嵌技能。

1. 在 skills 陣列中的內建分塊技能之後，接著呼叫 Azure OpenAI 嵌入技能或 Azure Vision 多模態嵌入技能（預覽）。 你可以貼上以下其中一個定義。

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

   註

   Azure Vision 多模態嵌入技能目前處於預覽階段。 如果你想呼叫這個技能，請使用最新的預覽 API 版本。

2. 如果你使用 Azure OpenAI 嵌入技能，請將 dimensions 設為由你的嵌入模型產生的 嵌入數量。

3. 如果您使用 Azure Vision 多模態嵌入技能，請在 陣列之後skills。 此附件僅供帳單用途。

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

4. 要建立技能組，請選擇 「發送請求」。

建立向量索引

在本節中，你要在Azure AI 搜尋服務服務上建立一個 向量索引來建立實體資料結構。 向量索引的模式需要以下條件：

• 名稱
• 鍵域（字串）
• 一個或多個向量場
• 向量配置

向量場儲存了分塊資料的數值表示。 它們必須是可以搜尋和檢索的，但不能是可篩選、可分面或可排序的。 它們也不能有分析器、正規化器或同義映射指派。

除了向量場外，以下步驟的範例索引還包含非向量場，適用於人類可讀的內容。 通常會包含你想要向量化內容的純文字對應物。 欲了解更多資訊，請參閱 建立向量索引。

1. 使用 Create Index 來定義向量索引的結構。

   ### 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. 在該區塊中新增vectorSearch。

       "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 指定用於索引與查詢向量場的演算法，並將 vectorSearch.profiles 演算法配置連結到你可以指派給向量場的設定檔。

3. 根據你的嵌入模型，請更新 vectorSearch.algorithms.metric。 距離度量的有效值 為 cosine、 dotproduct、 euclidean、 hamming和 。

4. 在陣列中加入欄位 fields 。 包含用於文件識別的鍵域、用於人類可讀內容的非向量欄位，以及用於嵌入的向量欄位。

       "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. 根據你的嵌入技能，為每個向量場設 dimensions 為以下數值。

   嵌入技巧	輸入這個數值
   Azure OpenAI	你的嵌入模型產生的嵌入數量。
   Azure Vision	1024

在索引中加入向量器

在本節中，你透過 在索引中定義向量化 器，在查詢時啟用向量化。 向量器利用嵌入模型，將你的資料索引，將搜尋字串或影像解碼成向量進行向量搜尋。

1. 在 vectorSearch.profiles 之後新增 Azure OpenAI 向量化工具 或 Azure Vision 向量化工具（預覽版） 你可以貼上以下其中一個定義。

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

   註

   Azure Vision 向量器目前處於預覽階段。 如果你想呼叫這個向量器，請使用最新的預覽版 API。

2. 在vectorSearch.profiles中指定你的向量器。

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

3. 要建立向量索引，請選擇 「發送請求」。

建立索引器

在這個章節中，你會建立一個 索引器 ，來驅動整個向量化流程，從資料擷取到技能組合執行再到索引。 我們建議您依 照排程執行索引器 ，以處理因限速而遺漏的變更或文件。

1. 使用 Create Indexer 來定義一個執行向量化管線的索引器。

   ### 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. 要建立索引器，請選擇 「發送請求」。

執行向量查詢以確認索引

在本節中，你將透過 建立向量查詢來驗證內容是否成功被索引。 因為你在 前一節設定了向量器，搜尋引擎可以將純文字或圖片解碼成向量以執行查詢。

1. 使用 Documents - Search Post 來定義一個在查詢時被向量化的查詢。

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

   註

   Azure Vision 向量器目前處於預覽階段。 如果你想呼叫這個向量器，請使用最新的預覽版 API。

   對於呼叫整合向量化的查詢， kind 必須設為 text，且 text 必須指定文字字串。 此字串會傳遞給指派給向量場的向量器。 欲了解更多資訊，請參閱 「帶整合向量化的查詢」。

2. 要執行向量查詢，請選擇 「發送請求」。

相關內容

• Azure AI 搜尋服務 中的整合向量嵌入
• 快速入門：在 Azure 入口網站中進行向量搜尋
• Python樣本用於整合載體化