開始使用 Python 的對話文檔安全功能

當您使用擷取擴增世代（RAG）模式，並使用您自己的數據來建置 聊天應用程式時，請確保每位使用者都會根據其許可權接收答案。 請遵循本文中的程式，將檔案訪問控制新增至聊天應用程式。

• 授權的使用者：此人應該能夠存取聊天應用程式檔中所包含的答案。

  

• 未經授權的使用者：此人不應該能夠從他們沒有授權查看的安全檔存取答案。

  

注意

本文使用一或多個 AI 應用程式範本， 作為本文範例和指引的基礎。 AI 應用程式範本提供易於部署且維護良好的參考實作。 它們可協助您確保 AI 應用程式的高品質起點。

架構概觀

若沒有文件安全性功能，企業聊天應用程式會使用 Azure AI 搜尋和 Azure OpenAI 來擁有簡單的架構。 答案是透過對存放文件的 Azure AI 搜尋進行查詢，並結合來自 Azure OpenAI GPT 模型的回應所決定的。 此簡單流程中不會使用任何用戶驗證。

若要新增檔案的安全性，您需要更新企業聊天應用程式：

• 使用 Microsoft Entra 將客戶端驗證新增至聊天應用程式。
• 新增伺服器端邏輯，以使用者和群組存取來填入搜尋索引。

Azure AI 搜尋不會提供 原生 檔層級許可權，而且無法依使用者許可權在索引內變更搜尋結果。 相反地，您的應用程式可以使用搜尋篩選器來確保特定使用者或特定群組可存取檔。 在您的搜尋索引內，每個文件都應該有可篩選的字段來儲存使用者或群組身分識別資訊。

由於授權並非原生包含在 Azure AI 搜尋中，因此您必須新增欄位來保存使用者或群組資訊，然後 篩選 不符合的任何檔。 若要實作這項技術，您需要：

• 在您的索引中建立檔訪問控制欄位，專門用來儲存具有檔存取權的使用者或群組詳細數據。
• 使用相關的使用者或群組資訊填寫文件的訪問控制欄位。
• 每當使用者或群組訪問許可權發生變更時，請更新此訪問控制欄位。

如果您的索引更新是由索引器按排程進行的，則會在下一次索引器運行時處理變更。 如果您沒有使用索引器，則需要手動重新編製索引。

在本文中，Azure AI 搜尋服務中保護檔的程式可透過 範例 腳本來達成，您身為搜尋系統管理員會執行此腳本。 腳本會將單一檔與單一使用者身分識別產生關聯。 您可以採用這些 腳本，並套用您自己的安全性和生產需求，以根據您的需求進行調整。

決定安全性設定

此解決方案提供布爾環境變數，以開啟此範例中檔安全性所需的功能。

參數	目的
AZURE_USE_AUTHENTICATION	當設定為 true時，可讓使用者登入聊天應用程式和 Azure 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 時，才應該使用此參數。

使用下列各節來瞭解此範例中支援的安全性概況。 本文會設定 Enterprise 設定檔。

企業：所需的帳戶 + 檔案篩選

網站 的每個用戶都必須 登入。 網站包含所有使用者公開的內容。 檔層級安全性篩選器會套用至所有要求。

環境變數：

• 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 （建議）

• GitHub 帳戶

Visual Studio Code

• Azure 開發人員 CLI。
• Docker Desktop。 如果 Docker Desktop 尚未執行，請啟動它。
• Visual Studio Code。
• 開發容器擴展。

開啟開發環境

使用下列指示來部署預先設定的開發環境，其中包含完成本文所需的所有相依性。

GitHub Codespaces （建議）

GitHub Codespaces 會執行由 GitHub 所管理的開發容器，並將 適用於 Web 的 Visual Studio Code 作為使用者介面。 要建立最簡單的開發環境，請使用 GitHub Codespaces，可以確保有預安裝的正確開發工具和依賴項，方便您完成這篇文章。

重要

所有 GitHub 帳戶每月可免費使用 GitHub Codespaces 長達 60 小時，並可運行兩個核心實例。 如需詳細資訊，請參閱 GitHub Codespaces 每月包含的儲存空間和核心時數。

1. 啟動程式，在 main GitHub 存放庫的 分支上建立新的 GitHub 程式代碼空間。

2. 以滑鼠右鍵按下列按鈕，然後選取 [在新視窗 中開啟連結]，讓開發環境和文件同時可供使用。

   

3. 在 [建立 codespace] 頁面上，檢閱 codespace 組態設定，然後選取 [建立新的 codespace]。

   

4. 等候 codespace 啟動。 此啟動程式可能需要幾分鐘的時間。

5. 在畫面底部的終端機中，使用 Azure 開發人員 CLI 登入 Azure。

   azd auth login
   

6. 完成驗證程式。

7. 本文其餘的任務將在此開發容器的環境中進行。

Visual Studio Code

適用於 Visual Studio Code 的 開發容器擴充功能 需要在本機電腦上安裝 Docker。 擴充功能藉由使用具有預先安裝好完成本文所需的開發人員工具和相依性的 Docker 主機，在本機裝載開發容器。

1. 在您的電腦上為專案建立新的本機目錄。

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

2. 在該目錄中開啟 Visual Studio Code。

   code .
   

3. 在 Visual Studio Code 中開啟新的終端機。

4. 執行下列 AZD 命令，將 GitHub 存放庫帶入本機電腦。

   azd init -t azure-search-openai-demo
   

5. 開啟 [命令] 調色盤，然後搜尋並選取 [開發容器：在容器中開啟資料夾] 以在開發容器中開啟專案。 等到開發容器開啟，再繼續進行。

6. 使用 Azure 開發人員 CLI 登入 Azure。

   azd auth login
   

   從終端機複製程式代碼，然後將它貼到瀏覽器中。 請依照指示向 Azure 帳戶進行驗證。

7. 此專案中的剩餘練習會在此開發容器的環境中進行。

使用 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。 對於具有條件式存取原則的租戶，請尋找沒有條件式存取原則的第二個租戶的ID，或 建立新的租戶。

設定環境變數

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

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

2. 執行下列命令來設定租使用者，以授權使用者登入託管的應用程式環境。 將 <YOUR_TENANT_ID> 替換為租戶 ID。

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

注意

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

將聊天應用程式部署至 Azure

部署包含下列步驟：

• 建立 Azure 資源。
• 上傳文件。
• 建立Microsoft Entra 身分識別應用程式（用戶端和伺服器）。
• 開啟託管資源的身分識別。

1. 執行下列 Azure 開發人員 CLI 命令來布建 Azure 資源並部署原始程式碼。

   azd up
   

2. 使用下表來回應 AZD 部署指示。

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

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

3. 應用程式成功部署之後，終端機中會出現URL。

4. 選取標示為 (✓) Done: Deploying service webapp 的 URL，以在瀏覽器中開啟聊天應用程式。

   

5. 同意應用程式的驗證快顯視窗。

6. 當聊天應用程式出現時，請注意在右上角顯示您的使用者已登入。

7. 開啟 開發人員設定，並注意到下列兩個選項已被選取且無法更改：

   • 使用 OID 安全性篩選器
   • 使用群組安全篩選器

8. 選擇具有 產品經理工作的卡片。

9. 您得到的答案類似如下：提供的來源中不包含有關 Contoso Electronics 公司產品經理角色的具體資訊。

   

開放用戶訪問文件權限

請開啟確切文件的許可權，以便 能夠 得到答案。 您需要數個資訊：

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

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

取得儲存空間中文件的 URL

1. 在專案根目錄的 [.azure] 資料夾中，尋找環境目錄，並使用該目錄開啟 .env 檔案。

2. 搜尋 AZURE_STORAGE_ACCOUNT 條目，並複製其值。

3. 使用下列 Azure CLI 命令來取得 role_library.pdf 容器中 content 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。

4. 複製 Blob URL 以供稍後使用。

取得您的使用者識別碼

1. 在聊天應用程式中，選取 [開發人員設定]。
2. 在 [標識符令牌宣告] 區段中，複製您的 objectidentifier 參數。 下一節中已知此參數為 USER_OBJECT_ID。

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

1. 使用下列腳本來變更 Azure AI 搜尋 oids 中的 [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_all與 list。
   --acl	群組或使用者 USER_OBJECT_ID。
   --url	檔案在 Azure 記憶體中的位置，例如 https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf。 請勿在 CLI 命令中使用引號括住 URL。

2. 此指令的主控台輸出如下所示：

   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
   

3. 選擇性地使用下列命令來確認您的許可權已針對 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	群組或使用者 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。

4. 此指令的主控台輸出如下所示：

   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

1. 開啟 Azure 入口網站 並搜尋 AI Search。

2. 從清單中選取您的搜尋資源。

3. 選取 搜尋管理>索引。

4. 選取 gptkbindex。

5. 選取 檢視>JSON 檢視。

6. 使用以下 JSON 取代目前的 JSON：

   {
     "search": "*",
     "select": "sourcefile, oids",
     "filter": "oids/any()"
   }
   

   此 JSON 會搜尋 oids 欄位具有任何值的所有檔，並傳回 sourcefile 和 oids 字段。

7. 如果 role_library.pdf 沒有您的 OID，請返回 提供使用者在 Azure 搜尋服務 區段中檔的存取權，並完成步驟。

確認使用者對檔的存取權

如果您已經完成所有步驟，但仍未看到正確答案，請確認在 Azure AI 搜索中，您的 USER_OBJECT_ID 參數是否已針對 role_library.pdf正確設置。

1. 返回聊天應用程式。 您可能需要再次登入。

2. 輸入相同的查詢，以便在 Azure OpenAI 回應中使用 role_library 內容：What does a product manager do?。

3. 檢視結果，現在包含角色庫檔中的適當答案。

   

清除資源

以下步驟將引導您完成整理所使用的資源。

清除 Azure 資源

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

執行下列 Azure 開發人員 CLI 命令來刪除 Azure 資源並移除原始程式碼。

azd down --purge

整理 GitHub Codespaces 和 Visual Studio Code

以下步驟將引導您完成整理所使用的資源。

GitHub Codespaces

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

重要

如需有關 GitHub 帳戶權利的詳細資訊，請參閱關於 GitHub Codespaces 中每月包含的儲存空間和運算核心時數的說明 。

1. 登入 GitHub Codespaces 儀錶板。

2. 找出您目前執行的程式代碼空間，其來源為 azure-Samples/azure-search-openai-demo GitHub 存放庫 。

   

3. 開啟 codespace 的操作功能表，然後選取 [刪除]。

   

Visual Studio Code

您不一定需要清理您的本機環境，但您可以停止正在運行的開發容器，然後在本機工作區的上下文中重新運行 Visual Studio Code。

1. 開啟 命令 選擇區，然後搜尋 開發容器 命令。

2. 選取 [開發容器：在本機重新開啟資料夾。

   

提示

Visual Studio Code 會停止執行中的開發容器，但容器仍存在於 Docker 中處於已停止狀態。 您一律可以選擇從 Docker 刪除容器實例、容器映像和磁碟區，以釋放本機電腦上的更多空間。

獲得幫助

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

故障排除

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

提供驗證租戶

當您的驗證位於與託管應用程式不同的租戶時，您必須使用下列程序來設定該驗證的租戶。

1. 執行下列命令以設定範例，使用第二個租戶作為驗證租戶。

   azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
   

   參數	目的
   AZURE_AUTH_TENANT_ID	如果已設定 AZURE_AUTH_TENANT_ID，則為托管應用程式的租戶。

2. 使用下列命令重新部署解決方案：

   azd up
   

相關內容

• 使用 Azure OpenAI 建置 聊天應用程式， 最佳做法解決方案架構。
• 瞭解在生成式 AI 應用程式中的 存取控制，以及如何使用 Azure AI 搜尋。
• 使用 Azure API 管理建置 企業就緒的 Azure OpenAI 解決方案。
• 請參閱 Azure AI 搜尋：超越向量搜尋，使用混合式擷取和排名功能。