Construindo com pensamento estendido
O pensamento estendido oferece ao Claude 3.7 Sonnet capacidades aprimoradas de raciocínio para tarefas complexas, ao mesmo tempo que proporciona transparência em seu processo de pensamento passo a passo antes de entregar sua resposta final.
Como funciona o pensamento estendido
Quando o pensamento estendido está ativado, o Claude cria blocos de conteúdo thinking
onde exibe seu raciocínio interno. O Claude incorpora insights deste raciocínio antes de elaborar uma resposta final.
A resposta da API incluirá blocos de conteúdo thinking
e text
.
Em conversas com múltiplos turnos, apenas os blocos de pensamento associados a uma sessão de uso de ferramenta ou turno do assistant
na última posição da mensagem são visíveis para o Claude e são cobrados como tokens de entrada; blocos de pensamento associados a mensagens anteriores do assistant
não são visíveis para o Claude durante a amostragem e não são cobrados como tokens de entrada.
Implementando o pensamento estendido
Adicione o parâmetro thinking
e um orçamento de tokens especificado para usar no pensamento estendido em sua requisição à API.
O parâmetro budget_tokens
determina o número máximo de tokens que o Claude pode usar para seu processo de raciocínio interno. Orçamentos maiores podem melhorar a qualidade da resposta ao permitir uma análise mais completa para problemas complexos, embora o Claude possa não usar todo o orçamento alocado, especialmente em faixas acima de 32K.
Seu budget_tokens
deve sempre ser menor que o max_tokens
especificado.
A resposta da API incluirá blocos de conteúdo thinking e text:
Entendendo os blocos de pensamento
Os blocos de pensamento representam o processo de pensamento interno do Claude. Para permitir que o Claude trabalhe em problemas com restrições internas mínimas enquanto mantém nossos padrões de segurança e nossas APIs sem estado, implementamos o seguinte:
- Os blocos de pensamento contêm um campo
signature
. Este campo contém um token criptográfico que verifica que o bloco de pensamento foi gerado pelo Claude, e é verificado quando os blocos de pensamento são passados de volta para a API. Ao transmitir respostas, a assinatura é adicionada via umsignature_delta
dentro de um eventocontent_block_delta
logo antes do eventocontent_block_stop
. Só é estritamente necessário enviar de volta blocos de pensamento ao usar uso de ferramentas com pensamento estendido. Caso contrário, você pode omitir blocos de pensamento de turnos anteriores, ou deixar que a API os remova para você se você os passar de volta. - Ocasionalmente, o raciocínio interno do Claude será sinalizado por nossos sistemas de segurança. Quando isso ocorre, criptografamos parte ou todo o bloco
thinking
e o retornamos para você como um blocoredacted_thinking
. Esses blocos de pensamento redatados são descriptografados quando passados de volta para a API, permitindo que o Claude continue sua resposta sem perder contexto.
Aqui está um exemplo mostrando blocos de pensamento normais e redatados:
Ver blocos de pensamento redatados em sua saída é um comportamento esperado. O modelo ainda pode usar este raciocínio redatado para informar suas respostas enquanto mantém as proteções de segurança.
Se você precisar testar o tratamento de pensamento redatado em sua aplicação, você pode usar esta string especial de teste como seu prompt: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB
Ao passar blocos thinking
e redacted_thinking
de volta para a API em uma conversa multi-turno, você deve incluir o bloco completo não modificado de volta para a API para o último turno do assistente.
Isso é crítico para manter o fluxo de raciocínio do modelo. Sugerimos sempre passar de volta todos os blocos de pensamento para a API. Para mais detalhes, veja a seção Preservando blocos de pensamento abaixo.
Sugestões para lidar com pensamento redatado em produção
Ao construir aplicações voltadas para o cliente que usam pensamento estendido:
- Esteja ciente de que os blocos de pensamento redatados contêm conteúdo criptografado que não é legível por humanos
- Considere fornecer uma explicação simples como: “Parte do raciocínio interno do Claude foi automaticamente criptografada por motivos de segurança. Isso não afeta a qualidade das respostas.”
- Se mostrar blocos de pensamento aos usuários, você pode filtrar os blocos redatados enquanto preserva os blocos de pensamento normais
- Seja transparente que usar recursos de pensamento estendido pode ocasionalmente resultar em algum raciocínio sendo criptografado
- Implemente tratamento de erros apropriado para gerenciar pensamento redatado sem quebrar sua UI
Transmitindo pensamento estendido
Quando o streaming está habilitado, você receberá conteúdo de pensamento via eventos thinking_delta
. Aqui está como lidar com streaming com pensamento:
Exemplo de saída de streaming:
Sobre o comportamento de streaming com pensamento
Ao usar streaming com pensamento habilitado, você pode notar que o texto às vezes chega em blocos maiores alternando com entrega token por token menor. Este é um comportamento esperado, especialmente para conteúdo de pensamento.
O sistema de streaming precisa processar conteúdo em lotes para desempenho ideal, o que pode resultar nesse padrão de entrega “em blocos”. Estamos continuamente trabalhando para melhorar essa experiência, com atualizações futuras focadas em fazer o conteúdo de pensamento fluir mais suavemente.
Blocos redacted_thinking
não terão deltas associados e serão enviados como um único evento.
Considerações importantes ao usar pensamento estendido
Trabalhando com o orçamento de pensamento: O orçamento mínimo é de 1.024 tokens. Sugerimos começar pelo mínimo e aumentar o orçamento de pensamento incrementalmente para encontrar a faixa ideal para o Claude ter um bom desempenho para seu caso de uso. Contagens de tokens mais altas podem permitir que você alcance um raciocínio mais abrangente e nuançado, mas também pode haver retornos decrescentes dependendo da tarefa.
- O orçamento de pensamento é um alvo em vez de um limite estrito - o uso real de tokens pode variar com base na tarefa.
- Esteja preparado para tempos de resposta potencialmente mais longos devido ao processamento adicional necessário para o processo de raciocínio.
- Streaming é necessário quando
max_tokens
é maior que 21.333.
Para orçamentos de pensamento acima de 32K: Recomendamos usar processamento em lote para cargas de trabalho onde o orçamento de pensamento é definido acima de 32K para evitar problemas de rede. Requisições que fazem o modelo pensar acima de 32K tokens causam requisições de longa duração que podem esbarrar em timeouts do sistema e limites de conexões abertas.
Compatibilidade do pensamento com outros recursos:
- O pensamento não é compatível com modificações de
temperature
,top_p
, outop_k
bem como uso forçado de ferramentas. - Você não pode pré-preencher respostas quando o pensamento está habilitado.
- Alterações no orçamento de pensamento invalidam prefixos de prompt em cache que incluem mensagens. No entanto, prompts do sistema em cache e definições de ferramentas continuarão funcionando quando os parâmetros de pensamento mudarem.
Preços e uso de tokens para pensamento estendido
Tokens de pensamento estendido contam para a janela de contexto e são cobrados como tokens de saída. Como os tokens de pensamento são tratados como tokens de saída normais, eles também contam para seus limites de taxa. Certifique-se de contabilizar este aumento no uso de tokens ao planejar seu uso da API.
Para o Claude 3.7 Sonnet, os preços são:
Uso de token | Custo |
---|---|
Tokens de entrada | $3 / MTok |
Tokens de saída (incluindo tokens de pensamento) | $15 / MTok |
Escrita em cache de prompt | $3,75 / MTok |
Leitura de cache de prompt | $0,30 / MTok |
Processamento em lote para pensamento estendido está disponível com 50% de desconto nesses preços e frequentemente é concluído em menos de 1 hora.
Todos os tokens de pensamento estendido (incluindo tokens de pensamento redatados) são cobrados como tokens de saída e contam para seus limites de taxa.
Em conversas multi-turno, blocos de pensamento associados a mensagens anteriores do assistente não são cobrados como tokens de entrada.
Quando o pensamento estendido está habilitado, um prompt de sistema especializado de 28 ou 29 tokens é automaticamente incluído para suportar este recurso.
Capacidades de saída estendida (beta)
O Claude 3.7 Sonnet pode produzir respostas substancialmente mais longas que modelos anteriores com suporte para até 128K tokens de saída (beta)—mais de 15x mais longo que outros modelos Claude. Esta capacidade expandida é particularmente efetiva para casos de uso de pensamento estendido envolvendo raciocínio complexo, geração rica de código e criação abrangente de conteúdo.
Este recurso pode ser habilitado passando um cabeçalho anthropic-beta
de output-128k-2025-02-19
.
Ao usar pensamento estendido com saídas mais longas, você pode alocar um orçamento de pensamento maior para suportar um raciocínio mais completo, enquanto ainda tem tokens amplos disponíveis para a resposta final.
Sugerimos usar streaming ou modo em lote com esta capacidade de saída estendida; para mais detalhes veja nossa orientação sobre considerações de confiabilidade de rede para requisições longas.
Usando pensamento estendido com cache de prompt
Cache de prompt com pensamento tem várias considerações importantes:
Inclusão de bloco de pensamento em prompts em cache
- O pensamento só é incluído ao gerar um turno do assistente e não é destinado a ser armazenado em cache.
- Blocos de pensamento de turnos anteriores são ignorados.
- Se o pensamento for desabilitado, qualquer conteúdo de pensamento passado para a API é simplesmente ignorado.
Regras de invalidação de cache
- Alterações nos parâmetros de pensamento (habilitar/desabilitar ou mudanças de orçamento) invalidam pontos de quebra de cache definidos em mensagens.
- Prompts do sistema e ferramentas mantêm o cache mesmo quando os parâmetros de pensamento mudam.
Exemplos de cache de prompt com pensamento estendido
Max tokens e tamanho da janela de contexto com pensamento estendido
Em modelos Claude mais antigos (anteriores ao Claude 3.7 Sonnet), se a soma dos tokens do prompt e max_tokens
excedesse a janela de contexto do modelo, o sistema ajustaria automaticamente max_tokens
para caber dentro do limite de contexto. Isso significava que você poderia definir um valor grande de max_tokens
e o sistema o reduziria silenciosamente conforme necessário.
Com o Claude 3.7 Sonnet, max_tokens
(que inclui seu orçamento de pensamento quando o pensamento está habilitado) é aplicado como um limite estrito. O sistema agora retornará um erro de validação se tokens do prompt + max_tokens
exceder o tamanho da janela de contexto.
Como a janela de contexto é calculada com pensamento estendido
Ao calcular o uso da janela de contexto com pensamento habilitado, existem algumas considerações a ter em mente:
- Blocos de pensamento de turnos anteriores são removidos e não contados para sua janela de contexto
- O pensamento do turno atual conta para seu limite de
max_tokens
para aquele turno
O diagrama abaixo demonstra o gerenciamento especializado de tokens quando o pensamento estendido está habilitado:
A janela de contexto efetiva é calculada como:
Recomendamos usar a API de contagem de tokens para obter contagens precisas de tokens para seu caso de uso específico, especialmente ao trabalhar com conversas multi-turno que incluem pensamento.
Você pode ler nosso guia sobre janelas de contexto para um mergulho mais profundo.
Gerenciando tokens com pensamento estendido
Dado o novo comportamento de janela de contexto e max_tokens
com modelos de pensamento estendido como o Claude 3.7 Sonnet, você pode precisar:
- Monitorar e gerenciar mais ativamente seu uso de tokens
- Ajustar valores de
max_tokens
conforme o comprimento do seu prompt muda - Potencialmente usar os endpoints de contagem de tokens com mais frequência
- Estar ciente de que blocos de pensamento anteriores não se acumulam em sua janela de contexto
Esta mudança foi feita para fornecer um comportamento mais previsível e transparente, especialmente à medida que os limites máximos de tokens aumentaram significativamente.
Pensamento estendido com uso de ferramentas
Ao usar pensamento estendido com uso de ferramentas, esteja ciente do seguinte padrão de comportamento:
-
Primeiro turno do assistente: Quando você envia uma mensagem inicial do usuário, a resposta do assistente incluirá blocos de pensamento seguidos por requisições de ferramentas.
-
Turno de resultado da ferramenta: Quando você passa a mensagem do usuário com blocos de resultado da ferramenta, a mensagem subsequente do assistente não conterá blocos de pensamento adicionais.
Para expandir aqui, a ordem normal de uma conversa de uso de ferramenta com pensamento segue estes passos:
- Usuário envia mensagem inicial
- Assistente responde com blocos de pensamento e requisições de ferramentas
- Usuário envia mensagem com resultados da ferramenta
- Assistente responde com mais chamadas de ferramentas ou apenas texto (sem blocos de pensamento nesta resposta)
- Se mais ferramentas forem requisitadas, repita os passos 3-4 até que a conversa esteja completa
Este design permite que o Claude mostre seu processo de raciocínio antes de fazer requisições de ferramentas, mas não repita o processo de pensamento após receber resultados da ferramenta. O Claude não produzirá outro bloco de pensamento até depois do próximo turno user
que não seja tool_result
.
O diagrama abaixo ilustra o gerenciamento de tokens da janela de contexto ao combinar pensamento estendido com uso de ferramentas:
Preservando blocos de pensamento
Durante o uso de ferramentas, você deve passar blocos thinking
e redacted_thinking
de volta para a API, e você deve incluir o bloco completo não modificado de volta para a API. Isso é crítico para manter o fluxo de raciocínio do modelo e a integridade da conversa.
Embora você possa omitir blocos thinking
e redacted_thinking
de turnos anteriores com papel assistant
, sugerimos sempre passar de volta todos os blocos de pensamento para a API para qualquer conversa multi-turno. A API irá:
- Filtrar automaticamente os blocos de pensamento fornecidos
- Usar os blocos de pensamento relevantes necessários para preservar o raciocínio do modelo
- Cobrar apenas pelos tokens de entrada para os blocos mostrados ao Claude
Por que os blocos de pensamento devem ser preservados
Quando o Claude invoca ferramentas, ele está pausando sua construção de uma resposta para aguardar informações externas. Quando os resultados da ferramenta são retornados, o Claude continuará construindo essa resposta existente. Isso necessita preservar blocos de pensamento durante o uso de ferramentas, por algumas razões:
-
Continuidade do raciocínio: Os blocos de pensamento capturam o raciocínio passo a passo do Claude que levou às requisições de ferramentas. Quando você posta resultados de ferramentas, incluir o pensamento original garante que o Claude possa continuar seu raciocínio de onde parou.
-
Manutenção do contexto: Embora os resultados da ferramenta apareçam como mensagens do usuário na estrutura da API, eles são parte de um fluxo contínuo de raciocínio. Preservar blocos de pensamento mantém este fluxo conceitual através de múltiplas chamadas de API.
Importante: Ao fornecer blocos thinking
ou redacted_thinking
, a sequência inteira de blocos consecutivos thinking
ou redacted_thinking
deve corresponder às saídas geradas pelo modelo durante a requisição original; você não pode reorganizar ou modificar a sequência destes blocos.
Dicas para fazer o melhor uso do modo de pensamento estendido
Para obter o máximo do pensamento estendido:
-
Defina orçamentos apropriados: Comece com orçamentos de pensamento maiores (16.000+ tokens) para tarefas complexas e ajuste com base em suas necessidades.
-
Experimente com orçamentos de tokens de pensamento: O modelo pode se comportar diferentemente com diferentes configurações máximas de orçamento de pensamento. Aumentar o orçamento máximo de pensamento pode fazer o modelo pensar melhor/mais intensamente, com o trade-off de maior latência. Para tarefas críticas, considere testar diferentes configurações de orçamento para encontrar o equilíbrio ideal entre qualidade e desempenho.
-
Você não precisa remover blocos de pensamento anteriores por conta própria: A API Anthropic automaticamente ignora blocos de pensamento de turnos anteriores e eles não são incluídos ao calcular o uso de contexto.
-
Monitore o uso de tokens: Mantenha o controle do uso de tokens de pensamento para otimizar custos e desempenho.
-
Use pensamento estendido para tarefas particularmente complexas: Habilite o pensamento para tarefas que se beneficiam de raciocínio passo a passo como matemática, codificação e análise.
-
Considere o tempo de resposta estendido: Leve em conta que gerar blocos de pensamento pode aumentar o tempo total de resposta.
-
Lide com streaming apropriadamente: Ao fazer streaming, esteja preparado para lidar com blocos de conteúdo tanto de pensamento quanto de texto conforme eles chegam.
-
Engenharia de prompt: Revise nossas dicas de prompting para pensamento estendido se você quiser maximizar as capacidades de pensamento do Claude.
Próximos passos
Was this page helpful?