Προχωρημένες Περιπτώσεις Χρήσης
Σε αυτήν τη σελίδα
Πέρα από τα Απλά Παραδείγματα
Έχετε κατακτήσει τα Pydantic, Zod και το client.chat.parse(). Οι επόμενες τρεις περιπτώσεις ξεπερνούν τα απλά σχήματα τεσσάρων πεδίων και εστιάζουν σε σενάρια που θα συναντήσετε σε επιχειρηματικά περιβάλλοντα: λογιστικά έγγραφα, λεπτομερή ανάλυση σχολίων πελατών και κείμενα που ανήκουν ταυτόχρονα σε πολλαπλές κατηγορίες. Κάθε μία από αυτές απεικονίζει μια διαφορετική τεχνική μοντελοποίησης.
Εξαγωγή Τιμολογίου
Η επεξεργασία εγγράφων αποτελεί το φυσικό πεδίο εφαρμογής για τα ένθετα σχήματα (nested schemas). Ένα τιμολόγιο δεν είναι ένα επίπεδο αντικείμενο: περιέχει μια κεφαλίδα, ένα υποσέλιδο με τα σύνολα και έναν μεταβλητό αριθμό γραμμών στοιχείων που διαθέτουν τη δική τους δομή. Επομένως, μοντελοποιούμε το LineItem ξεχωριστά και στη συνέχεια το αναφέρουμε εντός μιας λίστας. Το νόμισμα χρησιμοποιεί ένα enum, το οποίο εμποδίζει το μοντέλο να επιστρέφει τιμές όπως "euros" ή "€" ανάλογα με τη διατύπωση του εγγράφου.
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")
Η μορφή ημερομηνίας που επιβάλλεται στο prompt του συστήματος δεν είναι μια ασήμαντη λεπτομέρεια: χωρίς αυτήν, ένα γαλλικό έγγραφο θα μπορούσε να παράγει 12/03/2026, ενώ ένα αμερικανικό να δίνει 03/12/2026, δημιουργώντας δύο μη διακριτές συμβολοσειρές για τη βάση δεδομένων σας. Η έκδοση TypeScript ακολουθεί την ίδια αρχιτεκτονική, με τη μορφή να τεκμηριώνεται μέσω της .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}`);
Ανάλυση Σχολίων ανά Πτυχή
Ένα πραγματικό σχόλιο πελάτη σπάνια είναι ομοιόμορφα θετικό ή αρνητικό. Η παρακάτω κριτική για ξενοδοχείο επαινεί το δωμάτιο και το πρωινό, καταδικάζει το πάρκινγκ και το Wi-Fi, και προσφέρει μια nuanced άποψη για το προσωπικό: μια ενιαία γενική βαθμολογία θα έχανε όλες αυτές τις πληροφορίες. Η λύση είναι να μοντελοποιήσετε ένα επαναχρησιμοποιήσιμο AspectSentiment και να ζητήσετε μια λίστα από αυτά. Το πεδίο evidence είναι το πιο ενδιαφέρον μέρος του σχήματος—απαιτώντας ένα απόσπασμα από το κείμενο, αναγκάζετε το μοντέλο να τεκμηριώσει την κρίση του και σας παρέχετε τα μέσα για να την επαληθεύσετε.
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}")
Κατηγοριοποίηση Κειμένου σε Πολλαπλές Κατηγορίες
Σε αντίθεση με την απλή κατηγοριοποίηση, όπου αποδίδεται μια μοναδική ετικέτα, η ταξινόμηση πολλαπλών ετικετών (multi-label classification) αναγνωρίζει ότι ένα κείμενο μπορεί να ανήκει σε αρκετές κατηγορίες. Το περιστατικό που περιγράφεται παρακάτω αφορά ταυτόχρονα την ασφάλεια, τα οικονομικά, την απάτη και την προστασία δεδομένων: η επιβολή μίας μόνο ετικέτας θα φτώχαινε τη λογική δρομολόγησης.
Δύο στοιχεία του σχήματος αξίζουν προσοχής. Το reasoning απαιτεί αιτιολόγηση για κάθε ετικέτα, γεγονός που βελτιώνει την ποιότητα της βαθμολογίας. Το requires_human_review μετατρέπει την αβεβαιότητα του μοντέλου σε επιχειρησιακό σήμα: αντί να ανακαλύπτετε εκ των υστέρων ότι μια ταξινόμηση ήταν αμφίβολη, την κλιμακώνετε αυτόματα σε ανθρώπινο χειριστή όταν η εμπιστοσύνη πέφτει κάτω από το 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}")
Παραγοντοποίηση της Κλήσης
Αυτά τα τρία παραδείγματα μοιράζονται τον ίδιο μηχανισμό: ένα prompt συστήματος, ένα κείμενο, ένα σχήμα και temperature=0. Αντί να αντιγράφετε την κλήση για κάθε νέα περίπτωση, εξάγετέ την σε μια γενική συνάρτηση. Το TypeVar που δεσμεύεται στο BaseModel διατηρεί την τυποποίηση: το επιστρεφόμενο αντικείμενο έχει τον τύπο του σχήματος που περνά ως όρισμα και το IDE σας το γνωρίζει.
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.")
Τρεις πολύ διαφορετικές περιπτώσεις χρήσης, καθεμία από τις οποίες απαιτεί μόνο μία γραμμή κώδικα για την κλήση: αυτό είναι το απτό όφελος της καλής μοντελοποίησης σχημάτων.
Βασικά σημεία
- Τα ένθετα σχήματα (
list[LineItem],list[AspectSentiment]) επιτρέπουν σύνθετες αναλύσεις - Τα Enums (
Currency, κατηγορίες) περιορίζουν τις πιθανές τιμές - Το πεδίο
evidence/reasoningαναγκάζει το μοντέλο να αιτιολογήσει τις επιλογές του - Ένας γενικός περιτυλιγμένος κώδικας (wrapper) μειώνει την επανάληψη κώδικα
- Το
temperature=0είναι υποχρεωτικό για αυτές τις περιπτώσεις χρήσης σε παραγωγή