Ridurre i costi e migliorare le prestazioni con la piattaforma Claude

Ottimizzare la cache dei prompt, le istruzioni e l'impegno può ridurre il costo di Claude senza sacrificare le prestazioni dell'applicazione.

Prestazioni e costo sono spesso visti come un compromesso: per spendere meno, si accettano risultati peggiori. In pratica, abbiamo scoperto che molte applicazioni che utilizzano Claude Platform possono ridurre i costi senza rinunciare alle prestazioni con tre accorgimenti: massimizzare il tasso di hit della cache dei prompt, rimuovere gli anti-pattern dai prompt quando si passa ai modelli Claude più avanzati e calibrare l'impegno in base al compito. Abbiamo inserito queste indicazioni nella skill claude-api. In questo articolo, mostriamo come Claude Code con la skill claude-api possa spesso trovare modi per ridurre i costi mantenendo o migliorando le prestazioni.

Cache dei prompt

Prima che Claude generi una risposta, elabora il prompt in uno stato di lavoro interno. Questo passaggio, chiamato prefill, è la parte costosa della gestione dell'input. La cache dei prompt salva quello stato (la cache key-value, o KV): quando una richiesta inizia con lo stesso prefisso, Claude lo legge invece di ricalcolarlo. Le letture dalla cache vengono fatturate a una frazione del prezzo di input completo.

Ci sono alcune considerazioni pratiche per garantire un uso efficace della cache dei prompt. Innanzitutto, la cache dei prompt è associata a un modello specifico. In secondo luogo, le letture dalla cache dei prompt devono essere byte-esatte in tutto il prefisso. Infine, la cache dei prompt ha un time-to-live limitato (TTL).

Tenendo presenti questi punti, ecco alcuni suggerimenti pratici:

• Fai attenzione quando modifichi l'impostazione dell'impegno a metà conversazione. Queste impostazioni vengono renderizzate nel prompt prima del tuo contenuto, quindi fanno parte del prefisso memorizzato nella cache. Solo con alcuni modelli Claude selezionati, tra cui Opus 5 e Fable 5.1, puoi aggiornare l'impegno a metà conversazione senza rompere la cache.
• Mantieni i valori volatili fuori dal prefisso. Un timestamp o un ID dinamico nel prompt di sistema può cambiare tra le chiamate del modello e rompere la cache.
• Evita definizioni di strumenti che si riordinano da sole. Quando si utilizza l'API messages di Claude, il prompt viene assemblato in un ordine fisso con le definizioni degli strumenti renderizzate all'inizio. Qualsiasi modifica alla definizione dello strumento romperà la cache.
• Fai attenzione quando dividi le conversazioni in rami. I sottoagenti e i rami condividono la cache del genitore solo quando il prefisso del ramo è byte-identico, sullo stesso modello e utilizza lo stesso impegno.

Come risolvere

Abbiamo accumulato alcune lezioni per la gestione della cache dei prompt:

• Monitora attentamente il tasso di hit della cache dei prompt. Claude Console e l'API di diagnostica della cache forniscono diagnostica sulla cache dei prompt, inclusi i motivi dei miss della cache (Figura 1) e il punto esatto in cui due richieste divergono.

• Posticipa gli strumenti usati raramente. Dichiara tutti i tuoi strumenti in anticipo, ma contrassegna quelli usati raramente come defer_loading: rimangono fuori dal prefisso memorizzato nella cache e vengono aggiunti alla conversazione solo quando Claude li cerca con la ricerca degli strumenti, preservando così la cache.
• Applica gli aggiornamenti al prompt di sistema come messaggi. Alcuni modelli Claude ti consentono di aggiungere un'istruzione di sistema come messaggio a metà conversazione invece di modificare il prompt di sistema, preservando la cache.
• Organizza la richiesta in modo che la parte stabile rimanga stabile. Aggiungi prima il contesto statico (definizioni degli strumenti e prompt di sistema) e la conversazione in crescita dietro di essi (Figura 2).

• Apporta modifiche al modello o all'impegno quando la cache dei prompt sarà già rotta. Alcune operazioni, come la compattazione, riscrivono già gran parte della cache (la conversazione). Questo è un buon momento per cambiare modello o impegno, poiché pagherai comunque per un miss.
• Sposta il breakpoint della cache man mano che la conversazione cresce. Con Claude Platform, puoi impostare la memorizzazione automatica nella cache per applicare il breakpoint della cache all'ultimo blocco memorizzabile.
• Preriscalda la cache. Per ridurre la latenza, invia una richiesta con max_tokens: 0 e un breakpoint esplicito della cache, utilizzando la stessa impostazione di impegno del tuo traffico reale. Questo elabora il prompt e lo scrive nella cache senza generare nulla. Se lo esegui all'inizio della sessione (ad esempio, mentre un utente sta digitando), la prima richiesta reale troverà una cache calda.
• Non superare il TTL della cache dei prompt. Il TTL di 5 minuti della cache decorre dall'inizio della richiesta. Se un agente si blocca su chiamate di strumenti o richieste di sottoagenti che durano più di 5 minuti, la cache del genitore scade prima che il risultato torni. In casi come questo, considera l'idea di impostare un TTL di 1 ora sul prefisso.

Istruzioni

I prompt possono accumulare istruzioni che correggono le debolezze del modello. Queste istruzioni possono discostarsi dalle capacità dei modelli Claude più recenti. Ecco alcuni "anti-pattern" comuni di prompting che ostacolano i modelli Claude all'avanguardia e possono aumentare involontariamente i costi:

• Rituali di verifica. Istruzioni come "ricontrolla il tuo lavoro" o "verifica due volte prima di rispondere" vengono spesso prese alla lettera dai modelli all'avanguardia e possono sprecare token.
• Amplificatori di completezza ed enfasi. "Sii estremamente approfondito", "CRITICO: DEVI SEMPRE…" possono portare a verbosità e chiamate extra agli strumenti quando si lavora con modelli all'avanguardia.
• Procedure obbligatorie e strutture di scratchpad. Processi a passi fissi (ad es., "pensa passo dopo passo in uno scratchpad") o template di ragionamento sono rituali di cui i modelli all'avanguardia non hanno bisogno. Questa impalcatura può sovrapporsi al ragionamento nativo e utilizzare token non necessari.
• Esempi obsoleti. Esempi few-shot ottimizzati per le modalità di fallimento di un modello più vecchio possono insegnare a un modello all'avanguardia a imitare lunghe catene di ragionamento su richieste che non ne hanno bisogno.
• Regole contraddittorie. I modelli all'avanguardia sono migliori nel seguire le istruzioni. Istruzioni contraddittorie ("rimborsa sempre secondo la politica" vs. "non emettere mai rimborsi senza escalation") possono essere seguite più alla lettera dai modelli all'avanguardia, con conseguente degrado delle prestazioni.
• Configurazione datata. Impostazioni scritte per una generazione precedente di Claude (ad es., budget di pensiero manuali) possono essere rifiutate da Claude Platform con i modelli più recenti.

Come risolvere

Abbiamo aggiornato la skill claude-api con un nuovo comando che tiene d'occhio questi anti-pattern. In Claude Code, esegui /claude-api prompt-audit sui tuoi prompt, skill o descrizioni degli strumenti. Il controllo copre tutto ciò che si trova nella tua directory di lavoro, incluso il codice dell'applicazione che chiama l'API di Claude e la configurazione di Claude Code (ad es., CLAUDE.md o le skill).

Ad esempio, abbiamo testato una migrazione del modello da Opus 4.8 a Opus 5 su un benchmark di assistenza clienti. Siamo partiti da un prompt pulito e abbiamo inserito un anti-pattern alla volta (un'impostazione di pensiero ritirata, una coppia di regole di rimborso contraddittorie, uno scratchpad manuale, "verifica due volte", "sii estremamente approfondito" e una procedura obbligatoria in sei passaggi), ottenendo sei prompt legacy.

Abbiamo eseguito ciascuno su Opus 4.8, su Opus 5 con solo l'ID del modello cambiato e su Opus 5 dopo aver eseguito /claude-api prompt-audit una volta per prompt (la Figura 3 mostra la media dei sei).

Con Opus 5, i rituali di verifica ("verifica due volte") utilizzano token non necessari duplicando la ricerca dell'ordine su ogni rimborso. Gli amplificatori di enfasi ("sii estremamente approfondito") sono diventati dozzine di ricerche non necessarie nella knowledge base.

L'esecuzione di /claude-api prompt-audit ha rimosso gli anti-pattern, diminuendo i costi del 14,6% e aumentando la precisione del 5,3% in media. Il costo è diminuito perché sono state eliminate le chiamate extra agli strumenti e il ragionamento duplicato. La precisione è aumentata per tre motivi. L'impostazione di pensiero ritirata ha fatto sì che l'API rifiutasse immediatamente ogni richiesta di instradamento. Le regole di rimborso contraddittorie hanno portato Opus 5 a trattenere quattro rimborsi che doveva mentre chiedeva al cliente di confermare. E lo scratchpad manuale si è scontrato con il pensiero integrato di Opus 5: su tre ticket, ha scritto la chiamata allo strumento all'interno del suo ragionamento e non l'ha mai eseguita.

Impegno

L'impegno dice a Claude "quanto sforzo fare". A basso impegno, Claude generalmente raggiunge le conclusioni più velocemente. Ad alto impegno, Claude delibera, verifica ed esplora alternative prima di rispondere.

Il rapporto costo-prestazioni tra i diversi livelli di impegno su un singolo modello può variare. Ad esempio, Claude Fable 5 ottiene un punteggio dell'11,5% a basso impegno per $5,35 per attività su FrontierCode Diamond (le 50 attività più difficili). Al massimo impegno, Fable 5 ottiene il 30,9% per $19,00 per attività; cambiare l'impegno aumenta il punteggio di circa 2,7x (+19 punti) per circa 3,5x il costo (Figura 4).

Su Claude Fable 5.1, Humanity's Last Exam (senza strumenti) mostra una curva ripida con un ultimo passo decrescente. Ottiene circa il 53% a basso impegno per circa $0,30 per domanda e circa il 61% al massimo impegno per circa $2,23; l'ultimo passo fino al massimo aggiunge circa mezzo punto per un costo maggiore del 46%. Il guadagno rientra nel rumore run-to-run del benchmark, quindi paghi di più per nessun guadagno misurabile.

L'impegno può essere mal calibrato in entrambe le direzioni:

• Presupporre che più alto sia sempre meglio. Un impegno elevato può causare un eccesso di pensiero. Claude passa più tempo a deliberare di quanto il compito richieda, il che aggiunge costi e latenza e può degradare la qualità della risposta. La deliberazione aiuta solo finché c'è ancora evidenza da trovare.
• Propensione per un impegno basso. Impostato troppo basso, Claude si ferma prima di avere abbastanza evidenza. Effettua meno chiamate agli strumenti, quindi potrebbe rispondere in base al primo risultato di ricerca invece che al terzo. Pensa meno sui passaggi difficili e salta il controllo che normalmente eseguirebbe da solo. La risposta sembra completa, ma è costruita su informazioni parziali.

Come risolvere

Ci sono alcuni modi utili per calibrare l'impegno:

• Testa modelli più forti a impegno inferiore. Un modello più forte a basso impegno può essere più economico di un modello più debole che lavora sodo (alto impegno). Ad esempio, su CursorBench 3.2, Claude Fable 5.1 a basso impegno eguaglia le prestazioni di Fable 5 ad alto impegno a un terzo del costo (Figura 5). Due cose rendono il modello più recente più economico: a basso impegno fa meno lavoro per attività, e le letture dalla cache dei prompt di Fable 5.1 hanno un prezzo di $0,25 per milione di token contro $1,00 per Fable 5. Anche ai prezzi di Fable 5, Fable 5.1 a basso impegno costerebbe circa il 40% in meno.

• Comprendi la forma del tuo compito. Misurare le prestazioni dell'applicazione attraverso una serie di livelli di impegno è un modo utile per comprendere il compromesso costo-prestazioni per il tuo compito specifico. Su una valutazione non saturata, una curva costo-prestazioni piatta tra i livelli di impegno suggerisce che il compito non è vincolato dal pensiero computazionale; aumentare l'impegno non è vantaggioso.

Questa calibrazione spesso comporta l'esecuzione di una valutazione tra modelli e livelli di impegno. In Claude Code, /claude-api hillclimb esegue questa ricerca per te: divide la tua valutazione in set di training e test, propone modifiche alla configurazione e legge gli esempi di training falliti per correggere ciò che trova.

L'abbiamo eseguito su un benchmark di assistenza clienti, partendo da Opus 4.8 al suo impegno predefinito (alto). L'hillclimber ha prima provato Opus 5 a basso impegno, applicando prompt-audit per rimuovere rituali di chiamata obbligatori agli strumenti, passaggi di scratchpad e regole contraddittorie. Ciò ha superato la baseline di Opus 4.8 con una precisione del 98,9% sul training e ha ridotto il costo a 2,6 centesimi per ticket (Figura 6).

Ha poi abbassato l'impegno a Sonnet 5 a basso impegno, che era ancora più economico a 1 centesimo per ticket, ma la precisione è scesa all'88,9%. Leggendo i ticket di training falliti, Claude ha aggiunto regole di instradamento e un riferimento incrociato al limite di rimborso nel prompt, riportando Sonnet 5 al 98,9% allo stesso costo.

Sui 14 ticket trattenuti che la ricerca non ha mai visto, la configurazione finale ha ottenuto un punteggio del 90,5% contro il 78,6% della configurazione originale, a circa un quinto del costo.

Automazione della riduzione dei costi

La cache dei prompt, le istruzioni e l'impegno sono leve comuni per ridurre i costi. La nostra documentazione ne copre ancora di più. Per eseguire un controllo completo dei costi del codice dell'applicazione che utilizza l'API di Claude, abbiamo aggiunto /claude-api cost-optimize: profila dove va la tua spesa, applica riduzioni dei costi e, se fornisci una valutazione, mostra come i risparmi si confrontano con le prestazioni.

cost-optimize inizia trovando dove vanno i tuoi token: dai report di utilizzo e costo della tua organizzazione se hai una chiave API Admin di Claude, dall'oggetto di utilizzo su ogni risposta API se la tua applicazione lo registra o, in mancanza di entrambi, leggendo il codice di creazione della richiesta e stimando.

Classifica quindi i risparmi disponibili, iniziando dalla cache dei prompt, riducendo ciò che ogni richiesta trasporta (incluso un prompt-audit), limitando l'output e raggruppando il lavoro non presidiato. Se fornisci una valutazione, va oltre e calcola costi e prestazioni tra livelli di impegno e scelte di modello. Lo abbiamo eseguito su quattro benchmark pubblici con Sonnet 5 come baseline (Figura 7):

• LegalBench (~58% di costo inferiore): cost-optimize ha proposto di memorizzare nella cache un prefisso condiviso tra le attività, impostare un impegno basso ed elaborare le attività tramite l'API Batch. I token di pensiero sono passati da 102.779 a 8.284 e il tasso di superamento è rimasto entro il rumore e il costo è diminuito di circa il 58%.
• tau2-bench retail (~73% di costo inferiore): Implementando la cache dei prompt con posizionamento esplicito del breakpoint, cost-optimize ha ridotto la spesa del 72% mantenendo piatto il tasso di superamento.
• OfficeQA Pro (~52% di costo inferiore): cost-optimize ha aggiunto l'elaborazione batch e la memorizzazione nella cache dei documenti, che ha ridotto il costo da $136,20 a $64,87.
• SWE-bench Verified (~55% di costo inferiore): cost-optimize ha scoperto che la configurazione predefinita memorizza già correttamente nella cache. I risparmi sono derivati dall'impostazione dell'impegno su medio e dalla limitazione dell'output dell'agente a poche frasi concise. I passaggi mediani per attività sono passati da 29 a 17 e i token del prompt sono scesi da 75,2M a 33,7M.

Per iniziare

Inizia con /claude-api prompt-audit quando sei migrato a un modello Claude all'avanguardia e vuoi controllare i tuoi prompt esistenti. Scansiona i prompt, le skill e le descrizioni degli strumenti nella tua directory di lavoro. Può trattarsi di codice dell'applicazione che chiama l'API di Claude o della configurazione di Claude Code (CLAUDE.md, skill). Rimuove gli anti-pattern comuni che ostacolano i modelli all'avanguardia.

Ricorri a /claude-api cost-optimize quando la tua applicazione utilizza l'API di Claude e desideri un controllo dei costi. Profila la spesa in token e poi testa diverse leve: applica prompt-audit, ma controlla anche i modi per ridurre i costi tramite la cache dei prompt, il raggruppamento del lavoro non presidiato o la limitazione dell'output. Se fornisci una valutazione, misura i compromessi tra impegno e selezione del modello.

Infine, usa /claude-api hillclimb per una ricerca su costi e prestazioni. Data una valutazione, Claude la divide in set di training e test, quindi propone aggiornamenti alla tua applicazione che mirano a ridurre i costi mantenendo le prestazioni di base. Claude legge i casi di training falliti per guidare la ricerca e la configurazione finale viene valutata sul set di test trattenuto.

Per saperne di più:

• Consulta la nostra documentazione qui
• Consulta il nostro ricettario per la riduzione dei costi qui
• Consulta la skill claude-api qui; la skill è anche integrata in Claude Code
• Leggi questo articolo sul Claude Blog qui

Scritto da Lance Martin (@RLanceMartin), Brad Abrams (@brada), Isabella He (@IsabellaKHe) e Ben Lehrburger (@benlehrburger).