Przejdź do głównej treści
Polski— Wybierz język
Menu

Najlepsze praktyki produkcyjne

Lekcja 16 z 16 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Od dowodu koncepcji do wdrożenia
  2. Uwierzytelnianie i wersjonowanie modeli
  3. Klient obsługujący incydenty
  4. Śledź koszty na bieżąco
  5. Waliduj na obu końcach
  6. Zarządzaj oknem kontekstowym
  7. Co wynosisz z tego kursu
  8. Kluczowe wnioski
  9. Sprawdź swoją wiedzę

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-embed i 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_prompt jako 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.