Anti-padrões da API
Nesta página
Erros que custam dinheiro em produção
Depois de abordarmos as melhores práticas, é altura de olhar para o outro lado da moeda. Os anti-padrões abaixo são as armadilhas mais comuns ao utilizar a API de Chat Completions e partilham uma característica desagradável: não surgem durante o desenvolvimento. Em dez pedidos de teste, tudo funciona perfeitamente. É em produção que falham estrondosamente, causando custos inesperados, respostas incoerentes, latência elevada ou, pior ainda, fugas de dados sensíveis.
Tratar uma resposta truncada como completa
O erro mais comum é ignorar o finish_reason. Pede um contrato, recebe algum texto, guarda-o na base de dados: exceto que max_tokens=100 cortou a geração a meio de uma cláusula e ninguém se apercebe até o cliente assinar. A correção leva três linhas de código e deve tornar-se um reflexo.
# MAU — sem verificação
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=100 # Demasiado curto para um contrato!
)
contract = response.choices[0].message.content # Potencialmente truncado!
# BOM — verificação sistemática
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=4000
)
if response.choices[0].finish_reason == "length":
print("WARNING: Response truncated, increase max_tokens")
else:
contract = response.choices[0].message.content
Deixar o histórico de conversação crescer sem limites
A segunda armadilha dispara lentamente. Um ciclo de chat que envia todo o histórico da conversação em cada turno funciona perfeitamente nas primeiras dez trocas, custa o dobro na vigésima e, eventualmente, excede a janela de contexto na centésima — com a fatura a seguir a mesma curva. A solução é manter o prompt do sistema (não negociável) e reter apenas as últimas N mensagens.
# MAU — o histórico cresce indefinidamente
conversation = []
while True:
user_input = input("You: ")
conversation.append({"role": "user", "content": user_input})
response = client.chat.complete(
model="mistral-large-latest",
messages=conversation # 100 turnos = milhares de tokens!
)
reply = response.choices[0].message.content
conversation.append({"role": "assistant", "content": reply})
# BOM — janela deslizante com corte
MAX_MESSAGES = 20
def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
"""Mantém o prompt do sistema + as últimas N mensagens."""
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
if len(history) > max_messages:
history = history[-max_messages:]
return system + history
Assumir que a rede responde sempre
Uma chamada à API nua assume que nada correrá mal: sem timeouts, sem erros 429, sem erros 500. Em produção, os três acontecem, e o terceiro ocorre no pior momento possível. Note a distinção no código: um 429 justifica um recuo exponencial, um erro de servidor merece um segundo de paciência, mas um erro do cliente como um 400 ou 401 nunca deve ser repetido — a sua chave não se tornará válida na terceira tentativa; apenas atrasará o diagnóstico.
# MAU — sem tratamento de erros
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
# Falha em timeout, 429, 500...
# BOM — repetição com recuo exponencial
from mistralai.client.errors import SDKError
import time
def safe_complete(client, messages, max_retries=3, **kwargs):
"""Chamada à API com repetição e recuo exponencial."""
for attempt in range(max_retries):
try:
return client.chat.complete(messages=messages, **kwargs)
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
print(f"Rate limit hit, waiting {wait}s...")
time.sleep(wait)
elif e.status_code >= 500:
time.sleep(1)
else:
raise # Erro do cliente (400, 401) — não repetir
raise Exception("Failed after 3 attempts")
Pedir ao modelo que faça o que não consegue fazer
Três anti-padrões convergem aqui. O primeiro é a linguagem subjetiva: “curto”, “muitos”, “interessante” não referem nada verificável, e o modelo decidirá de forma diferente de uma chamada para outra. Substitua cada adjetivo por um número ou um critério observável.
# MAU — subjetivo, não mensurável
"Write a short summary." # Curto = 1 frase? 1 parágrafo?
"Give many examples." # Muitos = 3? 10? 50?
"Answer in an interesting way." # Interessante segundo que critérios?
# BOM — critérios objetivos
"Write a summary of 50 to 80 words."
"Give exactly 5 examples, one per line."
"Start every response with a relevant statistic."
O segundo é deixar o modelo contar. Os LLMs são notoriamente maus a contar palavras, caracteres e itens: pedir “exatamente 280 caracteres” produzirá texto de 240 ou 310. A contagem pertence à sua aplicação, não ao modelo.
# MAU — o modelo não consegue contar com precisão
"Write exactly 280 characters for a tweet."
# BOM — contar no lado da aplicação
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a tweet about AI in France."}],
max_tokens=100
)
tweet = response.choices[0].message.content
if len(tweet) > 280:
tweet = tweet[:277] + "..."
print(f"Tweet ({len(tweet)} chars): {tweet}")
O terceiro enquadra-se na mesma família: escalas numéricas. “Avalie de 1 a 5” assume que o modelo tem uma representação estável da diferença entre 3 e 4, o que não é verdade. Uma escala verbal onde cada passo é definido por um critério produz classificações muito mais reproduzíveis.
# MAU — os modelos interpretam mal as escalas numéricas
"Rate the quality of this text from 1 to 5."
# BOM — escala verbal com definições
"""Rate the quality of this text according to the following scale:
- EXCELLENT: Clear, well-structured, no errors
- GOOD: Generally correct, minor improvements possible
- AVERAGE: Understandable but lacks structure or contains errors
- POOR: Difficult to understand, significant errors
- VERY POOR: Incomprehensible or off-topic
Respond only with the label in uppercase."""
Implementar sem deixar rasto
O último anti-padrão é o mais discreto: chamar a API, devolver o conteúdo e não guardar nada. No dia em que um utilizador reporta uma resposta aberrante, não tem nem o ID do pedido, nem o modelo real servido, nem o consumo de tokens. O registo estruturado por chamada custa alguns milissegundos e torna a investigação possível.
# MAU — sem rasto
response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
return response.choices[0].message.content
# BOM — registo estruturado
import logging
import json
logger = logging.getLogger("mistral_api")
def logged_complete(client, messages, **kwargs):
"""Chamada à API com registo estruturado."""
response = client.chat.complete(messages=messages, **kwargs)
logger.info(json.dumps({
"request_id": response.id,
"model": response.model,
"prompt_tokens": response.usage.prompt_tokens,
"completion_tokens": response.usage.completion_tokens,
"finish_reason": response.choices[0].finish_reason
}))
return response
Uma rotina de depuração
Quando uma resposta não corresponde às suas expectativas, a tentação é reescrever o prompt. Em vez disso, comece com cinco verificações mecânicas, por ordem: A resposta está completa? O modelo correto respondeu? Quantos tokens foram consumidos? A resposta está vazia? A relação output/input é plausível? Uma relação abaixo de 1% num prompt grande sinaliza quase sempre que o modelo se recusou a processar o pedido em vez de o ter manuseado mal.
def debug_response(response):
"""Lista de verificação de depuração para respostas inesperadas."""
choice = response.choices[0]
# 1. A resposta está completa?
if choice.finish_reason == "length":
print("ISSUE: Response truncated — increase max_tokens")
# 2. Foi utilizado o modelo correto?
print(f"Model: {response.model}")
# 3. Quantos tokens foram consumidos?
print(f"Input tokens: {response.usage.prompt_tokens}")
print(f"Output tokens: {response.usage.completion_tokens}")
# 4. A resposta está vazia?
if not choice.message.content or not choice.message.content.strip():
print("ISSUE: Empty response")
# 5. Relação input/output suspeita?
ratio = response.usage.completion_tokens / max(response.usage.prompt_tokens, 1)
if ratio < 0.01:
print(f"WARNING: Very low output/input ratio ({ratio:.4f})")
Pontos-chave
- Verifique sempre o
finish_reasonpara detetar truncagem - Limite o histórico de conversação com uma janela deslizante
- Implemente repetição com recuo exponencial para erros de rede
- Utilize critérios objetivos e mensuráveis nos seus prompts
- Nunca deixe o modelo contar — valide no lado da aplicação
- Registe cada chamada à API em produção para depuração e controlo de custos