Megosztás a következőn keresztül:


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

Ha saját adatokkal hoz létre egy csevegőalkalmazást a RAG-minta alapján, győződjön meg arról, hogy minden felhasználó az engedélyei alapján kap választ. A jelen cikkben ismertetett eljárást követve dokumentumhozzáférés-vezérlést adhat hozzá a csevegőalkalmazáshoz.

A jogosult felhasználónak hozzáféréssel kell rendelkeznie a csevegőalkalmazás dokumentumaiban található válaszokhoz.

Képernyőkép a csevegőalkalmazásról a szükséges hitelesítési hozzáféréssel rendelkező válaszokkal.

Egy jogosulatlan felhasználónak nem szabad hozzáféréssel rendelkeznie az olyan biztonságos dokumentumok válaszaihoz, amelyek megtekintésére nem jogosult.

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

Feljegyzés

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

Architekturális áttekintés

Dokumentumbiztonsági funkció nélkül a vállalati csevegőalkalmazás egyszerű architektúrával rendelkezik az Azure AI Search és az Azure OpenAI használatával. A rendszer választ határoz meg a lekérdezésekből az Azure AI Searchbe, ahol a dokumentumok tárolása történik, és egy Azure OpenAI GPT-modell válaszával együtt. Ebben az egyszerű folyamatban nincs felhasználói hitelesítés.

Architekturális diagram, amely a lekérdezésekből az Azure AI Searchbe adott választ mutatja, ahol a dokumentumok tárolása történik, az Azure OpenAI gyors válaszával együtt.

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 a Microsoft Entra-azonosítóval való hitelesítést, majd a hitelesítés azure AI Search-nek való átadását mutatja be.

Az Azure AI Search nem biztosít natív dokumentumszintű engedélyeket, és nem tudja a keresési eredményeket az indexen belülről felhasználói engedélyek alapján eltérően használni. 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.

Architektúradiagram, amely azt mutatja be, hogy az Azure AI Searchben a dokumentumok védelme érdekében minden dokumentum tartalmaz felhasználói hitelesítést, amelyet a rendszer visszaad az eredményhalmazban.

Mivel az engedélyezés nem található natív módon az Azure AI Searchben, fel kell vennie egy mezőt a felhasználói vagy csoportadatok tárolásához, majd szűrnie kell 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 Searchben való biztonságossá tételének folyamatát példaszkriptekkel tették lehetővé, amelyeket Ön, mint a keresési rendszergazda futtatna. A szkriptek egyetlen dokumentumot társítanak egyetlen felhasználói identitáshoz. Ezeket a szkripteket használhatja, és saját biztonsági és élesítési követelményeket alkalmazhat az igényeinek megfelelően.

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 be van trueállítva, engedélyezi a felhasználó bejelentkezését a csevegőalkalmazásba és az App Service-hitelesítésbe. Engedélyezi Use oid security filter a csevegőalkalmazás fejlesztői beállításait.
AZURE_ENFORCE_ACCESS_CONTROL Ha be van trueállítva, minden dokumentum-hozzáféréshez hitelesítésre van szükség. Az oid- és csoportbiztonság fejlesztői beállításai be lesznek kapcsolva és le lesznek tiltva, így nem tilthatók le a felhasználói felületen.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS Ha be van trueá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 be van trueállítva, ez a beállítás lehetővé teszi a hitelesítés nélküli felhasználók számára az alkalmazás használatát, 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 konfigurálja a vállalati profilt.

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

A webhely minden felhasználójának be kell jelentkeznie, és 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=igaz
  • AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=igaz
  • AZURE_ENFORCE_ACCESS_CONTROL=igaz

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

A webhely minden felhasználója bejelentkezhet , és 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=igaz
  • AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=igaz
  • AZURE_ENFORCE_ACCESS_CONTROL=igaz
  • AZURE_ENABLE_UNAUTHENTICATED_ACCESS=igaz

Előfeltételek

A cikk elvégzéséhez szükséges összes függőséget tartalmazó fejlesztői tárolókörnyezet érhető el. 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.

Nyílt fejlesztési környezet

Kezdje most a jelen cikk végrehajtásához telepített összes függőséget tartalmazó fejlesztői környezettel.

A GitHub Codespaces egy, a GitHub által felügyelt fejlesztői tárolót futtat 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 Codespace-eket havonta 2 magpéldánysal. További információ: GitHub Codespaces havonta tartalmazza a tárterületet és az alapórákat.

  1. Indítsa el az új GitHub Codespace létrehozásának folyamatát a mainAzure-Samples/azure-search-openai-demo GitHub-adattár ágán.

  2. Kattintson a jobb gombbal a következő gombra, és válassza a Megnyitás hivatkozást az új ablakokban , hogy egyszerre legyen elérhető a fejlesztési környezet és a dokumentáció is.

    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

    Képernyőkép a megerősítést kérő képernyőről egy új kódtér létrehozása előtt.

  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 használni kívánt értéket.AZURE_TENANT_ID

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 rendszer a második, feltételes hozzáférés nélküli bérlőt használja a környezeti változóhoz a AZURE_AUTH_TENANT_ID 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őt.

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

  1. Futtassa az alábbi parancsokat az alkalmazás vállalati profilhoz való 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ónak a üzemeltetett alkalmazáskörnyezetbe való bejelentkezést. Cserélje le <YOUR_TENANT_ID> a bérlőazonosítót.

    azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
    

Feljegyzés

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.

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

Az üzembe helyezés magában foglalja az Azure-erőforrások létrehozását, a dokumentumok feltöltését, a Microsoft Entra identitásalkalmazások (ügyfél- és kiszolgáló) létrehozását, valamint az identitás bekapcsolását az üzemeltetési erőforráshoz.

  1. Futtassa a következő Azure Developer CLI-parancsot az Azure-erőforrások kiépítéséhez és a forráskód üzembe helyezéséhez:

    azd up
    
  2. Az AZD üzembe helyezési kéréseinek megválaszolásához használja az alábbi táblázatot:

    Felszólítás 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: tjones-secure-chat.
    Előfizetés Válassza ki az előfizetést az erőforrások létrehozásához.
    Azure-erőforrások helye Válasszon egy közeli helyet.
    Hely a következőhöz: documentIntelligentResourceGroupLocation Válasszon egy közeli helyet.
    Hely a következőhöz: openAIResourceGroupLocation Válasszon egy 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 címkével ellátott URL-címet (✓) Done: Deploying service webapp a csevegőalkalmazás böngészőben való megnyitásához.

    Képernyőkép a csevegőalkalmazásról a böngészőben, amelyen számos javaslat látható a csevegés bemenetére, valamint a kérdés megadására szolgáló csevegő szövegmező.

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

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

  7. Nyissa meg a fejlesztői beállításokat , és figyelje meg, hogy mindkét beállítás ki van jelölve és szürkítve jelenik meg (a módosítás letiltva).

    • Az oid biztonsági szűrő használata
    • Csoportok biztonsági szűrőjének használata
  8. Válassza ki a kártyát a következővel What does a product manager do?: .

  9. A következő választ kapja: The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

    Képernyőkép a csevegőalkalmazásról a böngészőben, amelyen a válasz nem adható vissza

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

Kapcsolja be a pontos dokumentum engedélyeit, hogy megkapja a választ. Ezekhez több információra van szükség:

  • Azure Storage
    • Számla neve
    • Tárolónév
    • Blob/dokumentum URL-címe a következőhöz: role_library.pdf
  • Felhasználó azonosítója a Microsoft Entra-azonosítóban

Miután ez az információ ismert, frissítse a dokumentum Azure AI Search indexmezőjének oidsrole_library.pdf tartalmát.

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

  1. .azure A projekt gyökérmappájában keresse meg a környezeti könyvtárat, és nyissa meg a fájlt ezzel a .env könyvtárral.

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

  3. Az alábbi Azure CLI-parancsokkal lekérheti a tartalomtárolóban található role_library.pdf blob URL-címét.

    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ónév a következő: content
    --név A blob neve ebben a lépésben a következő: 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 chap alkalmazásban válassza a Fejlesztői beállítások lehetőséget.
  2. Az Azonosító jogkivonat jogcímek szakaszában másolja ki a sajátjátobjectidentifier. Ezt a következő szakaszban USER_OBJECT_IDa .
  1. Az alábbi szkripttel módosíthatja az oids Azure AI Search role_library.pdf mezőit, hogy hozzáférhessen.

    ./scripts/manageacl.sh \
        -v \
        --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 Csoport- vagy felhasználói objektumazonosítók (OID-k): oids
    --acl-action Hozzáadás keresési indexmezőhöz. Egyéb lehetőségek: remove, remove_all. list
    --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 PARANCSSOR-parancsban.
  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 Searchben.

    ./scripts/manageacl.sh \
        -v \
        --acl-type oids \
        --acl-action list \
        --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
        --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
    
    Paraméter Cél
    -v Részletes kimenet.
    --acl-type Csoport vagy felhasználó (oidok): oids
    --acl-action Keresési index mező oidslistázása. Egyéb lehetőségek: remove, remove_all. list
    --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 PARANCSSOR-parancsban.
  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, és annak meghatározására szolgál, hogy a dokumentum szerepel-e az Azure OpenAI válaszában.

Ellenőrizze, hogy az Azure AI Search tartalmazza-e a USER_OBJECT_ID

  1. Nyissa meg az Azure Portalt, és keressen rá.AI Search

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

  3. Válassza a Kereséskezelés –> Indexek lehetőséget.

  4. Válassza ki a gptkbindexet.

  5. Válassza a Nézet –> JSON nézetet.

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

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

    Ez az összes olyan dokumentumot megkeresi, amelyben a oids mező bármilyen értékkel rendelkezik, és visszaadja a , és oids a sourcefilemezőket.

  7. Ha az role_library.pdf objektum nem rendelkezik az ön objektumával, térjen vissza a Felhasználó hozzáférésének biztosítása egy dokumentumhoz az Azure Search szakaszban, é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 megfelelően van-e role_library.pdfbeállítva az Azure AI Searchben.

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

  2. Adja meg ugyanazt a lekérdezést, hogy a role_library tartalom az Azure OpenAI-válaszban legyen használva: 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 a csevegőalkalmazásról a böngészőben, amelyen a válasz megjelenik.

Az erőforrások eltávolítása

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

A cikkben létrehozott Azure-erőforrások számlázása az Azure-előfizetésbe kerül. 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

GitHub-kódterek eltávolítása

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

A GitHub-fiók jogosultságairól további információt a GitHub Codespaces havi tartalmazza a tárterületet és az alapórákat.

  1. Jelentkezzen be a GitHub Codespaces irányítópultjára (https://github.com/codespaces).

  2. Keresse meg a Jelenleg futó, a Azure-Samples/azure-search-openai-demo GitHub-adattárból származó 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és lehetőséget.

    Képernyőkép egyetlen kódtér helyi menüjéről a törlési lehetőség kiemelésével.

Segítség kérése

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

Hibaelhárítás

Ez a szakasz a cikkhez kapcsolódó problémák hibaelhárítását ismerteti.

Hitelesítési bérlő megadása

Ha a hitelesítés az üzemeltetési alkalmazástól eltérő bérlőben található, a hitelesítési bérlőt az alábbi eljárással kell beállítania.

  1. Futtassa a következő parancsot, hogy konfigurálja a mintát úgy, hogy egy második bérlőt használjon a hitelesítési bérlőhöz.

    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 be van állítva, az az alkalmazást üzemeltető bérlő.
  2. Telepítse újra a megoldást az alábbi paranccsal.

    azd up
    

Következő lépések