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

Při vytváření chatovací aplikace pomocí vzoru 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 by měl mít přístup k odpovědím obsaženým v dokumentech chatovací aplikace.

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

Poznámka:

Tento článek používá jednu nebo více šablon aplikací AI jako základ pro příklady a pokyny v tomto článku. Šablony aplikací AI poskytují dobře udržované a snadno použitelné referenční implementace, které pomáhají zajistit vysoce kvalitní výchozí bod pro vaše aplikace AI.

Přehled architektury

Bez funkce zabezpečení dokumentů má podniková chatovací aplikace jednoduchou architekturu pomocí služby Azure AI Search a Azure OpenAI. Odpověď se určuje z dotazů do služby Azure AI Search, 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 Search 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 Search, musíte přidat pole pro uložení informací o uživateli nebo skupině a 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 se vyberou 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 Search 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í nastavení, 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í nezbytných pro zabezpečení dokumentů v této ukázce.

Parametr	Účel
AZURE_USE_AUTHENTICATION	Pokud je tato možnost nastavená, truepovolí přihlášení uživatele k chatovací aplikaci a ověřování pomocí služby App Service. Use oid security filter Povolí v nastavení pro vývojáře chatovací aplikace.
AZURE_ENFORCE_ACCESS_CONTROL	Pokud je nastavená hodnota true, vyžaduje ověřování pro jakýkoli přístup k dokumentu. Nastavení pro vývojáře pro oid a zabezpečení skupiny se zapne a zakáže, aby je nebylo možné zakázat z uživatelského rozhraní.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS	Pokud je tato možnost nastavená, trueumožňuje ověřeným uživatelům vyhledávat v dokumentech, které nemají přiřazené žádné řízení přístupu, i když je vyžadováno řízení přístupu. Tento parametr by se měl používat jenom v případě, že AZURE_ENFORCE_ACCESS_CONTROL je povolený.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS	Pokud je tato možnost nastavená na true, toto nastavení umožňuje neověřeným uživatelům používat aplikaci, i když se vynucuje řízení přístupu. Tento parametr by se měl používat jenom v případě, že AZURE_ENFORCE_ACCESS_CONTROL je povolený.

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 a 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 a 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é 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 permissions, jako je správce uživatelských přístupů nebo vlastník.
• Přístup k Azure OpenAI je udělován v požadovaném předplatném Azure. V současné době je přístup k této službě udělován pouze aplikací. Pokud chcete získat přístup k Azure OpenAI, vyplňte formulář na adrese https://aka.ms/oai/access.

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

Codespaces (doporučeno)

• Účet GitHub

Visual Studio Code

• Azure Developer CLI
• Docker Desktop – spusťte Docker Desktop , pokud ještě není spuštěný
• Visual Studio Code
• Rozšíření vývojového kontejneru

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

Začněte teď s vývojovým prostředím, které má nainstalované všechny závislosti k dokončení tohoto článku.

Codespaces GitHubu (doporučeno)

GitHub Codespaces spouští vývojový kontejner spravovaný GitHubem pomocí editoru Visual Studio Code pro web jako uživatelského rozhraní. Pro nejjednodušší vývojové prostředí použijte GitHub Codespaces, abyste měli předinstalované správné vývojářské nástroje a závislosti k dokončení tohoto článku.

Důležité

Všechny účty GitHubu můžou každý měsíc používat Codespaces až 60 hodin zdarma se 2 jádrovými instancemi. Další informace najdete v tématu GitHub Codespaces měsíčně zahrnuté úložiště a hodiny jádra.

1. Spusťte proces vytvoření nového prostředí GitHub Codespace ve main větvi Azure-Samples/azure-search-openai-demo úložiště GitHub.

2. Klikněte pravým tlačítkem myši na následující tlačítko a vyberte Otevřít odkaz v nových oknech , abyste měli k dispozici vývojové prostředí i dokumentaci najednou.

   

3. Na stránce Vytvořit kódspace zkontrolujte nastavení konfigurace codespace a pak vyberte Vytvořit nový prostor kódu.

   

4. Počkejte, až se prostor kódu spustí. Tento proces spuštění může trvat několik minut.

5. V terminálu v dolní části obrazovky se přihlaste k Azure pomocí Azure Developer CLI.

   azd auth login
   

6. Dokončete proces ověřování.

7. Zbývající úlohy v tomto článku probíhají v kontextu tohoto vývojového kontejneru.

Visual Studio Code

Rozšíření Dev Containers pro Visual Studio Code vyžaduje instalaci Dockeru na místním počítači. Rozšíření hostuje vývojový kontejner místně pomocí hostitele Dockeru se správnými vývojářskými nástroji a závislostmi předinstalovanými k dokončení tohoto článku.

1. Vytvořte nový místní adresář v počítači pro projekt.

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

2. Otevřete Visual Studio Code v daném adresáři:

   code .
   

3. Otevřete nový terminál v editoru Visual Studio Code.

4. Spuštěním následujícího příkazu AZD přeneste úložiště GitHub do místního počítače.

   azd init -t azure-search-openai-demo
   

5. Otevřete paletu příkazů, vyhledejte a vyberte Dev Containers: Otevřít složku v kontejneru a otevřete projekt v vývojovém kontejneru. Než budete pokračovat, počkejte na otevření vývojového kontejneru.

6. Přihlaste se k Azure pomocí Azure Developer CLI.

   azd auth login
   

   Zkopírujte kód z terminálu a vložte ho do prohlížeče. Postupujte podle pokynů k ověření pomocí účtu Azure.

7. Zbývající cvičení v tomto projektu probíhají v kontextu tohoto vývojového kontejneru.

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, která se má použít jako vaše 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.

• Pro proměnnou prostředí se používá váš první tenant přidružený k vašemu uživatelskému AZURE_TENANT_ID účtu.
• 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. Spuštěním následujícíchpříkazůch

   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 k prostředí hostované aplikace. Nahraďte <YOUR_TENANT_ID> ID tenanta.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Poznámka:

Pokud máte v tenantovi uživatele zásady podmíněného přístupu, musíte zadat tenanta ověřování.

Nasazení chatovací aplikace do Azure

Nasazení zahrnuje vytvoření prostředků Azure, nahrání dokumentů, vytvoření aplikací Microsoft Entra identity (klient a server) a zapnutí identity pro hostitelský prostředek.

1. Spuštěním následujícího příkazu Azure Developer CLI zřiďte prostředky Azure a nasaďte zdrojový kód:

   azd up
   

2. Pomocí následující tabulky odpovězte na výzvy k nasazení AZD:

   Instrukce	Odpověď
   Název prostředí	Použijte krátký název s identifikací informací, jako je váš alias a aplikace: tjones-secure-chat.
   Předplatné	Vyberte předplatné, ve které chcete prostředky vytvořit.
   Umístění prostředků Azure	Vyberte umístění blízko vás.
   Umístění pro documentIntelligentResourceGroupLocation	Vyberte umístění blízko vás.
   Umístění pro openAIResourceGroupLocation	Vyberte umístění 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. Výběrem této adresy URL otevřete (✓) Done: Deploying service webapp chatovací aplikaci v prohlížeči.

   

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

6. Po zobrazení chatovací aplikace si všimněte 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 jsou tyto možnosti vybrané i neaktivní (pro změnu jsou zakázané).

   • Použití filtru zabezpečení oid
   • Použití filtru zabezpečení skupin

8. Vyberte kartu s What does a product manager do?kartou .

9. Dostanete odpověď jako: The provided sources do not contain specific information about the role of a Product Manager at 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ěď. Tyto informace vyžadují 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

Jakmile jsou tyto informace známé, aktualizujte pole indexu oids Azure AI Search 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 blob role_library.pdf v kontejneru obsahu .

   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 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 aplikaci chap vyberte Nastavení pro vývojáře.
2. V oddílu deklarací identity tokenu ID zkopírujte své objectidentifier. To je známo 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 Search pro role_library.pdf , abyste k němu měli přístup.

   ./scripts/manageacl.sh \
       -v \
       --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	ID objektů skupiny nebo uživatele: oids
   --acl-action	Přidejte do pole indexu vyhledávání. Mezi další možnosti patří remove, remove_all, list.
   --Acl	Skupina nebo uživatel USER_OBJECT_ID
   --url	Umístění souboru v úložišti Azure, například https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. V příkazu rozhraní příkazového řádku neohraničíte adresu URL uvozovkami.

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, jestli je vaše oprávnění uvedené pro soubor ve službě 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>
   

   Parametr	Účel
   -v	Podrobný výstup
   --acl-type	Skupina nebo uživatel (oids): oids
   --acl-action	Vypsat pole oidsindexu vyhledávání . Mezi další možnosti patří remove, remove_all, list.
   --Acl	Skupina nebo uživatel USER_OBJECT_ID
   --url	Umístění souboru v úložišti Azure, například https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. V příkazu rozhraní příkazového řádku neohraničíte adresu URL uvozovkami.

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 a slouží k určení, jestli se dokument použije v odpovědi s Azure OpenAI.

Ověření, že Azure AI Search obsahuje vaše USER_OBJECT_ID

1. Otevřete Web Azure Portal a vyhledejte ho 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 Zobrazení –> zobrazení JSON.

6. Nahraďte JSON následujícím kódem JSON.

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

   Vyhledá se ve všech dokumentech, ve kterých oids má pole libovolnou hodnotu, a vrátí sourcefilepole a oids pole.

7. role_library.pdf Pokud váš identifikátor nemá, 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 ve službě Azure AI Search role_library.pdfsprávně nastavená vaše USER_OBJECT_ID .

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čištění 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í služby GitHub Codespaces

GitHub Codespaces

Odstraněním prostředí GitHub Codespaces zajistíte, že můžete maximalizovat nárok na počet bezplatných hodin za jádro, které získáte pro svůj účet.

Důležité

Další informace o oprávněních účtu GitHub najdete v tématu GitHub Codespaces měsíčně zahrnuté hodiny úložiště a jádra.

1. Přihlaste se k řídicímu panelu GitHub Codespaces (https://github.com/codespaces).

2. Vyhledejte aktuálně spuštěné Codespaces zdrojové z Azure-Samples/azure-search-openai-demo úložiště GitHub.

   

3. Otevřete místní nabídku pro codespace a pak vyberte Odstranit.

   

Visual Studio Code

Nemusíte nutně vyčistit místní prostředí, ale můžete zastavit spuštěný vývojový kontejner a vrátit se ke spuštění editoru Visual Studio Code v kontextu místního pracovního prostoru.

1. Otevřete paletu příkazů, vyhledejte příkazy Dev Containers a pak vyberte Dev Containers: Znovu otevřít složku místně.

   

Tip

Visual Studio Code zastaví spuštěný vývojový kontejner, ale kontejner stále existuje v Dockeru v zastaveném stavu. Vždy máte možnost odstranit instanci kontejneru, image kontejneru a svazky z Dockeru, abyste uvolnili více místa na místním počítači.

Získání pomoci

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

Řešení problému

Tato část nabízí řešení potíží souvisejících s tímto článkem.

Poskytnutí tenanta 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 tenanta pro tenanta 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
   

Další kroky

• Vytvoření chatovací aplikace s využitím architektury osvědčených postupů Azure OpenAI
• Řízení přístupu v generativních aplikacích AI pomocí Azure AI Search
• Vytvoření řešení OpenAI připravené pro podniky pomocí služby Azure API Management
• Outperforming vector search with hybrid retrieval and ranking capabilities