jq.
Veja a requisição real
ID do modelo, mensagens, ferramentas e parâmetros exatamente como o agente os enviou
Streaming intacto
Os chunks são encaminhados assim que chegam, então o agente se comporta normalmente
Sem dependências
Um único arquivo, Node.js 18 ou posterior, nada para instalar
Como funciona
Authorization, então sua chave de API permanece na configuração do agente e todos os endpoints da Venice funcionam através dele: /chat/completions, /responses, /models, /embeddings e os demais. A única mudança que você faz no agente é a URL base.
Para cada requisição, o proxy registra:
- O método, o caminho e o corpo da requisição, com sua chave de API mascarada exceto pelos últimos quatro caracteres
- O status e o corpo da resposta. Respostas em streaming são armazenadas como uma lista de chunks analisados.
- O uso de tokens, a partir do objeto
usageque a Venice retorna - A duração total e o tempo até o primeiro byte
- Os cabeçalhos de resposta
x-venice-*ex-ratelimit-*, como saldo restante, estado do limite de taxa e avisos de descontinuação de modelos
Esta é uma ferramenta de depuração para a sua própria máquina. Ela escuta apenas em
127.0.0.1, não tem autenticação própria e grava prompts e código em disco em texto simples. Não a implante como um gateway compartilhado. Se você precisar de um, veja Construindo um Gateway LLM em Rust.Pré-requisitos
- Node.js 18 ou posterior (
node --version) - Uma chave de API da Venice em venice.ai/settings/api
- Um agente de programação que já funcione com a Venice, como Claude Code, Codex CLI, OpenCode, Cline ou Aider
jqpara ler os logs (opcional, mas recomendado)
Configuração
1
Crie o proxy
Salve isto como Vale destacar alguns pontos:
venice-debug-proxy.mjs em um diretório temporário:venice-debug-proxy.mjs
- O streaming funciona normalmente. Cada chunk da Venice é enviado ao agente no momento em que chega, e uma cópia é guardada para o log. O agente vê o mesmo fluxo token a token que receberia diretamente da Venice.
- A compressão é tratada para você. O
fetchdo Node descomprime a resposta, então o proxy removecontent-encodingantes de repassar os cabeçalhos. Caso contrário, o agente tentaria descomprimir texto simples e falharia. - Desconexões são repassadas. Se você cancelar um turno no agente, o proxy também aborta a requisição upstream, para que a Venice não continue gerando tokens que ninguém lê.
2
Inicie-o
PORT ou LOG_FILE no ambiente para alterar qualquer um dos padrões.3
Verifique com curl
Em um segundo terminal, envie uma requisição pelo proxy:O proxy imprime uma linha por requisição:São muitos tokens de prompt para “Say hello”. A maioria vem do prompt de sistema padrão da Venice, que é adicionado às requisições de chat, a menos que você defina
venice_parameters.include_venice_system_prompt como false. É exatamente esse tipo de coisa que o proxy torna visível.4
Aponte seu agente para o proxy
Nas configurações da Venice do seu agente, substitua
https://api.venice.ai por http://127.0.0.1:8787 e mantenha o restante da URL como está. O proxy encaminha o caminho completo, então o que o guia do agente manda você inserir continua funcionando.O provedor Venice incluído no OpenCode e o provedor Venice nativo do Kilo Code não expõem uma URL base, então mude para o provedor manual ou compatível com OpenAI enquanto depura.No OpenCode, dê ao provedor de depuração um ID próprio, como
venice-debug, e execute-o com -m venice-debug/<model-id>. Se você salvou uma chave com /connect, o OpenCode envia essa chave armazenada para o ID de provedor venice, mesmo quando sua configuração define apiKey.Use 127.0.0.1 em vez de localhost. Em alguns sistemas, localhost resolve para o endereço IPv6 ::1, no qual o proxy não está escutando.5
Reproduza o problema
Use o agente normalmente até o problema acontecer de novo e, em seguida, veja a saída do proxy no terminal e o arquivo de log.
Lendo os logs
Cada linha devenice-debug.jsonl é um objeto JSON completo, então o jq pode recortá-lo como você precisar.
Mostre a requisição e a resposta mais recentes:
O que procurar
Sem escrever código
Se você prefere navegar pelo tráfego clicando em um navegador, o mitmproxy pode funcionar como proxy reverso na frente da Venice:http://127.0.0.1:8787/api/v1 da mesma forma e depois inspecione cada requisição na interface do mitmweb. O proxy Node é mais fácil de automatizar com scripts e mantém um log que você pode pesquisar com grep depois. O mitmproxy é melhor para explorar uma sessão de forma interativa.
Mantenha os logs privados
A Venice não armazena seus prompts nem respostas na inferência normal (veja Privacidade), mas este arquivo de log armazena. Ele contém seu código, prompts, saída de ferramentas e respostas do modelo em texto simples.- Execute o proxy fora do seu projeto ou adicione
venice-debug.jsonlao.gitignore. - Apague o log quando terminar de depurar.
- Não cole entradas completas do log em issues públicas. Extraia em vez disso
status,errore a parte relevante deresponse.
Finalizando
Quando terminar, pare o proxy comCtrl+C e volte a URL base do agente para https://api.venice.ai/api/v1. Se você esquecer, o agente falhará com um erro de conexão assim que o proxy não estiver em execução, o que pelo menos é fácil de perceber.
Obrigado pela leitura! Esperamos que, na próxima vez que um agente disser “something went wrong”, você consiga ver exatamente o que deu errado.