Osvědčené postupy pro nasazení
Na této stránce
Od prototypu k nasazení
Nyní ovládáš každý parametr API Chat Completions. To nejtěžší však teprve přijde: překlenout propast mezi fungujícím notebookem a službou, kterou ostatní používají bez tvého zásahu. Tato závěrečná lekce shrnuje celý kurz do akčního kontrolního seznamu pro produkci a ukazuje směr následných kurzů.
Autentizace a verzování modelů
Než napíšeš první řádek obchodní logiky, musíš učinit dvě rozhodnutí. První se týká API klíče: musí žít v proměnné prostředí, nikdy ne v kódu, a ověření při startu je lepší než None, která se propaguje o tři vrstvy níže do nepochopitelné chybové zprávy. Plánuj také rotaci – pokud chceš předejít výpadku služby, vytvoř nový klíč, nasaď ho a teprve poté zruš ten starý, přesně v tomto pořadí.
import os
# VŽDY: API klíč v proměnné prostředí
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY not defined"
# NIKDY: klíč natvrdo v kódu
# api_key = "sk-abc123..." # V PROVOZU ZAKÁZÁNO
# VŽDY: pravidelná rotace klíčů
# Vytvoř nový klíč, nasaď ho, poté zruš starý
Druhé rozhodnutí se týká identifikátoru modelu. Ve vývoji ti -latest přináší vylepšení bez námahy. V produkci však stejný alias znamená, že změna verze na straně poskytovatele může změnit chování tvé aplikace bez varování, třeba v úterý ráno, bez jakékoli stopy v commitu, která by to vysvětlila. Připni verzi.
# VÝVOJ — nejnovější verze
model = "mistral-large-latest"
# PRODUKCE — pevná verze pro reprodukovatelnost
model = "mistral-large-2512"
# Proč? Změna „latest“ může změnit chování tvé aplikace
# bez varování.
Klient, který zvládá incidenty
Srdcem produkční integrace není volání API, ale vše kolem něj. Níže uvedená třída sdružuje tři odpovědnosti do jediného kontrolního bodu: opakování s exponenciálním backoffem u chyb 429, krátkou pauzu u chyb serveru a okamžité eskalování chyb klienta, které žádné opakování neopraví. Také normalizuje odpověď do stabilního slovníku – obsah, finish_reason, využití, model, ID – takže zbytek tvého kódu již není závislý na přesné struktuře objektu vráceného SDK. Samotné logger.warning při oříznutí ospravedlňuje zapouzdření: je to jediný způsob, jak zjistit, že nastavení max_tokens je příliš těsné, dříve než si to stěžují uživatelé.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging
logger = logging.getLogger(__name__)
class MistralClient:
"""Produkční klient s opakováním, časovým limitem a logováním."""
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,
}
# Upozornění, pokud byla odpověď oříznuta
if result["finish_reason"] == "length":
logger.warning(f"Response truncated — req_id={response.id}")
return result
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
logger.warning(f"Rate limit, retry {attempt+1}/{self.max_retries} in {wait}s")
time.sleep(wait)
elif e.status_code >= 500:
logger.error(f"Server error {e.status_code}, retry {attempt+1}")
time.sleep(1)
else:
logger.error(f"Client error {e.status_code}: {e.message}")
raise
raise Exception(f"Failed after {self.max_retries} attempts")
Sleduj náklady v reálném čase
Zjišťování spotřeby až z měsíčního vyúčtování je luxus, který si málo týmů může dovolit. Níže uvedený sledovač zapisuje jeden řádek JSONL na volání – časové razítko, model, vstupní a výstupní tokeny, finish_reason, ID požadavku – a udržuje celkový součet relace, který můžeš kdykoli dotazovat. Formát JSONL není detail: agreguje se s jakýmkoli analytickým nástrojem bez kroku parsování a přítomnost ID požadavku ti umožňuje spojit anomálii v nákladech s konkrétním voláním.
import json
from datetime import datetime, timezone
class CostTracker:
"""Sledování nákladů na API v reálném čase."""
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"Session — Prompt: {self.session_tokens['prompt']:,} | "
f"Completion: {self.session_tokens['completion']:,} | "
f"Total: {total:,} tokens"
)
Validuj na obou koncích
Robustní aplikace nedůvěřuje tomu, co jde dovnitř, ani tomu, co vychází ven. Na vstupu zamítni prázdné zprávy, omez délku na 10 000 znaků, aby se nešťastné kopírování a vkládání nestalo důvodem nafouknutí účtu, a odstraň řídicí znaky, které narušují tokenizaci. Na výstupu nic nezamítej, ale vydávej upozornění: potenciálně oříznutá odpověď, abnormálně krátká odpověď pod pět znaků, abnormálně dlouhá odpověď nad 50 000. Tyto tři signály zachytí drtivou většinu tichých selhání.
def validate_input(user_message: str) -> str:
"""Validace a čištění uživatelského vstupu."""
if not user_message or not user_message.strip():
raise ValueError("Empty message")
if len(user_message) > 10_000:
raise ValueError("Message too long (max 10,000 characters)")
# Vyčištění řídicích znaků
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:
"""Validace výstupu API."""
warnings = []
if finish_reason == "length":
warnings.append("Response potentially truncated")
if not content or len(content.strip()) < 5:
warnings.append("Abnormally short response")
if len(content) > 50_000:
warnings.append("Abnormally long response")
return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}
Udržuj kontextové okno
Poslední problém: pomalý drift dlouhých konverzací. Funkce níže odhaduje objem jako jeden token na čtyři znaky ve francouzštině – hrubá aproximace, ale dostatečná jako ochranná bariéra – a nechá požadavky projít, dokud zůstávají pod 80 % limitu. Nad touto hranicí zachová systémový prompt a odstraní nejstarší zprávy, dokud se nedostane zpět pod 70 %. Tento rozdíl mezi dvěma prahy je záměrný: oříznutí pouze na spouštěcí práh by funkci při další zprávě znovu dostalo do červených čísel.
def manage_context(messages: list, max_tokens: int = 100_000) -> list:
"""Udržování zpráv v rámci limitu tokenů modelu."""
# Odhad: 1 token ~ 4 znaky ve francouzštině
total_chars = sum(len(m["content"]) for m in messages)
estimated_tokens = total_chars // 4
if estimated_tokens < max_tokens * 0.8:
return messages # Vše se vejde
# Zachování systému + první a poslední zprávy
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
# Odstranění nejstarších zpráv
while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
removed = history.pop(0)
estimated_tokens -= len(removed["content"]) // 4
return system + history
Co si z tohoto kurzu odnášíš
Cesta prošla čtyřmi kroky. Nejprve základy: koncový bod, role, základní parametry a struktura odpovědi. Dále streamování s protokolem SSE, jeho implementací v Pythonu, stop sekvencemi a zabezpečením prostřednictvím safe_prompt a guardrails. Třetí fázi zabralo tvoření promptů – produkční systémové prompty, few-shot, strukturování pomocí XML a Markdownu, anti-vzory. Pokročilé parametry uzavřely kruh: teplota a Top P v detailu, penalizace přítomnosti a frekvence, N dokončení a tento produkční kontrolní seznam.
Níže uvedená konfigurace destiluje tato rozhodnutí do obhajitelného výchozího bodu pro první produkční nasazení: pevná verze, strop tokenů přizpůsobený případu použití, nízká teplota pro faktickou konzistenci, top_p nezměněno, protože je upravena teplota, neutrální penalizace, pokud je specifická potřeba neodůvodňuje jinak, a povolené safe_prompt.
# Typická konfigurace pro produkční aplikaci
PRODUCTION_CONFIG = {
"model": "mistral-large-2512", # Pevná verze
"max_tokens": 2000, # Přizpůsobeno případu použití
"temperature": 0.3, # Konzistentní a faktické
"top_p": 1.0, # Nezměněno, pokud je upravena teplota
"presence_penalty": 0.0, # Výchozí, pokud není specifická potřeba
"frequency_penalty": 0.0, # Výchozí, pokud není specifická potřeba
"safe_prompt": True, # Bezpečnost povolena
}
Pokud chceš jít s Mistral API dál, na Corsen Academy následují čtyři doplňkové kurzy:
- Embeddings a RAG – Sémantické vyhledávání s
mistral-embeda vektorovými databázemi - Function Calling – Propojení modelu s tvými nástroji a externími API
- Fine-tuning – Přizpůsobení modelu tvé specifické doméně
- Produkce a evaluace – Metriky, automatizované evaluace, optimalizace nákladů
Klíčové poznatky
- V produkci používej verzované modely, nikdy
-latest - Implementuj opakování + backoff + logování již od prvního nasazení
- Validuj vstupy I výstupy každého volání API
- Sleduj náklady v reálném čase pomocí sledovače tokenů
- Spravuj kontextové okno pro dlouhé konverzace
- Povol
safe_promptjako minimální bezpečnostní síť - Před každým produkčním vydáním testuj své prompty s hraničními případy
Ověř si své znalosti
Žádná tajemství v koncovém bodě chat/completions? Pojďme to ověřit.
1. Které role strukturoují seznam zpráv?
Odpověď: system (rámec), user (požadavky), assistant (odpovědi modelu) – celá historie se při každém volání restartuje, protože API je bezstavové.
2. Co najdeš v poli usage odpovědi?
Odpověď: Tokeny spotřebované na vstupu a výstupu – základ pro fakturaci a metrika, kterou je třeba sledovat pro dimenzování a náklady.
3. Jak funguje streamování SSE?
Odpověď: Odpověď přichází jako Server-Sent Events, fragment po fragmentu: zobrazuješ je, jak přicházejí, a zřetězením získáš finální zprávu.
4. K čemu slouží stop sekvence?
Odpověď: K ukončení generování, jakmile se objeví daný řetězec: kontrola délky, zastavení na oddělovači, zajištění čistých formátů.
5. Teplota, Top P, penalizace: jaké použití v produkci?
Odpověď: Teplota/Top P nastavují determinismus podle úkolu; penalizace přítomnosti/frekvence omezují opakování – nastavení, která je třeba fixovat pro každý případ použití a dokumentovat alongside svých promptů.
Role, využití, streamování, stopy, ladění: základy platí – výše uvedené osvědčené postupy pro produkci je dávají do pořádku.