Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Geriausios praktikos ir apibendrinimas

Paskaita 12 iš 12 Atnaujinta 2026 m. lapkričio 2 d. Kūrėjas
Šiame puslapyje
  1. Kurso apibendrinimas
  2. Metodo pasirinkimas
  3. Dešimt auksinių taisyklių
  4. Trys brangiai kainuojančios klaidos
  5. Ką stebėti
  6. Tolimesni žingsniai
  7. Pilna sistema
  8. Svarbiausi punktai
  9. Patikrink savo žinias

Kurso apibendrinimas

Išnagrinėjai visą „Mistral API“ siūlomų struktūrizuotos išvesties mechanizmų spektrą. Šioje paskutinėje pamokoje sujungsime tai, kas kasdieniame darbe lemia skirtumą: kaip pasirinkti tarp dviejų metodų, kokios yra privalomos nuostatos, kokios dažniausiai pasitaikančios klaidos ir ką stebėti perkėlus sprendimą į gamybinę aplinką.

Metodo pasirinkimas

Sprendimui priimti pakanka keturių klausimų, kuriuos reikia užduoti šia tvarka. Ar turi apibrėžtą išvesties schemą? Jei atsakymas ne – laikykis JSON režimo: esi tyrimų ar prototipų kūrimo etape, ir duomenų modelio fiksavimas būtų priešlaikinis. Jei taip – eik prie kito klausimo.

Ar dirbi su „Python“ ar „TypeScript“? Jei taip, „Custom Structured Outputs“ (pritaikyta struktūrizuota išvestis) tau paruošta naudojant „Pydantic“ arba „Zod“. Jei ne – JSON režimas su rankiniu validavimu lieka tavo keliu.

Ar esi gamybinėje aplinkoje? Jei taip, „Custom Structured Outputs“ yra privalomi, visada. Kitu atveju prototipų kūrimui daugiau nei pakanka JSON režimo.

Ar schema dažnai keičiasi? Vis dar besivystanti schema iš pradžių daro JSON režimą praktiškesniu, kol reikalavimai nusistovės; fiksuota schema reiškia, kad reikia rinktis „Custom Structured Outputs“ ir jų teikiamą patikimumą.

Dešimt auksinių taisyklių

Pirmosios penkios susijusios su tuo, kaip rašai savo užklausas. Gamybinėje aplinkoje visada nustatyk temperature=0: temperatūros kintamumas yra patikimumo priešas, o duomenų išgavimui kūrybiškumo nereikia.

# Gamyba: deterministinė
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    temperature=0  # Atkuriamumas
)

Visada tikrink finish_reason. Tai vienintelis indikatorius, įspėjantis apie nutrauktą atsakymą prieš jį panaudojant.

if response.choices[0].finish_reason != "stop":
    # Atsakymas nutrauktas – padidinkite max_tokens
    raise ValueError(f"Nebaigtas atsakymas: {response.choices[0].finish_reason}")

JSON režime visada instruktuok modelį užklausoje (prompt). Parametras garantuoja sintaksę, bet ne struktūrą: tau tenka nurodyti raktus ir jų tipus.

# JSON režimas – užklausa PRIVALO aprašyti struktūrą
messages = [
    {
        "role": "system",
        "content": "Grąžink JSON su raktais: name (string), age (number), city (string)."
    },
    {"role": "user", "content": text}
]

„Custom“ režimu dokumentuok savo laukus. Tikslus aprašymas vertingesnis už ilgą užklausą ir keliauja kartu su schema abiem kalbomis.

class Product(BaseModel):
    name: str = Field(description="Komercinis produkto pavadinimas")
    price: float = Field(description="Kaina EUR be mokesčių, suapvalinta iki 2 skaitmenų po kablelio")
const ProductSchema = z.object({
  name: z.string().describe("Komercinis produkto pavadinimas"),
  price: z.number().describe("Kaina EUR be mokesčių, suapvalinta iki 2 skaitmenų po kablelio"),
});

Atskirk kontekstą nuo turinio. Instrukcijos turi būti sistemos žinutėje, o apdorojami duomenys – naudotojo žinutėje; niekada neatvirkščiai, kitaip modelis supainios instrukciją su šaltinio tekstu.

messages = [
    {"role": "system", "content": "Esi duomenų išgavimo įrankis. [Formato instrukcijos]"},
    {"role": "user", "content": "[Apdorojamas tekstas – JOKIŲ formato instrukcijų čia]"}
]

Kitos dvi taisyklės susijusios su tavo saugos tinklu. Įdiek kartojimo (retry) mechanizmą: niekada neatlik vieno kvietimo be atsarginio plano; kartojimas su grįžtamuoju ryšiu yra minimalus šablonas gamybinėje aplinkoje. Ir validuok daugiau nei tik pagal schemą, nes schema garantuoja struktūrą, o semantinė validacija – ribos, nuoseklumas, verslo logika – lieka tavo atsakomybe.

Paskutinės trys susijusios su orkestracija. Pasirink tinkamą modelį tinkamam naudojimui: mistral-large-latest – sudėtingoms užduotims ir daugialaukiam išgavimui, mistral-small-latest – paprastai klasifikacijai ir baziniam išgavimui, ministral-8b-latest – dideliam dažniui ir minimaliai delsai. Gamyboje registruok kiekvieną kvietimą, įrašydamas naudotą modelį, trukmę, finish_reason ir rezultatą: be žurnalų esi aklas. Galiausiai, neper anksti neoptimizuok užklausos (prompt) – pradėk paprastai, matuok, kartok; priešlaikinis užklausų optimizavimas yra dažna spąstai, tuo tarpu schema ir validacija yra tikrieji svertai.

Trys brangiai kainuojančios klaidos

Pirmoji – per maža max_tokens reikšmė. Ilgų atsakymų atveju JSON bus nutrauktas, o klaida pasireikš tik su dideliais dokumentais, dažnai jau perkėlus į gamybą.

# Pavojinga – JSON bus nutrauktas ilgiems atsakymams
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    max_tokens=128  # Per mažai sudėtingai schemai
)

Nustatyk max_tokens pagal numatomą išvesties dydį: sąskaita su 20 eilučių reikalauja daugiau tokenų nei paprasta klasifikacija.

Antroji – nulinė temperatūra, dėl kurios tavo rezultatai tampa neatkuriami be jokios naudos išgavimo užduočiai.

# Pavojinga gamyboje – neatkuriami rezultatai
response = client.chat.parse(
    ...,
    temperature=0.7  # Nereikalingas svyravimas išgavimui
)

Trečioji – refleksas naudoti vieną modelį. Nenaudok mistral-large viskam: dvejetainė klasifikacija nereikalauja galingiausio modelio, o ministral-8b tą patį darbą atliks 5 kartus greičiau ir mažesne kaina.

Ką stebėti

Keturi rodikliai parodo tavo sistemos būklę. Sėkmės rodiklis matuoja procentą kvietimų, kurie pirmuoju bandymu grąžina validų objektą; kartojimų rodiklis – procentą kvietimų, kuriems prireikė antro šanso. P50/P95 delsos laikas rodo medianinį atsako laiką ir 95-ąjį procentilį, kas yra informatyviau nei vidurkis. Kaina vienam išgavimui, išreikšta sunaudotais tokenais vienam kvietimui, leidžia kontroliuoti sąskaitą.

Remiantis šiais rodikliais, keletas įspėjimo slenksčių pasiteisina: sėkmės rodiklis žemiau 95 % pateisina geltoną įspėjimą, žemiau 85 % – raudoną; P95 delsos laikas, viršijantis 10 s, reikalauja tyrimo; o atidarytas grandinės pertraukiklis (circuit breaker) reikalauja neatidėliotino įspėjimo.

Tolimesni žingsniai

Keturios kryptys natūraliai papildo šį kursą. Funkcijų kvietimas (Function calling) naudoja struktūrizuotą išvestį agento funkcijoms maitinti. Srautinis perdavimas (Streaming) leidžia gauti struktūrizuotą išvestį palaipsniui, kas svarbu ilgiems atsakymams. Derinimas (Fine-tuning) pritaiko „Mistral“ modelį, siekiant pagerinti išgavimo kokybę specifiniams tavo duomenims. Vertinimas (Evaluation) – tai automatinės sistemos, pagrįstos „auksiniu“ duomenų rinkiniu ir rodikliais, sukūrimas; būtent tai parodys, ar užklausos pakeitimas iš tikrųjų pagerina rezultatus.

Pilna sistema

Toliau pateiktas kodas sujungia kurso praktikas į vieną srautą: laukas po lauko aprašyta schema, validuotojas, atmetantis už ribų esančius įverčius, užduočiai pritaikytas modelis, temperature=0, aiškus max_tokens, finish_reason patikrinimas ir registravimas abiem galimiems baigtims.

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="teigiamas, neigiamas arba neutralus")
    score: float = Field(description="Įvertis tarp -1.0 ir 1.0")
    category: str = Field(description="produktas, paslauga, pristatymas, kaina arba kita")
    action_required: bool = Field(description="Tiesa, jei reikia imtis veiksmų")
    summary: str = Field(description="Vieno sakinio santrauka")

    @field_validator("score")
    @classmethod
    def score_in_range(cls, v):
        if not -1.0 <= v <= 1.0:
            raise ValueError(f"Įvertis už ribų: {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": "Išanalizuok klientų atsiliepimus."},
                {"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 per {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
        return result
    except Exception as e:
        logger.error(f"KLAIDA per {time.time()-start:.2f}s — {e}")
        raise

Apie trisdešimt eilučių, ir turi komponentą, kurį galima saugiai integruoti į sistemos vidurį: būtent tai leidžia struktūrizuota išvestis.

Svarbiausi punktai

  • Gamyboje naudok „Custom Structured Outputs“, prototipams – JSON režimą
  • temperature=0, finish_reason tikrinimas ir kartojimas yra privalomi
  • Modelį rinkis pagal užduoties sudėtingumą ir biudžetą
  • Stebėk sėkmės rodiklį, delsos laiką ir kainą
  • Pradėk paprastai, matuok, tada optimizuok

Patikrink savo žinias

JSON režimas, schemos, kartojimas: ar struktūrizuota išvestis under kontrolė?

1. JSON režimas prieš „Custom Structured Outputs“: koks skirtumas?

Atsakymas: JSON režimas garantuoja sintaksiškai teisingą JSON; „Custom Structured Outputs“ papildomai užtikrina tikslią tavo schemą – laukus, tipus, struktūrą: tai pilna sutartis.

2. Ką suteikia `client.chat.parse()` naudojant „Pydantic“?

Atsakymas: Pilną ciklą: „Pydantic“ schema deklaruoja struktūrą, API riboja generavimą, o atsakymas atkeliauja jau validuotas ir tipizuotas kaip „Python“ objektas – joks rankinis analizavimas nereikalingas.

3. O „TypeScript“ pusėje?

Atsakymas: Tas pats patogumas su „Zod“: „Zod“ schema apibrėžia ir validuoja struktūrą – vienas tiesos šaltinis generavimui ir tipizavimui.

4. Ką daryti, kai išvestis neatitinka schemos?

Atsakymas: Sistemingai validuok ir suplanuok kartojimo strategiją: pakartok užklausą įtraukdamas klaidą į kontekstą arba elegantiškai sumažink funkcionalumą – niekada aklai nepasitikėk išvestimi.

5. Kada struktūrizuota išvestis yra būtina?

Atsakymas: Kai tik programos sunaudoja atsakymą be žmogaus peržiūros: išgavimas, integracijos, vamzdynai – formatas nustoja būti mandagumu, jis tampa sąsaja.

Deklaruota schema, ribotas generavimas, išvesties validavimas: triada, leidžianti DI integruoti į tikrą programinę įrangą.