PT ▾
Obter chave de API

InícioGuia

Atualizado

Janela de contexto de agente de IA: como usar 100k tokens

A janela de contexto de um agente de IA é o espaço total de tokens compartilhado pelo prompt, pelos resultados das ferramentas e pela resposta do modelo. Nesta API, esse espaço é de 100.000 tokens, e agentes de execução longa tendem a preenchê-lo mais rápido do que o esperado.

Recipiente de vidro enchendo com blocos brilhantes enquanto uma seta circular gira ao redor, ilustrando a janela de contexto de um agente

Pontos principais

  1. A janela de 100.000 tokens abrange prompt mais resposta, então cada resultado de ferramenta que você mantém reduz espaço para a próxima resposta.
  2. Em um loop de agente, todo o histórico é reenviado a cada etapa, então a entrada total cresce com o quadrado do número de etapas, não linearmente.
  3. Remova primeiro as saídas antigas de ferramentas, mantenha o prompt do sistema e as últimas interações, e meça com o campo usage.
  4. Um loop de 20 etapas com 1.500 tokens novos por etapa custa cerca de $0,055 no total.

Sem necessidade de cartão. Após o cadastro, reivindique $0,50 de crédito de teste grátis com um clique (uma vez por pessoa).

Obter chave de API

A resposta curta: um orçamento compartilhado de 100.000 tokens

Quando as pessoas pesquisam pela janela de contexto de agentes de IA, geralmente querem saber quanto um agente consegue lembrar antes de falhar. Aqui o número é 100.000 tokens, e conta tudo: o prompt do sistema, as definições de ferramentas, cada mensagem anterior, cada resultado de ferramenta e a resposta que o modelo está prestes a escrever. A resposta pode usar o que sobrar, e max_tokens é opcional.

Isso transforma a janela em um orçamento, não em um espaço de armazenamento. Um chatbot raramente chega perto do limite. Um agente que chama ferramentas em loop pode atingi-lo em uma tarde, porque cada etapa adiciona uma mensagem do modelo e um resultado de ferramenta ao histórico, e todo o histórico é enviado novamente na próxima chamada. O modelo não tem memória entre as requisições. O que parece ser memória é você reenviar o histórico.

O que realmente preenche a janela em um agente

A maior parte do espaço não é o texto do usuário. Acompanhe essas cinco fontes e você poderá prever onde uma execução ficará sem recursos.

  • Prompt do sistema. Regras, persona e formato de saída. Frequentemente de 500 a 2.000 tokens e enviado a cada chamada.
  • Definições de ferramentas. Cada nome de função, descrição e esquema JSON contam. Dez ferramentas com descrições longas podem custar vários milhares de tokens antes da primeira mensagem do usuário.
  • Resultados de ferramentas. O culpado habitual. Um resultado de pesquisa, uma extração de arquivo ou um conjunto de linhas de banco de dados pode ter milhares de tokens, e permanece no histórico a menos que você o remova.
  • Mensagens do assistente. Raciocínio escrito em texto e os argumentos tool_calls produzidos pelo modelo.
  • A resposta sendo gerada. Ela também precisa de espaço. Se o prompt tiver 99.000 tokens, a resposta terá cerca de 1.000 restantes.

A API relata números exatos no bloco usage de cada resposta, então você não precisa adivinhar. Registre prompt_tokens após cada etapa e você verá a curva.

Um exemplo prático: 20 etapas de um loop de ferramentas

Considere um agente com um início de 3.000 tokens (prompt do sistema mais definições de ferramentas). Cada etapa adiciona cerca de 1.500 tokens ao histórico: a chamada de ferramenta do modelo e o resultado da ferramenta. Ele também gera cerca de 300 tokens de saída por etapa. O agente executa 20 etapas.

A entrada na etapa k é 3.000 + 1.500 × (k − 1). Somado ao longo de 20 etapas:

  • 3.000 × 20 = 60.000 tokens para o início fixo, reenviado a cada vez.
  • 1.500 × (0 + 1 + ... + 19) = 1.500 × 190 = 285.000 tokens de histórico acumulado.
  • Entrada total: 345.000 tokens. Saída total: 20 × 300 = 6.000 tokens.
ItemTokensPreço por 1MCusto
Entrada345,000$0.15$0.05175
Saída6,000$0.50$0.003
Totalcerca de $0,055

Duas coisas se destacam. Primeiro, o contexto na etapa 20 é 3.000 + 1.500 × 19 = 31.500 tokens, bem dentro da janela, mas você pagou por 345.000 tokens de entrada, porque o histórico foi reenviado a cada vez. Segundo, uma única chamada com uma janela completamente cheia (100.000 tokens de entrada) custa 100.000 × $0,15 / 1M = $0,015 para o lado da entrada. Contextos longos são acessíveis por chamada; o custo vem de repeti-los em muitas etapas. Veja a página de preços para as tarifas e bônus de recarga.

Quantas etapas cabem antes que a janela encha

Você pode estimar isso antes de escrever qualquer código. Mantenha uma reserva para a resposta, digamos 20.000 tokens, o que deixa um orçamento de 80.000 tokens para o prompt. Com um início de 3.000 tokens e 1.500 tokens adicionados por etapa, o histórico atinge esse orçamento após (80.000 − 3.000) / 1.500, ou cerca de 51 etapas.

Agora calcule o custo de uma execução desse comprimento. Em 51 etapas, a entrada é 3.000 × 51 + 1.500 × (0 + 1 + ... + 50) = 153.000 + 1.500 × 1.275 = 153.000 + 1.912.500 = 2.065.500 tokens. Saída a 300 tokens por etapa é 15.300 tokens. Custo: 2.065.500 × $0,15 / 1M = $0,30983, mais 15.300 × $0,50 / 1M = $0,00765, então cerca de $0,32.

Compare isso com a execução de 20 etapas por cerca de $0,055. A execução é 2,55 vezes mais longa, mas custa cerca de 5,8 vezes mais, porque cada etapa carrega um histórico mais longo. Esta é a razão prática para reduzir: ela limita o custo por etapa, além de proteger a janela.

Mantendo um agente dentro da janela

Remova primeiro a saída antiga de ferramentas

Resultados brutos de ferramentas são a parte maior e menos útil de um histórico. Uma vez que o modelo agiu com base em uma listagem de arquivos, raramente precisa da listagem novamente. Substitua os resultados antigos por um stub de uma linha como "resultado removido, 4.200 tokens", ou exclua o par inteiro.

Resuma o meio, mantenha ambas as extremidades

Mantenha o prompt do sistema e as últimas interações literalmente. Para tudo entre, peça ao modelo um resumo curto das decisões tomadas e fatos encontrados, depois armazene esse resumo como uma única mensagem. Execute a chamada de resumo antes de atingir o limite, não depois.

Mova os fatos para fora da transcrição

Se o agente aprender algo que deve manter por horas, grave-o em um arquivo ou pequeno banco de dados por meio de uma ferramenta e leia-o de volta quando necessário. Isso é mais barato do que carregá-lo em cada solicitação e sobrevive a reinicializações.

Mantenha os esquemas de ferramentas curtos

Reduza as descrições ao necessário para o modelo escolher a ferramenta. Passe apenas as ferramentas relevantes para a fase atual da tarefa.

Código: um loop de ferramentas com orçamento de tokens

Este loop remove as mensagens mais antigas quando o tamanho aproximado ultrapassa um orçamento de 80.000 tokens, deixando espaço para a resposta. A estimativa divide caracteres por quatro, uma aproximação comum para texto em inglês; a contagem real volta em usage. O corte remove mensagens tool órfãs para que um resultado nunca apareça sem sua chamada.

import json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.aivideogenapi.com/v1", api_key=os.environ["API_KEY"])
BUDGET = 80_000

tools = [{"type": "function", "function": {
    "name": "get_scene_length",
    "description": "Return the length of a scene in seconds",
    "parameters": {"type": "object",
                   "properties": {"scene": {"type": "integer"}},
                   "required": ["scene"]}}}]

def rough_tokens(messages):
    return sum(len(json.dumps(m)) for m in messages) // 4

def trim(messages):
    system, rest = messages[0], messages[1:]
    while rough_tokens([system] + rest) > BUDGET and len(rest) > 4:
        rest.pop(0)
        while rest and rest[0]["role"] == "tool":
            rest.pop(0)
    return [system] + rest

def run_tool(name, args):
    return json.dumps({"seconds": 4 * args["scene"]})  # stub

messages = [
    {"role": "system", "content": "You plan video scenes. Use tools for lengths."},
    {"role": "user", "content": "Total the length of scenes 1 to 5."},
]

for step in range(20):
    resp = client.chat.completions.create(
        model="uncensored", messages=trim(messages), tools=tools)
    msg = resp.choices[0].message
    messages.append(msg.model_dump(exclude_none=True))
    print(step, resp.usage.prompt_tokens)
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        result = run_tool(call.function.name, json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id, "content": result})

A chamada de ferramentas segue o formato OpenAI: tools, tool_choice e resultados retornados como role: "tool". A documentação lista os parâmetros repassados.

Limites importantes além da janela

A janela é uma restrição. Agentes também atingem limites de requisições. Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto; uma chave de teste permite 2 e 60. Um loop apertado com sub-agentes paralelos pode exceder o limite de concorrência rapidamente. A API responde com HTTP 429 e o código de erro concurrency ou rate_limited, e em sobrecarga temporária com o cabeçalho Retry-After: 5. Aguarde esse tempo e tente novamente.

Se você usar streaming, lembre-se de que uma solicitação streaming mantém seu slot de concorrência até o stream terminar. Um cliente travado que nunca fecha o stream mantém um slot ocupado.

O corpo máximo é 8 MB, o que é muito mais do que 100.000 tokens de texto, então a janela é o limite que você atingirá primeiro. Para um exemplo de um pipeline apenas de texto construído com esta API, consulte o guia de roteiro de vídeo. Quando estiver pronto para executá-lo, crie uma chave de API; novos usuários podem reivindicar $0,50 de crédito de teste com um clique, válido por 7 dias e sem necessidade de pagamento.

Perguntas e respostas

Qual o tamanho da janela de contexto?

100.000 tokens, contando o prompt e a conclusão juntos. A resposta pode usar tudo o que o prompt deixar livre.

O modelo lembra das requisições anteriores?

Não. Cada requisição é independente, então seu código deve reenviar as mensagens que deseja que o modelo veja.

O que acontece quando excedo o limite?

A requisição não cabe, então reduza ou resuma o histórico antes de enviar. Requisições falhas não são cobradas.

Como conto os tokens?

Leia prompt_tokens e completion_tokens no bloco de uso de cada resposta, ou use uma estimativa aproximada de quatro caracteres por token para inglês antes de enviar.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.

Obter chave de API