Condividi tramite

Guida introduttiva: introduzione all'uso degli assistenti OpenAI di Azure (anteprima)

  • Articolo

Gli assistenti OpenAI di Azure (anteprima) consentono di creare assistenti di intelligenza artificiale personalizzati in base alle proprie esigenze tramite istruzioni personalizzate e ottimizzarli con strumenti avanzati come l'interprete del codice e funzioni personalizzate.

Prerequisiti

Passare a OpenAI Studio di Azure

Passare a OpenAI Studio di Azure in https://oai.azure.com/ e accedere con le credenziali di accesso alla risorsa OpenAI. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

Dalla pagina di destinazione di OpenAI Studio di Azure avviare il playground dell'assistente dal riquadro di spostamento sinistro Playground>degli assistenti (anteprima)

Screenshot della pagina di destinazione di OpenAI Studio di Azure..

Playground

Il playground degli assistenti consente di esplorare, creare prototipi e testare assistenti di intelligenza artificiale senza dover eseguire codice. Da questa pagina è possibile eseguire rapidamente l'iterazione e sperimentare le funzionalità.

Screenshot della schermata di configurazione dell'assistente senza tutti i valori inseriti.

Configurazione assistente

Usare il riquadro Configurazione assistente per creare un nuovo assistente di intelligenza artificiale o selezionarne uno esistente.

Nome Descrizione
Nome assistente Nome della distribuzione associata a un modello specifico.
Istruzioni Le istruzioni sono simili ai messaggi di sistema; qui è dove si forniscono al modello le istruzioni sul comportamento e su qualsiasi contesto a cui deve fare riferimento durante la generazione di una risposta. È possibile descrivere la personalità dell'assistente, definire cosa deve e non deve rispondere e come formattare le risposte. È anche possibile fornire esempi dei passaggi da eseguire quando si risponde alle risposte.
Distribuzione Qui è possibile impostare la distribuzione modello da usare con l'assistente.
Funzioni Creare definizioni di funzioni personalizzate per i modelli, per formulare chiamate API e strutturare gli output dei dati in base alle specifiche
Interprete del codice L'interprete del codice fornisce l'accesso a un ambiente Python in modalità sandbox che può essere utilizzato per consentire al modello di testare ed eseguire codice.
File È possibile caricare fino a 20 file, con dimensioni massime di 512 MB, da usare con gli strumenti.

Strumenti

Un singolo assistente può accedere a un massimo di 128 strumenti, tra cui code interpreter, nonché a qualsiasi strumento personalizzato creato tramite le funzioni.

Sessione chat

La sessione di chat, denominata anche thread all'interno dell'API dell'assistente, rappresenta la posizione in cui si verifica la conversazione tra l'utente e l'assistente. A differenza delle chiamate di completamento della chat tradizionali non esiste alcun limite al numero di messaggi in un thread. L'assistente comprimerà automaticamente le richieste per adattarle al limite di token di input del modello.

Ciò significa anche che non si controlla il numero di token passati al modello durante ogni svolta della conversazione. La gestione dei token viene astratta e gestita interamente dall'API dell’assistente.

Selezionare il pulsante Cancella chat per eliminare la cronologia della conversazione corrente.

Sotto la casella di input di testo sono presenti due pulsanti:

  • Aggiungere un messaggio senza esecuzione.
  • Aggiungere ed eseguire.

Registri

I log forniscono uno snapshot dettagliato dell'attività dell'API dell’assistente.

Mostra pannelli

Per impostazione predefinita sono disponibili tre pannelli: configurazione assistente, sessione chat e impostazioni. Mostra pannelli consente di aggiungere, rimuovere e riorganizzare i pannelli. Se si chiude un pannello e si deve tornare indietro, usare Mostra pannelli per ripristinare il pannello perso.

Creare il primo assistente

  1. Nell'elenco a discesa di configurazione dell’assistente selezionare Nuovo

  2. Assegnare un nome all'assistente

  3. Immettere le istruzioni seguenti"Si è un assistente di intelligenza artificiale in grado di scrivere codice per rispondere alle domande matematiche”

  4. Selezionare una distribuzione di gpt-4 (1106-preview). Nell'elenco a discesa verranno visualizzati i nomi delle distribuzioni personalizzati, quindi se i nomi del modello/della distribuzione sono diversi, è consigliabile scegliere una distribuzione in cui il modello sottostante equivale al modello di anteprima 1106.

  5. Selezionare l'interruttore che abilita l'interprete del codice.

  6. Seleziona Salva.

    Screenshot dell'assistente con i dettagli di configurazione immessi.

  7. Immettere una domanda a cui l'assistente deve rispondere: "Devo risolvere l'equazione 3x + 11 = 14. Mi può aiutare?”

  8. Selezionare il pulsante Aggiungi ed esegui 

    The solution to the equation (3x + 11 = 14) is (x = 1).

    Anche se la risposta è corretta, verrà posta una seconda domanda per verificare che il modello usi l'interprete del codice per ottenere questa risposta anziché ottenerla dai dati di training del modello e che il codice scritto sia valido.

  9. Immettere la domanda di completamento: "Mostra il codice eseguito per ottenere la soluzione".

    Certainly! Here's the Python code I ran to find the solution for the equation (3x + 11 = 14):

    from sympy import symbols, Eq, solve  

# Define the variable  
x = symbols('x')  

# Define the equation  
equation = Eq(3*x + 11, 14)  

# Solve the equation  
solution = solve(equation, x)  
solution

Screenshot della sessione di conversazione nel playground dell’assistente.

È anche possibile consultare i log nel pannello di destra per verificare che sia stato usato l'interprete del codice e per convalidare il codice eseguito per generare la risposta. È importante ricordare che mentre l'interprete del codice offre al modello la possibilità di rispondere a domande matematiche più complesse convertendo le domande in codice ed eseguendolo in modalità sandbox in un ambiente Python, è comunque necessario convalidare la risposta per verificare che il modello abbia convertito correttamente la domanda in una rappresentazione valida nel codice.

Pulire le risorse

Per pulire e rimuovere una risorsa OpenAI, è 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.

Vedi anche

Importante

Alcune funzionalità descritte in questo articolo potrebbero essere disponibili solo in anteprima. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Prerequisiti

Passare a Studio AI della piattaforma Azure (anteprima)

  1. Accedere a Studio AI della piattaforma Azure.

  2. Passare al progetto o creare un nuovo progetto in Studio AI della piattaforma Azure.

  3. Nella panoramica del progetto selezionare Assistenti disponibile nel playground del progetto.

    Il playground degli assistenti consente di esplorare, creare prototipi e testare assistenti di intelligenza artificiale senza dover eseguire codice. Da questa pagina è possibile eseguire rapidamente l'iterazione e sperimentare le funzionalità.

    Il playground offre diverse opzioni per configurare l'assistente. Nei passaggi seguenti verrà usato il riquadro di configurazione dell’assistente per creare un nuovo assistente di intelligenza artificiale.

    Nome Descrizione
    Nome assistente Nome della distribuzione associata a un modello specifico.
    Istruzioni Le istruzioni sono simili ai messaggi di sistema; qui è dove si forniscono al modello le istruzioni sul comportamento e su qualsiasi contesto a cui deve fare riferimento durante la generazione di una risposta. È possibile descrivere la personalità dell'assistente, definire cosa deve e non deve rispondere e come formattare le risposte. È anche possibile fornire esempi dei passaggi da eseguire quando si risponde alle risposte.
    Distribuzione Qui è possibile impostare la distribuzione modello da usare con l'assistente.
    Funzioni Creare definizioni di funzioni personalizzate per i modelli per formulare chiamate API e strutturare gli output dei dati in base alle specifiche. Non usato in questa guida introduttiva.
    Interprete di codice L'interprete del codice fornisce l'accesso a un ambiente Python in modalità sandbox che può essere utilizzato per consentire al modello di testare ed eseguire codice.
    File È possibile caricare fino a 20 file, con dimensioni massime di 512 MB, da usare con gli strumenti. Non usato in questa guida introduttiva.

    Screenshot della schermata di configurazione dell'assistente senza tutti i valori inseriti.

Creare il primo assistente

  1. Selezionare la distribuzione dall'elenco a discesa Distribuzioni.

  2. Nell'elenco a discesa Configurazione assistente selezionare Nuovo.

  3. Assegnare un nome all'assistente.

  4. Immettere le istruzioni seguenti"Si è un assistente di intelligenza artificiale in grado di scrivere codice per rispondere alle domande matematiche”

  5. Selezionare una distribuzione del modello. È consigliabile eseguire test con uno dei modelli gpt-4 più recenti.

  6. Selezionare l'interruttore che abilita l'interprete del codice.

  7. Seleziona Salva.

    Screenshot dell'assistente con i dettagli di configurazione immessi.

  8. Immettere una domanda a cui l'assistente deve rispondere: "Devo risolvere l'equazione 3x + 11 = 14. Mi può aiutare?”

  9. Selezionare il pulsante Aggiungi ed esegui 

    The solution to the equation (3x + 11 = 14) is (x = 1).

    Anche se la risposta è corretta, verrà posta una seconda domanda per verificare che il modello usi l'interprete del codice per ottenere questa risposta anziché ottenerla dai dati di training del modello e che il codice scritto sia valido.

  10. Immettere la domanda di completamento: "Mostra il codice eseguito per ottenere la soluzione".

    Sure. The code is very straightforward

    # calculation
x = (14 - 11) / 3
x


    First, we subtract 11 from 14, then divide the result by 3. This gives us the value of x which is 1.0.

    Screenshot della sessione di conversazione nel playground dell’assistente.

È anche possibile consultare i log nel pannello di destra per verificare che sia stato usato l'interprete del codice e per convalidare il codice eseguito per generare la risposta. È importante ricordare che mentre l'interprete del codice offre al modello la possibilità di rispondere a domande matematiche più complesse convertendo le domande in codice ed eseguendolo in modalità sandbox in un ambiente Python, è comunque necessario convalidare la risposta per verificare che il modello abbia convertito correttamente la domanda in una rappresentazione valida nel codice.

Concetti chiave

Durante l'uso del playground Assistenti, tenere presenti i concetti seguenti.

Strumenti

Un singolo assistente può accedere a un massimo di 128 strumenti, tra cui code interpreter, nonché a qualsiasi strumento personalizzato creato tramite le funzioni.

Sessione chat

La sessione di chat, denominata anche thread all'interno dell'API dell'assistente, rappresenta la posizione in cui si verifica la conversazione tra l'utente e l'assistente. A differenza delle chiamate di completamento della chat tradizionali non esiste alcun limite al numero di messaggi in un thread. L'assistente comprimerà automaticamente le richieste per adattarle al limite di token di input del modello.

Ciò significa anche che non si controlla il numero di token passati al modello durante ogni svolta della conversazione. La gestione dei token viene astratta e gestita interamente dall'API dell’assistente.

Selezionare il pulsante Cancella chat per eliminare la cronologia della conversazione corrente.

Sotto la casella di input di testo sono presenti due pulsanti:

  • Aggiungere un messaggio senza esecuzione.
  • Aggiungere ed eseguire.

Registri

I log forniscono uno snapshot dettagliato dell'attività dell'API dell’assistente.

Mostra pannelli

Per impostazione predefinita sono disponibili tre pannelli: configurazione assistente, sessione chat e impostazioni. Mostra pannelli consente di aggiungere, rimuovere e riorganizzare i pannelli. Se si chiude un pannello e si deve tornare indietro, usare Mostra pannelli per ripristinare il pannello perso.

Pulire le risorse

Per pulire e rimuovere una risorsa OpenAI, è 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.

In alternativa, è possibile eliminare l'assistenteo il thread tramite l'API dell’assistente.

Vedi anche

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto di codice(PyPi) |

Prerequisiti

Per l'autenticazione senza password, è necessario

  1. Usare il pacchetto azure-identity .
  2. Assegnare il ruolo Cognitive Services User all'account utente. Questa operazione può essere eseguita nel portale di Azure in Controllo di accesso (IAM)>Aggiungi un'assegnazione di ruolo.
  3. Accedere con l'interfaccia della riga di comando di Azure, ad esempio az login.

Impostazione

  1. Installare la libreria client Python OpenAI con:
pip install openai
  1. Per l'autenticazione senza password consigliata:
pip install azure-identity

Nota

  • La ricerca di file può inserire fino a 10.000 file per assistente- 500 volte più di prima. È veloce, supporta query parallele tramite ricerche multithread e funzionalità avanzate di reranking e riscrittura delle query.
    • L'archivio vettoriale è un nuovo oggetto nell'API. Dopo l'aggiunta di un file a un archivio vettoriale, l'analisi viene eseguita automaticamente, in blocchi e incorporati, pronta per la ricerca. Gli archivi vettoriali possono essere usati tra assistenti e thread, semplificando la gestione e la fatturazione dei file.
  • È stato aggiunto il supporto per il tool_choice parametro che può essere usato per forzare l'uso di uno strumento specifico (ad esempio la ricerca di file, l'interprete di codice o una funzione) in una determinata esecuzione.

Nota

Questa libreria viene gestita da OpenAI. Fare riferimento alla cronologia delle versioni per tenere traccia degli aggiornamenti più recenti della libreria.

Recuperare la chiave e l'endpoint

Per effettuare correttamente una chiamata al servizio Azure OpenAI, sarà necessario quanto segue:

Nome variabile Valore
ENDPOINT Questo valore è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa dal portale di Azure. In alternativa, è possibile trovare il valore in OpenAI Studio di Azure>Playground>Visualizzazione codice. Un endpoint di esempio è https://docs-test-001.openai.azure.com/.
API-KEY Questo valore è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa dal portale di Azure. È possibile usare KEY1 o KEY2.
DEPLOYMENT-NAME Questo valore corrisponderà al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni del modello nel portale di Azure o, in alternativa, in Gestione>Distribuzioni in OpenAI Studio di Azure.

Passare alla risorsa nel portale di Azure. Le chiavi e gli endpoint sono disponibili nella sezione Gestione risorse. Copiare l'endpoint e la chiave di accesso in base alle esigenze per l'autenticazione delle chiamate API. 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.

Screenshot del pannello di panoramica per una risorsa OpenAI di Azure nel portale di Azure con la posizione dell'endpoint e delle chiavi di accesso evidenziata in rosso.

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

Variabili di ambiente

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

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

Creare un assistente

Nel codice verranno specificati i valori seguenti:

Nome Descrizione
Nome assistente Nome della distribuzione associata a un modello specifico.
Istruzioni Le istruzioni sono simili ai messaggi di sistema; qui è dove si forniscono al modello le istruzioni sul comportamento e su qualsiasi contesto a cui deve fare riferimento durante la generazione di una risposta. È possibile descrivere la personalità dell'assistente, definire cosa deve e non deve rispondere e come formattare le risposte. È anche possibile fornire esempi dei passaggi che deve eseguire quando risponde alle risposte.
Modello Qui è possibile impostare il nome della distribuzione del modello da usare con l'assistente. Lo strumento di recupero richiede il modello gpt-35-turbo (1106) o gpt-4 (1106-preview). Impostare questo valore sul nome della distribuzione, non sul nome del modello, a meno che non sia lo stesso.
Interprete di codice L'interprete del codice fornisce l'accesso a un ambiente Python in modalità sandbox che può essere usato per consentire al modello di testare ed eseguire codice.

Strumenti

Un singolo assistente può accedere a un massimo di 128 strumenti, tra cui code interpreter, nonché a qualsiasi strumento personalizzato creato tramite le funzioni.

Creare l'app Python

Accedere ad Azure con az login quindi creare ed eseguire un assistente con l'esempio python senza password consigliato seguente:

import os
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

Per usare la chiave API del servizio per l'autenticazione, è possibile creare ed eseguire un assistente con l'esempio Python seguente:

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

Output

Esecuzione completata con lo stato: completato

{
  "data": [
    {
      "id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
      "assistant_id": "asst_cYqL1RuwLyFV3HU1gkaE2k0K",
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
          },
          "type": "text"
        }
      ],
      "created_at": 1716397091,
      "metadata": {},
      "object": "thread.message",
      "role": "assistant",
      "run_id": "run_hFgBPbUtO8ZNTnNPC8PgpH1S",
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    },
    {
      "id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
      "assistant_id": null,
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
          },
          "type": "text"
        }
      ],
      "created_at": 1716397025,
      "metadata": {},
      "object": "thread.message",
      "role": "user",
      "run_id": null,
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    }
  ],
  "object": "list",
  "first_id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
  "last_id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
  "has_more": false
}

Informazioni sui risultati

In questo esempio viene creato un assistente con interprete di codice abilitato. Quando si pone all'assistente una domanda matematica, la domanda viene convertita in codice Python e viene eseguito il codice nell'ambiente sandbox per determinare la risposta alla domanda. Il codice che il modello crea e testa per arrivare a una risposta è:

from sympy import symbols, Eq, solve  
  
# Define the variable  
x = symbols('x')  
  
# Define the equation  
equation = Eq(3*x + 11, 14)  
  
# Solve the equation  
solution = solve(equation, x)  
solution

È importante ricordare che, benché l'interprete di codice offra al modello la possibilità di rispondere a query più complesse convertendo le domande in codice ed eseguendo tale codice in modo iterativo nella sandbox Python fino a quando non raggiunge una soluzione, è comunque necessario convalidare la risposta per verificare che il modello abbia convertito correttamente la domanda in una rappresentazione valida nel codice.

Pulire le risorse

Per pulire e rimuovere una risorsa OpenAI, è 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.

Vedi anche

Documentazione di riferimento | Pacchetto del codice | sorgente (NuGet)

Prerequisiti

Impostazione

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-assistants-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.Assistants --prerelease

Recuperare la chiave e l'endpoint

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessari un endpoint e una chiave.

Nome variabile Valore
ENDPOINT Questo valore è disponibile nella sezione Chiavi &ed endpoint durante l'esame della risorsa dalla portale di Azure. In alternativa, è possibile trovare il valore in OpenAI Studio di Azure>Playground>Visualizzazione codice. Un endpoint di esempio è https://docs-test-001.openai.azure.com/.
API-KEY Questo valore è disponibile nella sezione Chiavi ed endpoint durante l'esame della risorsa dalla portale di Azure. Puoi usare entrambi KEY1 o KEY2.

Passare alla risorsa nel portale di Azure. La sezione Chiavi ed endpoint è disponibile nella sezione Gestione risorse. Copiare l'endpoint e la chiave di accesso in base alle esigenze per l'autenticazione delle chiamate API. 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.

Screenshot di panoramica dell'interfaccia utente per una risorsa OpenAI di Azure nel portale di Azure con l'endpoint e la posizione delle chiavi di accesso evidenziati in rosso.

Variabili di ambiente

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

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

Creare un assistente

Nel codice verranno specificati i valori seguenti:

Nome Descrizione
Nome assistente Nome della distribuzione associata a un modello specifico.
Istruzioni Le istruzioni sono simili ai messaggi di sistema; qui è dove si forniscono al modello le istruzioni sul comportamento e su qualsiasi contesto a cui deve fare riferimento durante la generazione di una risposta. È possibile descrivere la personalità dell'assistente, definire cosa deve e non deve rispondere e come formattare le risposte. È anche possibile fornire esempi dei passaggi che deve eseguire quando risponde alle risposte.
Modello Qui è possibile impostare il nome della distribuzione del modello da usare con l'assistente. Lo strumento di recupero richiede il modello gpt-35-turbo (1106) o gpt-4 (1106-preview). Impostare questo valore sul nome della distribuzione, non sul nome del modello, a meno che non sia lo stesso.
Interprete di codice L'interprete del codice fornisce l'accesso a un ambiente Python in modalità sandbox che può essere usato per consentire al modello di testare ed eseguire codice.

Strumenti

Un singolo assistente può accedere a un massimo di 128 strumenti, tra cui code interpreter, nonché a qualsiasi strumento personalizzato creato tramite le funzioni.

Creare ed eseguire un assistente con quanto segue:

using Azure;
using Azure.AI.OpenAI.Assistants;

string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new ArgumentNullException("AZURE_OPENAI_ENDPOINT");
string key = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY") ?? throw new ArgumentNullException("AZURE_OPENAI_API_KEY");
AssistantsClient client = new AssistantsClient(new Uri(endpoint), new AzureKeyCredential(key));

// Create an assistant
Assistant assistant = await client.CreateAssistantAsync(
    new AssistantCreationOptions("gpt-4-1106-preview") // Replace this with the name of your model deployment
    {
        Name = "Math Tutor",
        Instructions = "You are a personal math tutor. Write and run code to answer math questions.",
        Tools = { new CodeInterpreterToolDefinition() }
    });

// Create a thread
AssistantThread thread = await client.CreateThreadAsync();

// Add a user question to the thread
ThreadMessage message = await client.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "I need to solve the equation `3x + 11 = 14`. Can you help me?");

// Run the thread
ThreadRun run = await client.CreateRunAsync(
    thread.Id,
    new CreateRunOptions(assistant.Id)
);

// Wait for the assistant to respond
do
{
    await Task.Delay(TimeSpan.FromMilliseconds(500));
    run = await client.GetRunAsync(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued
    || run.Status == RunStatus.InProgress);

// Get the messages
PageableList<ThreadMessage> messagesPage = await client.GetMessagesAsync(thread.Id);
IReadOnlyList<ThreadMessage> messages = messagesPage.Data;

// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
foreach (ThreadMessage threadMessage in messages.Reverse())
{
    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
    foreach (MessageContent contentItem in threadMessage.ContentItems)
    {
        if (contentItem is MessageTextContent textItem)
        {
            Console.Write(textItem.Text);
        }
        Console.WriteLine();
    }
}

Verrà stampato un output nel modo seguente:

2024-03-05 03:38:17 -       user: I need to solve the equation `3x + 11 = 14`. Can you help me?
2024-03-05 03:38:25 -  assistant: The solution to the equation \(3x + 11 = 14\) is \(x = 1\).

È possibile creare nuovi messaggi nel thread prima di ripetere l’esecuzione; in questo modo l'assistente userà i messaggi precedenti come contesto all'interno del thread.

Pulire le risorse

Per pulire e rimuovere una risorsa OpenAI, è 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.

Vedi anche

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (npm) |

Prerequisiti

Per l'autenticazione senza password, è necessario

  1. Usare il pacchetto @azure/identity.
  2. Assegnare il ruolo Cognitive Services User all'account utente. Questa operazione può essere eseguita nel portale di Azure in Controllo di accesso (IAM)>Aggiungi un'assegnazione di ruolo.
  3. Accedere con l'interfaccia della riga di comando di Azure, ad esempio az login.

Impostazione

  1. Installare la libreria client degli assistenti OpenAI per JavaScript con:

    npm install openai

  2. Per l'autenticazione senza password consigliata:

    npm install @azure/identity

Recuperare la chiave e l'endpoint

Per effettuare correttamente una chiamata al servizio Azure OpenAI, sarà necessario quanto segue:

Nome variabile Valore
ENDPOINT Questo valore è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa dal portale di Azure. In alternativa, è possibile trovare il valore in OpenAI Studio di Azure>Playground>Visualizzazione codice. Un endpoint di esempio è https://docs-test-001.openai.azure.com/.
API-KEY Questo valore è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa dal portale di Azure. È possibile usare KEY1 o KEY2.
DEPLOYMENT-NAME Questo valore corrisponderà al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni del modello nel portale di Azure o, in alternativa, in Gestione>Distribuzioni in OpenAI Studio di Azure.

Passare alla risorsa nel portale di Azure. Le chiavi e gli endpoint sono disponibili nella sezione Gestione risorse. Copiare l'endpoint e la chiave di accesso in base alle esigenze per l'autenticazione delle chiamate API. 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.

Screenshot del pannello della panoramica per una risorsa OpenAI nel portale di Azure con la posizione dell'endpoint e delle chiavi di accesso evidenziata in rosso.

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

Variabili di ambiente

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

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

Aggiungere altre variabili di ambiente per il nome della distribuzione e la versione dell'API:

  • AZURE_OPENAI_DEPLOYMENT_NAME: nome della distribuzione, come illustrato nella portale di Azure.
  • OPENAI_API_VERSION: altre informazioni sulle versioni api.

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

setx AZURE_OPENAI_DEPLOYMENT_NAME "REPLACE_WITH_YOUR_DEPLOYMENT_NAME" 
setx OPENAI_API_VERSION "REPLACE_WITH_YOUR_API_VERSION"

Creare un assistente

Nel codice verranno specificati i valori seguenti:

Nome Descrizione
Nome assistente Nome della distribuzione associata a un modello specifico.
Istruzioni Le istruzioni sono simili ai messaggi di sistema; qui è dove si forniscono al modello le istruzioni sul comportamento e su qualsiasi contesto a cui deve fare riferimento durante la generazione di una risposta. È possibile descrivere la personalità dell'assistente, definire cosa deve e non deve rispondere e come formattare le risposte. È anche possibile fornire esempi dei passaggi che deve eseguire quando risponde alle risposte.
Modello Si tratta del nome della distribuzione.
Interprete di codice L'interprete del codice fornisce l'accesso a un ambiente Python in modalità sandbox che può essere usato per consentire al modello di testare ed eseguire codice.

Strumenti

Un singolo assistente può accedere a un massimo di 128 strumenti, tra cui code interpreter, nonché a qualsiasi strumento personalizzato creato tramite le funzioni.

Accedere ad Azure con az login quindi creare ed eseguire un assistente con il seguente modulo TypeScript senza password consigliato (index.ts):

import "dotenv/config";
import { AzureOpenAI } from "openai";
import {
  Assistant,
  AssistantCreateParams,
  AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";

// Add `Cognitive Services User` to identity for Azure OpenAI resource
import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from "@azure/identity";

// Get environment variables
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
  .AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;

// Check env variables
if (!azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
  throw new Error(
    "Please ensure to set AZURE_OPENAI_DEPLOYMENT_NAME and AZURE_OPENAI_ENDPOINT in your environment variables."
  );
}

// Get Azure SDK client
const getClient = (): AzureOpenAI => {
  const credential = new DefaultAzureCredential();
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: openAIVersion,
    azureADTokenProvider,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options: AssistantCreateParams = {
  model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

// Create an assistant
const assistantResponse: Assistant =
  await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);

// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);

// Add a user question to the thread
const threadResponse: Message =
  await assistantsClient.beta.threads.messages.create(assistantThread.id, {
    role,
    content: message,
  });
console.log(`Message created:  ${JSON.stringify(threadResponse)}`);

// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
console.log(`Run created:  ${JSON.stringify(runResponse)}`);

// Get the messages
const runMessages: MessagesPage =
  await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    // types are: "image_file" or "text"
    if (item.type === "text") {
      console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
    }
  }
}

Per usare la chiave del servizio per l'autenticazione, è possibile creare ed eseguire un assistente con il modulo TypeScript seguente (index.ts):

import "dotenv/config";
import { AzureOpenAI } from "openai";
import {
  Assistant,
  AssistantCreateParams,
  AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";

// Get environment variables
const azureOpenAIKey = process.env.AZURE_OPENAI_KEY as string;
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
  .AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;

// Check env variables
if (!azureOpenAIKey || !azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
  throw new Error(
    "Please set AZURE_OPENAI_KEY and AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT_NAME in your environment variables."
  );
}

// Get Azure SDK client
const getClient = (): AzureOpenAI => {
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: openAIVersion,
    apiKey: azureOpenAIKey,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options: AssistantCreateParams = {
  model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

// Create an assistant
const assistantResponse: Assistant =
  await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);

// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);

// Add a user question to the thread
const threadResponse: Message =
  await assistantsClient.beta.threads.messages.create(assistantThread.id, {
    role,
    content: message,
  });
console.log(`Message created:  ${JSON.stringify(threadResponse)}`);

// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
console.log(`Run created:  ${JSON.stringify(runResponse)}`);

// Get the messages
const runMessages: MessagesPage =
  await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    // types are: "image_file" or "text"
    if (item.type === "text") {
      console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
    }
  }
}

Output

Assistant created: {"id":"asst_zXaZ5usTjdD0JGcNViJM2M6N","createdAt":"2024-04-08T19:26:38.000Z","name":"Math Tutor","description":null,"model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"fileIds":[],"metadata":{}}
Thread created: {"id":"thread_KJuyrB7hynun4rvxWdfKLIqy","createdAt":"2024-04-08T19:26:38.000Z","metadata":{}}
Message created:  {"id":"msg_o0VkXnQj3juOXXRCnlZ686ff","createdAt":"2024-04-08T19:26:38.000Z","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","role":"user","content":[{"type":"text","text":{"value":"I need to solve the equation `3x + 11 = 14`. Can you help me?","annotations":[]},"imageFile":{}}],"assistantId":null,"runId":null,"fileIds":[],"metadata":{}}
Created run
Run created:  {"id":"run_P8CvlouB8V9ZWxYiiVdL0FND","object":"thread.run","status":"queued","model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"metadata":{},"usage":null,"assistantId":"asst_zXaZ5usTjdD0JGcNViJM2M6N","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","fileIds":[],"createdAt":"2024-04-08T19:26:39.000Z","expiresAt":"2024-04-08T19:36:39.000Z","startedAt":null,"completedAt":null,"cancelledAt":null,"failedAt":null}
Message content: "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
Message content: "Yes, of course! To solve the equation \\( 3x + 11 = 14 \\), we can follow these steps:\n\n1. Subtract 11 from both sides of the equation to isolate the term with x.\n2. Then, divide by 3 to find the value of x.\n\nLet me calculate that for you."
Message content: "I need to solve the equation `3x + 11 = 14`. Can you help me?"

È importante ricordare che, benché l'interprete di codice offra al modello la possibilità di rispondere a query più complesse convertendo le domande in codice ed eseguendo tale codice in modo iterativo in JavaScript fino a quando non raggiunge una soluzione, è comunque necessario convalidare la risposta per verificare che il modello abbia convertito correttamente la domanda in una rappresentazione valida nel codice.

Pulire le risorse

Per pulire e rimuovere una risorsa OpenAI, è 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.

Codice di esempio

Vedi anche

Prerequisiti

Impostazione

Recuperare la chiave e l'endpoint

Per eseguire correttamente una chiamata a OpenAI di Azure, è necessario quanto segue:

Nome variabile Valore
ENDPOINT Questo valore è disponibile nella sezione Chiavi &ed endpoint durante l'esame della risorsa dalla portale di Azure. In alternativa, è possibile trovare il valore in OpenAI Studio di Azure>Playground>Visualizzazione codice. Un endpoint di esempio è https://docs-test-001.openai.azure.com/.
API-KEY Questo valore è disponibile nella sezione Chiavi ed endpoint durante l'esame della risorsa dalla portale di Azure. È possibile usare KEY1 o KEY2.
DEPLOYMENT-NAME Questo valore corrisponderà 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 OpenAI Studio di Azure.

Passare alla risorsa nel portale di Azure. Endpoint e Chiavi sono disponibili nella sezione Gestione risorse. Copiare l'endpoint e la chiave di accesso in base alle esigenze per l'autenticazione delle chiamate API. 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.

Screenshot del pannello di panoramica per una risorsa OpenAI di Azure nel portale di Azure con la posizione dell'endpoint e delle chiavi di accesso evidenziata in rosso.

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

Variabili di ambiente

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

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

REST API

Creare un assistente

Nota

Con OpenAI di Azure è necessario specificare il nome della distribuzione del modello per il parametro model. Se il nome della distribuzione del modello è diverso dal nome del modello sottostante, è necessario modificare il codice in "model": "{your-custom-model-deployment-name}".

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "name": "Math Assist",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-1106-preview"
  }'

Strumenti

Un singolo assistente può accedere a un massimo di 128 strumenti, tra cui code interpreter, nonché a qualsiasi strumento personalizzato creato tramite le funzioni.

Creare un thread

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d ''

Aggiungere una domanda utente al thread

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

Eseguire il thread

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Recuperare lo stato dell'esecuzione

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs/run_abc123 \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

Risposta dell'assistente

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

Informazioni sui risultati

In questo esempio viene creato un assistente con interprete di codice abilitato. Quando si pone all'assistente una domanda matematica, la domanda viene convertita in codice Python e viene eseguito il codice nell'ambiente sandbox per determinare la risposta alla domanda. Il codice che il modello crea e testa per arrivare a una risposta è:

    from sympy import symbols, Eq, solve  
      
    # Define the variable  
    x = symbols('x')  
      
    # Define the equation  
    equation = Eq(3*x + 11, 14)  
      
    # Solve the equation  
    solution = solve(equation, x)  
    solution

È importante ricordare che, benché l'interprete di codice offra al modello la possibilità di rispondere a query più complesse convertendo le domande in codice ed eseguendo tale codice in modo iterativo nella sandbox Python fino a quando non raggiunge una soluzione, è comunque necessario convalidare la risposta per verificare che il modello abbia convertito correttamente la domanda in una rappresentazione valida nel codice.

Pulire le risorse

Per pulire e rimuovere una risorsa OpenAI, è 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.

Vedi anche