SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Paritok reduz a conta do seu agente de código?

O Paritok comprime leituras, ferramentas e histórico antes da API. Entenda a alegação de 74% menos tokens e calcule quando o gateway se paga.

O que o Paritok faz a 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 reduz os esquemas das ferramentas, as leituras de ficheiros, a saída das ferramentas e os turnos anteriores, envia o payload menor para o fornecedor e devolve a resposta sem alterações.

O fornecedor cobra-lhe pelo conteúdo que recebe, mas a fatura depende dos tokens removidos, do preço aplicável à cache e do número de turnos que o agente executa. Essa é toda a ideia. É uma afirmação diferente de “o seu contexto dura mais tempo” e é a razão pela qual esta ferramenta é interessante, em vez de ser apenas uma forma de organizar melhor os pedidos.

O projeto é recente. O gateway foi disponibilizado como código aberto em 15 July 2026. O PyPI regista a versão v1.3.14 em 6 October 2026 e a versão v1.3.0 em 5 August. 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) para o Qwen3-4B-Instruct-2507, destilado a partir de um conjunto de 45,000 segmentos extraídos de trajetórias reais de agentes de programação. Desses segmentos, 40,606 passaram a validação do professor e tornaram-se exemplos de treino.

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

A redução elimina conteúdo de forma definitiva. 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 era 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. Um redutor falha ao esquecer conteúdo e nunca o informa. Um compressor falha ao fornecer ao modelo um excerto com perda de informação, mas o modelo pode pedir o original quando o excerto não é suficiente.

Os esquemas de ferramentas filtrados continuam recuperáveis, mas o filtro adaptativo predefinido remove as ferramentas padrão não selecionadas e as ferramentas MCP não selecionadas, exceto quando o respetivo sinal de relevância MCP é acionado. Quando esse sinal é acionado, as ferramentas MCP não selecionadas são substituídas por stubs. gateway_search_tools permite a recuperação, e o gateway também deteta mensagens sobre ferramentas em falta e injeta as ferramentas correspondentes antes de repetir o pedido. Isto é importante porque um filtro que oculta permanentemente uma ferramenta altera o que o 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 de esquemas de ferramentas. Cada pedido inclui todo o array tools. Num turno do Claude Code sem servidores MCP (model context protocol) associados, o projeto mede esse bloco em aproximadamente 29,000 tokens; com MCP associado, indica 44,000 a 65,000 tokens. O filtro incorpora o pedido do utilizador e a descrição de cada ferramenta com BAAI/bge-small-en-v1.5, um modelo de embeddings de 130 MB, mantém as ferramentas correspondentes, remove as ferramentas padrão não selecionadas e cria stubs para ferramentas MCP não selecionadas apenas quando o sinal de relevância MCP é ativado. Caso contrário, remove também essas ferramentas MCP. No exemplo de 29,000 tokens do projeto, o bloco diminui para aproximadamente 8,000 tokens. Esse modelo de embeddings é executado no CPU.

A segunda alavanca é a compressão de conteúdo. É esta parte que utiliza o modelo 4B, numa GPU ou através do Ollama no CPU. As leituras de ficheiros, a saída das ferramentas e o histórico são reduzidos para 25.7% do tamanho original. O modelo seleciona principalmente trechos, em vez de os reescrever, permitindo apenas reescritas limitadas para conteúdos como resumos do raciocínio e enquadramento de chamadas de ferramentas. O artigo do projeto mede 96.0% dos identificadores, caminhos e números emitidos como ocorrências literais na entrada do corpus de treino gerado pelo professor; a saída do SWE-bench Lite retida para avaliação do modelo treinado obtém 96.2% na mesma auditoria. É daí que vem o valor de 74%. Leia-o com atenção: 74% é a taxa de compressão do conteúdo que é comprimido, não a redução da sua fatura.

A terceira alavanca é o resumo do histórico. Por predefinição, quando o contexto ultrapassa 80% da janela configurada, os turnos mais antigos são resumidos, enquanto quatro turnos recentes permanecem intactos, para que uma sessão longa continue a executar em vez de atingir o limite.

Uma GPU é opcional para a hospedagem própria. Essa é a frase mais útil desta página. pip install "paritok[toolselect]" disponibiliza o filtro de ferramentas num VPS comum com CPU, sem tarifa por token. Experimente-o antes de alugar uma placa.

O que o projeto mediu e em que harness

GráficoSWE-bench Lite: compression rate against solve quality retained (project's published figures)
Os dados por trás deste gráfico
[
  {
    "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%; nesse caso, pagaria preços de frontier para poupar preços de frontier.

Leia a coluna de qualidade com atenção. A qualidade mantida é a taxa de resolução do compressor dividida pela taxa de resolução de referência sem compressão. Manter 86.5% significa uma redução líquida de 13.5% nas resoluções em relação à referência. Esse valor não contabiliza a fração dos problemas resolvidos pela referência que deixou de ser resolvida, porque as execuções comprimidas também podem resolver problemas diferentes. O valor mede a compreensão, numa única execução, do código-fonte bruto comprimido, com a recuperação desativada e a recuperação de edições em produção ativada. Não mede o filtro de schema de ferramentas em CPU nem o gateway completo com várias interações.

GráficoReported input-token saving as a session grows (project's own harness)
Os dados por trás deste gráfico
[
  {
    "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 relata cerca de 25% numa única interação, 39% até à interação 5 e 63% até à interação 20. Apenas as interações 1 a 5 foram medidas; o README identifica as linhas posteriores como projeções. O README também indica onde o crescimento para: com um orçamento de 200,000 tokens, a poupança de conteúdo por interação estabiliza em cerca de 48,000 tokens, perto da interação 8 a 12, porque, quando o contexto fica cheio, o histórico deixa de crescer. A poupança adicional do filtro de ferramentas é de aproximadamente 21,000 tokens por interação, o que eleva o plateau combinado projetado para aproximadamente 69,000 tokens por interação. O valor frequentemente citado de "past 85%" descreve sessões com o contexto saturado. Esse é o melhor caso, e o mesmo README afirma que, com as definições predefinidas, a poupança estabiliza perto de um limite de cerca de 72%; por isso, não planeie com base nesse valor.

Uma GPU de 24 GB compensa para o Paritok?

A GPU é opcional, e o modelo cabe em placas com menos de 24 GB. Para um cálculo ilustrativo de aluguer, considere $0.44 por hora para uma placa de 24 GB. Se ficar ligada durante todo o mês, são 730 horas, ou seja, $321. Se funcionar apenas durante o horário de trabalho, 8 horas por dia durante 22 dias, são 176 horas, ou seja, $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, portanto o proxy não os comprime. Calcule separadamente o preço da alteração para novos tokens de entrada, escritas na cache e leituras da cache, usando as tarifas do seu fornecedor. Depois compare o custo total da API antes e depois. Mesmo que a entrada represente 80% do seu total em dólares, multiplicar uma redução de tokens por 0.8 não determina a poupança na fatura.

GráficoMonthly API saving needed to cover an illustrative $0.44/hour card
Os dados por trás deste gráfico
[
  {
    "label": "Always on (730 hours)",
    "required_api_saving_usd": 321.2
  },
  {
    "label": "Workday only (176 hours)",
    "required_api_saving_usd": 77.44
  }
]

Uma placa que fica ligada compensa o seu custo quando a poupança mensal medida na API ultrapassa $321.2, ou $77.44 se parar a instância fora do horário de trabalho. Uma redução de tokens de 85% não demonstra, por si só, uma poupança de 68% na fatura. Por isso, também não permite definir um limite mensal de despesas com agentes. Divida o custo do aluguer pela fração medida de poupança na fatura para obter esse limite.

Há dois fatores que tornam este cenário melhor do que o gráfico sugere. O modelo não precisa de 24 GB: a compilação q4 ocupa cerca de 2.5 GB e a compilação f16 cerca de 8 GB. Assim, uma placa mais pequena, ou uma máquina com GPU que já utilize para outra finalidade, reduz todos os valores apresentados no gráfico. Além disso, parar a instância quando ninguém está a programar é a medida com maior impacto, porque reduz o custo do aluguer em cerca de três quartos.

Há um fator que torna o cenário pior. A etapa de compressão exige processamento. Cada token que o modelo 4B comprime é um token que tem de ler, e cada segmento que mantém tem de ser escrito novamente. Isso acrescenta latência a 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 alugadas 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

Os metadados do pacote no PyPI aceitam Python 3.10 ou posterior, embora o selo no README indique 3.11 ou posterior. O Ubuntu 24.04 inclui Python 3.12, portanto uma imagem simples de VPS é suficiente para o filtro de ferramentas de 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.14"
pip install "paritok[toolselect]==1.3.14"

Fixe a versão. O PyPI regista v1.3.0 em 5 August 2026 e v1.3.14 em 6 October 2026. Um projeto que avança a esse ritmo renomeia elementos entre versões: a própria v1.3.0 renomeou expand_context para read_original na API. Um pip install paritok sem versão, ou um git clone de main, pode fornecer-lhe um gateway diferente na semana seguinte e não deixa registo de qual produziu os valores que mediu.

O backend predefinido é o Ollama. Faça pull do 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 escreve os spans que mantém para cada segmento comprimido, uma passagem de compressão que demora demasiado aparece como uma interação do agente bloqueada. O limite num_predict do Ollama para o tamanho da saída é o parâmetro que a limita.

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/v1
paritok proxy --port 8080 --config-file paritok.yaml

paritok up é o atalho para fazer pull do modelo, caso esteja em falta, e iniciar o proxy na porta 8080. O Ollama já tem de estar instalado. 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 conveniência, o 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 \
  --max-lora-rank 32 \
  --port 8000

A opção --max-lora-rank 32 está no comando do próprio projeto porque o adapter tem rank 32. Depois, defina local_model.base_url como http://localhost:8000/v1 em paritok.yaml para que o proxy comunique com o vLLM em vez do Ollama.

O Ollama é mais rápido de configurar. O vLLM gere pedidos concorrentes muito melhor, 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

O Codex CLI ignora OPENAI_BASE_URL. Por isso, paritok up escreve ~/.codex/config.toml por si 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 durante o trabalho.

Mantenha o listener em 127.0.0.1, nunca em 0.0.0.0. O proxy encaminha para o upstream as credenciais fornecidas em cada pedido, e o seu endpoint /stats sem autenticação expõe amostras do conteúdo original e comprimido. Assim, um listener exposto à Internet divulga contexto privado e recursos locais de compressão. 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 à sua instalação. Crie o utilizador paritok sob o qual a unidade será executada e dê-lhe o diretório de instalação:

sudo useradd --system --home-dir /opt/paritok --shell /usr/sbin/nologin paritok
sudo chown -R paritok:paritok /opt/paritok
[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 seu custo

O projeto também disponibiliza a compressão como serviço. Defina use_gpu_server: true com uma chave de API de paritok.com e o modelo 4B será executado no hardware desse serviço. Em 2 November 2026, o serviço cobra $0.30 por milhão de tokens de ficheiros comprimidos, usando crédito pré-pago, e a filtragem de esquemas de ferramentas é gratuita. As contas novas recebem $5 de crédito gratuito sem necessidade de cartão. O período de lançamento em que o serviço alojado era gratuito terminou em 1 October 2026. O serviço é pago desde então. Isto elimina a necessidade de alojar o modelo de compressão, mas o gateway continua a ser executado por si.

Isto também significa que os seus prompts e os ficheiros lidos pelo agente saem da sua máquina e chegam a terceiros antes de chegarem ao seu fornecedor de modelos. O alojamento próprio existe precisamente para evitar esse encaminhamento. Decida qual destas duas opções é a sua prioridade antes de definir essa flag. 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 com o harness 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, de escrita na cache, de leitura da cache e de saída em linhas separadas, usando a página de utilização do seu provedor, e não um único total em dólares.
  • Na semana seguinte, coloque o proxy à frente e execute o mesmo tipo de trabalho.
  • Compare as categorias de entrada com os preços efetivamente aplicados e inclua qualquer alteração no custo de saída. O proxy não comprime a saída, mas as alterações no comportamento do agente e no número de turnos ainda afetam a quantidade de saída que compra.
  • Conte as tarefas que teve de refazer. Essa é a parte da qualidade da comparação, e nenhum dashboard informa esse valor.
  • Adicione as horas de GPU à segunda semana antes de comparar os totais.

Separar a entrada da saída é importante porque os dois tipos de tokens têm preços muito diferentes e um compressor afeta apenas um deles. Em 2 November 2026, 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 prompt cache custa 10% da tarifa de entrada, ou $0.30 por milhão. O Claude Sonnet 5.5, mais recente, custa $2 e $10, e as leituras da cache custam 5% da tarifa de entrada, ou $0.10 por milhão. A diferença entre o custo dos tokens de entrada e de saída determina se um compressor no lado da entrada vale a pena para si. Para onde vão efetivamente os tokens do Claude Code mostra que parte do contexto é suficientemente grande para justificar a compressão.

A prompt caching complica sobretudo o cálculo relacionado com o filtro de ferramentas. O bloco de ferramentas fica no início do pedido. Por isso, depois do primeiro turno, normalmente é obtido a partir da cache; no Sonnet 4.6, isso custa 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 poderia custar mais do que pouparia.

O que continua por verificar

Todos os números de desempenho acima vêm do próprio projeto. Existe uma verificação independente da compressão num corpus sintético, mas ela declara explicitamente que não testa o sucesso das tarefas do SWE-bench; os números de qualidade de resolução do SWE-bench Lite apresentados pelo projeto continuam sem confirmação independente. Como o gateway foi disponibilizado como código aberto em julho de 2026, também existe 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 parte que beneficia de que pareçam bons. Isso não significa que estejam errados. Significa que continuam sem confirmação, e deve tratá-los de forma diferente de um número que tenha produzido por si próprio.

Convém conhecer um comportamento documentado antes de culpar a sua configuração. O modelo de embeddings usado pelo filtro de ferramentas é carregado no primeiro pedido, e não durante o arranque, pelo que 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 o primeiro turno real do agente não pareça ficar bloqueado.

Há quatro coisas que pode verificar por si próprio numa tarde: se o proxy arranca e continua em execução, se /stats muda enquanto trabalha, se a linha de tokens de entrada do seu fornecedor diminui efetivamente e se o agente continua a concluir o trabalho. Esses fatores determinam o resultado na sua configuração muito melhor do que qualquer benchmark publicado.

Quanto à posição desta ferramenta relativamente às restantes: um gateway LiteLLM autoalojado encaminha e contabiliza os pedidos sem alterar o respetivo conteúdo, pelo que 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 controlos de custos para um agente num VPS inclui várias alterações que pode experimentar primeiro sem custos.

FAQ

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

O Paritok reduz o pedido antes de este chegar ao fornecedor. A poupança na fatura depende dos preços dos tokens removidos e do número de turnos resultante do agente. A dimensão dessa redução é menor do que o valor destacado sugere. A taxa de 74% corresponde à compressão do conteúdo que está a ser comprimido. De ponta a ponta, o projeto indica cerca de 25% num único turno e projeta 63% até ao turno 20 em poupança de tokens de entrada. Os tokens de saída passam sem alterações, mas o volume gerado continua a depender do comportamento do agente.

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

Uma GPU é opcional: o Ollama também executa o modelo na CPU. A build q4 ocupa cerca de 2.5 GB e a build f16 cerca de 8 GB, pelo que o modelo cabe numa placa de 24 GB com bastante espaço disponível. Uma placa menor também funciona e melhora a relação de custo de equilíbrio a seu favor. O filtro de schemas de ferramentas não precisa de GPU: usa o BAAI/bge-small-en-v1.5, um modelo de embeddings de 130 MB que executa 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 é perdido permanentemente. O modelo remove trechos do conteúdo encaminhado, mas os segmentos comprimidos recebem a etiqueta [REF:id] e o modelo recupera o texto completo com read_original ou expand_context. O filtro de ferramentas predefinido remove as ferramentas padrão não selecionadas e as ferramentas MCP não selecionadas, exceto quando o sinal de relevância MCP é ativado; nesse caso, cria stubs para essas ferramentas MCP. A recuperação de ferramentas usa gateway_search_tools e a deteção de mensagens sobre ferramentas em falta. O risco real é mais difícil de detetar do que um ficheiro em falta: o modelo trabalha a partir de um excerto com perdas e nunca percebe que deveria pedir o original. O valor de 86.5% de qualidade preservada no SWE-bench Lite mede a compreensão numa única execução do código-fonte bruto comprimido, com a recuperação desativada e a recuperação de edições em produção ativada. Não mede o filtro de schemas de ferramentas na CPU nem o gateway completo com vários turnos.

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, cerca de 15 ms por chamada. Depois de iniciar o proxy, envie um pedido descartável com curl. Assim, 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 alojamento do modelo de compressão e o custo do aluguer de GPU, mas continua a exigir a manutenção do gateway. Em 2 de novembro de 2026, o custo é de $0.30 por milhão de tokens de ficheiros comprimidos, pago com crédito pré-pago, com $5 de crédito gratuito para contas novas. O período de lançamento gratuito terminou em 1 de outubro de 2026. Esta opção também envia os seus pedidos e os ficheiros lidos pelo agente para terceiros 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 elimina o motivo pelo qual começou. O alojamento local mantém a compressão no seu próprio servidor. Os pedidos comprimidos e as credenciais do fornecedor continuam a ser enviados para o fornecedor do modelo.

Este artigo foi útil?