O que significa model_context_window_exceeded
A string model_context_window_exceeded é como alguns clientes, SDKs e APIs rotulam uma falha específica: o texto que você enviou, mais o espaço necessário para uma resposta, é maior do que o modelo pode suportar em uma única requisição. A redação da mensagem varia entre ferramentas, então leia o corpo completo do erro que seu cliente mostra em vez de confiar apenas no nome. A causa é sempre a mesma.
Nesta API, a janela de contexto é de 100.000 tokens, e esse número cobre o prompt e a conclusão juntos. Se o seu prompt usar 95.000 tokens, restam no máximo cerca de 5.000 para a resposta. Se você também definir max_tokens como 8.000, a requisição pede mais do que a janela permite. O campo max_tokens é opcional e, quando omitido, a resposta simplesmente usa o espaço restante.
Uma requisição que falha dessa forma retorna um erro em vez de uma conclusão. Requisições falhas não são cobradas, então atingir o limite não custa nada além da ida e volta. A correção está do seu lado: envie menos ou peça menos.
Qual o tamanho de 100.000 tokens?
Um token é um trecho de texto, muitas vezes uma palavra curta ou parte de uma palavra mais longa. Para prosa em inglês comum, uma regra aproximada é um token a cada quatro caracteres, ou cerca de três quartos de uma palavra. Por essa regra, 100.000 tokens equivalem a cerca de 75.000 palavras, o que é um livro grosso. Código, JSON, tabelas e texto em outros idiomas são divididos em mais tokens por caractere, então a mesma contagem de caracteres pode resultar em muito mais tokens. Trate qualquer regra prática como um número de planejamento, não como uma garantia.
A contagem exata vem do próprio tokenizador do modelo. A API relata o uso real na resposta: o objeto usage lista tokens de prompt e de conclusão, e uma resposta em streaming envia o uso no final. Esse é o dado mais confiável que você tem, então registre-o.
| Conteúdo | Tamanho aproximado |
|---|---|
| Uma mensagem de chat de duas frases | de 40 a 60 tokens |
| Uma página de texto em inglês, 500 palavras | cerca de 670 tokens |
| Um documento de 10.000 palavras | cerca de 13.000 tokens |
| Um despejo JSON de 3 MB | muitas vezes mais de 100.000 tokens, grande demais para enviar como dados brutos |
O corpo da requisição também tem um limite de tamanho de 8 MB, que é um limite separado do de tokens. Entradas grandes podem falhar em qualquer um dos dois, e o limite de tokens é quase sempre o primeiro que você atinge.
Por que apps de chat atingem o limite
A API não mantém memória entre chamadas. Para continuar uma conversa, seu código envia toda a lista de mensagens a cada vez. Cada turno adiciona a mensagem do usuário e a resposta, então o prompt cresce a cada troca. Um bot que funciona bem por uma hora e depois começa a falhar é o sinal clássico.
A mesma coisa acontece em agentes. Cada resultado de ferramenta é anexado ao histórico, e uma função que retorna um registro grande pode adicionar milhares de tokens em uma única etapa. Configurações de recuperação adicionam uma terceira fonte: se você colar vinte trechos de documento em cada prompt, o custo base por requisição já é grande antes de qualquer histórico existir.
Antes de corrigir qualquer coisa, descubra qual dos três está crescendo. Imprima a contagem de tokens do prompt de usage após cada chamada. Se ela subir aproximadamente a mesma quantidade a cada turno, é o histórico. Se ela pular após etapas específicas, é saída de ferramenta ou texto recuperado.
Reduza o histórico antes de enviá-lo
A correção mais simples e confiável é uma função que remove os turnos mais antigos até que a estimativa caiba em um orçamento. Mantenha a mensagem do sistema sempre, e mantenha a última mensagem do usuário sempre. O orçamento deve deixar espaço para a resposta, então use algo como 80.000 tokens para o prompt e deixe o restante como espaço de geração.
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredmodelhub.com/v1",
api_key="YOUR_API_KEY",
)
def estimate_tokens(text: str) -> int:
return len(text) // 4 + 4 # rough: 4 characters per token plus overhead
def trim(messages, budget=80_000):
system = [m for m in messages if m["role"] == "system"]
rest = [m for m in messages if m["role"] not in ("system",)]
total = sum(estimate_tokens(m["content"]) for m in system + rest)
while total > budget and len(rest) > 1:
dropped = rest.pop(0) # oldest turn goes first
total -= estimate_tokens(dropped["content"])
return system + rest
history = [{"role": "system", "content": "You are a helpful assistant."}]
def ask(user_text):
history.append({"role": "user", "content": user_text})
resp = client.chat.completions.create(
model="uncensored",
messages=trim(history),
max_tokens=2000,
)
reply = resp.choices[0].message.content
history.append({"role": "assistant", "content": reply})
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)
return reply
Mantenha os turnos do usuário e do assistente em pares quando possível; remover apenas metade de um par pode confundir o modelo. Mensagens de ferramenta são semelhantes: uma mensagem role: "tool" deve permanecer com o turno do assistente que a solicitou, então remova-as juntas. Como a estimativa é aproximada, uma margem de segurança de 20% entre seu orçamento e a janela real é confortável.
Opções melhores do que remover turnos antigos
Resuma e continue
Quando o histórico ultrapassa um limite, envie a metade mais antiga ao modelo com uma instrução para resumi-la em algumas centenas de palavras, depois substitua esses turnos pelo resumo como uma mensagem de sistema ou de usuário. Você perde detalhes, mas mantém o fio da conversa. Execute esse passo fora do caminho de resposta em tempo real para que o usuário não fique esperando.
Fixe os fatos que devem sobreviver
Mantenha um pequeno bloco de notas duráveis, como nomes, decisões e configurações, e reinsira-o no topo de cada requisição. Isso funciona melhor do que esperar que um turno antigo ainda esteja visível.
Reduza o que você envia
Corte resultados de ferramentas aos campos que importam. Recupere menos trechos e corte cada um nos parágrafos relevantes. Para um documento muito longo, divida-o em partes, processe cada parte e combine os resultados em uma chamada final curta.
Defina max_tokens deliberadamente
Se as respostas são normalmente curtas, limite max_tokens a um valor que se encaixe no seu produto. Um limite protege o orçamento, mas um limite muito baixo corta respostas no meio da frase, então analise primeiro os comprimentos reais das suas respostas nos logs.
Reduzir também economiza dinheiro
Tokens de entrada custam $0,15 por 1 milhão, tokens de saída $0,50 por 1 milhão, cobrados do crédito pré-pago. Como o chat reenvia o histórico, o custo por conversa cresce mais rápido do que seu comprimento. Considere um chat onde cada troca adiciona 500 tokens ao histórico e a conversa tem 100 turnos.
- Sem redução, o turno n envia 500 x n tokens. A soma sobre 100 turnos é 500 x 5.050 = 2.525.000 tokens de entrada, que custam 2,525 x $0,15 = $0,379.
- Com um limite de 20.000 tokens, os primeiros 40 turnos são iguais (500 x 820 = 410.000 tokens). Os 60 turnos restantes enviam 20.000 cada, o que é 1.200.000. O total é 1.610.000 tokens, ou 1,61 x $0,15 = $0,242.
O limite economiza cerca de um terço aqui, e a diferença aumenta conforme as conversas ficam mais longas. No extremo, um prompt de 100.000 tokens custa 0,1 x $0,15 = $0,015 por requisição. Isso é barato por si só, mas se acumula em um bot que atende muitos usuários. Detalhes de preços e bônus de recarga estão na página de preços, e o crédito nunca expira.
Tratando o erro no código
Mesmo com redução, planeje-se para uma falha. Capture o erro da API, verifique se a mensagem aponta para o comprimento do contexto, reduza a requisição e tente novamente uma vez. Não tente novamente a mesma requisição, pois ela falhará da mesma forma.
from openai import BadRequestError
def safe_ask(messages, budget=80_000):
try:
return client.chat.completions.create(
model="uncensored", messages=trim(messages, budget)
)
except BadRequestError as err:
if "context" in str(err).lower() and budget > 10_000:
return safe_ask(messages, budget // 2)
raise
Verifique o código de status e a mensagem reais que seu cliente recebe para uma requisição grande demais e ajuste o teste; a correspondência de string acima é apenas um ponto de partida. Limites de taxa são separados: HTTP 429 com rate_limited ou concurrency significa muitas requisições, não muitos tokens, e 429 com Retry-After: 5 significa sobrecarga temporária. A documentação lista os campos da requisição, o explicador sobre modelos sem censura cobre o que é o modelo, e você pode obter uma chave para testar tudo isso com números de uso reais.
