使用 REST 在 Azure AI 搜索中设置集成矢量化

本文介绍如何使用技能集对 受支持数据源中的内容进行分块和向量化。 技能集调用 文本拆分技能 或 文档布局技能 进行分块，以及附加到 支持的嵌入模型 进行区块矢量化的嵌入技能。 你还将了解如何将分块内容和矢量化内容存储在 向量索引中。

本文介绍使用 REST 进行的端到端工作流。 有关基于门户的说明，请参阅 快速入门：在 Azure 门户中向量化文本和图像。

先决条件

• 拥有有效订阅的 Azure 帐户。 免费创建帐户。

• Azure AI 搜索服务。 建议使用基本层或更高层级。

• 支持的数据源。

• 支持的嵌入模型。

• 完成快速入门：在没有密钥的情况下连接并配置系统分配的托管标识。 尽管可以对数据平面作使用基于密钥的身份验证，但本文假定角色和托管标识更安全。

• 具有 REST 客户端的 。

支持的数据源

集成向量化适用于所有 受支持的数据源。 但是，本文重点介绍最常用的数据源，下表对此进行了介绍。

支持的数据源	DESCRIPTION
Azure Blob 存储服务	此数据源适用于 Blob 和表。 必须使用标准性能（常规用途 v2）帐户。 访问层可以是热层、温层或冷层。
Azure Data Lake Storage （ADLS） Gen2	这是启用了分层命名空间的 Azure 存储帐户。 若要确认你有 Data Lake Storage，请检查“概述”页上的“属性”选项卡。
Microsoft OneLake	此数据源连接到 OneLake 文件和快捷方式。

支持的嵌入模型

对于集成矢量化，请使用以下嵌入模型之一在 Azure AI 平台上。 稍后部分提供了部署说明。

¹ Azure OpenAI 资源的终结点必须具有 自定义子域，例如 https://my-unique-name.openai.azure.com。 如果在 Azure 门户中创建了资源，则此子域是在资源设置过程中自动生成的。

²不支持 Azure AI Foundry 门户中创建的 Azure OpenAI 资源（具有嵌入模型访问权限）。 必须在 Azure 门户中创建 Azure OpenAI 资源。

³ 出于计费目的，必须将 Azure AI 多服务资源附加到 Azure AI 搜索服务中的技能集。 除非使用 无键连接（预览版） 创建技能集，否则这两个资源必须位于同一区域。

⁴ Azure AI 视觉多模式嵌入模型在 所选区域中可用。

基于角色的访问权限

可以将 Microsoft Entra ID 与角色分配或基于密钥的身份验证与完全访问连接字符串配合使用。 对于与其他资源的 Azure AI 搜索连接，我们建议分配角色。

若要为集成矢量化配置基于角色的访问，请执行：

1. 在搜索服务上， 启用角色 并 配置系统分配的托管标识。

2. 在数据源平台和嵌入模型提供程序上，创建允许搜索服务访问数据和模型的角色分配。 请参阅 “准备数据 ”和 “准备嵌入模型”。

获取 Azure AI 搜索的连接信息

在本部分中，你将检索 Azure AI 搜索服务的端点和 Microsoft Entra 身份验证令牌。 这两个值都需要在 REST 请求中建立连接。

1. 登录到 Azure 门户 并选择 Azure AI 搜索服务。

2. 若要获取搜索终结点，请在 “概述 ”页上复制 URL。 一个示例搜索终结点是 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中获取的 Microsoft Entra 令牌替换 。

3. 根据数据源，添加以下变量。

   数据源	变量	输入此信息
   Azure Blob 存储	@storageConnectionString 和 @blobContainer	在准备数据中创建的容器的连接字符串和名称。
   ADLS Gen2	@storageConnectionString 和 @blobContainer	在准备数据中创建的容器的连接字符串和名称。
   OneLake	@workspaceId 和 @lakehouseId	在 准备数据中获取的工作区和 Lakehouse ID。

4. 根据您的嵌入模型提供商，可以添加以下变量。

   嵌入模型提供程序	变量	输入此信息
   Azure OpenAI	@aoaiEndpoint、@aoaiDeploymentName 和 @aoaiModelName	您在准备嵌入模型时获取的终结点、部署名称和模型名称。
   Azure AI 视觉	@aiMultiServiceEndpoint	在准备嵌入模型时中获取的终结点。

5. 若要验证变量，请发送以下请求。

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

   相邻窗格中应该会显示响应。 如果有现有索引，则会列出它们。 否则，列表将为空。 如果 HTTP 状态码是 200 OK，则可以继续。

连接到数据

在本部分中，将连接到 支持的数据源 ，以便进行基于索引器的索引编制。 Azure AI 搜索中的 索引器 需要指定类型、凭据和容器的数据源。

1. 使用 “创建数据源 ”定义在编制索引期间提供连接信息的数据源。

   ### 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. 将 type 设置为数据源：azureblob 或 adlsgen2。

3. 若要创建数据源，请选择“ 发送请求”。

4. 如果您使用 OneLake，请将credentials.connectionString设置为ResourceId={{workspaceId}}，将container.name设置为{{lakehouseId}}。

创建技能集

在本部分中，你将创建一个 技能集 ，该技能调用内置技能来对内容进行分块，并创建嵌入技能来创建区块的向量表示形式。 在索引编制过程中，技能集将在后面的部分执行。

调用内置技能以对内容进行分块

将内容分区为区块有助于满足嵌入模型的要求，并防止因截断而导致数据丢失。 有关分块的详细信息，请参阅 将大型文档分块以适应矢量搜索解决方案。

对于内置数据分块，Azure AI 搜索提供文本拆分技能和文档布局技能。 文本拆分技能将文本拆分为特定长度的句子或页面，而文档布局技能根据段落边界中断内容。

1. 使用 创建技能集 定义技能集。

   ### 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. 请在 skills 数组中调用文本拆分技能或文档布局技能。 可以粘贴以下定义之一。

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

   注释

   文档布局功能提供公共预览版。 如果要调用此技能，请使用预览 API，例如 2025-03-01-preview。

调用嵌入技能来向量化区块

若要将内容块向量化，技能集需要一个指向支持的嵌入模型的嵌入技能。

1. 在skills数组中内置分块技能之后，调用Azure OpenAI 嵌入技能或Azure AI 视觉技能。 可以粘贴以下定义之一。

        {
          "@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 AI 视觉技能处于公开预览阶段。 如果要调用此技能，请使用预览 API，例如 2025-03-01-preview。

2. 如果您使用 Azure OpenAI 嵌入技能，请将dimensions设置为嵌入模型生成的嵌入数量。

3. 如果使用 Azure AI 视觉技能，请在 阵列后skills。 此附件用于计费目的。

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

4. 若要创建技能集，请选择“ 发送请求”。

创建矢量索引

在本部分中，你将通过创建 矢量索引在 Azure AI 搜索服务上设置物理数据结构。 矢量索引的架构需要以下各项：

• 名称
• 关键字段（字符串）
• 一个或多个向量字段
• 矢量配置

矢量字段存储分块数据的数值表示形式。 它们必须是可搜索和可检索的，但不能是可筛选、可分面化或可排序的。 它们也不能具有分析器、规范化器或同义词映射分配。

除了向量字段，以下步骤中的示例索引还包含人类可读内容的非函数字段。 通常包括要向量化的内容的纯文本等效项。 有关详细信息，请参阅创建矢量索引。

1. 使用 “创建索引” 定义向量索引的架构。

   ### 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. 向部分添加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和euclideanhamming。

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 AI 视觉	1024

将向量器添加到索引

在本部分中，通过在索引中 定义向量器 ，在查询时启用矢量化。 向量器使用嵌入模型来为数据编制索引，以将搜索字符串或图像解码为矢量进行矢量搜索。

1. 在之后添加 Azure OpenAI 向量器或 vectorSearch.profiles。 可以粘贴以下定义之一。

         "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": "{{aiMultiServiceEndpoint}}",
               "modelVersion": "2023-04-15"
             }
           }
         ]
   

   注释

   Azure AI 视觉向量器以公共预览版提供。 如果要调用此向量器，请使用预览 API，例如 2025-03-01-preview。

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

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

3. 若要创建向量索引，请选择“ 发送请求”。

创建索引器

在本部分中，你将创建一个 索引器 来驱动整个向量化管道，从数据检索到技能集执行到索引编制。 建议 按计划运行索引器 来处理因限制而错过的更改或文档。

1. 使用 创建索引器 定义执行矢量化管道的索引器。

   ### 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. 若要创建索引器，请选择“ 发送请求”。

运行矢量查询以确认索引编制

在本部分中，你将通过 创建矢量查询来验证内容是否已成功编制索引。 由于在 上一节中配置了向量器，因此搜索引擎可以将纯文本或图像解码为查询执行的向量。

1. 使用文档 - 搜索帖子定义在查询时矢量化的查询。

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

   注释

   Azure AI 视觉向量器以公共预览版提供。 如果以前调用此向量器，请使用预览 API，例如 2025-03-01-preview。

   对于调用集成向量化的查询， kind 必须设置为 text，并且 text 必须指定文本字符串。 此字符串被传递给分配到矢量字段的矢量化器。 有关详细信息，请参阅 使用集成向量化的查询。

2. 若要运行向量查询，请选择“ 发送请求”。

相关内容

• Azure AI 搜索中的集成矢量化
• 快速入门：在 Azure 门户中向量化文本和图像
• 用于集成矢量化的 Python 示例