Legjobb gyakorlatok és összefoglaló
Ezen az oldalon
A tanfolyam összefoglalása
Végigvetted a Mistral API által kínált strukturált kimeneti mechanizmusok teljes skáláját. Ez az utolsó lecke összefoglalja mindazt, ami a mindennapi munkában számít: hogyan válassz a két megközelítés között, mik a megkerülhetetlen beállítások, mik a leggyakoribb buktatók, és mit kell figyelned éles környezetben.
A megközelítésed kiválasztása
Négy kérdés elég a döntéshez, ebben a sorrendben. Van definiált kimeneti sémád? Ha a válasz nem, maradj a JSON módnál: felfedező vagy prototípus-készítő üzemmódban vagy, és korai lenne még rögzíteni az adatmodellt. Ha igen, lépj a következő kérdésre.
Pythonban vagy TypeScriptben dolgozol? Ha igen, a Pydantic vagy a Zod segítségével készen állnak számodra az egyéni strukturált kimenetek. Ha nem, a JSON mód manuális validálással marad az utad.
Éles környezetben vagy? Ha igen, az egyéni strukturált kimenetek mindig kötelezőek. Ellenkező esetben a JSON mód több mint elegendő a prototípus-készítéshez.
Gyakran változik a séma? Egy még fejlődő séma esetén először a JSON mód praktikusabb, amíg a követelmények stabilizálódnak; egy rögzített séma az egyéni strukturált kimenetek mellett szól, és azon megbízhatóság mellett, amit nyújtanak.
A tíz aranyszabály
Az első öt arra vonatkozik, hogyan írod meg a hívásaidat. Éles környezetben mindig állítsd be a temperature=0 értéket: a hőmérséklet változékonysága a megbízhatóság ellensége, és a kinyerésnek nincs szüksége kreativitásra.
# Éles környezet: determinisztikus
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
temperature=0 # Reprodukálhatóság
)
Mindig ellenőrizd a finish_reason értékét. Ez az egyetlen jelző, amely figyelmeztet a csonkolt válaszra, mielőtt felhasználnád azt.
if response.choices[0].finish_reason != "stop":
# A válasz csonkolt — növeld a max_tokens értékét
raise ValueError(f"Hiányos válasz: {response.choices[0].finish_reason}")
JSON módban mindig utasítsd a modellt a promptban. A paraméter garantálja a szintaxist, de nem a struktúrát: neked kell megadnod a kulcsokat és azok típusait.
# JSON mód — a promptnak LE KELL írnia a struktúrát
messages = [
{
"role": "system",
"content": "Adj vissza JSON-t a következő kulcsokkal: name (string), age (number), city (string)."
},
{"role": "user", "content": text}
]
Egyéni módban dokumentáld a mezőidet. Egy pontos leírás többet ér, mint egy hosszú prompt, és mindkét nyelven együtt utazik a sémával.
class Product(BaseModel):
name: str = Field(description="Kereskedelmi termék neve")
price: float = Field(description="Ár EUR-ban, ÁFA nélkül, 2 tizedesjegyre kerekítve")
const ProductSchema = z.object({
name: z.string().describe("Kereskedelmi termék neve"),
price: z.number().describe("Ár EUR-ban, ÁFA nélkül, 2 tizedesjegyre kerekítve"),
});
Válaszd szét a kontextust a tartalomtól. Az utasítások a rendszerüzenetben élnek, a feldolgozandó adatok a felhasználói üzenetben – soha ne fordítva, mert a modell összekeveri az utasítást a forrásszöveggel.
messages = [
{"role": "system", "content": "Te egy adatkiemelő vagy. [Formátum utasítások]"},
{"role": "user", "content": "[Feldolgozandó szöveg — ITT NINCS formátum utasítás]"}
]
A következő két szabály a biztonsági hálódra vonatkozik. Valósíts meg újrapróbálkozási mechanizmust: soha ne indíts egyetlen hívást sem tartalék nélkül; a visszacsatolással történő újrapróbálkozás a minimális minta éles környezetben. És validálj a sémán túl, mivel a séma csak a struktúrát garantálja, míg a szemantikai validálás – határok, konzisztencia, üzleti logika – a te felelősséged marad.
Az utolsó három az orchestrációra vonatkozik. Válaszd ki a megfelelő modellt a megfelelő felhasználási esethez: mistral-large-latest komplex feladatokhoz és többmezős kinyeréshez, mistral-small-latest egyszerű osztályozáshoz és alapvető kinyeréshez, ministral-8b-latest nagy gyakorisághoz és minimális késleltetéshez. Naplózz minden hívást éles környezetben, rögzítve a használt modellt, az időtartamot, a finish_reason értékét és az eredményt: naplók nélkül vakon repülsz. Végül, ne optimalizáld túl korán a promptot – kezdj egyszerűen, mérj, iterálj; a korai prompt-optimalizálás gyakori csapda, míg a séma és a validálás az igazi emelők.
Három költséges buktató
Az első egy túl alacsony max_tokens érték. A JSON csonkolódni fog hosszú válaszok esetén, és a hiba csak nagy dokumentumoknál jelentkezik, gyakran már az élesítés után.
# Veszélyes — a JSON csonkolódni fog hosszú válaszoknál
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=128 # Túl alacsony egy komplex sémához
)
Állítsd be a max_tokens értékét a várt kimeneti méret alapján: egy 20 soros számla több tokent igényel, mint egy egyszerű osztályozás.
A második a nem nulla hőmérséklet, ami nem reprodukálhatóvá teszi az eredményeidet nulla haszonért cserébe egy kinyerési feladatnál.
# Veszélyes éles környezetben — nem reprodukálható eredmények
response = client.chat.parse(
...,
temperature=0.7 # Felesleges variáció kinyeréshez
)
A harmadik az a reflex, hogy egyetlen modellt használj. Ne használd a mistral-large modellt mindenre: egy bináris osztályozáshoz nincs szükség a legerősebb modellre, és a ministral-8b elvégzi a munkát ötször gyorsabban, kisebb költséggel.
Mit kell figyelni
Négy metrika mutatja a pipeline-od egészségét. A sikerarány azt méri, hány százaléknyi hívás ad vissza érvényes objektumot első próbálkozásra; az újrapróbálkozási arány pedig azt, hány százaléknyi hívásnak volt szüksége második esélyre. A P50/P95 késleltetés megadja a medián válaszidőt és a 95. percentilist, ami sokkal beszédesebb, mint az átlag. A kinyerésenkénti költség, tokennkénti fogyasztásban kifejezve hívásonként, kordában tartja a számlát.
Ezen metrikák alapján néhány riasztási küszöbérték jól működik: 95% alatti sikerarány sárga riasztást indokol, 85% alatt pirosat; a 10 másodpercnél nagyobb P95 késleltetés kivizsgálást igényel; egy nyitott áramkör-megszakító pedig azonnali riasztást hív elő.
Továbbhaladás
Négy irány természetes kiterjesztése ennek a tanfolyamnak. A függvényhívás strukturált kimeneteket használ ügynökök függvényhívásainak táplálására. A streamelés lehetővé teszi, hogy fokozatosan kapd meg a strukturált kimenetet, ami hosszú válaszoknál számít. A finomhangolás egy Mistral modellt igazít hozzád, hogy javítsa a kinyerés minőségét a specifikus adataidon. A kiértékelés végül egy automatikus keretrendszer felállítását jelenti egy arany adathalmaz és metrikák alapján – ez mondja meg neked, hogy egy prompt-változtatás ténylegesen javít-e a dolgokon.
Egy teljes pipeline
Az alábbi kód egyetlen folyamatban egyesíti a tanfolyam gyakorlatait: mezőről mezőre leírt séma, egy validátor, amely elutasítja a határokon kívüli pontszámokat, a feladathoz igazított modell, temperature=0, egy explicit max_tokens, a finish_reason ellenőrzése, és naplózás mindkét lehetséges kimenetelhez.
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="pozitív, negatív vagy semleges")
score: float = Field(description="Pontszám -1.0 és 1.0 között")
category: str = Field(description="termék, szolgáltatás, szállítás, ár vagy egyéb")
action_required: bool = Field(description="Igaz, ha intézkedés szükséges")
summary: str = Field(description="Egy mondatos összefoglaló")
@field_validator("score")
@classmethod
def score_in_range(cls, v):
if not -1.0 <= v <= 1.0:
raise ValueError(f"Pontszám határon kívül: {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": "Elemezd a vásárlói visszajelzéseket."},
{"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 {time.time()-start:.2f}s alatt — {result.sentiment} ({result.score:+.1f})")
return result
except Exception as e:
logger.error(f"HIBA {time.time()-start:.2f}s alatt — {e}")
raise
Körülbelül harminc sor, és máris van egy komponensed, amely biztonságosan beilleszthető egy rendszer közepébe: pontosan ezt teszik lehetővé a strukturált kimenetek.
Főbb megállapítások
- Használj egyéni strukturált kimeneteket éles környezetben, JSON módot prototípus-készítéshez
- A
temperature=0, afinish_reasonellenőrzése és az újrapróbálkozás nem tárgyalható - Válaszd ki a modellt a feladat komplexitása és a költségvetés alapján
- Figyeld a sikerarányt, a késleltetést és a költséget
- Kezdj egyszerűen, mérj, majd optimalizálj
Teszteld a tudásod
JSON mód, sémák, újrapróbálkozás: kézben tartod a strukturált kimenetet?
1. JSON mód vs. Egyéni strukturált kimenetek: mi a különbség?
Válasz: A JSON mód szintaktikailag érvényes JSON-t garantál; az Egyéni strukturált kimenetek emellett kikényszerítik a pontos sémádat – mezők, típusok, struktúra: a teljes szerződést.
2. Mit nyújt a client.chat.parse() Pydantic segítségével?
Válasz: A teljes ciklust: a Pydantic séma deklarálja a struktúrát, az API korlátozza a generálást, és a válasz már validálva és Python objektumként típusozva érkezik – nulla manuális parszolás.
3. És TypeScript oldalán?
Válasz: Ugyanaz a kényelem a Zoddal: a Zod séma definiálja és validálja a struktúrát – egyetlen igazságforrás a generáláshoz és a típusozáshoz.
4. Mit tegyél, ha a kimenet nem tartja be a sémát?
Válasz: Validálj szisztematikusan, és tervezz meg egy újrapróbálkozási stratégiát: kérd újra a hibát a kontextusban, vagy degradálj gracefully – soha ne bízz vakon a kimenetben.
5. Mikor elengedhetetlen a strukturált kimenet?
Válasz: Amint egy program emberi felülvizsgálat nélkül fogyasztja a választ: kinyerés, integrációk, pipeline-ok – a formátum megszűnik udvariasság lenni, interfésszé válik.
Deklarált séma, korlátozott generálás, kimeneti validálás: ez a hármas teszi lehetővé, hogy az AI valódi szoftverekbe illeszthető legyen.