Paritok reduz a conta do agente de programação?

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 menor para o upstream e devolve a resposta sem alterações.

O fornecedor cobra pelo conteúdo que recebe. Portanto, um payload menor resulta numa fatura menor. Essa é toda a ideia. Isto é diferente da afirmação de que "o seu contexto dura mais tempo" e é o motivo pelo qual esta ferramenta é interessante, em vez de ser apenas uma forma de organizar melhor os pedidos.

O projeto é recente. As primeiras tags públicas datam de July 2026 e a tag atual é v1.3.0, datada de 5 August 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 Qwen3-4B-Instruct-2507, treinado com 45,000 amostras destiladas por um professor e extraídas de trajetórias reais de agentes de programação.

Por que isto não é redução do contexto

A redução elimina conteúdo. Quando um agente se aproxima do limite de contexto e descarta os turnos mais antigos, o ficheiro que leu no turno 3 desaparece. Se precisar desse ficheiro no turno 20, lê-o novamente e esses tokens são contabilizados uma segunda vez. A poupança foi apenas temporária.

O Paritok substitui um segmento por uma forma mais curta e uma etiqueta, [REF:id], mantendo o texto completo no proxy. O modelo recupera um segmento chamando read_original ou expand_context. Isto altera o modo de falha. Um redutor falha por esquecer conteúdo e nunca o informa. Um compressor falha ao fornecer ao modelo um resumo com perdas, 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 seu agente consegue fazer, e só descobriria 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 sessão do Claude Code com alguns servidores MCP (model context protocol) associados, o projeto mede esse bloco em cerca de 29,000 tokens. O filtro gera embeddings do pedido do utilizador e da descrição de cada ferramenta com 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 cerca de 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 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 como destaque. Leia-o 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]" fornece o filtro de ferramentas numa VPS comum com CPU e é a metade do produto que não tem custos mensais. Experimente-o 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 números 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 preços de frontier.

Leia a coluna de qualidade com honestidade. Manter 86.5% da taxa de resolução significa que as execuções comprimidas falharam nos problemas que as execuções sem compressão resolveram, aproximadamente uma resolução em cada sete. Num benchmark, isto é um número numa tabela. No seu repositório, é uma tarefa que terá de executar 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 avança, 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, aproximadamente entre a interação 8 e a 12, porque, quando o contexto fica cheio, o histórico deixa de crescer. A referência frequentemente citada a "past 85%" descreve sessões com o contexto saturado. Esse é o melhor caso, por isso 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 de agosto de 2026, a tarifa mediana publicada para utilização sob demanda de uma RTX 4090 com 24 GB era de $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 for usada 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 correspondem a 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 é, portanto, 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
  }
]

No valor de 85% para uma sessão saturada, conserva 68% da fatura. Assim, uma placa que fique ligada paga-se quando a sua despesa mensal com o agente ultrapassa aproximadamente $472, ou aproximadamente $114 se desligar a instância fora do horário de trabalho. No valor de 63% para o turno 20, esses valores passam a ser $637 e $154. No valor de 39% para o turno 5, que corresponde ao comportamento real de sessões curtas, precisa de gastar aproximadamente $1,030 por mês antes de sequer compensar alugar a placa.

Dois fatores 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. Assim, uma placa mais pequena, ou uma máquina GPU que já use para outra finalidade, reduz todos os valores do gráfico. E parar a instância quando ninguém está a programar é a medida com maior impacto, porque reduz o aluguer em cerca de três quartos.

Um fator torna o resultado pior. A etapa de compressão exige processamento real. Cada token que o modelo 4B comprime é um token que precisa de ler e depois escrever, o que aumenta a latência de cada turno 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 alugadas com tokens de API, o ponto de equilíbrio entre uma GPU VPS e tokens de API faz o mesmo cálculo para a própria inferência.

Executar o gateway Paritok numa VPS

É necessário ter Python 3.10 ou mais recente. Ubuntu 24.04 inclui Python 3.12, por isso uma imagem VPS normal é suficiente para a parte que usa 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 marcou 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 deles 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

Escreva paritok.yaml ao lado 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 o que foi descrito acima: transfere o modelo se este estiver em falta 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 string 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 conveniência, vLLM disponibiliza 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 instalar. vLLM gere muito melhor os 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 a escolha neste caso.

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 avança enquanto trabalha.

Mantenha o listener em 127.0.0.1, nunca em 0.0.0.0. O proxy encaminha a sua chave de API do fornecedor para o upstream. Um proxy acessível a partir da internet torna-se 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 novamente curl /health. 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 associado

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

Isto 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 seu modelo. O self-hosting existe precisamente para evitar esse encaminhamento. Decida qual destas duas opções pretende privilegiar antes de definir essa flag, porque a alteração da flag ocupa uma linha, mas a consequência não.

Como medir os seus próprios resultados antes e depois

Os números publicados são os números do projeto, obtidos pelo conjunto de testes do projeto no SWE-bench Lite. O seu repositório não é o SWE-bench Lite. Meça os seus próprios resultados.

• 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 na página de utilização do seu provedor, e não como um único total em dólares.
• Na semana seguinte, execute o proxy à frente e faça 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, algo além do proxy mudou.
• Conte as tarefas que teve de refazer. Essa é a metade relacionada com a qualidade, 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 têm preços muito diferentes e um compressor só atua sobre uma delas. 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 uma leitura da cache de prompts custa 10% da tarifa de entrada, $0.30 por milhão. A diferença entre o custo dos tokens de entrada e de saída determina se um compressor do lado da entrada tem alguma utilidade para si. Para onde vão realmente os tokens do Claude Code mostra que parte do seu contexto é suficientemente grande para justificar a compressão.

A cache de prompts complica principalmente os cálculos do filtro de ferramentas. O bloco de ferramentas fica no início do pedido. Por isso, depois do primeiro turno, normalmente é um acerto da 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, ou cerca de $0.006 por turno, em vez dos $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 a 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 são de July 2026, também há muito pouco histórico operacional por trás do código. A taxa de compressão e o valor de qualidade preservada são medidos pela própria parte que beneficia de resultados favoráveis. Isso não significa que estejam errados. Significa que ainda não foram confirmados e que devem ser considerados de forma diferente de um número que você próprio produziu.

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 durante o arranque. Por isso, o projeto documenta um aquecimento de 10 a 15 segundos, seguido de 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.

Você pode verificar quatro coisas por conta própria numa tarde: se o proxy arranca e continua ativo, se /stats muda enquanto você trabalha, se a linha de tokens de entrada do seu provedor realmente diminui e se o agente continua a concluir o trabalho. Essas verificações são muito mais relevantes para a sua configuração do que qualquer benchmark publicado.

Quanto à posição desta ferramenta em relação às outras que você usa: um gateway LiteLLM auto-hospedado encaminha e contabiliza os pedidos sem alterar o seu conteúdo, portanto as duas ferramentas resolvem problemas diferentes e podem ser encadeadas, com o Paritok mais próximo do agente. Se o objetivo real for reduzir a fatura, e não usar especificamente esta ferramenta, o conjunto mais amplo de controles de custos para um agente numa VPS inclui várias alterações que não custam nada para testar primeiro.

FAQ

O Paritok reduz a minha fatura da API ou apenas o uso do 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 à sugerida pelo valor de destaque. A taxa de 74% corresponde à compressão do conteúdo comprimido. De ponta a ponta, o projeto regista cerca de 25% numa única interação e 63% na interação 20, e apenas os tokens de entrada sofrem alterações. Os tokens de saída passam sem alterações.

De que GPU preciso para alojar localmente o modelo de compressão?

A versão q4 ocupa cerca de 2.5 GB e a versão bf16 cerca de 8 GB, por isso o modelo cabe numa placa de 24 GB com bastante memória disponível. Uma placa menor também funciona e melhora o cálculo do ponto de equilíbrio a seu favor. O filtro de esquemas de ferramentas não precisa de GPU: usa paritok[toolselect], um modelo de embeddings de 130 MB que é executado na CPU. Instale paritok[toolselect] numa VPS comum para obter a redução dos blocos de ferramentas com um pequeno consumo adicional de RAM.

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

Nada é removido. Os segmentos comprimidos incluem uma etiqueta [REF:id], e o modelo recupera o texto completo com read_original ou expand_context. Os esquemas de ferramentas filtrados recebem stubs em vez de serem eliminados, e o modelo recupera um deles com gateway_search_tools. O risco real é mais silencioso do que um ficheiro em falta: o modelo trabalha a partir de um resumo com perdas e nunca percebe que deveria 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, para que a primeira interação real do agente não fique bloqueada.

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

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