Come usare GPT-4o Audio Preview con LangChain e ChatOpenAI

Ambiente virtuale e dipendenze

Prima di usare il modello gpt-4o-audio-preview di OpenAI, configuriamo un ambiente virtuale per il progetto. Mantiene tutto ordinato ed evita conflitti di dipendenze, cosa particolarmente utile quando lavori su più progetti.

Cos'è un ambiente virtuale?

Immagina di avere due progetti diversi. Uno richiede la versione 1.0 di un pacchetto, mentre l'altro ha bisogno della 2.0. Se installi tutto a livello globale, finirai per avere conflitti.

Gli ambienti virtuali creano uno spazio di lavoro isolato, una sorta di bolla, in cui puoi installare ciò che ti serve per un progetto specifico. Quando crei un ambiente per il tuo progetto, non devi più preoccuparti di rovinare l'installazione di Python del sistema o di avere pacchetti in conflitto.

Creare e attivare l'ambiente virtuale

Iniziamo creando un ambiente virtuale per il nostro progetto. Useremo il modulo venv integrato in Python. Dovremo:

1. Andare nella cartella del progetto—è qui che vuoi che risieda l'ambiente. Se non hai ancora una cartella del progetto, creane una.
2. Una volta dentro la cartella, è il momento di creare l'ambiente virtuale. Su macOS o Linux, esegui python3 -m venv env. Su Windows, così: python -m venv env.
1. Nota che venv è lo strumento di Python per creare ambienti virtuali e env è il nome della cartella dell'ambiente. Puoi chiamarla come vuoi: env, venv, my_project_env, ecc. È buona pratica tenerlo breve e semplice
3. Ora che hai creato l'ambiente virtuale, è il momento di attivarlo. Questo passaggio è fondamentale perché assicura che i pacchetti che installerai riguarderanno solo questo progetto.
1. Su macOS o Linux, lo attivi con source env/bin/activate. Su Windows, usa: .\env\Scripts\activate

Noterai che il prompt del terminale cambia in qualcosa come env—è il segnale che stai lavorando dentro l'ambiente virtuale. D'ora in poi, i pacchetti che installi o i comandi che esegui saranno isolati a questo progetto.

Installare langchain-openai

Con l'ambiente attivo, è ora di installare gli strumenti necessari. Dato che lavoriamo con OpenAI e LangChain, partiamo installando il pacchetto langchain-openai. Questo pacchetto ci permette di interagire con i modelli di OpenAI.

Esegui nel terminale: pip install langchain-openai.

Configurare le variabili d'ambiente

Il passo successivo è assicurarsi che le informazioni sensibili, come le chiavi API, non finiscano hardcodate negli script. Lo faremo impostando variabili d'ambiente.

Per prima cosa, ti serve l'accesso ai modelli di OpenAI. Se non l'hai già fatto, vai sulla piattaforma OpenAI e crea un account. Una volta registrato, dovrai generare una chiave API. Questa chiave è il tuo pass per accedere ai modelli di OpenAI, incluso gpt-4o-audio-preview.

Nel nostro caso, dovremo impostare OPENAI_API_KEY. Puoi farlo manualmente ogni volta che lavori al progetto oppure usare un file .env per conservarla e averla a portata di mano. Vediamo entrambi i metodi.

Metodo 1: Impostare le variabili d'ambiente manualmente

Se stai solo facendo una prova e vuoi una configurazione rapida, puoi impostare la variabile d'ambiente direttamente dal terminale.

• Su macOS/Linux, esegui: export OPENAI_API_KEY='your-api-key-here'
• Su Windows, usa: set OPENAI_API_KEY='your-api-key-here'

Ora la tua chiave API è disponibile nello script e puoi accedervi col modulo os in Python.

Metodo 2: Usare un file .env

Se preferisci una soluzione più stabile, puoi usare un file .env per salvare le variabili d'ambiente. Questo file resterà nella cartella del progetto e terrà al sicuro le chiavi.

Per prima cosa, crea un file .env nella directory del progetto e dentro aggiungi la tua chiave API così:

OPENAI_API_KEY=your-api-key-here

Poi, installa il pacchetto python-dotenv:

pip install python-dotenv

Ora, nel tuo script Python, carica le variabili d'ambiente dal file .env così:

from dotenv import load_dotenv
import os
load_dotenv()  # Load variables from .env file
api_key = os.getenv('OPENAI_API_KEY')

Questo metodo è particolarmente utile se devi gestire più variabili d'ambiente e mantiene il codice pulito e sicuro.

Opzionale: LangSmith per il tracing

Se vuoi tracciare e monitorare le chiamate API per debugging o performance, OpenAI ha una funzione interessante chiamata LangSmith. Fornisce log dettagliati di ogni chiamata API del tuo modello, molto utile se vuoi ottimizzare o risolvere problemi nel flusso di lavoro.

Puoi abilitare il tracing di LangSmith così:

os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"

Anche questo è del tutto opzionale, ma è uno strumento comodo se stai lavorando a un'app complessa e vuoi monitorare il comportamento dei modelli.

Istanziare il modello gpt-4o-audio-preview di OpenAI

Ora che l'ambiente è pronto, passiamo alla parte divertente: istanziare il modello gpt-4o-audio-preview di OpenAI. Qui iniziamo a interagire con il modello, fare richieste e gestire input e output.

In questa sezione vedremo come istanziare il modello con il framework LangChain, personalizzare alcuni parametri base e impostare tutto il necessario per iniziare a generare risposte.

Cosa significa istanziare il modello?

Prima del codice, capiamo cosa significa "istanziare" il modello. Vuol dire creare un oggetto in Python che ci permette di interagire con il modello gpt-4o-audio-preview. Questo oggetto è come un pannello di controllo: contiene impostazioni, configurazioni e metodi necessari per inviare dati al modello e ricevere i risultati.

Configurazione base del modello con LangChain

Creiamo questo oggetto modello. Poiché lavoriamo con LangChain, useremo la classe ChatOpenAI dal pacchetto langchain_openai. Questa classe dà accesso semplice ai modelli OpenAI e alle loro funzionalità.

from langchain_openai import ChatOpenAI

# Create the model object
llm = ChatOpenAI(
    model="gpt-4o-audio-preview",  # Specifying the model
    temperature=0,  # Controls randomness in the output
    max_tokens=None,  # Unlimited tokens in output (or specify a max if needed)
    timeout=None,  # Optional: Set a timeout for requests
    max_retries=2  # Number of retries for failed requests
)

Uno dei punti di forza di questo modello è la personalizzazione. Puoi regolare i parametri in base alle esigenze. Per esempio, se stai creando un'app che richiede la trascrizione audio, puoi adattare i parametri per gestire input più grandi o limitare la lunghezza dell'output.

Se ti servono risposte con tempi certi e vuoi evitare attese troppo lunghe, puoi impostare anche un timeout:

llm = ChatOpenAI(
    model="gpt-4o-audio-preview",
    timeout=30  # Set timeout to 30 seconds
)

Gpt-4o-audio-preview con input e output audio

Ora che il modello gpt-4o-audio-preview è operativo, vediamo la sua capacità di gestire input e output audio.

Caricare e codificare file audio

Prima di lavorare con l'audio, il primo passo è caricare e codificare il file audio in un formato che il modello possa capire. OpenAI si aspetta che i dati audio siano inviati in formato codificato base64, quindi partiamo dal caricamento del file e dalla codifica.

Poniamo di avere un file .wav da far processare al modello — l'ho chiamato gpt.wav. Puoi sostituirlo col tuo file usando il codice seguente. Ecco come caricare e preparare quel file:

import base64

# Open the audio file and convert to base64
with open("gpt.wav", "rb") as f:
   audio_data = f.read()

# Convert binary audio data to base64
audio_b64 = base64.b64encode(audio_data).decode()

Cosa succede qui? Leggiamo il file audio come dati binari (modalità "rb"), poi usiamo la libreria base64 per codificarlo in una stringa base64. Questo è il formato richiesto da OpenAI per elaborare input audio.

Inviare l'audio al modello per la trascrizione

Una volta codificato l'audio, è il momento di passarlo al modello. Il modello gpt-4o-audio-preview può trascrivere il parlato dai file audio—quindi, se hai mai avuto bisogno di trasformare in testo un podcast, una nota vocale o una registrazione di riunione, ecco ciò che fa per te! Vediamo come funziona.

# Define the input message with audio
messages = [
    (
        "human",
        [
            {"type": "text", "text": "Transcribe the following:"},
            {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "wav"}},
        ],
    )
]

# Send the request to the model and get the transcription
output_message = llm.invoke(messages)
print(output_message.content)

In questo esempio inviamo due elementi al modello:

• Un messaggio di testo che lo istruisce a "Transcribe the following."
• I dati audio codificati in base64 con il formato specificato come .wav.

Il modello elabora questo input e restituisce la trascrizione dell'audio. Quindi, se il tuo file audio contiene una frase come "I’m learning how to use AI", il modello restituirà un output testuale tipo: "I'm learning how to use AI."

Generare output audio con gpt-4o-audio-preview

Ma il modello gpt-4o-audio-preview non serve solo a comprendere l'audio—può anche generarlo. Ecco come configurarlo per generare output audio:

llm = ChatOpenAI(
    model="gpt-4o-audio-preview",
    temperature=0,
    model_kwargs={
        "modalities": ["text", "audio"],  # We’re telling the model to handle both text and audio
        "audio": {"voice": "alloy", "format": "wav"},  # Configure voice and output format
    }
)

# Send a request and ask the model to respond with audio
messages = [("human", "Are you human? Reply either yes or no.")]
output_message = llm.invoke(messages)

# Access the generated audio data
audio_response = output_message.additional_kwargs['audio']['data']

Vediamo nel dettaglio:

• modalities=["text", "audio"]: Diciamo al modello che vogliamo gestire sia testo che audio. Questo gli permette di generare risposte parlate.
• audio={"voice": "alloy", "format": "wav"}: Qui specifichiamo la voce (in questo caso "alloy") e il formato dell'output audio (.wav). OpenAI fornisce diverse voci, quindi puoi personalizzare l'esperienza in base alle esigenze della tua app.

La risposta audio codificata in base64 è salvata in output_message.additional_kwargs['audio']['data'] e puoi decodificarla e salvarla facilmente per la riproduzione.

Salvare e riprodurre file audio

Ora che generi audio, probabilmente vuoi salvare il file e riprodurlo, giusto? Ecco come prendere i dati audio in base64, decodificarli e salvarli come file .wav:

# Decode the base64 audio data
audio_bytes = base64.b64decode(output_message.additional_kwargs['audio']['data'])

# Save the audio file
with open("output.wav", "wb") as f:
    f.write(audio_bytes)
print("Audio saved as output.wav")

Ora puoi riprodurre questo file .wav in locale con qualsiasi lettore multimediale. Quindi ora, quando invochi il modello, ottieni non solo una risposta testuale ma anche un file audio che pronuncia la risposta.

Casi d'uso avanzati di gpt-4o-audio-preview

In questa sezione vedremo come collegare strumenti al modello gpt-4o-audio-preview, gestire flussi di lavoro più complessi e concatenare più passaggi per creare soluzioni completamente automatizzate. Se hai mai voluto costruire un assistente vocale che non solo trascrive l'audio ma recupera anche informazioni da fonti esterne, questa sezione ti sarà utile.

Tool calling

Partiamo dal tool calling. È l'arte di insegnare al modello a usare strumenti o funzioni esterne per migliorarne le capacità. Invece di limitarsi a processare testo o audio, il modello può svolgere compiti aggiuntivi come recuperare dati da API, fare calcoli o persino cercare informazioni sul meteo.

Il modello gpt-4o-audio-preview di OpenAI può essere combinato con altri strumenti e funzioni tramite il metodo bind_tools di LangChain. Con questo metodo puoi creare un flusso di lavoro fluido in cui il modello decide quando e come usare gli strumenti che hai fornito.

Ti guiderò attraverso un esempio pratico di collegamento di uno strumento al modello. In questo caso, collegheremo uno strumento che recupera il meteo.

Per prima cosa, definiamo un modello Pydantic che rappresenta lo strumento da usare. Poi lo leghiamo al modello gpt-4o-audio-preview così che possa essere invocato quando serve. Per questo ti servirà una chiave API di OpenWeatherMap.

import requests
from pydantic import BaseModel, Field

# Define a tool schema using Pydantic
class GetWeather(BaseModel):
   """Get the current weather in a given location."""
   location: str = Field(..., description="The city and state, e.g. Edinburgh, UK")
   def fetch_weather(self):
       # Using OpenWeatherMap API to fetch real-time weather
       API_KEY = "YOUR_API_KEY_HERE"  # Replace with your actual API key
       base_url = f"http://api.openweathermap.org/data/2.5/weather?q={self.location}&APPID={API_KEY}&units=metric"      
       response = requests.get(base_url)      
       if response.status_code == 200:
           data = response.json()
           weather_description = data['weather'][0]['description']
           temperature = data['main']['temp']
           return f"The weather in {self.location} is {weather_description} with a temperature of {temperature}°C."
       else:
           # Print the status code and response for debugging
           print(f"Error: {response.status_code}, {response.text}")
           return f"Could not fetch the weather for {self.location}."

# Example usage
weather_tool = GetWeather(location="Edinburgh, GB")  # Using city name and country code
ai_msg = weather_tool.fetch_weather()
print(ai_msg)

Ecco cosa succede:

• Definizione dello strumento: definiamo uno strumento chiamato GetWeather, che prende una località in input e restituisce il meteo corrente per quella località usando l'API di OpenWeatherMap.
• Meteo a Edimburgo: in questo caso, recuperiamo il meteo per Edimburgo, Regno Unito.
• Dati meteo in tempo reale: lo strumento ottiene i dati in tempo reale tramite un'API esterna e li restituisce.

In questo esempio, voglio sapere il meteo a Edimburgo. Quando l'ho eseguito, ho ottenuto questo output: The weather in Edinburgh, GB is broken clouds with a temperature of 13.48°C.

Concatenare attività: creare flussi multi-step

Concatenando attività puoi creare flussi di lavoro multi-step che combinano più strumenti e chiamate al modello per gestire richieste complesse. Immagina di voler far trascrivere all'assistente l'audio e poi eseguire un'azione in base alla località menzionata nell'audio. In questo esempio concateneremo una trascrizione audio con una ricerca del meteo basata sulla località trascritta.

import base64
import requests
from pydantic import BaseModel, Field
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

# Define the tool schema for fetching weather
class GetWeather(BaseModel):
   """Get the current weather in a given location."""
   location: str = Field(..., description="The city and state, e.g. Edinburgh, UK")
   def fetch_weather(self):
       # Using OpenWeatherMap API to fetch real-time weather
       API_KEY = "YOUR_API_KEY_HERE"  # Replace with your actual API key
       base_url = f"http://api.openweathermap.org/data/2.5/weather?q={self.location}&appid={API_KEY}&units=metric"       
       response = requests.get(base_url)
       if response.status_code == 200:
           data = response.json()
           weather_description = data['weather'][0]['description']
           temperature = data['main']['temp']
           return f"The weather in {self.location} is {weather_description} with a temperature of {temperature}°C."
       else:
           return f"Could not fetch the weather for {self.location}."

# Instantiate the LLM model
llm = ChatOpenAI(
   model="gpt-4o-audio-preview"
)
# Function to handle audio transcription using the LLM
def audio_to_text(audio_b64: str) -> str:
   # Define the message to send for transcription
   messages = [
       (
           "human",
           [
               {"type": "text", "text": "Transcribe the following:"},
               {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "wav"}},
           ],
       )
   ]
   # Invoke the model and get the transcription
   output_message = llm.invoke(messages)
   # Return the transcription from the model's output
   return output_message.content

# Create a prompt template for transcription and weather lookup
prompt = ChatPromptTemplate.from_messages(
   [
       ("system", "You are an assistant that transcribes audio and fetches weather information."),
       ("human", "Transcribe the following and tell me the weather in the location mentioned in the audio."),
   ]
)

# Bind the tool to the model
llm_with_tools = llm.bind_tools([GetWeather])

# Chain the transcription and weather tool
chain = prompt | llm_with_tools

# Read and encode the audio file in base64
audio_file = "weather_input.wav" #Replace with your audio file
with open(audio_file, "rb") as audio_file:
   audio_b64 = base64.b64encode(audio_file.read()).decode('utf-8')

# Transcribe the audio to get the location
transcribed_location = audio_to_text(audio_b64)

# Print the transcription result for debugging
print(f"Transcribed location: {transcribed_location}")

# Check if transcription returned a valid result
if transcribed_location:
   # Fetch weather for the transcribed location
   weather_tool = GetWeather(location=transcribed_location)
   weather_result = weather_tool.fetch_weather()
   print(f"Weather result: {weather_result}")
else:
   print("No valid location was transcribed from the audio.")

Analizziamo il codice:

• Trascrizione audio: l'utente fornisce un input audio (codificato in base64). L'audio viene inviato al modello, che trascrive il contenuto. Ad esempio, la trascrizione potrebbe dire "Edinburgh”.
• Ricerca meteo: dopo aver trascritto l'audio e determinato la località, il modello chiama lo strumento GetWeather per recuperare il meteo di quella località.
• Flusso completamente automatizzato: questa configurazione crea un flusso multi-step automatizzato in cui il modello prima capisce cosa è stato detto nell'audio (trascrivendolo) e poi agisce su quell'informazione recuperando i dati meteo rilevanti.

Per questo esempio, ho fornito al modello un file audio in cui ho detto: “Edinburgh”. Questo è l'output ottenuto:Transcribed location: Edinburgh

Weather result: The weather in Edinburgh is broken clouds with a temperature of 13.47°C.

Fine-tuning di gpt-4o-audio-preview

In alcuni casi potresti voler fare fine-tuning del modello per gestire compiti specifici in modo più efficace. Ad esempio, se stai creando un'app che trascrive audio medico, potresti voler che il modello abbia una profonda comprensione dei termini e del gergo medico. OpenAI consente di fare fine-tuning del modello addestrandolo su dataset personalizzati.

Vediamo come fare:

import base64
from langchain_openai import ChatOpenAI

# Step 1: Instantiate the fine-tuned audio-capable model
fine_tuned_model = ChatOpenAI(
    temperature=0,
    model="ft:gpt-4o-audio-preview:your-organization::model-id"
)

# Step 2: Capture and encode the input audio file (medical report)
audio_file = "medical_report.wav"
with open(audio_file, "rb") as audio_file:
    audio_b64 = base64.b64encode(audio_file.read()).decode('utf-8')

# Step 3: Create the message structure for transcription request
messages = [
    (
        "human",
        [
            {"type": "text", "text": "Please transcribe this medical report audio."},
            {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "wav"}},
        ],
    )
]

# Step 4: Invoke the fine-tuned model to transcribe the audio
result = fine_tuned_model.invoke(messages)

# Step 5: Extract and print the transcribed text from the response
transcription = result.content  # This contains the transcription
print(f"Transcription: {transcription}")

# Debugging: Print the full structure of the additional_kwargs for inspection
print(result.additional_kwargs)

Qui usiamo un modello fine-tuned addestrato specificamente per gestire audio medico, ma puoi fare fine-tuning anche per altri casi d'uso, come trascrizioni legali, registrazioni di assistenza clienti o editing di podcast. 

Esempio pratico: costruire un assistente con voce

Infine, vediamo un esempio pratico in cui costruiamo un assistente con funzionalità vocali che ascolta le richieste dell'utente tramite audio, genera una risposta e risponde a sua volta in audio. 

Suddivisione del flusso di lavoro

Seguiamo questo flusso:

1. L'utente parla al microfono e l'audio viene acquisito.
2. Il modello trascrive l'audio.
3. La trascrizione viene elaborata per generare una risposta.
4. Il modello quindi genera una risposta audio che può essere riprodotta all'utente.

Implementazione

Vediamo come codificarlo:

import base64
from langchain_openai import ChatOpenAI

# Step 1: Instantiate the audio-capable model with configuration for generating audio
llm = ChatOpenAI(
   model="gpt-4o-audio-preview",
   temperature=0,
   model_kwargs={
       "modalities": ["text", "audio"],  # Enable both text and audio modalities
       "audio": {"voice": "alloy", "format": "wav"},  # Set the desired voice and output format
   }
)

# Step 2: Capture and encode the audio 
audio_file = "math_joke_audio.wav" #You can replace your audio file here
with open(audio_file, "rb") as audio_file:
   audio_b64 = base64.b64encode(audio_file.read()).decode('utf-8')

# Step 3: Create the message structure for transcription and audio response
messages = [
   (
       "human",
       [
           {"type": "text", "text": "Answer the question."},
           {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "wav"}},
       ],
   )
]

# Step 4: Invoke the model to transcribe the audio and generate a response
result = llm.invoke(messages)

# Step 5: Extract the audio response
audio_response = result.additional_kwargs.get('audio', {}).get('data')  # Safely check if audio exists

# Step 6: Save the audio response to a file if it exists
if audio_response:
   # Decode the base64 audio data and save it as a .wav file
   audio_bytes = base64.b64decode(audio_response)
   with open("response.wav", "wb") as f:
       f.write(audio_bytes)
   print("Audio response saved as 'response.wav'")
else:
   print("No audio response available")

Come funziona

Ecco come funziona:

• Input audio: l'utente fornisce un input audio, ad esempio ponendo una domanda (es. "Tell me a math joke"). L'audio viene codificato in base64 e passato all'assistente.
• Trascrizione: il modello trascrive l'audio in testo. Questa trascrizione è disponibile se vuoi registrarla o mostrarla.
• Generazione della risposta: in base alla trascrizione, il modello genera una risposta usando le sue conoscenze interne (es. "The capital of France is Paris")
• Output audio: la risposta viene convertita in formato audio. L'audio è salvato come file (es. "response.wav"), che può essere riprodotto con qualsiasi player.

Questo assistente è pensato per conversare tramite audio. Ascolta la voce dell'utente, capisce la domanda e poi risponde con la propria voce. Questa configurazione è ottima per costruire semplici assistenti vocali e puoi renderla più avanzata in seguito, se necessario!

Conclusione

In questo tutorial abbiamo esplorato il modello gpt-4o-audio-preview di OpenAI, trattando configurazione, input/output audio, casi d'uso avanzati e la creazione di un semplice assistente vocale. Questo potente modello offre una base solida per creare applicazioni audio reali.

Se vuoi migliorare la tua pratica con LangChain, ti consiglio questi blog:

• Come creare interfacce utente per applicazioni AI con Streamlit e LangChain
• RAG con Llama 3.1 8B, Ollama e LangChain: tutorial
• Creare agenti LangChain per automatizzare task in Python