Python 聊天文档安全性入门

项目
01/04/2025

当您使用检索增强生成 (RAG) 模式和自己的数据生成聊天应用程序时，请确保每个用户都根据其权限接收答案。按照本文中的过程将文档访问控制添加到聊天应用。

授权用户：此人应有权访问聊天应用文档中包含的答案。
未经授权的用户：此人不应有权访问他们无权查看的安全文档的答案。

注意

本文使用一个或多个 AI 应用模板作为本文中的示例和指南的基础。 AI 应用模板提供易于部署的维护良好的参考实现。它们有助于确保你的 AI 应用有一个高质量的起点。

体系结构概述

如果没有文档安全功能，企业聊天应用使用 Azure AI 搜索和 Azure OpenAI 提供简单的体系结构。答案是通过查询存储文档的 Azure AI 搜索并结合 Azure OpenAI GPT 模型的响应来确定的。此简单流中不使用用户身份验证。

此体系结构图显示了根据对存储文档的 Azure AI 搜索的查询确定的回答，以及来自 Azure OpenAI 的提示响应。

若要为文档添加安全性，需要更新企业聊天应用：

使用 Microsoft Entra 将客户端身份验证添加到聊天应用。
添加服务器端逻辑，以使用用户和组访问权限填充搜索索引。

体系结构图，显示了利用 Microsoft Entra ID 进行身份验证，然后将该身份验证传递给 Azure AI 搜索。

Azure AI 搜索不提供本地的文档级权限，并且不能根据不同用户权限在索引内变化搜索结果。相反，应用程序可以使用搜索筛选器来确保特定用户或特定组可以访问文档。在搜索索引中，每个文档都应具有一个可筛选字段，用于存储用户或组标识信息。

由于授权并非 Azure AI 搜索中原本包含的内容，因此你需要添加一个字段来保存用户或组信息，然后筛选任何不匹配的文档。若要实现此技术，需要：

在索引中创建文档访问控制字段，专用于存储具有文档访问权限的用户或组的详细信息。
使用相关的用户或组详细信息填充文档的访问控制字段。
每当用户或组访问权限发生更改时，更新此访问控制字段。

如果索引更新是由索引器调度的，则在索引器下次运行时会获取更改。如果不使用索引器，则需要手动重新编制索引。

在本文中，作为搜索管理员，您可以通过运行示例脚本，实现对 Azure AI 搜索中的文档的保护过程。这些脚本将单个文档与单个用户标识相关联。你可以使用这些脚本，并应用自己的安全和生产要求来按需求进行缩放。

确定安全配置

该解决方案提供布尔环境变量，用于启用在该示例中确保文档安全性所需的功能。

参数	目的
`AZURE_USE_AUTHENTICATION`	设置为 `true`时，允许用户登录到聊天应用和 Azure 应用服务身份验证。在聊天应用开发人员设置中启用 `Use oid security filter`。
`AZURE_ENFORCE_ACCESS_CONTROL`	设置为 `true`时，需要对任何文档访问进行身份验证。对象 ID (OID) 和组安全性开发人员设置已打开并禁用，以便无法从 UI 中禁用它们。
`AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS`	设置为 `true`时，此设置允许经过身份验证的用户搜索未分配访问控制的文档，即使需要访问控制也是如此。仅当启用 `AZURE_ENFORCE_ACCESS_CONTROL` 时，才应使用此参数。
`AZURE_ENABLE_UNAUTHENTICATED_ACCESS`	如果设置为 `true`，此设置允许未经身份验证的用户使用应用，即使强制执行访问控制也是如此。仅当启用 `AZURE_ENFORCE_ACCESS_CONTROL` 时，才应使用此参数。

请使用以下部分了解此示例中支持的安全概况。本文配置企业配置文件。

企业：必需的帐户 + 文档筛选器

站点的每个用户都必须登录。该网站包含对所有用户开放的内容。文档级安全筛选器应用于所有请求。

环境变量：

AZURE_USE_AUTHENTICATION=true
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
AZURE_ENFORCE_ACCESS_CONTROL=true

混合使用：可选帐户 + 文档筛选器

站点的每个用户都可以登录。该网站包含向所有用户公开的内容。文档级安全筛选器应用于所有请求。

环境变量：

AZURE_USE_AUTHENTICATION=true
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
AZURE_ENFORCE_ACCESS_CONTROL=true
AZURE_ENABLE_UNAUTHENTICATED_ACCESS=true

先决条件

开发容器环境提供了完成本文所需的所有依赖项。可以在浏览器中的 GitHub Codespaces 或通过 Visual Studio Code 在本地运行开发容器。

若要使用本文，需要满足以下先决条件：

Azure 订阅。免费创建一个。
Azure 帐户权限：Azure 帐户必须具有：
- 管理 Microsoft Entra ID 中的应用程序的权限。
- Microsoft.Authorization/roleAssignments/write 权限，例如用户访问管理员或所有者。

需要更多先决条件，具体取决于首选的开发环境。

GitHub Codespaces （建议）
Visual Studio Code

GitHub 帐户

打开开发环境

现在开始使用已安装所有依赖项的开发环境，以便完成本文。

GitHub Codespaces （建议）
Visual Studio Code

GitHub Codespaces 运行由 GitHub 托管的开发容器，Visual Studio Code for web 作为用户界面。对于最直接的开发环境，请使用 GitHub Codespaces，以便预先安装正确的开发人员工具和依赖项来完成本文。

重要

所有 GitHub 帐户每月最多可以使用 GitHub Codespaces 60 小时，其中包含两个核心实例。有关详细信息，请参阅 GitHub Codespaces 每月包含的存储和核心小时数。

开始在 Azure-Samples/azure-search-openai-demo GitHub 存储库 main 分支上创建新的 GitHub 代码空间的过程。
右键单击以下按钮，并选择 在新窗口 中打开链接，让开发环境和文档同时可用。
在 创建 codespace 页上，查看 codespace 配置设置，然后选择 创建新的 codespace。
等待 Codespace 启动。此启动过程可能需要几分钟时间。
在屏幕底部的终端中，使用 Azure 开发人员 CLI 登录到 Azure。
```
azd auth login
```
完成身份验证过程。
本文中的剩余任务发生在此开发容器的上下文中。

Visual Studio Code 的开发容器扩展要求在本地计算机上安装 Docker。扩展使用 Docker 主机在本地托管开发容器，并预安装正确的开发人员工具和依赖项来完成本文。

在计算机上为项目创建新的本地目录。

mkdir my-intelligent-app && cd my-intelligent-app

在该目录中打开 Visual Studio Code。
```
code .
```
在 Visual Studio Code 中打开新终端。
运行以下命令 AZD 命令，将 GitHub 存储库引入本地计算机。
```
azd init -t azure-search-openai-demo
```
打开命令面板，搜索并选择 开发容器：在容器中打开文件夹 以在开发容器中打开项目。等到开发容器打开，然后继续。
使用 Azure 开发人员 CLI 登录到 Azure。
```
azd auth login
```
从终端复制代码，然后将其粘贴到浏览器中。按照说明使用 Azure 帐户进行身份验证。
项目中的剩余练习将在此开发容器的环境中进行。

使用 Azure CLI 获取所需信息

使用以下 Azure CLI 命令获取订阅 ID 和租户 ID。复制要用作 AZURE_TENANT_ID 值的值。

az account list --query "[].{subscription_id:id, name:name, tenantId:tenantId}" -o table

如果你收到有关租户条件访问策略的错误，则需要没有条件访问策略的第二个租户。

与用户帐户关联的第一个租户用于 AZURE_TENANT_ID 环境变量。
无条件访问的第二个租户用于让 AZURE_AUTH_TENANT_ID 环境变量访问 Microsoft Graph。对于具有条件访问策略的租户，请查找没有条件访问策略的第二个租户的 ID。或者创建新租户。

设置环境变量

运行以下命令，为企业配置文件配置应用程序。

azd env set AZURE_USE_AUTHENTICATION true
azd env set AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS true
azd env set AZURE_ENFORCE_ACCESS_CONTROL true

运行以下命令来设置租户，该租户授权用户登录到托管的应用程序环境。将 <YOUR_TENANT_ID> 替换为租户 ID。
```
azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
```

注意

如果您在用户租户中设置了条件访问策略，则需要指定一个身份验证租户。

将聊天应用部署到 Azure

部署由以下步骤组成：

创建 Azure 资源。
上传文档。
创建Microsoft Entra 标识应用（客户端和服务器）。
打开托管资源的标识。

运行以下 Azure 开发人员 CLI 命令来预配 Azure 资源并部署源代码。
```
azd up
```

使用下表回答 AZD 部署提示。

提示	答
环境名称	请使用简短名称，并包含如别名和应用程序等标识信息。示例是 `tjones-secure-chat`。
订阅	选择一个创建资源的订阅。
Azure 资源的位置	选择你附近的位置。
`documentIntelligentResourceGroupLocation` 的位置	选择你附近的位置。
`openAIResourceGroupLocation` 的位置	选择你附近的位置。

在应用部署后等待 5 或 10 分钟，以允许应用启动。

应用程序成功部署后，终端中会显示一个 URL。
选择标记为 (✓) Done: Deploying service webapp 的 URL，在浏览器中打开聊天应用程序。
同意应用身份验证弹出窗口。
聊天应用出现时，请注意右上角表明你的用户已登录。
打开 开发人员设置，并注意到以下两个选项被选中且无法更改：
- 使用 oid 安全筛选器
- 使用组安全筛选器
选择写有产品经理的作用是什么？的卡片。
获得如下答案：提供的源不包含有关 Contoso Electronics 产品经理角色的特定信息。

为用户打开对文档的访问权限

打开具体文档的权限，以便你能够获取答案。需要几条信息：

Azure 存储
- 帐户名称
- 容器名称
- role_library.pdf 的 Blob/文档 URL
Microsoft Entra ID 中的用户 ID

当此信息已知时，请更新 role_library.pdf 文档的 Azure AI 搜索索引 oids 字段。

获取存储中的文档的 URL

在项目的根目录 .azure 文件夹中，找到环境目录，并使用该目录打开 .env 文件。
搜索 AZURE_STORAGE_ACCOUNT 项并复制其值。
使用以下 Azure CLI 命令获取 content 容器中 role_library.pdf blob 的 URL。
```
az storage blob url \
    --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
    --container-name 'content' \
    --name 'role_library.pdf' 
```
参数目的

--account-name Azure 存储帐户名称。

--container-name 此示例中的容器名称 content。

--名字在此步骤中，blob 名称是 role_library.pdf。
复制 Blob URL 以供以后使用。

参数	目的
--account-name	Azure 存储帐户名称。
--container-name	此示例中的容器名称 `content`。
--名字	在此步骤中，blob 名称是 `role_library.pdf`。

获取用户 ID

在聊天应用中，选择开发人员设置。
在 ID 令牌声明部分，复制 objectidentifier 参数。下一节中已知此参数为 USER_OBJECT_ID。

在 Azure 搜索中提供对文档的用户访问权限

使用以下脚本更改 Azure AI 搜索 role_library.pdf 中的 oids 字段，以便你有权访问该字段。

./scripts/manageacl.sh \
    -v \
    --acl-type oids \
    --acl-action add \
    --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
    --url <REPLACE_WITH_YOUR_DOCUMENT_URL>

参数	目的
-v	详细输出。
--acl-type	组或用户 OID：`oids`。
--acl-action	向搜索索引字段添加。其他选项包括 `remove`、`remove_all`和 `list`。
--acl	组或用户 `USER_OBJECT_ID`。
--url	文件在 Azure 存储中的位置，例如 `https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf`。不要在 CLI 命令中用引号将 URL 括起来。

此命令的控制台输出如下所示：

Loading azd .env file from current environment...
Creating Python virtual environment "app/backend/.venv"...
Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action add --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
Adding acl 00000000-0000-0000-0000-000000000000 to 58 search documents

（可选）使用以下命令验证文件的权限是否列在 Azure AI Search 中。

./scripts/manageacl.sh \
    -v \
    --acl-type oids \
    --acl-action list \
    --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
    --url <REPLACE_WITH_YOUR_DOCUMENT_URL>

参数	目的
-v	详细输出。
--acl-type	组或用户 OID：`oids`。
--acl-action	列出搜索索引字段 `oids`。其他选项包括 `remove`、`remove_all`和 `list`。
--acl	组或用户的 `USER_OBJECT_ID` 参数。
--url	文件的位置，其中显示 `https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf` 等内容。不要在 CLI 命令中用引号将 URL 括起来。

此命令的控制台输出如下所示：

Loading azd .env file from current environment...
Creating Python virtual environment "app/backend/.venv"...
Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action view --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
[00000000-0000-0000-0000-000000000000]

输出末尾的数组包括你的 USER_OBJECT_ID 参数，用于确定是否在 Azure OpenAI 的回答中使用文档。

请验证 Azure AI 搜索是否包含您的 USER_OBJECT_ID

打开 Azure 门户并搜索 AI Search。
从列表中选择搜索资源。
选择搜索管理>索引。
选择 gptkbindex。
选择视图>JSON 视图。
将 JSON 替换为以下 JSON：
```
{
  "search": "*",
  "select": "sourcefile, oids",
  "filter": "oids/any()"
}
```
此 JSON 搜索所有 oids 字段有值的文档，并返回 sourcefile 和 oids 字段。
如果 role_library.pdf 没有你的 OID，请返回到提供对 Azure 搜索中文档的用户访问权限部分，并完成相关步骤。

验证用户对文档的访问权限

如果已完成这些步骤但未看到正确的答案，请验证是否在 Azure AI 搜索中为 role_library.pdf正确设置了 USER_OBJECT_ID 参数。

返回到聊天应用。可能需要再次登录。
输入相同的查询，以便在 Azure OpenAI 回答中使用 role_library 内容：What does a product manager do?。
查看结果，该结果现在包含来自角色库文档的适当回答。

清理资源

以下步骤将引导你完成清理所用资源的过程。

清理 Azure 资源

本文中创建的 Azure 资源将计费给 Azure 订阅。如果不希望将来需要这些资源，请将其删除，以避免产生更多费用。

运行以下 Azure 开发人员 CLI 命令以删除 Azure 资源并删除源代码。

azd down --purge

清理 GitHub Codespaces 和 Visual Studio Code

以下步骤将引导你完成清理所用资源的过程。

GitHub Codespaces
Visual Studio Code

删除 GitHub Codespaces 环境可确保可以最大程度地提高帐户获得的每核心免费小时数权利。

重要

有关 GitHub 帐户权利的详细信息，请参阅 GitHub Codespaces 每月包含的存储和核心小时数。

登录到 GitHub Codespaces 仪表板。
找到当前运行的代码空间，这些代码空间源自 Azure-Samples/azure-search-openai-demo GitHub 存储库。
打开代码空间的上下文菜单，然后选择删除。

获取帮助

此示例存储库提供故障排除信息。

故障排除

本部分提供有关本文特定问题的疑难解答。

提供身份验证租户

当您的身份验证位于与托管应用程序不同的租户中时，需要使用以下过程来设置该身份验证的租户。

运行以下命令，将示例配置为使用第二个租户作为身份验证租户。
```
azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
```
参数目的

AZURE_AUTH_TENANT_ID 如果设置了 AZURE_AUTH_TENANT_ID，则它是托管应用的租户。
使用以下命令重新部署解决方案：
```
azd up
```

参数	目的
`AZURE_AUTH_TENANT_ID`	如果设置了 `AZURE_AUTH_TENANT_ID`，则它是托管应用的租户。

使用 Azure OpenAI 最佳做法解决方案体系结构构建聊天应用。
了解使用 Azure AI 搜索在生成式 AI 应用中进行访问控制。
使用 Azure API 管理构建适合企业使用的 Azure OpenAI 解决方案。
请参阅 Azure AI 搜索：使用混合检索和排名功能超越矢量搜索。

通过

Python 聊天文档安全性入门

体系结构概述

确定安全配置

企业：必需的帐户 + 文档筛选器

混合使用：可选帐户 + 文档筛选器

先决条件

打开开发环境

使用 Azure CLI 获取所需信息

设置环境变量

将聊天应用部署到 Azure

为用户打开对文档的访问权限

获取存储中的文档的 URL

获取用户 ID

在 Azure 搜索中提供对文档的用户访问权限

请验证 Azure AI 搜索是否包含您的 USER_OBJECT_ID

验证用户对文档的访问权限

清理资源

清理 Azure 资源

清理 GitHub Codespaces 和 Visual Studio Code

获取帮助

故障排除

提供身份验证租户

反馈

其他资源

通过

Python 聊天文档安全性入门

体系结构概述

确定安全配置

企业：必需的帐户 + 文档筛选器

混合使用：可选帐户 + 文档筛选器

先决条件

打开开发环境

使用 Azure CLI 获取所需信息

设置环境变量

将聊天应用部署到 Azure

为用户打开对文档的访问权限

获取存储中的文档的 URL

获取用户 ID

在 Azure 搜索中提供对文档的用户访问权限

请验证 Azure AI 搜索是否包含您的 USER_OBJECT_ID

验证用户对文档的访问权限

清理资源

清理 Azure 资源

清理 GitHub Codespaces 和 Visual Studio Code

获取帮助

故障排除

提供身份验证租户

相关内容

反馈

其他资源