Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Assistente de Voz Multimodal

Aula 16 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Assistente de Voz Multimodal
  2. Texto e Áudio em Paralelo
  3. Mostrar uma Imagem ao Agente de Voz
  4. Interface Web Multimodal
  5. Casos de Uso Multimodal
  6. Pontos-chave

Atualizado a 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos: tts-1, tts-1-hd e gpt-4o-mini-tts deixarão de funcionar a 6 de janeiro de 2027 (a substituição indicada é gpt-realtime-2.1-mini, que o guia TTS da OpenAI afirma não ser suportado por /v1/audio/speech: a migração da síntese de fala deve ocorrer através da API Realtime); gpt-realtime, gpt-4o-realtime e modelos de áudio legados a 20 de janeiro de 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe e /v1/audio/translations a 26 de fevereiro de 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Para voz em full-duplex, o GPT-Live 1 está disponível na API desde 10 de setembro de 2026.

Corrigido a 3 de novembro de 2026. Para analisar uma imagem, a lição anterior fazia uma chamada separada à API de Respostas e injetava a descrição como uma mensagem de assistente com conteúdo input_text, um tipo reservado a mensagens de utilizador ou de sistema. No entanto, gpt-realtime-2.1 e gpt-realtime-2 aceitam imagens como entrada: a imagem é anexada diretamente, como input_image, a uma mensagem de utilizador. O evento response.text.delta da antiga versão beta passou a chamar-se response.output_text.delta. Formatos de eventos verificados com os tipos do SDK openai 3.42.1. Fontes: Conversas em tempo real, Entradas de imagem · gpt-realtime-2.1.

Assistente de Voz Multimodal

Um assistente de voz multimodal combina a voz com outras modalidades: texto, imagens, vídeo e dados estruturados. O utilizador fala, mas o agente também pode exibir informações visuais, analisar imagens enviadas pelo utilizador ou combinar múltiplas fontes de dados. Este é o futuro da interação humano-computador.

Texto e Áudio em Paralelo

A API Realtime suporta nativamente as modalidades de texto e áudio simultaneamente. Pode injetar texto na conversa enquanto mantém a troca de voz:

async def inject_text_context(ws, context: str):
    """Adiciona contexto de texto à conversa de voz."""
    await ws.send(json.dumps({
        "type": "conversation.item.create",
        "item": {
            "type": "message",
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": context
                }
            ]
        }
    }))

    # Aciona uma resposta de voz com base neste contexto
    await ws.send(json.dumps({"type": "response.create"}))

# O utilizador pede verbalmente "Lê-me o meu e-mail mais recente"
# Injeta o conteúdo do e-mail como texto
await inject_text_context(ws, """
Aqui está o e-mail mais recente recebido:
De: [email protected]
Assunto: Pedido de Orçamento
Conteúdo: Olá, gostaria de solicitar um orçamento para
integrar um agente de voz no nosso call center.
""")

Mostrar uma Imagem ao Agente de Voz

gpt-realtime-2.1 e gpt-realtime-2 aceitam texto, áudio e imagens como entrada. Uma imagem é anexada como uma parte input_image de uma mensagem de utilizador, usando um URI de dados Base64, tanto via WebSocket como através do canal de dados WebRTC. O modelo considera isto na sua resposta de voz, sem chamar outra API:

import base64
import json


async def mostrar_imagem(ws, caminho_imagem: str, pergunta: str) -> None:
    """Anexa uma imagem e uma pergunta à conversa e solicita uma resposta de voz."""
    with open(caminho_imagem, "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": pergunta},
            ],
        },
    }))
    await ws.send(json.dumps({"type": "response.create"}))


await mostrar_imagem(ws, "factura.jpg", "O que preciso de pagar e até que data?")

As imagens são faturadas como tokens de imagem, a uma taxa específica listada no cartão do modelo. Para análises pesadas ou para um modelo de visão mais capaz, pode ainda consultar a API de Respostas separadamente e passar o resultado para a sessão: faça-o através de uma mensagem system ou user (com conteúdo input_text), nunca através de uma mensagem de assistente falsa, que o modelo interpretaria como sendo as suas próprias palavras.

Interface Web Multimodal

Para uma aplicação web, combine o WebSocket Realtime com uma interface visual:

from fastapi import FastAPI, WebSocket
from fastapi.staticfiles import StaticFiles

app = FastAPI()

@app.websocket("/ws/agent")
async def agente_multimodal(client_ws: WebSocket):
    """Agente multimodal com interface 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 multimodal. Responda em inglês.",
                "audio": {"output": {"voice": "marin"}}
            }
        }))
        await openai_ws.recv()

        async def cliente_para_openai():
            async for message in client_ws.iter_text():
                data = json.loads(message)

                if data["type"] == "audio":
                    # Retransmite o áudio
                    await openai_ws.send(json.dumps({
                        "type": "input_audio_buffer.append",
                        "audio": data["audio"]
                    }))

                elif data["type"] == "text":
                    # Mensagem de texto (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_para_cliente():
            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(cliente_para_openai(), openai_para_cliente())

Casos de Uso Multimodal

Eis como um agente multimodal lida com diferentes cenários numa ferramenta de chamada de funções:

tools = [
    {
        "type": "function",
        "name": "show_chart",
        "description": "Exibe um gráfico de dados ao utilizador",
        "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": "Envia um documento ao cliente por e-mail",
        "parameters": {
            "type": "object",
            "properties": {
                "document_type": {"type": "string"},
                "recipient": {"type": "string"}
            },
            "required": ["document_type", "recipient"]
        }
    }
]

O utilizador diz verbalmente: «Mostra-me as vendas do último trimestre num gráfico». O agente chama show_chart, o seu frontend exibe o gráfico e o agente comenta verbalmente os resultados.

Pontos-chave

  • A API Realtime suporta modalidades de texto e áudio simultaneamente na mesma sessão
  • Injetar texto via conversation.item.create permite enriquecer o contexto de voz
  • Os modelos Realtime aceitam imagens: anexe-as como input_image a uma mensagem de utilizador
  • Ferramentas (chamada de funções) permitem exibir elementos visuais enquanto responde verbalmente
  • A arquitetura WebSocket do lado do cliente permite misturar áudio, texto e dados estruturados