Produção: Escalabilidade e Monitorização
Nesta página
Atualizado a 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos:
tts-1,tts-1-hdegpt-4o-mini-ttsdeixarão de funcionar a 6 de janeiro de 2027 (substituição:gpt-realtime-2.1-mini, que o guia TTS da OpenAI indica não ser suportado por/v1/audio/speech: a migração da síntese de fala deve passar pela API Realtime);gpt-realtime,gpt-4o-realtimee 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-transcribee/v1/audio/translationsa 26 de fevereiro de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para voz full-duplex, o GPT-Live 1 está disponível na API desde 10 de setembro de 2026.
Atualizado a 3 de novembro de 2026. A gestão de custos, que antes cabia numa única frase, reflete agora o modelo de faturação descrito pela OpenAI (faturação por resposta, conversa devolvida a cada turno, áudio contado em tokens, cache automático, transcrição faturada separadamente) e o truncamento via
retention_ratio, cujo formato foi verificado contra os tipos do SDKopenaiversão 3.42.1. Fonte: Otimização de custos.
Produção: Escalabilidade e Monitorização
Passar de um protótipo de agente de voz para um serviço de produção fiável e escalável exige atenção redobrada à infraestrutura, monitorização e tratamento de erros. Esta última lição cobre os essenciais operacionais para implementar um agente de voz em condições reais.
Arquitetura de Produção
Em produção, o agente de voz opera atrás de um balanceador de carga e de um pool de trabalhadores:
Balanceador de Carga (nginx / HAProxy)
Distribui as ligações WebSocket recebidas pelos trabalhadores. Suporta sessões persistentes (sticky sessions) para manter a afinidade.
Trabalhadores (FastAPI + uvicorn)
Cada trabalhador gere múltiplas sessões Realtime simultâneas graças ao asyncio.
Base de Dados (PostgreSQL)
Armazena registos de conversas, métricas e configuração do agente.
Monitorização (Prometheus + Grafana)
Recolhe métricas em tempo real: latência, contagem de sessões, erros, custos.
Gestão de Sessões Concorrentes
Cada ligação WebSocket mantém uma sessão da API Realtime. O número de sessões simultâneas é limitado pelas suas taxas de utilização da OpenAI e pela capacidade dos seus trabalhadores:
import asyncio
from dataclasses import dataclass
@dataclass
class SessionManager:
"""Gere sessões concorrentes da API Realtime."""
max_sessions: int = 50
active_sessions: dict = None
semaphore: asyncio.Semaphore = None
def __post_init__(self):
self.active_sessions = {}
self.semaphore = asyncio.Semaphore(self.max_sessions)
async def create_session(self, session_id: str, config: dict):
"""Cria uma nova sessão com controlo de concorrência."""
async with self.semaphore:
if session_id in self.active_sessions:
raise ValueError(f"Session {session_id} already active")
self.active_sessions[session_id] = {
"created_at": asyncio.get_event_loop().time(),
"config": config,
"status": "active"
}
return session_id
async def close_session(self, session_id: str):
"""Fecha corretamente uma sessão."""
if session_id in self.active_sessions:
del self.active_sessions[session_id]
@property
def active_count(self) -> int:
return len(self.active_sessions)
@property
def available_slots(self) -> int:
return self.max_sessions - self.active_count
session_manager = SessionManager(max_sessions=50)
Registos Estruturados
Registe todas as interações para depuração e conformidade:
import logging
import json
from datetime import datetime
class ConversationLogger:
"""Registador estruturado para conversas de voz."""
def __init__(self, session_id: str):
self.session_id = session_id
self.logger = logging.getLogger(f"voice.{session_id}")
self.events = []
def log_event(self, event_type: str, data: dict = None):
entry = {
"timestamp": datetime.utcnow().isoformat(),
"session_id": self.session_id,
"event_type": event_type,
"data": data or {}
}
self.events.append(entry)
self.logger.info(json.dumps(entry))
def log_transcription(self, role: str, text: str):
self.log_event("transcription", {
"role": role,
"text": text
})
def log_function_call(self, name: str, args: dict, result: dict, duration_ms: float):
self.log_event("function_call", {
"name": name,
"arguments": args,
"result": result,
"duration_ms": round(duration_ms)
})
def log_error(self, error_type: str, message: str):
self.log_event("error", {
"type": error_type,
"message": message
})
async def save_to_db(self, db_pool):
"""Persiste o registo completo na base de dados."""
async with db_pool.acquire() as conn:
await conn.execute(
"INSERT INTO conversation_logs (session_id, events, created_at) "
"VALUES ($1, $2, NOW())",
self.session_id, json.dumps(self.events)
)
Métricas Prometheus
Exponha métricas para monitorização em tempo real:
from prometheus_client import Counter, Histogram, Gauge, start_http_server
# Métricas chave
sessions_active = Gauge(
"voice_sessions_active",
"Number of active voice sessions"
)
session_duration = Histogram(
"voice_session_duration_seconds",
"Duration of voice sessions",
buckets=[30, 60, 120, 300, 600, 1800]
)
response_latency = Histogram(
"voice_response_latency_ms",
"Response latency (end of speech → first audio)",
buckets=[200, 400, 600, 800, 1000, 1500, 2000, 3000]
)
errors_total = Counter(
"voice_errors_total",
"Total number of errors",
["error_type"]
)
tokens_used = Counter(
"voice_tokens_total",
"Tokens consumed",
["type"] # input_audio, output_audio, input_text, output_text
)
# Iniciar o servidor de métricas
start_http_server(9090)
Gestão de Custos
De acordo com o guia de Otimização de custos da OpenAI, uma sessão de conversa Realtime é faturada por resposta, em tokens de entrada e saída para texto, áudio e imagens. Três mecanismos impulsionam a maior parte da fatura:
- Toda a conversa é reenviada ao modelo a cada resposta: os turnos posteriores custam mais do que os iniciais.
- O áudio é contado em tokens: 1 token por 100 ms de áudio do utilizador, 1 token por 50 ms de áudio do assistente.
- O cache de prompts aplica-se automaticamente: enquanto o início da conversa não mudar, é faturado à taxa reduzida de tokens em cache. Modificar ou apagar um elemento antigo “quebra” o cache a partir desse ponto.
A transcrição de entrada, se ativada, é faturada separadamente à taxa do seu próprio modelo: gpt-transcribe é cobrado por duração, lida a partir do evento conversation.item.input_audio_transcription.completed. O consumo de cada resposta aparece em response.done, sob response.usage (total_tokens, input_tokens, output_tokens, além da discriminação para texto, áudio, imagem e cache).
Para limitar o tamanho do contexto — e assim o custo dos turnos posteriores — a sessão aceita uma regra de truncamento: além do limite, as mensagens mais antigas são eliminadas. Com retention_ratio definido abaixo de 1, o servidor remove ligeiramente mais do que o necessário, o que espaça os truncamentos e preserva o cache:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"truncation": {
"type": "retention_ratio",
"retention_ratio": 0.8,
"token_limits": {"post_instructions": 8000},
},
},
}))
A contrapartida: um agente que retém menos contexto esquece mais depressa. Complemente isto com limites de sessão no seu código:
class CostController:
"""Controla os custos de uma sessão Realtime."""
def __init__(self, max_duration_s: int = 600, max_tokens: int = 50000):
self.max_duration_s = max_duration_s
self.max_tokens = max_tokens
self.total_tokens = 0
self.start_time = None
def start(self):
self.start_time = asyncio.get_event_loop().time()
def update_tokens(self, usage: dict):
self.total_tokens += usage.get("total_tokens", 0)
@property
def elapsed_seconds(self) -> float:
if not self.start_time:
return 0
return asyncio.get_event_loop().time() - self.start_time
@property
def should_terminate(self) -> bool:
if self.elapsed_seconds > self.max_duration_s:
return True
if self.total_tokens > self.max_tokens:
return True
return False
@property
def warning_message(self) -> str:
remaining = self.max_duration_s - self.elapsed_seconds
if remaining < 60:
return f"This session will end in {int(remaining)} seconds."
return ""
Tratamento de Erros em Produção
async def production_event_loop(ws, logger, cost_ctrl):
"""Ciclo de eventos robusto para produção."""
cost_ctrl.start()
try:
async for raw in ws:
event = json.loads(raw)
t = event["type"]
# Verificar limites de custo
if cost_ctrl.should_terminate:
logger.log_event("session_limit_reached")
await ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [{"type": "input_text",
"text": "The session is approaching its duration limit."}]
}
}))
break
if t == "response.done":
usage = event["response"].get("usage", {})
cost_ctrl.update_tokens(usage)
tokens_used.labels(type="total").inc(usage.get("total_tokens", 0))
elif t == "error":
error = event["error"]
logger.log_error(error["type"], error["message"])
errors_total.labels(error_type=error["type"]).inc()
if error["type"] == "rate_limit_error":
await asyncio.sleep(1)
except websockets.exceptions.ConnectionClosed as e:
logger.log_error("connection_closed", str(e))
except Exception as e:
logger.log_error("unexpected", str(e))
finally:
session_duration.observe(cost_ctrl.elapsed_seconds)
sessions_active.dec()
Pontos-chave
- A arquitetura de produção separa balanceador de carga, trabalhadores asyncio, base de dados e monitorização
- Um
SessionManagercom um semáforo controla o número de sessões simultâneas - Registos estruturados JSON permitem depuração e conformidade (gravação de conversas)
- Métricas Prometheus (TTFA, duração, tokens, erros) são essenciais para operações diárias
- O
CostControllerlimita a duração da sessão e os tokens para evitar estouros orçamentais
Teste os Seus Conhecimentos
Cinco questões que cobrem toda a cadeia de voz, desde o WebSocket até à implementação em produção.
1. Porque é que a API Realtime usa WebSocket em vez de pedidos HTTP?
Resposta: Porque uma ligação persistente e bidirecional permite transmitir áudio do microfone e receber respostas continuamente, sem pagar a sobrecarga de estabelecer um pedido para cada troca. Este é o pré-requisito para uma conversa de baixa latência.
2. O que deve enviar imediatamente após `session.created` e porquê?
Resposta: session.update, imediatamente: é aqui que configura a voz, instruções, ferramentas e formato de áudio. Até esta mensagem ser enviada, a sessão executa com valores padrão.
3. Porque é que um servidor proxy é essencial em produção?
Resposta: Impede a exposição da chave API no cliente e permite autenticar o utilizador, limitar o consumo e registar chamadas — três coisas impossíveis se o navegador falar diretamente com a API.
4. Qual é a finalidade do parâmetro `prompt` na API de transcrição?
Resposta: Orientar o reconhecimento para o vocabulário esperado: nomes próprios, marcas, jargão do domínio. Os termos que listar aí serão transcritos com muito mais precisão.
5. Qual é a principal alavanca para a latência percebida num agente de voz?
Resposta: Streaming de ponta a ponta: reproduzir áudio assim que os primeiros fragmentos chegam, em vez de esperar pela resposta completa, e gerir interrupções para que o utilizador possa intervir a qualquer momento.