Najlepsze praktyki produkcyjne
Na tej stronie
Od dowodu koncepcji do wdrożenia
Znasz już każdy parametr API Chat Completions. Najtrudniejsza część wciąż przed Tobą: pokonanie przepaści między działającym notatnikiem a usługą, z której inni korzystają bez Twojej interwencji. Ta ostatnia lekcja scala cały kurs w działającą listę kontrolną dla środowiska produkcyjnego, a następnie wskazuje kierunek dalszych szkoleń.
Uwierzytelnianie i wersjonowanie modeli
Dwie decyzje musisz podjąć przed napisaniem pierwszej linii logiki biznesowej. Pierwsza dotyczy klucza API: musi on znajdować się w zmiennej środowiskowej, nigdy w kodzie, a asercja przy starcie jest lepsza niż None, które propaguje się trzy warstwy w dół, generując niezrozumiały komunikat błędu. Zaplanuj także rotację – jeśli chcesz uniknąć przestoju usługi, najpierw utwórz nowy klucz, wdróż go, a dopiero potem unieważnij stary.
import os
# ZAWSZE: klucz API w zmiennej środowiskowej
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY not defined"
# NIGDY: klucz na sztywno w kodzie
# api_key = "sk-abc123..." # ZABRONIONE w produkcji
# ZAWSZE: regularna rotacja kluczy
# Utwórz nowy klucz, wdróż go, a następnie unieważnij stary
Druga decyzja dotyczy identyfikatora modelu. W fazie rozwoju -latest daje Ci ulepszenia bez wysiłku. W produkcji ten sam alias oznacza, że zmiana wersji po stronie dostawcy może zmienić zachowanie Twojej aplikacji bez ostrzeżenia, we wtorek rano, bez żadnego śladu w commitcie, który by to wyjaśniał. Przypnij wersję.
# ROZWÓJ — najnowsza wersja
model = "mistral-large-latest"
# PRODUKCJA — stała wersja dla powtarzalności
model = "mistral-large-2512"
# Dlaczego? Zmiana „latest“ może zmienić zachowanie Twojej aplikacji
# bez ostrzeżenia.
Klient obsługujący incydenty
Sercem integracji produkcyjnej nie jest wywołanie API, ale wszystko wokół niego. Poniższa klasa łączy trzy obowiązki w jednym punkcie kontrolnym: ponawianie z wykładniczym opóźnieniem przy kodach 429, krótka pauza przy błędach serwera i natychmiastowe zgłaszanie błędów klienta, których żadne ponowienie nie naprawi. Normalizuje też odpowiedź do stabilnego słownika – treść, finish_reason, zużycie, model, ID – dzięki czemu reszta Twojego kodu nie zależy już od dokładnej struktury obiektu zwracanego przez SDK. Samo logger.warning przy obcięciach uzasadnia tę enkapsulację: to jedyny sposób, by odkryć, że ustawienie max_tokens jest zbyt niskie, zanim zgłoszą to użytkownicy.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging
logger = logging.getLogger(__name__)
class MistralClient:
"""Klient produkcyjny z ponawianiem, limitem czasu i logowaniem."""
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,
}
# Alert, jeśli odpowiedź została obcięta
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")
Śledź koszty na bieżąco
Odkrywanie zużycia na miesięcznym rachunku to luksus, na który mało zespołów może sobie pozwolić. Poniższy tracker zapisuje jedną linię JSONL na wywołanie – znacznik czasu, model, tokeny wejściowe i wyjściowe, finish_reason, ID żądania – i utrzymuje sumę sesji, którą możesz sprawdzić w dowolnym momencie. Format JSONL nie jest szczegółem: agreguje się z dowolnym narzędziem analitycznym bez etapu parsowania, a obecność ID żądania pozwala powiązać anomalie kosztów z konkretnym wywołaniem.
import json
from datetime import datetime, timezone
class CostTracker:
"""Śledzenie kosztów API w czasie rzeczywistym."""
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"
)
Waliduj na obu końcach
Solidna aplikacja nie ufa ani temu, co wchodzi, ani temu, co wychodzi. Na wejściu odrzucaj puste wiadomości, ogranicz długość do 10 000 znaków, aby zapobiec sytuacji, w której nieszczęśliwe kopiowanie-i-wklejanie nadmiernie zwiększy Twój rachunek, i usuwaj znaki kontrolne, które zakłócają tokenizację. Na wyjściu niczego nie odrzucaj, ale generuj ostrzeżenia: potencjalnie obcięta odpowiedź, nienormalnie krótka odpowiedź (poniżej pięciu znaków), nienormalnie długa odpowiedź (powyżej 50 000). Te trzy sygnały wyłapują zdecydowaną większość cichych awarii.
def validate_input(user_message: str) -> str:
"""Walidacja i czyszczenie danych wejściowych użytkownika."""
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)")
# Czyszczenie znaków kontrolnych
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:
"""Walidacja danych wyjściowych 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}
Zarządzaj oknem kontekstowym
Ostatni problem: powolne dryfowanie długich rozmów. Poniższa funkcja szacuje objętość jako jeden token na cztery znaki w języku francuskim – to przybliżenie, ale wystarczające jako zabezpieczenie – i przepuszcza żądania, dopóki mieszczą się one w 80% limitu. Powyżej tego progu zachowuje monit systemowy i usuwa najstarsze wiadomości, aż zejdziesz poniżej 70%. Ta luka między dwoma progami jest celowa: cięcie tylko do progu wyzwalacza spowodowałoby, że funkcja natychmiast wróciłaby do strefy czerwonej przy następnej wiadomości.
def manage_context(messages: list, max_tokens: int = 100_000) -> list:
"""Utrzymanie wiadomości w limicie tokenów modelu."""
# Szacunek: 1 token ~ 4 znaki we francuskim
total_chars = sum(len(m["content"]) for m in messages)
estimated_tokens = total_chars // 4
if estimated_tokens < max_tokens * 0.8:
return messages # Wszystko się mieści
# Zachowaj system + pierwszą i ostatnią wiadomość
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
# Usuń najstarsze wiadomości
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 wynosisz z tego kursu
Podróż przebiegła w czterech krokach. Po pierwsze, fundamenty: punkt końcowy, role, podstawowe parametry i struktura odpowiedzi. Następnie strumieniowanie, z protokołem SSE, jego implementacją w Pythonie, sekwencjami stop i utwardzaniem poprzez safe_prompt oraz mechanizmy ochronne. Inżynieria promptów zajęła trzecią fazę – produkcyjne monity systemowe, few-shot, strukturyzacja XML i Markdown, antywzorce. Zaawansowane parametry domknęły całość: temperatura i Top P w szczegółach, kary za obecność i częstotliwość, N kompletacji oraz ta lista kontrolna dla produkcji.
Poniższa konfiguracja destyluje te wybory w obronny punkt wyjścia dla pierwszego wdrożenia produkcyjnego: stała wersja, sufit tokenów dopasowany do przypadku użycia, niska temperatura dla spójności faktograficznej, top_p nienaruszone, skoro temperatura jest dostosowana, neutralne kary, chyba że konkretna potrzeba je uzasadnia, oraz włączony safe_prompt.
# Typowa konfiguracja dla aplikacji produkcyjnej
PRODUCTION_CONFIG = {
"model": "mistral-large-2512", # Stała wersja
"max_tokens": 2000, # Dopasowane do przypadku użycia
"temperature": 0.3, # Spójne i faktograficzne
"top_p": 1.0, # Nienaruszone, jeśli temperatura dostosowana
"presence_penalty": 0.0, # Domyślne, chyba że konkretna potrzeba
"frequency_penalty": 0.0, # Domyślne, chyba że konkretna potrzeba
"safe_prompt": True, # Bezpieczeństwo włączone
}
Aby pójść dalej z API Mistral, na Corsen Academy dostępne są cztery uzupełniające kursy:
- Embeddings i RAG – Wyszukiwanie semantyczne z
mistral-embedi bazami danych wektorowych - Function Calling – Podłącz model do swoich narzędzi i zewnętrznych API
- Fine-tuning – Dostosuj model do swojej specyficznej domeny
- Produkcja i Ewaluacja – Metryki, automatyczne ewaluacje, optymalizacja kosztów
Kluczowe wnioski
- Używaj wersjonowanych modeli w produkcji, nigdy
-latest - Wdróż ponawianie + wykładnicze opóźnienie + logowanie już przy pierwszym wdrożeniu
- Waliduj zarówno dane wejściowe, JAK i wyjściowe każdego wywołania API
- Śledź koszty w czasie rzeczywistym za pomocą trackera tokenów
- Zarządzaj oknem kontekstowym dla długich rozmów
- Włącz
safe_promptjako minimalną siatkę bezpieczeństwa - Testuj swoje prompty na przypadkach brzegowych przed każdym wydaniem produkcyjnym
Sprawdź swoją wiedzę
Nie ma już tajemnic w punkcie końcowym chat/completions? Sprawdźmy to.
1. Jakie role strukturyzują listę wiadomości?
Odpowiedź: system (ramy), user (żądania), assistant (odpowiedzi modelu) – pełna historia restartuje się przy każdym wywołaniu, ponieważ API jest bezstanowe.
2. Co znajdziesz w polu usage odpowiedzi?
Odpowiedź: Tokeny zużyte na wejściu i wyjściu – podstawa rozliczeń i metryka, którą należy obserwować pod kątem skalowania i kosztów.
3. Jak działa strumieniowanie SSE?
Odpowiedź: Odpowiedź przybywa jako Server-Sent Events, fragment po fragmencie: wyświetlasz na bieżąco i łączysz, aby uzyskać końcową wiadomość.
4. Do czego służą sekwencje stop?
Odpowiedź: Do przerwania generowania, gdy tylko pojawi się dany ciąg: kontrola długości, zatrzymanie na delimiterze, gwarancja czystych formatów.
5. Temperatura, Top P, kary: jakie zastosowanie w produkcji?
Odpowiedź: Temperatura/Top P ustawiają determinizm dla zadania; kary za obecność/częstotliwość limitują powtórzenia – ustawienia do ustalenia dla każdego przypadku użycia i udokumentowania wraz z promptami.
Role, usage, strumieniowanie, stopy, dostrajanie: fundamenty są trwałe – powyższe najlepsze praktyki produkcyjne wprowadzają je w odpowiedni porządek.