Passer au contenu principal
Quand un agent de code se comporte mal, son interface vous dit rarement pourquoi. Un appel d’outil ne fait rien sans prévenir, une requête échoue avec “provider error”, le modèle ignore votre prompt système, ou une courte session coûte bien plus que prévu. La plupart du temps, la réponse se trouve dans le trafic HTTP entre l’agent et Venice, que vous ne voyez normalement pas. Dans ce guide, nous allons exécuter un petit proxy sur votre propre machine, placé entre l’agent et l’API Venice. L’agent parle au proxy, le proxy transmet tout à Venice sans modification, et chaque requête et réponse est écrite dans un fichier journal local que vous pouvez interroger avec jq.

Voir la vraie requête

ID du modèle, messages, outils et paramètres exactement tels que l’agent les a envoyés

Streaming préservé

Les fragments sont transmis dès leur arrivée, donc l’agent se comporte normalement

Aucune dépendance

Un seul fichier, Node.js 18 ou ultérieur, rien à installer

Fonctionnement

Le proxy transmet le chemin complet et votre en-tête Authorization, donc votre clé API reste dans la configuration de l’agent et tous les endpoints Venice fonctionnent à travers lui : /chat/completions, /responses, /models, /embeddings et les autres. Le seul changement à apporter à l’agent est l’URL de base. Pour chaque requête, le proxy journalise :
  • La méthode, le chemin et le corps de la requête, avec votre clé API masquée sauf ses quatre derniers caractères
  • Le statut et le corps de la réponse. Les réponses en streaming sont stockées sous forme de liste de fragments analysés.
  • L’utilisation des tokens, à partir de l’objet usage renvoyé par Venice
  • La durée totale et le temps jusqu’au premier octet
  • Les en-têtes de réponse x-venice-* et x-ratelimit-*, comme le solde restant, l’état de la limite de débit et les avertissements de dépréciation de modèle
Il s’agit d’un outil de débogage pour votre propre machine. Il n’écoute que sur 127.0.0.1, n’a aucune authentification propre et écrit les prompts et le code sur le disque en texte brut. Ne le déployez pas comme gateway partagé. Si vous en avez besoin d’un, consultez Créer une passerelle LLM en Rust.

Prérequis


Configuration

1

Créer le proxy

Enregistrez ceci sous venice-debug-proxy.mjs dans un répertoire de travail temporaire :
venice-debug-proxy.mjs
Quelques points méritent d’être soulignés :
  • Le streaming fonctionne normalement. Chaque fragment reçu de Venice est écrit vers l’agent dès son arrivée, et une copie est conservée pour le journal. L’agent voit le même flux token par token que s’il interrogeait Venice directement.
  • La compression est gérée pour vous. Le fetch de Node décompresse la réponse, donc le proxy supprime content-encoding avant de transmettre les en-têtes. Sinon, l’agent essaierait de décompresser du texte brut et échouerait.
  • Les déconnexions sont propagées. Si vous annulez un tour dans l’agent, le proxy interrompt aussi la requête upstream, afin que Venice ne continue pas à générer des tokens que personne ne lit.
2

Le démarrer

Vous devriez voir :
Définissez PORT ou LOG_FILE dans l’environnement pour modifier l’une ou l’autre valeur par défaut.
3

Le vérifier avec curl

Dans un second terminal, envoyez une requête via le proxy :
Le proxy affiche une ligne par requête :
Cela fait beaucoup de tokens de prompt pour “Say hello”. La plupart proviennent du prompt système par défaut de Venice, ajouté aux requêtes de chat sauf si vous définissez venice_parameters.include_venice_system_prompt sur false. C’est exactement le genre de chose que le proxy rend visible.
4

Faire pointer votre agent vers le proxy

Dans les paramètres Venice de votre agent, remplacez https://api.venice.ai par http://127.0.0.1:8787 et gardez le reste de l’URL tel quel. Le proxy transmet le chemin complet, donc ce que le guide de l’agent vous indique de saisir fonctionne toujours.Le fournisseur Venice intégré à OpenCode et le fournisseur Venice natif de Kilo Code n’exposent pas d’URL de base : passez donc au fournisseur manuel ou compatible OpenAI pendant le débogage.Dans OpenCode, donnez au fournisseur de débogage son propre ID, par exemple venice-debug, et lancez-le avec -m venice-debug/<model-id>. Si vous avez enregistré une clé avec /connect, OpenCode envoie cette clé stockée pour l’ID de fournisseur venice, même lorsque votre configuration définit apiKey.Utilisez 127.0.0.1 plutôt que localhost. Sur certains systèmes, localhost se résout vers l’adresse IPv6 ::1, sur laquelle le proxy n’écoute pas.
Cela ne fonctionne pas avec Cursor. Cursor envoie les requêtes des modèles personnalisés depuis ses propres serveurs, qui ne peuvent pas atteindre un proxy sur votre machine.
5

Reproduire le problème

Utilisez l’agent comme d’habitude jusqu’à ce que le problème se reproduise, puis consultez la sortie du proxy dans le terminal et le fichier journal.

Lire les journaux

Chaque ligne de venice-debug.jsonl est un objet JSON complet, donc jq peut le découper comme vous le souhaitez. Afficher la requête et la réponse les plus récentes :
Afficher uniquement les requêtes en échec ou interrompues :
Vérifier quels modèle, paramètres et outils l’agent a réellement envoyés :
Reconstituer le texte des chat completions en streaming :
Total des tokens par modèle pour la session :
Trouver les requêtes les plus lentes :

Ce qu’il faut rechercher


Sans écrire de code

Si vous préférez parcourir le trafic en cliquant dans un navigateur, mitmproxy peut fonctionner comme proxy inverse devant Venice :
Faites pointer l’agent vers http://127.0.0.1:8787/api/v1 de la même façon, puis inspectez chaque requête dans l’interface mitmweb. Le proxy Node est plus facile à scripter et conserve un journal que vous pouvez parcourir avec grep plus tard. mitmproxy convient mieux pour explorer une session de manière interactive.

Garder les journaux privés

Venice ne stocke pas vos prompts ni vos réponses pour l’inférence normale (voir Confidentialité), mais ce fichier journal, si. Il contient votre code, vos prompts, la sortie des outils et les réponses du modèle en texte brut.
  • Exécutez le proxy en dehors de votre projet, ou ajoutez venice-debug.jsonl à .gitignore.
  • Supprimez le journal une fois le débogage terminé.
  • Ne collez pas d’entrées complètes du journal dans des issues publiques. Extrayez plutôt status, error et la partie pertinente de response.
Pour les modèles E2EE, l’agent chiffre le contenu des messages avant qu’il ne quitte votre machine, donc le journal affichera des charges utiles chiffrées plutôt que du texte lisible.

Pour finir

Lorsque vous avez terminé, arrêtez le proxy avec Ctrl+C et remettez l’URL de base de l’agent sur https://api.venice.ai/api/v1. Si vous oubliez, l’agent échouera avec une erreur de connexion dès que le proxy ne tournera plus, ce qui a au moins le mérite d’être facile à repérer. Merci de votre lecture ! La prochaine fois qu’un agent dira “something went wrong”, vous pourrez, on l’espère, voir exactement ce qui s’est mal passé.