Začínáme se zabezpečením chatovacích dokumentů pro Python

Při vytváření chatovací aplikace pomocí vzoru Načtení rozšířené generace (RAG) s vlastními daty se ujistěte, že každý uživatel obdrží odpověď na základě svých oprávnění. Postupujte podle postupu v tomto článku a přidejte do chatovací aplikace řízení přístupu k dokumentu.

• Autorizovaný uživatel: Tato osoba by měla mít přístup k odpovědím obsaženým v dokumentech chatovací aplikace.

  

• Neoprávněný uživatel: Tato osoba by neměla mít přístup k odpovědím ze zabezpečených dokumentů, ke kterým nemá autorizaci.

  

Přehled architektury

Bez funkce zabezpečení dokumentů má podniková chatovací aplikace jednoduchou architekturu pomocí služby Azure AI Vyhledávač a modelů Azure OpenAI v Microsoft Foundry. Odpověď se určuje z dotazů do služby Azure AI Vyhledávač, kde jsou dokumenty uložené v kombinaci s odpovědí z modelu Azure OpenAI GPT. V tomto jednoduchém toku se nepoužívá žádné ověřování uživatelů.

Pokud chcete přidat zabezpečení dokumentů, musíte aktualizovat podnikovou chatovací aplikaci:

• Přidejte do chatovací aplikace ověřování klientů pomocí Microsoft Entra.
• Přidejte logiku na straně serveru pro naplnění indexu vyhledávání uživatelským a skupinovým přístupem.

Azure AI Vyhledávač neposkytuje nativní oprávnění na úrovni dokumentu a nemůže měnit výsledky hledání v indexu podle uživatelských oprávnění. Místo toho může vaše aplikace pomocí vyhledávacích filtrů zajistit, aby byl dokument přístupný konkrétnímu uživateli nebo konkrétní skupině. V indexu vyhledávání by měl mít každý dokument filtrovatelné pole, ve kterých jsou uložené informace o identitě uživatele nebo skupiny.

Vzhledem k tomu, že autorizace není nativně obsažená ve službě Azure AI Vyhledávač, musíte přidat pole pro uložení informací o uživateli nebo skupině a potom filtrovat všechny dokumenty, které se neshodovaly. K implementaci této techniky potřebujete:

• Vytvořte v indexu pole řízení přístupu k dokumentu vyhrazené k ukládání podrobností o uživatelích nebo skupinách s přístupem k dokumentu.
• Vyplňte pole řízení přístupu k dokumentu relevantními podrobnostmi o uživateli nebo skupině.
• Toto pole řízení přístupu aktualizujte vždy, když dojde ke změnám uživatelských nebo skupinových přístupových oprávnění.

Pokud jsou aktualizace indexu naplánované pomocí indexeru, změny budou zaznamenány při dalším spuštění indexeru. Pokud indexer nepoužíváte, musíte ručně přeindexovat.

V tomto článku je proces zabezpečení dokumentů ve službě Azure AI Vyhledávač možný pomocí ukázkových skriptů, které byste spustili jako správce vyhledávání. Skripty přidružují jeden dokument k jedné identitě uživatele. Tyto skripty můžete vzít a použít vlastní požadavky na zabezpečení a produkční prostředí, abyste mohli škálovat podle svých potřeb.

Určení konfigurace zabezpečení

Řešení poskytuje logické proměnné prostředí pro zapnutí funkcí, které jsou nezbytné pro zabezpečení dokumentů v této ukázce.

Následující části vám pomůžou porozumět profilům zabezpečení podporovaným v této ukázce. Tento článek konfiguruje podnikový profil.

Enterprise: Požadovaný účet a filtr dokumentů

Každý uživatel webu se musí přihlásit. Web obsahuje obsah, který je veřejný pro všechny uživatele. Filtr zabezpečení na úrovni dokumentu se použije u všech požadavků.

Proměnné prostředí:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true

Smíšené použití: Volitelný účet + filtr dokumentů

Každý uživatel webu se může přihlásit. Web obsahuje obsah, který je veřejný pro všechny uživatele. Filtr zabezpečení na úrovni dokumentu se použije u všech požadavků.

Proměnné prostředí:

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

Požadavky

Vývojové prostředí kontejneru je k dispozici se všemi závislostmi potřebnými k dokončení tohoto článku. Vývojový kontejner můžete spustit v GitHub Codespaces (v prohlížeči) nebo místně pomocí editoru Visual Studio Code.

Pokud chcete použít tento článek, potřebujete následující požadavky:

• Předplatné služby Azure. Vytvořte si ho zdarma.
• Oprávnění účtu Azure: Váš účet Azure musí mít:
  • Oprávnění ke správě aplikací v Microsoft Entra ID
  • Microsoft.Authorization/roleAssignments/write oprávnění, jako je správce uživatelských přístupů nebo vlastník.

V závislosti na upřednostňovaném vývojovém prostředí potřebujete další požadavky.

Otevření vývojového prostředí

Podle následujících pokynů nasaďte předkonfigurované vývojové prostředí obsahující všechny požadované závislosti pro dokončení tohoto článku.

Získání požadovaných informací pomocí Azure CLI

Pomocí následujícího příkazu Azure CLI získejte ID předplatného a ID tenanta. Zkopírujte hodnotu, kterou chcete použít jako hodnotu AZURE_TENANT_ID .

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

Pokud se zobrazí chyba týkající se zásad podmíněného přístupu tenanta, potřebujete druhého tenanta bez zásad podmíněného přístupu.

• Vaše první tenant, přidružený k vašemu uživatelskému účtu, je použit pro proměnnou prostředí AZURE_TENANT_ID.
• Druhý tenant bez podmíněného přístupu se používá pro proměnnou AZURE_AUTH_TENANT_ID prostředí pro přístup k Microsoft Graphu. U tenantů se zásadami podmíněného přístupu vyhledejte ID druhého tenanta bez zásad podmíněného přístupu nebo vytvořte nového tenanta.

Nastavení proměnných prostředí

1. Proveďte následující příkazy k nakonfigurování aplikace pro profil Enterprise.

   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. Spuštěním následujícího příkazu nastavte tenanta, který autorizuje přihlášení uživatele do prostředí hostované aplikace. Nahraďte <YOUR_TENANT_ID> ID tenanta.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Nasazení chatovací aplikace do Azure

Nasazení se skládá z následujících kroků:

• Vytvořte prostředky Azure.
• Nahrajte dokumenty.
• Vytvořte aplikace Microsoft Entra identity (klient a server).
• Zapněte identitu pro hostitelský prostředek.

1. Zřiďte prostředky Azure a nasaďte zdrojový kód.

   azd up
   

2. Při odpovídání na výzvy k AZD nasazení použijte následující tabulku.

   Podnět	Odpověď
   Název prostředí	Použijte krátký název s identifikací informací, jako je váš alias a aplikace. A příklad je tjones-secure-chat.
   Předplatné	Vyberte předplatné, ve kterém mají být prostředky vytvořeny.
   Umístění prostředků Azure	Vyberte polohu blízko vás.
   Umístění pro documentIntelligentResourceGroupLocation	Vyberte polohu blízko vás.
   Umístění pro openAIResourceGroupLocation	Vyberte polohu blízko vás.

   Počkejte 5 nebo 10 minut po nasazení aplikace, aby se aplikace mohla spustit.

3. Po úspěšném nasazení aplikace se v terminálu zobrazí adresa URL.

4. Vyberte adresu URL s (✓) Done: Deploying service webapp popiskem a otevřete chatovací aplikaci v prohlížeči.

   

5. Odsouhlaste automaticky otevírané okno ověřování aplikace.

6. Když se zobrazí chatovací aplikace, všimněte si v pravém horním rohu, že je uživatel přihlášený.

7. Otevřete nastavení pro vývojáře a všimněte si, že pro změnu jsou vybrány a zakázány obě následující možnosti:

   • Použít bezpečnostní filtr OID
   • Použití filtru zabezpečení skupin

8. Vyberte kartu s Co dělá produktový manažer?.

9. Dostanete odpověď jako: Poskytnuté zdroje neobsahují konkrétní informace o roli produktového manažera ve společnosti Contoso Electronics.

   

Otevření přístupu k dokumentu pro uživatele

Zapněte svá oprávnění pro přesný dokument, abyste mohli získat odpověď. Potřebujete několik informací:

• Azure Storage
  • Název účtu
  • Název kontejneru
  • Adresa URL objektu blob nebo dokumentu pro role_library.pdf
• ID uživatele v Microsoft Entra ID

Pokud jsou tyto informace známé, aktualizujte pole indexu oids Azure AI Vyhledávač pro role_library.pdf dokument.

Získání adresy URL dokumentu v úložišti

1. .azure Ve složce v kořenovém adresáři projektu vyhledejte adresář prostředí a otevřete .env soubor s tímto adresářem.

2. Vyhledejte AZURE_STORAGE_ACCOUNT položku a zkopírujte její hodnotu.

3. Pomocí následujících příkazů Azure CLI získejte adresu URL objektu role_library.pdf blob v kontejneru content .

   az storage blob url \
       --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
       --container-name 'content' \
       --name 'role_library.pdf' 
   

   Parametr	Účel
   --account-name	Název účtu služby Azure Storage
   --container-name	Název kontejneru v této ukázce je content.
   --Jméno	Název objektu blob v tomto kroku je role_library.pdf.

4. Zkopírujte adresu URL objektu blob, abyste ji mohli použít později.

Získání ID uživatele

1. V chatovací aplikaci vyberte Nastavení pro vývojáře.
2. V části deklarací identity tokenu ID zkopírujte parametr objectidentifier . Tento parametr je znám v další části jako USER_OBJECT_ID.

Poskytnutí přístupu uživatelů k dokumentu ve službě Azure Search

1. Pomocí následujícího skriptu změňte oids pole ve službě Azure AI Vyhledávač role_library.pdf tak, abyste k němu měli přístup.

   python ./scripts/manageacl.py --acl-type oids --acl-action add --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parametr	Účel
   -v	Podrobný výstup
   --acl-type	Identifikátory OID skupiny nebo uživatele: oids.
   --acl-action	Přidejte do pole indexu vyhledávání. Mezi další možnosti patří enable_acls, remove, remove_alla view.
   --Acl	Skupina nebo uživatel USER_OBJECT_ID.
   --url	Umístění souboru ve službě Azure Storage, například https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Adresu URL neohraničíte uvozovkami v příkazu rozhraní příkazového řádku.

2. Výstup konzoly pro tento příkaz vypadá takto:

   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. Volitelně můžete pomocí následujícího příkazu ověřit, že je vaše oprávnění uvedené pro soubor ve službě Azure AI Vyhledávač.

   python ./scripts/manageacl.py -v --acl-type groups --acl-action view --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parametr	Účel
   -v	Podrobný výstup
   --acl-type	Identifikátory OID skupiny nebo uživatele: oids.
   --acl-action	Zobrazit pole oidsindexu vyhledávání . Mezi další možnosti patří enable_acls, remove, remove_alla add.
   --url	Umístění souboru, které se v tom ukazuje, například https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Adresu URL neohraničíte uvozovkami v příkazu rozhraní příkazového řádku.

4. Výstup konzoly pro tento příkaz vypadá takto:

   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]
   

   Pole na konci výstupu obsahuje váš USER_OBJECT_ID parametr a slouží k určení, jestli se dokument používá v odpovědi s Azure OpenAI.

Ověřte, že Azure AI Vyhledávač obsahuje vaše USER_OBJECT_ID

1. Otevřete Azure Portal a vyhledejte AI Search.

2. V seznamu vyberte svůj vyhledávací prostředek.

3. Vyberte Správu vyhledávání>Indexy.

4. Vyberte gptkbindex.

5. Vyberte Pohled>zobrazení ve formátu JSON.

6. Nahraďte JSON následujícím JSON:

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

   Tento kód JSON prohledá všechny dokumenty, kde pole oids má libovolnou hodnotu, a vrátí pole sourcefile a oids.

7. Pokud role_library.pdf nemá váš identifikátor OID, vraťte se do části Poskytnout uživateli přístup k dokumentu ve službě Azure Search a proveďte kroky.

Ověření přístupu uživatele k dokumentu

Pokud jste dokončili kroky, ale neviděli správnou odpověď, ověřte, že je parametr USER_OBJECT_ID správně nastavený ve službě role_library.pdfAzure AI Vyhledávač.

1. Vraťte se do chatovací aplikace. Možná se budete muset znovu přihlásit.

2. Zadejte stejný dotaz, aby se role_library obsah použil v odpovědi Azure OpenAI: What does a product manager do?.

3. Podívejte se na výsledek, který teď obsahuje příslušnou odpověď z dokumentu knihovny rolí.

   

Vyčistěte zdroje

Následující kroky vás provedou procesem čištění použitých prostředků.

Vyčištění prostředků Azure

Prostředky Azure vytvořené v tomto článku se fakturují k vašemu předplatnému Azure. Pokud v budoucnu tyto prostředky nepotřebujete, odstraňte je, abyste se vyhnuli účtování dalších poplatků.

Spuštěním následujícího příkazu Azure Developer CLI odstraňte prostředky Azure a odeberte zdrojový kód.

azd down --purge

Vyčištění GitHub Codespaces a Visual Studio Code

Následující kroky vás provedou procesem čištění použitých prostředků.

Získání pomoci

Ukázkové úložiště nabízí informace o řešení potíží.

Řešení problémů

Tato část vám pomůže vyřešit problémy specifické pro tento článek.

Poskytněte nájemce ověřování

Pokud je ověřování v samostatném tenantovi od hostitelské aplikace, musíte ho nastavit následujícím postupem.

1. Spuštěním následujícího příkazu nakonfigurujte ukázku tak, aby používala druhého klienta pro ověřování.

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

   Parametr	Účel
   AZURE_AUTH_TENANT_ID	Pokud AZURE_AUTH_TENANT_ID je nastavená, jedná se o tenanta, který je hostitelem aplikace.

2. Znovu nasaďte řešení pomocí následujícího příkazu:

   azd up
   

Související obsah

• Vytvořte chatovací aplikaci s využitím architektury řešení osvědčených postupů pro Azure OpenAI.
• Seznamte se s řízením přístupu v generivních aplikacích AI pomocí služby Azure AI Vyhledávač.
• Sestavte řešení Azure OpenAI připravené pro podniky pomocí služby Azure API Management.
• Viz Azure AI vyhledávání: Překonávání vektorového vyhledávání s hybridními možnostmi vyhledávání a hodnocení.