Anti-patronen bij API's
Op deze pagina
Fouten die geld kosten in productie
Na het behandelen van best practices is het tijd om naar de keerzijde te kijken. De onderstaande anti-patronen zijn de meest voorkomende valkuilen bij het gebruik van de Chat Completions API. Ze hebben één onaangename eigenschap gemeen: ze manifesteren zich niet tijdens de ontwikkeling. Bij tien testverzoeken werkt alles prima. Pas in productie ontploffen ze, wat leidt tot onverwachte kosten, incoherente antwoorden, hoge latentie of, erger nog, lekken van gevoelige gegevens.
Een afgekapte respons als compleet beschouwen
De meest voorkomende fout is het negeren van finish_reason. U vraagt om een contract, krijgt wat tekst terug en slaat deze op in de database: behalve dat max_tokens=100 de generatie midden in een clausule heeft afgebroken, en niemand merkt het totdat de klant tekent. De oplossing vereist drie regels code en moet een reflex worden.
# SLECHT — geen verificatie
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=100 # Te kort voor een contract!
)
contract = response.choices[0].message.content # Mogelijk afgekapte tekst!
# GOED — systematische verificatie
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
Conversatiegeschiedenis onbeperkt laten groeien
De tweede valkuil manifesteert zich langzaam. Een chat-lus die bij elke beurt de volledige conversatiegeschiedenis verstuurt, werkt perfect voor de eerste tien uitwisselingen, kost het dubbele bij de twintigste en overschrijdt uiteindelijk bij de honderdste het contextvenster—waarbij de factuur dezelfde curve volgt. De oplossing is om de systeemprompt (niet-onderhandelbaar) te behouden en alleen de laatste N berichten te bewaren.
# SLECHT — geschiedenis groeit onbeperkt
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 beurten = duizenden tokens!
)
reply = response.choices[0].message.content
conversation.append({"role": "assistant", "content": reply})
# GOED — schuifend venster met inkorting
MAX_MESSAGES = 20
def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
"""Behoudt de systeemprompt + de laatste N berichten."""
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
Aannemen dat het netwerk altijd reageert
Een kale API-oproep gaat ervan uit dat er niets misgaat: geen time-outs, geen 429-fouten, geen 500-fouten. In productie gebeuren alle drie, en de derde gebeurt op het slechtst mogelijke moment. Let op het onderscheid in de code: een 429 rechtvaardigt exponentiële backoff, een serverfout vereist een seconde geduld, maar een clientfout zoals een 400 of 401 mag nooit opnieuw worden geprobeerd—uw sleutel wordt niet geldig bij de derde poging; u vertraagt alleen de diagnose.
# SLECHT — geen foutafhandeling
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
# Crasht bij time-out, 429, 500...
# GOED — opnieuw proberen met backoff
from mistralai.client.errors import SDKError
import time
def safe_complete(client, messages, max_retries=3, **kwargs):
"""API-oproep met opnieuw proberen en exponentiële backoff."""
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 # Clientfout (400, 401) — niet opnieuw proberen
raise Exception("Failed after 3 attempts")
Het model vragen wat het niet kan
Drie anti-patronen komen hier samen. De eerste is subjectieve taal: “kort”, “veel”, “interessant” verwijzen naar niets verifieerbaars, en het model zal bij elke oproep anders beslissen. Vervang elk bijvoeglijk naamwoord door een getal of een observeerbaar criterium.
# SLECHT — subjectief, niet meetbaar
"Write a short summary." # Kort = 1 zin? 1 alinea?
"Give many examples." # Veel = 3? 10? 50?
"Answer in an interesting way." # Interessant volgens welke criteria?
# GOED — objectieve criteria
"Write a summary of 50 to 80 words."
"Give exactly 5 examples, one per line."
"Start every response with a relevant statistic."
De tweede is het model laten tellen. LLM’s staan erom bekend slecht te zijn in het tellen van woorden, tekens en items: vragen om “precies 280 tekens” levert tekst op van 240 of 310. Tellwerk hoort thuis in uw applicatie, niet in het model.
# SLECHT — het model kan niet precies tellen
"Write exactly 280 characters for a tweet."
# GOED — tellen aan de kant van de applicatie
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}")
De derde valt in dezelfde familie: numerieke schalen. “Beoordeel van 1 tot 5” veronderstelt dat het model een stabiele representatie heeft van het verschil tussen 3 en 4, wat niet zo is. Een verbale schaal waarbij elke stap wordt gedefinieerd door een criterium, levert veel reproduceerbaardere beoordelingen op.
# SLECHT — modellen interpreteren numerieke schalen slecht
"Rate the quality of this text from 1 to 5."
# GOED — verbale schaal met definities
"""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."""
Implementeren zonder sporen na te laten
Het laatste anti-patroon is het meest discreet: de API aanroepen, de inhoud retourneren en niets bewaren. Op de dag dat een gebruiker een aberrante respons meldt, heeft u noch het request-ID, noch het daadwerkelijk bediende model, noch het tokenverbruik. Gestructureerde logging per oproep kost een paar milliseconden en maakt onderzoek mogelijk.
# SLECHT — geen spoor
response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
return response.choices[0].message.content
# GOED — gestructureerde logging
import logging
import json
logger = logging.getLogger("mistral_api")
def logged_complete(client, messages, **kwargs):
"""API-oproep met gestructureerde logging."""
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
Een debug-routine
Wanneer een respons niet aan uw verwachtingen voldoet, is de verleiding groot om de prompt herschrijven. Begin in plaats daarvan met vijf mechanische controles, in volgorde: Is de respons compleet? Heeft het juiste model geantwoord? Hoeveel tokens zijn verbruikt? Is de respons leeg? Is de verhouding output/input plausibel? Een verhouding onder de 1% bij een grote prompt wijst bijna altijd erop dat het model weigerde het verzoek te verwerken in plaats van het verkeerd af te handelen.
def debug_response(response):
"""Debug-checklist voor onverwachte responsen."""
choice = response.choices[0]
# 1. Is de respons compleet?
if choice.finish_reason == "length":
print("ISSUE: Response truncated — increase max_tokens")
# 2. Is het juiste model gebruikt?
print(f"Model: {response.model}")
# 3. Hoeveel tokens verbruikt?
print(f"Input tokens: {response.usage.prompt_tokens}")
print(f"Output tokens: {response.usage.completion_tokens}")
# 4. Is de respons leeg?
if not choice.message.content or not choice.message.content.strip():
print("ISSUE: Empty response")
# 5. Verdachte input/output-verhouding?
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})")
Belangrijkste punten
- Controleer altijd
finish_reasonom afkapping te detecteren - Beperk de conversatiegeschiedenis met een schuivend venster
- Implementeer opnieuw proberen met exponentiële backoff voor netwerkvouten
- Gebruik objectieve, meetbare criteria in uw prompts
- Laat het model nooit tellen—valideer aan de kant van de applicatie
- Log elke API-oproep in productie voor debugging en kostentracking