跳转到主要内容
当编程智能体出现异常时,它的界面很少告诉你原因。工具调用悄无声息地什么也没做,请求以 “provider error” 失败,模型忽略了你的系统提示词,或者一次很短的会话花费远超预期。大多数时候,答案就藏在智能体与 Venice 之间的 HTTP 流量里,而这些流量你通常看不到。 在本指南中,我们将在你自己的机器上运行一个小型代理,让它位于智能体和 Venice API 之间。智能体与代理通信,代理将所有内容原样转发给 Venice,每个请求和响应都会写入一个本地日志文件,你可以用 jq 查询它。

查看真实请求

模型 ID、消息、工具和参数,与智能体发送时完全一致

流式传输不受影响

数据块一到达就立即转发,因此智能体行为正常

无依赖

单个文件,Node.js 18 或更高版本,无需安装任何东西

工作原理

代理会转发完整路径和你的 Authorization 请求头,因此你的 API 密钥保留在智能体的配置中,所有 Venice 端点都可以通过它工作:/chat/completions、/responses、/models、/embeddings 等。你只需要修改智能体的 base URL。 对于每个请求,代理会记录:
  • 方法、路径和请求体,你的 API 密钥会被遮盖,只保留最后四个字符
  • 响应状态和响应体。流式响应会以解析后的数据块列表形式存储。
  • token 用量,来自 Venice 返回的 usage 对象
  • 总耗时和首字节时间
  • x-venice-* 和 x-ratelimit-* 响应头,例如剩余余额、速率限制状态和模型弃用警告
这是一个用于你自己机器的调试工具。它只绑定到 127.0.0.1,没有自己的身份验证,并以明文将提示词和代码写入磁盘。不要把它部署为共享网关。如果你需要网关,请参阅构建一个 Rust LLM 网关。

前提条件


设置

1

创建代理

将以下内容保存为临时目录中的 venice-debug-proxy.mjs:
venice-debug-proxy.mjs
这里有几点值得指出:
  • 流式传输正常工作。 来自 Venice 的每个数据块一到达就立即写给智能体,同时保留一份副本用于日志。智能体看到的逐 token 流与直接从 Venice 获取的完全相同。
  • 压缩已为你处理。 Node 的 fetch 会解压响应,因此代理在转发响应头之前会删除 content-encoding。否则智能体会尝试解压纯文本并失败。
  • 断开连接会被传递。 如果你在智能体中取消一轮对话,代理也会中止上游请求,这样 Venice 就不会继续生成没人读取的 token。
2

启动代理

你应该会看到:
在环境中设置 PORT 或 LOG_FILE 可以更改相应的默认值。
3

用 curl 检查

在第二个终端中,通过代理发送一个请求:
代理会为每个请求打印一行:
对 “Say hello” 来说,这些提示词 token 太多了。其中大部分是 Venice 的默认系统提示词,除非你将 venice_parameters.include_venice_system_prompt 设置为 false,否则它会被添加到聊天请求中。这正是代理能让你看到的那类问题。
4

将智能体指向代理

在智能体的 Venice 设置中,将 https://api.venice.ai 替换为 http://127.0.0.1:8787,URL 的其余部分保持不变。代理会转发完整路径,因此智能体指南中让你填写的内容仍然有效。OpenCode 内置的 Venice 提供商和 Kilo Code 的原生 Venice 提供商都不提供 base URL 设置,因此调试时请切换到手动提供商或 OpenAI 兼容提供商。在 OpenCode 中,为调试提供商设置一个独立的 ID,例如 venice-debug,并使用 -m venice-debug/<model-id> 运行。如果你曾通过 /connect 保存过密钥,即使配置中设置了 apiKey,OpenCode 仍会为 venice 提供商 ID 发送该已保存的密钥。请使用 127.0.0.1 而不是 localhost。在某些系统上,localhost 会解析为 IPv6 地址 ::1,而代理并未在该地址上监听。
这不适用于 Cursor。Cursor 从它自己的服务器发送自定义模型请求,这些服务器无法访问你机器上的代理。
5

复现问题

像平常一样使用智能体,直到问题再次出现,然后查看代理的终端输出和日志文件。

读取日志

venice-debug.jsonl 中的每一行都是一个完整的 JSON 对象,因此你可以用 jq 按需切分。 显示最近的请求和响应:
只显示失败或中断的请求:
检查智能体实际发送的模型、参数和工具:
重建流式 chat completions 的文本:
统计会话中每个模型的 token 总量:
找出最慢的请求:

需要关注什么


无需编写任何代码

如果你更想在浏览器中点击查看流量,可以让 mitmproxy 作为反向代理运行在 Venice 前面:
用同样的方式将智能体指向 http://127.0.0.1:8787/api/v1,然后在 mitmweb 界面中检查每个请求。Node 代理更容易用脚本处理,并会保留一份日志供你之后用 grep 搜索。mitmproxy 更适合交互式地浏览一次会话。

保护日志隐私

Venice 在常规推理中不会存储你的提示词或响应(参阅隐私),但这个日志文件会。它以明文形式包含你的代码、提示词、工具输出和模型响应。
  • 在项目之外运行代理,或将 venice-debug.jsonl 添加到 .gitignore。
  • 调试完成后删除日志。
  • 不要把完整的日志条目粘贴到公开 issue 中。只提取 status、error 和 response 中的相关部分。
对于 E2EE 模型,智能体会在消息内容离开你的机器之前对其进行加密,因此日志中显示的是加密的负载,而不是可读文本。

收尾

完成后,用 Ctrl+C 停止代理,并将智能体的 base URL 改回 https://api.venice.ai/api/v1。如果你忘了,只要代理没有运行,智能体就会因连接错误而失败,至少这很容易发现。 感谢阅读!希望下次智能体提示 “something went wrong” 时,你能准确看到究竟哪里出了问题。