1. Introduzione all'API degli assistenti di OpenAI

1.1 Definizione e Scopo dell'API degli assistenti

L'API degli assistenti consente ai sviluppatori di costruire assistenti di intelligenza artificiale all'interno delle proprie applicazioni. Definendo comandi personalizzati e selezionando modelli, gli assistenti possono utilizzare modelli, strumenti e conoscenze per rispondere alle richieste degli utenti. Attualmente, l'API degli assistenti supporta tre tipi di strumenti: Interprete di codice, Recupero e Chiamata di funzione.

1.2 Applicazioni dell'API degli assistenti

L'API degli assistenti è adatta a vari scenari che richiedono supporto interattivo dell'IA. Ad esempio:

  • Supporto clienti: Rispondere automaticamente alle domande comuni per ridurre il carico di lavoro del servizio clienti umano.
  • Educazione online: Rispondere alle domande degli studenti e fornire supporto personalizzato all'apprendimento.
  • Analisi dei dati: Analizzare i file dati caricati dagli utenti, generare report e visualizzare grafici.
  • Raccomandazioni personalizzate: Fornire suggerimenti e servizi personalizzati basati sulle interazioni storiche degli utenti.

1.3 Concetti fondamentali degli assistenti

Gli oggetti fondamentali dell'API degli assistenti includono Assistente, Thread e Messaggio. Di seguito sono presenti introduzioni dettagliate su questi oggetti e le loro funzioni:

Assistente

L'oggetto Assistente è costruito sopra i modelli OpenAI e può chiamare gli strumenti degli assistenti di intelligenza artificiale. È possibile personalizzare le istruzioni dell'Assistente per adattarne la personalità e la funzionalità. Ad esempio, è possibile creare un Assistente chiamato "Analista dei dati" che analizza i dati e genera grafici utilizzando lo strumento "code_interpreter".

Thread

L'oggetto Thread rappresenta la sessione di conversazione tra l'utente e l'Assistente. È possibile creare un Thread per ciascun utente e aggiungere messaggi ad esso quando l'utente interagisce con l'Assistente. L'oggetto Thread memorizza efficacemente la cronologia dei messaggi e tronca i messaggi quando necessario per rispettare il limite di lunghezza del contesto del modello.

Messaggio

L'oggetto Messaggio può essere creato dall'utente o dall'Assistente. I messaggi possono contenere testo, immagini e altri file. I messaggi sono memorizzati come elenco nel Thread. Nell'uso effettivo dell'API, i sviluppatori possono aggiungere messaggi dell'utente al Thread e attivare la risposta dell'Assistente come necessario.

Esecuzione

L'oggetto Run rappresenta l'esecuzione di una richiesta dell'assistente, chiamando l'assistente in base al contenuto del messaggio nel Thread. L'assistente utilizza la propria configurazione e i messaggi del Thread per eseguire compiti chiamando modelli e strumenti. Come parte dell'esecuzione, l'assistente aggiunge messaggi al thread.

2. Processo di sviluppo dell'API degli assistenti

2.1 Creare il tuo Assistente

Per creare un Assistente, è necessario inviare una richiesta all'API con istruzioni, nome del modello e configurazione degli strumenti. Ecco un semplice esempio di creazione di un assistente personale per matematica:

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Sei un tutor di matematica personale. Scrivi ed esegui codice per rispondere a domande di matematica.",
    "name": "Tutor di Matematica",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4"
  }'

Parametri dell'API:

  • instructions - istruzioni di sistema che indicano all'assistente cosa fare.
  • name - il nome dell'assistente.
  • tools - definisce quali strumenti può utilizzare l'assistente. Ogni assistente può avere fino a 128 strumenti. I tipi di strumento attuali possono essere code_interpreter, retrieval o function.
  • model - quale modello dovrebbe utilizzare l'assistente?

Dopo aver creato con successo l'Assistente, si riceverà un ID dell'Assistente.

2.2 Creare un Thread di sessione

Un Thread rappresenta una conversazione e consigliamo di creare un Thread di sessione per ciascun utente quando inizia una conversazione. È possibile creare un Thread come segue:

curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d ''

Dopo aver creato il Thread, si riceverà un ID del Thread.

2.3 Aggiungere messaggi al thread

Puoi aggiungere messaggi a un thread specifico, che contengono testo e facoltativamente consentono l'invio di file da parte dell'utente. Ad esempio:

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer LA_TUA_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "Devo risolvere questa equazione `3x + 11 = 14`. Puoi aiutarmi?"
    }'

Parametri dell'API:

  • thread_id - rappresenta l'ID del thread di conversazione, che puoi ottenere quando crei il thread.

Il corpo della richiesta API è un messaggio dell'utente, che di solito rappresenta la domanda dell'utente, simile alla struttura del messaggio del modello di conversazione.

2.4 Esegui l'Assistente per Generare una Risposta

Per far sì che l'assistente risponda ai messaggi dell'utente, è necessario creare una Run. Questo consente all'assistente di leggere il Thread e decidere se utilizzare gli strumenti (se abilitati) o semplicemente utilizzare il modello per rispondere al meglio alla query.

Nota: Fino a questo punto, l'assistente non ha risposto alla domanda dell'utente. Solo chiamando l'API Run l'assistente risponderà alla domanda dell'utente.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer LA_TUA_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "ID_dell'assistente",
    "instructions": "Rivolgersi all'utente come Jane Doe. L'utente è un account premium."
  }'

Parametri dell'API:

  • thread_id - rappresenta l'ID del thread di conversazione, che puoi ottenere quando crei il thread.
  • assistant_id - rappresenta l'ID dell'assistente, che puoi ottenere quando crei l'assistente.
  • instructions - istruzioni dell'assistente che possono sovrascrivere le istruzioni impostate durante la creazione dell'assistente.

Una richiesta API riuscita restituirà un ID della Run.

2.5 Verifica dello Stato di Esecuzione dell'Assistente

Dopo aver avviato un'attività (Run) nell'assistente, l'esecuzione dell'attività è asincrona. Ciò significa che è necessario verificare regolarmente lo stato della Run per determinare se è stata completata. Per controllare lo stato della Run, può essere effettuata una richiesta HTTP utilizzando CURL. Di seguito è riportata una specifica introduzione a questo processo.

Esempio di Richiesta CURL:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Spiegazione dei Parametri dell'API:

  • https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123: Questo è l'URL della richiesta dell'API, dove thread_abc123 è l'identificatore univoco del thread (Thread) e run_abc123 è l'identificatore univoco della Run.

Esempio del Corpo della Risposta:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "completed",
  "created_at": 1699073585,
  ...
}

Spiegazione dei Parametri della Risposta dell'API:

  • id: L'identificatore univoco della Run.
  • object: Indica il tipo dell'oggetto restituito, che in questo caso è thread.run.
  • status: Lo stato della Run, i valori possibili includono in coda, in corso, completato, richiede azione, fallito, ecc.
  • created_at: Il timestamp di quando la Run è stata creata.

2.6 Ottenere i Risultati della Risposta dell'Assistente

Dopo che la Run dell'Assistente è completata, è possibile leggere i risultati della risposta dell'Assistente controllando i messaggi aggiunti al thread (Thread). Di seguito è illustrato come effettuare la richiesta tramite CURL e una spiegazione dettagliata dei parametri dell'API.

Suggerimento: Similmente a una conversazione con un Assistente, quando l'Assistente ha finito di elaborare la query dell'utente, l'Assistente aggiornerà un messaggio al thread di conversazione (Thread). Pertanto, sarà sufficiente interrogare l'ultimo messaggio nel thread di conversazione (Thread) per ottenere la risposta dell'Assistente.

Esempio di Richiesta CURL:

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Spiegazione dei parametri dell'API:

  • https://api.openai.com/v1/threads/thread_abc123/messages: L'URL della richiesta dell'API, dove thread_abc123 è l'identificatore univoco del thread (Thread).
  • Come nelle intestazioni della richiesta utilizzate per controllare lo stato di esecuzione in precedenza, includendo informazioni di autenticazione e informazioni sulla versione dell'API.

Esempio di risultato della risposta dell'Assistente:

In questo esempio, l'utente ha posto all'Assistente una domanda di matematica, e l'Assistente ha aggiunto un messaggio di risposta al Thread dopo averla elaborata.

Utente: Devo risolvere l'equazione `3x + 11 = 14`. Puoi aiutarmi?
Assistente: Certo, Jane Doe. Per risolvere l'equazione `(3x + 11 = 14)`, devi isolare `(x)` su un lato dell'equazione. Lascia che calcoli il valore di `(x)` per te.
Assistente: La soluzione dell'equazione `(3x + 11 = 14)` è `(x = 1)`.

Dopo aver ottenuto i risultati della risposta dall'Assistente, possono essere presentati all'utente per aiutarli a comprendere e utilizzare meglio i servizi forniti dall'Assistente.

3. Strumenti: Strumenti Integrati Forniti da OpenAI

3.1 Strumento Interprete di Codice

Il tool Interprete di Codice consente all'API degli Assistenti di scrivere ed eseguire codice Python in un ambiente di esecuzione sandbox. Questo strumento può gestire vari formati di dati e file e generare file con dati e immagini grafiche. L'Interprete di Codice consente al tuo Assistente di eseguire in modo iterativo il codice per risolvere problemi complessi di codifica e matematica. Quando il codice scritto dall'Assistente non riesce ad eseguire, può iterare questo codice tentando codici diversi fino a quando il codice viene eseguito con successo.

Abilitazione dell'Interprete di Codice

Per abilitare l'Interprete di Codice, passa code_interpreter nel parametro tools durante la creazione dell'oggetto Assistente:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Sei un tutor di matematica personale. Quando ti viene posta una domanda di matematica, scrivi ed esegui il codice per rispondere.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

Successivamente, il modello deciderà quando invocare l'Interprete di Codice in fase di esecuzione in base alla natura della richiesta dell'utente. Puoi facilitare questo comportamento attraverso le istruzioni dell'Assistente (ad esempio, "Scrivi il codice per risolvere questo problema").

Utilizzo dell'Interprete di Codice per Elaborare File

L'Interprete di Codice può analizzare i dati dai file. Questo è utile quando vuoi fornire una grande quantità di dati all'Assistente o consentire ai tuoi utenti di caricare i propri file per l'analisi. Nota che i file caricati per l'Interprete di Codice non verranno indicizzati per il recupero. Per informazioni dettagliate su come indicizzare i file per il recupero, consulta la sezione Strumento di Recupero di seguito.

I file passati a livello di Assistente possono essere accessibili a tutte le Esecuzioni associate a questo Assistente:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/mydata.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Sei un tutor di matematica personale. Quando ti viene posta una domanda di matematica, scrivi ed esegui il codice per rispondere.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

Lettura di Immagini e File Generati dall'Interprete del Codice

L'Interprete del Codice può anche produrre file nell'API, come la generazione di grafici, file CSV e PDF. Ci sono due tipi di file generati: immagini e file di dati (ad esempio, un file CSV con dati generati dall'Assistente).

Quando l'Interprete del Codice produce un'immagine, è possibile trovare e scaricare questo file nel campo file_id della risposta del Messaggio dell'Assistente:

{
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_abc123",
    "role": "assistant",
    "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  // ...
}

3.2 Strumento di Recupero

Lo Strumento di Recupero potenzia le capacità dell'Assistente aggiungendo conoscenze esterne al modello (come informazioni su prodotti proprietari o documenti forniti dall'utente). Una volta caricato il file e passato all'Assistente, OpenAI slicerà automaticamente, indizzerà, memorizzerà embeddamenti del tuo documento e implementerà la ricerca vettoriale per recuperare contenuti rilevanti per rispondere alle richieste dell'utente.

Abilita il Recupero

Per abilitare il recupero nel parametro tools dell'Assistente, passa retrieval:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Sei un chatbot per il supporto clienti. Utilizza la tua base di conoscenze per rispondere in modo efficace alle domande dei clienti.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

Carica File per il Recupero

Analogamente all'Interprete del Codice, i file possono essere caricati a livello di Assistente o a livello di Singolo Messaggio.

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/percorso/a/conoscenze.pdf"

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Sei un chatbot per il supporto clienti. Utilizza la tua base di conoscenze per rispondere in modo efficace alle domande dei clienti.",
    "name": "Tutor di Matematica",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
    "file_ids": ["file_123abc456"]
  }'

3.3 Strumento di Chiamata alle Funzioni

Analogamente all'API di Completamento delle Chat, l'API degli Assistenti supporta la chiamata alle funzioni. La chiamata alle funzioni ti consente di descrivere le funzioni all'Assistente e restituire in modo intelligente la funzione da chiamare insieme ai suoi parametri. Quando viene eseguita una chiamata a una funzione, l'API degli Assistenti metterà in pausa l'esecuzione e potrai fornire il risultato della chiamata alla funzione per continuare l'esecuzione.

Definire le funzioni

Quando si crea un Assistente, è possibile definire un insieme di funzioni affinché l'assistente le utilizzi. Queste funzioni devono essere specificate esplicitamente durante la creazione dell'oggetto assistente. Ogni funzione dovrebbe avere un nome univoco, una descrizione e una specifica dei parametri.

Il seguente codice mostra come definire due funzioni utilizzando il comando curl durante la creazione di un assistente:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Sei un bot per le previsioni del tempo. Utilizza le funzioni fornite per rispondere alle domande.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "Ottieni le condizioni meteorologiche per una posizione specifica",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Città e stato, ad esempio, San Francisco, CA"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "Ottieni il soprannome per una città",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Città e stato, ad esempio, San Francisco, CA"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

Lettura delle funzioni chiamate dall'Assistente

Quando un utente invia un messaggio all'assistente e il contenuto del messaggio attiva una chiamata alla funzione, è necessario leggere le informazioni di questa chiamata alla funzione. Durante questo processo, l'assistente genererà una esecuzione con stato requires_action. A questo punto, è possibile recuperare l'oggetto Esecuzione per ottenere informazioni dettagliate sulla chiamata della funzione.

Ecco un esempio di recupero dell'oggetto Esecuzione, che mostra come ottenere le informazioni delle chiamate alle funzioni:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"San Francisco\"}"
          }
        },
        {
          "id": "call_abc456",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"Los Angeles\"}"
          }
        }
      ]
    }
  },
  ...
}

Il parametro tool_calls contiene le informazioni della chiamata alla funzione e è sufficiente chiamare la funzione corrispondente nel proprio programma locale.

Invio degli output delle funzioni

Dopo aver eseguito la chiamata alla funzione localmente e ottenuto i risultati, è necessario inviare questi risultati all'assistente Assistants in modo che l'assistente possa continuare a elaborare la richiesta dell'utente. Quando si inviano gli output delle funzioni, è necessario assicurarsi che gli output siano associati alle chiamate alle funzioni originali.

Ecco un esempio di codice su come inviare i risultati degli output delle funzioni:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_123/submit_tool_outputs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "{\"temperature\": \"22\", \"unit\": \"celsius\"}"
      }, 
      {
        "tool_call_id": "call_abc456",
        "output": "{\"nickname\": \"LA\"}"
      }
    ]
  }'

Spiegazione dei parametri:

  • thread_abc123 rappresenta l'ID del thread di conversazione
  • run_123 rappresenta l'ID dell'oggetto Esecuzione
  • tool_call_id rappresenta l'ID di una specifica chiamata alla funzione, che è ottenuto dal parametro tool_calls precedente.

Dopo aver inviato con successo tutti gli output delle funzioni, lo stato dell'oggetto Esecuzione verrà nuovamente aggiornato e l'assistente continuerà l'elaborazione e restituirà la risposta finale all'utente.