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

Najlepsze praktyki i podsumowanie

Lekcja 12 z 12 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Podsumowanie kursu
  2. Wybór podejścia
  3. Dziesięć złotych zasad
  4. Trzy kosztowne pułapki
  5. Co monitorować
  6. Kierunki dalszego rozwoju
  7. Kompletny potok
  8. Kluczowe wnioski
  9. Sprawdź swoją wiedzę

Podsumowanie kursu

Poznałeś pełen zakres mechanizmów strukturyzowanego wyjścia oferowanych przez API Mistral. Ta ostatnia lekcja łączy wszystko to, co ma znaczenie w codziennej pracy: jak wybrać między dwoma podejściami, jakie ustawienia są nienegocjowalne, jakie pułapki zdarzają się najczęściej i co monitorować, gdy już działasz na produkcji.

Wybór podejścia

Cztery pytania wystarczą, by podjąć decyzję – w tej właśnie kolejności. Czy masz zdefiniowany schemat wyjścia? Jeśli odpowiedź brzmi „nie“, trzymaj się trybu JSON: jesteś w fazie eksploracji lub prototypowania, a sztywne określanie modelu danych byłoby przedwczesne. Jeśli „tak“, przejdź do kolejnego pytania.

Czy pracujesz w Pythonie lub TypeScript? Jeśli tak, Niestandardowe Wyjścia Strukturyzowane są dla Ciebie gotowe dzięki Pydantic lub Zod. Jeśli nie, tryb JSON z ręczną walidacją pozostaje Twoją ścieżką.

Czy jesteś na produkcji? Jeśli tak, Niestandardowe Wyjścia Strukturyzowane są obowiązkowe – zawsze. W przeciwnym razie tryb JSON w zupełności wystarczy do prototypowania.

Czy schemat często się zmienia? Schemat wciąż ewoluujący sprawia, że tryb JSON jest początkowo bardziej praktyczny, dopóki wymagania się nie ustabilizują; ustalony schemat przemawia za Niestandardowymi Wyjściami Strukturyzowanymi i niezawodnością, jaką zapewniają.

Dziesięć złotych zasad

Pierwsze pięć dotyczy sposobu tworzenia wywołań. Zawsze ustawiaj temperature=0 na produkcji: zmienność temperatury to wróg niezawodności, a ekstrakcja nie potrzebuje kreatywności.

# Produkcja: deterministyczne
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    temperature=0  # Powtarzalność
)

Zawsze sprawdzaj finish_reason. To jedyny wskaźnik ostrzegający, że odpowiedź została ucięta, zanim spróbujesz jej użyć.

if response.choices[0].finish_reason != "stop":
    # Odpowiedź ucięta — zwiększ max_tokens
    raise ValueError(f"Incomplete response: {response.choices[0].finish_reason}")

W trybie JSON zawsze instruuj model w prompcie. Parametr gwarantuje składnię, nie strukturę: to Ty musisz określić klucze i ich typy.

# Tryb JSON — prompt MUSI opisywać strukturę
messages = [
    {
        "role": "system",
        "content": "Return JSON with keys: name (string), age (number), city (string)."
    },
    {"role": "user", "content": text}
]

W trybie niestandardowym dokumentuj pola. Precyzyjny opis jest wart więcej niż długi prompt i podróżuje razem ze schematem w obu językach.

class Product(BaseModel):
    name: str = Field(description="Commercial product name")
    price: float = Field(description="Price in EUR excluding tax, rounded to 2 decimals")
const ProductSchema = z.object({
  name: z.string().describe("Commercial product name"),
  price: z.number().describe("Price in EUR excluding tax, rounded to 2 decimals"),
});

Oddziel kontekst od treści. Instrukcje należą do wiadomości systemowej, dane do przetworzenia – do wiadomości użytkownika; nigdy odwrotnie, bo model pomyli instrukcję z tekstem źródłowym.

messages = [
    {"role": "system", "content": "You are a data extractor. [Format instructions]"},
    {"role": "user", "content": "[Text to process — NO format instructions here]"}
]

Kolejne dwie zasady dotyczą Twojej siatki bezpieczeństwa. Wdróż mechanizm ponawiania: nigdy nie wykonuj pojedynczego wywołania bez kopii zapasowej; ponowienie z informacją zwrotną to minimalny wzorzec na produkcji. I waliduj poza schematem, ponieważ schemat gwarantuje strukturę, podczas gdy walidacja semantyczna – granice, spójność, logika biznesowa – pozostaje Twoją odpowiedzialnością.

Ostatnie trzy odnoszą się do orkiestracji. Dobierz właściwy model do właściwego przypadku użycia: mistral-large-latest do zadań złożonych i ekstrakcji wielopól, mistral-small-latest do prostej klasyfikacji i podstawowej ekstrakcji, ministral-8b-latest do wysokiej częstotliwości i minimalnego opóźnienia. Loguj każde wywołanie na produkcji, rejestrując użyty model, czas trwania, finish_reason i wynik: bez logów jesteś ślepy. Na koniec, nie optymalizuj promptu zbyt wcześnie – zacznij od prostoty, mierz, iteruj; przedwczesna optymalizacja promptu to częsta pułapka, podczas gdy schemat i walidacja to prawdziwe dźwignie.

Trzy kosztowne pułapki

Pierwsza to zbyt niska wartość max_tokens. JSON zostanie ucięty przy długich odpowiedziach, a błąd ujawni się dopiero na dużych dokumentach, często już po uruchomieniu na żywo.

# Niebezpieczne — JSON zostanie ucięty przy długich odpowiedziach
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    max_tokens=128  # Za mało dla złożonego schematu
)

Ustaw max_tokens w oparciu o oczekiwany rozmiar wyjścia: faktura z 20 wierszami wymaga więcej tokenów niż prosta klasyfikacja.

Druga to temperatura różna od zera, która sprawia, że wyniki nie są powtarzalne, a zysk w zadaniu ekstrakcji jest zerowy.

# Niebezpieczne na produkcji — wyniki niepowtarzalne
response = client.chat.parse(
    ...,
    temperature=0.7  # Niepotrzebna zmienność przy ekstrakcji
)

Trzecia to odruch używania jednego modelu. Nie używaj mistral-large do wszystkiego: klasyfikacja binarna nie wymaga najpotężniejszego modelu, a ministral-8b zrobi to samo 5 razy szybciej i taniej.

Co monitorować

Cztery metryki mówią o zdrowiu Twojego potoku. Wskaźnik sukcesu mierzy procent wywołań, które zwracają poprawny obiekt za pierwszym razem; wskaźnik ponowień – procent wywołań, które wymagały drugiej próby. Latencja P50/P95 podaje medianę czasu odpowiedzi i 95. percentyl, co jest bardziej wymowne niż średnia. Koszt na ekstrakcję, wyrażony w tokenach zużytych na wywołanie, utrzymuje rachunki pod kontrolą.

W odniesieniu do tych metryk kilka progów alarmowych dobrze się sprawdza: wskaźnik sukcesu poniżej 95% uzasadnia alert żółty, poniżej 85% – czerwony; latencja P95 większa niż 10 s wymaga zbadania; a otwarty wyłącznik obwodu (circuit breaker) woła o natychmiastowy alert.

Kierunki dalszego rozwoju

Cztery kierunki naturalnie rozwijają ten kurs. Wywoływanie funkcji wykorzystuje strukturyzowane wyjścia do zasilania wywołań funkcji w agencie. Strumieniowanie pozwala otrzymywać strukturyzowane wyjście stopniowo, co ma znaczenie przy długich odpowiedziach. Dostrajanie (fine-tuning) dostosowuje model Mistral, aby poprawić jakość ekstrakcji na Twoich specyficznych danych. Ewaluacja wreszcie polega na wdrożeniu automatycznego frameworku opartego na złotym zbiorze danych i metrykach – to właśnie powie Ci, czy zmiana promptu rzeczywiście coś poprawia.

Kompletny potok

Poniższy kod łączy praktyki z kursu w jednym przepływie: schemat opisany pole po polu, walidator odrzucający wyniki poza zakresem, model dobrany do zadania, temperature=0, jawne max_tokens, weryfikacja finish_reason oraz logowanie dla obu możliwych wyników.

from mistralai.client import Mistral
from pydantic import BaseModel, Field, field_validator
import logging
import time

logger = logging.getLogger("pipeline")

class CustomerFeedback(BaseModel):
    sentiment: str = Field(description="positive, negative, or neutral")
    score: float = Field(description="Score between -1.0 and 1.0")
    category: str = Field(description="product, service, delivery, price, or other")
    action_required: bool = Field(description="True if action is required")
    summary: str = Field(description="One-sentence summary")

    @field_validator("score")
    @classmethod
    def score_in_range(cls, v):
        if not -1.0 <= v <= 1.0:
            raise ValueError(f"Score out of bounds: {v}")
        return v

def analyze_feedback(client: Mistral, text: str) -> CustomerFeedback:
    start = time.time()
    try:
        response = client.chat.parse(
            model="mistral-small-latest",
            messages=[
                {"role": "system", "content": "Analyze customer feedback."},
                {"role": "user", "content": text}
            ],
            response_format=CustomerFeedback,
            temperature=0,
            max_tokens=256
        )
        assert response.choices[0].finish_reason == "stop"
        result = response.choices[0].message.parsed
        logger.info(f"OK in {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
        return result
    except Exception as e:
        logger.error(f"ERROR in {time.time()-start:.2f}s — {e}")
        raise

Około trzydziestu linii kodu i masz komponent, który można bezpiecznie wpiąć w środek systemu: dokładnie to umożliwiają wyjścia strukturyzowane.

Kluczowe wnioski

  • Używaj Niestandardowych Wyjść Strukturyzowanych na produkcji, trybu JSON do prototypowania
  • temperature=0, sprawdzanie finish_reason i ponawianie są nienegocjowalne
  • Dobieraj model w zależności od złożoności zadania i budżetu
  • Monitoruj wskaźnik sukcesu, latencję i koszt
  • Zacznij od prostoty, mierz, potem optymalizuj

Sprawdź swoją wiedzę

Tryb JSON, schematy, ponawianie: czy strukturyzowane wyjście masz pod kontrolą?

1. Tryb JSON a Niestandardowe Wyjścia Strukturyzowane: jaka jest różnica?

Odpowiedź: Tryb JSON gwarantuje składniowo poprawny JSON; Niestandardowe Wyjścia Strukturyzowane dodatkowo wymuszają Twój dokładny schemat – pola, typy, strukturę: pełną umowę.

2. Co zapewnia client.chat.parse() z Pydantic?

Odpowiedź: Pełną pętlę: schemat Pydantic deklaruje strukturę, API ogranicza generowanie, a odpowiedź przychodzi już zwalidowana i typowana jako obiekt Pythona – zero ręcznego parsowania.

3. A po stronie TypeScript?

Odpowiedź: Ten sam komfort z Zod: schemat Zod definiuje i waliduje strukturę – pojedyncze źródło prawdy dla generowania i typowania.

4. Co zrobić, gdy wyjście nie respektuje schematu?

Odpowiedź: Waliduj systematycznie i zaplanuj strategię ponawiania: ponów żądanie z błędem w kontekście lub gracefully degrade – nigdy ślepego zaufania do wyjścia.

5. Kiedy strukturyzowane wyjście jest niezbędne?

Odpowiedź: Gdy tylko program konsumuje odpowiedź bez ludzkiej weryfikacji: ekstrakcja, integracje, potoki – format przestaje być uprzejmością, staje się interfejsem.

Zadeklarowany schemat, ograniczone generowanie, walidacja wyjścia: triada, która czyni AI możliwym do wpięcia w prawdziwe oprogramowanie.