Zum Hauptinhalt springen
Wenn sich ein Coding-Agent seltsam verhält, verrät Ihnen seine Oberfläche selten, warum. Ein Tool-Aufruf bewirkt stillschweigend nichts, eine Anfrage scheitert mit “provider error”, das Modell ignoriert Ihren System-Prompt, oder eine kurze Sitzung kostet weit mehr als erwartet. Meist steckt die Antwort im HTTP-Verkehr zwischen dem Agenten und Venice, den Sie normalerweise nicht sehen. In dieser Anleitung betreiben wir einen kleinen Proxy auf Ihrem eigenen Rechner, der zwischen dem Agenten und der Venice API sitzt. Der Agent spricht mit dem Proxy, der Proxy leitet alles unverändert an Venice weiter, und jede Anfrage und Antwort wird in eine lokale Logdatei geschrieben, die Sie mit jq durchsuchen können.

Die echte Anfrage sehen

Modell-ID, Nachrichten, Tools und Parameter genau so, wie der Agent sie gesendet hat

Streaming bleibt intakt

Chunks werden beim Eintreffen weitergeleitet, sodass sich der Agent normal verhält

Keine Abhängigkeiten

Eine Datei, Node.js 18 oder neuer, nichts zu installieren

So funktioniert es

Der Proxy leitet den vollständigen Pfad und Ihren Authorization-Header weiter. Ihr API-Schlüssel bleibt also in der Konfiguration des Agenten, und jeder Venice-Endpoint funktioniert über den Proxy: /chat/completions, /responses, /models, /embeddings und alle anderen. Die einzige Änderung am Agenten ist die Basis-URL. Für jede Anfrage protokolliert der Proxy:
  • Methode, Pfad und Anfrage-Body, wobei Ihr API-Schlüssel bis auf die letzten vier Zeichen maskiert wird
  • Status und Body der Antwort. Gestreamte Antworten werden als Liste geparster Chunks gespeichert.
  • Token-Verbrauch aus dem usage-Objekt, das Venice zurückgibt
  • Gesamtdauer und Zeit bis zum ersten Byte
  • Die Antwort-Header x-venice-* und x-ratelimit-*, etwa verbleibendes Guthaben, Rate-Limit-Status und Hinweise zur Modell-Abkündigung
Dies ist ein Debugging-Werkzeug für Ihren eigenen Rechner. Es lauscht nur auf 127.0.0.1, hat keine eigene Authentifizierung und schreibt Prompts und Code im Klartext auf die Festplatte. Setzen Sie es nicht als gemeinsam genutztes Gateway ein. Wenn Sie eines brauchen, lesen Sie Ein Rust-LLM-Gateway bauen.

Voraussetzungen


Einrichtung

1

Proxy erstellen

Speichern Sie Folgendes als venice-debug-proxy.mjs in einem temporären Verzeichnis:
venice-debug-proxy.mjs
Einige Punkte sind hier erwähnenswert:
  • Streaming funktioniert normal. Jeder Chunk von Venice wird sofort beim Eintreffen an den Agenten geschrieben, und eine Kopie wird für das Log aufbewahrt. Der Agent sieht denselben Token-für-Token-Stream, den er direkt von Venice erhalten würde.
  • Um die Komprimierung müssen Sie sich nicht kümmern. Das fetch von Node dekomprimiert die Antwort, daher entfernt der Proxy content-encoding, bevor er die Header weitergibt. Andernfalls würde der Agent versuchen, Klartext zu dekomprimieren, und scheitern.
  • Verbindungsabbrüche werden weitergegeben. Wenn Sie einen Turn im Agenten abbrechen, bricht der Proxy auch die Upstream-Anfrage ab, damit Venice keine Tokens weitergeneriert, die niemand liest.
2

Proxy starten

Sie sollten Folgendes sehen:
Setzen Sie PORT oder LOG_FILE in der Umgebung, um den jeweiligen Standardwert zu ändern.
3

Mit curl prüfen

Senden Sie in einem zweiten Terminal eine Anfrage über den Proxy:
Der Proxy gibt eine Zeile pro Anfrage aus:
Das sind viele Prompt-Tokens für “Say hello”. Die meisten davon stammen aus dem Standard-System-Prompt von Venice, der Chat-Anfragen hinzugefügt wird, sofern Sie venice_parameters.include_venice_system_prompt nicht auf false setzen. Genau solche Dinge macht der Proxy sichtbar.
4

Agenten auf den Proxy umstellen

Ersetzen Sie in den Venice-Einstellungen Ihres Agenten https://api.venice.ai durch http://127.0.0.1:8787 und lassen Sie den Rest der URL unverändert. Der Proxy leitet den vollständigen Pfad weiter, daher funktioniert weiterhin, was die Anleitung des Agenten Ihnen vorgibt.Der mitgelieferte Venice-Provider von OpenCode und der native Venice-Provider von Kilo Code bieten keine Basis-URL an. Wechseln Sie daher beim Debuggen zum manuellen bzw. OpenAI-kompatiblen Provider.Geben Sie in OpenCode dem Debug-Provider eine eigene ID, etwa venice-debug, und starten Sie ihn mit -m venice-debug/<model-id>. Wenn Sie einen Schlüssel mit /connect gespeichert haben, sendet OpenCode diesen gespeicherten Schlüssel für die Provider-ID venice, auch wenn Ihre Konfiguration apiKey setzt.Verwenden Sie 127.0.0.1 statt localhost. Auf manchen Systemen wird localhost zur IPv6-Adresse ::1 aufgelöst, auf der der Proxy nicht lauscht.
Mit Cursor funktioniert das nicht. Cursor sendet Anfragen für benutzerdefinierte Modelle von seinen eigenen Servern, die einen Proxy auf Ihrem Rechner nicht erreichen können.
5

Problem reproduzieren

Nutzen Sie den Agenten wie gewohnt, bis das Problem erneut auftritt. Sehen Sie sich dann die Terminal-Ausgabe des Proxys und die Logdatei an.

Logs lesen

Jede Zeile in venice-debug.jsonl ist ein vollständiges JSON-Objekt, sodass jq sie beliebig zerlegen kann. Die letzte Anfrage und Antwort anzeigen:
Nur fehlgeschlagene oder abgebrochene Anfragen anzeigen:
Prüfen, welches Modell, welche Parameter und welche Tools der Agent tatsächlich gesendet hat:
Den Text gestreamter Chat Completions rekonstruieren:
Tokens pro Modell für die Sitzung summieren:
Die langsamsten Anfragen finden:

Worauf Sie achten sollten


Ganz ohne Code

Wenn Sie den Verkehr lieber im Browser durchklicken möchten, kann mitmproxy als Reverse Proxy vor Venice laufen:
Stellen Sie den Agenten auf dieselbe Weise auf http://127.0.0.1:8787/api/v1 um und untersuchen Sie dann jede Anfrage in der mitmweb-Oberfläche. Der Node-Proxy lässt sich leichter skripten und hinterlässt ein Log, das Sie später mit grep durchsuchen können. mitmproxy eignet sich besser, um eine Sitzung interaktiv zu durchstöbern.

Logs privat halten

Venice speichert Ihre Prompts und Antworten bei normaler Inferenz nicht (siehe Datenschutz), diese Logdatei aber schon. Sie enthält Ihren Code, Ihre Prompts, Tool-Ausgaben und Modellantworten im Klartext.
  • Führen Sie den Proxy außerhalb Ihres Projekts aus, oder fügen Sie venice-debug.jsonl zur .gitignore hinzu.
  • Löschen Sie das Log, wenn Sie mit dem Debuggen fertig sind.
  • Fügen Sie keine vollständigen Log-Einträge in öffentliche Issues ein. Ziehen Sie stattdessen status, error und den relevanten Teil von response heraus.
Bei E2EE-Modellen verschlüsselt der Agent die Nachrichteninhalte, bevor sie Ihren Rechner verlassen. Das Log zeigt daher verschlüsselte Payloads statt lesbarem Text.

Abschluss

Wenn Sie fertig sind, beenden Sie den Proxy mit Ctrl+C und stellen Sie die Basis-URL des Agenten wieder auf https://api.venice.ai/api/v1 zurück. Wenn Sie das vergessen, scheitert der Agent mit einem Verbindungsfehler, sobald der Proxy nicht läuft, was immerhin leicht zu erkennen ist. Danke fürs Lesen! Hoffentlich können Sie das nächste Mal, wenn ein Agent “something went wrong” meldet, genau sehen, was schiefgelaufen ist.