Salt la conținutul principal
Română— Alege o limbă
Meniu

Cazuri de utilizare avansate

Lecția 10 din 12 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Dincolo de exemplele simple
  2. Extragerea unei facturi
  3. Analiza recenziilor pe aspecte
  4. Clasificarea textului în multiple categorii
  5. Factorizarea apelului
  6. Puncte cheie

Dincolo de exemplele simple

Ați stăpânit Pydantic, Zod și client.chat.parse(). Următoarele trei cazuri depășesc schemele simple cu patru câmpuri pentru a aborda scenarii pe care le veți întâlni în mediile enterprise: documente contabile, analize detaliate ale recenziilor clienților și texte care aparțin simultan mai multor categorii. Fiecare ilustrează o tehnică diferită de modelare.

Extragerea unei facturi

Procesarea documentelor este teritoriul natural al schemelor imbricate. O factură nu este un obiect plat: conține un antet, un subsol cu totaluri și un număr variabil de linii de articol care au propria structură. Prin urmare, modelăm LineItem separat și apoi îl referențiem într-o listă. Valuta folosește un enum, ceea ce împiedică modelul să returneze "euros" sau "€" în funcție de formularea din document.

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")

Formatul datei impus în promptul de sistem nu este un detaliu minor: fără acesta, un document francez ar putea produce 12/03/2026, în timp ce unul american ar genera 03/12/2026, creând două șiruri indistinguabile pentru baza de date. Versiunea TypeScript urmează aceeași arhitectură, cu formatul documentat prin .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}`);

Analiza recenziilor pe aspecte

O recenzie reală a unui client este rareori uniform pozitivă sau negativă. Recenzia hotelului de mai jos laudă camera și micul dejun, condamnă parcarea și Wi-Fi-ul și oferă o perspectivă nuanțată asupra personalului: un singur scor global ar pierde toate aceste informații. Soluția este modelarea unui AspectSentiment reutilizabil și solicitarea unei liste de astfel de elemente. Câmpul evidence este cea mai interesantă parte a schemei – prin cererea unui citat din text, forțați modelul să își fundamenteze judecata și vă oferiți mijloacele de a o verifica.

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}")

Clasificarea textului în multiple categorii

Spre deosebire de clasificarea simplă, unde se atribuie o singură etichetă, clasificarea multi-etichetă recunoaște faptul că un text poate aparține mai multor categorii. Incidentul descris mai jos atinge simultan securitatea, finanțele, frauda și protecția datelor: forțarea unei singure etichete ar sărăci logica de rutare.

Două elemente ale schemei merită atenție. reasoning necesită o justificare pentru fiecare etichetă, ceea ce îmbunătățește calitatea scorurilor. requires_human_review transformă incertitudinea modelului într-un semnal operațional: în loc să descoperiți post-factum că o clasificare a fost dubioasă, o escaladați automat către un om atunci când încrederea scade sub 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}")

Factorizarea apelului

Aceste trei exemple share-uiesc aceeași mecanică: un prompt de sistem, un text, o schemă și temperature=0. În loc să copiați apelul pentru fiecare nou caz, extrageți-l într-o funcție generică. TypeVar legat de BaseModel păstrează tipizarea: obiectul returnat are tipul schemei transmise ca argument, iar IDE-ul dumneavoastră știe acest lucru.

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.")

Trei cazuri de utilizare foarte diferite, fiecare necesitând doar o singură linie de cod pentru apel: acesta este beneficiul concret al unei modelări bune a schemelor.

Puncte cheie

  • Schemele imbricate (list[LineItem], list[AspectSentiment]) permit analize complexe
  • Enum-urile (Currency, categorii) constrâng valorile posibile
  • Câmpul evidence / reasoning forțează modelul să își justifice alegerile
  • Un wrapper generic reduce duplicarea codului
  • temperature=0 este obligatoriu pentru aceste cazuri de utilizare în producție