Guida introduttiva: Chattare con i modelli OpenAI di Azure usando i propri dati

  • Articolo

In questa guida introduttiva è possibile usare i propri dati con i modelli OpenAI di Azure. L'uso di modelli di OpenAI di Azure sui dati può offrire una potente piattaforma di intelligenza artificiale conversazionale che consente comunicazioni più veloci e accurate.

Prerequisiti

Le risorse seguenti:

Si è verificato un problema con i prerequisiti.

Aggiungere i propri dati con Azure OpenAI Studio

Suggerimento

È possibile usare Azure Developer CLI per creare a livello di codice le risorse necessarie per Azure OpenAI nei dati

Passare a Studio OpenAI di Azure e accedere con le credenziali di accesso alla risorsa OpenAI di Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

  1. Selezionare il riquadro Usare i dati personali

    Screenshot della pagina di destinazione di Azure OpenAI Studio.

  2. Nell'area di Chat playgroundselezionare Aggiungi dati e quindi Aggiungere un'origine dati

    Screenshot del playground della chat in OpenAI Studio.

  3. Nel riquadro visualizzato, selezionare Carica file (anteprima) in Seleziona origine dati. Azure OpenAI richiede sia una risorsa di archiviazione che una risorsa di ricerca per accedere ai dati e indicizzarli.

    Suggerimento

    1. Per consentire ad Azure OpenAI di accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra origini (CORS). Se CORS non è già attivato per la risorsa di archiviazione BLOB di Azure, selezionare Attiva CORS.

    2. Selezionare la risorsa di Azure AI Search e selezionare che si è consapevoli che la connessione comporta l'utilizzo nell'account. Quindi seleziona Avanti.

    Screenshot che mostra le opzioni per la selezione di un'origine dati in Azure OpenAI Studio.

  4. Nel riquadro Carica file selezionare Cerca un file e selezionare i file scaricati dalla sezione prerequisiti o i propri dati. Selezionare quindi Carica file. Quindi seleziona Avanti.

  5. Nel riquadro Gestione dei dati è possibile scegliere se abilitare la ricerca semantica o ricerca vettoriale per l'indice.

    Importante

    • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. È necessario scegliere SKU Basic o superiore per abilitare la ricerca semantica o la ricerca vettoriale. Per altre informazioni, vedere Differenze del piano tariffario e Limiti del servizio.
    • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, tedesco, cinese(Zh), giapponese, coreano, russo e arabo.

  6. Esaminare i dettagli immessi e selezionare Salva e chiudi. È ora possibile chattare con il modello, ed esso userà informazioni derivate dai dati per generare la risposta.

Si è verificato un problema durante l'aggiunta dei dati.

Playground Chat

Iniziare a esplorare le funzionalità di Azure OpenAI con un approccio senza codice tramite il playground chat. Si tratta semplicemente di una casella di testo in cui è possibile inviare una richiesta di generazione di un completamento. Da questa pagina è possibile eseguire rapidamente l'iterazione e sperimentare con le funzionalità.

Screenshot del riquadro Playground di Azure OpenAI Studio con le sezioni evidenziate.

Il playground offre opzioni per personalizzare l'esperienza di chat. A destra, è possibile selezionare Distribuzione per determinare quale modello genera una risposta usando i risultati della ricerca dall'indice. Si sceglie il numero di messaggi passati da includere come cronologia delle conversazioni per le risposte generate in futuro. La cronologia conversazioni fornisce contesto per generare risposte correlate, ma utilizza anche l’utilizzo dei token. L'indicatore di stato del token di input tiene traccia del numero di token della domanda inviata.

Le impostazioni avanzate a sinistra sono parametri di runtime che consentono di controllare il recupero e la ricerca delle informazioni pertinenti dai dati. Un caso d'uso valido è quello in cui ci si vuole assicurare che le risposte vengano generate solo in base ai propri dati o si scopre che il modello non può generare una risposta in base alle informazioni esistenti sui propri dati.

  • Il Rigore determina l'aggressività del sistema nell'applicazione di filtri ai documenti di ricerca in base ai punteggi di somiglianza. L'impostazione di rigore su 5 indica che il sistema filtra in modo aggressivo i documenti, applicando una soglia di somiglianza molto elevata. La ricerca semantica può essere utile in questo scenario perché i modelli di classificazione eseguono un lavoro migliore per dedurre la finalità della query. I livelli più bassi di rigidità producono risposte più dettagliate, ma possono includere anche informazioni che non si trovano nell'indice. Questa opzione è impostata su 3 per impostazione predefinita.

  • I Documenti recuperatisono un numero intero che può essere impostato su 3, 5, 10 o 20 e controlla il numero di blocchi di documento forniti al modello linguistico di grandi dimensioni per simulare la risposta finale. Per impostazione predefinita, il valore è impostato su 5.

  • Quando Limitare le risposte ai dati è abilitato, il modello tenta di basarsi solo sui documenti per le risposte. Questa proprietà è impostata su true per impostazione predefinita.

Screenshot delle impostazioni avanzate.

Inviare la prima query. I modelli di chat eseguono al meglio esercizi di domande e risposte. Ad esempio, "Quali sono i piani di integrità disponibili?" o "Qual è l'opzione di integrità più?".

Le query che richiedono l'analisi dei dati potrebbero avere esito negativo, ad esempio "Quale piano di integrità è più diffuso?". Anche le query che richiedono informazioni su tutti i dati avranno esito negativo, ad esempio "Quanti documenti sono stati caricati?". Tenere presente che il motore di ricerca cerca blocchi con termini, frasi o costruzione esatti o simili alla query. Mentre il modello potrebbe comprendere la domanda, se i risultati della ricerca sono blocchi dal set di dati, non sono le informazioni corrette per rispondere a quel tipo di domanda.

Le chat sono vincolate dal numero di documenti (blocchi) restituiti nella risposta (limitato a 3-20 nel playground di Azure OpenAI Studio). Come si può immaginare, porre una domanda su "tutti i titoli" richiede un'analisi completa dell'intero archivio vettoriale.

Distribuire il modello

Una volta soddisfatti dell'esperienza in Azure OpenAI Studio, è possibile distribuire un'app Web direttamente da Studio selezionando il pulsante Distribuisci in.

Screenshot che mostra il pulsante di distribuzione del modello in Azure OpenAI Studio.

In questo modo è possibile eseguire la distribuzione in un'applicazione Web autonoma o un copilota in Copilot Studio (anteprima) se si usando i propri dati nel modello.

Ad esempio, se si sceglie di distribuire un'app Web:

La prima volta che si distribuisce un'app Web, è necessario selezionare Crea una nuova app Web. Scegliere un nome per l'app, che diventerà parte del suo URL. Ad esempio, https://<appname>.azurewebsites.net.

Selezionare la sottoscrizione, il gruppo di risorse, la località e il piano tariffario per l'app pubblicata. Per aggiornare un'app esistente, selezionare Pubblica in un'app Web esistente e scegliere il nome dell'app precedente dal menu a discesa.

Se si sceglie di distribuire un'app Web, vedere le considerazioni importanti per l'uso.

Si è verificato un problema con la distribuzione del modello.

Prerequisiti

Le risorse seguenti:

Aggiungere i propri dati con Azure OpenAI Studio

Suggerimento

È possibile usare Azure Developer CLI per creare a livello di codice le risorse necessarie per Azure OpenAI nei dati

Passare a Studio OpenAI di Azure e accedere con le credenziali di accesso alla risorsa OpenAI di Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

  1. Selezionare il riquadro Usare i dati personali

    Screenshot della pagina di destinazione di Azure OpenAI Studio.

  2. Nell'area di Chat playgroundselezionare Aggiungi dati e quindi Aggiungere un'origine dati

    Screenshot del playground della chat in OpenAI Studio.

  3. Nel riquadro visualizzato, selezionare Carica file (anteprima) in Seleziona origine dati. Azure OpenAI richiede sia una risorsa di archiviazione che una risorsa di ricerca per accedere ai dati e indicizzarli.

    Suggerimento

    1. Per consentire ad Azure OpenAI di accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra origini (CORS). Se CORS non è già attivato per la risorsa di archiviazione BLOB di Azure, selezionare Attiva CORS.

    2. Selezionare la risorsa di Azure AI Search e selezionare che si è consapevoli che la connessione comporta l'utilizzo nell'account. Quindi seleziona Avanti.

    Screenshot che mostra le opzioni per la selezione di un'origine dati in Azure OpenAI Studio.

  4. Nel riquadro Carica file selezionare Cerca un file e selezionare i file scaricati dalla sezione prerequisiti o i propri dati. Selezionare quindi Carica file. Quindi seleziona Avanti.

  5. Nel riquadro Gestione dei dati è possibile scegliere se abilitare la ricerca semantica o ricerca vettoriale per l'indice.

    Importante

    • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. È necessario scegliere SKU Basic o superiore per abilitare la ricerca semantica o la ricerca vettoriale. Per altre informazioni, vedere Differenze del piano tariffario e Limiti del servizio.
    • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, tedesco, cinese(Zh), giapponese, coreano, russo e arabo.

  6. Esaminare i dettagli immessi e selezionare Salva e chiudi. È ora possibile chattare con il modello, ed esso userà informazioni derivate dai dati per generare la risposta.

Si è verificato un problema durante l'aggiunta dei dati.

Recuperare variabili obbligatorie

Per eseguire correttamente una chiamata a OpenAI di Azure, sono necessarie le seguenti variabili. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. In alternativa, è possibile trovare il valore in Azure AI studio>Playground chat>Visualizzazione codice. Un endpoint di esempio è https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Gestione delle risorse>Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure o, in alternativa, in Gestione>Distribuzioni in Azure AI studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni>Chiavi durante l'esame della risorsa di Azure AI Search dal portale di Azure. È possibile usare la chiave do amministrazione primaria o la chiave di amministrazione secondaria. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema di configurazione.

Creare una nuova applicazione .NET Core

In una finestra di una console, ad esempio cmd, PowerShell o Bash, usare il comando dotnet new per creare una nuova app console con il nome azure-openai-quickstart. Questo comando crea un semplice progetto "Hello World" con un singolo file di origine C#: program.cs.

dotnet new console -n azure-openai-quickstart

Spostarsi nella cartella dell'app appena creata. È possibile compilare l'applicazione con il comando seguente:

dotnet build

L'output di compilazione non deve contenere alcun avviso o errore.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Installare la libreria client .NET OpenAI con:

dotnet add package Azure.AI.OpenAI --prerelease

Dalla directory del progetto, aprire il file Program.cs e sostituire i contenuti con il codice seguente:

Senza flusso di risposta

using Azure;
using Azure.AI.OpenAI;
using Azure.AI.OpenAI.Chat;
using OpenAI.Chat;
using System.Text.Json;
using static System.Environment;

string azureOpenAIEndpoint = GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
string azureOpenAIKey = GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
string deploymentName = GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_ID");
string searchEndpoint = GetEnvironmentVariable("AZURE_AI_SEARCH_ENDPOINT");
string searchKey = GetEnvironmentVariable("AZURE_AI_SEARCH_API_KEY");
string searchIndex = GetEnvironmentVariable("AZURE_AI_SEARCH_INDEX");

#pragma warning disable AOAI001
AzureOpenAIClient azureClient = new(
    new Uri(azureOpenAIEndpoint),
    new AzureKeyCredential(azureOpenAIKey));
ChatClient chatClient = azureClient.GetChatClient(deploymentName);

ChatCompletionOptions options = new();
options.AddDataSource(new AzureSearchChatDataSource()
{
    Endpoint = new Uri(searchEndpoint),
    IndexName = searchIndex,
    Authentication = DataSourceAuthentication.FromApiKey(searchKey),
});

ChatCompletion completion = chatClient.CompleteChat(
    [
        new UserChatMessage("What are my available health plans?"),
    ], options);

Console.WriteLine(completion.Content[0].Text);

AzureChatMessageContext onYourDataContext = completion.GetAzureMessageContext();

if (onYourDataContext?.Intent is not null)
{
    Console.WriteLine($"Intent: {onYourDataContext.Intent}");
}
foreach (AzureChatCitation citation in onYourDataContext?.Citations ?? [])
{
    Console.WriteLine($"Citation: {citation.Content}");
}

Importante

Per la produzione, usare un metodo sicuro per l'archiviazione e l'accesso alle proprie credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sulla sicurezza dei servizi di Azure AI.

dotnet run program.cs

Output

Contoso Electronics offers two health plans: Northwind Health Plus and Northwind Standard [doc1]. Northwind Health Plus is a comprehensive plan that provides coverage for medical, vision, and dental services, prescription drug coverage, mental health and substance abuse coverage, and coverage for preventive care services. It also offers coverage for emergency services, both in-network and out-of-network. On the other hand, Northwind Standard is a basic plan that provides coverage for medical, vision, and dental services, prescription drug coverage, and coverage for preventive care services. However, it does not offer coverage for emergency services, mental health and substance abuse coverage, or out-of-network services [doc1].

Intent: ["What are the available health plans?", "List of health plans available", "Health insurance options", "Types of health plans offered"]

Citation:
Contoso Electronics plan and benefit packages

Thank you for your interest in the Contoso electronics plan and benefit packages. Use this document to

learn more about the various options available to you...// Omitted for brevity

Questa operazione attenderà fino a quando il modello non ha generato l'intera risposta prima di stampare i risultati. In alternativa, se si desidera trasmettere in modo asincrono la risposta e stampare i risultati, è possibile sostituire il contenuto di Program.cs con il codice dell'esempio successivo.

Asincrono con streaming

using Azure;
using Azure.AI.OpenAI;
using Azure.AI.OpenAI.Chat;
using OpenAI.Chat;
using static System.Environment;

string azureOpenAIEndpoint = GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
string azureOpenAIKey = GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
string deploymentName = GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_ID");
string searchEndpoint = GetEnvironmentVariable("AZURE_AI_SEARCH_ENDPOINT");
string searchKey = GetEnvironmentVariable("AZURE_AI_SEARCH_API_KEY");
string searchIndex = GetEnvironmentVariable("AZURE_AI_SEARCH_INDEX");

#pragma warning disable AOAI001

AzureOpenAIClient azureClient = new(
    new Uri(azureOpenAIEndpoint),
    new AzureKeyCredential(azureOpenAIKey));
ChatClient chatClient = azureClient.GetChatClient(deploymentName);

ChatCompletionOptions options = new();
options.AddDataSource(new AzureSearchChatDataSource()
{
    Endpoint = new Uri(searchEndpoint),
    IndexName = searchIndex,
    Authentication = DataSourceAuthentication.FromApiKey(searchKey),
});

var chatUpdates = chatClient.CompleteChatStreamingAsync(
    [
        new UserChatMessage("What are my available health plans?"),
    ], options);

AzureChatMessageContext onYourDataContext = null;
await foreach (var chatUpdate in chatUpdates)
{
    if (chatUpdate.Role.HasValue)
    {
        Console.WriteLine($"{chatUpdate.Role}: ");
    }

    foreach (var contentPart in chatUpdate.ContentUpdate)
    {
        Console.Write(contentPart.Text);
    }

    if (onYourDataContext == null)
    {
        onYourDataContext = chatUpdate.GetAzureMessageContext();
    }
}

Console.WriteLine();
if (onYourDataContext?.Intent is not null)
{
    Console.WriteLine($"Intent: {onYourDataContext.Intent}");
}
foreach (AzureChatCitation citation in onYourDataContext?.Citations ?? [])
{
    Console.Write($"Citation: {citation.Content}");
}

Si è verificato un problema durante l'esecuzione dei codici di esempio.

Codice sorgente| Codice sorgente | Esempio

Prerequisiti

Le risorse seguenti:

Aggiungere i propri dati con Azure OpenAI Studio

Suggerimento

È possibile usare Azure Developer CLI per creare a livello di codice le risorse necessarie per Azure OpenAI nei dati

Passare a Studio OpenAI di Azure e accedere con le credenziali di accesso alla risorsa OpenAI di Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

  1. Selezionare il riquadro Usare i dati personali

    Screenshot della pagina di destinazione di Azure OpenAI Studio.

  2. Nell'area di Chat playgroundselezionare Aggiungi dati e quindi Aggiungere un'origine dati

    Screenshot del playground della chat in OpenAI Studio.

  3. Nel riquadro visualizzato, selezionare Carica file (anteprima) in Seleziona origine dati. Azure OpenAI richiede sia una risorsa di archiviazione che una risorsa di ricerca per accedere ai dati e indicizzarli.

    Suggerimento

    1. Per consentire ad Azure OpenAI di accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra origini (CORS). Se CORS non è già attivato per la risorsa di archiviazione BLOB di Azure, selezionare Attiva CORS.

    2. Selezionare la risorsa di Azure AI Search e selezionare che si è consapevoli che la connessione comporta l'utilizzo nell'account. Quindi seleziona Avanti.

    Screenshot che mostra le opzioni per la selezione di un'origine dati in Azure OpenAI Studio.

  4. Nel riquadro Carica file selezionare Cerca un file e selezionare i file scaricati dalla sezione prerequisiti o i propri dati. Selezionare quindi Carica file. Quindi seleziona Avanti.

  5. Nel riquadro Gestione dei dati è possibile scegliere se abilitare la ricerca semantica o ricerca vettoriale per l'indice.

    Importante

    • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. È necessario scegliere SKU Basic o superiore per abilitare la ricerca semantica o la ricerca vettoriale. Per altre informazioni, vedere Differenze del piano tariffario e Limiti del servizio.
    • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, tedesco, cinese(Zh), giapponese, coreano, russo e arabo.

  6. Esaminare i dettagli immessi e selezionare Salva e chiudi. È ora possibile chattare con il modello, ed esso userà informazioni derivate dai dati per generare la risposta.

Si è verificato un problema durante l'aggiunta dei dati.

Recuperare variabili obbligatorie

Per eseguire correttamente una chiamata a OpenAI di Azure, sono necessarie le seguenti variabili. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Per altre informazioni, vedere Aggiungere i dati con Studio AI della piattaforma Azure.

Nome variabile Valore
AZURE_OPENAI_ENDPOINT È possibile trovare questo valore nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. In alternativa, è possibile trovare il valore in Azure AI studio>Playground chat>Visualizzazione codice. Un endpoint di esempio è https://my-resource.openai.azure.com.
AZURE_OPENAI_API_KEY È possibile trovare questo valore nella sezione Gestione delle risorse>Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_OPEN_AI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione delle risorse>Distribuzioni nel portale di Azure o, in alternativa, in Gestione>Distribuzioni in Studio AI della piattaforma Azure.
AZURE_AI_SEARCH_ENDPOINT È possibile trovare questo valore nella sezione Panoramica quando si esamina la risorsa Ricerca cognitiva di Azure dal portale di Azure.
AZURE_AI_SEARCH_API_KEY È possibile trovare questo valore nella sezione Impostazioni>Chiavi quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dal portale di Azure. È possibile usare la chiave do amministrazione primaria o la chiave di amministrazione secondaria. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

Nota

Spring AI imposta per impostazione predefinita il nome del modello su gpt-35-turbo. È necessario specificare il valore SPRING_AI_AZURE_OPENAI_MODEL solo se è stato distribuito un modello con un nome diverso.

export SPRING_AI_AZURE_OPENAI_ENDPOINT=REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE
export SPRING_AI_AZURE_OPENAI_API_KEY=REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE
export SPRING_AI_AZURE_COGNITIVE_SEARCH_ENDPOINT=REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE
export SPRING_AI_AZURE_COGNITIVE_SEARCH_API_KEY=REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE
export SPRING_AI_AZURE_COGNITIVE_SEARCH_INDEX=REPLACE_WITH_YOUR_INDEX_NAME_HERE
export SPRING_AI_AZURE_OPENAI_MODEL=REPLACE_WITH_YOUR_MODEL_NAME_HERE

Si è verificato un problema di configurazione.

Creare una nuova applicazione Spring

Spring AI non supporta attualmente le opzioni di AzureCognitiveSearchChatExtensionConfiguration che consentono a una query Azure AI di incapsulare il metodo di Recupero di generazione aumentata (RAG) e di nascondere i dettagli all'utente. In alternativa, è comunque possibile richiamare il metodo RAG direttamente nell'applicazione per eseguire query sui dati nell'indice di Ricerca intelligenza artificiale di Azure e usare i documenti recuperati per aumentare la query.

Spring AI supporta un'astrazione VectorStore ed è possibile eseguire il wrapping di Ricerca intelligenza artificiale di Azure in un'implementazione Spring AI VectorStore per eseguire query sui dati personalizzati. Il progetto seguente implementa un VectorStore personalizzato supportato da Ricerca di intelligenza artificiale di Azure ed esegue direttamente le operazioni RAG.

In una finestra Bash creare una nuova directory per l'app e passare a essa.

mkdir ai-custom-data-demo && cd ai-custom-data-demo

Eseguire il comando spring init dalla directory di lavoro. Questo comando crea una struttura di directory standard per il progetto Spring, incluso il file di origine della classe Java principale e il file pom.xml usato per la gestione dei progetti basati su Maven.

spring init -a ai-custom-data-demo -n AICustomData --force --build maven -x

I file e le cartelle generati sono simili alla struttura seguente:

ai-custom-data-demo/
|-- pom.xml
|-- mvn
|-- mvn.cmd
|-- HELP.md
|-- src/
    |-- main/
    |   |-- resources/
    |   |   |-- application.properties
    |   |-- java/
    |       |-- com/
    |           |-- example/
    |               |-- aicustomdatademo/
    |                   |-- AiCustomDataApplication.java
    |-- test/
        |-- java/
            |-- com/
                |-- example/
                    |-- aicustomdatademo/
                        |-- AiCustomDataApplicationTests.java

Modificare l'applicazione Spring

  1. Modificare il file pom.xml.

    Dalla radice della directory del progetto aprire il file pom.xml nell'editor o nell'IDE preferito e sovrascrivere il file con il contenuto seguente:

    <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>ai-custom-data-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>AICustomData</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.experimental.ai</groupId>
            <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
            <version>0.7.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.6.0-beta.10</version>
            <exclusions>
                <!-- exclude this to avoid changing the default serializer and the null-value behavior -->
                <exclusion>
                    <groupId>com.azure</groupId>
                    <artifactId>azure-core-serializer-json-jackson</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
    <repositories>
        <repository>
            <id>spring-snapshots</id>
            <name>Spring Snapshots</name>
            <url>https://repo.spring.io/snapshot</url>
            <releases>
                <enabled>false</enabled>
            </releases>
        </repository>
    </repositories>
</project>

  2. Dalla cartella src/main/java/com/example/aicustomdatademo aprire AiCustomDataApplication.java nell'editor o nell'IDE preferito e incollare il codice seguente:

    package com.example.aicustomdatademo;

import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.stream.Collectors;

import org.springframework.ai.client.AiClient;
import org.springframework.ai.document.Document;
import org.springframework.ai.embedding.EmbeddingClient;
import org.springframework.ai.prompt.Prompt;
import org.springframework.ai.prompt.SystemPromptTemplate;
import org.springframework.ai.prompt.messages.MessageType;
import org.springframework.ai.prompt.messages.UserMessage;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.util.Context;
import com.azure.search.documents.SearchClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.models.IndexingResult;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.RawVectorQuery;

import lombok.AllArgsConstructor;
import lombok.NoArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.extern.jackson.Jacksonized;

@SpringBootApplication
public class AiCustomDataApplication implements CommandLineRunner
{
    private static final String ROLE_INFO_KEY = "role";

    private static final String template = """
            You are a helpful assistant. Use the information from the DOCUMENTS section to augment answers.

            DOCUMENTS:
            {documents}
            """;

    @Value("${spring.ai.azure.cognitive-search.endpoint}")
    private String acsEndpoint;

    @Value("${spring.ai.azure.cognitive-search.api-key}")
    private String acsApiKey;

    @Value("${spring.ai.azure.cognitive-search.index}")
    private String acsIndexName;

    @Autowired
    private AiClient aiClient;

    @Autowired
    private EmbeddingClient embeddingClient;

    public static void main(String[] args) {
        SpringApplication.run(AiCustomDataApplication.class, args);
    }

    @Override
    public void run(String... args) throws Exception
    {
        System.out.println(String.format("Sending custom data prompt to AI service. One moment please...\r\n"));

        final var store = vectorStore(embeddingClient);

        final String question = "What are my available health plans?";

        final var candidateDocs = store.similaritySearch(question);

        final var userMessage = new UserMessage(question);

        final String docPrompts =
                candidateDocs.stream().map(entry -> entry.getContent()).collect(Collectors.joining("\n"));

        final SystemPromptTemplate promptTemplate = new SystemPromptTemplate(template);
        final var systemMessage = promptTemplate.createMessage(Map.of("documents", docPrompts));

        final var prompt = new Prompt(List.of(systemMessage, userMessage));

        final var resps = aiClient.generate(prompt);

        System.out.println(String.format("Prompt created %d generated response(s).", resps.getGenerations().size()));

        resps.getGenerations().stream()
          .forEach(gen -> {
              final var role = gen.getInfo().getOrDefault(ROLE_INFO_KEY, MessageType.ASSISTANT.getValue());

              System.out.println(String.format("Generated respose from \"%s\": %s", role, gen.getText()));
          });

    }

    @Bean
    public VectorStore vectorStore(EmbeddingClient embeddingClient)
    {
        final SearchClient searchClient = new SearchClientBuilder()
                .endpoint(acsEndpoint)
                .credential(new AzureKeyCredential(acsApiKey))
                .indexName(acsIndexName)
                .buildClient();
        return new AzureCognitiveSearchVectorStore(searchClient, embeddingClient);
    }

    public static class AzureCognitiveSearchVectorStore implements VectorStore
    {
        private static final int DEFAULT_TOP_K = 4;

        private static final Double DEFAULT_SIMILARITY_THRESHOLD = 0.0;

        private SearchClient searchClient;

        private final EmbeddingClient embeddingClient;

        public AzureCognitiveSearchVectorStore(SearchClient searchClient, EmbeddingClient embeddingClient)
        {
            this.searchClient = searchClient;
            this.embeddingClient = embeddingClient;
        }

        @Override
        public void add(List<Document> documents)
        {
            final var docs = documents.stream().map(document -> {

                final var embeddings = embeddingClient.embed(document);

                return new DocEntry(document.getId(), "", document.getContent(), embeddings);

            }).toList();

            searchClient.uploadDocuments(docs);
        }

        @Override
        public Optional<Boolean> delete(List<String> idList)
        {
            final List<DocEntry> docIds = idList.stream().map(id -> DocEntry.builder().id(id).build())
                .toList();

            var results = searchClient.deleteDocuments(docIds);

            boolean resSuccess = true;

            for (IndexingResult result : results.getResults())
                if (!result.isSucceeded()) {
                    resSuccess = false;
                    break;
                }

            return Optional.of(resSuccess);
        }

        @Override
        public List<Document> similaritySearch(String query)
        {
            return similaritySearch(query, DEFAULT_TOP_K);
        }

        @Override
        public List<Document> similaritySearch(String query, int k)
        {
            return similaritySearch(query, k, DEFAULT_SIMILARITY_THRESHOLD);
        }

        @Override
        public List<Document> similaritySearch(String query, int k, double threshold)
        {
            final var searchQueryVector = new RawVectorQuery()
                    .setVector(toFloatList(embeddingClient.embed(query)))
                    .setKNearestNeighborsCount(k)
                    .setFields("contentVector");

            final var searchResults = searchClient.search(null,
                    new SearchOptions().setVectorQueries(searchQueryVector), Context.NONE);

            return searchResults.stream()
                    .filter(r -> r.getScore() >= threshold)
                    .map(r -> {

                        final DocEntry entry = r.getDocument(DocEntry.class);

                        final Document doc = new Document(entry.getId(), entry.getContent(), Collections.emptyMap());
                        doc.setEmbedding(entry.getContentVector());

                        return doc;
                    })
                    .collect(Collectors.toList());
        }

        private List<Float> toFloatList(List<Double> doubleList)
        {
            return doubleList.stream().map(Double::floatValue).toList();
        }

    }

    @Data
    @Builder
    @Jacksonized
    @AllArgsConstructor
    @NoArgsConstructor
    static class DocEntry
    {
        private String id;

        private String hash;

        private String content;

        private List<Double> contentVector;
    }

}

    Importante

    Per la produzione, usare un metodo sicuro per l'archiviazione e l'accesso alle proprie credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sulla sicurezza dei servizi di Azure AI.

  3. Tornare alla cartella radice del progetto ed eseguire l'app usando il comando seguente:

    ./mvnw spring-boot:run

Output

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.1.5)

2023-11-07T14:40:45.250-06:00  INFO 18557 --- [           main] c.e.a.AiCustomDataApplication            : No active profile set, falling back to 1 default profile: "default"
2023-11-07T14:40:46.035-06:00  INFO 18557 --- [           main] c.e.a.AiCustomDataApplication            : Started AiCustomDataApplication in 1.095 seconds (process running for 1.397)
Sending custom data prompt to AI service. One moment please...

Prompt created 1 generated response(s).
Generated response from "assistant": The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans.

Si è verificato un problema durante l'esecuzione dei codici di esempio.

Prerequisiti

Documentazione di riferimento | Codice sorgente | Pacchetto (npm) | Campioni

Aggiungere i propri dati con Azure OpenAI Studio

Suggerimento

È possibile usare Azure Developer CLI per creare a livello di codice le risorse necessarie per Azure OpenAI nei dati

Passare a Studio OpenAI di Azure e accedere con le credenziali di accesso alla risorsa OpenAI di Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

  1. Selezionare il riquadro Usare i dati personali

    Screenshot della pagina di destinazione di Azure OpenAI Studio.

  2. Nell'area di Chat playgroundselezionare Aggiungi dati e quindi Aggiungere un'origine dati

    Screenshot del playground della chat in OpenAI Studio.

  3. Nel riquadro visualizzato, selezionare Carica file (anteprima) in Seleziona origine dati. Azure OpenAI richiede sia una risorsa di archiviazione che una risorsa di ricerca per accedere ai dati e indicizzarli.

    Suggerimento

    1. Per consentire ad Azure OpenAI di accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra origini (CORS). Se CORS non è già attivato per la risorsa di archiviazione BLOB di Azure, selezionare Attiva CORS.

    2. Selezionare la risorsa di Azure AI Search e selezionare che si è consapevoli che la connessione comporta l'utilizzo nell'account. Quindi seleziona Avanti.

    Screenshot che mostra le opzioni per la selezione di un'origine dati in Azure OpenAI Studio.

  4. Nel riquadro Carica file selezionare Cerca un file e selezionare i file scaricati dalla sezione prerequisiti o i propri dati. Selezionare quindi Carica file. Quindi seleziona Avanti.

  5. Nel riquadro Gestione dei dati è possibile scegliere se abilitare la ricerca semantica o ricerca vettoriale per l'indice.

    Importante

    • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. È necessario scegliere SKU Basic o superiore per abilitare la ricerca semantica o la ricerca vettoriale. Per altre informazioni, vedere Differenze del piano tariffario e Limiti del servizio.
    • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, tedesco, cinese(Zh), giapponese, coreano, russo e arabo.

  6. Esaminare i dettagli immessi e selezionare Salva e chiudi. È ora possibile chattare con il modello, ed esso userà informazioni derivate dai dati per generare la risposta.

Si è verificato un problema durante l'aggiunta dei dati.

Recuperare variabili obbligatorie

Per eseguire correttamente una chiamata a OpenAI di Azure, sono necessarie le seguenti variabili. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. In alternativa, è possibile trovare il valore in Azure AI studio>Playground chat>Visualizzazione codice. Un endpoint di esempio è https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Gestione delle risorse>Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure o, in alternativa, in Gestione>Distribuzioni in Azure AI studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni>Chiavi durante l'esame della risorsa di Azure AI Search dal portale di Azure. È possibile usare la chiave do amministrazione primaria o la chiave di amministrazione secondaria. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema di configurazione.

Inizializzare un'applicazione Node.js

In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app. Quindi, eseguire il comando npm init per creare un'applicazione node con un file package.json.

npm init

Installare la libreria client

Installare la libreria client OpenAI di Azure e le librerie di identità di Azure per JavaScript con npm:

npm install @azure/openai @azure/identity

Il file package.json dell'app verrà aggiornato con le dipendenze.

Aggiungere il codice JavaScript

  1. Aprire un prompt dei comandi nella posizione in cui si vuole il nuovo progetto e creare un nuovo file denominato ChatWithOwnData.js. Copiare il codice seguente nel file ChatWithOwnData.js.

    const { DefaultAzureCredential, getBearerTokenProvider } = require("@azure/identity");
const { AzureOpenAI } = require("openai");

// Set the Azure and AI Search values from environment variables
const endpoint = process.env["AZURE_OPENAI_ENDPOINT"];
const searchEndpoint = process.env["AZURE_AI_SEARCH_ENDPOINT"];
const searchIndex = process.env["AZURE_AI_SEARCH_INDEX"];

// keyless authentication    
const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

// Required Azure OpenAI deployment name and API version
const deploymentName = "gpt-4";
const apiVersion = "2024-07-01-preview";

function getClient() {
  return new AzureOpenAI({
    endpoint,
    azureADTokenProvider,
    deployment: deploymentName,
    apiVersion,
  });
}

async function main() {
  const client = getClient();

  const messages = [
    { role: "user", content: "What are my available health plans?" },
  ];

  console.log(`Message: ${messages.map((m) => m.content).join("\n")}`);

  const events = await client.chat.completions.create({
    stream: true,
    messages: [
      {
        role: "user",
        content:
          "What's the most common feedback we received from our customers about the product?",
      },
    ],
    max_tokens: 128,
    model: "",
    data_sources: [
      {
        type: "azure_search",
        parameters: {
          endpoint: searchEndpoint,
          index_name: searchIndex,
          authentication: {
            type: "api_key",
            key: searchKey,
          },
        },
      },
    ],
  });

  let response = "";
  for await (const event of events) {
    for (const choice of event.choices) {
      const newText = choice.delta?.content;
      if (newText) {
        response += newText;
        // To see streaming results as they arrive, uncomment line below
        // console.log(newText);
      }
    }
  }
  console.log(response);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

  2. Eseguire l'applicazione con il comando seguente:

    node ChatWithOwnData.js

Importante

Per la produzione, usare un metodo sicuro per l'archiviazione e l'accesso alle proprie credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sulla sicurezza dei servizi di Azure AI.

Output

Message: What are my available health plans?
The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans.

Si è verificato un problema durante l'esecuzione del codice di esempio.

Prerequisiti

Documentazione di riferimento | Codice sorgente | Pacchetto (npm) | Campioni

Aggiungere i propri dati con Azure OpenAI Studio

Suggerimento

È possibile usare Azure Developer CLI per creare a livello di codice le risorse necessarie per Azure OpenAI nei dati

Passare a Studio OpenAI di Azure e accedere con le credenziali di accesso alla risorsa OpenAI di Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

  1. Selezionare il riquadro Usare i dati personali

    Screenshot della pagina di destinazione di Azure OpenAI Studio.

  2. Nell'area di Chat playgroundselezionare Aggiungi dati e quindi Aggiungere un'origine dati

    Screenshot del playground della chat in OpenAI Studio.

  3. Nel riquadro visualizzato, selezionare Carica file (anteprima) in Seleziona origine dati. Azure OpenAI richiede sia una risorsa di archiviazione che una risorsa di ricerca per accedere ai dati e indicizzarli.

    Suggerimento

    1. Per consentire ad Azure OpenAI di accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra origini (CORS). Se CORS non è già attivato per la risorsa di archiviazione BLOB di Azure, selezionare Attiva CORS.

    2. Selezionare la risorsa di Azure AI Search e selezionare che si è consapevoli che la connessione comporta l'utilizzo nell'account. Quindi seleziona Avanti.

    Screenshot che mostra le opzioni per la selezione di un'origine dati in Azure OpenAI Studio.

  4. Nel riquadro Carica file selezionare Cerca un file e selezionare i file scaricati dalla sezione prerequisiti o i propri dati. Selezionare quindi Carica file. Quindi seleziona Avanti.

  5. Nel riquadro Gestione dei dati è possibile scegliere se abilitare la ricerca semantica o ricerca vettoriale per l'indice.

    Importante

    • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. È necessario scegliere SKU Basic o superiore per abilitare la ricerca semantica o la ricerca vettoriale. Per altre informazioni, vedere Differenze del piano tariffario e Limiti del servizio.
    • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, tedesco, cinese(Zh), giapponese, coreano, russo e arabo.

  6. Esaminare i dettagli immessi e selezionare Salva e chiudi. È ora possibile chattare con il modello, ed esso userà informazioni derivate dai dati per generare la risposta.

Si è verificato un problema durante l'aggiunta dei dati.

Recuperare variabili obbligatorie

Per eseguire correttamente una chiamata a OpenAI di Azure, sono necessarie le seguenti variabili. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. In alternativa, è possibile trovare il valore in Azure AI studio>Playground chat>Visualizzazione codice. Un endpoint di esempio è https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Gestione delle risorse>Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure o, in alternativa, in Gestione>Distribuzioni in Azure AI studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni>Chiavi durante l'esame della risorsa di Azure AI Search dal portale di Azure. È possibile usare la chiave do amministrazione primaria o la chiave di amministrazione secondaria. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema di configurazione.

Inizializzare un'applicazione Node.js

In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app. Quindi, eseguire il comando npm init per creare un'applicazione node con un file package.json.

npm init

Installare la libreria client

Installare la libreria client OpenAI di Azure e le librerie di identità di Azure per JavaScript con npm:

npm install openai @azure/identity @azure/openai

La dipendenza @azure/openai/types è inclusa per estendere il modello di Azure OpenAI per la proprietà data_sources. Questa importazione è necessaria solo per TypeScript.

Il file package.json dell'app verrà aggiornato con le dipendenze.

Aggiungere il codice TypeScript

  1. Aprire un prompt dei comandi nella posizione in cui si vuole il nuovo progetto e creare un nuovo file denominato ChatWithOwnData.ts. Copiare il codice seguente nel file ChatWithOwnData.ts.

    import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import "@azure/openai/types";

// Set the Azure and AI Search values from environment variables
const endpoint = process.env["AZURE_OPENAI_ENDPOINT"];
const searchEndpoint = process.env["AZURE_AI_SEARCH_ENDPOINT"];
const searchIndex = process.env["AZURE_AI_SEARCH_INDEX"];

// keyless authentication    
const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

// Required Azure OpenAI deployment name and API version
const deploymentName = "gpt-4";
const apiVersion = "2024-07-01-preview";

function getClient(): AzureOpenAI {
  return new AzureOpenAI({
    endpoint,
    azureADTokenProvider,
    deployment: deploymentName,
    apiVersion,
  });
}

async function main() {
  const client = getClient();

  const messages = [
    { role: "user", content: "What are my available health plans?" },
  ];

  console.log(`Message: ${messages.map((m) => m.content).join("\n")}`);

  const events = await client.chat.completions.create({
    stream: true,
    messages: [
      {
        role: "user",
        content:
          "What's the most common feedback we received from our customers about the product?",
      },
    ],
    max_tokens: 128,
    model: "",
    data_sources: [
      {
        type: "azure_search",
        parameters: {
          endpoint: searchEndpoint,
          index_name: searchIndex,
          authentication: {
            type: "api_key",
            key: searchKey,
          },
        },
      },
    ],
  });

  let response = "";
  for await (const event of events) {
    for (const choice of event.choices) {
      const newText = choice.delta?.content;
      if (newText) {
        response += newText;
        // To see streaming results as they arrive, uncomment line below
        // console.log(newText);
      }
    }
  }
  console.log(response);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

  2. Compilare l'applicazione con il comando seguente:

    tsc

  3. Eseguire l'applicazione con il comando seguente:

    node ChatWithOwnData.js

Importante

Per la produzione, usare un metodo sicuro per l'archiviazione e l'accesso alle proprie credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sulla sicurezza dei servizi di Azure AI.

Output

Message: What are my available health plans?
The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans.

Prerequisiti

Le risorse seguenti:

Riferimento | Codice sorgente | Pacchetto (pypi) | Esempi

Questi collegamenti fanno riferimento all'API OpenAI per Python. Non è disponibile OpenAI Python SDK specifico di Azure. Informazioni su come passare tra i servizi OpenAI e i servizi OpenAI di Azure.

Aggiungere i propri dati con Azure OpenAI Studio

Suggerimento

È possibile usare Azure Developer CLI per creare a livello di codice le risorse necessarie per Azure OpenAI nei dati

Passare a Studio OpenAI di Azure e accedere con le credenziali di accesso alla risorsa OpenAI di Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

  1. Selezionare il riquadro Usare i dati personali

    Screenshot della pagina di destinazione di Azure OpenAI Studio.

  2. Nell'area di Chat playgroundselezionare Aggiungi dati e quindi Aggiungere un'origine dati

    Screenshot del playground della chat in OpenAI Studio.

  3. Nel riquadro visualizzato, selezionare Carica file (anteprima) in Seleziona origine dati. Azure OpenAI richiede sia una risorsa di archiviazione che una risorsa di ricerca per accedere ai dati e indicizzarli.

    Suggerimento

    1. Per consentire ad Azure OpenAI di accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra origini (CORS). Se CORS non è già attivato per la risorsa di archiviazione BLOB di Azure, selezionare Attiva CORS.

    2. Selezionare la risorsa di Azure AI Search e selezionare che si è consapevoli che la connessione comporta l'utilizzo nell'account. Quindi seleziona Avanti.

    Screenshot che mostra le opzioni per la selezione di un'origine dati in Azure OpenAI Studio.

  4. Nel riquadro Carica file selezionare Cerca un file e selezionare i file scaricati dalla sezione prerequisiti o i propri dati. Selezionare quindi Carica file. Quindi seleziona Avanti.

  5. Nel riquadro Gestione dei dati è possibile scegliere se abilitare la ricerca semantica o ricerca vettoriale per l'indice.

    Importante

    • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. È necessario scegliere SKU Basic o superiore per abilitare la ricerca semantica o la ricerca vettoriale. Per altre informazioni, vedere Differenze del piano tariffario e Limiti del servizio.
    • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, tedesco, cinese(Zh), giapponese, coreano, russo e arabo.

  6. Esaminare i dettagli immessi e selezionare Salva e chiudi. È ora possibile chattare con il modello, ed esso userà informazioni derivate dai dati per generare la risposta.

Si è verificato un problema durante l'aggiunta dei dati.

Recuperare variabili obbligatorie

Per eseguire correttamente una chiamata a OpenAI di Azure, sono necessarie le seguenti variabili. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. In alternativa, è possibile trovare il valore in Azure AI studio>Playground chat>Visualizzazione codice. Un endpoint di esempio è https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Gestione delle risorse>Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure o, in alternativa, in Gestione>Distribuzioni in Azure AI studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni>Chiavi durante l'esame della risorsa di Azure AI Search dal portale di Azure. È possibile usare la chiave do amministrazione primaria o la chiave di amministrazione secondaria. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema di configurazione.

Creare un ambiente Python

  1. Creare una nuova cartella denominata openai-python per il progetto e un nuovo file di codice Python denominato main.py. Passare a tale directory:
mkdir openai-python
cd openai-python
  1. Installare le librerie Python seguenti:
pip install openai
pip install python-dotenv

Creare l'app Python

  1. Dalla directory del progetto aprire il file main.py e aggiungere il codice seguente:
import os
import openai
import dotenv

dotenv.load_dotenv()

endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
api_key = os.environ.get("AZURE_OPENAI_API_KEY")
deployment = os.environ.get("AZURE_OPENAI_DEPLOYMENT_ID")

client = openai.AzureOpenAI(
    azure_endpoint=endpoint,
    api_key=api_key,
    api_version="2024-02-01",
)

completion = client.chat.completions.create(
    model=deployment,
    messages=[
        {
            "role": "user",
            "content": "What are my available health plans?",
        },
    ],
    extra_body={
        "data_sources":[
            {
                "type": "azure_search",
                "parameters": {
                    "endpoint": os.environ["AZURE_AI_SEARCH_ENDPOINT"],
                    "index_name": os.environ["AZURE_AI_SEARCH_INDEX"],
                    "authentication": {
                        "type": "api_key",
                        "key": os.environ["AZURE_AI_SEARCH_API_KEY"],
                    }
                }
            }
        ],
    }
)

print(completion.model_dump_json(indent=2))

Importante

Per la produzione, usare un metodo sicuro per l'archiviazione e l'accesso alle proprie credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sulla sicurezza dei servizi di Azure AI.

  1. Eseguire il comando seguente:
python main.py

L'applicazione stampa la risposta in un formato JSON adatto per l'uso in molti scenari. Include entrambe le risposte alla query e alle citazioni dai file caricati.

Si è verificato un problema durante l'esecuzione dei codici di esempio.

Prerequisiti

Le risorse seguenti:

Aggiungere i propri dati con Azure OpenAI Studio

Suggerimento

È possibile usare Azure Developer CLI per creare a livello di codice le risorse necessarie per Azure OpenAI nei dati

Passare a Studio OpenAI di Azure e accedere con le credenziali di accesso alla risorsa OpenAI di Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

  1. Selezionare il riquadro Usare i dati personali

    Screenshot della pagina di destinazione di Azure OpenAI Studio.

  2. Nell'area di Chat playgroundselezionare Aggiungi dati e quindi Aggiungere un'origine dati

    Screenshot del playground della chat in OpenAI Studio.

  3. Nel riquadro visualizzato, selezionare Carica file (anteprima) in Seleziona origine dati. Azure OpenAI richiede sia una risorsa di archiviazione che una risorsa di ricerca per accedere ai dati e indicizzarli.

    Suggerimento

    1. Per consentire ad Azure OpenAI di accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra origini (CORS). Se CORS non è già attivato per la risorsa di archiviazione BLOB di Azure, selezionare Attiva CORS.

    2. Selezionare la risorsa di Azure AI Search e selezionare che si è consapevoli che la connessione comporta l'utilizzo nell'account. Quindi seleziona Avanti.

    Screenshot che mostra le opzioni per la selezione di un'origine dati in Azure OpenAI Studio.

  4. Nel riquadro Carica file selezionare Cerca un file e selezionare i file scaricati dalla sezione prerequisiti o i propri dati. Selezionare quindi Carica file. Quindi seleziona Avanti.

  5. Nel riquadro Gestione dei dati è possibile scegliere se abilitare la ricerca semantica o ricerca vettoriale per l'indice.

    Importante

    • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. È necessario scegliere SKU Basic o superiore per abilitare la ricerca semantica o la ricerca vettoriale. Per altre informazioni, vedere Differenze del piano tariffario e Limiti del servizio.
    • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, tedesco, cinese(Zh), giapponese, coreano, russo e arabo.

  6. Esaminare i dettagli immessi e selezionare Salva e chiudi. È ora possibile chattare con il modello, ed esso userà informazioni derivate dai dati per generare la risposta.

Si è verificato un problema durante l'aggiunta dei dati.

Recuperare variabili obbligatorie

Per eseguire correttamente una chiamata a OpenAI di Azure, sono necessarie le seguenti variabili. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. In alternativa, è possibile trovare il valore in Azure AI studio>Playground chat>Visualizzazione codice. Un endpoint di esempio è https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Gestione delle risorse>Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure o, in alternativa, in Gestione>Distribuzioni in Azure AI studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni>Chiavi durante l'esame della risorsa di Azure AI Search dal portale di Azure. È possibile usare la chiave do amministrazione primaria o la chiave di amministrazione secondaria. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema di configurazione.

Comandi di PowerShell di esempio

I modelli di chat OpenAI di Azure sono ottimizzati per lavorare con input formattati come conversazione. La variabile messages passa una matrice di dizionari con ruoli diversi nella conversazione delineata da sistema, utente, strumento e assistente. La variabile dataSources si connette all'indice di Ricerca cognitiva di Azure e consente ai modelli OpenAI di Azure di rispondere usando i dati.

Per ottenere una risposta da parte modello, è necessario terminare con un messaggio utente che indichi che è il turno della risposta dell'assistente.

Suggerimento

È possibile usare diversi parametri per modificare la risposta del modello, ad esempio temperature o top_p. Per altre informazioni, vedere la documentazione di riferimento.

# Azure OpenAI metadata variables
   $openai = @{
       api_key     = $Env:AZURE_OPENAI_API_KEY
       api_base    = $Env:AZURE_OPENAI_ENDPOINT # your endpoint should look like the following https://YOUR_RESOURCE_NAME.openai.azure.com/
       api_version = '2023-07-01-preview' # this may change in the future
       name        = 'YOUR-DEPLOYMENT-NAME-HERE' #This will correspond to the custom name you chose for your deployment when you deployed a model.
   }

   $acs = @{
       search_endpoint     = 'YOUR ACS ENDPOINT' # your endpoint should look like the following https://YOUR_RESOURCE_NAME.search.windows.net/
       search_key    = 'YOUR-ACS-KEY-HERE' # or use the Get-Secret cmdlet to retrieve the value
       search_index = 'YOUR-INDEX-NAME-HERE' # the name of your ACS index
   }

   # Completion text
   $body = @{
    dataSources = @(
        @{
            type = 'AzureCognitiveSearch'
            parameters = @{
                    endpoint = $acs.search_endpoint
                    key = $acs.search_key
                    indexName = $acs.search_index
                }
        }
    )
    messages = @(
            @{
                role = 'user'
                content = 'What are my available health plans?'
            }
    )
   } | convertto-json -depth 5

   # Header for authentication
   $headers = [ordered]@{
       'api-key' = $openai.api_key
   }

   # Send a completion call to generate an answer
   $url = "$($openai.api_base)/openai/deployments/$($openai.name)/extensions/chat/completions?api-version=$($openai.api_version)"

   $response = Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Post -ContentType 'application/json'
   return $response.choices.messages[1].content

Output di esempio

The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans.

Importante

Per la produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio La gestione dei segreti di PowerShell con Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sulla sicurezza dei servizi di Azure AI.

Si è verificato un problema con l'invio della richiesta.

Chattare con il modello usando un'app Web

Per iniziare a chattare con il modello OpenAI di Azure che usa i dati, è possibile distribuire un'app Web Python usandoAzure OpenAI Studio o il codice di esempio fornito in GitHub. Questa app viene distribuita usando il servizio app di Azure e fornisce un'interfaccia utente per l'invio di query. Questa app può essere usata con modelli OpenAI di Azure che usano i dati o modelli che non li usano. Per istruzioni sui requisiti, la configurazione e la distribuzione, vedere il file readme nel repository. Facoltativamente, è possibile personalizzare la logica front-end e back-end dell'app Web apportando modifiche al codice sorgente.

Prerequisiti

Le risorse seguenti:

Riferimento | Codice sorgente | Pacchetto (Go) | Esempi

Aggiungere i propri dati con Azure OpenAI Studio

Suggerimento

È possibile usare Azure Developer CLI per creare a livello di codice le risorse necessarie per Azure OpenAI nei dati

Passare a Studio OpenAI di Azure e accedere con le credenziali di accesso alla risorsa OpenAI di Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

  1. Selezionare il riquadro Usare i dati personali

    Screenshot della pagina di destinazione di Azure OpenAI Studio.

  2. Nell'area di Chat playgroundselezionare Aggiungi dati e quindi Aggiungere un'origine dati

    Screenshot del playground della chat in OpenAI Studio.

  3. Nel riquadro visualizzato, selezionare Carica file (anteprima) in Seleziona origine dati. Azure OpenAI richiede sia una risorsa di archiviazione che una risorsa di ricerca per accedere ai dati e indicizzarli.

    Suggerimento

    1. Per consentire ad Azure OpenAI di accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra origini (CORS). Se CORS non è già attivato per la risorsa di archiviazione BLOB di Azure, selezionare Attiva CORS.

    2. Selezionare la risorsa di Azure AI Search e selezionare che si è consapevoli che la connessione comporta l'utilizzo nell'account. Quindi seleziona Avanti.

    Screenshot che mostra le opzioni per la selezione di un'origine dati in Azure OpenAI Studio.

  4. Nel riquadro Carica file selezionare Cerca un file e selezionare i file scaricati dalla sezione prerequisiti o i propri dati. Selezionare quindi Carica file. Quindi seleziona Avanti.

  5. Nel riquadro Gestione dei dati è possibile scegliere se abilitare la ricerca semantica o ricerca vettoriale per l'indice.

    Importante

    • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. È necessario scegliere SKU Basic o superiore per abilitare la ricerca semantica o la ricerca vettoriale. Per altre informazioni, vedere Differenze del piano tariffario e Limiti del servizio.
    • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, tedesco, cinese(Zh), giapponese, coreano, russo e arabo.

  6. Esaminare i dettagli immessi e selezionare Salva e chiudi. È ora possibile chattare con il modello, ed esso userà informazioni derivate dai dati per generare la risposta.

Si è verificato un problema durante l'aggiunta dei dati.

Recuperare variabili obbligatorie

Per eseguire correttamente una chiamata a OpenAI di Azure, sono necessarie le seguenti variabili. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. In alternativa, è possibile trovare il valore in Azure AI studio>Playground chat>Visualizzazione codice. Un endpoint di esempio è https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Gestione delle risorse>Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure o, in alternativa, in Gestione>Distribuzioni in Azure AI studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni>Chiavi durante l'esame della risorsa di Azure AI Search dal portale di Azure. È possibile usare la chiave do amministrazione primaria o la chiave di amministrazione secondaria. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema di configurazione.

Creare un ambiente Go

  1. Creare una nuova cartella denominata openai-go per il progetto e un nuovo file di codice Go denominato sample.go. Passare a tale directory:

    mkdir openai-go
cd openai-go

  2. Installare i pacchetti seguenti Go:

    go get github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai

  3. Abilitare il rilevamento delle dipendenze per il codice.

    go mod init example/azure-openai

Creare l'app Go

  1. Dalla directory del progetto aprire il file sample.go e aggiungere il codice seguente:

    package main

import (
 "context"
 "fmt"
 "log"
 "os"

 "github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
 "github.com/Azure/azure-sdk-for-go/sdk/azcore"
 "github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)

func main() {
 azureOpenAIKey := os.Getenv("AZURE_OPENAI_API_KEY")
 modelDeploymentID := os.Getenv("AZURE_OPENAI_DEPLOYMENT_ID")

 // Ex: "https://<your-azure-openai-host>.openai.azure.com"
 azureOpenAIEndpoint := os.Getenv("AZURE_OPENAI_ENDPOINT")

 // Azure AI Search configuration
 searchIndex := os.Getenv("AZURE_AI_SEARCH_INDEX")
 searchEndpoint := os.Getenv("AZURE_AI_SEARCH_ENDPOINT")
 searchAPIKey := os.Getenv("AZURE_AI_SEARCH_API_KEY")

 if azureOpenAIKey == "" || modelDeploymentID == "" || azureOpenAIEndpoint == "" || searchIndex == "" || searchEndpoint == "" || searchAPIKey == "" {
 	fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
 	return
 }

 keyCredential := azcore.NewKeyCredential(azureOpenAIKey)

 // In Azure OpenAI you must deploy a model before you can use it in your client. For more information
 // see here: https://video2.skills-academy.com/azure/cognitive-services/openai/how-to/create-resource
 client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)

 if err != nil {
 	//  TODO: Update the following line with your application specific error handling logic
 	log.Fatalf("ERROR: %s", err)
 }

 resp, err := client.GetChatCompletions(context.TODO(), azopenai.ChatCompletionsOptions{
 	Messages: []azopenai.ChatRequestMessageClassification{
 		&azopenai.ChatRequestUserMessage{Content: azopenai.NewChatRequestUserMessageContent("What are my available health plans?")},
 	},
 	MaxTokens: to.Ptr[int32](512),
 	AzureExtensionsOptions: []azopenai.AzureChatExtensionConfigurationClassification{
 		&azopenai.AzureSearchChatExtensionConfiguration{
 			// This allows Azure OpenAI to use an Azure AI Search index.
 			//
 			// > Because the model has access to, and can reference specific sources to support its responses, answers are not only based on its pretrained knowledge
 			// > but also on the latest information available in the designated data source. This grounding data also helps the model avoid generating responses
 			// > based on outdated or incorrect information.
 			//
 			// Quote from here: https://video2.skills-academy.com/en-us/azure/ai-services/openai/concepts/use-your-data
 			Parameters: &azopenai.AzureSearchChatExtensionParameters{
 				Endpoint:  &searchEndpoint,
 				IndexName: &searchIndex,
 				Authentication: &azopenai.OnYourDataAPIKeyAuthenticationOptions{
 					Key: &searchAPIKey,
 				},
 			},
 		},
 	},
 	DeploymentName: &modelDeploymentID,
 }, nil)

 if err != nil {
 	//  TODO: Update the following line with your application specific error handling logic
 	log.Fatalf("ERROR: %s", err)
 }

 fmt.Fprintf(os.Stderr, "Extensions Context Role: %s\nExtensions Context (length): %d\n",
 	*resp.Choices[0].Message.Role,
 	len(*resp.Choices[0].Message.Content))

 fmt.Fprintf(os.Stderr, "ChatRole: %s\nChat content: %s\n",
 	*resp.Choices[0].Message.Role,
 	*resp.Choices[0].Message.Content,
 )
}

    Importante

    Per la produzione, usare un metodo sicuro per l'archiviazione e l'accesso alle proprie credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sulla sicurezza dei servizi di Azure AI.

  2. Eseguire il comando seguente:

    go run sample.go

    L'applicazione stampa la risposta, incluse entrambe le risposte alla query e alle citazioni dei file caricati.

Si è verificato un problema durante l'esecuzione dei codici di esempio.

Prerequisiti

Le risorse seguenti:

Aggiungere i propri dati con Azure OpenAI Studio

Suggerimento

È possibile usare Azure Developer CLI per creare a livello di codice le risorse necessarie per Azure OpenAI nei dati

Passare a Studio OpenAI di Azure e accedere con le credenziali di accesso alla risorsa OpenAI di Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

  1. Selezionare il riquadro Usare i dati personali

    Screenshot della pagina di destinazione di Azure OpenAI Studio.

  2. Nell'area di Chat playgroundselezionare Aggiungi dati e quindi Aggiungere un'origine dati

    Screenshot del playground della chat in OpenAI Studio.

  3. Nel riquadro visualizzato, selezionare Carica file (anteprima) in Seleziona origine dati. Azure OpenAI richiede sia una risorsa di archiviazione che una risorsa di ricerca per accedere ai dati e indicizzarli.

    Suggerimento

    1. Per consentire ad Azure OpenAI di accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra origini (CORS). Se CORS non è già attivato per la risorsa di archiviazione BLOB di Azure, selezionare Attiva CORS.

    2. Selezionare la risorsa di Azure AI Search e selezionare che si è consapevoli che la connessione comporta l'utilizzo nell'account. Quindi seleziona Avanti.

    Screenshot che mostra le opzioni per la selezione di un'origine dati in Azure OpenAI Studio.

  4. Nel riquadro Carica file selezionare Cerca un file e selezionare i file scaricati dalla sezione prerequisiti o i propri dati. Selezionare quindi Carica file. Quindi seleziona Avanti.

  5. Nel riquadro Gestione dei dati è possibile scegliere se abilitare la ricerca semantica o ricerca vettoriale per l'indice.

    Importante

    • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. È necessario scegliere SKU Basic o superiore per abilitare la ricerca semantica o la ricerca vettoriale. Per altre informazioni, vedere Differenze del piano tariffario e Limiti del servizio.
    • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, tedesco, cinese(Zh), giapponese, coreano, russo e arabo.

  6. Esaminare i dettagli immessi e selezionare Salva e chiudi. È ora possibile chattare con il modello, ed esso userà informazioni derivate dai dati per generare la risposta.

Si è verificato un problema durante l'aggiunta dei dati.

Recuperare variabili obbligatorie

Per eseguire correttamente una chiamata a OpenAI di Azure, sono necessarie le seguenti variabili. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. In alternativa, è possibile trovare il valore in Azure AI studio>Playground chat>Visualizzazione codice. Un endpoint di esempio è https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Gestione delle risorse>Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure o, in alternativa, in Gestione>Distribuzioni in Azure AI studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni>Chiavi durante l'esame della risorsa di Azure AI Search dal portale di Azure. È possibile usare la chiave do amministrazione primaria o la chiave di amministrazione secondaria. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema con la configurazione.

Comandi cURL di esempio

I modelli di chat OpenAI di Azure sono ottimizzati per lavorare con input formattati come conversazione. La variabile messages passa una matrice di dizionari con ruoli diversi nella conversazione delineata da sistema, utente, strumento e assistente. La variabile dataSources si connette all'indice di Azure AI Search e consente ai modelli OpenAI di Azure di rispondere usando i dati.

Per ottenere una risposta da parte modello, è necessario terminare con un messaggio utente che indichi che è il turno della risposta dell'assistente.

Suggerimento

È possibile usare diversi parametri per modificare la risposta del modello, ad esempio temperature o top_p. Per altre informazioni, vedere la documentazione di riferimento.

curl -i -X POST $AZURE_OPENAI_ENDPOINT/openai/deployments/$AZURE_OPENAI_DEPLOYMENT_ID/chat/completions?api-version=2024-02-15-preview \
-H "Content-Type: application/json" \
-H "api-key: $AZURE_OPENAI_API_KEY" \
-d \
'
{
    "data_sources": [
        {
            "type": "azure_search",
            "parameters": {
                "endpoint": "'$AZURE_AI_SEARCH_ENDPOINT'",
                "key": "'$AZURE_AI_SEARCH_API_KEY'",
                "index_name": "'$AZURE_AI_SEARCH_INDEX'"
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are my available health plans?"
        }
    ]
}
'

Output di esempio

{
    "id": "12345678-1a2b-3c4e5f-a123-12345678abcd",
    "model": "gpt-4",
    "created": 1709835345,
    "object": "extensions.chat.completion",
    "choices": [
        {
            "index": 0,
            "finish_reason": "stop",
            "message": {
                "role": "assistant",
                "content": "The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans. [doc1].",
                "end_turn": true,
                "context": {
                    "citations": [
                        {
                            "content": "...",
                            "title": "...",
                            "url": "https://mysearch.blob.core.windows.net/xyz/001.txt",
                            "filepath": "001.txt",
                            "chunk_id": "0"
                        }
                    ],
                    "intent": "[\"Available health plans\"]"
                }
            }
        }
    ],
    "usage": {
        "prompt_tokens": 3779,
        "completion_tokens": 105,
        "total_tokens": 3884
    }
}

Si è verificato un problema con l'invio della richiesta.

Chattare con il modello usando un'app Web

Per iniziare a chattare con il modello OpenAI di Azure che usa i dati, è possibile distribuire un'app Web Python usandoAzure OpenAI Studio o il codice di esempio fornito in GitHub. Questa app viene distribuita usando il servizio app di Azure e fornisce un'interfaccia utente per l'invio di query. Questa app può essere usata con modelli OpenAI di Azure che usano i dati o modelli che non li usano. Per istruzioni sui requisiti, la configurazione e la distribuzione, vedere il file readme nel repository. Facoltativamente, è possibile personalizzare la logica front-end e back-end dell'app Web apportando modifiche al codice sorgente.

Pulire le risorse

Se si vuole ripulire e rimuovere una risorsa Azure OpenAI o Azure AI Search, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

Passaggi successivi