Validointi- ja uudelleenyritysstrategiat
Tällä sivulla
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