Paritok: gateway token per ridurre i costi degli agent

Cosa fa Paritok a una richiesta

Paritok è un gateway per i token: un proxy che si interpone tra il tuo coding agent e l'API del modello e comprime ogni richiesta prima di inoltrarla. Il tuo agent comunica con http://127.0.0.1:8080 invece che con il provider. Il proxy riscrive gli schemi degli strumenti, le letture dei file, l'output degli strumenti e i turni precedenti, invia a monte un payload più piccolo e restituisce la risposta senza modificarla.

Il provider ti addebita ciò che riceve, quindi un payload più piccolo produce una fattura più contenuta. Questo è il principio fondamentale. È un'affermazione diversa da "il tuo contesto dura più a lungo" ed è il motivo per cui questo strumento è interessante, non solo più ordinato.

Il progetto è recente. I primi tag pubblici sono datati luglio 2026 e il tag attuale è v1.3.0, datato 5 agosto 2026. I pesi e il codice del gateway sono distribuiti con licenza Apache 2.0. Il modello di compressione è un adapter LoRA (low-rank adaptation) basato su Qwen3-4B-Instruct-2507, addestrato su 45,000 campioni distillati da un teacher e ricavati da traiettorie reali di coding agent.

Perché non si tratta di riduzione del contesto

La riduzione elimina i contenuti. Quando un agente si avvicina al limite del contesto e scarta i turni più vecchi, il file letto al turno 3 non è più disponibile. Se gli serve al turno 20, legge di nuovo il file e paghi quei token una seconda volta. Il risparmio era solo temporaneo.

Paritok sostituisce un segmento con una forma più breve e un tag, [REF:id], mantenendo il testo completo sul proxy. Il modello recupera un segmento chiamando read_original o expand_context. Questo modifica la modalità di errore. Un sistema di riduzione fallisce dimenticando il contenuto e non te lo segnala. Un compressore fallisce fornendo al modello un riepilogo con perdita di informazioni; il modello può richiedere l'originale quando il riepilogo non è sufficiente.

Il filtro degli strumenti funziona nello stesso modo. Gli schemi degli strumenti filtrati vengono sostituiti da stub anziché rimossi, e il modello ne recupera uno chiamando gateway_search_tools. Questo è importante perché un filtro che nasconde definitivamente uno strumento modifica ciò che l'agente è in grado di fare, e te ne accorgeresti solo tramite un'attività terminata silenziosamente in modo errato.

Le tre leve e quale non comporta costi

La prima leva è il filtro dello schema degli strumenti. Ogni richiesta contiene l'intero array tools. In un turno di Claude Code con alcuni server MCP (Model Context Protocol) collegati, il progetto misura questo blocco in circa 29,000 token. Il filtro crea gli embedding della richiesta dell'utente e della descrizione di ogni strumento con BAAI/bge-small-en-v1.5, un modello di embedding da 130 MB, mantiene gli strumenti pertinenti e sostituisce gli altri con stub. Il blocco si riduce a circa 8,000 token. Questo modello di embedding viene eseguito sulla CPU.

La seconda leva è la compressione dei contenuti ed è quella che richiede il modello 4B su una GPU. La lettura dei file, l'output degli strumenti e la cronologia vengono riscritti fino a raggiungere il 25.7% delle dimensioni originali. È da qui che deriva il dato del 74%. Va interpretato correttamente: il 74% è il tasso di compressione applicato ai contenuti compressi, non la riduzione della fattura.

La terza leva è il riepilogo della cronologia. Quando il budget del contesto si esaurisce, i turni precedenti alla finestra recente vengono riepilogati. In questo modo una sessione lunga può continuare invece di raggiungere il limite.

Solo la seconda leva richiede una GPU. Questa è la frase più importante di questa pagina. pip install "paritok[toolselect]" offre il filtro degli strumenti su un normale VPS con CPU e rappresenta la parte del prodotto che non comporta costi mensili. Provalo prima di noleggiare una scheda.

Cosa ha misurato il progetto e con quale 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
  }
]

Questi sono i dati pubblicati dal progetto, misurati con il suo harness su SWE-bench Lite. Paritok-4B-v1 comprime il contenuto al 25.7% delle dimensioni originali, mantenendo il 86.5% del tasso di risoluzione non compresso. Usando gpt-5 come compressore si conserva una qualità maggiore, 93.6%, ma il contenuto viene compresso soltanto al 61.9%; in pratica, pagheresti prezzi da modello frontier per risparmiare sui prezzi da modello frontier.

Leggi onestamente la colonna della qualità. Mantenere l'86.5% del tasso di risoluzione significa che le esecuzioni compresse hanno fallito problemi risolti dalle esecuzioni non compresse: quasi un problema su sette. Su un benchmark è un numero in una tabella. Nel tuo repository è un'attività che esegui due volte.

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

Il risparmio end-to-end aumenta con la durata della sessione, perché la cronologia si accumula ed è proprio la cronologia a essere compressa. Il progetto riporta circa il 25% su un singolo turno, il 39% entro il turno 5 e il 63% entro il turno 20. Indica anche quando la crescita si arresta: con un budget di 200,000 token, il risparmio assoluto si stabilizza intorno a 48,000 token per turno, tra il turno 8 e il turno 12 circa, perché quando il contesto è pieno la cronologia smette di crescere. La cifra ampiamente citata di "oltre l'85%" descrive sessioni in cui il contesto è saturo. Questo è il caso migliore, quindi non pianificare il sistema su questa percentuale.

Una GPU da 24 GB si ripaga con Paritok?

Una scheda da 24 GB è l'unità di noleggio abituale per un modello di queste dimensioni. Al 7 agosto 2026, la tariffa on-demand mediana pubblicata per una RTX 4090 da 24 GB era di $0.44 all'ora, mentre le offerte più economiche erano vicine a $0.20. Usiamo $0.44. Se resta in esecuzione per tutto il mese, sono 730 ore, quindi $321. Se la esegui soltanto durante l'orario di lavoro, 8 ore al giorno per 22 giorni, sono 176 ore, quindi $77.

Ora converti la riduzione dei token in una riduzione dei costi. La riduzione si applica ai token di input. I token di output attraversano il proxy senza modifiche, quindi non cambiano. Supponi che i token di input rappresentino l'80% del costo totale, un valore normale per un coding agent, e verifica questa ipotesi sulla tua fattura. Il risparmio in denaro è quindi la riduzione dei token moltiplicata per 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
  }
]

Con il valore dell'85% per le sessioni sature, mantieni il 68% della spesa. Una scheda lasciata sempre in esecuzione si ripaga quindi quando la spesa mensile per l'agent supera circa $472, oppure circa $114 se arresti l'istanza al di fuori dell'orario di lavoro. Con il valore del 63% al turno 20, le soglie diventano $637 e $154. Con il valore del 39% al turno 5, che corrisponde alle sessioni brevi reali, servono circa $1,030 al mese prima che valga la pena noleggiare la scheda.

Due aspetti migliorano il risultato rispetto a quanto mostra la tabella. Il modello non richiede 24 GB: la build q4 occupa circa 2.5 GB e la build bf16 circa 8 GB. Una scheda più piccola, oppure un GPU box che esegui già per un altro scopo, riduce quindi tutti i valori del grafico. Inoltre, arrestare l'istanza quando nessuno scrive codice è il fattore più importante, perché riduce il costo di noleggio di circa tre quarti.

Un aspetto peggiora il risultato. Il passaggio di compressione richiede effettivamente risorse. Ogni token che il modello 4B comprime deve prima essere letto e poi riscritto, aumentando la latenza di ogni turno dell'agent. Se noleggi la scheda a ore, questo costo si manifesta come tempo di attesa e non come una voce in fattura. Per questo è facile non accorgersene finché non lo si sperimenta direttamente.

Se stai confrontando in generale le ore di GPU noleggiate con i token API, il punto di pareggio tra un GPU VPS e i token API applica lo stesso calcolo all'inferenza vera e propria.

Eseguire il gateway Paritok su un VPS

È richiesto Python 3.10 o versioni successive. Ubuntu 24.04 include Python 3.12, quindi per la parte che usa soltanto la CPU è sufficiente un'immagine VPS standard.

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"

Bloccare la versione. Il repository ha contrassegnato v1.2.8 il 29 luglio 2026 e v1.3.0 il 5 agosto 2026; un progetto che procede a questo ritmo rinomina le chiavi di configurazione tra una release e l'altra. Un semplice pip install paritok o un git clone di main installa la versione del gateway disponibile la settimana successiva e non lascia traccia della versione che ha prodotto i valori misurati.

Il backend predefinito è Ollama. Scaricare il modello, quindi assegnargli il nome breve cercato dal proxy.

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

Poiché il modello locale genera una riscrittura per ogni segmento che comprime, un passaggio di compressione troppo lungo si manifesta come un turno dell'agente bloccato; il limite num_predict di Ollama sulla lunghezza dell'output è il parametro che lo limita.

Scrivere paritok.yaml accanto a esso. use_gpu_server: false mantiene la compressione sul proprio hardware.

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

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

paritok up è la scorciatoia per tutte le operazioni precedenti: scarica il modello se non è presente e avvia il proxy sulla porta 8080. Controllare il proxy prima di configurarlo nell'agente.

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

/health restituisce un piccolo oggetto JSON contenente "status":"ok" e una stringa con la versione. /stats restituisce i totali della compressione e la stima del proxy sul risparmio ottenuto. Considerare questa stima come una valutazione del proxy sul proprio lavoro e verificarla nella pagina dei consumi del provider.

Per privilegiare il throughput rispetto alla praticità, vLLM esegue l'adapter sopra il modello di base.

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

Ollama è più rapido da configurare. vLLM gestisce molto meglio le richieste concorrenti, una differenza che diventa rilevante non appena più di un agente condivide la macchina. La differenza pratica tra Ollama e vLLM determina quale soluzione scegliere.

Configurare l'agente affinché utilizzi il proxy tramite le variabili d'ambiente dell'URL di 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, quindi il progetto scrive ~/.codex/config.toml quando codex.enabled: true è impostato in paritok.yaml. Esportare soltanto la variabile lascia Codex collegato direttamente al provider; il segnale è un contatore /stats che non cambia durante il lavoro.

Mantenere il listener su 127.0.0.1, mai su 0.0.0.0. Il proxy inoltra la chiave API del provider al servizio upstream, quindi un proxy raggiungibile da Internet diventa un relay aperto per quella chiave: chiunque trovi la porta può spendere il denaro dell'account senza vedere la chiave. Raggiungerlo da un laptop tramite un tunnel SSH o una VPN invece di aprire la porta.

Eseguire il servizio tramite systemd, in modo che sopravviva a un riavvio. Adattare i percorsi alla propria installazione.

[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

Abilitarlo con sudo systemctl enable --now paritok, quindi eseguire nuovamente curl /health. Un'unità che si avvia e termina subito indica di solito un percorso errato del file di configurazione; journalctl -u paritok -n 50 stampa il motivo.

L'opzione hosted e il relativo costo

Il progetto offre anche la compressione come servizio. Imposta use_gpu_server: true con una chiave API: il modello 4B viene eseguito sull'hardware del fornitore, al costo di $0.30 per milione di token elaborati, gratuitamente fino alla fine di agosto 2026 secondo la documentazione del progetto. In questo modo elimini il costo del noleggio della GPU e tutte le attività operative descritte sopra.

Questo significa anche che i prompt e i file letti dal tuo agente lasciano il tuo computer e raggiungono una terza parte prima di arrivare al fornitore del modello. Il self-hosting serve proprio a evitare questo passaggio. Prima di impostare quel flag, stabilisci quale dei due obiettivi vuoi privilegiare: modificare il flag richiede una sola riga, ma la conseguenza è molto più ampia.

Come misurare il proprio prima e dopo

I numeri pubblicati sono quelli del progetto, ottenuti con l'harness del progetto su SWE-bench Lite. Il vostro repository non è SWE-bench Lite. Misurate il vostro caso.

• Eseguite una settimana normale senza proxy nel percorso. Registrate i token di input, i token letti dalla cache e i token di output su righe separate nella pagina di utilizzo del vostro provider, non come un unico totale in dollari.
• Eseguite la settimana successiva con il proxy davanti, svolgendo lo stesso tipo di lavoro.
• Confrontate le righe relative all'input e ai token letti dalla cache. L'output dovrebbe rimanere sostanzialmente stabile, perché nulla lo comprime. Se l'output è cambiato molto, è intervenuto un altro cambiamento oltre al proxy.
• Contate le attività che avete dovuto ripetere. Questa è la parte relativa alla qualità del compromesso e nessun dashboard la riporta.
• Prima di confrontare i totali, aggiungete le ore GPU della seconda settimana.

Separare input e output è importante perché hanno prezzi molto diversi e un compressore interviene soltanto su uno dei due. Ad agosto 2026, Claude Sonnet 4.6 costa $3 per milione di token di input e $15 per milione di token di output; la lettura dalla cache dei prompt costa il 10% della tariffa di input, cioè $0.30 per milione. La differenza tra il costo dei token di input e di output determina se un compressore lato input è utile nel vostro caso. Dove vengono effettivamente utilizzati i token di Claude Code indica quale parte del contesto è abbastanza grande da giustificare la compressione.

Il prompt caching complica in particolare i calcoli relativi al filtro degli strumenti. Il blocco degli strumenti si trova all'inizio della richiesta, quindi dopo il primo turno normalmente viene letto dalla cache al 10% del prezzo dell'input. Rimuovere 21,000 token da un blocco memorizzato nella cache consente di risparmiare 21,000 token alla tariffa di $0.30 per milione, cioè circa $0.006 per turno, invece dei $0.063 suggeriti dalla tariffa senza cache. Il progetto mantiene invariato il blocco filtrato per tutta la sessione, così il prefisso memorizzato nella cache non cambia. Un filtro che selezionasse nuovamente gli strumenti a ogni turno invaliderebbe quel prefisso e costerebbe più di quanto farebbe risparmiare.

Cosa non è ancora verificato

Tutti i dati sulle prestazioni riportati sopra provengono direttamente dal progetto. Non esiste una riproduzione indipendente dei risultati SWE-bench Lite e, con i primi tag datati July 2026, il codice ha anche una storia operativa molto limitata. Sia il tasso di compressione sia il dato sulla qualità conservata sono misurati dalla parte che trae vantaggio dal fatto che risultino positivi. Questo non significa che siano errati. Significa che non sono confermati e che dovresti considerarli diversamente da un dato prodotto direttamente da te.

Prima di attribuire il problema alla tua configurazione, è utile conoscere un comportamento documentato. Il modello di embedding usato dal filtro dello strumento viene caricato alla prima richiesta, non all'avvio. Per questo il progetto indica un avvio a regime di 10 to 15 secondi, seguito da circa 15 ms per chiamata. Invia una richiesta di prova subito dopo l'avvio del proxy, così il primo turno reale dell'agente non sembrerà bloccato.

In un pomeriggio puoi verificare direttamente quattro aspetti: se il proxy si avvia e resta attivo, se /stats cambia mentre lavori, se la voce relativa agli input token del tuo provider diminuisce davvero e se l'agente completa comunque il lavoro. Per la tua configurazione, questi elementi sono molto più determinanti di qualsiasi benchmark pubblicato.

Per quanto riguarda l'integrazione con gli altri strumenti: un gateway LiteLLM self-hosted inoltra e misura le richieste senza modificarne il contenuto, quindi le due soluzioni risolvono problemi diversi e possono essere usate in catena, con Paritok nel punto più vicino all'agente. Se l'obiettivo reale è ridurre la spesa, invece di usare proprio questo strumento, l'insieme più ampio di controlli dei costi per un agente su un VPS include diverse modifiche che puoi provare gratuitamente come primo passo.

FAQ

Paritok riduce il costo della mia API o soltanto l'utilizzo del contesto?

Riduce il costo, perché il proxy riscrive la richiesta prima che raggiunga il provider, che addebita i token ricevuti. L'entità della riduzione è inferiore a quanto suggerisce il dato principale. Il 74% indica il tasso di compressione del contenuto compresso. Considerando l'intero flusso, il progetto riporta circa il 25% su un singolo turno e il 63% entro il turno 20; inoltre, cambiano soltanto i token di input. I token di output passano senza modifiche.

Quanta GPU serve per eseguire autonomamente il modello di compressione?

La build q4 occupa circa 2.5 GB e la build bf16 circa 8 GB, quindi il modello entra in una scheda da 24 GB con molto spazio disponibile. È sufficiente anche una scheda più piccola, e il punto di pareggio economico diventa più favorevole. Il filtro degli schemi degli strumenti non richiede alcuna GPU: usa BAAI/bge-small-en-v1.5, un modello di embedding da 130 MB che viene eseguito sulla CPU. Installa paritok[toolselect] su un VPS ordinario per ottenere la riduzione dei blocchi degli strumenti usando soltanto una piccola quantità di RAM.

Cosa succede se il compressore rimuove qualcosa che serviva all'agente?

Non viene rimosso nulla. I segmenti compressi includono il tag [REF:id] e il modello recupera il testo completo con read_original o expand_context. Gli schemi degli strumenti filtrati vengono sostituiti da stub anziché eliminati, e il modello ne recupera uno con gateway_search_tools. Il rischio reale è meno evidente di un file mancante: il modello lavora su un riepilogo con perdita di informazioni e non si accorge di dover richiedere l'originale. È questo che misura il dato dell'86.5% di qualità mantenuta su SWE-bench Lite.

Perché la prima richiesta richiede quindici secondi?

Il modello di embedding usato dal filtro degli strumenti viene caricato alla prima richiesta, non all'avvio. Il progetto documenta un riscaldamento iniziale di 10-15 secondi, seguito da circa 15 ms per chiamata. Dopo avere avviato il proxy, invia una richiesta di prova con curl: il primo turno reale dell'agente non subirà ritardi.

Devo usare il server GPU gestito invece di eseguire il servizio autonomamente?

Elimina il costo della GPU e della manutenzione, con un prezzo di $0.30 per milione di token elaborati ad agosto 2026. Inoltre, invia i prompt e i file letti dall'agente a una terza parte prima di inoltrarli al provider del modello. Se esegui il servizio autonomamente per mantenere il codice su un'infrastruttura sotto il tuo controllo, questa impostazione annulla il motivo per cui hai iniziato. L'esecuzione autonoma mantiene sia il contesto sia la chiave API del provider sul tuo server.