Geavanceerde use-cases
Op deze pagina
Voorbij eenvoudige voorbeelden
U heeft Pydantic, Zod en client.chat.parse() onder de knie. De volgende drie casussen gaan verder dan eenvoudige schema’s met vier velden en behandelen scenario’s die u in enterprise-omgevingen zult tegenkomen: boekhoudkundige documenten, gedetailleerde analyse van klantrecensies en teksten die gelijktijdig tot meerdere categorieën behoren. Elk illustreert een andere modelleringstechniek.
Een factuur extraheren
Documentverwerking is het natuurlijke domein voor geneste schema’s. Een factuur is geen plat object: deze bevat een koptekst, een voettekst met totalen en een variabel aantal regelitems met een eigen structuur. Daarom modelleren we LineItem apart en verwijzen er vervolgens naar binnen een lijst. De valuta gebruikt een enum, wat voorkomt dat het model "euros" of "€" retourneert, afhankelijk van hoe het document is geformuleerd.
from pydantic import BaseModel, Field
from typing import Optional
from enum import Enum
class Currency(str, Enum):
eur = "EUR"
usd = "USD"
gbp = "GBP"
class LineItem(BaseModel):
description: str = Field(description="Line item description")
quantity: float = Field(description="Quantity")
unit_price: float = Field(description="Unit price excluding tax")
vat_rate: float = Field(description="VAT rate as a percentage (e.g., 20.0)")
total_ht: float = Field(description="Line total excluding tax")
class InvoiceData(BaseModel):
invoice_number: str = Field(description="Invoice number")
date: str = Field(description="Invoice date in YYYY-MM-DD format")
due_date: Optional[str] = Field(default=None, description="Due date")
vendor_name: str = Field(description="Vendor name")
vendor_address: Optional[str] = Field(default=None)
client_name: str = Field(description="Client name")
line_items: list[LineItem] = Field(description="Invoice line items")
subtotal_ht: float = Field(description="Subtotal excluding tax")
total_vat: float = Field(description="Total VAT amount")
total_ttc: float = Field(description="Total including tax")
currency: Currency = Field(description="Currency")
payment_method: Optional[str] = Field(default=None)
# Extraction
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": """You are an accounting expert. Extract data from the invoice.
Be precise with amounts. Calculate totals if necessary.
Dates must be in YYYY-MM-DD format."""
},
{"role": "user", "content": invoice_text}
],
response_format=InvoiceData,
temperature=0
)
invoice = response.choices[0].message.parsed
print(f"Invoice {invoice.invoice_number} — {invoice.vendor_name}")
print(f"Total incl. tax: {invoice.total_ttc} {invoice.currency.value}")
for item in invoice.line_items:
print(f" - {item.description}: {item.quantity} x {item.unit_price}€ = {item.total_ht}€ excl. tax")
De datumnotatie die in de systeemprompt wordt afgedwongen, is geen detail: zonder deze notatie kan een Frans document 12/03/2026 opleveren terwijl een Amerikaans document 03/12/2026 geeft, wat resulteert in twee niet te onderscheiden strings voor uw database. De TypeScript-versie volgt dezelfde architectuur, waarbij de notatie wordt gedocumenteerd via .describe().
import { z } from "zod";
const LineItemSchema = z.object({
description: z.string(),
quantity: z.number(),
unitPrice: z.number().describe("Unit price excluding tax"),
vatRate: z.number().describe("VAT rate in %"),
totalHt: z.number(),
});
const InvoiceSchema = z.object({
invoiceNumber: z.string(),
date: z.string().describe("Format YYYY-MM-DD"),
dueDate: z.string().nullable(),
vendorName: z.string(),
clientName: z.string(),
lineItems: z.array(LineItemSchema),
subtotalHt: z.number(),
totalVat: z.number(),
totalTtc: z.number(),
currency: z.enum(["EUR", "USD", "GBP"]),
});
const response = await client.chat.parse({
model: "mistral-large-latest",
messages: [
{ role: "system", content: "Extract invoice data precisely." },
{ role: "user", content: invoiceText },
],
responseFormat: InvoiceSchema,
temperature: 0,
});
const invoice = response.choices[0].message.parsed!;
console.log(`Invoice ${invoice.invoiceNumber} — Total: ${invoice.totalTtc} ${invoice.currency}`);
Recensies aspect per aspect analyseren
Een echte klantrecensie is zelden uniform positief of negatief. De onderstaande hotelrecensie prijst de kamer en het ontbijt, veroordeelt het parkeren en de wifi, en biedt een genuanceerde kijk op het personeel: een enkele globale score zou al deze informatie verliezen. De oplossing is een herbruikbaar AspectSentiment te modelleren en een lijst hiervan op te vragen. Het veld evidence is het meest interessante deel van het schema: door een citaat uit de tekst te vereisen, dwingt u het model om zijn oordeel te onderbouwen en geeft u uzelf de middelen om dit te verifiëren.
from pydantic import BaseModel, Field
class AspectSentiment(BaseModel):
aspect: str = Field(description="The aspect analyzed (quality, price, service, delivery, etc.)")
sentiment: str = Field(description="positive, negative, or neutral")
score: float = Field(description="Score between -1.0 (very negative) and 1.0 (very positive)")
evidence: str = Field(description="Quote or excerpt from the text justifying the sentiment")
class ReviewAnalysis(BaseModel):
overall_sentiment: str = Field(description="Overall sentiment: positive, negative, mixed, or neutral")
overall_score: float = Field(description="Overall score between -1.0 and 1.0")
aspects: list[AspectSentiment] = Field(description="Aspect-by-aspect analysis")
recommendation: bool = Field(description="Does the author recommend the product/service?")
key_strengths: list[str] = Field(description="Identified strengths")
key_weaknesses: list[str] = Field(description="Identified weaknesses")
review_text = """
The hotel is magnificent; the room was spacious and clean. The breakfast is excellent
with a wide selection. However, the parking is outrageously expensive (€35/night) and the Wi-Fi was
unstable throughout the stay. The reception staff was very welcoming,
but room service took over an hour to deliver our order.
"""
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Analyze this customer review by detailing each mentioned aspect."
},
{"role": "user", "content": review_text}
],
response_format=ReviewAnalysis,
temperature=0
)
review = response.choices[0].message.parsed
print(f"Overall sentiment: {review.overall_sentiment} ({review.overall_score:+.1f})")
for aspect in review.aspects:
print(f" [{aspect.score:+.1f}] {aspect.aspect}: {aspect.sentiment}")
Tekst indelen in meerdere categorieën
In tegenstelling tot eenvoudige classificatie, waarbij één label wordt toegewezen, erkent multi-label classificatie dat een tekst tot meerdere categorieën kan behoren. Het hieronder beschreven incident raakt gelijktijdig aan beveiliging, financiën, fraude en gegevensbescherming: het afdwingen van één enkel label zou de routeringslogica verarmen.
Twee elementen van het schema verdienen aandacht. reasoning vereist een rechtvaardiging voor elk label, wat de kwaliteit van de scores verbetert. requires_human_review zet onzekerheid van het model om in een operationeel signaal: in plaats van achteraf te ontdekken dat een classificatie twijfelachtig was, escaleert u deze automatisch naar een mens wanneer het vertrouwen onder de 0,7 zakt.
from pydantic import BaseModel, Field
class LabelScore(BaseModel):
label: str = Field(description="Category name")
confidence: float = Field(description="Confidence score between 0.0 and 1.0")
reasoning: str = Field(description="One-sentence justification")
class MultiLabelClassification(BaseModel):
primary_label: str = Field(description="Primary category")
all_labels: list[LabelScore] = Field(
description="All applicable categories with their confidence scores"
)
requires_human_review: bool = Field(
description="True if classification is uncertain (confidence < 0.7)"
)
text = """
Our mobile payment application has a security vulnerability allowing
access to banking data. Several customers have reported unauthorized
transactions. The technical team is currently investigating.
"""
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": """Classify this text among the following categories (multiple possible):
security, finance, technical, legal, customer_support, compliance, fraud, data_privacy.
Assign a confidence score to each applicable category."""
},
{"role": "user", "content": text}
],
response_format=MultiLabelClassification,
temperature=0
)
result = response.choices[0].message.parsed
print(f"Primary category: {result.primary_label}")
print(f"Human review required: {'Yes' if result.requires_human_review else 'No'}")
for label in result.all_labels:
print(f" [{label.confidence:.0%}] {label.label} — {label.reasoning}")
De aanroep factoriseren
Deze drie voorbeelden delen dezelfde mechanica: een systeemprompt, een tekst, een schema en temperature=0. In plaats van de aanroep voor elk nieuw geval te kopiëren, extraheert u deze in een generieke functie. De TypeVar gebonden aan BaseModel behoudt de typering: het geretourneerde object heeft het type van het schema dat als argument is doorgegeven, en uw IDE weet dit.
from typing import TypeVar, Type
from pydantic import BaseModel
T = TypeVar("T", bound=BaseModel)
def extract(client, text: str, schema: Type[T], system_prompt: str = "") -> T:
"""Reusable structured extraction."""
messages = []
if system_prompt:
messages.append({"role": "system", "content": system_prompt})
messages.append({"role": "user", "content": text})
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=schema,
temperature=0
)
return response.choices[0].message.parsed
# Usage
invoice = extract(client, invoice_text, InvoiceData, "Extract invoice data.")
review = extract(client, customer_review, ReviewAnalysis, "Analyze this customer review.")
classification = extract(client, ticket, MultiLabelClassification, "Classify this text.")
Drie zeer verschillende use-cases, die elk slechts één regel code vereisen om aan te roepen: dit is het concrete voordeel van goede schemamodellering.
Belangrijkste punten
- Geneste schema’s (
list[LineItem],list[AspectSentiment]) maken complexe analyses mogelijk - Enums (
Currency, categorieën) beperken de mogelijke waarden - Het veld
evidence/reasoningdwingt het model om zijn keuzes te rechtvaardigen - Een generieke wrapper vermindert codeduplicatie
temperature=0is verplicht voor deze productie-use-cases