Supporto dell'output strutturato per l'API Prompt

Thomas Steiner

Pubblicato il 13 maggio 2025

I modelli linguistici di grandi dimensioni (LLM) sono noti per le loro risposte occasionalmente lunghe. Anche se indichi al modello di rispondere solo con "true" o "false", il modello potrebbe rispondere con un output amichevole e più di quanto richiesto, ad esempio: "Certo, 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 per l'output strutturato è disponibile a partire dalla versione 137 di Chrome.

Che cos'è lo schema JSON

Lo schema JSON è un vocabolario che consente la coerenza, la validità e l'interoperabilità dei dati JSON su larga scala. Per quanto riguarda lo 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.

Lo schema JSON è lo standard di settore per garantire l'output strutturato, 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 per questa forma dell'oggetto di output richiesto sarà il seguente:

{
  "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 campo hashtags con i seguenti vincoli:

  • "type": "object": il valore radice 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 corrisponde 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.

Per una descrizione completa delle funzionalità del formato, consulta la documentazione Nozioni di base sullo schema JSON.

In realtà, 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 e sei a metà strada. Puoi quindi convalidare gli oggetti JSON rispetto allo schema JSON generato con uno dei validatori di schemi JSON, ad esempio il validatore di schemi JSON Newtonsoft online.

Convalida corretta di un oggetto JSON rispetto a uno schema JSON in un convalidatore di 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 delle opzioni 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 either true or 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

Supportare output prevedibili

Il supporto per l'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, gli sviluppatori ora possono presupporre che la risposta del modello sia un JSON valido.

In questo modo, l'AI integrata si avvicina di un passo alle API basate sul cloud, con tutti i vantaggi dell'esecuzione dell'AI locale lato client.