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

Anti-padrões da API

Aula 12 de 16 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Erros que custam dinheiro em produção
  2. Tratar uma resposta truncada como completa
  3. Deixar o histórico de conversação crescer sem limites
  4. Assumir que a rede responde sempre
  5. Pedir ao modelo que faça o que não consegue fazer
  6. Implementar sem deixar rasto
  7. Uma rotina de depuração
  8. Pontos-chave

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_reason para 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