Introduzione alla sicurezza dei documenti di chat per Python

Quando costruisci un'applicazione di chat usando il modello RAG (Retrieval Augmented Generation) con i tuoi dati, assicurati che ogni utente riceva una risposta in base alle autorizzazioni dell'utente. Seguire la procedura descritta in questo articolo per aggiungere il controllo di accesso ai documenti all'app di chat.

• utente autorizzato: questa persona deve avere accesso alle risposte contenute nei documenti dell'app di chat.

  

• utente non autorizzato: questa persona non dovrebbe avere accesso alle risposte da documenti protetti che non è autorizzata a vedere.

  

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 che sono facili da distribuire. Consentono di garantire un punto di partenza di alta qualità per le app di intelligenza artificiale.

Panoramica dell'architettura

Senza una 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 alla Ricerca di intelligenza artificiale di Azure, dove i documenti sono archiviati, 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:

• Aggiungi l'autenticazione client all'app di chat con Microsoft Entra.
• Aggiungere la logica lato server per popolare un indice di ricerca con accesso di utenti e gruppi.

Ricerca AI di Azure non fornisce autorizzazioni native a livello di documenti e non può variare i risultati della ricerca all'interno di un indice in base alle autorizzazioni degli utenti. 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 e 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.
• Compilare il campo di controllo di accesso del documento con i dettagli pertinenti dell'utente o del gruppo.
• 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 rilevate durante l'esecuzione successiva. Se non si usa un indicizzatore, è necessario reindicizzare manualmente.

In questo articolo, il processo di protezione dei documenti in Azure AI Search è reso possibile con gli script di esempio e, che verranno eseguiti dall'amministratore della ricerca. Gli script associano un singolo documento a una singola identità utente. È possibile eseguire questi script e applicare requisiti di sicurezza e produzione personalizzati per adattarli alle proprie esigenze.

Determinare la configurazione della sicurezza

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 all'autenticazione del servizio app di Azure. Abilita il Use oid security filter nelle impostazioni sviluppatore per l'app di chat.
AZURE_ENFORCE_ACCESS_CONTROL	Se impostato su true, richiede l'autenticazione per qualsiasi accesso ai documenti. Le impostazioni di Sviluppatore per l'ID oggetto (OID) e la sicurezza dei gruppi vengono 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 impostato 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.

Enterprise: account obbligatorio e filtro documento

Ogni utente del sito deve accedere. 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

Uso misto: account facoltativo e filtro per documento

Ogni utente del sito può accedere. 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

Prerequisiti

È disponibile un ambiente contenitore di sviluppo con tutte le dipendenze necessarie per completare questo articolo. È possibile 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:

• Una sottoscrizione di Azure. Crearne uno gratuitamente.
• Autorizzazioni dell'account Azure: l'account Azure deve avere:
  • Autorizzazione per gestire le applicazioni in Microsoft Entra ID.
  • Microsoft.Authorization/roleAssignments/write autorizzazioni, ad esempio amministratore accesso utenti o proprietario .

Sono necessari altri prerequisiti a seconda dell'ambiente di sviluppo preferito.

gitHub Codespaces (scelta consigliata)

• account GitHub

• Azure Developer CLI.
• Docker Desktop. Avviare Docker Desktop se non è già in esecuzione.
• Visual Studio Code.
• estensione Dev Containers.

Aprire un ambiente di sviluppo

Iniziare ora con un ambiente di sviluppo con tutte le dipendenze installate per completare questo articolo.

gitHub Codespaces (scelta consigliata)

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, usare GitHub Codespaces per avere gli strumenti di sviluppo e le dipendenze corretti preinstallati per completare questo articolo.

Importante

Tutti gli account GitHub possono usare GitHub Codespaces per un massimo di 60 ore gratuite ogni mese con due istanze principali. Per ulteriori informazioni, vedere GitHub Codespaces archiviazione mensile inclusa e ore di base.

1. Avviare il processo per creare un nuovo spazio di codice GitHub nel ramo main del repository GitHub Azure-Samples/azure-search-openai-demo GitHub.

2. Clicca con il tasto destro del mouse sul pulsante qui sotto e seleziona Apri il link in nuove finestre per avere l'ambiente di sviluppo e la documentazione disponibili contemporaneamente.

   

3. Nella pagina Crea spazio di codice esaminare le impostazioni di configurazione dello spazio di codice e quindi selezionare Crea nuovo spazio di codice.

   

4. Attendere l'avvio dello spazio di codice. Questo processo di avvio può richiedere alcuni minuti.

5. Nel terminale nella parte inferiore della schermata, accedi ad Azure con l'Azure Developer CLI.

   azd auth login
   

6. Completare il processo di autenticazione.

7. Le attività rimanenti in questo articolo vengono eseguite nel contesto di questo contenitore di sviluppo.

L'estensione Dev Containers per Visual Studio Code richiede Docker da installare nel computer locale. L'estensione ospita il contenitore di sviluppo in locale usando l'host Docker con gli strumenti di sviluppo e le dipendenze corretti preinstallati per completare questo articolo.

1. Creare una nuova directory locale nel computer per il progetto.

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

2. Apri Visual Studio Code in quella directory.

   code .
   

3. Aprire un nuovo terminale in Visual Studio Code.

4. Eseguire il comando AZD seguente per portare il repository GitHub nel computer locale.

   azd init -t azure-search-openai-demo
   

5. Aprire il riquadro comandi e cercare e selezionare Dev Containers: Apri cartella nel contenitore per aprire il progetto in un contenitore di sviluppo. Attendere l'apertura del contenitore di sviluppo prima di continuare.

6. Accedere ad Azure con l'interfaccia della riga di comando per sviluppatori di Azure.

   azd auth login
   

   Copiare il codice dal terminale e incollarlo in un browser. Seguire le istruzioni per eseguire l'autenticazione con l'account Azure.

7. Gli esercizi rimanenti in questo progetto si svolgono nel contesto di questo contenitore di sviluppo.

Ottenere le informazioni necessarie con l'interfaccia della riga di comando di Azure

Ottenere l'ID sottoscrizione e l'ID tenant tramite il seguente comando dell'interfaccia della riga di comando di Azure. Copiare il valore da usare come valore 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 variabile di ambiente AZURE_TENANT_ID.
• Il tuo secondo tenant, senza accesso condizionale, viene utilizzato per la variabile d'ambiente AZURE_AUTH_TENANT_ID 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.

Impostare le variabili di ambiente

1. 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
   

2. 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 del tenant.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Nota

Se disponi di regole di accesso condizionale sul tuo tenant utente, devi specificare un tenant di autenticazione.

Distribuire l'app di chat in Azure

La distribuzione è costituita dai passaggi seguenti:

• Creare le risorse di Azure.
• Caricare i documenti.
• Creare le app Microsoft Entra Identity (client e server).
• Attivare l'identità per la risorsa di hosting.

1. Esegui il seguente comando Azure Developer CLI per eseguire il provisioning delle risorse di Azure e distribuire il codice sorgente.

   azd up
   

2. Utilizzare la tabella seguente per rispondere alle istruzioni di distribuzione AZD.

   Immediato	Risposta
   Il nome dell'ambiente	Usare un nome breve con informazioni di identificazione, ad esempio l'alias e l'app. Ad esempio, tjones-secure-chat.
   Abbonamento	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.

3. Dopo la distribuzione dell'applicazione, viene visualizzato un URL nel terminale.

4. Selezionare l'URL con etichetta (✓) Done: Deploying service webapp per aprire l'applicazione di chat in un browser.

   

5. Accettare il popup di autenticazione dell'app.

6. Quando viene visualizzata l'app di chat, nota che nell'angolo superiore destro il tuo utente ha eseguito l'accesso.

7. Aprire Impostazioni sviluppatore e notare che entrambe le opzioni seguenti sono selezionate e non possono essere modificate:

   • Usare il filtro di sicurezza OID
   • Usare i filtri di sicurezza dei gruppi

8. Seleziona la scheda con Cosa fa un product manager?.

9. Si ottiene una risposta simile a: Le fonti fornite non contengono informazioni specifiche sul ruolo di un Product Manager presso Contoso Electronics.

   

Aprire l'accesso a un documento per un utente

Attivare le autorizzazioni per il documento esatto in modo da possibile ottenere la risposta. Sono necessarie diverse informazioni:

• Archiviazione di Azure
  • Nome dell'account
  • Nome contenitore
  • URL BLOB/documento per role_library.pdf
• ID dell'utente in Microsoft Entra ID

Quando queste informazioni sono note, aggiornare il campo dell'indice di Azure AI Search oids per il documento role_library.pdf.

Ottenere l'URL di un documento nell'archivio

1. Nella cartella .azure alla radice del progetto individuare la directory dell'ambiente e aprire il file .env con tale directory.

2. Cerca la voce AZURE_STORAGE_ACCOUNT e copia il suo valore.

3. Usare i comandi seguenti della CLI di Azure per ottenere l'URL del BLOB role_library.pdf nel contenitore content.

   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.
   --nome	Il nome del blob in questo passaggio è role_library.pdf.

4. Copiare l'URL del BLOB da usare in un secondo momento.

Ottenere l'ID utente

1. Nell'app di chat selezionare Impostazioni sviluppatore.
2. Nella sezione attestazioni token ID id copiare il parametro . Questo parametro è noto nella sezione successiva come USER_OBJECT_ID.

Fornire all'utente l'accesso a un documento in Ricerca di Azure

1. Usare il seguente script per modificare il campo oids in Azure AI Search per role_library.pdf, in modo da avere accesso ad esso.

   ./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 gruppo o utente (OID): oids.
   --acl-action	Aggiungere a un campo indice di ricerca. Altre opzioni includono remove, remove_alle list.
   --Acl	Gruppo o utente USER_OBJECT_ID.
   --URL	La posizione 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 CLI.

2. 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
   

3. Facoltativamente, usare il comando seguente per verificare che le tue autorizzazioni siano elencate per il file nella 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	ID gruppo o utente: oids.
   --acl-action	Elencare un campo dell'indice di ricerca oids. Altre opzioni includono remove, remove_alle list.
   --Acl	Parametro di USER_OBJECT_ID del gruppo o dell'utente.
   --URL	La posizione del file che viene mostrata, ad esempio https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Non racchiudere l'URL tra virgolette nel comando CLI.

4. 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 parametro USER_OBJECT_ID e viene usato per determinare se il documento viene usato nella risposta con Azure OpenAI.

Verificare che Azure AI Search contenga il vostro USER_OBJECT_ID

1. Apri il portale Azure e cerca AI Search.

2. Selezionare la risorsa di ricerca dall'elenco.

3. Selezionare Gestione ricerca>Indici.

4. Selezionare gptkbindex.

5. Selezionare Visualizza>visualizzazione JSON.

6. Sostituire il JSON con il seguente JSON.

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

   Questo codice JSON cerca tutti i documenti in cui il campo oids ha qualsiasi valore e restituisce i campi sourcefile e oids.

7. Se l'role_library.pdf non ha il tuo OID, tornare alla sezione Fornire accesso utente a un documento in Azure Search e completare i passaggi.

Verificare l'accesso utente al documento

Se sono stati completati i passaggi ma non è stata visualizzata la risposta corretta, verificare che il parametro USER_OBJECT_ID sia impostato correttamente in Ricerca di intelligenza artificiale di Azure per role_library.pdf.

1. Tornare all'app di chat. Potrebbe essere necessario eseguire di nuovo l'accesso.

2. Immettere la stessa query affinché il contenuto role_library venga usato nella risposta di Azure OpenAI: What does a product manager do?.

3. Visualizzare il risultato, che include ora la risposta appropriata dal documento della libreria dei ruoli.

   

Pulire le risorse

I passaggi seguenti illustrano il processo di pulizia delle risorse usate.

Pulire le risorse di Azure

Le risorse di Azure create in questo articolo vengono addebitate al tuo abbonamento Azure. Se non si prevede che queste risorse siano necessarie in futuro, eliminarle per evitare di incorrere in costi aggiuntivi.

Eseguire il comando seguente dell'interfaccia della riga di comando per sviluppatori di Azure per eliminare le risorse di Azure e rimuovere il codice sorgente.

azd down --purge

Pulire GitHub Codespaces e Visual Studio Code

I passaggi seguenti illustrano il processo di pulizia delle risorse usate.

GitHub Codespaces

L'eliminazione dell'ambiente GitHub Codespaces garantisce che sia possibile massimizzare l'ammontare delle ore gratuite per core assegnato al tuo account.

Importante

Per altre informazioni sui diritti dell'account GitHub, vedere: Spazio di archiviazione e ore di calcolo mensilmente inclusi nei GitHub Codespaces.

1. Accedi al dashboard GitHub Codespaces.

2. Individuare gli spazi di codice attualmente in esecuzione originati dal repository GitHub Azure-Samples/azure-search-openai- demo.

   

3. Apri il menu di scelta rapida per il codespace e quindi seleziona Elimina.

   

Non è necessario eseguire necessariamente la pulizia dell'ambiente locale, ma è possibile arrestare il contenitore di sviluppo in esecuzione e tornare all'esecuzione di Visual Studio Code nel contesto di un'area di lavoro locale.

1. Aprire la palette dei comandi e cercare i comandi contenitori di sviluppo .

2. Selezionare Dev Containers: Apri nuovamente la cartella in locale.

   

Suggerimento (only if the intended meaning is a non-financial tip/suggestion).

Visual Studio Code arresta il contenitore di sviluppo in esecuzione, ma il contenitore esiste ancora in Docker in uno stato arrestato. È sempre possibile eliminare l'istanza del contenitore, l'immagine del contenitore e i volumi da Docker per liberare più spazio nel computer locale.

Ottenere assistenza

Questo repository di esempio offre informazioni sulla risoluzione dei problemi.

Risoluzione dei problemi

Questa sezione offre la risoluzione dei problemi specifici di questo articolo.

Specificare il tenant di autenticazione

Quando l'autenticazione si trova in un tenant separato dall'applicazione di hosting, è necessario impostare tale tenant di autenticazione con il processo seguente.

1. 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.

2. Ridistribuire la soluzione con il comando seguente:

   azd up
   

Contenuto correlato

• Creare un'app di chat con Azure OpenAI'architettura delle soluzioni consigliate.
• Informazioni sul controllo di accesso nelle app di intelligenza artificiale generativa con Azure AI Search.
• Creare una soluzione Azure OpenAI pronta per l'azienda con la Gestione API di Azure.
• Vedere Ricerca di intelligenza artificiale di Azure: ricerca di vettori con prestazioni superiori con funzionalità di recupero e classificazione ibride.