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

Boas Práticas de Produção

Aula 17 de 22 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Boas Práticas de Produção
  2. 1. Arquitetura do Cliente
  3. 2. Gestão de Prompts
  4. 3. Tempos Limite e Limites
  5. 4. Fallback de Modelo
  6. 5. Processamento em Lote
  7. 6. Testes e Validação
  8. 7. Lista de Verificação de Implementação em Produção
  9. Pontos-chave

Lição atualizada em 3 de novembro de 2026 com base na documentação da OpenAI: temperature e top_p só são aceites com um esforço de raciocínio de none, enquanto os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificar reasoning={"effort": "none"} (Responses API) ou reasoning_effort="none" (Chat Completions). Fontes: Using GPT-6 · GPT-5.6 Terra.

Boas Práticas de Produção

Esta lição abrange as boas práticas essenciais para implementar uma aplicação baseada na API da OpenAI em produção. Encare isto como a sua lista de verificação pré-lançamento. As lições anteriores forneceram-lhe os blocos de construção — tratamento de erros, limites de taxa, resiliência, observabilidade e custos. Agora é altura de os reunir numa aplicação que um colega possa assumir e executar sem a sua intervenção.

1. Arquitetura do Cliente

Singleton com Configuração Centralizada

Instanciar um cliente OpenAI em cada chamada desperdiça a ligação HTTP subjacente e, mais grave ainda, dispersa a sua configuração. Acaba com um tempo limite de 30 segundos aqui e o valor predefinido ali, sem forma de saber qual se aplica em produção. O decorador lru_cache garante uma única instância, configurada num único local.

from openai import OpenAI
from functools import lru_cache

@lru_cache(maxsize=1)
def get_client() -> OpenAI:
    """Cliente singleton com configuração de produção."""
    return OpenAI(
        max_retries=3,
        timeout=30.0,
    )

# Em todo o seu código:
client = get_client()

Variáveis de Ambiente

O mesmo princípio aplica-se às definições que variam entre ambientes. Verifique as variáveis obrigatórias no arranque: é preferível que um serviço se recuse a iniciar com uma mensagem clara do que iniciar e falhar na primeira chamada do utilizador. Isto torna o modelo, o limite de tokens e a temperatura ajustáveis sem necessidade de nova implementação.

import os

# OBRIGATÓRIO: nunca codifique chaves diretamente
REQUIRED_ENV = ["OPENAI_API_KEY"]

for var in REQUIRED_ENV:
    if not os.environ.get(var):
        raise RuntimeError(f"Missing variable {var}")

# Configuração específica do ambiente
MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.6-terra")
MAX_TOKENS = int(os.environ.get("OPENAI_MAX_TOKENS", "4096"))
TEMPERATURE = float(os.environ.get("OPENAI_TEMPERATURE", "0.7"))

2. Gestão de Prompts

Separar Prompts do Código

Um prompt é um ativo empresarial, tal como uma regra de negócio. Enterrá-lo numa f-string dentro de uma função torna impossível que alguém que conheça o negócio, mas não Python, o reveja. Isole-o como um modelo parametrizado: a função reduz-se então à formatação e à chamada, e uma temperatura de 0.0 torna a classificação reproduzível.

# prompts/classification.txt
PROMPT_CLASSIFICATION = """You are a text classifier.
Classify the following text into one of these categories:
{categories}

Text: {texte}

Reply only with the category name."""

def classifier(texte: str, categories: list[str]) -> str:
    prompt = PROMPT_CLASSIFICATION.format(
        categories=", ".join(categories),
        texte=texte
    )
    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # temperature requires effort none
        input=prompt,
        temperature=0.0
    )
    return response.output_text.strip()

Versionar os Seus Prompts

Alterar um prompt altera o comportamento do sistema com a mesma certeza que alterar o código, mas sem que nenhum teste unitário o detete. Mantenha versões sucessivas e selecione a ativa através da configuração. Isto permite-lhe comparar duas formulações em tráfego real e reverter para a anterior com uma variável de ambiente se a nova degradar os resultados.

PROMPTS = {
    "classification_v1": "Classify: {texte}",
    "classification_v2": "Analyze and classify precisely: {texte}",
}

# Em produção, utilize uma versão específica
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Tempos Limite e Limites

Limite qualquer entrada externa antes de esta chegar à API. Um utilizador que cole um PDF de 200 páginas no seu campo de entrada não deve poder desencadear uma chamada de vários dólares ou fazer com que o pedido falhe devido a excesso de contexto. O truncamento preventivo, combinado com o limite de saída e a temperatura da configuração, torna o custo e a latência de cada chamada previsíveis.

def appel_avec_garde_fous(prompt: str) -> str:
    """Chamada API com todas as salvaguardas."""
    # Limitar o tamanho do prompt
    MAX_PROMPT_CHARS = 50000
    if len(prompt) > MAX_PROMPT_CHARS:
        prompt = prompt[:MAX_PROMPT_CHARS]
        print(f"Prompt truncated to {MAX_PROMPT_CHARS} characters")

    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # temperature requires effort none
        input=prompt,
        max_output_tokens=MAX_TOKENS,
        temperature=TEMPERATURE,
    )

    return response.output_text

4. Fallback de Modelo

Quando um modelo está saturado ou temporariamente indisponível, devolver um erro não é a sua única opção. Mudar para um modelo secundário degrada a qualidade, mas preserva o serviço — uma compensação muitas vezes preferível para um assistente de suporte, menos para análise de contratos. O ciclo itera pelos modelos por ordem de preferência e levanta uma exceção apenas se todos falharem.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Tenta o Terra e recorre ao Luna em caso de erro."""
    modeles = ["gpt-5.6-terra", "gpt-5.6-luna"]

    for modele in modeles:
        try:
            response = get_client().responses.create(
                model=modele,
                input=prompt
            )
            return response.output_text
        except (RateLimitError, InternalServerError) as e:
            print(f"{modele} unavailable: {e}")
            continue

    raise RuntimeError("All models are unavailable")

5. Processamento em Lote

Para processar mil documentos, as chamadas sequenciais são demasiado lentas e as chamadas simultâneas explodem os seus limites de taxa. Um semáforo encontra o equilíbrio certo. Dois detalhes tornam esta implementação robusta: return_exceptions=True impede que uma única falha cancele todo o lote, e a ordenação por índice restaura a ordem original, que o asyncio.gather não garante no tempo de execução.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Processa um lote de prompts com concorrência limitada."""
    client = AsyncOpenAI()
    semaphore = asyncio.Semaphore(max_concurrent)
    resultats = []

    async def traiter_un(index: int, prompt: str):
        async with semaphore:
            response = await client.responses.create(
                model="gpt-5.6-terra",
                input=prompt
            )
            return index, response.output_text

    tasks = [traiter_un(i, p) for i, p in enumerate(prompts)]
    results = await asyncio.gather(*tasks, return_exceptions=True)

    # Ordenar por índice para manter a ordem
    sorted_results = sorted(
        [(idx, res) for idx, res in results if not isinstance(res, Exception)],
        key=lambda x: x[0]
    )
    return [res for _, res in sorted_results]

# prompts = ["Question 1", "Question 2", "Question 3"]
# résultats = asyncio.run(traiter_batch(prompts))

6. Testes e Validação

Precisa de dois tipos diferentes de testes. O primeiro verifica a infraestrutura — a chave funciona, a rede passa, o modelo responde — e encaixa bem numa verificação de saúde no arranque. O segundo, mais original, testa a qualidade do próprio prompt: submete um caso onde conhece a resposta correta e verifica se esta aparece. Estas asserções são a sua rede de segurança contra regressões quando reformula um modelo.

def test_api_disponible():
    """Verifica se a API está acessível."""
    try:
        response = get_client().responses.create(
            model="gpt-5.6-terra",
            input="test",
            max_output_tokens=5
        )
        assert response.output_text is not None
        print("API OK")
        return True
    except Exception as e:
        print(f"API KO: {e}")
        return False

def test_prompt_quality(prompt: str, attendu: str) -> bool:
    """Verifica se um prompt devolve um resultado consistente."""
    response = get_client().responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        input=prompt,
        temperature=0.0
    )
    resultat = response.output_text.lower()
    return attendu.lower() in resultat

# Testes de regressão de prompts
assert test_prompt_quality(
    "Classify 'excellent product': positive or negative?",
    "positive"
)

Construa uma dúzia de casos de teste como este, representativos dos seus casos de uso reais, e execute-os sempre que modificar um prompt. Uma suíte de testes de dez minutos poupar-lhe-á semanas de dúvidas sobre a qualidade percebida.

7. Lista de Verificação de Implementação em Produção

Antes de implementar, verifique cada ponto:

Infraestrutura

  • Variáveis de ambiente configuradas (OPENAI_API_KEY, etc.)
  • Tempos limite e max_retries configurados
  • Registo estruturado implementado
  • Monitorização de custos ativada

Resiliência

  • Tratamento de erros completo (todos os códigos HTTP)
  • Backoff exponencial para novas tentativas
  • Disjuntor para indisponibilidades prolongadas
  • Fallback para um modelo alternativo

Segurança

  • Chave API nunca exposta no código ou registos
  • Validação de entrada do utilizador
  • Limitação de taxa no lado do cliente
  • Sem dados sensíveis nos prompts

Desempenho

  • Streaming ativado para interfaces de utilizador
  • Processamento em lote para tarefas de alto volume
  • Cache para pedidos repetitivos
  • Escolha do modelo adaptada a cada tarefa

Custos

  • Orçamento diário definido
  • Alertas configurados
  • max_output_tokens definido sempre que possível
  • Modelo mais económico selecionado por tarefa

Pontos-chave

  • Centralize a configuração do cliente com um singleton
  • Separe e versionar os seus prompts fora do código
  • Implemente fallback de modelo para alta disponibilidade
  • Utilize processamento em lote com concorrência limitada para volume
  • Teste os seus prompts com asserções de qualidade
  • Siga a lista de verificação completa antes de cada implementação em produção