Programma Lezione 138 di 250 · Output strutturati e chiamate a funzioni/strumenti
Output strutturati e chiamate a funzioni/strumenti

Output vincolati e imposti da uno schema

Nelle ultime lezioni hai validato a mano il JSON del modello. La pratica moderna va un passo prima: impedire al modello di emettere JSON sbagliato fin dall'inizio. Questa è la decodifica vincolata (chiamata anche output strutturati). Dai all'API uno schema, e il decodificatore può estrarre solo token che mantengono l'uscita valida rispetto a quello. Il modello letteralmente non può produrre un campo mancante o un valore del tipo sbagliato.

Con un'API in stile OpenAI passi un response_format con un JSON Schema e strict: true (solo illustrativo -> qui non chiamiamo nessun modello):

resp = client.chat.completions.create(
    model="...",
    messages=[...],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
                "required": ["name", "age"],
            },
        },
    },
)

Il resto di questo corso chiama Anthropic, che offre la stessa garanzia con output_config per risposte in JSON garantito e con l'uso strict degli strumenti per input degli strumenti perfettamente conformi allo schema:

resp = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[...],
    output_config={"format": {
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
            "required": ["name", "age"],
        },
    }},
)

In ogni caso è il fornitore a vincolare. Ma la decodifica vincolata non può comunque controllare le tue regole di business (l'età è plausibile? la valuta è una che supporti?), e non tutti i modelli o gateway la supportano. Quindi validi comunque dalla tua parte. Quel validatore è ciò che costruisci adesso.

Dal lato Python lo standard di fatto per dichiarare e validare quella forma è Pydantic. Scrivi una classe modello e la libreria legge, converte e valida per te:

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

record = Person.model_validate_json(text)   # raises if it does not fit

Pydantic non è disponibile in questa sandbox nel browser, quindi costruirai la stessa idea a mano con la libreria standard. È esattamente ciò che queste librerie fanno sotto il cofano, e rende impossibile sorvolare sulle regole. Stai scrivendo validate_against_schema(obj, schema).

Lo schema è un dict. Ogni valore è o una stringa con il nome di un tipo ("int", "float", "str", "bool", "list", "dict") o un piccolo dict di specifica come {"type": "int", "default": 0}. La tua funzione restituisce un dict di risultato {"ok": bool, "value": dict, "errors": list}:

  • Se obj non è un dict, restituisci ok=False con un errore alla radice e un value vuoto.
  • Per ogni campo: se manca e la specifica ha un "default", metti il default (il passo di conversione/default). Se manca senza default, registra un errore.
  • Se c'è, controlla il suo tipo. Se non corrisponde, registra un errore che nomina il campo.
  • Converti un semplice int in un float quando serve un float (è senza perdite e sicuro), ma non convertire nient'altro.
  • Se ci sono stati errori, restituisci ok=False con gli errors raccolti e un value vuoto; altrimenti restituisci ok=True con il value validato.

La trappola bool-è-int. In Python bool è una sottoclasse di int, quindi isinstance(True, int) è True e il true di JSON diventa il True di Python. Un controllo del tipo ingenuo lascerebbe passare "age": true in un campo int. Rifiuta esplicitamente un bool ovunque sia richiesto un int o un float:

if expected is int and isinstance(value, bool):
    errors.append(field + ": expected int, got bool")

Costruiscila in modo che due payload diversi e ben formati passino entrambi, che un campo mancante e un tipo sbagliato finiscano ciascuno in errors, che un default venga messo, che un int venga convertito in float, e che un bool furbetto venga rifiutato dove è richiesto un numero.

Tocca a te

Scrivi validate_against_schema(obj, schema) che restituisce {"ok", "value", "errors"}. schema associa a ogni campo una stringa con il nome di un tipo ("int"/"float"/"str"/"bool"/"list"/"dict") o un dict di specifica {"type": ..., "default": ...}. Rifiuta un obj che non è un dict, registra un errore per ogni campo mancante (senza default) o del tipo sbagliato, metti un default quando è dato, converti un semplice int in float, e rifiuta un bool dove è richiesto un int o un float (la trappola bool-è-int). Restituisci ok=True con il value validato solo quando non ci sono errori.

Hai notato un problema in questa lezione? Segnalalo · Chiedi qualcosa su questa lezione

Questo esercizio si apre presto

Finisci la lezione precedente e questa si sblocca. L'intero corso è gratuito, senza account, e puoi leggere questa lezione subito.