開始使用適用於 Python 的聊天文件安全性

發行項
06/15/2024

當您使用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`時，可讓使用者登入聊天應用程式和 App Service 驗證。在聊天應用程式中啟用`Use oid security filter`開發人員設定。
`AZURE_ENFORCE_ACCESS_CONTROL`	當設定為 `true`時，需要驗證任何檔存取權。 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 許可權，例如使用者存取系統管理員或擁有者。
在所需的 Azure 訂用帳戶中授與 Azure OpenAI 的存取權。目前只有應用程式會授予此服務的存取權。您可以填妥 https://aka.ms/oai/access 的表單，以申請 Azure OpenAI 的存取權。

視您慣用的開發環境而定，您需要更多必要條件。

Codespaces (建議)
Visual Studio Code

GitHub 帳戶

開啟開發環境

立即使用已安裝所有相依性的開發環境開始，以完成本文。

GitHub Codespaces (建議)
Visual Studio Code

GitHub Codespaces 會使用網頁版 Visual Studio Code 作爲使用者介面，執行由 GitHub 管理的開發容器。如需最直接的開發環境，請使用 GitHub Codespaces，使得您有已預先安裝的正確開發人員工具和相依性，以便完成本文。

重要

所有 GitHub 帳戶每個月最多可以使用 Codespaces 60 小時，且有 2 個核心執行個體。如需詳細資訊，請參閱 GitHub Codespaces 每月包含的儲存體和核心時數。

開始在 Azure-Samples/azure-search-openai-demo GitHub 存放庫分的 main 分支上建立新的 GitHub Codespace 的流程。
在以下按鈕上按一下以滑鼠右鍵，然後選取 [在新視窗中開啟連結]，以便同時取得開發環境和文件。
在 [建立 Codespace] 頁面上，檢閱 Codespace 組態設定，然後選取 [建立新的 Codespace]
等候 Codespace 開始。此啟動程序可能需要幾分鐘的時間。
在畫面底部的終端機中，使用 Azure Developer 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 Developer CLI 登入 Azure。
```
azd auth login
```
從終端機複製程式碼，然後將它貼到瀏覽器中。遵循指示使用 Azure 帳戶進行驗證。
此專案中的其餘練習會在此開發容器的內容中進行。

使用 Azure CLI 取得必要資訊

使用下列 Azure CLI 命令取得訂用帳戶標識碼和租用戶標識碼。複製值以作為您的 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。對於具有條件式存取原則的租使用者，請尋找沒有條件式存取原則或建立新租使用者的第二個租用戶的標識符。

設定環境變數

執行下列命令來設定企業配置檔的應用程式。

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> 為租用戶標識碼。
```
azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
```

注意

如果您的使用者租使用者上有條件式存取原則，則必須指定驗證租使用者。

部署聊天應用程式至 Azure

部署包括建立 Azure 資源、上傳檔、建立Microsoft Entra 身分識別應用程式（用戶端和伺服器），以及開啟裝載資源的身分識別。

執行下列 Azure Developer CLI 命令來佈建 Azure 資源並部署原始程式碼：
```
azd up
```

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

提示	回答
環境名稱	使用簡短名稱來識別資訊，例如您的別名和應用程式： `tjones-secure-chat`。
訂用帳戶	選取要在其中建立資源的訂用帳戶。
Azure 資源的位置	選取與您接近的位置。
的位置 `documentIntelligentResourceGroupLocation`	選取與您接近的位置。
的位置 `openAIResourceGroupLocation`	選取與您接近的位置。

在應用程式部署後等候 5 或 10 分鐘，以允許應用程式啟動。

成功部署應用程式之後，您會看到終端機中顯示 URL。
選取標示為 (✓) Done: Deploying service webapp 的 URL，以在瀏覽器中開啟聊天應用程式。
同意應用程式驗證快顯。
顯示聊天應用程式時，請注意右上角的使用者已登入。
開啟 [開發人員設定 ]，並注意這兩個選項都會選取並呈現灰色（已停用變更）。
- 使用 oid 安全性篩選器
- 使用群組安全性篩選
選取具有 What does a product manager do?的卡片。
您得到的答案如下： The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

為用戶開啟檔的存取權

開啟確切文件的許可權，以便取得答案。這些需要數項資訊：

Azure 儲存體
- 帳戶名稱
- 容器名稱
- 的 Blob/檔 URL role_library.pdf
Microsoft Entra 識別碼中的使用者標識碼

一旦知道這項資訊，請更新檔的 Azure AI 搜尋服務索引 oids 字段 role_library.pdf 。

取得記憶體中檔的 URL

在 .azure 專案根目錄的資料夾中，尋找環境目錄，並使用該目錄開啟 .env 檔案。
AZURE_STORAGE_ACCOUNT搜尋專案並複製其值。
使用下列 Azure CLI 命令來取得內容容器中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

--name 此步驟中的 Blob 名稱為 role_library.pdf
複製 Blob URL 以供稍後使用。

參數	目的
--account-name	Azure 儲存體帳戶名稱
--container-name	此範例中的容器名稱為 `content`
--name	此步驟中的 Blob 名稱為 `role_library.pdf`

取得您的使用者識別碼

在chap應用程式中，選取 [ 開發人員設定]。
在 [ 識別元令牌宣告] 區段中，複製您的 objectidentifier。這在下一節 USER_OBJECT_ID中稱為。

在 Azure 搜尋服務中提供文件的使用者存取權

使用下列腳本來變更 oids Azure AI 搜尋服務 中的欄位role_library.pdf ，讓您能夠存取它。

./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_alllist`、。
--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 搜尋服務中的檔案列出。

./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	群組或使用者（oids）： `oids`
--acl-action	列出搜尋索引欄位 `oids`。其他選項包括`remove`、 `remove_alllist`、。
--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 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()"
}
```
這會搜尋欄位具有任何值並傳sourcefile回、和 oids 欄位的所有檔oids。
role_library.pdf如果沒有您的 oid，請返回 [提供使用者存取 Azure 搜尋服務] 區段中的檔，並完成步驟。

確認使用者對檔的存取權

如果您已完成步驟但未看到正確的答案，請確認您的USER_OBJECT_ID已在 Azure AI 搜尋中正確設定。role_library.pdf

返回聊天應用程式。您可能需要再次登入。
輸入相同的查詢，讓 role_library 內容用於 Azure OpenAI 答案： What does a product manager do?。
檢視結果，現在包含角色庫檔中的適當答案。

清除資源

清除 Azure 資源

在本文中建立的 Azure 資源會向您的 Azure 訂用帳戶計費。如果您預計未來不需要這些資源，請將其刪除，以避免產生更多費用。

執行下列 Azure Developer CLI 命令來刪除 Azure 資源並移除原始程式碼：

azd down --purge

刪除 GitHub Codespaces 環境，可確保您可將您為帳戶取得的每個核心免費時數權利數量最大化。

重要

如需 GitHub 帳戶權利的詳細資訊，請參閱 GitHub Codespaces 每月包含的儲存體和核心時數。

登入 GitHub Codespaces 儀表板 (https://github.com/codespaces)。
找出您目前執行中的 Codespaces，而其來源為 Azure-Samples/azure-search-openai-demo GitHub 存放庫。
開啟 Codespace 的快顯功能表，然後選取 [刪除]。

取得協助

此範例存放庫可提供疑難排解資訊。

疑難排解

本節提供本文特定問題的疑難解答。

提供驗證租使用者

當您的驗證位於與主控應用程式不同的租使用者中時，您必須使用下列程式來設定該驗證租使用者。

執行下列命令來設定範例，以針對驗證租使用者使用第二個租使用者。
```
azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
```
參數目的

AZURE_AUTH_TENANT_ID 如果 AZURE_AUTH_TENANT_ID 已設定，則為裝載應用程式的租使用者。
使用下列命令重新部署方案。
```
azd up
```

共用方式為