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

Boas Práticas de Produção

Aula 16 de 16 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Da Prova de Conceito à Implementação
  2. Autenticação e Versionamento de Modelos
  3. Um Cliente que Gere Incidentes
  4. Acompanhe os Custos em Tempo Real
  5. Valide em Ambas as Extremidades
  6. Mantenha a Janela de Contexto
  7. O Que Retém Deste Curso
  8. Pontos-chave
  9. Teste os Seus Conhecimentos

Da Prova de Conceito à Implementação

Agora domina todos os parâmetros da API de Completions de Chat. A parte mais delicada permanece: colmatar o fosso entre um caderno funcional e um serviço que outros utilizam sem a sua intervenção. Esta última lição consolida todo o curso numa lista de verificação de produção acionável e indica o caminho para os cursos de acompanhamento.

Autenticação e Versionamento de Modelos

Duas decisões antecedem a primeira linha de lógica de negócio. A primeira diz respeito à chave da API: esta deve residir numa variável de ambiente, nunca no código, e uma asserção no arranque é preferível a um None que se propaga por três camadas até gerar uma mensagem de erro incompreensível. Planeie também a rotação — crie a nova chave, implemente-a e, só depois, revogue a antiga, por esta ordem, se quiser evitar colocar o serviço fora de linha.

import os

# SEMPRE: Chave da API em variável de ambiente
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY não definida"

# NUNCA: Chave codificada no código
# api_key = "sk-abc123..."  # PROIBIDO em produção

# SEMPRE: Rotação regular de chaves
# Criar uma nova chave, implementá-la e, depois, revogar a antiga

A segunda decisão concerne o identificador do modelo. Em desenvolvimento, -latest oferece melhorias sem esforço. Em produção, esse mesmo alias significa que uma alteração de versão da parte do fornecedor pode modificar o comportamento da sua aplicação sem aviso, numa terça-feira de manhã, sem qualquer registo de commit para o explicar. Fixe a versão.

# DESENVOLVIMENTO — versão mais recente
model = "mistral-large-latest"

# PRODUÇÃO — versão fixa para reprodutibilidade
model = "mistral-large-2512"

# Porquê? Uma alteração "latest" pode modificar o comportamento da sua aplicação
# sem aviso prévio.

Um Cliente que Gere Incidentes

O coração de uma integração de produção não é a chamada à API, mas tudo o que a envolve. A classe abaixo agrupa três responsabilidades num único ponto de estrangulamento: nova tentativa com recuo exponencial em caso de erro 429, uma breve pausa em erros de servidor e escalada imediata de erros de cliente que nenhuma nova tentativa resolverá. Normaliza também a resposta num dicionário estável — conteúdo, finish_reason, utilização, modelo, ID — para que o resto do seu código deixe de depender da forma exata do objeto devolvido pelo SDK. O logger.warning nas truncaturas, por si só, justifica o encapsulamento: é a única forma de descobrir que uma definição de max_tokens é demasiado restritiva antes que os utilizadores o reportem.

from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging

logger = logging.getLogger(__name__)

class MistralClient:
    """Cliente de produção com nova tentativa, tempo limite e registo."""

    def __init__(self, api_key: str, max_retries: int = 3):
        self.client = Mistral(api_key=api_key)
        self.max_retries = max_retries

    def complete(self, messages: list, **kwargs) -> dict:
        for attempt in range(self.max_retries):
            try:
                response = self.client.chat.complete(
                    messages=messages,
                    **kwargs
                )

                result = {
                    "content": response.choices[0].message.content,
                    "finish_reason": response.choices[0].finish_reason,
                    "usage": {
                        "prompt": response.usage.prompt_tokens,
                        "completion": response.usage.completion_tokens,
                        "total": response.usage.total_tokens,
                    },
                    "model": response.model,
                    "id": response.id,
                }

                # Alertar se a resposta for truncada
                if result["finish_reason"] == "length":
                    logger.warning(f"Resposta truncada — req_id={response.id}")

                return result

            except SDKError as e:
                if e.status_code == 429:
                    wait = 2 ** attempt
                    logger.warning(f"Limite de taxa, nova tentativa {attempt+1}/{self.max_retries} em {wait}s")
                    time.sleep(wait)
                elif e.status_code >= 500:
                    logger.error(f"Erro de servidor {e.status_code}, nova tentativa {attempt+1}")
                    time.sleep(1)
                else:
                    logger.error(f"Erro de cliente {e.status_code}: {e.message}")
                    raise

        raise Exception(f"Falhou após {self.max_retries} tentativas")

Acompanhe os Custos em Tempo Real

Descobrir o seu consumo na fatura mensal é um luxo que poucas equipas podem permitir-se. O rastreador abaixo escreve uma linha JSONL por chamada — carimbo de data/hora, modelo, tokens de entrada e saída, finish_reason, ID do pedido — e mantém um total de sessão que pode consultar a qualquer momento. O formato JSONL não é um detalhe: agrega-se com qualquer ferramenta de análise sem etapa de análise sintática, e a presença do ID do pedido permite ligar uma anomalia de custos a uma chamada específica.

import json
from datetime import datetime, timezone

class CostTracker:
    """Rastreamento de custos da API em tempo real."""

    def __init__(self, log_path: str = "api_costs.jsonl"):
        self.log_path = log_path
        self.session_tokens = {"prompt": 0, "completion": 0}

    def log(self, response_data: dict):
        usage = response_data["usage"]
        self.session_tokens["prompt"] += usage["prompt"]
        self.session_tokens["completion"] += usage["completion"]

        entry = {
            "ts": datetime.now(timezone.utc).isoformat(),
            "model": response_data["model"],
            "prompt_tokens": usage["prompt"],
            "completion_tokens": usage["completion"],
            "finish_reason": response_data["finish_reason"],
            "id": response_data["id"],
        }

        with open(self.log_path, "a") as f:
            f.write(json.dumps(entry) + "\n")

    def report(self) -> str:
        total = self.session_tokens["prompt"] + self.session_tokens["completion"]
        return (
            f"Sessão — Prompt: {self.session_tokens['prompt']:,} | "
            f"Conclusão: {self.session_tokens['completion']:,} | "
            f"Total: {total:,} tokens"
        )

Valide em Ambas as Extremidades

Uma aplicação robusta não confia nem no que entra nem no que sai. Na entrada, rejeite mensagens vazias, limite o comprimento a 10.000 caracteres para evitar que um copiar-colar infeliz inflacione a sua fatura e remova caracteres de controlo que perturbam a tokenização. Na saída, não rejeite nada, mas emita avisos: resposta potencialmente truncada, resposta anormalmente curta (menos de cinco caracteres), resposta anormalmente longa (mais de 50.000). Estes três sinais detetam a vasta maioria das falhas silenciosas.

def validate_input(user_message: str) -> str:
    """Validar e limpar a entrada do utilizador."""
    if not user_message or not user_message.strip():
        raise ValueError("Mensagem vazia")

    if len(user_message) > 10_000:
        raise ValueError("Mensagem demasiado longa (máx. 10.000 caracteres)")

    # Limpar caracteres de controlo
    cleaned = "".join(c for c in user_message if c.isprintable() or c in "\n\t")
    return cleaned.strip()

def validate_output(content: str, finish_reason: str) -> dict:
    """Validar a saída da API."""
    warnings = []

    if finish_reason == "length":
        warnings.append("Resposta potencialmente truncada")

    if not content or len(content.strip()) < 5:
        warnings.append("Resposta anormalmente curta")

    if len(content) > 50_000:
        warnings.append("Resposta anormalmente longa")

    return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}

Mantenha a Janela de Contexto

Uma última questão: a deriva lenta das conversas longas. A função abaixo estima o volume em um token por cada quatro caracteres em português — uma aproximação grosseira, mas suficiente como guarda-rail — e permite a passagem de pedidos enquanto estes se mantiverem abaixo de 80% do limite. Para além disso, preserva o prompt do sistema e remove as mensagens mais antigas até voltar a descer abaixo de 70%. Esta lacuna entre os dois limiares é deliberada: cortar apenas até ao limiar de acionamento faria com que a função voltasse a entrar na zona vermelha na mensagem seguinte.

def manage_context(messages: list, max_tokens: int = 100_000) -> list:
    """Manter as mensagens dentro do limite de tokens do modelo."""
    # Estimativa: 1 token ~ 4 caracteres em português
    total_chars = sum(len(m["content"]) for m in messages)
    estimated_tokens = total_chars // 4

    if estimated_tokens < max_tokens * 0.8:
        return messages  # Tudo cabe

    # Manter sistema + primeira e última mensagens
    system = [m for m in messages if m["role"] == "system"]
    history = [m for m in messages if m["role"] != "system"]

    # Remover mensagens mais antigas
    while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
        removed = history.pop(0)
        estimated_tokens -= len(removed["content"]) // 4

    return system + history

O Que Retém Deste Curso

O percurso seguiu quatro passos. Primeiro, os fundamentos: o endpoint, papéis, parâmetros básicos e estrutura da resposta. Em seguida, a transmissão em fluxo (streaming), com o protocolo SSE, a sua implementação em Python, sequências de paragem e reforço via safe_prompt e guard-rails. A engenharia de prompts ocupou a terceira fase — prompts de sistema de produção, few-shot, estruturação em XML e Markdown, anti-padrões. Os parâmetros avançados fecharam o ciclo: temperatura e Top P em detalhe, penalizações de presença e frequência, N completions e esta lista de verificação de produção.

A configuração abaixo destila estas escolhas num ponto de partida defensável para uma primeira implementação em produção: versão fixa, teto de tokens adequado ao caso de uso, baixa temperatura para consistência factual, top_p intocado uma vez ajustada a temperatura, penalizações neutras a menos que uma necessidade específica as justifique e safe_prompt ativado.

# Configuração típica para uma aplicação de produção
PRODUCTION_CONFIG = {
    "model": "mistral-large-2512",      # Versão fixa
    "max_tokens": 2000,                  # Adequado ao caso de uso
    "temperature": 0.3,                  # Consistente e factual
    "top_p": 1.0,                        # Intocado se a temperatura for ajustada
    "presence_penalty": 0.0,             # Padrão, salvo necessidade específica
    "frequency_penalty": 0.0,            # Padrão, salvo necessidade específica
    "safe_prompt": True,                 # Segurança ativada
}

Para ir mais longe com a API da Mistral, quatro cursos complementares seguem-se na Corsen Academy:

  • Embeddings e RAG — Pesquisa semântica com mistral-embed e bases de dados vetoriais
  • Chamada de Funções (Function Calling) — Ligar o modelo às suas ferramentas e APIs externas
  • Ajuste Fino (Fine-tuning) — Adaptar um modelo ao seu domínio específico
  • Produção e Avaliação — Métricas, avaliações automatizadas, otimização de custos

Pontos-chave

  • Utilize modelos versionados em produção, nunca -latest
  • Implemente nova tentativa + recuo exponencial + registo desde a primeira implementação
  • Valide tanto as entradas COMO as saídas de cada chamada à API
  • Acompanhe os custos em tempo real com um rastreador de tokens
  • Gerencie a janela de contexto para conversas longas
  • Ative safe_prompt como rede de segurança mínima
  • Teste os seus prompts com casos extremos antes de cada lançamento em produção

Teste os Seus Conhecimentos

Já não há segredos no endpoint chat/completions? Vamos verificar.

1. Quais papéis estruturam a lista de mensagens?

Resposta: system (o enquadramento), user (pedidos), assistant (respostas do modelo) — o histórico completo reinicia a cada chamada, pois a API é stateless.

2. O que encontra no campo usage da resposta?

Resposta: Tokens consumidos na entrada e na saída — a base para a faturação e a métrica a vigiar para dimensionamento e custos.

3. Como funciona a transmissão em fluxo (streaming) SSE?

Resposta: A resposta chega como Eventos Enviados pelo Servidor (Server-Sent Events), fragmento por fragmento: exibe à medida que chega e concatena para obter a mensagem final.

4. Para que servem as sequências de paragem?

Resposta: Para cortar a geração assim que uma determinada cadeia aparece: controlar o comprimento, parar num delimitador, garantir formatos limpos.

5. Temperatura, Top P, penalizações: qual a utilização em produção?

Resposta: Temperatura/Top P definem o determinismo por tarefa; as penalizações de presença/frequência limitam a repetição — definições a fixar por caso de uso e a documentar juntamente com os seus prompts.

Papéis, utilização, transmissão em fluxo, paragens, afinação: os fundamentos mantêm-se — as boas práticas de produção acima colocam-nos em ordem.