Στρατηγικές Επικύρωσης και Επαναληπτικών Δοκιμών
Σε αυτήν τη σελίδα
Επικύρωση: Η Τελευταία Γραμμή Άμυνας Πριν την Παραγωγή
Ακόμη και με τις Προσαρμοσμένες Δομημένες Εξόδους (Custom Structured Outputs), η επικύρωση παραμένει απαραίτητη. Το σχήμα εγγυάται τη δομή, όχι τη σημασιολογική συνοχή. Ένα πεδίο price μπορεί να περιέχει -999.0: ένα έγκυρο float που ταιριάζει απόλυτα με το σχήμα, αλλά δεν έχει κανένα νόημα για μια τιμή.
Η διάκριση είναι σαφής. Τα Pydantic και Zod χειρίζονται αυτόματα την δομική επικύρωση: απαιτούμενα πεδία, τύποι πεδίων, περιορισμούς enum και εμφωλευμένες δομές. Δεν χρειάζεται να γράψετε κανέναν κώδικα για αυτό. Ωστόσο, η σημασιολογική επικύρωση είναι αποκλειστικά δική σας ευθύνη. Αυτό περιλαμβάνει αριθμητικά όρια (μια τιμή μεγαλύτερη από το μηδέν, μια βαθμολογία μεταξύ 0 και 1), συνοχή μεταξύ πεδίων (το σύνολο πρέπει να ισούται με το άθροισμα των γραμμών στοιχείων), μορφές συμβολοσειρών (ένα πραγματικά έγκυρο email, μια σωστά μορφοποιημένη ημερομηνία) και επιχειρηματική λογική (μια ημερομηνία λήξης μεταγενέστερη από την ημερομηνία τιμολογίου).
Ενσωμάτωση Επιχειρηματικών Κανόνων στο Σχήμα
Το Pydantic σάς επιτρέπει να ενσωματώνετε αυτούς τους ελέγχους απευθείας στο μοντέλο, καθιστώντας τους αναπόσπαστους από τη δομή. Το @field_validator διαχειρίζεται μεμονωμένα πεδία—για παράδειγμα, διασφαλίζοντας ότι μια ποσότητα είναι θετική ή ότι η τιμή μονάδας δεν είναι αρνητική. Το @model_validator(mode="after") εκτελείται μόλις συμπληρωθούν όλα τα πεδία, επιτρέποντας ελέγχους μεταξύ πεδίων, όπως η επαλήθευση ότι το δηλωμένο σύνολο ταιριάζει με την ποσότητα × την τιμή μονάδας εντός ενός λεπτού.
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 εκφράζει την ίδια λογική χρησιμοποιώντας ενσωματωμένους περιορισμούς όπως .positive() και .nonnegative() για πεδία, και .refine() για κανόνες μεταξύ αντικειμένων που εφαρμόζονται στο πλήρες αντικείμενο.
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" }
);
Επαναληπτική Δοκιμή με Ανατροφοδότηση
Όταν η επικύρωση αποτύχει, το πιο αποτελεσματικό μοτίβο είναι να στείλετε το σφάλμα πίσω στο μοντέλο ώστε να μπορέσει να διορθωθεί μόνο του. Η παρακάτω συνάρτηση αλυσιδώνει τρεις ελέγχους με σειρά σημασίας: πλήρης απάντηση, αντικείμενο διαφορετικό του null και συμμόρφωση με τους επιχειρηματικούς κανόνες. Σε περίπτωση αποτυχίας, προσαρτά την εσφαλμένη απάντηση και το μήνυμα σφάλματος στη συνομιλία, παρέχοντας στο επόμενο εγχείρημα ακριβές διαγνωστικό πλαίσιο. Σημειώστε το αντίγραφο της λίστας μηνυμάτων στην αρχή της συνάρτησης—χωρίς αυτό, θα μολύνατε το ιστορικό συνομιλίας του καλούντος.
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}"
)
Μια Καταρράκτης Εναλλακτικών Σχεδίων
Η επαναληπτική δοκιμή δεν λύνει τα πάντα: μερικές φορές ένα έγγραφο είναι πολύ άτυπο για το σχήμα. Αντί να αποτύχετε απότομα, υποβαθμίστε σταδιακά την λειτουργία. Η πρώτη προσπάθεια χρησιμοποιεί τις Προσαρμοσμένες Δομημένες Εξόδους, την πιο αξιόπιστη επιλογή. Εάν αυτό αποτύχει, περάστε στη Λειτουργία JSON (JSON Mode), η οποία είναι πιο ευέλικτη, και στη συνέχεια περάστε την έξοδο μέσω του model_validate()—αυτό διατηρεί τους περιορισμούς του σχήματος χωρίς να βασίζεται στο μοντέλο για να τα παράγει τέλεια. Ως έσχατη λύση, η συνάρτηση επιστρέφει None, αφήνοντας τον καλούντα να αποφασίσει μεταξύ χειροκίνητης ουροποίησης ή εγκατάλειψης.
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
Διακόψτε τη Ροή Έγκαιρα
Σε μια αγωγό υψηλής συχνότητας, μια διακοπή λειτουργίας του API μετατρέπει την επαναληπτική δοκιμή σε ενισχυτή: κάθε έγγραφο αποτυγχάνει τρεις φορές, ο λογαριασμός σας τριπλασιάζεται και η καθυστέρηση εκτοξεύεται. Ένας διακόπτης κυκλώματος (circuit breaker) παρακολουθεί τις αποτυχίες σε ένα κυλιόμενο παράθυρο και μπλοκάρει τις κλήσεις μόλις ξεπεραστεί ένα κατώφλι—πέντε αποτυχίες σε εξήντα δευτερόλεπτα στη διαμόρφωση που φαίνεται εδώ. Μια επιτυχία κλείνει το κύκλωμα και μηδενίζει τον μετρητή.
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
Κάντε το Ορατό
Όλος αυτός ο μηχανισμός παραμένει τυφλός χωρίς ίχνη. Καταγράψτε κάθε κλήση με τη διάρκειά της και το εμπλεκόμενο σχήμα, είτε succeeds είτε αποτύχει. Αυτά τα δεδομένα σάς επιτρέπουν αργότερα να προσδιορίσετε εάν η υποβάθμιση οφείλεται σε πρόβλημα του μοντέλου, σε τύπο εγγράφου ή σε αλλαγή prompt.
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
Βασικά σημεία
- Η δομική επικύρωση (τύποι) είναι αυτόματη· η σημασιολογική επικύρωση (λογική) είναι δική σας ευθύνη
- Η επαναληπτική δοκιμή με ανατροφοδότηση είναι το πιο αποτελεσματικό μοτίβο: στείλτε το σφάλμα πίσω στο μοντέλο
- Υλοποιήστε μια καταρράκτη εναλλακτικών: Προσαρμοσμένο > Λειτουργία JSON > προεπιλεγμένη τιμή
- Σε παραγωγή υψηλής συχνότητας, χρησιμοποιήστε έναν διακόπτη κυκλώματος για να αποτρέψετε καταρράκτες σφαλμάτων
- Καταγράψτε κάθε κλήση για παρακολούθηση και διάγνωση