Best Practices voor Productie
Op deze pagina
Van Proof of Concept naar Implementatie
U beheerst nu elke parameter van de Chat Completions API. Het lastigste deel blijft echter: de kloof overbruggen tussen een werkend notebook en een dienst die anderen zonder uw tussenkomst gebruiken. Deze laatste les bundelt de volledige cursus tot een actieproductiechecklist en wijst vervolgens de weg naar vervolgcursussen.
Authenticatie en Modelversiebeheer
Twee beslissingen gaan aan de eerste regel bedrijfslogica vooraf. De eerste betreft de API-sleutel: deze staat in een omgevingsvariabele, nooit in de code, en een startup-controle voorkomt dat een None zich drie lagen dieper voortplant tot een onbegrijpelijke foutmelding. Plan ook rotatie in: maak de nieuwe sleutel aan, implementeer deze en trek vervolgens de oude in, in die volgorde, als u wilt voorkomen dat de dienst offline gaat.
import os
# ALTIJD: API-sleutel in omgevingsvariabele
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY niet gedefinieerd"
# NOOIT: hardcoded sleutel in code
# api_key = "sk-abc123..." # VERBODEN in productie
# ALTIJD: regelmatige sleutelrotatie
# Maak een nieuwe sleutel aan, implementeer deze en trek vervolgens de oude in
De tweede beslissing betreft de modelidentificatie. Tijdens de ontwikkeling geeft -latest u verbeteringen zonder inspanning. In productie betekent diezelfde alias echter dat een versiewijziging aan de kant van de provider het gedrag van uw applicatie kan wijzigen zonder waarschuwing, op een dinsdagochtend, zonder commit-spoor om het uit te leggen. Pin de versie vast.
# ONTWIKKELING — laatste versie
model = "mistral-large-latest"
# PRODUCTIE — vaste versie voor reproduceerbaarheid
model = "mistral-large-2512"
# Waarom? Een wijziging in "latest" kan het gedrag van uw applicatie
# zonder waarschuwing wijzigen.
Een Client die Incidenten Afhandelt
Het hart van een productie-integratie is niet de API-aanroep, maar alles eromheen. De onderstaande klasse bundelt drie verantwoordelijkheden in één knelpunt: opnieuw proberen met exponentiële back-off bij 429-fouten, een korte pauze bij serverfouten en onmiddellijke escalatie van clientfouten die door geen enkele retry opgelost worden. Het normaliseert ook het antwoord naar een stabiel dictionary—inhoud, finish_reason, gebruik, model, ID—zodat de rest van uw code niet langer afhankelijk is van de exacte vorm van het object dat door de SDK wordt teruggegeven. De logger.warning bij truncaties alleen al rechtvaardigt de encapsulatie: het is de enige manier om erachter te komen dat een max_tokens-instelling te krap is voordat gebruikers erover klagen.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging
logger = logging.getLogger(__name__)
class MistralClient:
"""Productieclient met retry, timeout en logging."""
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,
}
# Waarschuwing als antwoord is ingekort
if result["finish_reason"] == "length":
logger.warning(f"Antwoord ingekort — req_id={response.id}")
return result
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
logger.warning(f"Ratelimit, retry {attempt+1}/{self.max_retries} in {wait}s")
time.sleep(wait)
elif e.status_code >= 500:
logger.error(f"Serverfout {e.status_code}, retry {attempt+1}")
time.sleep(1)
else:
logger.error(f"Clientfout {e.status_code}: {e.message}")
raise
raise Exception(f"Mislukt na {self.max_retries} pogingen")
Kosten Bijhouden Terwijl Ze Ontstaan
Het ontdekken van uw verbruik op de maandelijkse factuur is een luxe die weinig teams zich kunnen veroorloven. De onderstaande tracker schrijft één JSONL-regel per aanroep—tijdstempel, model, input- en outputtokens, finish_reason, request-ID—en houdt een sessietotaal bij dat u op elk moment kunt opvragen. Het JSONL-formaat is geen detail: het aggregeert met elke analysetool zonder parse-stap, en de aanwezigheid van de request-ID stelt u in staat een kostenafwijking aan een specifieke aanroep te koppelen.
import json
from datetime import datetime, timezone
class CostTracker:
"""Real-time API-kostentracking."""
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"Sessie — Prompt: {self.session_tokens['prompt']:,} | "
f"Completion: {self.session_tokens['completion']:,} | "
f"Totaal: {total:,} tokens"
)
Valideren aan Beide Kanten
Een robuuste applicatie vertrouwt noch op wat erin gaat, noch op wat eruit komt. Bij input wijst u lege berichten af, beperkt u de lengte tot 10.000 tekens om te voorkomen dat een ongelukkige copy-paste uw factuur doet exploderen, en verwijdert u besturingstekens die de tokenisatie verstoren. Bij output wijst u niets af, maar geeft u wel waarschuwingen: mogelijk ingekort antwoord, abnormaal kort antwoord onder de vijf tekens, abnormaal lang antwoord boven de 50.000. Deze drie signalen vangen het overgrote deel van de stille fouten op.
def validate_input(user_message: str) -> str:
"""Valideer en reinig gebruikersinput."""
if not user_message or not user_message.strip():
raise ValueError("Leeg bericht")
if len(user_message) > 10_000:
raise ValueError("Bericht te lang (max 10.000 tekens)")
# Verwijder besturingstekens
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:
"""Valideer API-output."""
warnings = []
if finish_reason == "length":
warnings.append("Antwoord mogelijk ingekort")
if not content or len(content.strip()) < 5:
warnings.append("Abnormaal kort antwoord")
if len(content) > 50_000:
warnings.append("Abnormaal lang antwoord")
return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}
Het Contextvenster Beheren
Een laatste punt: de langzame drift van lange gesprekken. De onderstaande functie schat het volume op één token per vier tekens in het Frans—een ruwe benadering, maar voldoende als veiligheidsmarge—en laat verzoeken toe zolang ze onder de 80% van de limiet blijven. Daarboven behoudt het de systeemprompt en verwijdert het de oudste berichten totdat het weer onder de 70% zakt. Deze kloof tussen de twee drempels is opzettelijk: alleen snijden tot de triggerdrempel zou de functie bij het volgende bericht weer in het rood duwen.
def manage_context(messages: list, max_tokens: int = 100_000) -> list:
"""Houd berichten binnen de tokenlimiet van het model."""
# Schatting: 1 token ~ 4 tekens in het Frans
total_chars = sum(len(m["content"]) for m in messages)
estimated_tokens = total_chars // 4
if estimated_tokens < max_tokens * 0.8:
return messages # Alles past
# Behoud systeem + eerste en laatste berichten
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
# Verwijder oudste berichten
while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
removed = history.pop(0)
estimated_tokens -= len(removed["content"]) // 4
return system + history
Wat U Meeneemt uit Deze Cursus
De reis volgde vier stappen. Ten eerste de fundamenten: het endpoint, rollen, basisparameters en responsstructuur. Vervolgens streaming, met het SSE-protocol, de Python-implementatie, stop-sequenties en hardening via safe_prompt en guardrails. Prompting nam de derde fase in beslag—productie systeemprompts, few-shot, XML- en Markdown-structurering, anti-patronen. Geavanceerde parameters sloot de cirkel: temperatuur en Top P in detail, presence- en frequency-penalties, N completions, en deze productiechecklist.
De onderstaande configuratie destilleert deze keuzes tot een verdedigbaar startpunt voor een eerste productie-implementatie: vaste versie, tokenplafond afgestemd op de use case, lage temperatuur voor feitelijke consistentie, top_p ongewijzigd aangezien de temperatuur is aangepast, neutrale penalties tenzij een specifieke behoefte ze rechtvaardigt, en safe_prompt ingeschakeld.
# Typische configuratie voor een productieapplicatie
PRODUCTION_CONFIG = {
"model": "mistral-large-2512", # Vaste versie
"max_tokens": 2000, # Afgestemd op use case
"temperature": 0.3, # Consistent en feitelijk
"top_p": 1.0, # Ongewijzigd als temperatuur is aangepast
"presence_penalty": 0.0, # Standaard tenzij specifieke behoefte
"frequency_penalty": 0.0, # Standaard tenzij specifieke behoefte
"safe_prompt": True, # Veiligheid ingeschakeld
}
Om verder te gaan met de Mistral API, volgen vier aanvullende cursussen op Corsen Academy:
- Embeddings en RAG — Semantisch zoeken met
mistral-embeden vector databases - Function Calling — Verbind het model met uw tools en externe API’s
- Fine-tuning — Pas een model aan uw specifieke domein aan
- Productie en Evaluatie — Metrieken, geautomatiseerde evals, kostenoptimalisatie
Belangrijkste punten
- Gebruik versiebeheerde modellen in productie, nooit
-latest - Implementeer retry + backoff + logging vanaf de eerste implementatie
- Valideer zowel inputs ALS outputs van elke API-aanroep
- Houd kosten in real-time bij met een tokentracker
- Beheer het contextvenster voor lange gesprekken
- Schakel
safe_promptin als minimaal veiligheidsnet - Test uw prompts met edge cases voor elke productierelease
Test Uw Kennis
Geen geheimen meer in het chat/completions-endpoint? Laten we het verifiëren.
1. Welke rollen structureren de berichtenlijst?
Antwoord: system (het kader), user (verzoeken), assistant (modelantwoorden)—de volledige geschiedenis start bij elke aanroep opnieuw, aangezien de API stateless is.
2. Wat vindt u in het usage-veld van het antwoord?
Antwoord: Tokens verbruikt bij input en output—de basis voor facturering en de metriek om in de gaten te houden voor schaal en kosten.
3. Hoe werkt SSE-streaming?
Antwoord: Het antwoord komt binnen als Server-Sent Events, fragment voor fragment: u toont het terwijl het binnenkomt en concateneert het om het uiteindelijke bericht te krijgen.
4. Waar dienen stop-sequenties voor?
Antwoord: Om de generatie af te breken zodra een bepaalde string verschijnt: lengte beheersen, stoppen bij een delimiter, schone formaten garanderen.
5. Temperatuur, Top P, penalties: welk gebruik in productie?
Antwoord: Temperatuur/Top P stellen determinisme per taak in; presence/frequency-penalties beperken herhaling—instellingen om per use case vast te leggen en te documenteren naast uw prompts.
Rollen, gebruik, streaming, stops, tuning: de fundamenten staan—de bovenstaande best practices voor productie brengen ze in orde.