Come ridurre la spesa per l'API di Claude: una guida pratica al costo dei token

Il modello mentale del budget di token

Ogni richiesta ha due fattori di costo:

• Token di input: prompt di sistema, messaggio dell'utente, cronologia della conversazione, definizioni degli strumenti, documenti recuperati e qualsiasi prefisso memorizzato nella cache che viene comunque conteggiato quando non è presente nella cache.
• Token di output: la risposta del modello, compresi la verbosità involontaria e i tentativi ripetuti.

Una formula mentale utile è:

request_cost ≈ input_tokens × input_rate + output_tokens × output_rate

Sembra ovvio, ma cambia il modo in cui analizzi la spesa. Se la richiesta media è “economica” nell'output ma costosa nell'input, eliminare 400 token dal prompt di sistema può contare più che chiedere al modello di essere più conciso.

Inizia dalla scelta del modello

Non tutte le attività richiedono il modello più capace. Nei sistemi reali, la selezione del modello è spesso l'ottimizzazione meno costosa.

Un errore comune è scegliere per impostazione predefinita il modello di fascia più alta. I team spesso inviano ogni prompt al modello di punta perché sembra più sicuro. In pratica, è una copertura costosa per attività che non ne traggono vantaggio. Un livello di instradamento di solito vale lo sforzo:

• Haiku per classificazione rapida, estrazione di JSON, etichettatura dei log e valutazione preliminare.
• Sonnet per la maggior parte dei carichi di lavoro basati su agenti o strumenti per sviluppatori.
• Opus solo quando l'attività richiede davvero un ragionamento più avanzato, una sintesi ricca di sfumature o quando hai misurato il costo di un errore.

Una semplice regola che funziona bene è:

1. Prova Haiku per attività strutturate a basso costo.
2. Passa a Sonnet se il livello di confidenza è basso o l'output non è nel formato corretto.
3. Passa a Opus solo per i casi davvero difficili.

Una catena di ripiego di questo tipo è solitamente più economica che pagare le tariffe di Opus per ogni richiesta.

Riduci il prompt di sistema senza compromessi

Il prompt di sistema è il luogo in cui lo spreco di token si nasconde in piena vista. Tende a crescere come il debito tecnico: una direttiva qui, una regola di stile là, cinque esempi che nessuno ha rimosso.

Cosa rimuovere

• Istruzioni duplicate che l'applicazione già applica.
• Lunghi testi sull'“essere utile” che non cambiano il comportamento.
• Vecchi esempi per casi limite che non contano più.
• Testi di policy ripetuti in ogni richiesta.
• Descrizioni prolisse degli strumenti quando basta uno schema compatto.

Cosa mantenere

• Vincoli di comportamento non negoziabili.
• Regole sul formato dell'output.
• Istruzioni essenziali per la sicurezza.
• Esempi minimi che migliorano concretamente l'affidabilità.

Nella pratica, ho visto team eliminare centinaia o migliaia di token dal prefisso ripetuto senza modificare la qualità del modello. Il trucco è trattare il prompt di sistema come codice di produzione: elimina il testo inutile, rimuovi le regole duplicate e conserva solo ciò che influisce sul comportamento.

Un approccio migliore è codificare la struttura invece di descriverla in prosa:

{
  "style": "concise",
  "output": "json",
  "must_include": ["root_cause", "next_steps"],
  "must_avoid": ["speculation", "apologies"]
}

È più facile da analizzare rispetto a tre paragrafi di istruzioni narrative.

Usa la cache dei prompt per i prefissi stabili

Se il tuo stack supporta la memorizzazione dei prompt nella cache, usala per tutto ciò che si ripete tra le richieste: prompt di sistema, schemi degli strumenti, esempi few-shot e lunghi blocchi di policy.

Il punto importante non è che “la cache è gratuita”. Non lo è. Il vantaggio è che smetti di pagare il prezzo pieno per lo stesso prefisso a ogni chiamata.

Buoni candidati per la cache

• Prompt di sistema comuni a tutto il prodotto
• Definizioni estese di funzioni e strumenti
• Istruzioni di recupero delle informazioni riutilizzate
• Esempi statici di formattazione o stile
• Struttura di supporto dell'agente che cambia raramente

Candidati inadatti alla cache

• Contesto dell'utente specifico di ogni richiesta
• Documenti appena recuperati
• Istruzioni che cambiano rapidamente
• Contenuto degli appunti di lavoro specifico della sessione

L'errore comune è inserire contenuti molto variabili nel prefisso e poi chiedersi perché le richieste trovino così raramente una corrispondenza nella cache. Per ottenere un vantaggio, mantieni stabile il segmento memorizzato nella cache e sposta dopo di esso i dati specifici della richiesta.

Esempio di struttura della richiesta:

{
  "system": "Stable application prompt + tool definitions + output contract",
  "messages": [
    { "role": "user", "content": "New ticket text here" }
  ]
}

Se mantieni stabile la parte stabile, dai alla cache la possibilità di essere davvero utile. Se il prefisso cambia a ogni richiesta, stai semplicemente pagando i costi aggiuntivi di gestione della cache senza alcun beneficio.

Imposta max_tokens Con decisione

Uno dei costi nascosti più comuni è un limite di completamento troppo alto. Se imposti max_tokens a un valore enorme “per sicurezza”, favorisci risposte lunghe, soprattutto quando il modello è incerto o prolisso.

Usa il limite più basso che consenta comunque di completare l'attività.

Intervalli pratici

• Estrazione / classificazione: 32–128 token
• Riepiloghi brevi: 128–256 token
• Diff del codice / spiegazioni: 256–800 token
• Generazione aperta: solo quanto necessario

Se il compito è «restituire un oggetto JSON», imposta un limite massimo rigido. Se il compito è «spiegare questa architettura», non lasciare al modello lo spazio per scrivere un romanzo, a meno che non sia quello che vuoi.

Molti team dimenticano anche di limitare i cicli di tentativi. Se il parsing fallisce e chiedi automaticamente al modello di riprovare con lo stesso generoso limite di output, puoi raddoppiare o triplicare la spesa per l'output di una singola azione dell'utente.

Raggruppa i piccoli compiti in batch

L'elaborazione in batch è utile quando hai molti compiti piccoli e indipendenti con un sovraccarico simile dovuto alle istruzioni.

Invece di fare così:

• 50 richieste di classificazione separate
• 50 prompt di sistema ripetuti
• 50 definizioni di strumenti ripetute

Fai così:

• Una richiesta contenente 50 elementi
• Un blocco di istruzioni condiviso
• Uno schema di output compatto

Esempio di struttura del prompt:

Classify each item into one of: bug, feature, question, billing.

Items:
1. "App crashes after login"
2. "Can you add dark mode?"
3. "How do I reset my password?"

E il contratto della risposta:

[
  {"id": 1, "label": "bug"},
  {"id": 2, "label": "feature"},
  {"id": 3, "label": "question"}
]

Questo riduce il sovraccarico ripetuto e spesso migliora la capacità di elaborazione. Il compromesso riguarda l'impatto degli errori: se un elemento non rispetta il formato, potrebbe essere necessario recuperare l'intero batch. Per i flussi di alto valore o rivolti agli utenti e sensibili alla latenza, batch più piccoli possono comunque essere preferibili.

Lo streaming migliora la reattività, non il costo dei token

Lo streaming è ottimo per l'esperienza utente e talvolta per il controllo dei costi, ma Non non riduce magicamente da solo i token fatturati. Paghi comunque per tutto ciò che il modello genera.

Lo streaming è utile soprattutto per l'interruzione anticipata:

• L'utente vede prima i progressi.
• La tua applicazione può annullare la generazione quando ha contenuto sufficiente.
• Puoi interrompere una risposta fuori controllo prima che raggiunga il limite configurato.

Quest'ultimo punto conta. Se stai generando una risposta per un parser a valle e i primi 120 token contengono già il JSON necessario, non continuare a raccogliere altri 800 token di spiegazione.

In pratica, lo streaming conviene quando la tua app può reagire durante la generazione. Se ti limiti a inviare lo stream a un log e ad aspettare comunque la risposta completa, ottieni il vantaggio per l'esperienza utente, ma una riduzione dei costi minima.

Misura il costo per richiesta, non solo quello mensile

La spesa mensile ti dice che hai un problema. Le metriche a livello di richiesta ti dicono dove si trova.

Monitora almeno:

• input_tokens
• output_tokens
• cache_hit_tokens se disponibile
• nome del modello
• endpoint / percorso della funzionalità
• latenza
• numero di tentativi
• tasso di troncamento o di errori di parsing

Un semplice payload di registrazione potrebbe essere così:

usage = response["usage"]

record = {
    "model": response["model"],
    "input_tokens": usage["input_tokens"],
    "output_tokens": usage["output_tokens"],
    "latency_ms": latency_ms,
    "cache_hit_tokens": usage.get("cache_read_input_tokens", 0),
    "request_type": "ticket_summary",
}
print(record)

Poi calcola il costo in modo centralizzato:

def estimate_cost(input_tokens, output_tokens, input_rate, output_rate):
    return (input_tokens * input_rate) + (output_tokens * output_rate)

Le tariffe esatte dipendono dal provider e dal modello, ma il flusso di lavoro rimane lo stesso. Una volta che puoi ordinare le richieste per costo, i responsabili di solito saltano all'occhio:

• Un prompt «piccolo» con un enorme prefisso nascosto
• Una chiamata a uno strumento che invia nuovamente documenti interi a ogni turno
• Un limite di completamento pari a 10x rispetto a quanto serve al compito
• Un ciclo di tentativi che raddoppia silenziosamente il consumo
• Un percorso che dovrebbe usare Haiku ma usa sempre Opus

Evita gli sprechi silenziosi

La maggior parte degli sprechi di token è banale, ed è per questo che sfugge alla revisione del codice.

Cause comuni

• Inviare nuovamente la stessa lunga cronologia della conversazione a ogni turno
• Includere file sorgente completi quando serve solo un diff
• Chiedere testo discorsivo quando basterebbe JSON strutturato
• Restituire spiegazioni prolisse a sistemi automatici
• Passare schemi degli strumenti più grandi del compito stesso
• Lasciare che i tentativi automatici rieseguano lo stesso prompt costoso
• Mantenere log o note interne nel contesto del modello

Un'insidia particolarmente fastidiosa è l'«espansione del contesto per aiutare». I sistemi di recupero spesso recuperano troppo materiale perché qualcuno voleva andare sul sicuro. Se al modello servono solo i tre paragrafi più pertinenti, non fornirgli l'intero documento solo perché il livello di suddivisione in blocchi lo rende facile.

Un'altra: se aggiungi attorno al modello un secondo prompt che dice «sii conciso», potresti aver appena aggiunto token per risolvere un problema di prolissità che avrebbe dovuto essere risolto con uno schema di output più restrittivo.

Una progettazione pratica delle richieste

Ecco una struttura che funziona bene per molti compiti in produzione:

request = {
    "model": "claude-sonnet-4.6",
    "max_tokens": 180,
    "system": "Extract the root cause and next action. Return strict JSON.",
    "messages": [
        {
            "role": "user",
            "content": "Investigate this incident summary: ... "
        }
    ]
}

Perché questa struttura funziona:

• Il modello scelto è abbastanza capace per un ragionamento di media complessità.
• Il limite di output tiene sotto controllo la prolissità.
• Il prompt di sistema è breve e specifico.
• Il formato di output è adatto all'elaborazione automatica.
• Il payload dell'utente contiene solo l'input necessario per il compito.

Se ti serve più contesto, aggiungilo intenzionalmente. Non lasciare che si accumuli per caso.

Cosa incide davvero sulla spesa

Se dovessi classificare i vantaggi maggiori, l'ordine sarebbe questo:

1. Scegli un modello più economico per i compiti semplici
2. Elimina il superfluo dai prompt
3. Limita max_tokens in modo deciso
4. Usa la cache dei prompt per i prefissi stabili
5. Raggruppa in batch i piccoli compiti indipendenti
6. Misura il consumo a livello di richiesta
7. Impedisci ai cicli di tentativi di raddoppiare la spesa

Quest'ordine conta. I team spesso iniziano con ottimizzazioni esotiche prima di risolvere il problema evidente: chiedono semplicemente troppo, troppo spesso, al modello più costoso, fornendogli troppo contesto.

Indicazioni pratiche

• Usa Haiku per l'estrazione e l'instradamento semplici, Sonnet per la maggior parte delle attività sul prodotto e Opus solo quando il compito lo giustifica.
• Considera la prompt di sistema come un centro di costo; elimina il testo ripetuto e mantieni solo le istruzioni che modificano il comportamento.
• Attiva la cache dei prompt per prefissi stabili come policy, schemi degli strumenti ed esempi few-shot.
• Imposta max_tokens al limite massimo utile più basso e rivedilo per ogni compito.
• Raggruppa in batch i piccoli compiti indipendenti quando il sovraccarico delle istruzioni è predominante.
• Monitora token di input, token di output, riscontri nella cache, tentativi e latenza per ogni richiesta.
• Fai attenzione agli sprechi silenziosi: cronologia ripetuta, recupero eccessivo di contenuti, output prolissi e cicli di tentativi automatici.

Se vuoi, posso trasformare questo testo in un articolo complementare con un esempio concreto di dashboard dei costi e alcune regole di instradamento per Haiku/Sonnet/Opus.