Supporto dell'output strutturato per l'API Prompt

Thomas Steiner

Data di pubblicazione: 13 maggio 2025

I modelli linguistici di grandi dimensioni (LLM) sono noti per le loro risposte occasionalmente lunghe. Anche se chiedi al modello di rispondere solo con "true" o "false", il modello potrebbe rispondere con un output amichevole e più di quanto richiesto, ad esempio: "Certamente, la risposta è: true."

Per risolvere questo problema, l'API Prompt ti consente di specificare un formato di output JSON della risposta del modello passando uno schema JSON ai metodi LanguageModel.prompt() e LanguageModel.promptStreaming(). Il supporto dell'output strutturato è disponibile a partire dalla versione 137 di Chrome.

Che cos'è JSON Schema

JSON Schema è un vocabolario che consente la consistenza, la validità e l'interoperabilità dei dati JSON su larga scala. Quando si tratta di scambio di dati, lo schema JSON si distingue come un potente standard per definire la struttura e le regole dei dati JSON. Utilizza un insieme di parole chiave per definire le proprietà dei dati.

JSON Schema è lo standard di settore per garantire un'uscita strutturata, utilizzato, tra gli altri, dall'API OpenAI e dall'API Gemini.

Ad esempio, chiedi al modello di assegnare al massimo tre hashtag per un post su un social network online, come Mastodon. L'output ideale potrebbe essere simile al seguente JSON:

{
  "hashtags": [
    "#pottery",
    "#dyi"
  ] 
}

Lo schema JSON corrispondente a questa forma dell'oggetto di output richiesto sarà quindi come segue:

{
  "type": "object",
  "properties": {
    "hashtags": {
      "type": "array",
      "maxItems": 3,
      "items": {
        "type": "string",
        "pattern": "^#[^\\s#]+$"
      }
    }
  },
  "required": ["hashtags"],
  "additionalProperties": false
}

Questo schema JSON definisce una struttura per un oggetto che deve contenere un hashtags campo con i seguenti vincoli:

  • "type": "object": il valore principale deve essere un oggetto JSON.
  • "properties": { "hashtags": ... }: l'oggetto può (e in questo caso deve) avere una proprietà denominata hashtags.

  • "hashtags":

    • "type": "array": il valore deve essere un array.
    • "maxItems": 3: l'array può contenere al massimo 3 elementi.
    • "items": { "type": "string", "pattern": "^#[^\\s#]+$" }: ogni elemento dell'array deve essere una stringa che corrisponda al pattern dell'espressione regolare specificato: ^#[^\\s#]+$:
      • ^# → deve iniziare con un #.
      • [^\\s#]+ → seguito da uno o più caratteri che non sono uno spazio (\s) o un altro #.
      • $ → deve terminare qui.

  • "required": ["hashtags"]: l'oggetto deve contenere la proprietà hashtags.

  • "additionalProperties": false: non sono consentite altre proprietà oltre agli hashtag.

Leggi la documentazione di JSON Schema di base per una descrizione completa delle funzionalità del formato.

Infatti, gli LLM sono molto bravi a creare schemi JSON. Descrivi i vincoli in linguaggio naturale nel prompt e fornisci un oggetto JSON di esempio valido. È tutto qui. Puoi quindi convalidare gli oggetti JSON in base allo schema JSON generato con uno dei validatori JSON Schema, ad esempio Newtonsoft JSON SchemaValidator online.

Convalida di un oggetto JSON rispetto a uno schema JSON in uno strumento di convalida dello schema JSON.

Passare uno schema JSON all'API Prompt

Per assicurarti che il modello rispetti uno schema JSON richiesto, devi passare lo schema JSON come argomento all'oggetto options dei metodi prompt() o promptStreaming() come valore di un campo responseConstraint.

Ecco un esempio di schema JSON molto semplice che assicura che il modello risponda con true o false per classificare se un determinato messaggio come questo post di Mastodon riguarda la ceramica.

const session = await LanguageModel.create();

const schema = {
  "type": "boolean"
};

const post = "Mugs and ramen bowls, both a bit smaller than intended- but that's
how it goes with reclaim. Glaze crawled the first time around, but pretty happy
with it after refiring.";

const result = await session.prompt(  
  `Is this post about pottery?\n\n${post}`,  
  {  
    responseConstraint: schema,  
  }  
);  
console.log(JSON.parse(result));  
// true

Supporta output prevedibili

Il supporto dell'output strutturato per l'API Prompt rende le risposte dell'LLM molto più prevedibili. Anziché estrarre un oggetto da una risposta Markdown o da un'altra post-elaborazione, ora gli sviluppatori possono assumere che la risposta del modello sia JSON valido.

In questo modo, l'AI integrata è un passo più vicina alle API basate su cloud, con tutti i vantaggi dell'esecuzione dell'AI lato client locale.