Pular para o conteúdo principal
Quando um agente de programação se comporta mal, a interface dele raramente diz por quê. Uma chamada de ferramenta silenciosamente não faz nada, uma requisição falha com “provider error”, o modelo ignora seu prompt de sistema ou uma sessão curta custa muito mais do que você esperava. Na maioria das vezes, a resposta está no tráfego HTTP entre o agente e a Venice, que normalmente você não consegue ver. Neste guia, vamos executar um pequeno proxy na sua própria máquina, posicionado entre o agente e a API da Venice. O agente conversa com o proxy, o proxy encaminha tudo para a Venice sem alterações, e cada requisição e resposta é gravada em um arquivo de log local que você pode consultar com 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

O proxy encaminha o caminho completo e seu cabeçalho 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 usage que a Venice retorna
  • A duração total e o tempo até o primeiro byte
  • Os cabeçalhos de resposta x-venice-* e x-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


Configuração

1

Crie o proxy

Salve isto como venice-debug-proxy.mjs em um diretório temporário:
venice-debug-proxy.mjs
Vale destacar alguns pontos:
  • 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 fetch do Node descomprime a resposta, então o proxy remove content-encoding antes 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

Você deve ver:
Defina 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.
Isso não funciona com o Cursor. O Cursor envia requisições de modelos personalizados a partir dos próprios servidores, que não conseguem alcançar um proxy na sua máquina.
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 de venice-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:
Mostre apenas requisições com falha ou interrompidas:
Verifique qual modelo, parâmetros e ferramentas o agente realmente enviou:
Reconstrua o texto de chat completions em streaming:
Total de tokens por modelo na sessão:
Encontre as requisições mais lentas:

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:
Aponte o agente para 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.jsonl ao .gitignore.
  • Apague o log quando terminar de depurar.
  • Não cole entradas completas do log em issues públicas. Extraia em vez disso status, error e a parte relevante de response.
Para modelos E2EE, o agente criptografa o conteúdo das mensagens antes que ele saia da sua máquina, então o log mostrará payloads criptografados em vez de texto legível.

Finalizando

Quando terminar, pare o proxy com Ctrl+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.