Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Casi d'uso avanzati

Lezione 10 di 12 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Oltre gli esempi semplici
  2. Estrazione di una fattura
  3. Analisi delle recensioni aspetto per aspetto
  4. Classificazione del testo in più categorie
  5. Fattorizzazione della chiamata
  6. Punti chiave

Oltre gli esempi semplici

Hai padroneggiato Pydantic, Zod e client.chat.parse(). I prossimi tre casi vanno oltre gli schemi semplici a quattro campi per affrontare scenari che incontrerai negli ambienti aziendali: documenti contabili, analisi dettagliata delle recensioni dei clienti e testi appartenenti simultaneamente a più categorie. Ognuno illustra una tecnica di modellazione diversa.

Estrazione di una fattura

L’elaborazione dei documenti è il terreno naturale per gli schemi annidati. Una fattura non è un oggetto piatto: contiene un’intestazione, un piè di pagina con i totali e un numero variabile di righe di dettaglio con una propria struttura. Pertanto, modelliamo LineItem separatamente e poi lo riferiamo all’interno di una lista. La valuta utilizza un enum, il che impedisce al modello di restituire "euros" o "€" a seconda di come è formulato il documento.

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

Il formato della data imposto nel prompt di sistema non è un dettaglio minore: senza di esso, un documento francese potrebbe produrre 12/03/2026 mentre uno americano restituisce 03/12/2026, creando due stringhe indistinguibili per il tuo database. La versione TypeScript segue la stessa architettura, con il formato documentato tramite .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}`);

Analisi delle recensioni aspetto per aspetto

Una recensione reale di un cliente è raramente uniformemente positiva o negativa. La recensione dell’hotel qui sotto loda la camera e la colazione, condanna il parcheggio e il Wi-Fi e offre una visione sfumata del personale: un unico punteggio globale perderebbe tutte queste informazioni. La soluzione consiste nel modellare un AspectSentiment riutilizzabile e richiederne una lista. Il campo evidence è la parte più interessante dello schema: richiedendo una citazione dal testo, costringi il modello a fondare il suo giudizio e ti dai i mezzi per verificarlo.

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

Classificazione del testo in più categorie

A differenza della classificazione semplice, dove viene assegnata una singola etichetta, la classificazione multi-etichetta riconosce che un testo può appartenere a diverse categorie. L’incidente descritto qui sotto tocca simultaneamente sicurezza, finanza, frode e protezione dei dati: forzare un’unica etichetta impoverirebbe la logica di instradamento.

Due elementi dello schema meritano attenzione. reasoning richiede una giustificazione per ogni etichetta, il che migliora la qualità del punteggio. requires_human_review trasforma l’incertezza del modello in un segnale operativo: invece di scoprire dopo il fatto che una classificazione era dubbia, la escalati automaticamente a un umano quando la fiducia scende sotto 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}")

Fattorizzazione della chiamata

Questi tre esempi condividono la stessa meccanica: un prompt di sistema, un testo, uno schema e temperature=0. Invece di copiare la chiamata per ogni nuovo caso, estraila in una funzione generica. Il TypeVar vincolato a BaseModel preserva la tipizzazione: l’oggetto restituito ha il tipo dello schema passato come argomento e il tuo IDE lo sa.

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

Tre casi d’uso molto diversi, ognuno dei quali richiede una sola riga di codice per essere chiamato: questo è il beneficio concreto di una buona modellazione degli schemi.

Punti chiave

  • Gli schemi annidati (list[LineItem], list[AspectSentiment]) abilitano analisi complesse
  • Gli enum (Currency, categorie) vincolano i valori possibili
  • Il campo evidence / reasoning costringe il modello a giustificare le sue scelte
  • Un wrapper generico riduce la duplicazione del codice
  • temperature=0 è obbligatorio per questi casi d’uso in produzione