安全使用基于自有数据的 Azure OpenAI

本文介绍如何使用 Microsoft Entra ID 基于角色的访问控制、虚拟网络和专用终结点保护数据和资源，从而安全地使用基于自有数据的 Azure OpenAI。

本文仅适用于使用基于自有数据的 Azure OpenAI 处理文本。 它不适用于使用基于自有数据的 Azure OpenAI 处理图像。

数据引入体系结构

在使用基于自有数据的 Azure OpenAI 将数据从 Azure Blob 存储、本地文件或 URL 引入 Azure AI 搜索时，以下过程用于处理数据。

• 步骤 1 和步骤 2 仅用于上传文件。
• 此图中未演示将 URL 下载到 Blob 存储。 从 Internet 下载网页并上传到 Blob 存储后，步骤 3 及后续步骤是相同的。
• 在 Azure AI 搜索资源中创建两个索引器、两个索引、两个数据源和一个自定义技能。
• 区块容器是在 Blob 存储中创建的。
• 如果引入是由计划的刷新触发的，则引入过程将从步骤 7 开始。
• Azure OpenAI preprocessing-jobs API 实现 Azure AI 搜索客户技能 Web API 协议，并处理队列中的文档。
• Azure OpenAI：
  1. 在内部使用之前创建的索引器破解文档。
  2. 使用基于启发式的算法执行分块、遵守区块边界中的表布局和其他格式元素，以确保最佳分块质量。
  3. 如果选择启用矢量搜索，Azure OpenAI 将使用所选的嵌入部署在内部向量化区块。
• 处理服务监视的所有数据时，Azure OpenAI 会触发另一个索引器。
• 索引器将处理的数据存储在 Azure AI 搜索服务中。

对于服务调用中使用的托管标识，仅支持系统分配的托管标识。 不支持用户分配的托管标识。

推理体系结构

发送 API 调用以在数据上与 Azure OpenAI 模型聊天时，如果请求中未显式设置字段映射，则服务需要在推理期间检索索引字段，以便自动执行字段映射。 因此，即使在推理期间，该服务也需要 Azure OpenAI 标识为搜索服务提供 Search Service Contributor 角色。

如果在推理请求中提供了嵌入部署，则重写的查询将由 Azure OpenAI 进行矢量化，并且查询和矢量都将发送到 Azure AI 搜索进行矢量搜索。

文档级访问控制

通过基于自有数据的 Azure OpenAI，你可以使用 Azure AI 搜索安全筛选器限制可用于响应不同用户的文档。 启用文档级访问时，将基于用户 Microsoft Entra 组成员身份剪裁从 Azure AI 搜索返回并用于生成响应的搜索结果。 只能对现有 Azure AI 搜索索引启用文档级访问。 若要启用文档级访问，请执行以下操作：

1. 按照 Azure AI 搜索文档中的步骤注册应用程序并创建用户和组。

2. 使用允许的组为文档编制索引。 请确保新的安全字段具有以下架构：

   {"name": "group_ids", "type": "Collection(Edm.String)", "filterable": true }
   

   group_ids 是默认字段名称。 如果使用其他字段名称（如 my_group_ids），则可以在“索引字段映射”中映射字段。

3. 确保索引中的每个敏感文档在此安全字段上正确设置了值，以指示允许的文档组。

4. 在 Azure OpenAI Studio 中，添加数据源。 在“索引字段映射”部分中，只要架构兼容，就可以将零个或一个值映射到“允许的组”字段。 如果未映射“允许的组”字段，则不会启用文档级访问。

Azure OpenAI Studio

连接 Azure AI 搜索索引后，Studio 中的响应将具有基于登录用户 Microsoft Entra 权限的文档访问权限。

Web 应用程序

如果使用的是已发布的 Web 应用，则需要重新部署它以升级到最新版本。 最新版本的 Web 应用支持检索已登录用户的 Microsoft Entra 帐户组、对其进行缓存并在每个 API 请求中包含组 ID。

API

使用 API 时，请在每个 API 请求中传递 filter 参数。 例如：

{
    "messages": [
        {
            "role": "user",
            "content": "who is my manager?"
        }
    ],
    "dataSources": [
        {
            "type": "AzureCognitiveSearch",
            "parameters": {
                "endpoint": "'$AZURE_AI_SEARCH_ENDPOINT'",
                "key": "'$AZURE_AI_SEARCH_API_KEY'",
                "indexName": "'$AZURE_AI_SEARCH_INDEX'",
                "filter": "my_group_ids/any(g:search.in(g, 'group_id1, group_id2'))"
            }
        }
    ]
}

• my_group_ids 是在字段映射期间为“允许的组”选择的字段名称。
• group_id1, group_id2 是属于已登录用户的组。 客户端应用程序可以检索和缓存用户的组。

资源配置

根据下文内容配置资源以确保安全使用。 即使你计划仅保护部分资源，仍需执行以下步骤。

本文介绍了与禁用 Azure OpenAI 资源、Azure AI 搜索资源和存储帐户的公共网络相关的网络设置。 不支持使用具有 IP 规则的所选网络，因为服务的 IP 地址是动态的。

创建资源组

创建资源组，以便整理所有相关资源。 资源组中的资源包括但不限于：

• 一个虚拟网络
• 三项关键服务：一个 Azure OpenAI、一个 Azure AI 搜索、一个存储帐户
• 三个专用终结点，每个终结点都链接到一个密钥服务
• 三个网络接口，每个接口都与一个专用终结点相关联
• 一个虚拟网络网关，用于从本地客户端计算机进行访问
• 集成了虚拟网络的 Web 应用
• 一个专用 DNS 区域，因此 Web 应用会查找 Azure OpenAI 的 IP

创建虚拟网络

此虚拟网络有三个子网。

1. 第一个子网用于三个专用终结点的专用 IP。
2. 创建虚拟网络网关时，会自动创建第二个子网。
3. 第三个子网为空，用于 Web 应用出站虚拟网络集成。

请注意，Microsoft 托管的虚拟网络是由 Microsoft 创建的，你看不到它。 Azure OpenAI 使用 Microsoft 托管的虚拟网络安全地访问 Azure AI 搜索。

配置 Azure OpenAI

已启用自定义子域

如果通过 Azure 门户创建了 Azure OpenAI，则应已创建自定义子域。 基于 Microsoft Entra ID 的身份验证和专用 DNS 区域需要自定义子域。

启用托管标识

若要允许 Azure AI 搜索和存储帐户通过 Microsoft Entra ID 身份验证识别 Azure OpenAI 服务，需要为 Azure OpenAI 服务分配托管标识。 最简单的方法是在 Azure 门户上切换系统分配的托管标识。

若要通过管理 API 设置托管标识，请参阅管理 API 参考文档。

"identity": {
  "principalId": "12345678-abcd-1234-5678-abc123def",
  "tenantId": "1234567-abcd-1234-1234-abcd1234",
  "type": "SystemAssigned, UserAssigned", 
  "userAssignedIdentities": {
    "/subscriptions/1234-5678-abcd-1234-1234abcd/resourceGroups/my-resource-group",
    "principalId": "12345678-abcd-1234-5678-abcdefg1234", 
    "clientId": "12345678-abcd-efgh-1234-12345678"
  }
}

启用受信任的服务

若要在 Azure OpenAI 没有公用网络访问权限的情况下，允许 Azure AI 搜索以自定义技能 web API 调用 Azure OpenAI preprocessing-jobs，你需要设置 Azure OpenAI，使其基于托管标识，以受信任的服务绕过 Azure AI 搜索。 Azure OpenAI 将通过验证 JSON Web 令牌 (JWT) 中的声明来识别来自 Azure AI 搜索的流量。 Azure AI 搜索必须使用系统分配的托管标识身份验证来调用自定义技能 Web API。

从管理 API 将 networkAcls.bypass 设置为 AzureServices。 有关详细信息，请参阅虚拟网络一文。

仅当 Azure AI 搜索资源具有共享专用链接时，才能跳过此步骤。

禁用公用网络访问

你可以在 Azure 门户中禁用 Azure OpenAI 资源的公用网络访问。

若要允许从客户端计算机（例如使用 Azure OpenAI Studio）访问 Azure OpenAI 服务，需要创建连接到 Azure OpenAI 资源的专用终结点连接。

配置 Azure AI 搜索

可以对以下配置使用基本定价层和更高定价层。 这不是必要的，但如果使用 S2 定价层，你将看到可供选择的其他选项。

启用托管标识

若要允许其他服务使用 Microsoft Entra ID 身份验证识别 Azure AI 搜索，需要为 Azure AI 搜索服务分配托管标识。 最简单的方法是在 Azure 门户中将系统分配的托管标识切换为“启用”。

启用基于角色的访问控制

由于 Azure OpenAI 使用托管标识访问 Azure AI 搜索，因此需要在 Azure AI 搜索中启用基于角色的访问控制。 若要在 Azure 门户中执行此操作，请在 Azure 门户的“密钥”选项卡中选择“两者”。

要使用 REST API 启用基于角色的访问控制，请将 authOptions 设置为 aadOrApiKey。 有关详细信息，请参阅 Azure AI 搜索 RBAC 一文。

"disableLocalAuth": false,
"authOptions": { 
    "aadOrApiKey": { 
        "aadAuthFailureMode": "http401WithBearerChallenge"
    }
}

若要使用 Azure OpenAI Studio，无法为 Azure AI 搜索禁用基于 API 密钥的身份验证，因为 Azure OpenAI Studio 使用 API 密钥从浏览器调用 Azure AI 搜索 API。

禁用公用网络访问

你可以在 Azure 门户中禁用 Azure AI 搜索资源的公用网络访问。

若要允许从客户端计算机（例如使用 Azure OpenAI Studio）访问 Azure AI 搜索资源，需要创建连接到 Azure AI 搜索资源的专用终结点连接。

专用终结点资源在 Microsoft 托管租户中预配，而链接的资源则位于你的租户中。 仅通过单击“网络”页面“专用访问”选项卡中的“专用终结点”链接（蓝色字体），无法访问专用终结点资源。 相反，单击行上的任何其他位置后，应该能够单击上面的“批准”按钮。

详细了解手动审批工作流。

创建共享专用链接

本部分仅适用于 S2 定价层搜索资源，因为它需要包含技能集的索引器的专用终结点支持。

若要从连接到 Azure OpenAI 资源的搜索资源创建共享专用链接，请参阅搜索文档。 选择“资源类型”作为 Microsoft.CognitiveServices/accounts，“组 ID”作为 openai_account。

使用共享专用链接时，数据引入体系结构关系图的步骤 8 从“绕过受信任的服务”更改为“专用终结点”。

创建的 Azure AI 搜索共享专用链接也位于 Microsoft 托管虚拟网络中，而不是你的虚拟网络中。 与之前创建的其他托管专用终结点相比，不同之处在于，从 Azure OpenAI 到 Azure 认知搜索的托管专用终结点 [1] 是通过表单应用程序预配的，而从 Azure 认知搜索到 Azure OpenAI 的托管专用终结点 [2] 是通过 Azure 门户或 Azure 认知搜索的 REST API 预配的。

配置存储帐户

启用受信任的服务

若要在存储帐户没有公共网络访问权限的情况下，允许从 Azure OpenAI 和 Azure AI 搜索访问存储帐户，需要设置存储帐户，使其基于托管标识，以受信任的服务绕过 Azure OpenAI 和 Azure AI 搜索。

在 Azure 门户中，导航到存储帐户网络选项卡，选择“所选网络”，然后选择“允许受信任的服务列表中的 Azure 服务访问此存储帐户”，并单击“保存”。

禁用公用网络访问

你可以在 Azure 门户中禁用存储帐户的公用网络访问。

若要允许从客户端计算机（例如使用 Azure OpenAI Studio）访问存储帐户，需要创建连接到 blob 存储的专用终结点连接。

角色分配

到目前为止，你已独立设置每个资源工作。 接下来，需要允许服务相互授权。

角色	被分派人	资源	说明
Search Index Data Reader	Azure OpenAI	Azure AI 搜索	推理服务从索引中查询数据。
Search Service Contributor	Azure OpenAI	Azure AI 搜索	推理服务查询自动字段映射的索引架构。 数据引入服务创建索引、数据源、技能集、索引器并查询索引器状态。
Storage Blob Data Contributor	Azure OpenAI	存储帐户	从输入容器读取，并将预处理结果写入输出容器。
Cognitive Services OpenAI Contributor	Azure AI 搜索	Azure OpenAI	自定义技能
Storage Blob Data Contributor	Azure AI 搜索	存储帐户	读取 Blob 和写入知识存储。

在上表中，Assignee 表示该资源的系统分配的托管标识。

管理员需要拥有针对这些资源的 Owner 角色才能添加角色分配。

有关在 Azure 门户中设置这些角色的说明，请参阅 Azure RBAC 文档。 可以使用 GitHub 上可用的脚本以编程方式添加角色分配。

若要使开发人员能够使用这些资源来生成应用程序，管理员需要向资源添加具有以下角色分配的开发人员标识。

角色	资源	说明
Cognitive Services OpenAI Contributor	Azure OpenAI	从 Azure OpenAI Studio 调用公共引入 API。 Contributor 角色是不够的，因为如果只有 Contributor 角色，你将无法通过 Microsoft Entra ID 身份验证调用数据平面 API，并且本文所述的安全设置中需要 Microsoft Entra ID 身份验证。
Cognitive Services User	Azure OpenAI	从 Azure OpenAI Studio 列出 API 密钥。
Contributor	Azure AI 搜索	列出用于列出 Azure OpenAI Studio 中的索引的 API 密钥。
Contributor	存储帐户	列出帐户 SAS 以从 Azure OpenAI Studio 上传文件。
Contributor	开发人员需要将 Web 应用部署到其中的资源组或 Azure 订阅	将 Web 应用部署到开发人员的 Azure 订阅。

配置网关和客户端

若要从本地客户端计算机访问 Azure OpenAI 服务，其中一种方法是配置 Azure VPN 网关和 Azure VPN 客户端。

按照此指南为你的虚拟网络创建虚拟网络网关。

按照此准则添加点到站点配置，并启用基于 Microsoft Entra ID 的身份验证。 下载 Azure VPN 客户端配置文件配置包、解压缩 AzureVPN/azurevpnconfig.xml 文件并将其导入 Azure VPN 客户端。

将本地计算机 hosts 文件配置为将资源主机名指向虚拟网络中的专用 IP。 hosts 文件在 Windows 上位于 C:\Windows\System32\drivers\etc，在 Linux 上位于 /etc/hosts。 示例：

10.0.0.5 contoso.openai.azure.com
10.0.0.6 contoso.search.windows.net
10.0.0.7 contoso.blob.core.windows.net

Azure OpenAI Studio

你应该能够在本地客户端计算机上使用所有 Azure OpenAI Studio 功能，包括引入和推理。

Web 应用程序

Web 应用会与 Azure OpenAI 资源通信。 由于 Azure OpenAI 资源已禁用公用网络，因此需要设置 Web 应用才能使用虚拟网络中的专用终结点访问 Azure OpenAI 资源。

Web 应用需要将 Azure OpenAI 主机名解析为 Azure OpenAI 专用终结点的专用 IP。 因此，首先需要为虚拟网络配置专用 DNS 区域。

1. 在资源组中创建专用 DNS 区域。
2. 添加 DNS 记录。 该 IP 是 Azure OpenAI 资源的专用终结点的专用 IP，你可以从与 Azure OpenAI 的专用终结点关联的网络接口获取该 IP 地址。
3. 将专用 DNS 区域链接到虚拟网络，以便此虚拟网络中集成的 Web 应用可以使用此专用 DNS 区域。

从 Azure OpenAI Studio 部署 Web 应用时，请选择与虚拟网络相同的位置，并选择适当的 SKU，以便它支持虚拟网络集成功能。

部署 Web 应用后，在 Azure 门户网络选项卡中，配置 Web 应用出站流量虚拟网络集成，选择为 Web 应用保留的第三个子网。

使用 API

确保登录凭据在 Azure OpenAI 资源上具有 Cognitive Services OpenAI Contributor 角色，并首先运行 az login。

引入 API

有关引入 API 使用的请求和响应对象的详细信息，请参阅引入 API 参考一文。

更多备注：

• API 路径中的 JOB_NAME 将用作 Azure AI 搜索中的索引名称。
• 使用 Authorization 标头而不是 api 密钥。
• 显式设置 storageEndpoint 标头：
• 为 storageConnectionString 标头使用 ResourceId= 格式，以便 Azure OpenAI 和 Azure AI 搜索使用托管标识对存储帐户进行身份验证，这是绕过网络限制所必需的。
• 不要设置 searchServiceAdminKey 标头。 Azure OpenAI 资源的系统分配标识将用于对 Azure AI 搜索进行身份验证。
• 不要设置 embeddingEndpoint 或 embeddingKey。 而是用 embeddingDeploymentName 标头启用文本矢量化。

提交作业示例

accessToken=$(az account get-access-token --resource https://cognitiveservices.azure.com/ --query "accessToken" --output tsv)
curl -i -X PUT https://my-resource.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/vpn1025a?api-version=2023-10-01-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $accessToken" \
-H "storageEndpoint: https://mystorage.blob.core.windows.net/" \
-H "storageConnectionString: ResourceId=/subscriptions/1234567-abcd-1234-5678-1234abcd/resourceGroups/my-resource/providers/Microsoft.Storage/storageAccounts/mystorage" \
-H "storageContainer: my-container" \
-H "searchServiceEndpoint: https://mysearch.search.windows.net" \
-H "embeddingDeploymentName: ada" \
-d \
'
{
}
'

获取作业状态示例

accessToken=$(az account get-access-token --resource https://cognitiveservices.azure.com/ --query "accessToken" --output tsv)
curl -i -X GET https://my-resource.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/abc1234?api-version=2023-10-01-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $accessToken"

推理 API

有关推理 API 使用的请求和响应对象的详细信息，请参阅推理 API 参考一文。