Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Flussi di lavoro automatizzati e pipeline

Lezione 12 di 12 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Passaggio alla produzione
  2. Flusso di lavoro: elaborazione documenti
  3. Pipeline di convalida dei dati
  4. Architettura della pipeline multi-step
  5. Best practice per la produzione
  6. Riepilogo del corso
  7. Punti chiave
  8. Metti alla prova le tue conoscenze

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() e response_format in 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.