jq.
Vedi la richiesta reale
ID del modello, messaggi, strumenti e parametri esattamente come li ha inviati l’agente
Streaming intatto
I chunk vengono inoltrati appena arrivano, quindi l’agente si comporta normalmente
Nessuna dipendenza
Un solo file, Node.js 18 o successivo, niente da installare
Come funziona
Authorization, quindi la tua chiave API resta nella configurazione dell’agente e ogni endpoint di Venice funziona attraverso il proxy: /chat/completions, /responses, /models, /embeddings e tutti gli altri. L’unica modifica da fare all’agente è l’URL di base.
Per ogni richiesta, il proxy registra:
- Il metodo, il percorso e il corpo della richiesta, con la tua chiave API mascherata tranne gli ultimi quattro caratteri
- Lo stato e il corpo della risposta. Le risposte in streaming vengono salvate come elenco di chunk analizzati.
- L’utilizzo dei token, dall’oggetto
usagerestituito da Venice - La durata totale e il tempo al primo byte
- Gli header di risposta
x-venice-*ex-ratelimit-*, come il saldo residuo, lo stato del rate limit e gli avvisi di deprecazione dei modelli
Questo è uno strumento di debug per la tua macchina. Ascolta solo su
127.0.0.1, non ha un’autenticazione propria e scrive prompt e codice su disco in chiaro. Non distribuirlo come gateway condiviso. Se te ne serve uno, consulta Costruire un gateway LLM in Rust.Prerequisiti
- Node.js 18 o successivo (
node --version) - Una chiave API di Venice da venice.ai/settings/api
- Un agente di programmazione che funzioni già con Venice, come Claude Code, Codex CLI, OpenCode, Cline o Aider
jqper leggere i log (facoltativo, ma consigliato)
Configurazione
1
Crea il proxy
Salva questo file come Ci sono alcune cose che vale la pena sottolineare:
venice-debug-proxy.mjs in una directory temporanea:venice-debug-proxy.mjs
- Lo streaming funziona normalmente. Ogni chunk di Venice viene scritto verso l’agente appena arriva, e una copia viene conservata per il log. L’agente vede lo stesso flusso token per token che riceverebbe direttamente da Venice.
- La compressione è gestita per te. Il
fetchdi Node decomprime la risposta, quindi il proxy rimuovecontent-encodingprima di inoltrare gli header. Altrimenti l’agente proverebbe a decomprimere testo in chiaro e fallirebbe. - Le disconnessioni vengono propagate. Se annulli un turno nell’agente, il proxy interrompe anche la richiesta upstream, così Venice non continua a generare token che nessuno legge.
2
Avvialo
PORT o LOG_FILE nell’ambiente per cambiare uno dei due valori predefiniti.3
Verificalo con curl
In un secondo terminale, invia una richiesta tramite il proxy:Il proxy stampa una riga per ogni richiesta:Sono molti token di prompt per “Say hello”. La maggior parte proviene dal prompt di sistema predefinito di Venice, che viene aggiunto alle richieste di chat a meno che tu non imposti
venice_parameters.include_venice_system_prompt su false. È proprio questo il tipo di cosa che il proxy rende visibile.4
Punta l'agente al proxy
Nelle impostazioni di Venice del tuo agente, sostituisci
https://api.venice.ai con http://127.0.0.1:8787 e lascia invariato il resto dell’URL. Il proxy inoltra il percorso completo, quindi qualunque valore indicato dalla guida dell’agente continua a funzionare.Il provider Venice integrato in OpenCode e il provider Venice nativo di Kilo Code non espongono un URL di base, quindi durante il debug passa al provider manuale o compatibile con OpenAI.In OpenCode, assegna al provider di debug un ID proprio, come
venice-debug, ed eseguilo con -m venice-debug/<model-id>. Se hai salvato una chiave con /connect, OpenCode invia quella chiave salvata per l’ID provider venice anche quando la tua configurazione imposta apiKey.Usa 127.0.0.1 invece di localhost. Su alcuni sistemi localhost si risolve nell’indirizzo IPv6 ::1, su cui il proxy non è in ascolto.5
Riproduci il problema
Usa l’agente come fai di solito finché il problema non si ripresenta, poi controlla l’output del proxy nel terminale e il file di log.
Leggere i log
Ogni riga divenice-debug.jsonl è un oggetto JSON completo, quindi jq può analizzarla come preferisci.
Mostra la richiesta e la risposta più recenti:
Cosa cercare
Senza scrivere codice
Se preferisci esplorare il traffico con un browser, mitmproxy può funzionare come reverse proxy davanti a Venice:http://127.0.0.1:8787/api/v1 nello stesso modo, poi ispeziona ogni richiesta nell’interfaccia di mitmweb. Il proxy Node è più facile da automatizzare con script e conserva un log che puoi cercare con grep in seguito. mitmproxy è più adatto per esplorare una sessione in modo interattivo.
Mantieni privati i log
Venice non memorizza i tuoi prompt né le tue risposte per l’inferenza normale (vedi Privacy), ma questo file di log sì. Contiene il tuo codice, i prompt, l’output degli strumenti e le risposte del modello in chiaro.- Esegui il proxy fuori dal tuo progetto, oppure aggiungi
venice-debug.jsonla.gitignore. - Elimina il log quando hai finito il debug.
- Non incollare voci di log complete in issue pubbliche. Estrai invece
status,errore la parte rilevante diresponse.
Per concludere
Quando hai finito, arresta il proxy conCtrl+C e reimposta l’URL di base dell’agente su https://api.venice.ai/api/v1. Se te ne dimentichi, l’agente fallirà con un errore di connessione non appena il proxy non sarà in esecuzione, il che almeno è facile da notare.
Grazie per aver letto! Speriamo che la prossima volta che un agente dice “something went wrong”, tu possa vedere esattamente cosa è andato storto.