Boas Práticas de Produção
Nesta página
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-embede 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_promptcomo 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.