你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。 它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

Important

这些特性和功能支持与其他Microsoft 服务和第三方服务的连接。 使用这些服务受其各自的条款的约束，可能会导致数据处理或存储超出Azure符合性边界，以及流入Azure符合性边界的数据。

您有责任管理您的数据是否会流出您组织的合规和地理边界之外及其任何相关影响，并确保已配置适当的权限、边界和审批。

你负责仔细查看和测试在特定用例上下文中生成的应用程序，并做出所有适当的决策和自定义。 这包括实施自己的负责任的 AI 缓解措施，例如元系统、内容筛选器或其他安全系统，并确保应用程序满足适当的质量、可靠性、安全性和可信度标准。 有关详细信息，请参阅 Azure AI 搜索 透明度说明。

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

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

先决条件

支持的数据源

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

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

Azure 门户中 Azure Data Lake Storage 帐户的截图。
Microsoft OneLake 此数据源连接到 OneLake 文件和快捷方式。

支持的嵌入模型

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

供应商 支持的模型
Azure OpenAI 资源1、2 text-embedding-ada-002
text-embedding-3-small
text-embedding-3-large
Microsoft Foundry 资源3 对于文本和图像：Azure视觉多模态4

1 Azure OpenAI 资源的终结点必须具有一个自定义子域，例如 。 如果在 Azure 门户中创建了资源，则此子域是在资源设置过程中自动生成的。

不支持在 Microsoft Foundry 门户中创建的 2 个 Azure OpenAI 资源（这些资源可以访问嵌入模型）。 必须在Azure门户中创建 Azure OpenAI 资源。

3 出于计费目的，必须将 Microsoft Foundry 资源附加到 Azure AI 搜索技能组。 除非使用 无键连接 来创建技能集，否则这两个资源必须位于同一区域。

4 Azure 视觉多模式嵌入模型在 选择区域 中可用。

基于角色的访问

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

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

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

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

注意

免费搜索服务支持与Azure AI 搜索的基于角色的连接。 但是，它们不支持在与 Azure 存储 或 Azure Vision 的出站连接中使用托管标识。 此行为要求对免费搜索服务和其他Azure资源之间的连接使用基于密钥的身份验证。

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

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

提示

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

  1. 在 Azure 门户 中转到你的搜索服务。

  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

准备您的数据

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

  1. 在 Azure 门户 中转到 Azure 存储帐户。

  2. 在左窗格中，选择 “数据存储>容器”。

  3. 创建容器或选择现有容器，然后将文件上传到容器。

  4. 若要分配角色，请执行以下操作：

    1. 在左窗格中，选择访问控制 （IAM）。

    2. 选择 添加>角色分配。

    3. 在 “作业功能角色”下，选择 存储 Blob 数据读取者，然后选择 下一步。

    4. 在Members下，选择Managed identity，然后选择Select members。

    5. 选择订阅和搜索服务的托管标识信息。

  5. 若要获取连接字符串，

    1. 在左窗格中，选择 “安全性 + 网络>访问密钥”。

    2. 复制任一连接字符串，并在稍后的 设置变量 中进行指定。

  6. （可选）将容器中的删除与搜索索引中的删除同步。 要配置索引器以进行删除检测，请执行以下操作：

    1. 在存储帐户上启用软删除。 如果使用 本机软删除，则不需要下一步。

    2. 添加可供索引器扫描的自定义元数据，以确定哪些 Blob 被标记为删除。 为自定义属性指定描述性名称。 例如，可以命名属性“IsDeleted”并将其设置为 false。 对容器中的每个 Blob 重复此步骤。 如果要删除 Blob，请将属性更改为 true。 有关详细信息，请参阅从 Azure 存储编制索引时的更改和删除检测。

准备你的嵌入模型

在本部分中，你将通过分配角色、获取终结点和部署 supported embedding model，为集成向量化准备Azure AI 资源。

Azure AI 搜索支持 text-embedding-ada-002、text-embedding-3-small 和 text-embedding-3-large。 在内部，Azure AI 搜索调用 Azure OpenAI 嵌入技能以连接到 Azure OpenAI。

  1. 在 Azure 门户中，转到 Azure OpenAI 资源。

  2. 若要分配角色，请执行以下操作：

    1. 在左窗格中，选择“访问控制”（IAM）。

    2. 选择 添加>角色分配。

    3. 在 “作业功能角色”下，选择 “认知服务 OpenAI 用户”，然后选择“ 下一步”。

    4. 在Members下，选择Managed identity，然后选择Select members。

    5. 选择订阅和搜索服务的托管标识信息。

  3. 若要获取终结点，请执行以下操作：

    1. 在左窗格中，选择 “资源管理>密钥和终结点”。

    2. 复制 Azure OpenAI 资源的终结点。 稍后在 Set 变量中指定此 URL。

  4. 若要部署嵌入模型，请执行以下操作：

    1. 登录到 Foundry 门户并选择Azure OpenAI 资源。

    2. 部署 支持的嵌入模型。

    3. 复制稍后在 Set 变量中指定的部署和模型名称。 部署名称是所选的自定义名称，而模型名称是部署的模型，例如 text-embedding-ada-002。

设置变量

在本部分中，请指定您的 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 令牌。

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

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

  4. 根据嵌入模型提供程序的要求，添加以下变量。

    嵌入模型提供程序 变量 输入此信息
    Azure OpenAI @aoaiEndpoint、 @aoaiDeploymentName和 @aoaiModelName 您在准备嵌入模型时获取的终结点、部署名称和模型名称。
    Azure视觉系统 @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 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 内容理解技能。 文本拆分技能将文本拆分为特定长度的句子或页面，而Azure内容理解技能执行遵循段落边界的语义式布局感知分块。

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

    ### 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 视觉多模式嵌入功能以预览版提供。 若要调用此技能，请使用最新的预览 API 版本。

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

  3. 如果使用的是 Azure Vision 多模式嵌入技能，请在 数组之后skills。 此附件用于计费目的。

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

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

创建矢量索引

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

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

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

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

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

    ### 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和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视觉系统 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视觉向量器处于预览状态。 如果要调用此向量器，请使用最新的预览 API 版本。

  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=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. 使用文档 - 搜索帖子定义在查询时矢量化的查询。

    ### 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视觉向量器处于预览状态。 如果要调用此向量器，请使用最新的预览 API 版本。

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

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

相关内容

  • Last updated on