Usare l'app Web OpenAI di Azure

Insieme a Studio AI della piattaforma Azure, Azure OpenAI Studio, API e SDK, è possibile usare l'app Web personalizzabile disponibile per interagire con i modelli del Servizio OpenAI di Azure usando un'interfaccia utente grafica. Le funzionalità principali includono:

• Connettività con più origini dati per supportare la generazione avanzata di query e recupero, tra cui Azure AI Search, Prompt flow e altro ancora.
• Cronologia conversazioni e raccolta di commenti e suggerimenti degli utenti tramite Cosmos DB.
• Autenticazione con il controllo degli accessi in base al ruolo tramite Microsoft Entra ID.
• Personalizzazione dell'interfaccia utente, delle origini dati e delle funzionalità usando le variabili di ambiente (senza codice, tramite il portale di Azure).
• Supporto per la modifica del codice sorgente dell'applicazione Web sottostante come repository open source.

È possibile distribuire l'app usando Studio AI della piattaforma Azure o Azure OpenAI Studio, oppure tramite una distribuzione manuale tramite il portale di Azure o Azure Developer CLI tramite il computer locale (istruzioni disponibili qui nel repository). A seconda del canale di distribuzione, è possibile precaricare un'origine dati con cui chattare tramite l'applicazione Web, ma questa operazione può essere modificata dopo la distribuzione.

Per i principianti di Azure OpenAI che desiderano chattare con i propri dati tramite l'applicazione Web, Studio AI della piattaforma Azure è il supporto consigliato per la distribuzione iniziale e la configurazione dell'origine dati.

Considerazioni importanti

• Questa applicazione Web e molte delle sue funzionalità sono in anteprima, il che significa che potrebbero verificarsi bug e che non tutte le funzionalità potrebbero essere complete. Se si trova un bug o si richiede assistenza, generare un problema nel repository GitHub associato.
• La pubblicazione di una app Web crea un'istanza del Servizio app di Azure nella sottoscrizione. Potrebbe comportare costi, a seconda del piano prezzi selezionato. Una volta finito di lavorare all'app, è possibile eliminarla, insieme a tutte le risorse associate dal portale di Azure.
• I modelli di GPT-4 Turbo with Vision non sono supportati al momento.
• Per impostazione predefinita, l'app viene distribuita con il provider di identità Microsoft già configurato. Il provider di identità limita l'accesso all'app ai membri del tenant di Azure. Per aggiungere o modificare l'autenticazione:

  1. Passare al portale di Azure e cercare il nome dell'app specificato durante la pubblicazione. Selezionare l'app Web e quindi selezionare Autenticazione nel menu a sinistra. Selezionare quindi Aggiungi provider di identità.

     

  2. Selezionare Microsoft come provider di identità. Le impostazioni predefinite in questa pagina limitano l'app solo al tenant, quindi qui non è necessario modificare altri elementi. Selezionare Aggiungi.

A questo punto agli utenti sarà chiesto di accedere con il proprio account Microsoft Entra per accedere all'app. Se si preferisce, è possibile seguire un processo simile per aggiungere un altro provider di identità. L'app usa le informazioni di accesso dell'utente unicamente per verificare che l'utente sia membro del tenant. Per altre informazioni sulla gestione dell'autenticazione, vedere questa guida introduttiva sull'autenticazione per le app Web nel Servizio app di Azure.

Personalizzazione dell'applicazione tramite variabili di ambiente

La logica front-end e back-end dell'app sono personalizzabili. L'app fornisce diverse variabili di ambiente per scenari di personalizzazione comuni, ad esempio la modifica dell'icona nell'app.

Queste variabili di ambiente possono essere modificate tramite il portale di Azure dopo la distribuzione dell'applicazione Web.

1. Nel portale di Azure, cercare e selezionare la pagina Servizi app.
2. Selezionare l'app Web appena distribuita.
3. Nel menu a sinistra dell'app, selezionare Impostazioni > Variabili di ambiente.
4. Per modificare una variabile di ambiente esistente, fare clic sul relativo nome.
5. Per aggiungere una singola variabile di ambiente, fare clic su Aggiungi nella barra dei menu nella parte superiore del pannello.
6. Per usare l'editor basato su JSON per gestire le variabili di ambiente, fare clic su Modifica avanzata.

Quando si personalizza l'app, è consigliabile:

• Comunicare chiaramente che qualsiasi impostazione implementata influisce sull'esperienza utente.

• Aggiornare le impostazioni dell'app per ognuna delle app distribuite per l'uso di nuove chiavi API dopo aver ruotato le chiavi per la risorsa di Azure OpenAI o Azure AI Search.

Il codice sorgente di esempio per l'app Web è disponibile in GitHub. Il codice sorgente è fornito "così come è" e vale solo come esempio. I clienti sono responsabili di tutte le personalizzazioni e dell'implementazione delle app Web.

Modifica dell'interfaccia utente dell'applicazione

Le variabili di ambiente rilevanti per la personalizzazione dell'interfaccia utente sono:

• UI_CHAT_DESCRIPTION: questo è il paragrafo di testo più piccolo mostrato sotto UI_CHAT_TITLE al centro della pagina al caricamento.
  • Tipo di dati: testo
• UI_CHAT_LOGO: immagine di grandi dimensioni visualizzata al centro della pagina al caricamento.
  • Tipo di dati: URL per l'immagine
• UI_CHAT_TITLE: testo di grandi dimensioni visualizzato al centro della pagina al caricamento.
  • Tipo di dati: testo
• UI_FAVICON: questo è il favicon visualizzato nella finestra/scheda del browser.
  • Tipo di dati: URL per l'immagine
• UI_LOGO: questo è il logo visualizzato in alto a sinistra nella pagina e a sinistra del titolo.
  • Tipo di dati: URL per l'immagine
• UI_TITLE: questo è il titolo visualizzato nella finestra/scheda del browser. Viene visualizzato anche nella parte superiore sinistra della pagina dal logo.
  • Tipo di dati: testo
• UI_SHOW_SHARE_BUTTON: questo pulsante viene visualizzato in alto a destra della pagina e consente agli utenti di condividere un URL collegato all'app Web.
  • Tipo di dati: valore booleano, bisogna immettere True o False. L'impostazione predefinita è True se viene lasciato vuoto o non specificato.
• UI_SHOW_CHAT_HISTORY_BUTTON: viene visualizzato in alto a destra nella pagina e a sinistra di UI_SHOW_SHARE_BUTTON.
  • Tipo di dati: valore booleano, bisogna immettere True o False. L'impostazione predefinita è True se viene lasciato vuoto o non specificato.

Per modificare l'interfaccia utente dell'applicazione, seguire le istruzioni del passaggio precedente per aprire la pagina delle variabili di ambiente per l'app Web. Usare quindi Modifica avanzata per aprire l'editor basato su JSON. Nella parte superiore del codice JSON (dopo il carattere [), incollare il blocco di codice seguente e personalizzare i valori di conseguenza:

  {
    "name": "UI_CHAT_DESCRIPTION",
    "value": "This is an example of a UI Chat Description. Chatbots can make mistakes. Check important info and sensitive info.",
    "slotSetting": false
  },
  {
    "name": "UI_CHAT_LOGO",
    "value": "https://learn-bot.azurewebsites.net/assets/Contoso-ff70ad88.svg",
    "slotSetting": false
  },
  {
    "name": "UI_CHAT_TITLE",
    "value": "This is an example of a UI Chat Title. Start chatting",
    "slotSetting": false
  },
  {
    "name": "UI_FAVICON",
    "value": "https://learn-bot.azurewebsites.net/assets/Contoso-ff70ad88.svg",
    "slotSetting": false
  },
  {
    "name": "UI_LOGO",
    "value": "https://learn-bot.azurewebsites.net/assets/Contoso-ff70ad88.svg",
    "slotSetting": false
  },
  {
    "name": "UI_TITLE",
    "value": "This is an example of a UI Title",
    "slotSetting": false
  },

Abilitazione della cronologia delle chat con Cosmos DB

È possibile attivare la cronologia delle chat per gli utenti dell'app Web. Quando si attiva la funzionalità, gli utenti hanno accesso alle singole query e risposte precedenti.

Per attivare la cronologia delle chat, distribuire o ridistribuire il modello come app Web usando Azure OpenAI Studio o Studio AI della piattaforma Azure e selezionare Abilita cronologia chat e commenti degli utenti nell'app Web.

Importante

L'attivazione della cronologia delle chat crea un'istanza di Azure Cosmos DB nel gruppo di risorse e comporta costi aggiuntivi per l'archiviazione usata oltre i livelli gratuiti.

Dopo aver attivato la cronologia delle chat, gli utenti possono visualizzarla e nasconderla nell'angolo superiore destro dell'app. Quando gli utenti mostrano la cronologia delle chat, possono rinominare o eliminare conversazioni. È possibile modificare se gli utenti possono accedere a questa funzione usando la variabile di ambiente UI_SHOW_CHAT_HISTORY_BUTTON, come specificato nella sezione precedente. Poiché gli utenti hanno eseguito l'accesso all'app, le conversazioni vengono ordinate automaticamente dalla più recente alla meno recente. Le conversazioni vengono denominate in base alla prima domanda nella conversazione.

Nota

Le aree dove Azure è più diffuso, come gli Stati Uniti orientali, possono riscontrare periodi di domanda elevata in cui potrebbe non essere possibile distribuire una nuova istanza di Cosmos DB. In tal caso, scegliere di eseguire la distribuzione in un'area alternativa, ad esempio Stati Uniti orientali 2 o ripetere la distribuzione fino a quando non riesce. Se la distribuzione di Cosmos DB ha esito negativo, l'app sarà disponibile all'URL specificato, ma la cronologia delle chat non sarà disponibile. L'abilitazione della cronologia delle conversazioni abiliterà anche il pulsante Visualizza cronologia conversazioni, in alto a destra.

La distribuzione con l'opzione cronologia chat selezionata popola automaticamente le variabili di ambiente seguenti, quindi non è necessario modificarle a meno che non si desideri cambiare le istanze di Cosmos DB. Sono:

• AZURE_COSMOSDB_ACCOUNT: nome dell'account Cosmos DB distribuito insieme all'app Web.
  • Tipo di dati: testo
• AZURE_COSMOSDB_ACCOUNT_KEY: si tratta di una variabile di ambiente alternativa usata solo quando le autorizzazioni non vengono concesse tramite Microsoft Entra ID e viene invece usata l'autenticazione basata su chiave.
  • Tipo di dati: testo. In genere non è presente o popolato.
• AZURE_COSMOSDB_DATABASE: nome dell'oggetto di database all'interno di Cosmos DB distribuito insieme all'app Web.
  • Tipo di dati: testo, deve essere db_conversation_history
• AZURE_COSMOSDB_CONTAINER: nome dell'oggetto contenitore di database all'interno di Cosmos DB distribuito insieme all'app Web.
  • Tipo di dati: testo, deve essere conversations
• AZURE_COSMOSDB_ACCOUNT: nome dell'account Cosmos DB distribuito insieme all'app Web.
  • Tipo di dati: testo

Raccolta di commenti e suggerimenti degli utenti

Per raccogliere commenti e suggerimenti degli utenti, è possibile abilitare un set di icone "pollice su" e "pollice giù" visualizzate in ognuna delle risposte del chatbot. In questo modo gli utenti potranno valutare la qualità di una risposta e indicare dove si verificano errori usando una finestra modale "fornisci feedback negativo".

Per abilitare questa funzionalità, impostare la variabile di ambiente seguente su True:

• AZURE_COSMOSDB_ENABLE_FEEDBACK: nome dell'account Cosmos DB distribuito insieme all'app Web.
  • Tipo di dati: Tipo di dati: booleano, bisogna immettere True o False

Questa operazione può essere eseguita usando le opzioni Modifica avanzata o Modifica semplice, come illustrato in precedenza. Il codice JSON da incollare nell'editor JSON di modifica avanzata è:

  {
    "name": "AZURE_COSMOSDB_ENABLE_FEEDBACK",
    "value": "True",
    "slotSetting": false
  },

Connessione ad Azure AI Search e file caricati come origine dati

Uso di Studio AI della piattaforma Azure

Seguire questa esercitazione sull'integrazione di Azure AI Search di Azure con Studio AI e ridistribuire l'applicazione.

Usando Azure OpenAI Studio

Seguire questa esercitazione sull'integrazione di Azure AI Search di Azure con OpenAI Studio e sulla ridistribuzione dell'applicazione.

Uso delle variabili di ambiente

Per connettersi ad Azure AI Search senza ridistribuire l'app, è possibile modificare le variabili di ambiente obbligatorie seguenti usando una delle opzioni di modifica descritte in precedenza.

• DATASOURCE_TYPE: determina l'origine dati da usare per rispondere alle query di un utente.
  • Tipo di dati: testo. Deve essere impostato su AzureCognitiveSearch (nome precedente per Azure AI Search)
• AZURE_SEARCH_SERVICE: nome dell'istanza di Azure AI Search.
  • Tipo di dati: testo
• AZURE_SEARCH_INDEX: nome dell'indice dell'istanza di Azure AI Search.
  • Tipo di dati: testo
• AZURE_SEARCH_KEY: questa è la chiave di autenticazione dell'istanza di Azure AI Search. Facoltativo se si usa Microsoft Entra ID per l'autenticazione.
  • Tipo di dati: testo

Altri scenari di personalizzazione che usano le variabili di ambiente

• AZURE_SEARCH_USE_SEMANTIC_SEARCH: indica se usare la ricerca semantica in Azure AI Search.
  • Tipo di dati: booleano, deve essere impostato su False se non si usa la ricerca semantica.
• AZURE_SEARCH_SEMANTIC_SEARCH_CONFIG: specifica il nome della configurazione della ricerca semantica da usare se la ricerca semantica è abilitata.
  • Tipo di dati: testo, per impostazione predefinita è azureml-default.
• AZURE_SEARCH_INDEX_TOP_K: definisce il numero di documenti principali da recuperare da Azure AI Search.
  • Tipo di dati: integer, deve essere impostato su 5.
• AZURE_SEARCH_ENABLE_IN_DOMAIN: limita le risposte alle query correlate solo ai dati.
  • Tipo di dati: booleano, deve essere impostato su True.
• AZURE_SEARCH_CONTENT_COLUMNS: specifica l'elenco dei campi nell'indice di Azure AI Search che contiene il contenuto di testo dei documenti, usato per simulare una risposta del bot.
  • Tipo di dati: testo, valore predefinito content se distribuito da Studio AI della piattaforma Azure o da Azure OpenAI Studio,
• AZURE_SEARCH_FILENAME_COLUMN: specifica il campo dell'indice di Azure AI Search che fornisce un identificatore univoco dei dati di origine da visualizzare nell'interfaccia utente.
  • Tipo di dati: testo, valore predefinito filepath se distribuito da Studio AI della piattaforma Azure o da Azure OpenAI Studio,
• AZURE_SEARCH_TITLE_COLUMN: specifica il campo dell'indice di Azure AI Search che fornisce un titolo o un'intestazione pertinenti per il contenuto dei dati da visualizzare nell'interfaccia utente.
  • Tipo di dati: testo, valore predefinito title se distribuito da Studio AI della piattaforma Azure o da Azure OpenAI Studio,
• AZURE_SEARCH_URL_COLUMN: specifica il campo dell'indice di Azure AI Search che contiene un URL per il documento.
  • Tipo di dati: testo, valore predefinito url se distribuito da Studio AI della piattaforma Azure o da Azure OpenAI Studio,
• AZURE_SEARCH_VECTOR_COLUMNS: specifica l'elenco di campi nell'indice di Azure AI Search che contengono incorporamenti vettoriali dei documenti, usati per simulare una risposta del bot.
  • Tipo di dati: testo, valore predefinito contentVector se distribuito da Studio AI della piattaforma Azure o da Azure OpenAI Studio,
• AZURE_SEARCH_QUERY_TYPE: specifica il tipo di query da usare: simple, semantic, vector, vectorSimpleHybrido vectorSemanticHybrid. Questa impostazione ha la precedenza su AZURE_SEARCH_USE_SEMANTIC_SEARCH.
  • Tipo di dati: testo, è consigliabile eseguire il test con vectorSemanticHybrid.
• AZURE_SEARCH_PERMITTED_GROUPS_COLUMN: specifica il campo dell'indice di Azure AI Search che contiene gli ID di gruppo di Microsoft Entra, determinando il controllo di accesso a livello di documento.
  • Tipo di dati: testo
• AZURE_SEARCH_STRICTNESS: specifica il livello di severità per il modello che limita le risposte ai dati.
  • Tipo di dati: integer, deve essere impostato tra 1 e 5, con 3 consigliato.
• AZURE_OPENAI_EMBEDDING_NAME: specifica il nome della distribuzione del modello di incorporamento se si usa la ricerca vettoriale.
  • Tipo di dati: testo

Il codice JSON da incollare nell'editor JSON di modifica avanzata è:

{
    "name": "AZURE_SEARCH_CONTENT_COLUMNS",
    "value": "",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_ENABLE_IN_DOMAIN",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_FILENAME_COLUMN",
    "value": "",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_INDEX",
    "value": "",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_KEY",
    "value": "",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_PERMITTED_GROUPS_COLUMN",
    "value": "",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_QUERY_TYPE",
    "value": "vectorSemanticHybrid",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_SEMANTIC_SEARCH_CONFIG",
    "value": "azureml-default",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_SERVICE",
    "value": "",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_STRICTNESS",
    "value": "3",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_TITLE_COLUMN",
    "value": "",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_TOP_K",
    "value": "5",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_URL_COLUMN",
    "value": "",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_USE_SEMANTIC_SEARCH",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "AZURE_SEARCH_VECTOR_COLUMNS",
    "value": "contentVector",
    "slotSetting": false
  },

Connessione a Prompt flow come origine dati

Prompt flow consente di definire logica di elaborazione e RAG altamente personalizzabile nelle query di un utente.

Creazione e distribuzione di Prompt flow in Studio AI della piattaforma Azure

Seguire questa esercitazione per creare, testare e distribuire un endpoint di inferenza per Prompt flow in Studio AI della piattaforma Azure.

Abilitare le citazioni sottostanti da prompt flow

Quando si configura Prompt flow per visualizzare le citazioni quando vengono integrate con questa applicazione Web, deve restituire due output chiave: uno chiamato documents (le citazioni) e uno chiamato reply (risposta in linguaggio naturale).

1. documents è un oggetto JSON che deve contenere gli elementi seguenti. citations è un elenco che può contenere più elementi che seguono lo stesso schema. l'oggetto documents deve essere generato e popolato in base al modello RAG selezionato.

{
    "citations": [
        {
                "content": "string",
                "id": 12345,
                "title": "string",
                "filepath": "string",
                "url": "string",
                "metadata": "string",
                "chunk_id": None,
                "reindex_id": None,
                "part_index": None
        }
    ],
    "intent": "Your_string_here"
}

2. reply è costituito da una stringa restituita che rappresenta il linguaggio naturale finale in risposta a una determinata query utente. reply deve contenere riferimenti a ognuno dei documenti (origini) nel formato seguente: [doc1], [doc2], e così via. L'applicazione Web analizzerà reply ed elaborerà i riferimenti, sostituendo tutte le istanze di [doc1] con indicatori numerici di apice piccoli che si collegano direttamente ai documents ordinati restituiti. Di conseguenza, è necessario richiedere all'LLM che genera il linguaggio naturale finale di includere questi riferimenti, che devono essere passati anche nella chiamata LLM, per assicurarsi che siano allineati correttamente. Ad esempio:

system:
You are a helpful chat assistant that answers a user's question based on the information retrieved from a data source. 

YOU MUST ALWAYS USE CITATIONS FOR ALL FACTUAL RESPONSES. YOU MUST INCLUDE CITATIONS IN YOUR ANSWER IN THE FORMAT [doc1], [doc2], ... AND SO FORTH WHEN YOU ARE USING INFORMATION RELATING TO SAID SOURCE. THIS MUST BE RETURNED IN YOUR ANSWER.

Provide sort and concise answers with details directly related to the query. 

## Conversation history for context
{% for item in chat_history %}
user:
{{item.inputs.query}}

assistant:
{{item.outputs.reply}}
{% endfor %}

## Current question
user:
### HERE ARE SOME CITED SOURCE INFORMATION FROM A MOCKED API TO ASSIST WITH ANSWERING THE QUESTION BELOW. ANSWER ONLY BASED ON THE TRUTHS PRESENTED HERE.
{{your_input_name_for_documents}}
FOR EACH OF THE CITATIONS ABOVE, YOU MUST INCLUDE IN YOUR ANSWER [doc1], [doc2], ... AND SO FORTH WHEN YOU ARE USING INFORMATION RELATING TO SAID SOURCE. THIS MUST BE RETURNED IN YOUR ANSWER.
### HERE IS THE QUESTION TO ANSWER.
{{question}}
  

Configurazione delle variabili di ambiente per integrare prompt flow

Le variabili di ambiente da modificare sono:

• AZURE_OPENAI_STREAM: determina se la risposta viene caricata in un formato di streaming (caricamento incrementale). Questo non è supportato per prompt flow e pertanto deve essere impostato su False per usare questa funzionalità.
  • Tipo di dati: booleano, impostato su True se non si usa prompt flow, False se si usa
• USE_PROMPTFLOW: indica se usare un endpoint distribuito del Prompt flow esistente. Se è impostato su True, sia PROMPTFLOW_ENDPOINT che PROMPTFLOW_API_KEY devono essere impostati.
  • Tipo di dati: booleano, deve essere impostato su False se non si usa il Prompt flow.
• PROMPTFLOW_ENDPOINT: specifica l'URL dell'endpoint del Prompt flow distribuito.
  • Tipo di dati: testo, ad esempio https://pf-deployment-name.region.inference.ml.azure.com/score
• PROMPTFLOW_API_KEY: chiave di autenticazione per l'endpoint del Prompt flow distribuito. Nota: è supportata solo l'autenticazione basata su chiave.
  • Tipo di dati: testo
• PROMPTFLOW_RESPONSE_TIMEOUT: definisce il valore di timeout in secondi affinché l'endpoint del Prompt flow risponda.
  • Tipo di dati: integer, deve essere impostato su 120.
• PROMPTFLOW_REQUEST_FIELD_NAME: nome del campo predefinito per costruire la richiesta di Prompt flow. Nota: chat_history viene costruito automaticamente in base all'interazione. Se l'API prevede altri campi obbligatori, sarà necessario modificare i parametri della richiesta nella funzione promptflow_request.
  • Tipo di dati: testo, deve essere impostato su query.
• PROMPTFLOW_RESPONSE_FIELD_NAME: nome del campo predefinito per elaborare la risposta dalla richiesta di Prompt flow.
  • Tipo di dati: testo, deve essere impostato su reply.
• PROMPTFLOW_CITATIONS_FIELD_NAME: nome del campo predefinito per elaborare l'output delle citazioni dalla richiesta di Prompt flow.
  • Tipo di dati: testo, deve essere impostato su documents.

Connessione ad altre origini dati

Sono supportate altre origini dati, tra cui:

• Azure Cosmos DB
• Elasticsearch
• Azure SQL Server
• Pinecone
• Indice Azure Machine Learning

Per altre istruzioni sull'abilitazione di queste origini dati, vedere il repository GitHub.

Aggiornamento dell'app Web per includere le modifiche più recenti

Nota

A partire dal 1° febbraio 2024, il comando di avvio dell'app Web deve essere impostato su python3 -m gunicorn app:app. Per aggiornare un'app pubblicata prima del 1° febbraio 2024, è necessario aggiungere manualmente il comando di avvio dalla pagina Configurazione del servizio app.

È consigliabile eseguire frequentemente il pull delle modifiche dal ramo main per il codice sorgente dell'app Web, per assicurarsi di avere le correzioni di bug, la versione dell'API e i miglioramenti più recenti. L'app Web deve essere inoltre sincronizzata ogni volta che la versione dell'API usata viene ritirata. Valutare la possibilità di selezionare il pulsante Watch o Star nel repository GitHub dell'app Web per ricevere notifiche sulle modifiche e sugli aggiornamenti al codice sorgente.

Se l'app Web non è stata personalizzata, è possibile usare questi passaggi per sincronizzarla:

1. Passare all'app Web nel portale di Azure.

2. Nel menu a sinistra in Distribuzione selezionare Centro distribuzione.

3. Selezionare Sincronizza nella parte superiore del riquadro e verificare che l'app venga ridistribuita.

   

Se il codice sorgente dell'app è stato personalizzato o modificato, è necessario aggiornare manualmente il codice sorgente dell'app e ridistribuirlo:

• Se l'app è ospitata in GitHub, eseguire il push delle modifiche al codice nel repository e quindi seguire la procedura di sincronizzazione precedente.
• Se si ridistribuisce l'app manualmente, ad esempio tramite l'interfaccia della riga di comando di Azure, seguire i passaggi per la strategia di distribuzione.

Eliminazione dell'istanza di Cosmos DB

L'eliminazione dell'app Web non comporta l'eliminazione automatica dell'istanza di Cosmos DB. Per eliminare l'istanza di Cosmos DB, insieme a tutte le chat archiviate, è necessario passare alla risorsa associata nel portale di Azure ed eliminarla. Se si elimina la risorsa Cosmos DB, ma si mantiene selezionata l'opzione cronologia chat per gli aggiornamenti successivi da Azure OpenAI Studio, l'applicazione invia una notifica all'utente di un errore di connessione. Tuttavia, l'utente può continuare a usare l'app Web senza accedere alla cronologia delle chat.

Abilitazione dell'autenticazione di Microsoft Entra ID tra i servizi

Per abilitare Microsoft Entra ID per l'autenticazione all'interno del servizio per l'app Web, seguire questa procedura.

Abilitare l'identità gestita nella risorsa OpenAI di Azure e nel Servizio app di Azure

È possibile abilitare l'identità gestita per la risorsa OpenAI di Azure e il Servizio app di Azure passando a "Identità" e attivando l'identità gestita assegnata dal sistema nel portale di Azure per ogni risorsa.

Nota

Se si usa un modello di incorporamento distribuito nella stessa risorsa usata per l'inferenza, è sufficiente abilitare l'identità gestita in una risorsa OpenAI di Azure. Se si usa un modello di incorporamento distribuito in una risorsa diversa da quella usata per l'inferenza, è anche necessario abilitare l'identità gestita nella risorsa OpenAI di Azure usata per distribuire il modello di incorporamento.

Abilitare il controllo degli accessi in base al ruolo nella risorsa di Ricerca di Azure (facoltativo)

Se si usa On Your Data con Ricerca di Azure, seguire questo passaggio.

Per abilitare la risorsa OpenAI di Azure per accedere alla risorsa di Ricerca di Azure, è necessario abilitare il controllo degli accessi in base al ruolo nella risorsa di Ricerca di Azure. Altre informazioni sull'abilitazione dei ruoli Controllo degli accessi in base al ruolo per le risorse.

Assegnare ruoli controllo degli accessi in base al ruolo per abilitare la comunicazione all'interno del servizio

La tabella seguente riepiloga le assegnazioni di ruolo del controllo degli accessi in base al ruolo necessarie per tutte le risorse di Azure associate all'applicazione.

Ruolo	Assegnatario	Conto risorse
Search Index Data Reader	OpenAI di Azure (inferenza)	Azure AI Search
Search Service Contributor	OpenAI di Azure (inferenza)	Azure AI Search
Cognitive Services OpenAI User	Applicazione Web	OpenAI di Azure (inferenza)
Cognitive Services OpenAI User	OpenAI di Azure (inferenza)	Azure OpenAI (incorporamenti)

Per assegnare questi ruoli, seguire queste istruzioni per creare le assegnazioni di ruolo necessarie.

Modifiche alle impostazioni dell'app

Nelle impostazioni dell'applicazione webapp passare a "Variabili di ambiente" e apportare le modifiche seguenti:

• Rimuovere la variabile di ambiente AZURE_OPENAI_KEY, perché non è più necessaria.
• Se si usa On Your Data con Ricerca di Azure e si usa l'autenticazione Microsoft Entra ID tra Azure OpenAI e Ricerca di Azure, è anche necessario eliminare le variabili di ambiente AZURE_SEARCH_KEY per le chiavi di accesso all'origine dati.

Se si usa un modello di incorporamento distribuito nella stessa risorsa del modello usato per l'inferenza, non sono necessarie altre modifiche alle impostazioni.

Tuttavia, se si usa un modello di incorporamento distribuito in una risorsa diversa, apportare le modifiche aggiuntive seguenti alle variabili di ambiente dell'app:

• Impostare la variabile AZURE_OPENAI_EMBEDDING_ENDPOINT sul percorso API completo dell'API di incorporamento per la risorsa usata per gli incorporamenti, come https://<your embedding AOAI resource name>.openai.azure.com/openai/deployments/<your embedding deployment name>/embeddings
• Eliminare la variabile AZURE_OPENAI_EMBEDDING_KEY per usare l'autenticazione di Microsoft Entra ID.

Una volta completate tutte le modifiche alle variabili di ambiente, riavviare l'app Web per iniziare a usare l'autenticazione di Microsoft Entra ID tra i servizi nell'app Web. Il riavvio richiederà alcuni minuti per rendere effettive le modifiche alle impostazioni.

Contenuto correlato

• Progettazione prompt
• Azure OpenAI sui dati