✔️✔️ Doppie Spunte Blu Cap. 11 · Prompt engineering decente

Puntata 115

Puntata 115 — Formato output

Livello: ✔️✔️ Doppie Spunte Blu · Capitolo 11 · Prompt engineering decente

Tabella, JSON, elenco, markdown, codice. Specificare il formato è uno dei modi più semplici per trasformare il modello da “amico chiacchierone” a “componente di un sistema”.

lo stesso prompt che entra in un imbuto e ne escono cinque output diversi: un paragrafo, una lista puntata, una tabella, un blocco JSON, uno schema Mermaid. Sotto, un robottino sceglie quale “tubo” prendere

Perché il formato è un’arma sottovalutata

L’AI sa scrivere in tanti formati. Ma se non glielo dici, sceglie il più “narrativo” — un paragrafo. Che è il peggior formato se:

  • Devi comparare elementi → ti serve una tabella.
  • Devi integrare con altro software → ti serve JSON.
  • Devi stampare un cheatsheet → ti serve markdown strutturato.
  • Devi eseguire qualcosa → ti serve codice.

Cambiare il formato non è cosmetica. Cambia come usi la risposta dopo.

I 7 formati che dovresti dominare

1. Paragrafo libero (default)

Per spiegazioni, narrativa, contenuti che si leggono. Default del modello, non serve specificarlo.

2. Lista puntata o numerata

“Rispondi in formato lista puntata, ogni voce di max 1 riga.”

Bene per: opzioni, ricette di prompt, take-aways. Velocità di lettura alta.

3. Tabella markdown

“Confronta i 3 modelli in una tabella markdown con colonne: nome, prezzo/1M token input, MMLU, context window. Una riga per modello.”

Resa visiva immediata. Funziona perfetto in Notion, Obsidian, GitHub.

4. JSON

“Output in JSON con questo schema: { ‘titolo’: string, ‘autori’: [string], ‘anno’: number, ‘parole_chiave’: [string] }. Niente testo extra prima o dopo il JSON.”

Per integrazione con codice. Vedi sotto la sezione JSON mode.

5. YAML

Più leggibile di JSON per umani, struttura simile. Usato in config DevOps.

6. Codice (Python/SQL/altro)

“Scrivi una funzione Python che [task]. Usa type hints. Aggiungi docstring. Non scrivere spiegazioni fuori dal codice.”

7. Diagrammi (Mermaid)

“Disegna un flow chart in sintassi Mermaid che rappresenti il processo di onboarding utente.”

Mermaid è leggibile come testo e renderizzabile su GitHub, Notion, Obsidian, vari tool. Disegnare diagrammi è diventato un prompt.

La sintassi-tipo

Frase chiave da incollare nel prompt:

“Output esclusivamente in [FORMATO]. Niente testo prima o dopo. Niente commenti.”

Le ultime due frasi sono importanti: senza, il modello tende ad aggiungere “Ecco il JSON che hai chiesto:” prima dell’output, rompendo il parsing automatico.

JSON mode: il caso più importante in produzione

In produzione, JSON valido è oro. Tutti i grandi provider hanno una modalità dedicata:

ProviderFeature
OpenAIresponse_format: { type: "json_object" } + structured outputs con JSON schema
AnthropicTool use forzato, structured output via XML/JSON schema
GeminiresponseSchema per JSON tipizzato
Modelli open (Llama, Qwen)Tool / function calling, BAML, Outlines

Senza modalità dedicata: il modello a volte rompe il JSON (virgolette sbagliate, virgole finali, commenti che non dovrebbero esserci).

Con modalità dedicata: il JSON è garantito sintatticamente valido. Cambia tutto per la stabilità in produzione.

⚠️ Garanzia sintattica ≠ semantica. JSON valido non significa “contenuto giusto”. Il modello può ancora allucinare i valori.

Schema-driven outputs

L’evoluzione di JSON mode: passi al modello uno schema preciso (JSON Schema, Pydantic, Zod) e il modello deve conformarsi.

Esempio Python con OpenAI SDK:

from pydantic import BaseModel
from openai import OpenAI

class EstrazioneFattura(BaseModel):
    numero_fattura: str
    data_emissione: str
    importo_totale: float
    iva_percentuale: float
    cliente: str

client = OpenAI()
response = client.responses.parse(
    model="gpt-5",
    input=[{"role": "user", "content": "Estrai dati da: [PDF fattura]"}],
    response_format=EstrazioneFattura
)
fattura = response.output_parsed
print(fattura.importo_totale)

Il modello restituisce un oggetto già tipizzato. Niente parsing manuale, niente errori di formato. Standard de-facto dal 2024.

Markdown ben gerarchizzato

Per documenti e report:

“Output in markdown, con: H1 per titolo, H2 per sezioni principali, H3 per sottosezioni, blockquotes per citazioni, code-block per esempi tecnici, tabelle per confronti. Niente HTML.”

Risultato: documento già pronto per essere incollato in Notion, Obsidian, GitHub README. Niente formattazione manuale.

I 5 errori più diffusi sul formato

1. Non specificare quando serve

“Genera 10 personas utente” → paragrafi lunghi, difficili da confrontare. Soluzione: “…in una tabella markdown con colonne: nome, età, lavoro, frustrazioni principali, motivazioni”.

2. Chiedere JSON senza specificare lo schema

“Output in JSON” → ogni run schema diverso. Inutilizzabile in produzione. Soluzione: includi lo schema esatto + esempio.

3. Mixare formati

“Scrivimi un riassunto in paragrafi + lista puntata + tabella” → il modello fa confusione, niente è ben strutturato. Soluzione: un solo formato dominante; eventualmente sezioni separate.

4. Dimenticare “no extra text”

JSON con prefisso “Ecco:” o suffisso “Fammi sapere se serve altro” → parser rotto. Soluzione: specifica esplicitamente “Output ESCLUSIVAMENTE [formato]. Niente prima, niente dopo.”

5. Strutture troppo profonde

JSON nidificati a 6 livelli → il modello sbaglia, alluci, perde tracciamento. Soluzione: appiattisci, usa array di oggetti semplici.

Formati misti utili

Esistono pattern in cui formati misti aiutano. Esempio per “analisi + raccomandazione”:

Output strutturato:

## Analisi
[paragrafo di 6-8 righe]

## Punti chiave
- bullet 1
- bullet 2
- bullet 3

## Raccomandazioni
| Priorità | Azione | Effort | Impatto atteso |
|---|---|---|---|
| Alta | … | Basso | Alto |

## Prossimi passi
1. …
2. …

Funziona: la struttura è fissa e prevedibile.

Output a lunghezza controllata

VincoloEsempio sintassi
Numero di parole”Massimo 300 parole.”
Numero di righe/bullet”Esattamente 5 bullet.”
Numero di caratteri”Max 280 caratteri (tweet).”
Tempo di lettura”2 minuti di lettura.”
Numero di paragrafi”3 paragrafi distinti.”

⚠️ I modelli non contano benissimo. Un “esattamente 5 bullet” può uscire con 4 o 6. Per garantirne 5 in produzione: post-processing nel codice, non fiducia cieca.

Streaming + formato

In produzione, vuoi mostrare la risposta mentre arriva (streaming). Il formato influisce sull’esperienza:

  • Paragrafo: streaming naturale, leggibile in tempo reale.
  • JSON: streaming “parziale” funziona solo con structured-output parsers (es. partial-json). Altrimenti l’utente vede JSON rotto fino alla fine.
  • Tabella markdown: si renderizza male in streaming finché non è completa.

Strategia comune: JSON in modalità non-streaming per stabilità + paragrafo in streaming per UX.

TEST pratico (5 minuti)

Prendi una task ripetuta: estrazione dati da email, generazione descrizioni prodotto, classificazione feedback. Provala in 4 formati diversi:

  1. Paragrafo libero (zero formato).
  2. Lista puntata (formato leggero).
  3. Tabella markdown (struttura visiva).
  4. JSON con schema (per integrazione codice).

Per ognuno, misura:

  • Tempo di lettura/parsing umano.
  • Riusabilità da codice.
  • Tasso di “errori di formato” su 10 run.

Sceglierai il formato giusto per il tuo caso. Nove volte su dieci il formato fa la differenza tra “demo che funziona” e “produzione stabile”.

Take-away in una riga

Il formato non è cosmetica: è interfaccia. JSON con schema è il “componente” del 2026; markdown ben gerarchizzato è il documento già pronto.

➡️ Prossima puntata: Vincoli negativi — dire cosa NON fare.