Flussi di lavoro automatizzati e pipeline
In questa pagina
Passaggio alla produzione
Le lezioni precedenti hanno coperto le basi e i casi d’uso individuali. Questa lezione finale mette insieme tutto per costruire flussi di lavoro automatizzati e pipeline di convalida pronti per la produzione.
Flusso di lavoro: elaborazione documenti
Una pipeline completa per elaborare automaticamente i documenti in arrivo:
from pydantic import BaseModel
from typing import Literal
# Step 1: Document classification
class ClassificationDocument(BaseModel):
type: Literal["facture", "contrat", "devis", "courrier", "autre"]
langue: str
urgence: Literal["basse", "normale", "haute"]
departement: Literal["comptabilite", "juridique", "commercial", "direction"]
# Step 2: Extraction by type
class DonneesFacture(BaseModel):
numero: str
date_emission: str
date_echeance: str
emetteur: str
montant_ht: float
montant_ttc: float
lignes: list[dict]
# Step 3: Validation
class ResultatValidation(BaseModel):
document_valide: bool
champs_manquants: list[str]
anomalies: list[str]
score_confiance: float
action_recommandee: str
async def traiter_document(texte: str):
# Classify
_, classification = client.chat.parse(
model="grok-4.20-0309-reasoning",
messages=[{"role": "user", "content": f"Classify this document: {texte}"}],
response_format=ClassificationDocument
)
# Extract by type
if classification.type == "facture":
_, donnees = client.chat.parse(
model="grok-4.20-0309-reasoning",
messages=[{"role": "user", "content": f"Extract data from this invoice: {texte}"}],
response_format=DonneesFacture
)
# Validate
_, validation = client.chat.parse(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": f"Validate this extracted data: {donnees.model_dump_json()}"
}],
response_format=ResultatValidation
)
return classification, donnees, validation
Pipeline di convalida dei dati
Utilizza output strutturati per convalidare e normalizzare i dati in arrivo:
class AdresseNormalisee(BaseModel):
ligne_1: str
ligne_2: str | None
code_postal: str
ville: str
pays: str
format_valide: bool
class ContactNormalise(BaseModel):
prenom: str
nom: str
email_valide: bool
telephone_normalise: str | None
adresse: AdresseNormalisee
class ResultatNormalisation(BaseModel):
contacts: list[ContactNormalise]
nombre_traites: int
nombre_erreurs: int
erreurs: list[str]
Questa pipeline prende contatti in vari formati e li normalizza in una struttura uniforme.
Architettura della pipeline multi-step
Ecco lo scheletro di una pipeline di produzione robusta:
class PipelineResult(BaseModel):
etape: str
succes: bool
donnees: dict
erreurs: list[str]
duree_ms: int
def pipeline_complet(texte: str) -> list[PipelineResult]:
resultats = []
# Each step uses a dedicated schema
etapes = [
("extraction", SchemaExtraction, "Extract data from this text"),
("enrichissement", SchemaEnrichi, "Enrich this data"),
("validation", SchemaValidation, "Validate this data"),
("formatage", SchemaFinal, "Format the final result"),
]
donnees_courantes = texte
for nom, schema, instruction in etapes:
try:
_, parsed = client.chat.parse(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": f"{instruction}: {donnees_courantes}"
}],
response_format=schema
)
resultats.append(PipelineResult(
etape=nom, succes=True,
donnees=parsed.model_dump(),
erreurs=[], duree_ms=0
))
donnees_courantes = parsed.model_dump_json()
except Exception as e:
resultats.append(PipelineResult(
etape=nom, succes=False,
donnees={}, erreurs=[str(e)], duree_ms=0
))
break
return resultats
Best practice per la produzione
Idempotenza
Progetta le tue pipeline in modo che possano essere rieseguite senza effetti collaterali. Lo stesso documento elaborato due volte deve produrre lo stesso risultato.
Logging strutturato
Registra ogni chiamata con lo schema utilizzato, il conteggio dei token e il tempo di risposta.
Retry con backoff
import time
def appel_avec_retry(messages, schema, max_retries=3):
for tentative in range(max_retries):
try:
return client.chat.parse(
model="grok-4.20-0309-reasoning",
messages=messages,
response_format=schema
)
except Exception as e:
if tentative < max_retries - 1:
time.sleep(2 ** tentative)
else:
raise
Monitoraggio
Traccia queste metriche per ogni pipeline:
- Tasso di successo per step
- Tempo medio di elaborazione
- Numero di token consumati
- Frequenza di fallback
Riepilogo del corso
In queste 12 lezioni, hai imparato a:
- Comprendere gli output strutturati e le loro garanzie
- Padroneggiare i tipi supportati e i loro limiti
- Utilizzare
parse()eresponse_formatin base alle tue esigenze - Definire schemi con Pydantic (Python) e Zod (JavaScript)
- Combinare output strutturati con ricerca web ed esecuzione di codice
- Costruire pipeline di estrazione, classificazione e convalida
Gli output strutturati trasformano gli LLM da strumenti conversazionali in componenti software affidabili, integrabili in qualsiasi architettura.
Punti chiave
- I flussi di lavoro multi-step utilizzano uno schema dedicato per ogni step
- La convalida incrociata confronta i risultati dell’estrazione con fonti di riferimento
- In produzione: idempotenza, logging strutturato, retry con backoff, monitoraggio
- Gli output strutturati sono il fondamento di qualsiasi pipeline AI affidabile
- Combina schemi (struttura) + prompt (contenuto) + strumenti (dati) per risultati ottimali
Metti alla prova le tue conoscenze
JSON garantito, schemi, pipeline: output strutturato, versione Grok.
1. Cosa garantisce l'output strutturato tramite schema?
Risposta: Un output strettamente conforme allo schema JSON dichiarato: tipi, campi, struttura, utilizzabile dal codice senza parsing difensivo; il formato è vincolato già in fase di generazione.
2. Cosa aggiunge il metodo parse() rispetto a response_format manuale?
Risposta: Il ciclo completamente automatizzato: il modello Pydantic (o Zod in JS) dichiara lo schema e la risposta torna già convalidata e tipizzata come oggetto: zero codice boilerplate.
3. Perché è importante conoscere i tipi non supportati?
Risposta: Perché uno schema che utilizza costrutti non supportati fallisce o si degrada: devi progettare i tuoi modelli entro il sottoinsieme accettato e convalidare in uscita.
4. Cosa permette di fare la combinazione output strutturati + ricerca web o esecuzione codice?
Risposta: Pipeline in cui la ricerca o il calcolo alimentano un output strutturato: informazioni aggiornate o calcolate arrivano direttamente nei tuoi campi tipizzati.
5. Fai due esempi di casi d'uso tipici in produzione.
Risposta: Estrazione e classificazione di entità (documenti, ticket, contenuti) collegate ai tuoi sistemi: flussi di lavoro automatizzati in cui l’AI riempie strutture, non paragrafi.
Schema dichiarato, generazione vincolata, convalida dell’output: l’output strutturato è l’interfaccia tra Grok e il tuo software: trattalo come tale.