Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Labākās prakses un kopsavilkums

Nodarbība 12 no 12 Atjaunota 2026. gada 2. novembris Programmētājs
Šajā lapā
  1. Kursu kopsavilkums
  2. Pieejas izvēle
  3. Desmit zelta likumi
  4. Trīs dārgas kļūdas
  5. Kas jāuzrauga
  6. Virzība tālāk
  7. Pilnīgs cauruļvads
  8. Galvenās atziņas
  9. Pārbaudi savas zināšanas

Kursu kopsavilkums

Tu esi izpētījis visu Mistral API piedāvāto strukturētās izvades mehānismu klāstu. Šī noslēguma nodarbība apkopo to, kas ikdienas darbā rada atšķirību: kā izvēlēties starp abām pieejām, kādi ir neapstrīdamie iestatījumi, visbiežāk sastopamās kļūdas un kas jāuzrauga, kad esi nonācis produkcijas vidē.

Pieejas izvēle

Četri jautājumi ir pietiekami, lai pieņemtu lēmumu šādā secībā. Vai tev ir definēta izvades shēma? Ja atbilde ir nē, paliec pie JSON režīma: tu esi izpētes vai prototipēšanas fāzē, un datu modeļa fiksēšana būtu pāragra. Ja jā, pārej pie nākamā jautājuma.

Vai strādā ar Python vai TypeScript? Ja jā, pielāgotās strukturētās izvades (Custom Structured Outputs) ir gatavas lietošanai ar Pydantic vai Zod. Ja nē, JSON režīms ar manuālu validāciju paliek tavs ceļš.

Vai esi produkcijas vidē? Ja jā, pielāgotās strukturētās izvades ir obligātas, vienmēr. Pretējā gadījumā JSON režīms prototipēšanai ir vairāk nekā pietiekams.

Vai shēma mainās bieži? Joprojām attīstoša shēma sākotnēji padara JSON režīmu praktiskāku, līdz prasības stabilizējas; fiksēta shēma liek izvēlēties pielāgotās strukturētās izvades un to nodrošināto uzticamību.

Desmit zelta likumi

Pirmie pieci attiecas uz to, kā raksti savus pieprasījumus. Produkcijā vienmēr iestati temperature=0: temperatūras mainīgums ir uzticamības ienaidnieks, un datu ieguvei radošums nav vajadzīgs.

# Production: deterministic
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    temperature=0  # Reproducibility
)

Vienmēr pārbaudi finish_reason. Tas ir vienīgais indikators, kas brīdina par apgrieztu atbildi, pirms mēģini to izmantot.

if response.choices[0].finish_reason != "stop":
    # Response is truncated — increase max_tokens
    raise ValueError(f"Incomplete response: {response.choices[0].finish_reason}")

JSON režīmā vienmēr norādi modeli uzdevumā (prompt). Parametrs garantē sintaksi, nevis struktūru: tev pašam jānorāda atslēgas un to tipi.

# JSON Mode — the prompt MUST describe the structure
messages = [
    {
        "role": "system",
        "content": "Return JSON with keys: name (string), age (number), city (string)."
    },
    {"role": "user", "content": text}
]

Pielāgotajā režīmā dokumentē savus laukus. Precīzs apraksts ir vērtīgāks par garu uzdevumu, un tas ceļo kopā ar shēmu abās valodās.

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"),
});

Atdali kontekstu no satura. Instrukcijas dzīvo sistēmas ziņojumā, apstrādājamie dati – lietotāja ziņojumā; nekad otrādi, citādi modelis sajauks instrukciju ar avota tekstu.

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

Nākamie divi noteikumi attiecas uz tavu drošības tīklu. Ievies atkārtošanas mehānismu (retry): nekad neveic vienu vienīgu izsaukumu bez rezerves plāna; atkārtošana ar atsauksmēm ir minimālais raksts produkcijas vidē. Un validē ārpus shēmas robežām, jo shēma garantē struktūru, bet semantiskā validācija – robežas, konsekvence, biznesa loģika – paliek tava atbildība.

Pēdējie trīs attiecas uz orķestrāciju. Izvēlies pareizo modeli konkrētajam lietojumam: mistral-large-latest sarežģītiem uzdevumiem un daudzu lauku ieguvei, mistral-small-latest vienkāršai klasifikācijai un pamata ieguvei, ministral-8b-latest augstai frekvencei un minimālai latentumam. Produkcijā reģistrē katru izsaukumu (log), fiksējot izmantoto modeli, ilgumu, finish_reason un rezultātu: bez žurnāliem tu esi akls. Visbeidzot, nepārspīlē uzdevuma (prompt) optimizāciju pārāk agri – sāc vienkārši, mēri, iterē; priekšlaicīga uzdevuma optimizācija ir izplatīts slazds, turpretī shēma un validācija ir īstie sviras.

Trīs dārgas kļūdas

Pirmā ir pārāk zema max_tokens vērtība. JSON tiks apgriezts garās atbildēs, un kļūda izpaudīsies tikai pie lieliem dokumentiem, bieži vien jau pēc palaišanas ekspluatācijā.

# Dangerous — JSON will be truncated for long responses
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    max_tokens=128  # Too low for a complex schema
)

Iestati max_tokens, balstoties uz sagaidāmo izvades apjomu: rēķinam ar 20 rindām ir vajadzīgi vairāk tokeni nekā vienkāršai klasifikācijai.

Otrā ir temperatūra, kas nav nulle, kas padara rezultātus neatkārtojamus, nedodot nekādu labumu datu ieguves uzdevumā.

# Dangerous in production — non-reproducible results
response = client.chat.parse(
    ...,
    temperature=0.7  # Unnecessary variation for extraction
)

Trešā ir reflekss izmantot vienu vienīgu modeli. Nelieto mistral-large visam: binārai klasifikācijai nav vajadzīgs jaudīgākais modelis, un ministral-8b paveiks darbu 5 reizes ātrāk par mazākām izmaksām.

Kas jāuzrauga

Četri rādītāji pastāsta par tavas cauruļvada veselību. Veiksmes rādītājs mēra to izsaukumu procentuālo daļu, kas pirmajā mēģinājumā atgriež derīgu objektu; atkārtošanas rādītājs – to izsaukumu procentuālo daļu, kuriem bija vajadzīgs otrais mēģinājums. P50/P95 latentums dod vidējo atbildes laiku un 95. percentili, kas ir atklāsmīgāks par vidējo rādītāju. Izmaksas par vienu ieguvi, izteiktas patērētajos tokenos uz izsaukumu, ļauj kontrolēt rēķinu.

Attiecībā uz šiem rādītājiem daži brīdinājuma sliekšņi ir labi pierādījuši sevi: veiksmes rādītājs zem 95% attaisno dzeltenu brīdinājumu, zem 85% – sarkanu; P95 latentums, kas lielāks par 10 s, prasa izmeklēšanu; un atvērts ķēdes pārtraucējs (circuit breaker) prasa tūlītēju brīdinājumu.

Virzība tālāk

Četri virzieni dabiski papildina šo kursu. Funkciju izsaukumi (Function calling) izmanto strukturētās izvades, lai barotu funkciju izsaukumus aģentā. Straumēšana (Streaming) ļauj saņemt strukturēto izvadi pakāpeniski, kas ir svarīgi garām atbildēm. Smalkā noregulēšana (Fine-tuning) pielāgo Mistral modeli, lai uzlabotu ieguves kvalitāti taviem specifiskajiem datiem. Novērtēšana (Evaluation), visbeidzot, sastāv no automātiskas sistēmas izveides, balstoties uz „zelta” datu kopu un rādītājiem – tieši tas pateiks, vai uzdevuma (prompt) izmaiņas faktiski uzlabo situāciju.

Pilnīgs cauruļvads

Tālāk redzamais kods apvieno kursa prakses vienā plūsmā: lauku pa laukam aprakstīta shēma, validētājs, kas noraida vērtības ārpus robežām, uzdevumam piemērots modelis, temperature=0, eksplicīts max_tokens, finish_reason pārbaude un žurnālēšana abiem iespējamiem iznākumiem.

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

Aptuveni trīsdesmit rindiņas, un tev ir komponents, ko droši var iekļaut sistēmas vidū: tieši to padara iespējamu strukturētās izvades.

Galvenās atziņas

  • Izmanto pielāgotās strukturētās izvades (Custom Structured Outputs) produkcijā, JSON režīmu – prototipēšanai
  • temperature=0, finish_reason pārbaude un atkārtošana (retry) ir neapstrīdami
  • Izvēlies modeli, balstoties uz uzdevuma sarežģītību un budžetu
  • Uzraugi veiksmes rādītāju, latentumu un izmaksas
  • Sāc vienkārši, mēri, tad optimizē

Pārbaudi savas zināšanas

JSON režīms, shēmas, atkārtošana: vai strukturētā izvade ir kontrolēta?

1. JSON režīms pret pielāgotām strukturētām izvādēm: kāda ir atšķirība?

Atbilde: JSON režīms garantē sintaktiski derīgu JSON; pielāgotās strukturētās izvades papildus izpilda tavu precīzo shēmu – laukus, tipus, struktūru: pilnu līgumu.

2. Ko nodrošina client.chat.parse() ar Pydantic?

Atbilde: Pilnu ciklu: Pydantic shēma deklarē struktūru, API ierobežo ģenerēšanu, un atbilde pienāk jau validēta un tipēta kā Python objekts – nulles manuāla parsēšana.

3. Un TypeScript pusē?

Atbilde: Tāds pats komforts ar Zod: Zod shēma definē un validē struktūru – viens patiesības avots ģenerēšanai un tipēšanai.

4. Ko darīt, ja izvade neatbilst shēmai?

Atbilde: Validē sistemātiski un plāno atkārtošanas stratēģiju: pieprasī vēlreiz, iekļaujot kļūdu kontekstā, vai eleganti degradē – nekad neakla uzticēšanās izvadei.

5. Kad strukturētā izvade ir neaizstājama?

Atbilde: Tiklīdz programma patērē atbildi bez cilvēka pārskata: ieguve, integrācijas, cauruļvadi – formāts vairs nav pieklājība, tas kļūst par saskarni.

Deklarēta shēma, ierobežota ģenerēšana, izvades validācija: triāde, kas padara AI iekļaujamu reālā programmatūrā.