Introduzione alla sicurezza dei documenti di chat per Python
Quando si compila un'applicazione di chat usando il modello RAG con i propri dati, assicurarsi che ogni utente riceva una risposta in base alle relative autorizzazioni. Seguire la procedura descritta in questo articolo per aggiungere il controllo di accesso ai documenti all'app di chat.
Un utente autorizzato deve avere accesso alle risposte contenute nei documenti dell'app di chat.
Un utente non autorizzato non deve avere accesso alle risposte da documenti protetti che non hanno l'autorizzazione per visualizzare.
Nota
Questo articolo usa uno o più modelli di app di intelligenza artificiale come base per gli esempi e le linee guida nell’articolo. I modelli di app di intelligenza artificiale offrono implementazioni di riferimento ben gestite e facili da distribuire per garantire un punto di partenza di alta qualità per le app di intelligenza artificiale.
Senza la funzionalità di sicurezza dei documenti, l'app di chat aziendale ha un'architettura semplice usando Ricerca di intelligenza artificiale di Azure e Azure OpenAI. Una risposta viene determinata dalle query a Ricerca di intelligenza artificiale di Azure in cui vengono archiviati i documenti, in combinazione con una risposta da un modello GPT di Azure OpenAI. In questo semplice flusso non viene usata alcuna autenticazione utente.
Per aggiungere sicurezza per i documenti, è necessario aggiornare l'app di chat aziendale:
- Aggiungere l'autenticazione client all'app di chat con Microsoft Entra.
- Aggiungere la logica lato server per popolare un indice di ricerca con accesso utente e gruppo.
Ricerca di intelligenza artificiale di Azure non fornisce autorizzazioni native a livello di documento e non può variare i risultati della ricerca dall'interno di un indice in base alle autorizzazioni utente. L'applicazione può invece usare filtri di ricerca per garantire che un documento sia accessibile a un utente specifico o a un gruppo specifico. All'interno dell'indice di ricerca, ogni documento deve avere un campo filtrabile che archivia le informazioni sull'identità dell'utente o del gruppo.
Poiché l'autorizzazione non è contenuta in modo nativo in Ricerca di intelligenza artificiale di Azure, è necessario aggiungere un campo per contenere informazioni sull'utente o sul gruppo, quindi filtrare i documenti che non corrispondono. Per implementare questa tecnica, è necessario:
- Creare un campo di controllo di accesso al documento nell'indice dedicato all'archiviazione dei dettagli di utenti o gruppi con accesso ai documenti.
- Popolare il campo di controllo di accesso del documento con i dettagli dell'utente o del gruppo pertinenti.
- Aggiornare questo campo di controllo di accesso ogni volta che vengono apportate modifiche alle autorizzazioni di accesso a utenti o gruppi.
- Se gli aggiornamenti dell'indice sono pianificati con un indicizzatore, le modifiche vengono prelevate nell'esecuzione successiva dell'indicizzatore. Se non si usa un indicizzatore, è necessario reindicizzare manualmente.
In questo articolo il processo di protezione dei documenti in Ricerca di intelligenza artificiale di Azure è reso possibile con gli script di esempio eseguiti dall'amministratore della ricerca. Gli script associano un singolo documento a una singola identità utente. È possibile accettare questi script e applicare requisiti di sicurezza e produzione personalizzati per adattarli alle proprie esigenze.
La soluzione fornisce variabili di ambiente booleane per attivare le funzionalità necessarie per la sicurezza dei documenti in questo esempio.
Parametro | Scopo |
---|---|
AZURE_USE_AUTHENTICATION |
Se impostato su true , abilita l'accesso utente all'app di chat e servizio app l'autenticazione. Abilita Use oid security filter nelle impostazioni sviluppatore dell'app di chat. |
AZURE_ENFORCE_ACCESS_CONTROL |
Se impostato su true , richiede l'autenticazione per qualsiasi accesso ai documenti. Le impostazioni sviluppatore per la sicurezza dell'oid e del gruppo verranno attivate e disabilitate in modo che non possano essere disabilitate dall'interfaccia utente. |
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS |
Se impostata su true , questa impostazione consente agli utenti autenticati di cercare nei documenti senza controlli di accesso assegnati, anche quando è necessario il controllo di accesso. Questo parametro deve essere usato solo quando AZURE_ENFORCE_ACCESS_CONTROL è abilitato. |
AZURE_ENABLE_UNAUTHENTICATED_ACCESS |
Se impostata su true , questa impostazione consente agli utenti non autenticati di usare l'app, anche quando viene applicato il controllo di accesso. Questo parametro deve essere usato solo quando AZURE_ENFORCE_ACCESS_CONTROL è abilitato. |
Usare le sezioni seguenti per comprendere i profili di sicurezza supportati in questo esempio. Questo articolo configura il profilo Enterprise.
Ogni utente del sito deve accedere e il sito contiene contenuto pubblico per tutti gli utenti. Il filtro di sicurezza a livello di documento viene applicato a tutte le richieste.
Variabili di ambiente:
- AZURE_USE_AUTHENTICATION=true
- AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
- AZURE_ENFORCE_ACCESS_CONTROL=true
Ogni utente del sito può accedere e il sito contiene contenuto pubblico per tutti gli utenti. Il filtro di sicurezza a livello di documento viene applicato a tutte le richieste.
Variabili di ambiente:
- AZURE_USE_AUTHENTICATION=true
- AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
- AZURE_ENFORCE_ACCESS_CONTROL=true
- AZURE_ENABLE_UNAUTHENTICATED_ACCESS=true
Per completare questo articolo è disponibile un ambiente contenitore di sviluppo con tutte le dipendenze necessarie. Puoi eseguire il contenitore di sviluppo in GitHub Codespaces (in un browser) o in locale usando Visual Studio Code.
Per usare questo articolo, sono necessari i prerequisiti seguenti:
- Abbonamento di Azure. Crearne uno gratuito
- Autorizzazioni per l'account Azure: l'account Azure deve avere
- Autorizzazione per gestire le applicazioni in Microsoft Entra ID.
- Autorizzazioni Microsoft.Authorization/roleAssignments/write, ad esempio Amministratore accesso utenti o Proprietario.
- Accesso concesso ad Azure OpenAI nella sottoscrizione di Azure desiderata. Attualmente, l'accesso a questo servizio viene concesso solo dall'applicazione. È possibile richiedere l'accesso a OpenAI di Azure completando il modulo all'indirizzo https://aka.ms/oai/access.
Sono necessari altri prerequisiti a seconda dell'ambiente di sviluppo preferito.
Inizia ora con un ambiente di sviluppo che ha tutte le dipendenze installate per completare questo articolo.
GitHub Codespaces esegue un contenitore di sviluppo gestito da GitHub con Visual Studio Code per il Web come interfaccia utente. Per l'ambiente di sviluppo più semplice, usa GitHub Codespaces per avere gli strumenti di sviluppo e le dipendenze corretti preinstallati per completare questo articolo.
Importante
Tutti gli account GitHub possono usare Codespaces per un massimo di 60 ore gratuite ogni mese con 2 istanze di core. Per altre informazioni, vedere Spazio di archiviazione e ore core mensili inclusi in GitHub Codespaces.
Avviare il processo per creare un nuovo codespace GitHub nel ramo
main
del repository GitHubAzure-Samples/azure-search-openai-demo
.Fai clic con il pulsante destro del mouse sul pulsante seguente e scegli Apri collegamento in nuove finestre per avere a disposizione allo stesso tempo sia l'ambiente di sviluppo che la documentazione.
Nella pagina Crea codespace esaminare le impostazioni di configurazione del codespace e quindi selezionare Crea nuovo codespace
Attendere l'avvio del codespace. Questo processo di avvio può richiedere alcuni minuti.
Nel terminale nella parte inferiore della schermata, accedi ad Azure con Azure Developer CLI.
azd auth login
Completare il processo di autenticazione.
Le attività rimanenti in questo articolo vengono eseguite nel contesto di questo contenitore di sviluppo.
Ottenere l'ID sottoscrizione e l'ID tenant con il comando dell'interfaccia della riga di comando di Azure seguente. Copiare il valore da usare come AZURE_TENANT_ID
.
az account list --query "[].{subscription_id:id, name:name, tenantId:tenantId}" -o table
Se viene visualizzato un errore relativo ai criteri di accesso condizionale del tenant, è necessario un secondo tenant senza criteri di accesso condizionale.
- Il primo tenant, associato all'account utente, viene usato per la
AZURE_TENANT_ID
variabile di ambiente. - Il secondo tenant, senza accesso condizionale, viene usato per la
AZURE_AUTH_TENANT_ID
variabile di ambiente per accedere a Microsoft Graph. Per i tenant con criteri di accesso condizionale, trovare l'ID di un secondo tenant senza criteri di accesso condizionale o creare un nuovo tenant.
Eseguire i comandi seguenti per configurare l'applicazione per il profilo 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
Eseguire il comando seguente per impostare il tenant, che autorizza l'accesso dell'utente all'ambiente dell'applicazione ospitata. Sostituire
<YOUR_TENANT_ID>
con l'ID tenant.azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
Nota
Se si dispone di un criterio di accesso condizionale nel tenant utente, è necessario specificare un tenant di autenticazione.
La distribuzione include la creazione delle risorse di Azure, il caricamento dei documenti, la creazione delle app di identità Di Microsoft Entra (client e server) e l'attivazione dell'identità per la risorsa di hosting.
Esegui il seguente comando Azure Developer CLI per effettuare il provisioning delle risorse di Azure e distribuire il codice sorgente:
azd up
Usare la tabella seguente per rispondere alle richieste di distribuzione azd:
Richiesta Risposta Nome ambiente Usare un nome breve con informazioni di identificazione, ad esempio l'alias e l'app: tjones-secure-chat
.Subscription Selezionare una sottoscrizione in cui creare le risorse. Località per le risorse di Azure Selezionare una località nelle vicinanze. Posizione per documentIntelligentResourceGroupLocation
Selezionare una località nelle vicinanze. Posizione per openAIResourceGroupLocation
Selezionare una località nelle vicinanze. Attendere 5 o 10 minuti dopo la distribuzione dell'app per consentire l'avvio dell'app.
Dopo che l'applicazione è stata distribuita correttamente, viene visualizzato un URL nel terminale.
Seleziona l'URL etichettato
(✓) Done: Deploying service webapp
per aprire l'applicazione di chat in un browser.Accettare il popup di autenticazione dell'app.
Quando viene visualizzata l'app di chat, si noti nell'angolo superiore destro che l'utente ha eseguito l'accesso.
Aprire Le impostazioni sviluppatore e notare che entrambe le opzioni sono selezionate e disattivate (disabilitate per la modifica).
- Usare il filtro di sicurezza oid
- Usare il filtro di sicurezza dei gruppi
Selezionare la scheda con
What does a product manager do?
.Si ottiene una risposta simile alla seguente:
The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.
Attivare le autorizzazioni per il documento esatto in modo da ottenere la risposta. Queste informazioni richiedono diverse informazioni:
- Archiviazione di Azure
- Nome conto
- Nome contenitore
- URL BLOB/documento per
role_library.pdf
- ID utente in Microsoft Entra ID
Dopo aver conosciuto queste informazioni, aggiornare il campo dell'indice oids
di Ricerca intelligenza artificiale di Azure per il role_library.pdf
documento.
.azure
Nella cartella nella radice del progetto individuare la directory dell'ambiente e aprire il.env
file con tale directory.Cercare la
AZURE_STORAGE_ACCOUNT
voce e copiarne il valore.Usare i comandi seguenti dell'interfaccia della riga di comando di Azure per ottenere l'URL del BLOB role_library.pdf nel contenitore del contenuto .
az storage blob url \ --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \ --container-name 'content' \ --name 'role_library.pdf'
Parametro Scopo --account-name Nome dell'account di archiviazione di Azure --container-name Il nome del contenitore in questo esempio è content
--name Il nome del BLOB in questo passaggio è role_library.pdf
Copiare l'URL del BLOB da usare in un secondo momento.
- Nell'app chap selezionare Impostazioni sviluppatore.
- Nella sezione Attestazioni token ID copiare
objectidentifier
. Questa operazione è nota nella sezione successiva comeUSER_OBJECT_ID
.
Usare lo script seguente per modificare il
oids
campo in Ricerca di intelligenza artificiale di Azure per role_library.pdf in modo da potervi accedere../scripts/manageacl.sh \ -v \ --acl-type oids \ --acl-action add \ --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \ --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
Parametro Scopo -v Output dettagliato. --acl-type ID oggetto gruppo o utente (OID): oids
--acl-action Aggiungere a un campo dell'indice di ricerca. Altre opzioni includono remove
,remove_all
,list
.--Acl Gruppo o utente USER_OBJECT_ID
--URL Percorso del file in Archiviazione di Azure, ad esempio https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf
. Non racchiudere l'URL tra virgolette nel comando dell'interfaccia della riga di comando.L'output della console per questo comando è simile al seguente:
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
Facoltativamente, usare il comando seguente per verificare che l'autorizzazione sia elencata per il file in Ricerca di intelligenza artificiale di Azure.
./scripts/manageacl.sh \ -v \ --acl-type oids \ --acl-action list \ --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \ --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
Parametro Scopo -v Output dettagliato. --acl-type Gruppo o utente (oid): oids
--acl-action Elencare un campo oids
dell'indice di ricerca . Altre opzioni includonoremove
,remove_all
,list
.--Acl Gruppo o utente USER_OBJECT_ID
--URL Percorso del file in Archiviazione di Azure, ad esempio https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf
. Non racchiudere l'URL tra virgolette nel comando dell'interfaccia della riga di comando.L'output della console per questo comando è simile al seguente:
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]
La matrice alla fine dell'output include il USER_OBJECT_ID e viene usata per determinare se il documento viene usato nella risposta con Azure OpenAI.
Aprire il portale di Azure e cercare .
AI Search
Selezionare la risorsa di ricerca dall'elenco.
Selezionare Gestione della ricerca -> Indici.
Selezionare il gptkbindex.
Selezionare Visualizza -> Visualizzazione JSON.
Sostituire json con il codice JSON seguente.
{ "search": "*", "select": "sourcefile, oids", "filter": "oids/any()" }
In questo modo vengono cercati tutti i documenti in cui il
oids
campo ha qualsiasi valore e restituisce isourcefile
campi eoids
.Se l'oggetto
role_library.pdf
non dispone dell'oid, tornare alla sezione Fornire l'accesso utente a un documento in Ricerca di Azure e completare i passaggi.
Se sono stati completati i passaggi ma non è stata visualizzata la risposta corretta, verificare che il USER_OBJECT_ID sia impostato correttamente in Ricerca di intelligenza artificiale di Azure per tale role_library.pdf
.
Tornare all'app di chat. Potrebbe essere necessario eseguire di nuovo l'accesso.
Immettere la stessa query in modo che il
role_library
contenuto venga usato nella risposta OpenAI di Azure:What does a product manager do?
.Visualizzare il risultato, che include ora la risposta appropriata dal documento della raccolta ruoli.
Le risorse di Azure create in questo articolo vengono fatturate alla sottoscrizione di Azure. Se prevedi che queste risorse non ti servano in futuro, eliminale per evitare di incorrere in costi aggiuntivi.
Esegui il seguente comando Azure Developer CLI per eliminare le risorse di Azure e rimuovere il codice sorgente:
azd down --purge
L'eliminazione dell'ambiente GitHub Codespaces offre la possibilità di aumentare le ore gratuite per core a cui si ha diritto per l'account.
Importante
Per altre informazioni sui diritti dell'account GitHub, vedere Ore di archiviazione e di core mensili incluse in GitHub Codespaces.
Accedere al dashboard di GitHub Codespaces (https://github.com/codespaces).
Individuare i codespace attualmente in esecuzione provenienti dal repository GitHub
Azure-Samples/azure-search-openai-demo
.Aprire il menu di scelta rapida per il codespace e selezionare Elimina.
Questo repository di esempio offre informazioni sulla risoluzione dei problemi.
Questa sezione offre la risoluzione dei problemi specifici di questo articolo.
Quando l'autenticazione si trova in un tenant separato dall'applicazione di hosting, è necessario impostare tale tenant di autenticazione con il processo seguente.
Eseguire il comando seguente per configurare l'esempio in modo da usare un secondo tenant per il tenant di autenticazione.
azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
Parametro Scopo AZURE_AUTH_TENANT_ID
Se AZURE_AUTH_TENANT_ID
è impostato, è il tenant che ospita l'app.Ridistribuire la soluzione con il comando seguente.
azd up
- Creare un'app di chat con OpenAI di Azure: procedura consigliata per l’architettura della soluzione
- Controllo di accesso nelle app di IA generative con Azure AI Search
- Creare una soluzione OpenAI Enterprise pronta con Gestione API di Azure
- Prestazioni della ricerca vettoriale con funzionalità di recupero e classificazione ibride