Naudojimo atvejai pažengusiems
Šiame puslapyje
Anapus paprastų pavyzdžių
Jau puikiai valdai Pydantic, Zod ir client.chat.parse(). Šie trys atvejai peržengia paprastų keturių laukų schemų ribas ir pereina prie scenarijų, su kuriais susidursi įmonių aplinkoje: apskaitos dokumentai, išsami klientų atsiliepimų analizė ir tekstai, vienu metu priklausantys kelioms kategorijoms. Kiekvienas iš jų iliustruoja skirtingą modeliavimo techniką.
Sąskaitos faktūros ištraukimas
Dokumentų apdorojimas yra natūrali sudėtinių schemų teritorija. Sąskaita faktūra nėra plokščias objektas: ji turi antraštę, poraštę su sumomis ir kintamą eilučių skaičių, turinčią savo struktūrą. Todėl pirmiausia modeliuojame LineItem atskirai, o tada įtraukiame jį į sąrašą. Valiutai naudojamas enumeracija (enum), kas neleidžia modeliui grąžinti "euros" arba "€" priklausomai nuo to, kaip suformuluotas dokumentas.
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")
Sistemos priminime (system prompt) nustatytas datos formatas nėra smulkmena: be jo prancūziškas dokumentas gali sugeneruoti 12/03/2026, o amerikietiškas – 03/12/2026, todėl tavo duomenų bazėje atsiras dvi neatskiriamos eilutės. TypeScript versija laikosi tos pačios architektūros, o formatas dokumentuojamas naudojant .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}`);
Atsiliepimų analizė pagal aspektus
Tikras kliento atsiliepimas retai būna vienodai teigiamas arba neigiamas. Žemiau pateiktame viešbučio atsiliepime giriamas kambarys ir pusryčiai, peikiama automobilių stovėjimo aikštelė ir „Wi-Fi“, o apie aptarnaujantį personalą nuomonė yra niuansuota: vienas bendras įvertis prarastų visą šią informaciją. Sprendimas – sukurti pakartotinai naudojamą AspectSentiment modelį ir paprašyti jų sąrašo. Laukas evidence yra įdomiausia schemos dalis – reikalaudami citatos iš teksto, priverčiate modelį pagrįsti savo vertinimą ir suteikiate sau galimybę jį patikrinti.
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}")
Teksto klasifikavimas į kelias kategorijas
Skirtingai nei paprastoje klasifikacijoje, kai priskiriama viena etiketė, daugialypė klasifikacija pripažįsta, kad tekstas gali priklausyti kelioms kategorijoms. Toliau aprašytas incidentas vienu metu liečia saugumą, finansus, sukčiavimą ir duomenų apsaugą: vienos etiketės primetimas susilpnintų maršrutizavimo logiką.
Du schemos elementai nusipelno dėmesio. Laukas reasoning reikalauja kiekvienos etiketės pagrindimo, kas pagerina įverčių kokybę. Laukas requires_human_review modelio neapibrėžtumą paverčia operaciniu signalu: vietoj to, kad po fakto sužinotumėte, jog klasifikacija buvo abejotina, automatiškai perduodate ją žmogui, kai pasitikėjimas nukrenta žemiau 0,7.
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}")
Kvietimo faktorizavimas
Šie trys pavyzdžiai dalijasi ta pačia mechanika: sistemos priminimas, tekstas, schema ir temperature=0. Užuot kopijavę kvietimą kiekvienam naujam atvejui, išskirkite jį į bendrąją funkciją. TypeVar, susietas su BaseModel, išlaiko tipizaciją: grąžinamas objektas turi tą patį tipą, kaip ir argumento pavidalu perduota schema, ir tavo IDE tai žino.
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.")
Trys labai skirtingi naudojimo atvejai, kuriems kiekvienam pakanka vienos kodo eilutės iškvietimui: tai yra konkreti gero schemų modeliavimo nauda.
Svarbiausi punktai
- Sudėtinės schemos (
list[LineItem],list[AspectSentiment]) leidžia atlikti sudėtingas analizes - Enumeracijos (
Currency, kategorijos) apriboja galimas reikšmes - Laukas
evidence/reasoningverčia modelį pagrįsti savo pasirinkimus - Bendroji apvyniotinė funkcija sumažina kodo dubliavimąsi
temperature=0yra privalomas šiems gamybiniams naudojimo atvejams