Tutorial sull'API Assistants di OpenAI

L'OpenAI Dev Day ha segnato una tappa importante nell'intelligenza artificiale, presentando una suite di servizi IA innovativi, tra cui GPTs, il GPTs App Store, GPT-4 Turbo e la nuova Assistants API.

Questa API offre agli sviluppatori strumenti di IA avanzati per creare assistenti personalizzati in grado di gestire compiti diversi.

In questo tutorial entriamo nel mondo degli Assistants, esplorandone nel dettaglio le capacità, le applicazioni pratiche nei vari settori e fornendo una guida passo passo per implementarli in Python. Seguici mentre affrontiamo le complessità di costruire il tuo assistente IA personalizzato.

Panoramica dell'Assistants API

Al momento della stesura di questo articolo, l'Assistants API è in beta e il team di sviluppo di OpenAI sta lavorando attivamente per includere più funzionalità; prima di allora, però, vediamo cosa offre l'attuale versione!

Questa sezione approfondisce come funzionano gli Assistants e l'interazione tra i componenti sottostanti.

Come funziona l'Assistants API?

I due pilastri principali degli Assistants sono i modelli e gli strumenti di OpenAI.

• C'è un set diversificato di modelli tra cui, ma non solo: GPT-4, GPT-4 Turbo, GPT-3.5, GPT-3, DALL-E, TTS, Whisper, Embeddings, Moderation. Questi modelli sono usati dagli Assistants per svolgere uno specifico compito intelligente.

• Gli strumenti, invece, danno agli Assistants accesso a tool ospitati da OpenAI come Code Interpreter e Knowledge Retrieval. Consentono persino agli utenti di creare i propri strumenti usando la funzionalità di Function Calling.

Come funzionano gli Assistants

Ora vediamo i cinque passaggi principali coinvolti nell'implementazione di un Assistant.

• Crea e descrivi un Assistant: un Assistant è un'IA specializzata sviluppata usando modelli, linee guida e vari strumenti.
• Avvia un Thread: un thread rappresenta una sequenza di dialogo avviata dall'utente in cui si possono aggiungere messaggi, dando forma a uno scambio coinvolgente.
• Aggiungi messaggi: i messaggi comprendono gli input testuali dell'utente e possono includere testo, file e immagini.
• Attiva l'Assistant: l'Assistant viene attivato per analizzare il Thread, utilizzare gli strumenti necessari e produrre una risposta adeguata.

Casi d'uso dell'Assistants API nei settori

Sfruttare la Assistant API può essere un modo potente per integrare l'IA in vari processi aziendali, migliorando l'efficienza, automatizzando compiti noiosi e fornendo risposte più rapide e accurate alle domande degli utenti.

Di seguito cinque casi d'uso convincenti dell'Assistant API nei vari settori.

Supporto allo sviluppo

L'Assistant può fungere da assistente alla programmazione on-demand. Usando il code interpreter, può tradurre snippet di codice da un linguaggio all'altro, supportando lo sviluppo software e rendendo più agevole l'apprendimento di nuovi linguaggi. Questa funzione è particolarmente utile per team che lavorano con più linguaggi o in contesti educativi per insegnare a programmare.

Gestione della conoscenza in azienda

La funzione di retrieval può essere sfruttata per la gestione della conoscenza all'interno delle organizzazioni. Caricando ed elaborando documenti, report e manuali interni, l'Assistant diventa un repository centralizzato di conoscenza. I dipendenti possono interrogarlo per informazioni specifiche, migliorando l'efficienza e riducendo il tempo speso a cercare in grandi insiemi di documenti.

Automazione del supporto clienti

L'Assistant può essere integrato nei sistemi di assistenza clienti. Usando il function calling, può rispondere alle richieste recuperando informazioni da API esterne o database, automatizzando di fatto le risposte alle domande più comuni. Questa integrazione può migliorare l'esperienza del cliente fornendo risposte rapide e accurate e riducendo il carico sul personale umano.

Analisi dei dati

Descrivendo funzioni per l'analisi dei dati, gli utenti possono chiedere all'Assistant di effettuare complesse manipolazioni dei dati e generare report, traducendo richieste in linguaggio naturale in task strutturati di analisi.

Automazione delle operazioni IT

I team IT possono usare l'Assistant per automatizzare le operazioni di routine. Definendo funzioni che corrispondono a compiti IT comuni, come diagnostica di sistema, controlli di rete o aggiornamenti software, l'Assistant può eseguirli in risposta ai comandi degli utenti. Questa capacità può ridurre significativamente il tempo che i professionisti IT dedicano alla manutenzione ordinaria, permettendo loro di concentrarsi su problemi più complessi.

Hands-on: primi passi con l'Assistants API di OpenAI

Con questa comprensione dell'API di OpenAI, passiamo a un caso d'uso più pratico. Questa sezione ti guida nella creazione di un assistant che recupera conoscenza da file PDF.

Il notebook end-to-end completo è disponibile su DataLab.

Workflow di knowledge retrieval

Per qualsiasi implementazione tecnica, è meglio fornire un workflow visivo che illustri l'interazione tra i principali componenti dell'applicazione in sviluppo.

Questo workflow evidenzia i cinque passaggi principali dell'implementazione dell'assistant, dal caricamento dei file alla generazione della risposta finale.

Cinque passaggi principali del workflow di knowledge retrieval

• Caricamento dei file: il processo inizia con il caricamento dei PDF con cui gli utenti vogliono interagire.
• Creazione dell'assistant: l'assistant è progettato specificamente per elaborare e comprendere le informazioni dai PDF caricati.
• Avvia l'interazione: è il punto di partenza del thread di conversazione, in cui gli utenti forniscono messaggi di input da elaborare.
• Attiva l'assistant: a questo punto l'assistant elabora i messaggi di input per generare una risposta pertinente.
• Output della risposta: è la fase finale, in cui l'assistant mostra le risposte ai messaggi degli utenti.

Configura la OpenAI KEY

Gli strumenti principali necessari per riprodurre con successo i risultati di questo tutorial sono:

• Python: è il linguaggio di programmazione principale che useremo in questo tutorial. Un'alternativa è NodeJS.
• OpenAI: il pacchetto per interagire con i servizi OpenAI. Il nostro cheatsheet OpenAI API in Python offre una panoramica completa per padroneggiare le basi dell'uso dell'OpenAI API.
• OS: il pacchetto del sistema operativo per configurare la variabile d'ambiente.

Il primo passo è ottenere la OpenAI KEY, che consente l'accesso al modello DALL-E 3. I passaggi principali sono illustrati di seguito:

Quattro passaggi principali per creare una OpenAI KEY

I quattro passaggi sopra sono autoesplicativi. È comunque importante creare un account dal sito ufficiale di OpenAI.

Puoi esplorare ulteriormente l'OpenAI API con la nostra Guida per principianti all'OpenAI API: tutorial pratico e best practice. Ti introduce all'OpenAI API, ai suoi casi d'uso, a un approccio hands-on e a tutte le best practice da seguire.

Inizia a costruire l'assistant

Una volta ottenuta la KEY, assicurati di non condividerla con nessuno. La chiave deve rimanere privata. Poi impostala come variabile d'ambiente come segue per poterla utilizzare:

import os
OPENAI_API_KEY= "<YOUR PRIVATE KEY>"
os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY

Caricamento dei file

La funzione helper seguente sfrutta la funzione "create" per caricare automaticamente sul proprio account OpenAI il file con cui gli utenti vogliono interagire.

La funzione "create" ha due parametri principali:

• Il percorso del file da caricare
• Lo scopo d'uso del file, che in questo caso è "assistants"

def upload_file(file_path):
    
	# Upload a file with an "assistants" purpose
	file_to_upload = client.files.create(
  	file=open(file_path, "rb"),
  	purpose='assistants'
	)
     return file_to_upload

La funzione helper viene infine utilizzata per avviare il processo di caricamento del paper sui transformer presente nella cartella data.

transformer_paper_path = "./data/transformer_paper.pdf"
file_to_upload = upload_file(transformer_paper_path)

Dopo l'esecuzione corretta della funzione, il file transformer_paper.pdf viene caricato ed è visibile dalla scheda Files, come mostrato di seguito.

Paper sui transformer caricato sull'account OpenAI

Creazione dell'assistant

La creazione dell'assistant avviene usando la funzione create del modulo client.beta.assistants e richiede cinque parametri principali:

• Nome: è il nome dato all'assistant dal suo creatore. Chiamiamo il nostro Scientific Paper Assistant.
• Istruzioni: descrivono come l'assistant deve comportarsi o rispondere alle domande. In questo caso d'uso, l'assistant applica la seguente istruzione: "You are a polite and expert knowledge retrieval assistant. Use the documents provided as a knowledge base to answer questions."
• Modello: il modello sottostante da usare per il knowledge retrieval. Si possono usare modelli GPT-3 o GPT-4. Questo articolo sfrutta il modello più recente al momento della stesura, ovvero gpt-4-1106-preview.
• Strumenti: il tipo di strumento da utilizzare. Le due scelte possibili sono code interpreter e retrieval. Il focus di questo articolo è il retrieval, quindi ignoriamo l'interpreter.
• File_ids: un elenco di identificatori univoci di ciascun file nella knowledge base.

La funzione helper create_assistant combina tutte queste informazioni per creare l'assistant come illustrato di seguito:

def create_assistant(assistant_name,
                 	my_instruction,
                 	uploaded_file,
                 	model="gpt-4-1106-preview"):
    
	my_assistant = client.beta.assistants.create(
	name = assistant_name,
	instructions = my_instruction,
	model="gpt-4-1106-preview",
	tools=[{"type": "retrieval"}],
	file_ids=[uploaded_file.id]
	)
    
	return my_assistant

Ora possiamo eseguire la funzione per creare l'assistant usando l'istruzione e il nome dell'assistant:

inst="You are a polite and expert knowledge retrieval assistant. Use the documents provided as a knowledge base to answer questions"
assistant_name="Scientific Paper Assistant"

my_assistant = create_assistant(assistant_name, inst, uploaded_file)

Avvia l'interazione

Una volta creato l'assistant, il passo successivo naturale è avviare un thread di interazione usando il messaggio o la richiesta degli utenti.

Il thread e il messaggio sono creati usando le funzioni create dei moduli client.beta.threads e client.beta.threads.messages rispettivamente.

Queste due funzionalità sono combinate nella funzione helper initiate_interaction.

def initiate_interaction(user_message, uploaded_file):
    
	my_thread = client.beta.threads.create()
	message = client.beta.threads.messages.create(thread_id=my_thread.id,
                                              	role="user",
                                              	content=user_message,
                                              	file_ids=[uploaded_file.id]
	)
    
	return my_thread

Si può avviare un'interazione a partire dalla variabile user_message:

user_message = "Why do authors use the self-attention strategy in the paper?"
my_thread = initiate_interaction(user_message, uploaded_file)

Attiva l'assistant e genera una risposta

Dal thread sopra, è possibile attivare l'assistant per fornire una risposta al messaggio dell'utente. L'azione di attivazione è definita nella funzione helper trigger_assistant e la risposta è fornita dalla variabile response.

def trigger_assistant():
	run = client.beta.threads.runs.create(
  	thread_id = my_thread.id,
  	assistant_id = my_assistant.id,
	)


trigger_assistant()

messages = client.beta.threads.messages.list(
  thread_id = my_thread.id
)

response = messages.data[0].content[0].text.value
response

La seguente risposta viene generata dopo l'esecuzione corretta del codice sopra.

Risposta dell'assistant al messaggio dell'utente

Questa risposta è esattamente quanto riportato dagli autori come risposta alla domanda a pagina 6.

Passaggio che menziona la risposta dal paper sui transformer

Best practice per usare l'Assistants API di OpenAI

Quando integri la Assistant API in un progetto, è importante attenersi alle best practice per garantire prestazioni ottimali e una buona esperienza utente. Ecco alcuni punti chiave da considerare.

• Definisci obiettivi chiari: stabilisci traguardi specifici per l'Assistant per assicurarti che soddisfi efficacemente lo scopo previsto e le esigenze degli utenti.

• Ottimizza i dati in input: la qualità e la pertinenza dei dati usati, come i file caricati, sono cruciali per l'accuratezza e l'efficienza delle risposte dell'Assistant.

• Dai priorità alla privacy degli utenti: implementa solidi protocolli di protezione dei dati per tutelare le informazioni degli utenti e rispettare le normative vigenti.

• Testa e iteri: prova regolarmente l'Assistant in scenari reali e itera in base ai feedback per migliorare prestazioni ed esperienza d'uso.

• Fornisci documentazione chiara: offri indicazioni complete sull'uso dell'Assistant, aiutando gli utenti a comprenderne funzionalità e limiti.


Conclusione

In sintesi, questo articolo ha esplorato l'Assistants API, evidenziando come funziona e come può essere utilizzata in diversi settori. Abbiamo iniziato presentando l'API e le sue funzioni chiave, ponendo le basi per una comprensione più profonda.

Abbiamo poi esaminato le funzionalità specifiche dell'Assistants API e discusso come possano essere applicate in vari ambiti aziendali, mostrando la sua ampia utilità.

Abbiamo anche fornito una guida passo passo per iniziare a usare l'Assistants API, semplificando l'impostazione in base alle tue esigenze.

Inoltre, abbiamo condiviso alcune importanti best practice da tenere a mente durante l'uso dell'API, così da ottenere il massimo.

In breve, l'Assistants API è uno strumento versatile e prezioso, adattabile a molti utilizzi e in grado di offrire benefici significativi a chi impara a usarla in modo efficace.

Vuoi fare un salto di qualità con le API di OpenAI e adottare un approccio più creativo? La nostra Guida completa all'API di DALL-E 3 ti aiuterà a scoprire il potere trasformativo dell'API DALL-E 3, coprendone le funzionalità principali, le applicazioni nei vari settori e i consigli per sprigionare il tuo potenziale creativo.

Se sei alle primissime armi, perché non iniziare con il nostro corso Working with the OpenAI API.