Pensiero esteso

Il pensiero esteso offre a Claude capacità di ragionamento avanzate per le attività complesse, garantendo al contempo diversi livelli di trasparenza nel processo di riflessione graduale prima di fornire la risposta definitiva. Ogni volta che si abilita la modalità pensiero di Claude, è necessario impostare un budget per il numero massimo di token che Claude può utilizzare per il processo di ragionamento interno.

I modelli supportati sono i seguenti:

Best practice e considerazioni sul pensiero esteso

Linee guida per l'utilizzo

Considerazioni sulle prestazioni

Compatibilità delle funzionalità

Utilizzo dei budget di pensiero

Funzionamento del pensiero esteso

Quando la funzionalità di pensiero esteso è attivata, Claude crea blocchi di contenuto thinking in cui produce il suo ragionamento interno. Claude incorpora le informazioni derivanti da questo ragionamento prima di formulare una risposta finale. La risposta dell’API includerà blocchi di contenuto thinking, seguiti da blocchi di contenuto text.

Ecco un esempio del formato di risposta predefinito:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text", 
      "text": "Based on my analysis..."
    }
  ]
}

Per ulteriori informazioni sul formato di risposta del pensiero esteso, consulta Richiesta e risposta dell’API Messages di Anthropic.

Come utilizzare il pensiero esteso

Per attivare il pensiero esteso, aggiungi un oggetto thinking, con il parametro thinking impostato su enabled e il parametro budget_tokens impostato su un budget di token specificato per il pensiero esteso.

Il parametro budget_tokens determina il numero massimo di token che Claude può utilizzare per il processo di ragionamento interno. Nel modelli Claude 4, questo limite si applica ai token di pensiero completo e non all’output riepilogato. Budget maggiori possono migliorare la qualità della risposta, consentendo un’analisi più approfondita per problemi complessi, anche se Claude può non utilizzare l’intero budget allocato, soprattutto per intervalli superiori a 32.000.

Il valore di budget_tokens deve essere impostato su un valore inferiore a max_tokens. Tuttavia, quando si utilizza Pensiero interlacciato (beta) con gli strumenti, è possibile superare questo limite perché il limite di token diventa l’intera finestra di contesto (200.000 token).

Pensiero riepilogativo

Con la funzionalità di pensiero esteso abilitata, l’API Messages per i modelli Claude 4 restituisce un riepilogo del processo di pensiero completo di Claude. Il pensiero riepilogativo offre tutti i vantaggi in termini di intelligenza del pensiero esteso, prevenendone al contempo l’uso improprio.

Di seguito sono riportate alcune considerazioni importanti per il pensiero riepilogativo:

Pensiero in streaming

Puoi trasmettere in streaming risposte di pensiero estese tramite eventi inviati dal server. Quando lo streaming è abilitato per il pensiero esteso, ricevi contenuti di pensiero tramite eventi thinking_delta. Non è garantito che gli eventi trasmessi in streaming vengano restituiti a una velocità costante. Potrebbero infatti verificarsi ritardi tra gli eventi. Per ulteriori informazioni sullo streaming tramite l’API Messages, consulta Streaming dei messaggi.

Ecco come gestire lo streaming nell’ambito del pensiero con InvokeModelWithResponseStream:

{
    "anthropic_version": "bedrock-2023-05-31",
    "max_tokens": 10000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 4000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is 27 * 453?"
        }
    ]
}

Risposta:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

Pensiero esteso con uso di strumenti

Il pensiero esteso può essere utilizzato insieme a Utilizzo degli strumenti, permettendo a Claude di ragionare tramite la selezione degli strumenti e l’elaborazione dei risultati. Quando utilizzi il pensiero esteso con gli strumenti, tieni presente le limitazioni seguenti:

Ecco come funziona la gestione delle finestre contestuali con gli strumenti:

{
    "anthropic_version": "bedrock-2023-05-31",
    "max_tokens": 10000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 4000
    },
  "tools": [
  {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string"
        }
      },
      "required": [
        "location"
      ]
    }
  }
],
    "messages": [
        {
            "role": "user",
            "content": "What's the weather in Paris?"
        }
    ]
}

La prima risposta è la seguente:

{
    "content": [
        {
            "type": "thinking",
            "thinking": "The user wants to know the current weather in Paris. I have access to a function `get_weather`...",
            "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxYsNrcs...."
        },
        {
            "type": "text",
            "text": "I can help you get the current weather information for Paris. Let me check that for you"
        },
        {
            "type": "tool_use",
            "id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
            "name": "get_weather",
            "input": {
                "location": "Paris"
            }
        }
    ]
}

La continuazione della conversazione con l’uso degli strumenti genererà un’altra risposta. Si noti che vengono passati sia thinking_block sia tool_use_block. Se il passaggio non avviene, si verifica un errore.

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 10000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 4000
  },
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string"
          }
        },
        "required": [
          "location"
        ]
      }
    }
  ],
      "messages": [
        {
          "role": "user",
          "content": "What's the weather in Paris?"
        },
        {
          "role": "assistant",
          "content": [
            {
              "type": "thinking",
              "thinking": "The user wants to know the current weather in Paris. I have access to a function `get_weather`…",
              "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxY",
            },
            {
              "type": "tool_use",
              "id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
              "name": "get_weather",
              "input": {
                "location": "Paris"
              }
            }
          ]
        },
        {
          "role": "user",
          "content": [
            {
              "type": "tool_result",
              "tool_use_id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
              "content": "Current temperature: 88°F"
            }
          ]
        }
      ]
    }

La risposta dell’API ora include solo testo

{
  "content": [
    {
      "type": "text",
      "text": "Currently in Paris, the temperature is 88°F (31°C)"
    }
  ]
}

Conservazione dei blocchi di pensiero

Quando si utilizza lo strumento, è necessario restituire i blocchi di pensiero all’API e includere nuovamente il blocco completo non modificato nell’API. Ciò è fondamentale per mantenere il flusso di ragionamento del modello e l’integrità della conversazione.

Quando Claude invoca gli strumenti, sospende la creazione di una risposta in attesa di informazioni esterne. Quando i risultati dello strumento vengono restituiti, Claude continua a creare la risposta esistente. Ciò richiede la conservazione dei blocchi di pensiero durante l’uso dello strumento per i seguenti motivi:

Pensiero interlacciato (beta)

I modelli Claude 4 supportano il pensiero interlacciato, una funzionalità che consente a Claude di pensare tra le chiamate agli strumenti e di eseguire ragionamenti più sofisticati dopo aver ricevuto i risultati dello strumento. Ciò consente interazioni di agenti più complesse in cui Claude può:

Per abilitare il pensiero interlacciato, aggiungi l’intestazione beta interleaved-thinking-2025-05-14 alla richiesta API.

Pensiero esteso con caching dei prompt

L’uso del caching dei prompt con il pensiero si presta a diverse importanti considerazioni:

Rimozione del contesto dei blocchi di pensiero

Modelli di invalidazione della cache

Informazioni sul comportamento del caching dei blocchi di pensiero

Quando si utilizza il pensiero esteso con gli strumenti, i blocchi di pensiero mostrano un comportamento di caching specifico che influisce sul conteggio dei token. La sequenza seguente illustra questo funzionamento.

Ecco un esempio dettagliato di flusso:

Richiesta 1

User: "What's the weather in Paris?"

Risposta 1

[thinking_block 1] + [tool_use block 1]

Richiesta 2

User: "What's the weather in Paris?",
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]

Risposta 2

[thinking_block 2] + [text block 2]

La richiesta 2 scrive nella cache il contenuto della richiesta (non della risposta). La cache include il messaggio utente originale, il primo blocco di pensiero, il blocco di utilizzo dello strumento e il risultato dello strumento.

Richiesta 3

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

Poiché è stato incluso un blocco utente non basato sui risultati degli strumenti, tutti i blocchi di pensiero precedenti vengono ignorati. Questa richiesta viene elaborata in modo analogo alla richiesta seguente:

Richiesta 3 alternativa

User: ["What's the weather in Paris?"]
Assistant: [tool_use block 1]
User: [tool_result_1, cache=True]
Assistant: [text block 2]
User: [Text response, cache=True]

Questo comportamento è coerente sia che si utilizzi il pensiero regolare che il pensiero interlacciato.

Numero massimo di token e dimensione della finestra contestuale nell’ambito del pensiero esteso

Nei modelli Claude meno recenti (precedenti a Claude 3.7 Sonnet), se la somma dei token di prompt e di max_tokens superava la finestra contestuale del modello, il sistema regolava automaticamente il valore max_tokens per adeguarlo al limite previsto per il contesto. In tal modo era possibile impostare un valore max_tokens elevato e il sistema lo riduceva automaticamente in base alle esigenze. Nei modelli Claude 3.7 e 4, il valore max_tokens, che include il budget di pensiero quando la funzionalità è abilitata, viene applicato come limite rigoroso. Il sistema ora restituisce un errore di convalida se la somma dei token di prompt e di max_tokens supera la dimensione della finestra contestuale.

Finestra contestuale nell’ambito del pensiero esteso

Quando si calcola l’utilizzo della finestra contestuale con la funzionalità di pensiero abilitata, è necessario considerare gli aspetti seguenti:

La finestra contestuale effettiva viene calcolata come: finestra contestuale = (token di input correnti - token di pensiero precedenti) + (token di pensiero + token di pensiero criptati + token di output di testo).

Gestione dei token nell’ambito del pensiero esteso e dell’uso degli strumenti

Quando si utilizza il pensiero esteso con gli strumenti, i blocchi di pensiero devono essere preservati in modo esplicito e restituiti con i risultati dello strumento. Il calcolo efficace della finestra contestuale per il pensiero esteso con l’uso degli strumenti diventa il seguente:

context window = (current input tokens + previous thinking tokens + tool use tokens) + (thinking tokens + encrypted thinking tokens + text output tokens)

Gestione dei token nell’ambito del pensiero esteso

In base alla finestra contestuale e al comportamento di max_tokens con i modelli Claude 3.7 e 4 con pensiero esteso, potrebbe essere necessario eseguire una di queste azioni:

Considerazioni sul costo dei token di pensiero esteso

Il processo di pensiero prevede costi per gli elementi seguenti:

Il parametro budget_tokens determina il numero massimo di token che Claude può utilizzare per il processo di ragionamento interno. Budget maggiori possono migliorare la qualità della risposta, consentendo un’analisi più approfondita per problemi complessi, anche se Claude può non utilizzare l’intero budget allocato, soprattutto per intervalli superiori a 32.000.

Con il pensiero interlacciato, il valore di budget_tokens può superare quello del parametro max_tokens, in quanto rappresenta il budget totale di tutti i blocchi di pensiero all’interno di un turno dell’assistente.

Quando si utilizza un pensiero riepilogativo, tenere presente le seguenti informazioni: