Paritok reduz a conta de tokens do seu agente?

O que o Paritok faz com um pedido

O Paritok é um gateway de tokens: um proxy que fica entre o seu agente de programação e a API do modelo e comprime cada pedido antes de o encaminhar. O seu agente comunica com http://127.0.0.1:8080 em vez de comunicar diretamente com o fornecedor. O proxy reescreve os esquemas das ferramentas, as leituras de ficheiros, a saída das ferramentas e os turnos anteriores, envia o payload mais pequeno para o upstream e devolve a resposta sem alterações.

O fornecedor cobra pelo que recebe, portanto um payload mais pequeno resulta numa fatura mais baixa. Essa é a ideia. A afirmação é diferente de dizer que "o seu contexto dura mais tempo", e é por isso que esta ferramenta é interessante, em vez de ser apenas uma forma de manter tudo organizado.

O projeto é recente. As primeiras tags públicas são de julho de 2026 e a tag atual é v1.3.0, de 5 de agosto de 2026. Os pesos e o código do gateway estão sob a licença Apache 2.0. O modelo de compressão é um adaptador LoRA (low-rank adaptation) sobre o Qwen3-4B-Instruct-2507, treinado com 45,000 amostras destiladas por um teacher, obtidas a partir de trajetórias reais de agentes de programação.

Porque isto não é redução do contexto

A redução elimina conteúdo. Quando um agente se aproxima do limite de contexto e remove as interações mais antigas, o ficheiro que leu na interação 3 desaparece. Se precisar desse ficheiro na interação 20, lê-o novamente e paga esses tokens uma segunda vez. A poupança foi apenas um empréstimo.

O Paritok substitui um segmento por uma forma mais curta e uma etiqueta, [REF:id], e mantém o texto completo no proxy. O modelo recupera um segmento chamando read_original ou expand_context. Isto altera o modo de falha. Uma ferramenta de redução falha por esquecimento e nunca o informa. Um compressor falha ao fornecer ao modelo um resumo com perda de informação, e o modelo pode pedir o original quando o resumo não é suficiente.

O filtro de ferramentas funciona da mesma forma. Os esquemas de ferramentas filtrados são substituídos por stubs, em vez de serem removidos, e o modelo recupera um deles chamando gateway_search_tools. Isto é importante porque um filtro que oculta permanentemente uma ferramenta altera aquilo que o agente consegue fazer, e só perceberia o problema através de uma tarefa que falhou silenciosamente.

As três alavancas e qual delas é gratuita

A primeira alavanca é o filtro do esquema de ferramentas. Cada pedido inclui todo o array tools. Numa interação do Claude Code com alguns servidores MCP (model context protocol) ligados, o projeto mede esse bloco em aproximadamente 29,000 tokens. O filtro gera embeddings do pedido do utilizador e da descrição de cada ferramenta com o BAAI/bge-small-en-v1.5, um modelo de embeddings de 130 MB, mantém as ferramentas correspondentes e substitui as restantes por stubs. O bloco diminui para aproximadamente 8,000 tokens. Esse modelo de embeddings é executado na CPU.

A segunda alavanca é a compressão de conteúdo. Esta é a parte que precisa do modelo de 4B numa GPU. As leituras de ficheiros, a saída das ferramentas e o histórico são reescritos para 25.7% do tamanho original. É daí que vem o valor de 74% apresentado. Leia com atenção: 74% é a taxa de compressão do conteúdo comprimido, não a redução da sua fatura.

A terceira alavanca é o resumo do histórico. Quando o orçamento de contexto fica preenchido, as interações anteriores à janela recente são resumidas. Assim, uma sessão longa continua a funcionar em vez de atingir o limite.

Apenas a segunda alavanca precisa de uma GPU. Esta é a frase mais útil desta página. pip install "paritok[toolselect]" disponibiliza o filtro de ferramentas numa VPS normal com CPU e corresponde à parte do produto que não tem custo mensal. Teste-a antes de alugar uma placa.

O que o projeto mediu e em que harness

[
  {
    "label": "Paritok-4B-v1",
    "compressed_to_pct": 25.7,
    "quality_retained_pct": 86.5
  },
  {
    "label": "gpt-4.1-mini",
    "compressed_to_pct": 50.2,
    "quality_retained_pct": 85.6
  },
  {
    "label": "gpt-5",
    "compressed_to_pct": 61.9,
    "quality_retained_pct": 93.6
  }
]

Estes são os valores publicados pelo próprio projeto, medidos no seu próprio harness com o SWE-bench Lite. O Paritok-4B-v1 comprime o conteúdo para 25.7% do tamanho original, mantendo 86.5% da taxa de resolução sem compressão. Usar o gpt-5 como compressor mantém mais qualidade, 93.6%, mas comprime apenas para 61.9%, e teria de pagar preços de frontier para poupar nos preços de frontier.

Leia a coluna da qualidade com atenção. Manter 86.5% da taxa de resolução significa que as execuções comprimidas falharam problemas que as execuções sem compressão resolveram, quase uma resolução em cada sete. Num benchmark, isto é um número numa tabela. No seu repositório, é uma tarefa que executa duas vezes.

[
  {
    "label": "Turn 1",
    "saved_pct": 25
  },
  {
    "label": "Turn 5",
    "saved_pct": 39
  },
  {
    "label": "Turn 12",
    "saved_pct": 57
  },
  {
    "label": "Turn 20",
    "saved_pct": 63
  }
]

A poupança de ponta a ponta aumenta à medida que a sessão decorre, porque o histórico se acumula e é o histórico que é comprimido. O projeto indica cerca de 25% numa única interação, 39% na interação 5 e 63% na interação 20. Também indica onde o crescimento termina: com um orçamento de 200,000 tokens, a poupança absoluta estabiliza em cerca de 48,000 tokens por interação, algures entre as interações 8 e 12, porque, quando o contexto fica cheio, o histórico deixa de crescer. O valor de "past 85%" frequentemente citado descreve sessões com o contexto saturado. Esse é o melhor caso, portanto não planeie com base nele.

Uma GPU de 24 GB compensa para o Paritok?

Uma placa de 24 GB é a unidade de aluguer habitual para um modelo deste tamanho. Em 7 August 2026, a tarifa mediana publicada para uma RTX 4090 com 24 GB era $0.44 por hora, com as ofertas mais baratas perto de $0.20. Use $0.44. Se ficar ligada durante todo o mês, são 730 horas, ou $321. Se funcionar apenas durante o horário de trabalho, 8 horas por dia durante 22 dias, são 176 horas, ou $77.

Agora converta a redução de tokens numa redução em dólares. A redução aplica-se aos tokens de entrada. Os tokens de saída passam pelo proxy sem alterações, por isso não mudam. Suponha que os tokens de entrada representam 80% do total em dólares, o que é normal num agente de programação, e confirme essa suposição na sua própria fatura. A poupança em dólares é então a redução de tokens multiplicada por 0.8.

[
  {
    "label": "Turn 5 (39% saved)",
    "bill_always_on_usd": "1,030",
    "bill_workday_only_usd": 248
  },
  {
    "label": "Turn 20 (63% saved)",
    "bill_always_on_usd": 637,
    "bill_workday_only_usd": 154
  },
  {
    "label": "Saturated (85% saved)",
    "bill_always_on_usd": 472,
    "bill_workday_only_usd": 114
  }
]

Com a taxa de 85% para sessões saturadas, poupa 68% da fatura. Assim, uma placa que fica ligada paga-se quando a sua despesa mensal com o agente ultrapassa cerca de $472, ou cerca de $114 se parar a instância fora do horário de trabalho. Com a taxa de 63% na interação 20, esses valores passam a $637 e $154. Com a taxa de 39% na interação 5, que corresponde ao comportamento real de sessões curtas, precisa de gastar cerca de $1,030 por mês para que valha a pena alugar a placa.

Há dois fatores que tornam este resultado melhor do que a tabela sugere. O modelo não precisa de 24 GB: a compilação q4 ocupa cerca de 2.5 GB e a compilação bf16 cerca de 8 GB. Por isso, uma placa mais pequena, ou um servidor GPU que já utilize para outra finalidade, reduz todos os valores do gráfico. Parar a instância quando ninguém está a programar é a medida com maior impacto, porque reduz o custo de aluguer em cerca de três quartos.

Há um fator que torna o resultado pior. A passagem de compressão exige processamento real. Cada token que o modelo 4B comprime tem primeiro de ser lido e depois escrito, o que aumenta a latência de cada interação do agente. Numa placa alugada à hora, esse custo aparece como tempo de espera, não como uma linha na fatura. Por isso, é fácil não o detetar até começar a senti-lo.

Se estiver a comparar, de forma geral, horas de GPU alugada com tokens de API, o ponto de equilíbrio entre uma GPU VPS e tokens de API aplica o mesmo cálculo à própria inferência.

Executar o gateway Paritok numa VPS

É necessário Python 3.10 ou mais recente. O Ubuntu 24.04 inclui Python 3.12, por isso uma imagem VPS básica é suficiente para a parte que utiliza apenas a CPU.

sudo apt update && sudo apt install -y python3-venv curl
python3 -m venv /opt/paritok/venv
source /opt/paritok/venv/bin/activate
pip install "paritok[proxy]==1.3.0"
pip install "paritok[toolselect]==1.3.0"

Fixe a versão. O repositório etiquetou v1.2.8 em 29 July 2026 e v1.3.0 em 5 August 2026. Um projeto que avança a esse ritmo altera os nomes das chaves de configuração entre versões. Um pip install paritok simples ou um git clone de main instala um gateway diferente na semana seguinte e não deixa registo de qual versão produziu os valores medidos.

O backend predefinido é Ollama. Transfira o modelo e atribua-lhe o nome curto que o proxy procura.

ollama pull paritok/paritok-4b-v1
ollama cp paritok/paritok-4b-v1 paritok-4b-v1

Como o modelo local gera uma reescrita para cada segmento que comprime, uma passagem de compressão que demora demasiado aparece como uma interação do agente bloqueada. O limite num_predict do Ollama para o comprimento da saída é a opção que a limita.

Escreva paritok.yaml junto dele. use_gpu_server: false é o que mantém a compressão no seu próprio hardware.

use_gpu_server: false
local_model:
  base_url: http://localhost:11434

paritok proxy --port 8080 --config-file paritok.yaml

paritok up é o atalho para tudo isto: transfere o modelo se este não estiver presente e inicia o proxy na porta 8080. Verifique o proxy antes de apontar um agente para ele.

curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/stats

/health devolve um pequeno objeto JSON que contém "status":"ok" e uma cadeia de versão. /stats devolve os totais de compressão e a estimativa do próprio proxy sobre o que poupou. Trate essa estimativa como uma avaliação que o proxy faz do próprio trabalho e confirme-a na página de utilização do seu fornecedor.

Para obter throughput em vez de simplicidade, vLLM serve o adapter sobre o modelo base.

vllm serve Qwen/Qwen3-4B-Instruct-2507 \
  --enable-lora \
  --lora-modules paritok-4b-v1=paritok/paritok-4b-v1 \
  --port 8000

Ollama é mais rápido de configurar. vLLM lida muito melhor com pedidos concorrentes, o que começa a ser importante assim que mais de um agente partilha o servidor. A diferença prática entre Ollama e vLLM é o que determina esta escolha.

Aponte o agente para o proxy através das variáveis de ambiente do URL base.

export ANTHROPIC_BASE_URL=http://127.0.0.1:8080
export OPENAI_BASE_URL=http://127.0.0.1:8080

Codex CLI ignora OPENAI_BASE_URL, por isso o projeto escreve ~/.codex/config.toml quando codex.enabled: true está definido em paritok.yaml. Exportar apenas a variável deixa o Codex a comunicar diretamente com o fornecedor. O sinal disso é um contador /stats que nunca aumenta enquanto trabalha.

Mantenha o listener em 127.0.0.1, nunca em 0.0.0.0. O proxy encaminha a sua chave da API do fornecedor para o upstream. Por isso, um proxy acessível pela Internet funciona como um relay aberto para essa chave: quem encontrar a porta pode gastar o seu dinheiro sem nunca ver a própria chave. Aceda-lhe a partir de um portátil através de um túnel SSH ou de uma VPN, em vez de abrir a porta.

Execute-o com systemd para que sobreviva a um reboot. Ajuste os caminhos de acordo com a sua instalação.

[Unit]
Description=Paritok compression proxy
After=network-online.target

[Service]
User=paritok
WorkingDirectory=/opt/paritok
ExecStart=/opt/paritok/venv/bin/paritok proxy --port 8080 --config-file /opt/paritok/paritok.yaml
Restart=on-failure

[Install]
WantedBy=multi-user.target

Ative-o com sudo systemctl enable --now paritok e execute curl /health novamente. Uma unidade que inicia e termina imediatamente normalmente indica que o caminho do ficheiro de configuração está errado. journalctl -u paritok -n 50 mostra o motivo.

A opção alojada e o custo que tem

O projeto também disponibiliza a compressão como serviço. Defina use_gpu_server: true com uma chave de API e o modelo 4B será executado no hardware do fornecedor, ao preço de $0.30 por milhão de tokens processados, gratuitamente até ao final de August 2026, de acordo com a documentação do próprio projeto. Isto elimina o custo do aluguer da GPU e todo o trabalho operacional descrito acima.

Também significa que os seus prompts e os ficheiros lidos pelo seu agente saem da sua máquina e chegam a um terceiro antes de chegarem ao fornecedor do modelo. O alojamento próprio existe precisamente para evitar esse encaminhamento. Decida qual dos dois objetivos pretende otimizar antes de definir essa flag, porque a alteração da flag ocupa uma linha, mas a consequência não.

Como medir o seu antes e depois

Os números publicados são os números do projeto, obtidos com o harness do projeto no SWE-bench Lite. O seu repositório não é o SWE-bench Lite. Faça as suas próprias medições.

• Execute uma semana normal sem proxy no caminho. Registe os tokens de entrada, os tokens lidos da cache e os tokens de saída em linhas separadas, a partir da página de utilização do seu provedor, e não como um único total em dólares.
• Execute a semana seguinte com o proxy à frente, realizando o mesmo tipo de trabalho.
• Compare as linhas de entrada e de leitura da cache. A saída deve permanecer aproximadamente estável, porque nada a comprime. Se a saída variar muito, alguma coisa além do proxy mudou.
• Conte as tarefas que teve de refazer. Essa é a parte de qualidade da comparação, e nenhum dashboard a reporta.
• Some as horas de GPU da segunda semana antes de comparar os totais.

Separar a entrada da saída é importante porque os dois componentes têm preços muito diferentes e um compressor só atua sobre um deles. Em agosto de 2026, o Claude Sonnet 4.6 custa $3 por milhão de tokens de entrada e $15 por milhão de tokens de saída, e a leitura da cache de prompts custa 10% da tarifa de entrada, ou $0.30 por milhão. A diferença entre o custo dos tokens de entrada e de saída determina se um compressor aplicado à entrada é útil para si. Para onde vão realmente os tokens do Claude Code mostra qual parte do seu contexto é suficientemente grande para justificar a compressão.

A cache de prompts complica particularmente o cálculo da filtragem de ferramentas. O bloco de ferramentas fica no início do pedido, por isso, depois do primeiro turno, normalmente é um acerto de cache a 10% do preço de entrada. Remover 21,000 tokens de um bloco em cache poupa 21,000 tokens a $0.30 por milhão, cerca de $0.006 por turno, e não os $0.063 que a tarifa sem cache indicaria. O projeto mantém o bloco filtrado inalterado durante a sessão, para que o prefixo em cache não mude. Um filtro que escolhesse novamente as ferramentas em cada turno invalidaria esse prefixo e custaria mais do que pouparia.

O que ainda não foi verificado

Todos os números de desempenho acima vêm do próprio projeto. Não existe uma reprodução independente dos resultados do SWE-bench Lite e, como as primeiras tags estão datadas de July 2026, também há muito pouco histórico operacional do código. A taxa de compressão e o valor de qualidade preservada são ambos medidos pela parte que beneficia de eles parecerem bons. Isso não significa que estejam errados. Significa que ainda não foram confirmados e que deve tratá-los de forma diferente de um número que produziu pessoalmente.

Há um comportamento documentado que vale a pena conhecer antes de culpar a sua configuração. O modelo de embeddings usado pelo filtro da ferramenta é carregado no primeiro pedido, e não no arranque. Por isso, o projeto documenta um aquecimento de 10 a 15 segundos e, depois, cerca de 15 ms por chamada. Envie um pedido descartável depois de o proxy arrancar para que a primeira interação real do agente não pareça bloqueada.

Há quatro coisas que pode verificar pessoalmente numa tarde: se o proxy arranca e continua em execução, se /stats se altera enquanto trabalha, se a linha de tokens de entrada do seu provider diminui efetivamente e se o agente continua a concluir o trabalho. Esses fatores são muito mais decisivos para a sua configuração do que qualquer benchmark publicado.

Quanto à posição desta ferramenta em relação às restantes: um gateway LiteLLM autoalojado encaminha e contabiliza os pedidos sem alterar o seu conteúdo, por isso as duas ferramentas resolvem problemas diferentes e podem ser encadeadas, com o Paritok colocado mais perto do agente. Se o objetivo real for reduzir a fatura, e não usar especificamente esta ferramenta, o conjunto mais amplo de controlos de custos para um agente num VPS inclui várias alterações que não custam nada experimentar primeiro.

FAQ

O Paritok reduz a minha fatura de API ou apenas o uso de contexto?

Reduz a fatura, porque o proxy reescreve o pedido antes de este chegar ao fornecedor, e o fornecedor cobra pelo que recebe. A dimensão dessa redução é inferior ao que o valor apresentado sugere. A taxa de 74% corresponde à compressão do conteúdo comprimido. De ponta a ponta, o projeto indica cerca de 25% num único turno e 63% no turno 20, e apenas os tokens de entrada são afetados. Os tokens de saída passam sem alterações.

De quanta GPU preciso para alojar o modelo de compressão?

A build q4 ocupa cerca de 2.5 GB e a build bf16 cerca de 8 GB, portanto o modelo cabe numa placa de 24 GB com muita memória disponível. Uma placa menor também funciona e melhora a relação de custo de equilíbrio. O filtro de schemas de ferramentas não precisa de GPU: usa BAAI/bge-small-en-v1.5, um modelo de embeddings de 130 MB que funciona na CPU. Instale paritok[toolselect] num VPS comum e terá a redução dos blocos de ferramentas pelo custo de uma pequena quantidade de RAM.

O que acontece se o compressor remover algo de que o agente precisava?

Nada é removido. Os segmentos comprimidos recebem uma tag [REF:id], e o modelo recupera o texto completo com read_original ou expand_context. Os schemas de ferramentas filtrados são substituídos por stubs, em vez de serem eliminados, e o modelo recupera um deles com gateway_search_tools. O risco real é mais discreto do que um ficheiro em falta: o modelo trabalha com um resumo com perdas e nunca percebe que deve pedir o original. É isso que o valor de 86.5% de qualidade retida no SWE-bench Lite mede.

Porque é que o meu primeiro pedido demora quinze segundos?

O modelo de embeddings usado pelo filtro de ferramentas é carregado no primeiro pedido, e não no arranque. O projeto documenta um aquecimento de 10 a 15 segundos e, depois disso, cerca de 15 ms por chamada. Envie um pedido descartável com curl depois de iniciar o proxy, e o primeiro turno real do agente não ficará bloqueado.

Devo usar o servidor GPU alojado em vez de alojar o serviço localmente?

Esta opção elimina o custo da GPU e a manutenção, por $0.30 por milhão de tokens processados em agosto de 2026. Também envia os seus prompts e os ficheiros lidos pelo agente para um terceiro antes de estes chegarem ao fornecedor do modelo. Se aloja o serviço localmente para manter o código numa infraestrutura sob o seu controlo, essa opção anula o motivo pelo qual começou. O alojamento local mantém o contexto e a chave de API do fornecedor no seu próprio servidor.