Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Assistente vocale multimodale

Lezione 16 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Assistente vocale multimodale
  2. Testo e audio in parallelo
  3. Mostrare un’immagine all’agente vocale
  4. Interfaccia web multimodale
  5. Casi d’uso multimodali
  6. Punti chiave

Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati: tts-1, tts-1-hd e gpt-4o-mini-tts smetteranno 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-realtime e 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-transcribe e /v1/audio/translations il 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.1 e gpt-realtime-2 accettano immagini come input: l’immagine viene allegata direttamente, come input_image, a un messaggio utente. L’evento response.text.delta della vecchia beta è ora denominato response.output_text.delta. Formati degli eventi verificati rispetto ai tipi SDK openai 3.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.create ti permette di arricchire il contesto vocale
  • I modelli Realtime accettano immagini: allegale come input_image a 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