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

Prerequisiti

• Una sottoscrizione di Azure: crearne una gratuitamente.
• Una risorsa dell'hub di Azure per intelligenza artificiale con un modello distribuito. Per altre informazioni sulla distribuzione del modello, vedere la guida alla distribuzione delle risorse.
• Un progetto di Azure per intelligenza artificiale in Studio AI della piattaforma Azure.

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 10.000 file, con dimensioni massime di 512 MB, da usare con gli strumenti. Non usato in questa guida introduttiva.

   

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.

   

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.
    

    

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

• Azure portal
• Interfaccia della riga di comando di Azure

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

Vedi anche

• Per altre informazioni su come usare gli assistenti, vedere la guida pratica sugli assistenti.
• Esempi di API degli assistenti OpenAI di Azure

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

Prerequisiti

• Una sottoscrizione di Azure: creare un account gratuitamente
• Python 3.8 o versioni successive
• Le librerie Python seguenti: os, openai (è necessaria la versione 1.x)
• Interfaccia della riga di comando di Azure usata per l'autenticazione senza password in un ambiente di sviluppo locale, creare il contesto necessario eseguendo l'accesso tramite l'interfaccia della riga di comando di Azure.
• Una risorsa di OpenAI di Azure con un modello compatibile in un'area supportata.
• È consigliabile esaminare la nota sulla trasparenza dell'intelligenza artificiale responsabile e altre risorse di intelligenza artificiale responsabile per acquisire familiarità con le funzionalità e le limitazioni del servizio OpenAI di Azure.
• In questo esempio è stata usata una risorsa OpenAI di Azure con il modello distribuito gpt-4 (1106-preview).

È consigliabile eseguire l'autenticazione senza password

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

2. Per l'autenticazione senza password consigliata:

pip install azure-identity

Recuperare la chiave e l'endpoint

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

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.

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" 

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')
[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

export AZURE_OPENAI_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE"
export AZURE_OPENAI_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE"

Creare un assistente

Nel codice verranno specificati i valori 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.

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 completa con stato: completed

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

• Azure portal
• Interfaccia della riga di comando di Azure

Vedi anche

• Per altre informazioni su come usare gli assistenti, vedere la guida pratica sugli assistenti.
• Esempi di API degli assistenti OpenAI di Azure

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

Prerequisiti

• Una sottoscrizione di Azure: creare un account gratuitamente
• L’SDK .NET 8
• Una risorsa di OpenAI di Azure con un modello compatibile in un'area supportata.
• È consigliabile esaminare la nota sulla trasparenza dell'intelligenza artificiale responsabile e altre risorse di intelligenza artificiale responsabile per acquisire familiarità con le funzionalità e le limitazioni del servizio OpenAI di Azure.
• In questo esempio è stata usata una risorsa OpenAI di Azure con il modello distribuito gpt-4 (1106-preview).

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.

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.

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" 

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')
[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

export AZURE_OPENAI_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE"
export AZURE_OPENAI_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE"

Creare un assistente

Nel codice verranno specificati i valori 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.

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.

• Azure portal
• Interfaccia della riga di comando di Azure

Vedi anche

• Per altre informazioni su come usare gli assistenti, vedere la guida pratica sugli assistenti.
• Esempi di API degli assistenti OpenAI di Azure

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

Prerequisiti

• Una sottoscrizione di Azure: creare un account gratuitamente
• Node.js LTS con supporto TypeScript o ESM.
• Interfaccia della riga di comando di Azure usata per l'autenticazione senza password in un ambiente di sviluppo locale, creare il contesto necessario eseguendo l'accesso tramite l'interfaccia della riga di comando di Azure.
• Una risorsa di OpenAI di Azure con un modello compatibile in un'area supportata.
• È consigliabile esaminare la nota sulla trasparenza dell'intelligenza artificiale responsabile e altre risorse di intelligenza artificiale responsabile per acquisire familiarità con le funzionalità e le limitazioni del servizio OpenAI di Azure.
• In questo esempio è stata usata una risorsa OpenAI di Azure con il modello distribuito gpt-4 (1106-preview).

È consigliabile eseguire l'autenticazione senza password

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:

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.

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" 

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')
[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

export AZURE_OPENAI_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE"
export 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 mostrato nel portale di Azure.
• OPENAI_API_VERSION: altre informazioni sulle versioni dell'API.

setx AZURE_OPENAI_DEPLOYMENT_NAME "REPLACE_WITH_YOUR_DEPLOYMENT_NAME" 
setx OPENAI_API_VERSION "REPLACE_WITH_YOUR_API_VERSION" 

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_DEPLOYMENT_NAME', 'REPLACE_WITH_YOUR_DEPLOYMENT_NAME', 'User')
[System.Environment]::SetEnvironmentVariable('OPENAI_API_VERSION', 'REPLACE_WITH_YOUR_API_VERSION', 'User')

export AZURE_OPENAI_DEPLOYMENT_NAME="REPLACE_WITH_YOUR_DEPLOYMENT_NAME"
export OPENAI_API_VERSION="REPLACE_WITH_YOUR_API_VERSION"

Creare un assistente

Nel codice verranno specificati i valori 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.

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)}`);
    }
  }
}

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)}`);
    }
  }
}

import "dotenv/config";
import { AzureOpenAI } from "openai";

// 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;
const azureOpenAIDeployment = process.env.AZURE_OPENAI_DEPLOYMENT_NAME;
const azureOpenAIVersion = process.env.OPENAI_API_VERSION;

// Check env variables
if (!azureOpenAIEndpoint || !azureOpenAIDeployment || !azureOpenAIVersion) {
  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 = () => {
  const credential = new DefaultAzureCredential();
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: azureOpenAIVersion,
    azureADTokenProvider,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options = {
  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" }],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

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

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

// Add a user question to the thread
const threadResponse = 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 = 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 = 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)}`);
    }
  }
}

import "dotenv/config";
import { AzureOpenAI } from "openai";

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

// Check env variables
if (!azureOpenAIKey || !azureOpenAIEndpoint || !azureOpenAIDeployment || !azureOpenAIVersion) {
  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 = () => {
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: azureOpenAIVersion,
    apiKey: azureOpenAIKey,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options = {
  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" }],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

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

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

// Add a user question to the thread
const threadResponse = 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 = 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 = 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.

• Azure portal
• Interfaccia della riga di comando di Azure

Codice di esempio

• Codice di avvio rapido di esempio

Vedi anche

• Per altre informazioni su come usare gli assistenti, vedere la guida pratica sugli assistenti.
• Esempi di API degli assistenti OpenAI di Azure

Prerequisiti

• Una sottoscrizione di Azure: creare un account gratuitamente
• Python 3.8 o versioni successive
• Una risorsa di OpenAI di Azure con un modello compatibile in un'area supportata.
• È consigliabile esaminare la nota sulla trasparenza dell'intelligenza artificiale responsabile e altre risorse di intelligenza artificiale responsabile per acquisire familiarità con le funzionalità e le limitazioni del servizio OpenAI di Azure.
• In questo esempio è stata usata una risorsa OpenAI di Azure con il modello distribuito gpt-4 (1106-preview).

Impostazione

Recuperare la chiave e l'endpoint

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

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.

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" 

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')
[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

export AZURE_OPENAI_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE"
export AZURE_OPENAI_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE"

REST API

Creare un assistente

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.

• Azure portal
• Interfaccia della riga di comando di Azure

Vedi anche

• Per altre informazioni su come usare gli assistenti, vedere la guida pratica sugli assistenti.
• Esempi di API degli assistenti OpenAI di Azure