Azure OpenAI 嵌入技能

Azure OpenAI Embedding 技能连接到部署在你的 Azure OpenAI in Foundry Models 资源或 Microsoft Foundry 项目中的嵌入模型，用于在索引过程中生成嵌入。 你的数据会在模型部署的 地理环境中 处理。

Azure门户中的Import data向导使用Azure OpenAI嵌入技能来向量内容。 你可以运行向导，查看生成的技能集，看看向导是如何构建嵌入模型的技能的。

先决条件

• 一个Azure OpenAI in Foundry Models资源或 Foundry 项目。

  • 你的Azure OpenAI资源必须有自定义子域名，比如https://<resource-name>.openai.azure.com。 你可以在Azure门户的Keys and Endpoint页面找到这个端点，并用它来实现该技能中的resourceUri属性。

  • 你的 Foundry 项目的 父资源 提供访问多个端点，包括 https://<resource-name>.openai.azure.com、 https://<resource-name>.services.ai.azure.com和 https://<resource-name>.cognitiveservices.azure.com。 你可以在Azure门户的Keys和Endpoint页面找到这些端点，并用它们作为该技能中的resourceUri属性。

• 部署到您的资源或项目中的 Azure OpenAI 嵌入模型。 关于支持的模型，请参见 技能参数 部分。

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

数据限制

文本输入的最大容量应为8,000个令牌。 如果输入超过允许的最大值，模型会抛出无效请求错误。 更多信息请参见Azure OpenAI文档中的tokens关键概念。 如果你需要数据分块，可以考虑使用 文本分割技能 。

技能参数

参数区分大小写。

支持的维度由 modelName

Azure OpenAI 嵌入技能支持的尺寸取决于所配置的 modelName。

技能输入

技能输出

示例定义

考虑一个记录，其字段如下：

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

那么你的技能定义可能如下：

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://my-demo-openai-eastus.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"
    }
  ]

最佳做法

以下是你在使用这项技能时需要考虑的一些最佳实践：

• 如果你已经达到Azure OpenAI每分钟代币数（TPM）上限，可以考虑quota limits advisory以便相应应对。 请参阅 Azure OpenAI monitoring 文档，了解您的 OpenAI 实例Azure性能。

• 你用来部署该技能的Azure OpenAI嵌入模型，理想情况下应该与其他用例（包括query vectorizer的部署分开。 这有助于每次部署针对其具体用例进行定制，从而优化性能，并轻松识别来自索引器和索引嵌入调用的流量。

• 你的 Azure OpenAI 实例应该位于同一个区域，或者至少地理上接近你 AI 搜索服务托管的区域。 这降低了延迟，提高了服务间的数据传输速度。

• 为了避免经常遇到 429 错误代码，请考虑通过 API 管理实现负载均衡，方法是在多个 Azure OpenAI 嵌入模型部署前实现网关。

• 如果你的OpenAI TPM（每分钟代币数）Azurequotas and limits文档中发布的限制大于默认，请向Azure AI 搜索团队support提交申诉，以便相应调整。 这有助于避免因默认TPM限制而被记录的TPM限制不必要地拖慢，如果你的TPM限制更高。

• 有关使用该技能的示例和实际代码示例，请参见以下链接：

  • 集成矢量化（Python）
  • 集成矢量化（C#）
  • 积分矢量化（Java）

错误与警告

托管标识身份验证的安全注意事项

Azure OpenAI 嵌入技能使用托管标识身份验证时，Azure AI 搜索获取 Foundry 工具受众（https://cognitiveservices.azure.com）的Microsoft Entra访问令牌，并将其包含在发送到终结点resourceUri的请求中。 托管标识身份验证适用于设置时authIdentity或同时为apiKeyauthIdentity空且服务使用系统分配的标识。

引用的resourceUri终结点应是自己的Azure OpenAI 或 Foundry Tools 资源。 支持的域名有：

• openai.azure.com
• cognitiveservices.azure.com
• services.ai.azure.com

还支持Azure API 管理（APIM）终结点（*.azure-api.net）。 由于 APIM 主机名不能单独从其名称进行验证，因此Azure AI 搜索在配置时通过实时连接检查来验证这些终结点，而不是通过域匹配进行验证。 你负责配置和维护 APIM 终结点与其后面的 Azure OpenAI 或 Foundry Tools 资源之间的关系。

为 Foundry 工具访问群体颁发的托管标识令牌对任何 Foundry 工具或Azure OpenAI 资源有效，该标识已授权。 将其发送到不受信任的终结点可能会公开令牌。

建议的安全做法

若要帮助维护安全部署，请遵循以下做法：

• 仅设置为 resourceUri 你拥有和信任的终结点。 首选前面列出的 Foundry Tools 域。 如果使用 APIM 终结点，请在启用托管标识之前确认它位于自己的资源前面。 受信任的主机名不是所有权证明。
• 将最低特权原则应用于搜索服务使用的托管标识。 Azure OpenAI 嵌入技能只需要目标资源上的认知服务 OpenAI 用户角色。 避免授予更广泛的角色。
• 使用 网络安全外围（NSP） 和专用终结点或 VNet 集成来限制搜索服务可以访问的终结点，以及目标资源接受来自哪些源的请求。
• 如果使用 APIM 终结点，请确保网关验证入站请求，并仅将它们转发到预期的后端。 还应定期查看其访问策略。
• 首选托管标识而不是 apiKey。 如果使用 apiKey，请安全地存储和旋转它，不要将其嵌入源代码管理中。 服务拒绝同时设置 apiKey 和 authIdentity设置的配置。
• 定期查看技能组定义、托管标识角色分配和 APIM 配置，以确认 resourceUri 值、访问控制和标识权限保持最新且合适。 通过建立的变更管理和安全评审流程查看配置更改。
• 监视 Azure OpenAI 和 Foundry Tools 登录日志、身份验证事件和访问日志，以获取意外或未经授权的活动。
• 删除不再需要的技能、终结点、角色分配和 API 密钥。

限制对技能集配置的访问

可以创建、修改或运行技能集的用户控制目标终结点（resourceUri）和技能使用的身份验证配置。 由于技能向该终结点发送 Foundry 工具受众的托管标识令牌，因此请在配置已启用托管标识的技能时将这些权限限制为受信任的管理员，并遵循标准变更管理和安全评审过程。

另请参阅

• 内置技能
• 如何定义技能组
• 如何定义输出场映射