Assistente vocale multimodale
In questa pagina
Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati:
tts-1,tts-1-hdegpt-4o-mini-ttssmetteranno di funzionare il 6 gennaio 2027 (la sostituzione indicata ègpt-realtime-2.1-mini, che la guida TTS di OpenAI specifica non essere supportata da/v1/audio/speech: la migrazione della sintesi vocale deve avvenire tramite le API Realtime);gpt-realtime,gpt-4o-realtimee i modelli audio legacy il 20 gennaio 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsil 26 febbraio 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Per il voice full-duplex, GPT-Live 1 è disponibile nelle API dal 10 settembre 2026.
Corretto il 3 novembre 2026. Per analizzare un’immagine, la lezione precedente effettuava una chiamata separata alle API Responses, per poi iniettare la descrizione come messaggio dell’assistente con contenuto
input_text, un tipo riservato ai messaggi utente o di sistema. Tuttavia,gpt-realtime-2.1egpt-realtime-2accettano immagini come input: l’immagine viene allegata direttamente, comeinput_image, a un messaggio utente. L’eventoresponse.text.deltadella vecchia beta è ora denominatoresponse.output_text.delta. Formati degli eventi verificati rispetto ai tipi SDKopenai3.42.1. Fonti: Conversazioni in tempo reale, Input di immagini · gpt-realtime-2.1.
Assistente vocale multimodale
Un assistente vocale multimodale combina la voce con altre modalità: testo, immagini, video e dati strutturati. L’utente parla, ma l’agente può anche mostrare informazioni visive, analizzare immagini inviate dall’utente o combinare più fonti di dati. Questo è il futuro dell’interazione uomo-computer.
Testo e audio in parallelo
Le API Realtime supportano nativamente le modalità testo e audio simultaneamente. Puoi iniettare testo nella conversazione mantenendo lo scambio vocale:
async def inject_text_context(ws, context: str):
"""Aggiunge contesto testuale alla conversazione vocale."""
await ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": context
}
]
}
}))
# Attiva una risposta vocale basata su questo contesto
await ws.send(json.dumps({"type": "response.create"}))
# L'utente chiede verbalmente "Leggimi la mia ultima email"
# Tu inietti il contenuto dell'email come testo
await inject_text_context(ws, """
Ecco l'ultima email ricevuta:
Da: [email protected]
Oggetto: Richiesta di preventivo
Contenuto: Salve, vorrei richiedere un preventivo per
l'integrazione di un agente vocale nel nostro call center.
""")
Mostrare un’immagine all’agente vocale
gpt-realtime-2.1 e gpt-realtime-2 accettano testo, audio e immagini come input. Un’immagine viene allegata come parte input_image di un messaggio utente, utilizzando un Data URI Base64, sia su WebSocket che sul canale dati WebRTC. Il modello ne tiene conto nella sua risposta vocale, senza chiamare un’altra API:
import base64
import json
async def montrer_image(ws, chemin_image: str, question: str) -> None:
"""Allega un'immagine e una domanda alla conversazione, quindi richiede una risposta vocale."""
with open(chemin_image, "rb") as f:
image_b64 = base64.b64encode(f.read()).decode()
await ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [
{"type": "input_image", "image_url": f"data:image/jpeg;base64,{image_b64}"},
{"type": "input_text", "text": question},
],
},
}))
await ws.send(json.dumps({"type": "response.create"}))
await montrer_image(ws, "facture.jpg", "Cosa devo pagare e entro quale data?")
Le immagini vengono fatturate come token immagine, a una tariffa specifica elencata nella scheda del modello. Per analisi pesanti o per un modello di visione più capace, puoi comunque interrogare separatamente le API Responses, per poi passare il risultato alla sessione: fallo tramite un messaggio system o user (con contenuto input_text), mai tramite un falso messaggio dell’assistente, che il modello interpretrebbe come parole proprie.
Interfaccia web multimodale
Per un’applicazione web, combina il WebSocket Realtime con un’interfaccia visiva:
from fastapi import FastAPI, WebSocket
from fastapi.staticfiles import StaticFiles
app = FastAPI()
@app.websocket("/ws/agent")
async def multimodal_agent(client_ws: WebSocket):
"""Agente multimodale con interfaccia web."""
await client_ws.accept()
headers = {
"Authorization": f"Bearer {OPENAI_API_KEY}"
}
async with websockets.connect(REALTIME_URL, additional_headers=headers) as openai_ws:
await openai_ws.recv() # session.created
await openai_ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "Assistente multimodale. Rispondi in italiano.",
"audio": {"output": {"voice": "marin"}}
}
}))
await openai_ws.recv()
async def client_to_openai():
async for message in client_ws.iter_text():
data = json.loads(message)
if data["type"] == "audio":
# Inoltra l'audio
await openai_ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": data["audio"]
}))
elif data["type"] == "text":
# Messaggio di testo (chat)
await openai_ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [{
"type": "input_text",
"text": data["text"]
}]
}
}))
await openai_ws.send(json.dumps({
"type": "response.create"
}))
async def openai_to_client():
async for message in openai_ws:
event = json.loads(message)
t = event["type"]
if t == "response.output_audio.delta":
await client_ws.send_json({
"type": "audio",
"delta": event["delta"]
})
elif t == "response.output_audio_transcript.delta":
await client_ws.send_json({
"type": "transcript",
"delta": event["delta"]
})
elif t == "response.output_text.delta":
await client_ws.send_json({
"type": "text",
"delta": event["delta"]
})
await asyncio.gather(client_to_openai(), openai_to_client())
Casi d’uso multimodali
Ecco come un agente multimodale gestisce diversi scenari in uno strumento di chiamata di funzione:
tools = [
{
"type": "function",
"name": "show_chart",
"description": "Mostra un grafico dei dati all'utente",
"parameters": {
"type": "object",
"properties": {
"chart_type": {"type": "string", "enum": ["bar", "line", "pie"]},
"title": {"type": "string"},
"data": {"type": "object"}
},
"required": ["chart_type", "title", "data"]
}
},
{
"type": "function",
"name": "send_document",
"description": "Invia un documento al cliente via email",
"parameters": {
"type": "object",
"properties": {
"document_type": {"type": "string"},
"recipient": {"type": "string"}
},
"required": ["document_type", "recipient"]
}
}
]
L’utente dice verbalmente: «Mostrami le vendite dell’ultimo trimestre come grafico». L’agente chiama show_chart, il tuo frontend visualizza il grafico e l’agente commenta verbalmente i risultati.
Punti chiave
- Le API Realtime supportano le modalità testo e audio simultaneamente nella stessa sessione
- Iniettare testo tramite
conversation.item.createti permette di arricchire il contesto vocale - I modelli Realtime accettano immagini: allegale come
input_imagea un messaggio utente - Gli strumenti (chiamata di funzione) ti permettono di mostrare elementi visivi mentre rispondi verbalmente
- L’architettura WebSocket lato client ti permette di mescolare audio, testo e dati strutturati