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

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

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

先决条件

具有活动订阅的Azure帐户。创建试用版订阅。
Azure AI Search service。建议使用基本层或更高层级。
支持的数据源。
支持的嵌入模型。
完成快速入门：在没有密钥的情况下连接并配置系统分配的托管标识。尽管可以使用基于密钥的身份验证进行数据平面操作，但本文假设角色和托管标识更为安全。
Visual Studio Code REST 客户端扩展。

支持的数据源

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

数据源	DESCRIPTION
Azure Blob 存储	此数据源适用于 Blob 和表。必须使用标准性能（常规用途 v2）帐户。访问层级可以是热层、温层或冷层。
Azure Data Lake Storage （ADLS） Gen2	这是启用了分层命名空间的Azure Storage帐户。若要确保您有 Data Lake Storage，请检查“概述”页面上的“属性”选项卡。

支持的嵌入模型

使用以下嵌入模型之一进行集成向量化。稍后部分提供了部署说明。

提供者	支持的模型
Azure AI 服务多重服务资源³	对于文本和图像：Azure AI Vision多模态⁴

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

³ Azure AI Vision 多模式嵌入模型在选择区域中可用。

基于角色的访问控制

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

若要为向量化集成配置基于角色的访问，

在搜索服务，启用角色并配置系统分配的托管标识。
在您的数据源平台和嵌入模型提供商上，创建允许您的搜索服务访问数据和模型的角色分配。请参阅 “准备数据 ”和 “准备嵌入模型”。

注释

免费搜索服务支持与Azure AI Search的基于角色的连接。但是，它们不支持通过出站连接到 Azure Storage 或 Azure Vision 时使用托管标识。这种缺乏支持要求你在免费搜索服务和其他Azure资源之间的连接上使用基于密钥的身份验证。

若要获得更安全的连接，请使用基本层或更高版本。然后，可以为授权访问启用角色并配置托管身份。

获取Azure AI Search的连接信息

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

小窍门

以下步骤假定你在进行概念验证测试时使用的是基于角色的访问。如果要将集成矢量化用于应用开发，请参阅通过标识将应用连接到 Azure AI Search。

登录到 Azure portal 并选择Azure AI Search service。
若要获取搜索终结点，请在 “概述 ”页上复制 URL。示例搜索终结点是 https://my-service.search.azure.cn。
若要获取Microsoft Entra 令牌，请在本地系统上运行以下命令。此步骤需要完成快速入门：在没有密钥的情况下连接。
```
az account get-access-token --scope https://search.azure.cn/.default --query accessToken --output tsv
```

准备您的数据

在本部分中，通过将文件上传到受支持的数据源、分配角色和获取连接信息，为集成矢量化准备数据。

登录到 Azure portal 并选择Azure Storage帐户。
在左窗格中，选择Data storage>Containers。
创建容器或选择现有容器，然后将文件上传到容器。
要分配角色，请执行以下操作：
1. 在左窗格中，选择Access Control （IAM）。
2. 选择添加>添加角色分配。
3. 在 作业函数角色下，选择 Storage Blob 数据读取者，然后选择 下一步。
4. 在“成员”下，选择“托管标识”，然后选择“选择成员”。
5. 选择您的订阅和搜索服务的托管标识。
若要获取连接字符串，
1. 在左窗格中，选择Security + networking>Access keys。
2. 复制任一连接字符串，并在稍后的Set variables中进行指定。
（可选）将容器中的删除与搜索索引中的删除同步。为了配置索引器以检测删除，请按照以下步骤操作：
1. 在存储帐户上启用软删除。如果使用性软删除，则不需要下一步。
2. 添加自定义元数据，以便索引器可以扫描并确定哪些 blob 被标记为要删除。为自定义属性指定描述性名称。例如，可以命名属性“IsDeleted”并将其设置为 false。对容器中的每个 Blob 重复此步骤。如果要删除 Blob，请将属性更改为 true。有关详细信息，请参阅从 Azure Storage 编制索引时的更改和删除检测。

Azure AI Search通过多模态嵌入（版本 4.0）支持Azure Vision的图像检索。在内部，Azure AI Search 调用 multimodal 嵌入技能连接到 Azure 视觉。

登录到 Azure 门户并选择 AI 服务资源。
要分配角色，请执行以下操作：
1. 在左窗格中，选择Access control （IAM）。
2. 选择添加>添加角色分配。
3. 在 “作业功能角色”下，选择 “认知服务用户”，然后选择“ 下一步”。
4. 在“成员”下，选择“托管标识”，然后选择“选择成员”。
5. 选择您的订阅和搜索服务的托管标识。
若要获取端点，请执行以下步骤：
1. 在左窗格中，选择 “资源管理>密钥和终结点”。
2. 复制 Azure AI 多服务资源的终结点。稍后在 Set 变量中指定此 URL。
注释

多模式嵌入内置于 Azure AI 多服务资源中，因此没有模型部署步骤。

设置变量

在本部分中，请指定 Azure AI 搜索服务、支持的数据源和支持的嵌入模型的连接信息。

在 Visual Studio Code 中，将以下占位符粘贴到 .rest 或 .http 文件中。

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

将 @baseUrl 替换成搜索终结点，将 @token 替换成你在获取 Azure AI Search 连接信息中获得的 Microsoft Entra 令牌。

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

数据源	变量	输入此信息
Azure Blob 存储	`@storageConnectionString` 和 `@blobContainer`	在准备数据中创建的容器的连接字符串和名称。
ADLS Gen2	`@storageConnectionString` 和 `@blobContainer`	在准备数据中创建的容器的连接字符串和名称。

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

嵌入模型提供程序变量输入此信息

Azure AI 视觉 @aiMultiServiceEndpoint 在准备嵌入模型时中获取的终结点。
若要验证变量，请发送以下请求。
```
### 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 视觉	`@aiMultiServiceEndpoint`	在准备嵌入模型时中获取的终结点。

连接到数据

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

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

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

将 type 设置为数据源：azureblob 或 adlsgen2。
若要创建数据源，请选择“ 发送请求”。
如果您使用 OneLake，请将credentials.connectionString设置为ResourceId={{workspaceId}}，将container.name设置为{{lakehouseId}}。

创建技能集

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

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

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

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

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

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

请在 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。

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

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

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

     {
       "@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 视觉多模态嵌入功能以公开预览提供。若要调用此技能，请使用最新的预览 API。

如果您正在使用 Azure Vision 多模式嵌入技能，请在skills数组后附加 AI 服务资源。此附件用于计费目的。

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

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

创建矢量索引

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

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

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

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

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

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

向部分添加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 将算法配置链接到可分配给向量字段的配置文件。

根据嵌入模型，更新 vectorSearch.algorithms.metric。距离指标cosine的有效值为、dotproduct和euclideanhamming。

向数组 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"
      }
    ]

根据嵌入技能，为每个向量字段设置 dimensions 为以下值。

嵌入技能输入本值

Azure 视觉服务 1024

嵌入技能	输入本值
Azure 视觉服务	`1024`

将向量器添加到索引

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

请在之后添加 vectorSearch.profiles。可以粘贴以下定义之一。

      "profiles": [ ... ],
      "vectorizers": [
        {
          "name": "my-ai-services-vision-vectorizer",
          "kind": "aiServicesVision",
          "aiServicesVisionParameters": {
            "resourceUri": "{{AiAI servicesEndpoint}}",
            "modelVersion": "2023-04-15"
          }
        }
      ]

注释

Azure视觉矢量化工具正在公开预览。如果要调用此向量器，请使用预览 API，例如 2025-03-01-preview。

在vectorSearch.profiles中指定向量器。

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

创建索引器

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

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

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

若要创建索引器，请选择“ 发送请求”。

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

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

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

### 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视觉矢量化工具正在公开预览。如果以前调用此向量器，请使用预览 API，例如 2025-03-01-preview。

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

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

Last updated on 2026-03-25