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

Produção: Escalabilidade e Monitorização

Aula 18 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Produção: Escalabilidade e Monitorização
  2. Arquitetura de Produção
  3. Gestão de Sessões Concorrentes
  4. Registos Estruturados
  5. Métricas Prometheus
  6. Gestão de Custos
  7. Tratamento de Erros em Produção
  8. Pontos-chave
  9. Teste os Seus Conhecimentos

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 (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-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 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 SDK openai versã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:

1

Balanceador de Carga (nginx / HAProxy)

Distribui as ligações WebSocket recebidas pelos trabalhadores. Suporta sessões persistentes (sticky sessions) para manter a afinidade.

2

Trabalhadores (FastAPI + uvicorn)

Cada trabalhador gere múltiplas sessões Realtime simultâneas graças ao asyncio.

3

Base de Dados (PostgreSQL)

Armazena registos de conversas, métricas e configuração do agente.

4

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 SessionManager com 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 CostController limita 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.