Azure OpenAI Embedding 技能

2025-06-13

Azure OpenAI 嵌入技能连接到Azure OpenAI资源上已部署的嵌入模型，以在索引期间生成嵌入项。数据在部署模型的地理位置进行处理。

先决条件

Azure AI Foundry Models 资源中的 Azure OpenAI 必须具有关联的自定义子域。如果服务是通过 Azure 门户创建的，则会在服务设置过程中自动生成此子域。确保在将服务与 Azure AI 搜索集成之前包含自定义子域。

不支持在 Azure AI Foundry 门户中创建的 Azure OpenAI 资源（有权访问嵌入模型）。只有 Azure 门户中创建的 Azure OpenAI 资源与 Azure OpenAI 嵌入 技能集成兼容。

Azure 门户中的导入和矢量化数据向导使用Azure OpenAI 嵌入技能来矢量化内容。你可以运行向导并查看生成的技能集，了解向导如何构建用于嵌入模型的技能。

注意

此技能绑定到 Azure OpenAI，并按现有的 Azure OpenAI 标准版价格收费。

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

数据限制

文本输入的最大大小应为 8,000 个标记。如果输入超出允许的最大值，模型将引发“请求无效”错误。有关详细信息，请参阅 Azure OpenAI 文档中的令牌关键概念。如果需要数据分块，请考虑使用文本拆分技能。

技能参数

参数区分大小写。

输入	说明
`resourceUri`	在本例中，模型提供程序的 URI 是 Azure OpenAI 资源。此参数仅支持带有域名 `openai.azure.com` 的 URL，例如 `https://<resourcename>.openai.azure.com`。如果 Azure OpenAI 终结点具有带域名 `cognitiveservices.azure.com` 的 URL（如 `https://<resourcename>.cognitiveservices.azure.com`），则必须先为 Azure OpenAI 资源创建一个带的`openai.azure.com`，然后改用 `https://<resourcename>.openai.azure.com`。
`apiKey`	用于访问模型的密钥。如果你提供密钥，请将 `authIdentity` 留空。如果同时设置 `apiKey` 和 `authIdentity`，则会在连接上使用 `apiKey` =。
`deploymentId`	已部署的 Azure OpenAI 嵌入模型的名称。模型应该是嵌入模型，例如 text-embedding-ada-002。有关支持的模型，请参阅 Azure OpenAI 模型列表。
`authIdentity`	搜索服务用于连接到 Azure OpenAI 的用户托管标识。可以使用系统托管标识或用户托管标识。若要使用系统托管标识，请保留并`apiKey`留`authIdentity`空。会自动使用系统托管标识。托管标识必须具有认知服务 OpenAI 用户权限才能将文本发送到 Azure OpenAI。
`modelName`	如果技能集是使用 2024-05-01-preview 或 2024-07-01 REST API 创建的，则此属性是必需的。将此属性设置为在提供程序（通过`resourceUri`指定，通过`deploymentId`确定）上部署的 Azure OpenAI 嵌入模型部署名称。目前受支持的值为`text-embedding-ada-002`、`text-embedding-3-large`和`text-embedding-3-small`。
`dimensions`	（可选）从 2024-05-01-preview REST API 开始，假设模型支持一系列维度，则表示要生成的嵌入维度的维度。下面列出了支持的范围，目前仅适用于文本嵌入-3 模型系列。默认值是每个模型的最大维度。对于使用早期 REST API 版本创建的技能集，可追溯到 2023-10-01-preview，维度固定在 1536。在技能上设置维度属性时，请确保将`dimensions`向量字段定义上的属性设置为相同的值。

`modelName`支持的维度

Azure OpenAI 嵌入技能支持的维度取决于配置的modelName。

`modelName`	最小维度	最大维度
text-embedding-ada-002	1536	1536
text-embedding-3-large	1	3072
text-embedding-3-small	1	1536

技能输入

输入	说明
`text`	要矢量化的输入文本。如果使用数据分块，则源可能是 `/document/pages/*`。

技能输出

输出	说明
`embedding`	输入文本的矢量化嵌入。

示例定义

考虑具有以下字段的记录：

{
    "content": "Microsoft released Windows 10."
}

然后，技能定义可能会如下所示：

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://my-demo-openai-chinaeast.openai.azure.com/",
  "deploymentId": "my-text-embedding-ada-002-model",
  "modelName": "text-embedding-ada-002",
  "dimensions": 1536,
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

示例输出

对于给定的输入文本，将生成矢量化嵌入输出。

{
  "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... 
        0.021276434883475304,
      ]
}

输出驻留在内存中。若要将此输出发送到搜索索引中的字段，必须定义一个 outputFieldMapping，用于将矢量化的嵌入输出（即数组）映射到一个矢量字段。假设技能输出驻留在文档的嵌入节点中，且 content_vector 是搜索索引中的字段，那么索引器中的 outputFieldMapping 应如下所示：

  "outputFieldMappings": [
    {
      "sourceFieldName": "/document/embedding/*",
      "targetFieldName": "content_vector"
    }
  ]

错误和警告

条件	结果
null 或无效 URI	错误
null 或无效的 deploymentID	错误
文本为空	警告
文本大于 8,000 个标记	错误

通过