Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Validointi- ja uudelleenyritysstrategiat

Oppitunti 11 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Validointi: Viimeinen puolustuslinja ennen tuotantoon siirtoa
  2. Liiketoimintasääntöjen upottaminen skeemaan
  3. Uudelleenyritys palautteen avulla
  4. Varasuunnitelmien ketju
  5. Katkaise virta ajoissa
  6. Tee siitä näkyvää
  7. Keskeiset asiat

Validointi: Viimeinen puolustuslinja ennen tuotantoon siirtoa

Vaikka käytät mukautettuja jäsennettyjä tulosteita (Custom Structured Outputs), validointi on edelleen välttämätöntä. Skeema takaa rakenteen, ei semanttista johdonmukaisuutta. Kenttä price voi sisältää arvon -999.0: tämä on kelvollinen liukuluku, joka vastaa täydellisesti skeemaa, mutta ei ole järkevä hinta.

Ero on selvä. Pydantic ja Zod hoitavat rakenteellisen validoinnin automaattisesti: vaaditut kentät, kenttien tyypit, enum-rajoitukset ja sisäkkäiset rakenteet. Sinun ei tarvitse kirjoittaa tähän mitään koodia. Semanttinen validointi on kuitenkin täysin sinun vastuullasi. Tämä sisältää numeeriset rajat (hinnan on oltava suurempi kuin nolla, pistemäärän välillä 0–1), kenttien välisen johdonmukaisuuden (summan on vastattava rivityksien summaa), merkkijonojen muodot (aidosti kelvollinen sähköpostiosoite, oikein muotoiltu päivämäärä) ja liiketoimintalogiikan (eräpäivän on oltava myöhempi kuin laskun päivämäärä).

Liiketoimintasääntöjen upottaminen skeemaan

Pydanticin avulla voit upottaa nämä tarkistukset suoraan malliin, jolloin ne ovat erottamaton osa rakennetta. @field_validator käsittelee yksittäisiä kenttiä – esimerkiksi varmistaa, että määrä on positiivinen tai yksikköhinta ei ole negatiivinen. @model_validator(mode="after") suoritetaan, kun kaikki kentät on täytetty, mikä mahdollistaa kenttien väliset tarkistukset, kuten sen varmistamisen, että ilmoitettu summa vastaa määrän ja yksikköhinnan tuloa yhden sentin tarkkuudella.

from pydantic import BaseModel, Field, field_validator, model_validator

class InvoiceLine(BaseModel):
    description: str
    quantity: float
    unit_price: float
    total: float

    @field_validator("quantity")
    @classmethod
    def quantity_positive(cls, v):
        if v <= 0:
            raise ValueError(f"Quantity must be positive, got: {v}")
        return v

    @field_validator("unit_price")
    @classmethod
    def price_non_negative(cls, v):
        if v < 0:
            raise ValueError(f"Unit price cannot be negative: {v}")
        return v

    @model_validator(mode="after")
    def check_total(self):
        expected = round(self.quantity * self.unit_price, 2)
        if abs(self.total - expected) > 0.01:
            raise ValueError(
                f"Inconsistent total: {self.total} != {self.quantity} x {self.unit_price} = {expected}"
            )
        return self

Zod ilmaisee saman logiikan käyttämällä sisäänrakennettuja rajoitteita, kuten .positive() ja .nonnegative() kentille, ja .refine()-metodia objektien välisiin sääntöihin, jotka kohdistetaan koko objektiin.

import { z } from "zod";

const InvoiceLineSchema = z
  .object({
    description: z.string(),
    quantity: z.number().positive("Quantity must be positive"),
    unitPrice: z.number().nonnegative("Price cannot be negative"),
    total: z.number(),
  })
  .refine(
    (data) => Math.abs(data.total - data.quantity * data.unitPrice) < 0.01,
    { message: "Total does not match quantity x unit price" }
  );

Uudelleenyritys palautteen avulla

Kun validointi epäonnistuu, tehokkain malli on lähettää virhe takaisin mallille, jotta se voi korjata itseään. Alla oleva funktio ketjuttaa kolme tarkistusta tärkeysjärjestyksessä: vastauksen täydellisyys, ei-null-objekti ja liiketoimintasääntöjen noudattaminen. Epäonnistuessaan se lisää virheellisen vastauksen ja virheilmoituksen keskusteluun, antaen seuraavalle yritykselle tarkan diagnostisen kontekstin. Huomaa viestilistan kopioiminen funktion alussa – ilman sitä saastuttaisit kutsujan keskusteluhistorian.

from mistralai.client import Mistral
from pydantic import BaseModel, ValidationError
import json

def extract_with_retry(
    client: Mistral,
    messages: list,
    schema,
    max_retries: int = 3,
    model: str = "mistral-large-latest"
):
    """Extraction with retry and structured error feedback."""
    conversation = list(messages)  # Copy to avoid modifying the original

    for attempt in range(max_retries):
        try:
            response = client.chat.parse(
                model=model,
                messages=conversation,
                response_format=schema,
                temperature=0,
                max_tokens=2048
            )

            # Check that the response is complete
            if response.choices[0].finish_reason != "stop":
                raise ValueError(
                    f"Incomplete response (finish_reason={response.choices[0].finish_reason})"
                )

            parsed = response.choices[0].message.parsed
            if parsed is None:
                raise ValueError("Parsed response is None")

            # Additional semantic validation
            validate_business_rules(parsed)

            return parsed

        except (ValidationError, ValueError) as e:
            error_msg = str(e)
            print(f"Attempt {attempt + 1}/{max_retries} failed: {error_msg}")

            if attempt < max_retries - 1:
                # Add feedback to context
                raw = response.choices[0].message.content if response else ""
                conversation.append({"role": "assistant", "content": raw})
                conversation.append({
                    "role": "user",
                    "content": f"Your response contains an error: {error_msg}. Please correct it."
                })
            else:
                raise RuntimeError(
                    f"Failed after {max_retries} attempts. Last error: {error_msg}"
                )

Varasuunnitelmien ketju

Uudelleenyritys ei ratkaise kaikkea: joskus asiakirja on liian epätyypillinen skeemalle. Älä epäonnistu äkillisesti, vaan heikennä toimintaa hallitusti. Ensimmäinen yritys käyttää mukautettuja jäsennettyjä tulosteita, jotka ovat luotettavin vaihtoehto. Jos se epäonnistuu, siirry JSON-tilaan, joka on joustavampi, ja syötä tuloste funktion model_validate() läpi – tämä säilyttää skeeman rajoitukset luottamatta siihen, että malli tuottaa ne täydellisesti. Viimeisenä keinona funktio palauttaa None, jolloin kutsuja voi päättää jatkaako manuaalisessa jonossa vai hylkääkö prosessin.

def extract_with_fallback(client, text, schema, system_prompt):
    """Extraction with fallback cascade."""

    # Attempt 1: Custom Structured Output (best)
    try:
        return extract_with_retry(
            client,
            [
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": text}
            ],
            schema,
            max_retries=2,
            model="mistral-large-latest"
        )
    except RuntimeError:
        print("Custom parse failed, falling back to JSON Mode")

    # Attempt 2: JSON Mode (more flexible)
    try:
        response = client.chat.complete(
            model="mistral-large-latest",
            messages=[
                {"role": "system", "content": system_prompt + "\nReturn valid JSON."},
                {"role": "user", "content": text}
            ],
            response_format={"type": "json_object"},
            temperature=0
        )
        raw = json.loads(response.choices[0].message.content)
        return schema.model_validate(raw)  # Attempt Pydantic validation
    except Exception:
        print("JSON Mode failed, falling back to manual extraction")

    # Attempt 3: Return partial object or error
    return None

Katkaise virta ajoissa

Suurtaajuusputkistossa API-katkos muuttaa uudelleenyrityksen vahvistimeksi: jokainen asiakirja epäonnistuu kolme kertaa, laskusi kolminkertaistuu ja viiveet kasvavat räjähdysmäisesti. Piirikatkaisin (circuit breaker) tarkkailee epäonnistumisia liukuvassa ikkunassa ja estää kutsut, kun kynnysarvo ylittyy – tässä konfiguraatiossa viisi epäonnistumista kuudenkymmenen sekunnin aikana. Onnistuminen sulkee piirin ja nollaa laskurin.

from collections import deque
from time import time

class CircuitBreaker:
    def __init__(self, failure_threshold=5, window_seconds=60):
        self.failures = deque()
        self.threshold = failure_threshold
        self.window = window_seconds
        self.is_open = False

    def record_failure(self):
        now = time()
        self.failures.append(now)
        # Clean up errors outside the window
        while self.failures and self.failures[0] < now - self.window:
            self.failures.popleft()
        if len(self.failures) >= self.threshold:
            self.is_open = True

    def record_success(self):
        self.is_open = False
        self.failures.clear()

    def can_proceed(self) -> bool:
        if not self.is_open:
            return True
        # Check if the window has passed
        now = time()
        while self.failures and self.failures[0] < now - self.window:
            self.failures.popleft()
        if len(self.failures) < self.threshold:
            self.is_open = False
            return True
        return False

# Usage
breaker = CircuitBreaker(failure_threshold=5, window_seconds=60)

def safe_extract(client, text, schema):
    if not breaker.can_proceed():
        raise RuntimeError("Circuit open—too many recent errors")
    try:
        result = extract_with_retry(client, [...], schema)
        breaker.record_success()
        return result
    except RuntimeError:
        breaker.record_failure()
        raise

Tee siitä näkyvää

Kaikki tämä koneisto pysyy sokeana ilman jälkiä. Lokita jokainen kutsu kestoineen ja siihen liittyvine skeemoineen, onnistuiko se tai epäonnistuiko. Tämän datan avulla voit myöhemmin määrittää, johtuuko heikkeneminen malliongelmasta, asiakirjatyypistä vai kehotteen muutoksesta.

import logging
import time

logger = logging.getLogger("structured_output")

def monitored_extract(client, text, schema, **kwargs):
    start = time.time()
    try:
        result = extract_with_retry(client, [...], schema, **kwargs)
        duration = time.time() - start
        logger.info(f"Extraction succeeded in {duration:.2f}s — schema={schema.__name__}")
        return result
    except Exception as e:
        duration = time.time() - start
        logger.error(f"Extraction failed in {duration:.2f}s — schema={schema.__name__} — {e}")
        raise

Keskeiset asiat

  • Rakenteellinen validointi (tyypit) on automaattista; semanttinen validointi (logiikka) on sinun vastuullasi
  • Uudelleenyritys palautteen kanssa on tehokkain malli: lähetä virhe takaisin mallille
  • Toteuta varasuunnitelmien ketju: Mukautettu > JSON-tila > oletusarvo
  • Käytä suurtaajuustuotannossa piirikatkaisinta virheketjujen estämiseksi
  • Lokita jokainen kutsu valvontaa ja vianmääritystä varten