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.

Panoramica dell'architettura

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.

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

Enterprise: account obbligatorio e filtro documento

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

Uso misto: account facoltativo e filtro documento

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

Prerequisiti

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.

Codespaces (scelta consigliata)

• Account GitHub

Visual Studio Code

• Azure Developer CLI
• Docker Desktop: avviare Docker Desktop se non è già in esecuzione
• Visual Studio Code
• Estensione contenitore di sviluppo

Ambiente di sviluppo aperto

Inizia ora con un ambiente di sviluppo che ha 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, 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.

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

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

   

3. Nella pagina Crea codespace esaminare le impostazioni di configurazione del codespace e quindi selezionare Crea nuovo codespace

   

4. Attendere l'avvio del codespace. Questo processo di avvio può richiedere alcuni minuti.

5. Nel terminale nella parte inferiore della schermata, accedi ad Azure con 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.

Visual Studio Code

L'estensione Dev Containers per Visual Studio Code richiede l'installazione di Docker 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. Aprire Visual Studio Code in tale directory:

   code .
   

3. Apri una nuova finestra del 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, cercare e selezionare Contenitori di sviluppo: Apri cartella nel contenitore per aprire il progetto in un contenitore di sviluppo. Attendere l'apertura del contenitore di sviluppo prima di continuare.

6. Accedi ad Azure con Azure Developer CLI.

   azd auth login
   

   Copia il codice dal terminale e incollalo in un browser. Segui 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 informazioni necessarie con l'interfaccia della riga di comando di Azure

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.

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

Distribuire l'app di chat in Azure

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.

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

   azd up
   

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

3. Dopo che l'applicazione è stata distribuita correttamente, viene visualizzato un URL nel terminale.

4. Seleziona l'URL etichettato (✓) 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, si noti nell'angolo superiore destro che l'utente ha eseguito l'accesso.

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

8. Selezionare la scheda con What does a product manager do?.

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

   

Aprire l'accesso a un documento per un utente

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.

Ottenere l'URL per un documento nell'archiviazione

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

2. Cercare la AZURE_STORAGE_ACCOUNT voce e copiarne il valore.

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

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

Ottenere l'ID utente

1. Nell'app chap selezionare Impostazioni sviluppatore.
2. Nella sezione Attestazioni token ID copiare objectidentifier. Questa operazione è nota nella sezione successiva come USER_OBJECT_ID.

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

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

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 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 oidsdell'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.

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

Verificare che Ricerca di intelligenza artificiale di Azure contenga i USER_OBJECT_ID

1. Aprire il portale di Azure e cercare .AI Search

2. Selezionare la risorsa di ricerca dall'elenco.

3. Selezionare Gestione della ricerca -> Indici.

4. Selezionare il gptkbindex.

5. Selezionare Visualizza -> Visualizzazione JSON.

6. 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 i sourcefilecampi e oids .

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

Verificare l'accesso utente al documento

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.

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

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

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

   

Pulire le risorse

Pulire le risorse di Azure

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

Pulire GitHub Codespaces

GitHub Codespaces

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.

1. Accedere al dashboard di GitHub Codespaces (https://github.com/codespaces).

2. Individuare i codespace attualmente in esecuzione provenienti dal repository GitHub Azure-Samples/azure-search-openai-demo.

   

3. Aprire il menu di scelta rapida per il codespace e selezionare Elimina.

   

Visual Studio Code

Non si è tenuti necessariamente a pulire l'ambiente locale, ma è possibile arrestare il contenitore di sviluppo in esecuzione e tornare a eseguire Visual Studio Code nel contesto di un'area di lavoro locale.

1. Aprire il riquadro comandi, cercare i comandi Dev Containers e quindi selezionare Dev Containers: Reopen Folder Locally.

   

Suggerimento

Il contenitore di sviluppo in esecuzione verrà arrestato da Visual Studio Code, ma continuerà a esistere 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.

Come 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
   

Passaggi successivi

• 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