Najlepsze praktyki i podsumowanie
Na tej stronie
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, sprawdzaniefinish_reasoni 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.