Output strutturati

Gli output strutturati vincolano le risposte di Claude a seguire uno schema specifico, garantendo output validi e analizzabili per l'elaborazione a valle. Gli output strutturati forniscono due funzionalità complementari:

• Output JSON (output_config.format): Ottieni la risposta di Claude in un formato JSON specifico
• Uso rigoroso degli strumenti (strict: true): Garantisci la convalida dello schema sui nomi e gli input degli strumenti

Puoi utilizzare queste funzionalità indipendentemente o insieme nella stessa richiesta.

Perché utilizzare output strutturati

Senza output strutturati, Claude può generare risposte JSON malformate o input di strumenti non validi che interrompono le tue applicazioni. Anche con un prompt attento, potresti incontrare:

• Errori di analisi da sintassi JSON non valida
• Campi obbligatori mancanti
• Tipi di dati incoerenti
• Violazioni dello schema che richiedono gestione degli errori e nuovi tentativi

Gli output strutturati garantiscono risposte conformi allo schema attraverso la decodifica vincolata:

• Sempre validi: Nessun altro errore JSON.parse()
• Type safe: Tipi di campo garantiti e campi obbligatori
• Affidabili: Nessun nuovo tentativo necessario per violazioni dello schema

Output JSON

Gli output JSON controllano il formato della risposta di Claude, garantendo che Claude restituisca JSON valido corrispondente al tuo schema. Utilizza gli output JSON quando hai bisogno di:

• Controllare il formato della risposta di Claude
• Estrarre dati da immagini o testo
• Generare report strutturati
• Formattare risposte API

Avvio rapido

Formato della risposta: JSON valido corrispondente al tuo schema in response.content[0].text

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}

Come funziona

Lavorare con output JSON negli SDK

Gli SDK forniscono helper che semplificano il lavoro con output JSON, inclusa la trasformazione dello schema, la validazione automatica e l'integrazione con librerie di schema popolari.

Utilizzo di definizioni di schema native

Invece di scrivere schemi JSON grezzi, puoi utilizzare strumenti di definizione di schema familiari nel tuo linguaggio:

• Python: modelli Pydantic con client.messages.parse()
• TypeScript: schemi Zod con zodOutputFormat() o letterali JSON Schema tipizzati con jsonSchemaOutputFormat()
• Java: classi Java semplici con derivazione automatica dello schema tramite outputConfig(Class<T>)
• Ruby: classi Anthropic::BaseModel con output_config: {format: Model}
• PHP: classi che implementano StructuredOutputModel con outputConfig: ['format' => MyClass::class]
• CLI, C#, : schemi JSON grezzi passati tramite

Metodi specifici dell'SDK

Ogni SDK fornisce helper che semplificano il lavoro con output strutturati. Consulta le pagine individuali dell'SDK per i dettagli completi.

Come funziona la trasformazione dell'SDK

Gli SDK Python, TypeScript, Ruby e PHP trasformano automaticamente gli schemi con funzionalità non supportate:

1. Rimuovi i vincoli non supportati (ad esempio, minimum, maximum, minLength, maxLength)
2. Aggiorna le descrizioni con informazioni sui vincoli (ad esempio, "Deve essere almeno 100"), quando il vincolo non è direttamente supportato con output strutturati
3. Aggiungi additionalProperties: false a tutti gli oggetti
4. Filtra i formati di stringa solo all'elenco supportato
5. Convalida le risposte rispetto al tuo schema originale (con tutti i vincoli)

Ciò significa che Claude riceve uno schema semplificato, ma il tuo codice applica comunque tutti i vincoli tramite validazione.

Esempio: un campo Pydantic con minimum: 100 diventa un numero intero semplice nello schema inviato, ma l'SDK aggiorna la descrizione a "Deve essere almeno 100" e convalida la risposta rispetto al vincolo originale.

Casi d'uso comuni

Uso rigoroso degli strumenti

Per applicare la conformità dello schema JSON agli input degli strumenti con campionamento vincolato dalla grammatica, vedi Uso rigoroso degli strumenti.

Utilizzo di entrambe le funzionalità insieme

Gli output JSON e l'uso rigoroso degli strumenti risolvono problemi diversi e funzionano insieme:

• Output JSON controllano il formato della risposta di Claude (cosa dice Claude)
• Uso rigoroso degli strumenti convalidano i parametri degli strumenti (come Claude chiama le tue funzioni)

Se combinati, Claude può chiamare strumenti con parametri garantiti validi E restituire risposte JSON strutturate. Questo è utile per flussi di lavoro agentici in cui hai bisogno sia di chiamate di strumenti affidabili che di output finali strutturati.

Considerazioni importanti

Compilazione della grammatica e caching

Gli output strutturati utilizzano il campionamento vincolato con artefatti di grammatica compilati. Questo introduce alcune caratteristiche di prestazione di cui essere consapevoli:

• Latenza della prima richiesta: La prima volta che utilizzi uno schema specifico, c'è una latenza aggiuntiva mentre la grammatica viene compilata
• Caching automatico: Le grammatiche compilate vengono memorizzate nella cache per 24 ore dall'ultimo utilizzo, rendendo le richieste successive molto più veloci
• Invalidazione della cache: La cache viene invalidata se modifichi:
  • La struttura dello schema JSON
  • L'insieme degli strumenti nella tua richiesta (quando si utilizzano sia output strutturati che uso degli strumenti)
  • La modifica solo dei campi name o description non invalida la cache

Modifica del prompt e costi dei token

Quando si utilizzano output strutturati, Claude riceve automaticamente un prompt di sistema aggiuntivo che spiega il formato di output previsto. Questo significa:

• Il tuo conteggio dei token di input è leggermente superiore
• Il prompt iniettato ti costa token come qualsiasi altro prompt di sistema
• La modifica del parametro output_config.format invaliderà qualsiasi cache dei prompt per quel thread di conversazione

Limitazioni dello schema JSON

Gli output strutturati supportano lo schema JSON standard con alcune limitazioni. Sia gli output JSON che l'uso rigoroso degli strumenti condividono queste limitazioni.

Ordinamento delle proprietà

Quando si utilizzano output strutturati, le proprietà negli oggetti mantengono il loro ordinamento definito dallo schema, con un'avvertenza importante: le proprietà richieste appaiono per prime, seguite dalle proprietà opzionali.

Ad esempio, dato questo schema:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

L'output ordinerà le proprietà come:

1. name (richiesto, in ordine di schema)
2. email (richiesto, in ordine di schema)
3. notes (opzionale, in ordine di schema)
4. age (opzionale, in ordine di schema)

Questo significa che l'output potrebbe assomigliare a:

{
  "name": "John Smith",
  "email": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Se l'ordine delle proprietà nell'output è importante per la tua applicazione, contrassegna tutte le proprietà come richieste o tieni conto di questo riordinamento nella tua logica di parsing.

Output non validi

Sebbene gli output strutturati garantiscano la conformità dello schema nella maggior parte dei casi, ci sono scenari in cui l'output potrebbe non corrispondere al tuo schema:

Rifiuti (stop_reason: "refusal")

Claude mantiene le sue proprietà di sicurezza e utilità anche quando si utilizzano output strutturati. Se Claude rifiuta una richiesta per motivi di sicurezza:

• La risposta ha stop_reason: "refusal"
• Riceverai un codice di stato 200
• Verrai addebitato per i token generati
• L'output potrebbe non corrispondere al tuo schema perché il messaggio di rifiuto ha la precedenza sui vincoli dello schema

Limite di token raggiunto (stop_reason: "max_tokens")

Se la risposta viene interrotta a causa del raggiungimento del limite max_tokens:

• La risposta ha stop_reason: "max_tokens"
• L'output potrebbe essere incompleto e non corrispondere al tuo schema
• Riprova con un valore max_tokens più alto per ottenere l'output strutturato completo

Limiti di complessità dello schema

Gli output strutturati funzionano compilando i tuoi schemi JSON in una grammatica che vincola l'output di Claude. Gli schemi più complessi producono grammatiche più grandi che richiedono più tempo per la compilazione. Per proteggere contro tempi di compilazione eccessivi, l'API applica diversi limiti di complessità.

Limiti espliciti

I seguenti limiti si applicano a tutte le richieste con output_config.format o strict: true:

Limiti interni aggiuntivi

Oltre ai limiti espliciti sopra, ci sono limiti interni aggiuntivi sulla dimensione della grammatica compilata. Questi limiti esistono perché la complessità dello schema non si riduce a una singola dimensione: funzionalità come parametri opzionali, tipi di unione, oggetti annidati e numero di strumenti interagiscono tra loro in modi che possono rendere la grammatica compilata sproporzionatamente grande.

Quando questi limiti vengono superati, riceverai un errore 400 con il messaggio "Schema is too complex for compilation." Questi errori significano che la complessità combinata dei tuoi schemi supera ciò che può essere compilato in modo efficiente, anche se ogni singolo limite sopra è soddisfatto. Come ultimo ostacolo, l'API applica anche un timeout di compilazione di 180 secondi. Gli schemi che superano tutti i controlli espliciti ma producono grammatiche compilate molto grandi possono raggiungere questo timeout.

Suggerimenti per ridurre la complessità dello schema

Se stai raggiungendo i limiti di complessità, prova queste strategie in ordine:

1. Contrassegna solo gli strumenti critici come rigorosi. Se hai molti strumenti, riservalo agli strumenti in cui le violazioni dello schema causano problemi reali e affidati all'aderenza naturale di Claude per gli strumenti più semplici.

2. Riduci i parametri opzionali. Rendi i parametri required dove possibile. Ogni parametro opzionale raddoppia approssimativamente una porzione dello spazio degli stati della grammatica. Se un parametro ha sempre un valore predefinito ragionevole, considera di renderlo richiesto e di far fornire a Claude quel valore predefinito esplicitamente.

3. Semplifica le strutture annidate. Gli oggetti profondamente annidati con campi opzionali compongono la complessità. Appiattisci le strutture dove possibile.

4. Dividi in più richieste. Se hai molti strumenti rigorosi, considera di dividerli tra richieste separate o sub-agenti.

Per problemi persistenti con schemi validi, contatta il supporto con la definizione del tuo schema.

Conservazione dei dati

I prompt e le risposte vengono elaborati con ZDR quando si utilizzano output strutturati. Tuttavia, lo schema JSON stesso viene temporaneamente memorizzato nella cache per un massimo di 24 ore dall'ultimo utilizzo a scopo di ottimizzazione. Nessun dato di prompt o risposta viene conservato oltre la risposta dell'API.

Gli output strutturati sono idonei per HIPAA, ma PHI non deve essere incluso nelle definizioni dello schema JSON. L'API compila gli schemi JSON in grammatiche che vengono memorizzate nella cache separatamente dal contenuto dei messaggi, e questi schemi memorizzati nella cache non ricevono le stesse protezioni PHI dei prompt e delle risposte. Non includere PHI nei nomi delle proprietà dello schema, nei valori enum, nei valori const o nelle espressioni regolari pattern. PHI dovrebbe apparire solo nel contenuto dei messaggi (prompt e risposte), dove è protetto secondo le garanzie di HIPAA.

Per l'idoneità ZDR e HIPAA in tutte le funzionalità, vedi API e conservazione dei dati.

Compatibilità delle funzionalità

Funziona con:

• Elaborazione batch: Elabora output strutturati su larga scala con sconto del 50%
• Conteggio dei token: Conta i token senza compilazione
• Streaming: Trasmetti output strutturati come risposte normali
• Utilizzo combinato: Utilizza output JSON (output_config.format) e uso rigoroso degli strumenti (strict: true) insieme nella stessa richiesta

Incompatibile con:

• Citazioni: Le citazioni richiedono l'interleaving di blocchi di citazione con testo, il che entra in conflitto con i vincoli dello schema JSON rigoroso. Restituisce errore 400 se le citazioni sono abilitate con output_config.format.
• Prefilling dei messaggi: Incompatibile con gli output JSON