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 网关。前提条件
- Node.js 18 或更高版本(
node --version) - 来自 venice.ai/settings/api 的 Venice API 密钥
- 一个已经能与 Venice 配合使用的编程智能体,例如 Claude Code、Codex CLI、OpenCode、Cline 或 Aider
- 用于读取日志的
jq(可选,但推荐)
设置
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,而代理并未在该地址上监听。5
复现问题
像平常一样使用智能体,直到问题再次出现,然后查看代理的终端输出和日志文件。
读取日志
venice-debug.jsonl 中的每一行都是一个完整的 JSON 对象,因此你可以用 jq 按需切分。
显示最近的请求和响应:
需要关注什么
无需编写任何代码
如果你更想在浏览器中点击查看流量,可以让 mitmproxy 作为反向代理运行在 Venice 前面:http://127.0.0.1:8787/api/v1,然后在 mitmweb 界面中检查每个请求。Node 代理更容易用脚本处理,并会保留一份日志供你之后用 grep 搜索。mitmproxy 更适合交互式地浏览一次会话。
保护日志隐私
Venice 在常规推理中不会存储你的提示词或响应(参阅隐私),但这个日志文件会。它以明文形式包含你的代码、提示词、工具输出和模型响应。- 在项目之外运行代理,或将
venice-debug.jsonl添加到.gitignore。 - 调试完成后删除日志。
- 不要把完整的日志条目粘贴到公开 issue 中。只提取
status、error和response中的相关部分。
收尾
完成后,用Ctrl+C 停止代理,并将智能体的 base URL 改回 https://api.venice.ai/api/v1。如果你忘了,只要代理没有运行,智能体就会因连接错误而失败,至少这很容易发现。
感谢阅读!希望下次智能体提示 “something went wrong” 时,你能准确看到究竟哪里出了问题。