Pokročilé případy použití
Na této stránce
Za hranicí jednoduchých příkladů
Ovládl jsi Pydantic, Zod a client.chat.parse(). Následující tři případy vybočují z rámce jednoduchých schémat se čtyřmi poli a přenášejí tě do scénářů, se kterými se setkáš v podnikovém prostředí: zpracování účetních dokumentů, detailní analýza recenzí zákazníků a texty patřící současně do více kategorií. Každý z nich ilustruje odlišnou techniku modelování.
Extrakce faktury
Zpracování dokumentů je přirozeným územím pro vnořená schémata. Faktura není plochý objekt: obsahuje hlavičku, patičku s celkovými součty a proměnný počet řádkových položek, které mají vlastní strukturu. Proto nejprve modelujeme LineItem samostatně a následně na něj odkazujeme uvnitř seznamu. Měna využívá výčet (enum), což zabraňuje modelu vracet hodnoty jako "euros" nebo "€" v závislosti na formulaci dokumentu.
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")
Formát data vynucený v systémovém promptu není zanedbatelným detailem: bez něj by francouzský dokument mohl vyprodukovat 12/03/2026, zatímco americký 03/12/2026, což by v databázi vytvořilo dva nerozlišitelné řetězce. Verze v TypeScriptu následuje stejnou architekturu, přičemž formát je zdokumentován pomocí .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}`);
Analýza recenzí podle jednotlivých aspektů
Skutečná recenze zákazníka je jen zřídka jednotně pozitivní nebo negativní. Níže uvedená recenze hotelu chválí pokoj a snídani, odsuzuje parkování a Wi-Fi a nabízí vyvážený pohled na personál: jediné globální hodnocení by všechny tyto informace ztratilo. Řešením je modelovat znovu použitelné AspectSentiment a požadovat jejich seznam. Pole evidence je nejzajímavější částí schématu – vyžadováním citace z textu donutíš model ukotvit svůj úsudek a dáš si prostředky k jeho ověření.
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}")
Klasifikace textu do více kategorií
Na rozdíl od jednoduché klasifikace, kde je přiřazen jediný štítek, víceštítková klasifikace uznává, že text může patřit do několika kategorií současně. Níže popsaný incident se dotýká bezpečnosti, financí, podvodů i ochrany dat najednou: vynucení jediného štítku by ochudilo logiku směrování.
Dva prvky schématu si zaslouží pozornost. reasoning vyžaduje zdůvodnění pro každý štítek, což zlepšuje kvalitu skóre. requires_human_review přeměňuje nejistotu modelu na operační signál: místo abys dodatečně zjistil, že klasifikace byla pochybná, automaticky ji eskaluješ na člověka, jakmile klesne míra jistoty pod 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}")
Faktorizace volání
Tyto tři příklady sdílejí stejnou mechaniku: systémový prompt, text, schéma a temperature=0. Místo kopírování volání pro každý nový případ jej extrahuj do obecné funkce. TypeVar svázaný s BaseModel zachovává typování: vrácený objekt má typ schématu předaného jako argument a tvé IDE to ví.
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.")
Tři velmi odlišné případy použití, z nichž každý vyžaduje pouze jediný řádek kódu pro volání: to je konkrétní přínos dobrého modelování schémat.
Klíčové poznatky
- Vnořená schémata (
list[LineItem],list[AspectSentiment]) umožňují komplexní analýzy - Výčty (
Currency, kategorie) omezují možné hodnoty - Pole
evidence/reasoningnutí model zdůvodnit jeho volby - Obecný wrapper redukuje duplikaci kódu
temperature=0je pro tyto produkční případy použití povinné