Ismerkedés a csevegődokumentumok Pythonhoz való biztonságával

Ha a saját adatai felhasználásával, a Retrieval Augmented Generation (RAG) mintát használva csevegőalkalmazást hoz létre, győződjön meg arról, hogy minden felhasználó a jogosultságainak megfelelő választ kapjon. A jelen cikkben ismertetett eljárást követve dokumentumhozzáférés-vezérlést adhat hozzá a csevegőalkalmazáshoz.

  • Jogosult felhasználói: Ennek a személynek hozzáféréssel kell rendelkeznie a csevegőalkalmazás dokumentumaiban található válaszokhoz.

    Képernyőkép, amely a csevegőalkalmazást jeleníti meg a szükséges hitelesítési hozzáféréssel rendelkező válaszsal.

  • Jogosulatlan felhasználói: Ennek a személynek nem szabad hozzáféréssel rendelkeznie az olyan biztonságos dokumentumok válaszaihoz, amelyek megtekintéséhez nincs engedélye.

    Képernyőkép a csevegőalkalmazásról egy olyan válaszsal, amely azt jelzi, hogy a felhasználó nem fér hozzá az adatokhoz.

Jegyzet

A cikk a példák és útmutatók alapjául egy vagy több AI-alkalmazássablont használ. Az AI-alkalmazássablonok könnyen üzembe helyezhető, jól karbantartott referencia-implementációkat biztosítanak. Segítenek magas színvonalú kiindulópontot biztosítani az AI-alkalmazások számára.

Architektúra áttekintése

Dokumentumbiztonsági funkció nélkül a vállalati csevegőalkalmazás egyszerű architektúrával rendelkezik az Azure AI Keresés és az Azure OpenAI-modellek használatával a Microsoft Foundryben. A rendszer választ határoz meg lekérdezések alapján az Azure AI Keresés segítségével, ahol a dokumentumok tárolva vannak, az Azure OpenAI GPT-modell válaszával együtt. Ebben az egyszerű folyamatban nincs felhasználói hitelesítés.

Architekturális diagram, amely bemutatja, hogy az Azure AI Keresés hogyan talál válaszokat a tárolt dokumentumokból, és hogyan kombinálja őket az Azure OpenAI válaszával.

A dokumentumok biztonságának hozzáadásához frissítenie kell a vállalati csevegőalkalmazást:

  • Ügyfél-hitelesítés hozzáadása a csevegőalkalmazáshoz a Microsoft Entra használatával.
  • Adjon hozzá kiszolgálóoldali logikát a keresési index felhasználói és csoporthozzáférésekkel való feltöltéséhez.

Architektúradiagram, amely azt mutatja be, hogy egy felhasználó hitelesíti a Microsoft Entra-azonosítót, majd átadja a hitelesítést az Azure AI Keresésnek.

Az Azure AI Keresés nem biztosít natív dokumentumszintű engedélyeket, és a keresési eredményeket nem módosíthatja az indexben a felhasználói engedélyek alapján. Ehelyett az alkalmazás keresési szűrőkkel biztosíthatja, hogy egy dokumentum elérhető legyen egy adott felhasználó vagy egy adott csoport számára. A keresési indexben minden dokumentumnak rendelkeznie kell egy szűrhető mezővel, amely a felhasználói vagy csoportidentitás-adatokat tárolja.

Architekturális diagram, amely azt mutatja, hogy az Azure AI Keresés minden dokumentuma rendelkezik felhasználói hitelesítéssel, amely megjelenik a keresési eredményekben.

Mivel az engedélyezés nem található natív módon az Azure AI Keresésben, hozzá kell adnia egy mezőt a felhasználói vagy csoportadatok tárolásához, majd szűrni a nem egyező dokumentumokat. A technika implementálásához a következőkre van szükség:

  • Hozzon létre egy dokumentumhozzáférés-vezérlési mezőt az indexben, amely a dokumentumhozzáféréssel rendelkező felhasználók vagy csoportok adatait tárolja.
  • Töltse ki a dokumentum hozzáférés-vezérlési mezőjét a megfelelő felhasználó- vagy csoportadatokkal.
  • Frissítse ezt a hozzáférés-vezérlési mezőt, amikor a felhasználói vagy csoporthozzáférés-engedélyek módosulnak.

Ha az indexfrissítések indexelővel vannak ütemezve, a módosítások a következő indexelő futtatásakor lesznek elérhetők. Ha nem használ indexelőt, manuálisan kell újraindexelnie.

Ebben a cikkben a dokumentumok Azure AI Keresésben való biztonságossá tételének folyamatát példa szkriptekkel teszi lehetővé, amelyeket Ön, mint a keresési rendszergazda futtatna. A szkriptek egyetlen dokumentumot társítanak egyetlen felhasználói identitáshoz. A szkripteket saját biztonsági és működési követelményekkel alkalmazhatja, hogy igényeihez igazítsa a méreteket.

Biztonsági konfiguráció meghatározása

A megoldás logikai környezeti változókat biztosít a mintában szereplő dokumentumbiztonsághoz szükséges funkciók bekapcsolásához.

Paraméter Cél
AZURE_USE_AUTHENTICATION Ha trueértékre van állítva, engedélyezi a felhasználók bejelentkezését a csevegőalkalmazásba és az Azure App Service-hitelesítésbe. Engedélyezi a Use oid security filter-t a csevegőalkalmazásban a Fejlesztői beállításokban.
AZURE_ENFORCE_ACCESS_CONTROL Ha trueértékre van állítva, minden dokumentum-hozzáféréshez hitelesítésre van szükség. Az objektumazonosító (OID) és a csoportbiztonság fejlesztői beállítások be vannak kapcsolva és le vannak tiltva, hogy ne tilthassák le őket a felhasználói felületen.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS Ha trueértékre van állítva, ez a beállítás lehetővé teszi a hitelesített felhasználók számára, hogy olyan dokumentumokban keressenek, amelyekhez nincs hozzáférés-vezérlés hozzárendelve, még akkor is, ha hozzáférés-vezérlésre van szükség. Ezt a paramétert csak akkor szabad használni, ha AZURE_ENFORCE_ACCESS_CONTROL engedélyezve van.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS Ha trueértékre van állítva, ez a beállítás lehetővé teszi, hogy a hitelesítés nélküli felhasználók is használják az alkalmazást, még akkor is, ha a hozzáférés-vezérlés kényszerítve van. Ezt a paramétert csak akkor szabad használni, ha AZURE_ENFORCE_ACCESS_CONTROL engedélyezve van.

Az alábbi szakaszokban megismerheti a mintában támogatott biztonsági profilokat. Ez a cikk a Vállalati profilbeállításait tartalmazza.

Vállalati: Kötelező fiók + dokumentumszűrő

A webhely minden felhasználójának be kell jelentkeznie. A webhely minden felhasználó számára nyilvános tartalmat tartalmaz. A dokumentumszintű biztonsági szűrő minden kérésre érvényes.

Környezeti változók:

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

Vegyes használat: Nem kötelező fiók + dokumentumszűrő

A webhely minden felhasználója bejelentkezhet . A webhely minden felhasználó számára nyilvános tartalmat tartalmaz. A dokumentumszintű biztonsági szűrő minden kérésre érvényes.

Környezeti változók:

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

Előfeltételek

A fejlesztői tároló környezet elérhető minden olyan függőséggel, amelyek a cikk elkészítéséhez szükségesek. A fejlesztői tárolót a GitHub Codespacesben (böngészőben) vagy helyileg is futtathatja a Visual Studio Code használatával.

A cikk használatához a következő előfeltételekre van szüksége:

Az előnyben részesített fejlesztési környezettől függően további előfeltételekre van szüksége.

Fejlesztői környezet megnyitása

A cikk elvégzéséhez használja az alábbi utasításokat egy előre konfigurált fejlesztési környezet üzembe helyezéséhez, amely tartalmazza az összes szükséges függőséget.

GitHub Codespaces a GitHub által felügyelt fejlesztői tárolót futtatja a webes Visual Studio Code-tal felhasználói felületként. A legegyszerűbb fejlesztési környezethez használja a GitHub Codespacest, hogy a megfelelő fejlesztői eszközökkel és függőségekkel rendelkezzen a cikk elvégzéséhez.

Fontos

Minden GitHub-fiók legfeljebb 60 órán át használhatja a GitHub Codespace-eket havonta két alapvető példánnyal. További információért lásd: GitHub Codespaces havi tartalmazott tárterület és alapórák.

  1. Indítsa el az új GitHub-kódtér létrehozását az main GitHub-adattár ágán.

  2. Kattintson jobb gombbal a következő gombra, majd válassza a Hivatkozás megnyitása új ablakban lehetőséget, hogy a fejlesztési környezet és a dokumentáció egyszerre legyen elérhető.

    Megnyitás a GitHub Codespacesben.

  3. A Kódtér létrehozása lapon tekintse át a kódtér konfigurációs beállításait, majd válassza az Új kódtér létrehozása lehetőséget.

    Új kódtér létrehozása előtt a megerősítést kérő képernyő képernyőképe.

  4. Várja meg, amíg a kódtér elindul. Ez az indítási folyamat eltarthat néhány percig.

  5. A képernyő alján lévő terminálon jelentkezzen be az Azure-ba az Azure Developer CLI használatával.

    azd auth login
    
  6. Fejezze be a hitelesítési folyamatot.

  7. A cikkben szereplő fennmaradó feladatok ennek a fejlesztési tárolónak a kontextusában történnek.

A szükséges információk lekérése az Azure CLI-vel

Kérje le az előfizetés azonosítóját és a bérlőazonosítót az alábbi Azure CLI-paranccsal. Másolja ki a AZURE_TENANT_ID értékként használni kívánt értéket.

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

Ha hibaüzenetet kap a bérlő feltételes hozzáférési szabályzatáról, szüksége lesz egy második, feltételes hozzáférési szabályzat nélküli bérlőre.

  • A rendszer a felhasználói fiókjához társított első bérlőt használja a AZURE_TENANT_ID környezeti változóhoz.
  • A második, feltételes hozzáféréssel nem rendelkező bérlőt a AZURE_AUTH_TENANT_ID környezeti változó használja a Microsoft Graph eléréséhez. Feltételes hozzáférési szabályzattal rendelkező bérlők esetén keresse meg egy második bérlő azonosítóját feltételes hozzáférési szabályzat nélkül, vagy hozzon létre egy új bérlői.

Környezeti változók beállítása

  1. Futtassa az alábbi parancsokat az alkalmazásnak a Enterprise profil szerint történő konfigurálásához.

    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. Futtassa a következő parancsot a bérlő beállításához, amely engedélyezi a felhasználó bejelentkezését az üzemeltetett alkalmazáskörnyezetbe. Cserélje le a <YOUR_TENANT_ID>-t a bérlőazonosítóra.

    azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
    

Jegyzet

Ha feltételes hozzáférési szabályzattal rendelkezik a felhasználói bérlőn, meg kell adnia egy hitelesítési bérlőt.

A csevegőalkalmazás üzembe helyezése az Azure-ban

Az üzembe helyezés a következő lépésekből áll:

  • Hozza létre az Azure-erőforrásokat.
  • Töltse fel a dokumentumokat.
  • Hozza létre a Microsoft Entra identitásalkalmazásokat (ügyfél és kiszolgáló).
  • Kapcsolja be az identitást az üzemeltetési erőforráshoz.
  1. Az Azure-erőforrások kiépítése és a forráskód üzembe helyezése.

    azd up
    
  2. Az alábbi táblázat segítségével válaszolhat a AZD üzembe helyezési kérésekre.

    Haladéktalan Válasz
    Környezet neve Használjon rövid nevet az olyan információk azonosításához, mint az alias és az alkalmazás. Példa: tjones-secure-chat.
    Előfizetés Válassza ki azt az előfizetést, amelyben létre szeretné hozni az erőforrásokat.
    Azure-erőforrások helye Válasszon egy Önhöz közeli helyet.
    A documentIntelligentResourceGroupLocation helye Válasszon egy Önhöz közeli helyet.
    A openAIResourceGroupLocation helye Válasszon egy Önhöz közeli helyet.

    Várjon 5 vagy 10 percet az alkalmazás üzembe helyezése után, hogy az alkalmazás elindulhasson.

  3. Az alkalmazás sikeres üzembe helyezése után megjelenik egy URL-cím a terminálban.

  4. Válassza ki a (✓) Done: Deploying service webapp címkével ellátott URL-címet a csevegőalkalmazás böngészőben való megnyitásához.

    Képernyőkép a csevegőalkalmazásról egy böngészőben csevegési javaslatokkal és a csevegés szövegmezőjével.

  5. Fogadja el az alkalmazáshitelesítés előugró ablakát.

  6. Amikor megjelenik a csevegőalkalmazás, figyelje meg a jobb felső sarokban, hogy a felhasználó bejelentkezett.

  7. Nyissa meg fejlesztői beállításokat, és figyelje meg, hogy a módosításhoz az alábbi lehetőségek közül mindkét lehetőség ki van választva és le van tiltva:

    • Használja az oid biztonsági szűrőt
    • Csoportok biztonsági szűrőjének használata
  8. Válassza ki a kártyát: Mit csinál egy termékmenedzser?.

  9. A következőhöz hasonló választ kap: A megadott források nem tartalmaznak konkrét információkat a Contoso Electronics termékmenedzserének szerepéről.

    Képernyőkép egy csevegőalkalmazás böngészőben való megjelenítéséről, amely azt mutatja, hogy a válasz nem adható vissza.

Dokumentumhoz való hozzáférés megnyitása egy felhasználó számára

Kapcsolja be az engedélyeket a pontos dokumentumhoz, hogy kaphassa meg a választ. Több információra van szüksége:

  • Azure Storage
    • Fióknév
    • Tároló neve
    • Blob-dokumentum URL role_library.pdf
  • Felhasználó azonosítója a Microsoft Entra-azonosítóban

Ha ez az információ ismert, frissítse az Azure AI Keresés index oids mezőt a role_library.pdf dokumentumhoz.

Dokumentum URL-címének lekérése a tárban

  1. A projekt gyökerében található .azure mappában keresse meg a környezeti könyvtárat, és nyissa meg a .env fájlt ezzel a könyvtárral.

  2. Keresse meg a AZURE_STORAGE_ACCOUNT bejegyzést, és másolja ki az értékét.

  3. Az alábbi Azure CLI-parancsokkal kérje le a role_library.pdf blob URL-címét a content tárolóban.

    az storage blob url \
        --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
        --container-name 'content' \
        --name 'role_library.pdf' 
    
    Paraméter Cél
    --account-name Azure Storage-fiók neve.
    --container-name A mintában szereplő tároló neve content.
    --név Ebben a lépésben a blob neve role_library.pdf.
  4. Másolja ki a blob URL-címét későbbi használatra.

A felhasználói azonosító lekérése

  1. A csevegőalkalmazásban válassza Fejlesztői beállításoklehetőséget.
  2. Az ID-jogkivonat igényeinek szakaszában másolja ki a objectidentifier paramétert. Ez a paraméter a következő szakaszban USER_OBJECT_IDnéven ismert.
  1. Az alábbi szkripttel módosíthatja a oids mezőt az Azure AI Keresésben a role_library.pdf keresésében, hogy hozzáférése legyen hozzá.

    python ./scripts/manageacl.py --acl-type oids --acl-action add --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
    
    Paraméter Cél
    -v Részletes kimenet.
    --acl-type (hozzáférés-ellenőrzési lista típus) Csoport- vagy felhasználói azonosítók: oids.
    --acl-action hozzáadása keresési indexmezőhöz. Egyéb lehetőségek: enable_acls, remove, remove_allés view.
    --Acl Csoport vagy felhasználó USER_OBJECT_ID.
    --url A fájl helye az Azure Storage-ban, például https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Ne vegye körül az URL-címet idézőjelekkel a parancssorban.
  2. A parancs konzolkimenete a következőképpen néz ki:

    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. Ha szeretné, az alábbi paranccsal ellenőrizze, hogy az Ön engedélye szerepel-e a fájlhoz az Azure AI Keresésben.

    python ./scripts/manageacl.py -v --acl-type groups --acl-action view --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
    
    Paraméter Cél
    -v Részletes kimenet.
    --acl-type (hozzáférés-ellenőrzési lista típus) Csoport- vagy felhasználói azonosítók: oids.
    --acl-action Keresési index mező oidsmegtekintése. Egyéb lehetőségek: enable_acls, remove, remove_allés add.
    --url A fájl helyének megjelölése, például https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Ne vegye körül az URL-címet idézőjelekkel a parancssorban.
  4. A parancs konzolkimenete a következőképpen néz ki:

    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]
    

    A kimenet végén található tömb tartalmazza a USER_OBJECT_ID paramétert, és annak meghatározására szolgál, hogy a dokumentum szerepel-e a válaszban az Azure OpenAI-val.

Ellenőrizze, hogy az Azure AI Keresés tartalmazza-e a USER_OBJECT_ID

  1. Nyissa meg az Azure Portal, és keresse meg a AI Search.

  2. Válassza ki a keresési erőforrást a listából.

  3. Válassza Kereséskezelés>Indexeklehetőséget.

  4. Válassza gptkbindexlehetőséget.

  5. Válassza a Nézet>JSON-nézetlehetőséget.

  6. Cserélje le a JSON-t a következő JSON-ra:

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

    Ez a JSON minden olyan dokumentumot keres, amelyben a oids mező bármilyen értékkel rendelkezik, és visszaadja a sourcefile és oids mezőket.

  7. Ha a nem rendelkezik az Ön OID-jával, térjen vissza a szakaszban lévő Az Azure Search felhasználói hozzáférés biztosításához dokumentumhoz, és végezze el a lépéseket.

A dokumentumhoz való felhasználói hozzáférés ellenőrzése

Ha elvégezte a lépéseket, de nem látja a helyes választ, ellenőrizze, hogy a USER_OBJECT_ID paraméter helyesen van-e beállítva az Azure AI Keresés for role_library.pdf.

  1. Térjen vissza a csevegőalkalmazáshoz. Előfordulhat, hogy újra be kell jelentkeznie.

  2. Adja meg ugyanazt a lekérdezést, hogy az Azure OpenAI a role_library tartalmat használja a válaszában: What does a product manager do?.

  3. Tekintse meg az eredményt, amely most már tartalmazza a szerepkörtár dokumentumából kapott megfelelő választ.

    Képernyőkép, amely egy csevegőalkalmazást mutat be a böngészőben, amikor a válasz visszaérkezik.

Erőforrások törlése

Az alábbi lépések végigvezetik a használt erőforrások megtisztításának folyamatán.

Azure-erőforrások tisztítása

A cikkben létrehozott Azure-erőforrások költsége az Azure-előfizetésedre kerül kiszámlázásra. Ha a jövőben nem lesz szüksége ezekre az erőforrásokra, törölje őket, hogy elkerülje a további költségek felmerülését.

Futtassa a következő Azure Developer CLI-parancsot az Azure-erőforrások törléséhez és a forráskód eltávolításához.

azd down --purge

A GitHub Codespaces és a Visual Studio Code eltávolítása

Az alábbi lépések végigvezetik a használt erőforrások megtisztításának folyamatán.

A GitHub Codespaces-környezet törlése biztosítja, hogy maximálisan kihasználható legyen a fiókhoz tartozó ingyenes óránkénti jogosultság.

Fontos

További információ a GitHub-fiók jogosultságairól: lásd GitHub Codespaces havi tárhely- és alapóra-keret.

  1. Lépjen be a GitHub Codespaces irányítópultra.

  2. Keresse meg az azure-samples/azure-search-openai-demo GitHub-adattárból származó, jelenleg futó kódtereket.

    Képernyőkép az összes futó kódtérről, beleértve azok állapotát és sablonjait.

  3. Nyissa meg a kódtér helyi menüjét, majd válassza a Törléslehetőséget.

    Képernyőkép, amely egyetlen kódtér helyi menüjét jeleníti meg a Törlés lehetőség kiemelésével.

Segítség kérése

A mintaadattár hibaelhárítási információkat nyújt.

Hibaelhárítás

Ez a szakasz segítséget nyújt a cikkhez kapcsolódó problémák elhárításában.

Hitelesítési felhasználói fiók megadása

Ha a hitelesítés egy gazdaalkalmazástól eltérő bérlőben található, az autentikációs bérlőt a következő eljárással kell beállítania.

  1. Futtassa a következő parancsot, hogy a példát úgy állítsa be, hogy egy második bérlőt használjon hitelesítésre.

    azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
    
    Paraméter Cél
    AZURE_AUTH_TENANT_ID Ha AZURE_AUTH_TENANT_ID van beállítva, akkor az a bérlő az alkalmazás üzemeltetője.
  2. Telepítse újra a megoldást a következő paranccsal:

    azd up