Este texto explica o que é um LLM por dentro: como ele lê e escreve em tokens, o que é a janela de contexto e por que ele não conhece os seus dados privados nem o que aconteceu depois do treino. Também mostra por que ele inventa respostas com tanta segurança e quais são as três formas de dar conhecimento novo a ele: colar o material no prompt, ajustar o modelo (fine-tuning) ou buscar, na hora, o trecho certo e colocá-lo no prompt (RAG, geração aumentada por busca).

A aula parte do zero. Não pressupõe que você tenha olhado por dentro de um chatbot, só que já tenha visto um. Os exemplos de código usam Python e são curtos. As figuras são animadas e foram geradas com o ArchFlow. Tudo o que muda com o tempo (tamanhos de janela, tokenizadores, comportamento de modelos) vem da documentação oficial consultada em 15 de outubro de 2026, e a seção de fontes diz o que ficou sem verificação. Confira a documentação do modelo que você usa antes de copiar qualquer número.

Mapa da aula

Pré-requisito: nenhum. Ajuda ter lido Agents, porque lá a janela de contexto aparece como o recurso escasso que o brief protege (seções 5 e 11), e Spec-driven development, cuja seção 10 organiza o contexto em camadas. Ambas voltam aqui com um pouco mais de fundamento. Quase toda figura segue o mesmo mapa de cores: laranja para o que a pessoa escreve ou pergunta, um tom escuro de bronze e cinza (o hexágono do LLM) para o modelo, verde para dados, documentos e respostas boas, azul para instruções e parâmetros, cinza para infraestrutura neutra, e rosa para o que dá errado.

Parte 1: Fundamentos

1. O que é um LLM

Pense no teclado do seu celular sugerindo a próxima palavra enquanto você digita “Vou chegar em”. Ele não entende de pontualidade. Ele só aprendeu, olhando muito texto, que depois dessa frase costumam vir palavras como “casa”, “breve” ou “dez minutos”. Agora imagine esse mesmo truque feito por algo que leu uma fração gigantesca de tudo o que foi escrito em livros, sites, manuais e código, e que consegue considerar milhares de palavras anteriores para decidir a próxima. Esse algo é um LLM.

LLM vem de large language model, modelo de linguagem grande. A definição curta é esta: um LLM é um programa que, dado um texto, calcula quais pedaços de texto têm mais chance de vir em seguida. Só isso. Escolhe um pedaço, anexa ao texto, calcula de novo, escolhe outro, e repete até terminar. Quando o texto de partida é “Explique o que é um índice de banco de dados”, a continuação mais plausível é uma explicação. Quando é def soma(a, b):, é código. A aparência de conversa, de raciocínio, de tradução, tudo isso nasce do mesmo laço: prever o próximo pedaço, anexar, repetir.

A figura mostra o laço inteiro com um exemplo minúsculo.

Comece pelo documento laranja no topo, o texto escrito até agora (“O céu está”). Ele entra no hexágono do LLM, que é o modelo, e o selo “pesos fixos” lembra que nada dentro dele muda durante a conversa (a seção 6 explica por quê). O modelo não devolve uma palavra, e sim uma nota para cada pedaço possível, convertida em probabilidade: no exemplo, “azul” com 62%, “nublado” com 21%, “limpo” com 6%, e milhares de outros dividindo o resto (os valores são ilustrativos, inventados para a figura). Os pacotes verdes mais numerosos na seta de “azul” mostram que ele recebe a maior parte da chance. O losango azul “Escolhe um” sorteia um dos candidatos de acordo com essas probabilidades, o escolhido é anexado ao texto, e o losango “Acabou?” decide se o laço continua. O caminho “não” volta ao começo com um texto maior, e o caminho “sim” entrega a resposta pronta.

Uma ressalva de vocabulário que vale a pena fixar desde já: “pedaço de texto” é uma simplificação. A unidade real é o token, e a seção 4 explica o que ele é. Até lá, leia “token” como “um pedaço de palavra, uma palavra curta ou um sinal de pontuação”.

2. Por que isso existe: o problema que o LLM resolve

Antes dos modelos de linguagem grandes, cada tarefa de linguagem pedia um sistema próprio. Um programa para corrigir ortografia, outro para traduzir, outro para classificar e-mails em “spam” e “não spam”, outro para responder perguntas de uma lista fixa, cada um com regras escritas à mão ou com um modelo treinado só para aquilo. Quem quisesse um resumidor de contratos precisava juntar exemplos, treinar e manter um modelo exclusivo. Quem quisesse mudar a tarefa recomeçava.

A ideia que mudou o jogo foi treinar um único modelo na tarefa mais genérica possível, prever o próximo pedaço de texto, usando uma quantidade enorme de texto. Para prever bem o que vem depois de “A capital da França é”, o modelo precisa absorver geografia. Para prever bem o que vem depois de uma função com um erro, precisa absorver programação. Para continuar um diálogo de forma plausível, precisa absorver como as pessoas conversam. Uma tarefa simples e escalável acaba exigindo, de brinde, uma enorme variedade de habilidades.

O ganho prático é que a interface passa a ser a própria língua. Para trocar a tarefa, você troca o texto de entrada: “traduza”, “resuma em três linhas”, “extraia as datas deste contrato em JSON”. Não há novo treino a cada pedido. O preço dessa generalidade é o que o resto da aula investiga: o modelo é um previsor de texto plausível, não um banco de dados de fatos verificados, e isso explica tanto o que ele faz bem quanto os lugares onde ele falha.

3. Exemplos no plural: o mesmo mecanismo em quatro produtos

Vale ver o mecanismo em contextos diferentes, porque é fácil achar que “chatbot” e “assistente de código” são tecnologias distintas.

À esquerda, em laranja, estão quatro começos de texto escritos por uma pessoa. À direita, em verde, as continuações. No meio, o mesmo hexágono. As quatro setas de entrada saem com defasagem, uma de cada vez, só para mostrar que são consultas independentes, e o mesmo vale na volta. O que muda de um produto para outro é o começo do texto e o acabamento ao redor do modelo, e o mecanismo central continua igual.

No teclado do celular, o começo é “Vou chegar em” e a continuação é uma palavra sugerida. No chatbot, o começo é uma pergunta e a continuação é uma resposta em parágrafos. O chat parece uma conversa de duas pessoas porque o produto formata o texto como um diálogo (marcando quem fala) e o modelo, treinado também para isso, continua do lado do assistente. No assistente de código, o começo é uma assinatura de função ou um comentário e a continuação é o corpo, porque código é texto com padrões fortes. No tradutor, o começo é uma instrução com o texto de origem e a continuação é a tradução. Em todos, quem decide o que vem a seguir é a probabilidade de cada pedaço dado tudo o que veio antes.

Isso também antecipa um tema que volta o tempo todo: o modelo só reage ao texto que recebe. Se você quer que ele traduza, resuma ou responda com base em um documento, o jeito é colocar essa intenção e esse documento no texto de entrada.

Parte 2: Tokens e geração

4. Tokens: a moeda do modelo

Quando você digita “O gato subiu no telhado.”, o modelo não recebe letras e também não recebe palavras. Recebe uma sequência de números inteiros, cada um representando um pedaço de texto de um dicionário fixo chamado vocabulário. Esses pedaços são os tokens. Um token pode ser uma palavra inteira e comum (” gato”), um pedaço de palavra rara (“tel” e “hado”, em “telhado”), um sinal de pontuação ou até um byte solto de um caractere pouco comum.

O programa que faz a conversão entre texto e números é o tokenizador. Ele é separado do modelo, tem seu próprio vocabulário e é aplicado duas vezes, como mostra a figura: antes do modelo, para converter o seu texto em ids, e depois, para converter em texto os ids que o modelo escolhe.

Siga a figura de cima para baixo. O texto laranja entra no tokenizador, que o corta em pedaços conhecidos. A divisão real, obtida com a biblioteca tiktoken (versão 0.14.0, vocabulário o200k_base), foi O, gato, sub, iu, no, tel, hado, .. Repare que o espaço pertence ao pedaço seguinte: gato é um token, gato sem espaço é outro. Cada pedaço é procurado no vocabulário e vira um id, e a lista de ids (46, 99767, 1543 e assim por diante) é a única coisa que o LLM enxerga. Do outro lado, o modelo devolve um id por vez e o segundo tokenizador converte de volta em texto. A divisão acima é ilustrativa: cada tokenizador divide de um jeito, então outro modelo cortaria a mesma frase em outros pedaços e com outros ids.

Por que não usar letras ou palavras? Com letras, as sequências ficam longas demais (uma página teria milhares de passos) e o modelo teria de reaprender a formar palavras a cada frase. Com palavras inteiras, o vocabulário precisaria de um item para cada forma de cada palavra em cada idioma, mais nomes próprios, erros de digitação, código e emojis, e qualquer palavra fora da lista ficaria sem representação. Os tokens são um meio-termo: palavras frequentes ocupam um token só, e palavras raras se decompõem em pedaços, de modo que nenhum texto fica sem representação.

BPE em alto nível

O método mais usado para construir esse vocabulário se chama BPE (byte pair encoding, codificação por pares de bytes). A ideia, em alto nível, é começar com os símbolos mais básicos (caracteres ou bytes) e olhar um corpus enorme de texto, procurando qual par de símbolos vizinhos aparece com mais frequência. Esse par vira um símbolo novo. Repete-se o processo milhares de vezes, e cada rodada cria um pedaço maior a partir dos que já existem. No fim, o que é muito frequente (“ção”, ” de”, ” the”) virou um token só, e o que é raro continua em pedaços pequenos. A documentação do tiktoken descreve o BPE como reversível e sem perdas (dá para voltar ao texto original), capaz de lidar com texto que nunca viu, e com compressão média de cerca de 4 bytes por token, além de manter inteiros os subpedaços comuns: “encoding” pode virar “encod” e “ing”.

Por que o português costuma gastar mais tokens

O vocabulário é montado a partir de um corpus, e o corpus de treino costuma ter muito mais inglês do que português. Pedaços frequentes em inglês viram tokens únicos, enquanto o português, menos representado, tende a ser cortado em pedaços menores, o que gera mais tokens para o mesmo conteúdo. A figura compara dois tokenizadores sobre o mesmo parágrafo em duas línguas.

À esquerda estão os dois textos laranja, um parágrafo de contrato em português (37 palavras, 223 caracteres) e a tradução em inglês (36 palavras, 222 caracteres). No meio, dois tokenizadores da biblioteca tiktoken. À direita, a contagem. Com o o200k_base, o português gastou 46 tokens contra 42 do inglês, uma diferença de cerca de 10%. Com o cl100k_base, um vocabulário anterior, foram 58 contra 42, uma diferença de cerca de 38%, e é por isso que o retângulo está em rosa, com os pacotes pesados e lentos na seta. O inglês gastou 42 nos dois, ou seja, o vocabulário mais novo melhorou principalmente o português. São contagens de um único parágrafo que eu mesmo medi, e servem para ilustrar a ordem de grandeza, não para prever o seu texto. O que vale como regra é a lição de método: a quantidade de tokens depende do texto e do tokenizador, e muda de um modelo para outro.

Há um exemplo oficial dessa dependência. A documentação da Claude diz que os modelos a partir da versão Claude 4.7 usam um tokenizador mais novo, e que o mesmo texto produz aproximadamente 30% mais tokens do que nos modelos anteriores, dependendo do conteúdo. A recomendação da própria documentação é recontar os prompts com o modelo que você vai usar em vez de reaproveitar contagens antigas.

Token como unidade de custo e de limite

Tokens importam por duas razões práticas. A primeira é o custo: serviços de LLM cobram por token processado, em geral com preços separados para o que entra e o que sai, de modo que um texto mais longo, ou escrito num idioma que gasta mais tokens, custa mais. A segunda é o limite: a janela de contexto (seção 7) é medida em tokens, não em palavras nem em páginas. Qualquer conversa sobre “quanto cabe” ou “quanto custa” é uma conversa sobre tokens.

A regra de bolso de que um token tem alguns caracteres (a documentação do tiktoken cita cerca de 4 bytes por token em média) serve para estimar em inglês, mas falha em português, em código, em tabelas e em texto com números. Por isso o hábito certo é medir. O exercício 1 mostra como, e vale lembrar que o contador oficial de cada fornecedor é o que conta: a API de contagem de tokens da Anthropic, por exemplo, é gratuita (com limite de requisições por minuto) e retorna uma estimativa que pode diferir um pouco do valor real cobrado.

5. Como o modelo gera texto

Já vimos o laço da figura 1. Agora vamos olhar dentro de uma rodada.

Para cada posição, o modelo produz uma nota (um número) para cada token do vocabulário, que tem da ordem de centenas de milhares de itens. Essas notas passam por uma função que as transforma em probabilidades positivas que somam 100%. Uma distribuição de probabilidade é isso: uma lista de candidatos com a chance de cada um. O token escolhido para continuar é sorteado dessa distribuição. Se “azul” tem 62%, ele sai em cerca de 62 de cada 100 sorteios, e “nublado” sai em cerca de 21. Esse sorteio explica por que fazer a mesma pergunta duas vezes pode render respostas diferentes.

Temperatura

A temperatura é um parâmetro que ajusta o quanto o sorteio respeita o favorito. Tecnicamente, as notas são divididas pela temperatura antes de virarem probabilidades. Com temperatura baixa, a divisão exagera a vantagem do token mais pontuado, e a distribuição fica afiada: o favorito leva quase tudo. Com temperatura alta, a vantagem diminui, a distribuição fica achatada e tokens menos prováveis ganham chance. Com temperatura tendendo a zero, o modelo escolhe praticamente sempre o primeiro colocado.

A figura parte das mesmas notas do mesmo LLM (hexágono à esquerda) e mostra os dois caminhos. No caminho de cima, a temperatura baixa gera uma distribuição afiada: “azul” com 90%, e as setas para “nublado” e “limpo” são finas, com um pacote lento, indicando chance pequena. O sorteio quase sempre cai em “azul”, e o resultado é “quase sempre igual”. No caminho de baixo, a temperatura alta achata: “azul” com 45%, “nublado” com 30%, “limpo” com 15% e outros com 10%, e o resultado varia a cada execução. Os percentuais são ilustrativos, escolhidos para a figura.

O porquê prático: temperatura baixa serve quando você quer consistência (extrair dados de um contrato, gerar código, responder com base em um documento). Temperatura mais alta serve quando você quer variedade (sugerir nomes, brincar com texto criativo). Em tarefas de RAG, em que a resposta deve seguir os documentos, é comum preferir temperatura baixa. Duas ressalvas: a temperatura reduz a variação, mas não garante resposta idêntica em toda chamada nem garante que a resposta esteja certa, porque um token provável pode ser factualmente errado; e alguns modelos e APIs restringem ou ignoram esses parâmetros, então confira a documentação do modelo que você usa (não verifiquei os valores aceitos por cada modelo atual).

Existe também o parâmetro top-p, que corta a cauda da distribuição e sorteia só entre os candidatos que somam uma probabilidade acumulada escolhida. É outro jeito de controlar o quanto o modelo se arrisca, e geralmente se ajusta um ou outro, não os dois ao mesmo tempo.

Parada

O laço precisa parar em algum momento. O modelo tem um token especial de fim de turno, e quando o sorteio o escolhe, a geração termina. Na API da Anthropic, isso aparece como stop_reason: "end_turn". Você também pode definir sequências de parada (stop sequences): se o texto gerado chegar a uma delas, a geração para e o motivo é "stop_sequence". E existe o limite de tamanho da resposta, max_tokens: a documentação avisa que o modelo pode parar antes de atingir esse máximo, e que, se o atingir, a resposta pode terminar cortada no meio da frase. A parada abrupta por limite é uma das primeiras coisas que confundem quem começa: a resposta “acabou” porque o orçamento acabou, não porque o modelo concluiu o raciocínio.

6. Treino e uso: o que fica fixo

O LLM passa por duas fases muito diferentes. A primeira é o treino (para ser mais exato, o pré-treino): bilhões de ajustes nos números internos do modelo, chamados pesos ou parâmetros, para que ele acerte cada vez mais a previsão do próximo token em um corpus gigante. Isso leva meses, usa milhares de processadores especializados e custa uma fortuna, e por isso é feito uma vez, pelo fornecedor. Depois do pré-treino, os modelos passam por etapas adicionais que os ensinam a seguir instruções e a se comportar como assistentes, mas o princípio é o mesmo: no fim, os pesos são salvos.

A segunda fase é o uso, também chamado de inferência: você envia um texto e o modelo gera a continuação. Aqui os pesos não mudam. O modelo é uma função fixa que recebe texto e devolve probabilidades. Nada do que você digita é gravado nos pesos.

O grupo de cima é o treino. O corpus (verde) entra no treinamento, que gira (a animação marca processamento contínuo) e tem o selo “caro e demorado”. O resultado são os pesos congelados, que carregam tudo o que o modelo aprendeu até uma data, o corte de conhecimento. A nuvem rosa ao lado representa tudo o que ficou de fora: fatos que surgiram depois do corte e dados privados que nunca estiveram no corpus. A seta rosa com o ✕, “fora do corpus”, mostra que esse conteúdo não chega ao treinamento. O grupo de baixo é o uso, a cada chamada. Os pesos congelados chegam como “cópia fixa” (seta grossa) ao modelo em inferência, que lê o seu prompt (laranja) e um documento que você colou (verde), e gera a resposta. O documento vale só para aquela chamada, e na próxima ele terá sumido, a menos que seja enviado de novo.

Essa separação é a chave de quase tudo que vem a seguir. O modelo sabe o que absorveu no treino, até o corte. O que acontece depois, e o que é seu e nunca foi público, só chega a ele se for colocado no texto de entrada. As seções 10 a 12 desenvolvem isso.

Parte 3: Janela de contexto

7. O que é a janela de contexto e o que entra nela

A janela de contexto é o limite de texto, medido em tokens, que o modelo consegue considerar em uma única chamada. A documentação da Claude a define como todo o texto que o modelo pode referenciar ao gerar uma resposta, incluindo a própria resposta, e a compara a uma memória de trabalho, diferente do corpus de treino. É como a mesa de um estudante em dia de prova: cabe uma certa quantidade de papel, e o que não está sobre a mesa não existe para ele naquele momento, por mais que tenha estudado na semana anterior.

O ponto que mais surpreende iniciantes é o que ocupa essa mesa. Pela documentação, tudo o que vai na requisição conta: o prompt de sistema, cada mensagem do histórico (incluindo resultados de ferramentas, imagens e documentos), e as definições das ferramentas. A saída que o modelo gera no turno também conta, inclusive o raciocínio interno (thinking), quando ativado.

Na figura, o grande retângulo é a janela, e dentro dela estão os seis ocupantes. As instruções do sistema (papel, regras, formato) e as definições de ferramentas têm o selo “fixo” porque vão em toda chamada e mudam pouco. É aqui que as ferramentas de um servidor MCP pesam: cada ferramenta exposta ao modelo consome tokens com nome, descrição e parâmetros, mesmo que nunca seja chamada. O histórico (cinza) tem o selo “cresce” porque a cada turno há mais conversa. Os documentos (verde) “variam”: dependem do que foi colado ou do que uma ferramenta devolveu. A pergunta atual (laranja, seta grossa) é o que importa agora. O retângulo tracejado “espaço da resposta” é uma reserva: os tokens que o modelo vai gerar também precisam caber. Todas as setas convergem para o LLM, que só considera o que está dentro da janela, e dele sai o texto gerado.

Uma consequência decisiva: o modelo não tem memória própria entre chamadas. Quando você conversa com um chatbot e ele “lembra” do que falou três mensagens atrás, o que ocorre é que o produto reenviou todo o histórico junto da sua nova pergunta. A documentação da Claude descreve exatamente isso: cada turno consiste em todo o histórico anterior mais a mensagem atual. Alguns produtos têm recursos de memória de longo prazo, mas eles funcionam guardando notas fora do modelo e colocando-as de volta no contexto, não alterando os pesos.

Que tamanho tem a janela

O número cresceu bastante nos últimos anos. Pela documentação da Claude (consultada em 15 de outubro de 2026), vários modelos atuais têm janela de até 1 milhão de tokens, e outros modelos têm 200 mil. Os tamanhos e a lista de modelos mudam a cada lançamento, então use essa informação como uma fotografia de data e consulte a tabela de comparação de modelos do fornecedor. Ao longo da aula, a janela aparece sem número porque o raciocínio vale para qualquer tamanho.

8. Quando enche, e o que custa encher

Como o histórico é reenviado inteiro a cada turno, a conversa só cresce. A figura mostra a progressão.

Os quatro turnos da faixa central, do verde ao rosa, acumulam conteúdo: o turno 1 tem as instruções e uma pergunta, o turno 2 reenvia tudo do turno 1 mais uma nova pergunta, o turno 3 reenvia tudo de novo e acrescenta documentos, e a seta que o liga ao turno 4 é a mais grossa e lenta, porque a quantidade de tokens em trânsito é grande. No turno 4, o limite chega. Se o conteúdo de entrada sozinho já excede a janela, a API devolve um erro: a documentação da Claude registra um erro 400 invalid_request_error com a mensagem “prompt is too long”. É a seta rosa que termina no ✕ e no retângulo “Pedido recusado”. Em outros produtos, o comportamento pode ser descartar silenciosamente as mensagens mais antigas, e a documentação cita que interfaces de chat podem gerir a janela em modo “primeiro a entrar, primeiro a sair”. Perder o começo da conversa sem aviso é uma das fontes mais comuns de respostas estranhas em conversas longas.

O que fazer quando a janela enche são as três saídas verdes, à direita. Resumir o começo (compactar o histórico, o que a documentação chama de compaction), descartar o que ficou velho (por exemplo, limpar resultados antigos de ferramentas) ou, melhor ainda, não carregar tudo desde o início, buscando só o necessário quando for preciso.

A seta laranja pontilhada para “Custo e latência” mostra o outro efeito de encher a janela, que existe mesmo quando nada estoura. Mais tokens de entrada significam uma chamada mais cara, já que a cobrança é por token, e mais lenta, porque o modelo precisa processar tudo antes de começar a responder. O artigo de engenharia da Anthropic sobre contexto acrescenta que, pela arquitetura dos transformers (a família de redes neurais por trás dos LLMs atuais), cada token se relaciona com todos os outros, o que resulta em n² relações para n tokens. Não é preciso saber a conta para guardar a consequência: contexto não é de graça, e cada token a mais tem de justificar o espaço. Recursos como o cache de prompt (prompt caching) reduzem o que você paga por prefixos repetidos, mas, segundo a documentação, os tokens em cache continuam ocupando a janela.

9. Caber não é usar bem

Se a janela tem 1 milhão de tokens, o problema da escassez acabou? Não, e a razão é que o modelo não aproveita todas as posições do contexto igualmente.

O estudo mais citado sobre isso é “Lost in the Middle: How Language Models Use Long Contexts” (Liu e colaboradores, publicado na revista TACL em 2024, volume 12, páginas 157 a 173; a versão preliminar é de 2023). Os autores testaram modelos em duas tarefas, responder perguntas com base em vários documentos e recuperar um valor em uma lista de pares chave-valor, variando a posição da informação relevante no contexto. O resultado foi que o desempenho era melhor quando a informação estava no começo ou no fim, e piorava quando ela estava no meio, mesmo em modelos projetados para contextos longos.

A figura reproduz o experimento em miniatura, com a mesma pergunta e os mesmos três documentos. No grupo de cima, o documento que contém a resposta (verde, borda dupla, selo “meio”) está no centro da lista. Sua seta para o LLM é fina e tem um único pacote lento, enquanto os documentos irrelevantes das pontas mandam setas grossas, e o resultado é “acerta menos” (rosa). No grupo de baixo, o mesmo documento vai para o início, com seta grossa verde, e o resultado é “acerta mais”. É uma simplificação visual de uma tendência medida, não uma lei: a força do efeito varia entre modelos, e modelos mais novos podem se sair melhor. Mas o aviso permanece, e a documentação da Claude diz algo parecido com outras palavras: mais contexto não é automaticamente melhor, e conforme a quantidade de tokens cresce, a precisão e a lembrança se degradam, um fenômeno que ela chama de context rot (podridão de contexto).

A conclusão prática é que o espaço da janela é um orçamento a ser gasto com critério. O artigo de engenharia da Anthropic sobre contexto resume o princípio como encontrar o menor conjunto possível de tokens de alto sinal que maximize a chance do resultado desejado. Um contexto com cinco trechos certos tende a render mais que um com cinquenta trechos em que quatro são úteis. E quando o contexto precisa ser longo, vale colocar o que mais importa no começo ou no fim, e não no meio. Essa lógica aparece em outras aulas do vault: Spec-driven development separa o contexto em camadas por esse motivo, e Agents manda no brief só o que o subagent precisa.

Parte 4: O que o modelo não sabe

10. Três lacunas de conhecimento

Juntando as seções 6 e 7, dá para listar o que o modelo, por construção, não tem.

A primeira lacuna são os dados privados. O contrato do seu cliente, o wiki da sua empresa, os tickets de suporte, o código do repositório fechado e as suas anotações pessoais não estavam no corpus público de treino. O modelo não tem como saber o que está escrito neles, por mais capaz que seja. Perguntar a ele sobre esses documentos sem entregá-los é como perguntar a alguém que nunca esteve na sua empresa qual é a política de férias dela.

A segunda lacuna são os fatos posteriores ao corte de conhecimento. O treino termina em uma data, e o modelo só conhece o mundo até lá. Os modelos costumam ser lançados e usados por muitos meses depois do corte, então há sempre uma janela de tempo sobre a qual ele não sabe nada: versões novas de bibliotecas, notícias, resultados esportivos, preços. Cada fornecedor publica a data de corte de cada modelo na documentação, e vale conferir.

A terceira lacuna são os dados que mudam. Mesmo que o fato estivesse no corpus, ele pode ter mudado: o cargo de alguém, a cotação do dólar, o prazo de uma política, a assinatura de uma função de biblioteca. Os pesos guardam uma fotografia, e a fotografia envelhece.

Uma confusão frequente: os chatbots que respondem sobre notícias de hoje parecem contradizer isso. O que ocorre é que o produto dá ao modelo uma ferramenta de busca na web, executa a busca quando o modelo pede, e coloca o resultado no contexto (ocupando, como vimos, a janela). O modelo continua sem saber nada novo, ele só recebeu texto novo no prompt. Entender essa diferença desfaz boa parte do mistério de como “o chatbot sabe de coisas recentes”.

11. Alucinação

Quando a resposta certa não está nos pesos nem no contexto, o modelo tem duas saídas: dizer que não sabe ou continuar o texto de forma plausível. Como o treino o recompensou por produzir continuações prováveis, e não por checar fatos, a segunda saída é a mais natural. O resultado é uma resposta fluente, confiante e inventada. Isso se chama alucinação (hallucination), e a documentação da Claude descreve o fenômeno como a geração de texto factualmente incorreto ou inconsistente com o contexto dado.

Os exemplos são variados. Um modelo pode citar uma referência bibliográfica com autores, título, revista e ano que soam perfeitamente corretos e que não existem. Pode usar em um código um método que a biblioteca nunca teve, porque o nome é plausível e segue o padrão das outras funções. Pode errar um detalhe da biografia de uma pessoa pouco conhecida, misturando-a com outra, porque a distribuição de probabilidade favorece nomes e datas que combinam. Pode responder com segurança o prazo de reembolso de uma loja que ele nunca viu, como na figura.

O grupo de cima mostra o erro. A pergunta (laranja) chega ao LLM sem nenhum documento. O hexágono tem a descrição “nunca viu a política; completa com o mais provável” e a seta grossa rosa entrega “Prazo de 30 dias”, que o retângulo rosa tremendo descreve como “fluente, confiante e inventado”. Trinta dias é um prazo comum em reembolsos, então é um chute probável, só que sem relação com a loja. A seta pontilhada final leva a “Conferir na fonte”, e o modelo não consultou nenhuma. O grupo de baixo repete a pergunta, só que agora a política da loja (verde, borda dupla) segue para o modelo com a seta grossa “trecho relevante”. A resposta passa a ser “Prazo de 7 dias”, com a frase da política citada ao lado, e a pessoa pode conferir.

O ponto central da seção é que dar o texto certo no contexto reduz o problema, porque transforma uma tarefa de memória (“o que eu lembro sobre essa loja?”) em uma tarefa de leitura (“o que diz este trecho?”). A documentação da Claude recomenda técnicas nesse sentido: permitir explicitamente que o modelo diga “não sei”, pedir que extraia citações literais antes de responder quando os documentos são longos, exigir que cada afirmação venha com a citação que a sustenta (e retirar a que não tiver), e restringir o modelo a usar só os documentos fornecidos. A mesma documentação alerta que essas técnicas reduzem significativamente as alucinações, mas não as eliminam, e que informações críticas devem ser validadas.

Isso tem um efeito colateral valioso para a auditoria: uma resposta ancorada em um trecho pode ser conferida. Uma resposta tirada dos pesos não pode, porque não há de onde ela veio.

Parte 5: Dar conhecimento ao modelo

12. As três saídas

Se o modelo não sabe o que você precisa, há três caminhos para lhe dar esse conhecimento. Cada um mexe em um lugar diferente: dois mexem no que o modelo lê, e um mexe no próprio modelo.

A figura coloca os três caminhos em três grupos, todos terminando no mesmo LLM. A cor das setas finais já resume a diferença: a do primeiro e a do terceiro levam texto para o contexto, e a do segundo leva conhecimento para dentro dos pesos.

Saída 1: colar no prompt

É o jeito mais simples: você coloca o documento inteiro junto da pergunta. Funciona em qualquer modelo, sem preparação, e o conhecimento está sempre atualizado, porque é o texto que você acabou de colar. A resposta pode citar o documento, o que dá auditoria. Os limites são os da janela: o documento precisa caber, ele ocupa tokens (e dinheiro e tempo) em toda chamada, e conforme a seção 9, muito texto dilui a atenção. Para um ou dois documentos pequenos, é a melhor escolha. Para cem mil páginas, não cabe.

Saída 2: ajustar o modelo (fine-tuning)

O fine-tuning continua o treino do modelo com os seus exemplos, alterando os pesos. O resultado é um modelo que se comporta de um jeito específico: um estilo, um formato de saída, um vocabulário de domínio, uma tarefa de classificação. Depois de ajustado, o prompt pode ser mais curto. Em contrapartida, tem custo de preparar dados e de treinar, precisa ser refeito quando o conhecimento muda (os pesos voltam a ser uma fotografia, agora da sua), e não aponta de onde veio cada afirmação. Além disso, a experiência comum é que o fine-tuning é melhor em ensinar um comportamento do que em fixar fatos de forma confiável, de modo que usá-lo só para “ensinar os documentos da empresa” costuma decepcionar. Essa avaliação vem do conhecimento geral da área e não de uma fonte oficial consultada hoje, então confirme com a documentação do seu fornecedor antes de decidir.

Saída 3: buscar e injetar o trecho certo na hora (RAG)

RAG, de retrieval-augmented generation, combina as duas ideias anteriores: mantém os documentos fora do modelo, em um acervo, e a cada pergunta busca só os trechos relevantes e os coloca no prompt, como na saída 1, mas sem precisar colocar tudo. O nome vem de um artigo de 2020, “Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks” (Lewis e colaboradores, NeurIPS 2020), que descreve a combinação de memória paramétrica (o que o modelo guarda nos pesos) com memória não paramétrica (um índice externo que o modelo consulta). Hoje a palavra RAG se aplica a uma família de arquiteturas, mas a ideia central é a mesma. Para atualizar o conhecimento, basta atualizar o acervo, sem retreinar. Como o trecho usado é conhecido, a resposta pode citar a fonte. O custo é construir e manter a busca, e a qualidade da resposta passa a depender de a busca trazer os trechos certos.

13. Comparando as três saídas

Depois de explicar cada uma, uma tabela ajuda a escolher.

Uma ressalva importante sobre a tabela: as três saídas não competem entre si. Um sistema real pode ter um modelo ajustado para seguir o formato da empresa, que recebe, por RAG, os trechos de documentos atualizados, dentro de um prompt com instruções fixas. A escolha de qual usar depende da pergunta que você faz: o conhecimento é pequeno e cabe? Use o prompt. O que você quer mudar é o jeito de responder? Pense em fine-tuning. O conhecimento é grande, muda e precisa de fonte? É o caso do RAG.

Parte 6: Prática

14. Erros comuns de quem começa

O primeiro erro é achar que o modelo “pesquisa”. O modelo prevê texto, e o que parece pesquisa é, quando existe, uma ferramenta de busca ligada ao produto, cujo resultado vai para o contexto. O porquê importa: se você supõe que o modelo consultou uma fonte, vai confiar em uma resposta que saiu só dos pesos. Pergunte sempre se há ferramenta, de onde veio o texto e se a resposta cita um trecho.

O segundo é achar que um contexto maior resolve tudo. Uma janela de 1 milhão de tokens é um limite máximo, e não uma garantia de uso. Os estudos de posição (seção 9) e a própria documentação sobre context rot mostram que a qualidade pode cair com a quantidade, e o custo e a latência sobem com ela. Colocar o acervo inteiro no prompt é caro, lento e, muitas vezes, pior do que colocar três trechos bem escolhidos.

O terceiro é achar que o modelo lembra das conversas anteriores. Entre chamadas, ele não guarda nada nos pesos. O que parece memória é histórico reenviado (seção 7) ou notas guardadas fora e reinjetadas. Esquecer isso leva a dois enganos: esperar que uma sessão nova saiba o que foi dito na antiga, e não perceber que o histórico longo está custando tokens e empurrando as instruções iniciais para longe.

O quarto é contar palavras em vez de tokens. Uma estimativa por palavras subestima o custo em português, em código e em texto com números, e leva a prompts que estouram a janela ou a orçamentos furados. Meça com o tokenizador do modelo que você usa, e recontem ao trocar de modelo, porque o mesmo texto pode render outra contagem (seção 4).

O quinto é tratar uma resposta fluente como uma resposta verificada. A fluência vem do treino em prever texto plausível e não diz nada sobre a verdade do conteúdo. Quando o fato importa, exija a fonte e confira (seção 11).

O sexto é usar fine-tuning como se fosse uma forma de colocar documentos dentro do modelo. Ele ajusta comportamento e estilo com mais confiabilidade do que fixa fatos, e ainda deixa os fatos congelados no dia do treino. Para conhecimento que muda e precisa de fonte, a ferramenta costuma ser a busca (seção 12).

15. Exercícios

1. Conte tokens do mesmo texto em dois idiomas com um tokenizador. Instale a biblioteca e rode:

python3 -m venv .venv && .venv/bin/pip install tiktoken

import tiktoken

pt = "O cliente pode cancelar a assinatura a qualquer momento, desde que avise com trinta dias de antecedência."
en = "The customer may cancel the subscription at any time, provided that thirty days' notice is given."

for nome in ["o200k_base", "cl100k_base"]:
    enc = tiktoken.get_encoding(nome)
    for rotulo, texto in [("pt", pt), ("en", en)]:
        ids = enc.encode(texto)
        print(nome, rotulo, len(texto.split()), "palavras,", len(ids), "tokens")
        print([enc.decode([i]) for i in ids])

Compare as contagens e os cortes. Troque o texto por um trecho de código, por uma tabela e por um parágrafo com números, e veja onde o resultado mais se afasta da regra de “alguns caracteres por token”. O tiktoken serve ao vocabulário da OpenAI, então a contagem é ilustrativa para outros modelos.

2. Use o contador oficial do fornecedor que você usa. Na API da Anthropic, o endpoint de contagem de tokens aceita a mesma estrutura de uma mensagem e devolve input_tokens. Em Python, conforme a documentação consultada em 15 de outubro de 2026:

import anthropic

client = anthropic.Anthropic()
resposta = client.messages.count_tokens(
    model="<id do modelo atual>",
    system="Você é um assistente de suporte.",
    messages=[{"role": "user", "content": "Qual é o prazo de reembolso?"}],
)
print(resposta.input_tokens)

Substitua o id do modelo por um da tabela de modelos do fornecedor. Conte o mesmo prompt com dois modelos diferentes e compare. A documentação avisa que o valor é uma estimativa.

3. Meça o que acontece ao encher o contexto. Escolha um fato inventado e curto (“O código do cofre da sala 12 é 7391”) e um texto longo qualquer para servir de enchimento. Monte quatro prompts com o fato no começo, a 25%, no meio e no fim do enchimento, e peça a cada um que diga o código. Faça uma série com poucos milhares de tokens e outra com dezenas de milhares, e anote em que posição e em que tamanho o modelo erra ou hesita. Compare o que você observou com o resultado da seção 9, lembrando que modelos novos podem se sair melhor do que os do estudo.

4. Provoque uma alucinação e depois corrija-a. Invente uma empresa e uma política (“Loja Zeta, reembolso em até 11 dias úteis”), pergunte a um chatbot o prazo sem dar o documento, e anote o que ele responde e com que segurança. Em seguida, cole o texto da política e pergunte de novo, pedindo que cite a frase que sustenta a resposta. Por fim, pergunte algo que o documento não cobre (“posso devolver na loja física?”) e veja se o modelo admite que não sabe. Repita incluindo a instrução “se o documento não disser, responda que não sabe”.

5. Teste a temperatura. Se o seu ambiente permite ajustá-la, faça a mesma pergunta aberta (“sugira cinco nomes para um café”) cinco vezes com temperatura baixa e cinco com alta. Anote quantos nomes se repetem. Depois faça uma pergunta factual curta e veja se a variação aparece (e se algo errado aparece com mais frequência na temperatura alta).

6. Estime um custo. Pegue um documento seu de umas dez páginas, conte os tokens e multiplique pelo preço de entrada da tabela de preços do fornecedor (consulte o valor do dia, que não está nesta aula). Calcule o custo de mandá-lo inteiro em mil perguntas por dia e compare com mandar só três trechos de 300 tokens.

7. Releia a seção 7 de Agents ou a seção 10 de Spec-driven development e liste o que cada camada de contexto ocupa da janela. Qual ocupante da figura 7 você poderia cortar sem perder resposta?

16. Glossário

Fontes

Consultadas em 15 de outubro de 2026.

• Claude: context windows: definição de janela de contexto, o que conta nela, context rot, tamanhos por modelo, erro “prompt is too long”, compaction.
• Claude: token counting: endpoint de contagem, estimativa, gratuidade, tokenizador novo com cerca de 30% mais tokens.
• Claude: reduce hallucinations: permitir “não sei”, citações literais, verificação por citação, restrição a documentos fornecidos.
• Claude: Messages API: stop_reason end_turn e stop_sequence, e o aviso sobre max_tokens. A página é longa e foi lida só em parte, e por isso não confirmei nela a descrição de temperature e top_p.
• Anthropic: effective context engineering for AI agents: context rot, n² relações entre tokens, menor conjunto de tokens de alto sinal.
• Liu et al., Lost in the Middle: How Language Models Use Long Contexts (TACL 2024): posição da informação e desempenho.
• Lewis et al., Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks (NeurIPS 2020): origem do termo RAG, memória paramétrica e não paramétrica.
• tiktoken (OpenAI): BPE, vocabulários o200k_base e cl100k_base, compressão média de cerca de 4 bytes por token. As divisões de tokens e as contagens das figuras 3 e 4 foram medidas por mim com a versão 0.14.0, em 15 de outubro de 2026.

As fontes abaixo sustentam as seções 17 a 19, consultadas em 18 de outubro de 2026:

• Claude: Messages API: objeto Message, valores de stop_reason, campos de usage, max_tokens, stop_sequences, e os avisos de descontinuação de temperature, top_p e top_k para modelos lançados depois do Claude Opus 4.6.
• Claude: pricing: preços por milhão de tokens do Claude Sonnet 5.5 e do Claude Haiku 5.5, multiplicadores de cache, desconto de 50% do Batch API e faixa de preço do Haiku 5.5 acima de 100 mil tokens.
• Claude: token counting: endpoint de contagem, gratuidade, limite de 5.000 requisições por minuto no nível inicial, estimativa e tokenizador com cerca de 30% mais tokens.
• Anthropic Python SDK (versão 1.15.0, instalada num ambiente isolado em 18 de outubro de 2026): nomes dos campos de Message e Usage e os valores de StopReason, conferidos no código do pacote.

Os preços citados na seção 19 foram consultados em 18 de outubro de 2026. A frase sobre preços no fim desta lista se refere às seções anteriores à 17.

Sem fonte consultada (escrito do conhecimento geral do autor): a descrição passo a passo do BPE e seu uso em vocabulários, a fórmula da temperatura e o top-p, o fato de o pré-treino ser seguido de etapas que ensinam a seguir instruções, o comportamento de produtos de chat com ferramenta de busca ou memória, a avaliação de que o fine-tuning ensina comportamento melhor do que fixa fatos, e a ideia de que a temperatura baixa não garante respostas idênticas. Não verifiquei os valores aceitos de temperatura em cada modelo atual, nem datas de corte de conhecimento, nem preços. Os percentuais das figuras 1 e 5 e o prazo de reembolso das figuras 6 e 10 são inventados para ilustrar.

Parte 7: Na API

As seções anteriores explicaram os conceitos sem falar de código. Esta parte mostra onde eles aparecem quando o seu programa chama a API da Anthropic. Os nomes de campo, os valores de stop_reason e os preços foram conferidos na documentação oficial consultada em 18 de outubro de 2026, e os nomes de campo também foram conferidos no SDK oficial de Python (versão 1.15.0). Não rodei nenhuma chamada real à API, porque não havia chave configurada. Os exemplos de código rodam sem rede, usando os tipos do SDK e a tabela de preços.

17. Os conceitos no campo da resposta

Quando o seu programa chama a API, a conversa da seção 7 vira uma requisição HTTP. O endpoint é POST /v1/messages, e o corpo traz a lista de mensagens (messages), o modelo, o limite de saída (max_tokens) e, se você quiser, o prompt de sistema (system). O max_tokens é o teto de saída da seção 5, e a referência o marca como campo obrigatório. Cada mensagem da lista é um pedaço do histórico que o produto reenvia a cada turno, e o system é o bloco que vai em toda chamada.

A resposta chega como um objeto Message. Dele, cinco campos importam para quem escreve código. content é a lista de blocos gerados, e é ali que está o texto que a seção 5 descreveu como sorteio de tokens. stop_reason diz por que a geração parou. stop_sequence traz o texto que bateu numa sequência de parada, e fica null quando nenhuma foi usada. usage traz as contagens de tokens, e é o campo que liga a resposta à conta e à janela. Os demais (id, type, role e model) identificam a resposta e o modelo que a produziu, e há campos de casos especiais, como container, que aparece quando uma ferramenta de execução de código roda, e stop_details, que traz detalhes de uma parada.

O usage merece leitura atenta, porque a conta de entrada não é tão direta quanto parece. input_tokens conta a entrada que não veio do cache. Quando você usa cache de prompt, aparecem também cache_creation_input_tokens, que é o que foi gravado no cache, e cache_read_input_tokens, que é o que foi lido dele. O total de entrada é a soma dos três, e é esse total que ocupa a janela da seção 7. Quem olha só para input_tokens pode concluir que a chamada foi barata quando parte da entrada veio por outro campo. Já output_tokens é a saída, e a documentação o descreve como o total autoritativo para cobrança. Dentro dele existe output_tokens_details, que separa quantos tokens foram gastos em raciocínio interno (thinking_tokens). Esses tokens contam na cobrança e no max_tokens, mesmo quando o texto final é curto.

A figura mostra a resposta como um documento que se abre em quatro partes. O usage (verde) é a parte que vira conta: as três entradas se somam no retângulo laranja “Total de entrada”, e a saída segue direto para o custo, que depende de preços diferentes para entrada e saída. Os campos content e stop_reason (em tons de bronze e azul) não entram na conta, mas são os que você lê para saber o que veio e por que parou.

Agora vamos ao stop_reason, que responde à pergunta deixada em aberto pelo laço da figura 1. Quando o modelo para, a geração acabou porque terminou, porque bateu num limite, ou porque pediu alguma coisa ao seu código? A documentação lista sete valores, e o SDK de Python confirma os mesmos sete. O valor end_turn é o caso normal: o modelo chegou a um ponto natural de parada. O valor max_tokens significa que o limite de saída foi atingido, e a resposta pode estar cortada no meio de uma frase, então trate-a como incompleta. O valor stop_sequence aparece quando o texto gerado bateu numa das sequências que você definiu. O valor tool_use significa que o modelo quer executar uma ferramenta, e o bloco tool_use dentro de content traz o nome e os argumentos. O seu código executa a ferramenta e devolve o resultado numa nova requisição, e esse ciclo é o mesmo laço de agentes da nota Agents. Os valores pause_turn, refusal e model_context_window_exceeded são menos frequentes. O primeiro indica um turno longo pausado, que pode ser continuado; o segundo indica que classificadores interferiram por possível violação de política; o terceiro indica que a geração chegou ao limite da janela.

A figura trata a resposta como um roteamento. Tudo sai do modelo (hexágono) e chega ao losango, que lê o campo stop_reason. Cada saída leva a uma consequência diferente. O caminho verde, end_turn, é o único que segue sem aviso. A seta bloqueada com o ✕ rosa marca max_tokens, porque ali a geração foi barrada antes de terminar, e o retângulo rosa treme porque é o caso que mais convém tratar com cuidado. O ramo azul de tool_use é o que o agente percorre a cada passo. Os motivos raros ficam juntos, de propósito, porque o código costuma tratá-los com uma regra comum.

Um trecho de código mostra a leitura desses campos. Ele usa um corpo de resposta com os nomes da documentação e valores inventados, e roda sem chamar a API:

from anthropic.types import Message

# Exemplo de corpo de resposta com os nomes de campo da documentação (valores inventados).
corpo = {
    "id": "msg_exemplo",
    "type": "message",
    "role": "assistant",
    "model": "claude-opus-5-5",
    "content": [{"type": "text", "text": "O prazo é de 7 dias."}],
    "stop_reason": "max_tokens",
    "stop_sequence": None,
    "usage": {
        "input_tokens": 500,
        "output_tokens": 1024,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 2500,
    },
}

msg = Message.model_validate(corpo)
print("stop_reason:", msg.stop_reason)
print("stop_sequence:", msg.stop_sequence)
print("saida:", msg.content[0].text)
u = msg.usage
entrada_total = u.input_tokens + (u.cache_creation_input_tokens or 0) + (u.cache_read_input_tokens or 0)
print("entrada total:", entrada_total, "| saida:", u.output_tokens)
if msg.stop_reason == "max_tokens":
    print("aviso: resposta cortada pelo limite de max_tokens")

A saída real, rodada com o SDK instalado num ambiente isolado, foi:

stop_reason: max_tokens
stop_sequence: None
saida: O prazo é de 7 dias.
entrada total: 3000 | saida: 1024
aviso: resposta cortada pelo limite de max_tokens

O código mostra o hábito que a figura 13 sugere: ler o motivo antes de ler o texto. Um programa que só lê content aceita sem perceber uma resposta cortada. Um programa que lê stop_reason primeiro sabe que aquela resposta não pode ir ao usuário como se estivesse completa. Em modo de streaming, o campo stop_reason vem null no primeiro evento e só é preenchido depois, o que também precisa ser levado em conta.

18. Geração na API: temperatura, limite e parada

A seção 5 explicou temperatura, top-p e parada como ideias. Na API, cada uma vira um campo do corpo da requisição. A documentação atual mostra, porém, que nem todos esses campos continuam disponíveis para todos os modelos, e vale separar o que você controla do que o modelo decide.

temperature, top_p e top_k

O campo temperature aceita valores de 0.0 a 1.0 e tem padrão 1.0. A documentação recomenda valores mais perto de 0 para tarefas analíticas e de múltipla escolha, e mais perto de 1 para tarefas criativas. Ela também avisa que, mesmo com 0.0, o resultado não é totalmente determinístico, o que confirma a ressalva da seção 5.

O problema é que a própria referência marca temperature como descontinuado para modelos lançados depois do Claude Opus 4.6. Esses modelos aceitam só o valor 1.0, e qualquer outro é recusado com erro 400. O mesmo vale para top_p, que aceita apenas valores a partir de 0.99 por compatibilidade, e para top_k, que é recusado nesses modelos. Na prática, quem escreve código para um modelo novo não pode contar com a temperatura como botão de consistência. A consistência precisa vir do prompt, do formato de saída pedido e da validação do que volta. Antes de fixar qualquer valor, confira o ID do modelo que você usa, porque a regra vale por geração de modelo e pode mudar com um lançamento.

max_tokens

O max_tokens é o teto de tokens que o modelo pode gerar antes de parar. A documentação faz duas ressalvas que mudam a forma de escolher esse número. A primeira é que o modelo pode parar antes de chegar ao teto, então o campo não é uma meta de tamanho. A segunda é que, ao atingi-lo, o stop_reason vira max_tokens e a resposta pode ficar cortada. Como o teto também cobre o raciocínio interno quando o thinking está ativo, um valor pequeno pode consumir toda a saída antes de o texto final começar. Há ainda um uso menos óbvio: pela documentação, max_tokens igual a 0 preenche o cache de prompt sem gerar resposta. Para custo, o max_tokens define o pior caso da saída, como a seção 19 mostra.

stop_sequences

stop_sequences é uma lista de textos. Quando o modelo gera um deles, a geração para, stop_reason vira stop_sequence e o campo stop_sequence traz o texto que casou. Ela serve quando você quer um ponto de corte que não depende de o modelo decidir sozinho onde termina, como um marcador combinado no formato de saída. A página da documentação que consultei não diz se o texto que casou aparece também em content. Não afirmo isso aqui, e vale testar antes de depender desse detalhe.

A tabela resume o que cada campo controla e onde você vê o efeito:

19. Calcular tokens e custo

Estimar o custo de uma chamada tem duas partes: quantos tokens entram e saem, e quanto cada token custa. A primeira parte pode ser medida antes do envio. O endpoint de contagem de tokens aceita a mesma estrutura de uma mensagem, inclusive sistema, ferramentas e imagens, e devolve input_tokens. Segundo a documentação, a contagem é gratuita e tem limite próprio de requisições por minuto, separado do limite de criação de mensagens, com 5.000 por minuto no nível inicial. O valor é uma estimativa, e pode incluir tokens que a Anthropic adiciona automaticamente para otimizações do sistema. Esses tokens não são cobrados. E a lição da seção 4 continua valendo: modelos a partir do Claude 4.7 usam um tokenizador que gera cerca de 30% mais tokens para o mesmo texto, então a documentação manda contar de novo com o modelo que você vai usar.

A segunda parte é a fórmula. Com preços em dólares por milhão de tokens (MTok), o custo de uma chamada é:

custo = (input_tokens × preço de entrada + output_tokens × preço de saída + tokens gravados no cache × preço de escrita + tokens lidos do cache × preço de leitura) ÷ 1.000.000

Os termos de cache só entram quando a chamada os usa. Os preços abaixo foram consultados na página oficial de preços em 18 de outubro de 2026, para o Claude Sonnet 5.5: 2 dólares por MTok de entrada e 10 dólares por MTok de saída. A escrita no cache de 5 minutos custa 2,50 dólares por MTok, e a leitura custa 0,10. Esses valores mudam com o tempo, então confira antes de usar. A mesma página informa que o Batch API tem 50% de desconto sobre entrada e saída, e que o Claude Haiku 5.5 cobra mais por MTok quando o prompt passa de 100 mil tokens. Não confirmei nesta consulta se o preço de lote se aplica igualmente a todos os modelos, então leia a tabela do modelo que você escolheu.

O script abaixo calcula dois cenários com esses preços. Ele não chama a API, porque usa só a tabela:

# Preços oficiais (USD por milhão de tokens), página de preços consultada em 18/10/2026.
# Modelo: Claude Sonnet 5.5
PRECO_ENTRADA = 2.00      # base input
PRECO_SAIDA = 10.00       # output
PRECO_CACHE_ESCRITA_5M = 2.50
PRECO_CACHE_LEITURA = 0.10

def custo_usd(entrada, saida, escrita_cache=0, leitura_cache=0):
    return (entrada * PRECO_ENTRADA
            + saida * PRECO_SAIDA
            + escrita_cache * PRECO_CACHE_ESCRITA_5M
            + leitura_cache * PRECO_CACHE_LEITURA) / 1_000_000

# Cenário A: 3.000 tokens de entrada, sem cache, 500 de saída
a = custo_usd(entrada=3000, saida=500)
print(f"A sem cache: {a:.5f} USD por chamada")

# Cenário B: 2.500 tokens de prefixo em cache (lidos), 500 novos, 500 de saída
b = custo_usd(entrada=500, saida=500, leitura_cache=2500)
print(f"B com cache lido: {b:.5f} USD por chamada")

# Mensal: 1.000 perguntas por dia, 30 dias
print(f"A mensal: {a * 1000 * 30:.2f} USD")
print(f"B mensal: {b * 1000 * 30:.2f} USD")

# Tokens de entrada totais de uma resposta, segundo o campo usage
usage = {"input_tokens": 500, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 2500, "output_tokens": 500}
total_entrada = usage["input_tokens"] + usage["cache_creation_input_tokens"] + usage["cache_read_input_tokens"]
print(f"total de entrada pelo usage: {total_entrada}")

A saída real foi:

A sem cache: 0.01100 USD por chamada
B com cache lido: 0.00625 USD por chamada
A mensal: 330.00 USD
B mensal: 187.50 USD
total de entrada pelo usage: 3000

No cenário A, 3.000 tokens de entrada e 500 de saída custam 0,011 dólar por chamada. No cenário B, 2.500 desses tokens vêm de um prefixo já gravado no cache, e só 500 são novos. A chamada cai para 0,00625 dólar, e a diferença mensal, para mil perguntas por dia durante 30 dias, vai de 330 para 187,50 dólares. O último resultado do script confirma a regra do usage: as duas formas de escrever a entrada somam os mesmos 3.000 tokens, e é essa soma que pesa na janela.

Cuidado com o cenário B. Ele supõe que toda chamada encontra o cache, e o cache tem tempo de vida. Uma chamada que chega depois de ele expirar paga a escrita de novo, que custa mais que a entrada comum. O cálculo mostra a ordem de grandeza do ganho, e não uma garantia. Também não verifiquei nesta consulta o tamanho mínimo de prefixo para o cache funcionar, então confira a documentação de cache de prompt antes de desenhar um sistema em torno dele.

A saída é o caso mais difícil de prever, porque você não sabe antes quantos tokens o modelo vai gerar. O que você conhece é o teto, o max_tokens. Multiplicar esse teto pelo preço de saída dá o pior caso da parte de saída de uma chamada, e é esse número que protege o orçamento. O stop_reason da seção 17 confirma depois se a resposta bateu no teto.

Relacionados

• Agents
• Spec-driven development
• MCP
• Prompt e contexto
• Embeddings