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 "vero" o "falso", il modello potrebbe rispondere con un output amichevole e più di quanto hai chiesto, ad esempio: "Certo, la risposta è: vero".

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'è lo schema JSON

JSON Schema è un vocabolario che consente la coerenza, la validità e l'interoperabilità dei dati JSON su larga scala. Per quanto riguarda lo scambio di dati, JSON Schema si distingue come standard efficace 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 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 avrebbe il seguente aspetto:

{
  "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 tre elementi.
  • "items": { "type": "string", "pattern": "^#[^\\s#]+$" }: ogni elemento dell'array deve essere una stringa che corrisponda al pattern dell'espressione regolare specificata: ^#[^\\s#]+$:
    • ^# → deve iniziare con un #.
    • [^\\s#]+ → seguito da uno o più caratteri che non siano uno spazio (\s) o un altro #.
    • $ → must end there.

• "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, leggi la documentazione JSON Schema Basics.

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 e sarai a metà strada. Puoi quindi convalidare gli oggetti JSON in base allo schema JSON generato con uno dei convalidatori dello schema JSON, ad esempio il convalidatore dello schema JSON Newtonsoft online.

Trasmettere uno schema JSON all'API Prompt

Per assicurarti che il modello rispetti uno schema JSON richiesto, devi passare lo schema JSON come argomento ai metodi prompt() o promptStreaming() dell'oggetto options 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

Supportare 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, gli sviluppatori possono ora 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.