透视每一个请求：OpenRouter ai-sdk-provider调试模式echo_upstream

【免费下载链接】ai-sdk-provider

The OpenRouter provider for the Vercel AI SDK contains support for hundreds of models through the OpenRouter chat and completion APIs.

项目地址：https://gitcode.com/gh_mirrors/ai/ai-sdk-provider

点击查看免费下载

在使用ai-sdk-provider（Vercel AI SDK 的 OpenRouter 官方 provider）时，你是否遇到过这样的困惑：模型输出不符合预期，却不知道发给上游 provider 的请求体到底长什么样？本文带你实战debug.echo_upstream_body调试模式——只需一行配置，就能让 OpenRouter 把"最终发出去的请求体"原样回显给你，是排查 API 请求问题的利器。

🔍 什么是 echo_upstream_body 调试模式

OpenRouter 是连接你与数百个模型的"中间层"。你的请求在到达真实模型之前，会经过消息转换、参数映射、provider 路由等一系列处理。调试模式的作用是：把处理后发给上游 provider 的请求体，作为流式响应的第一个块回显给你。

它的核心特性如下：

特性	说明
配置方式	`debug: { echo_upstream_body: true }`，写在模型配置里
适用场景	仅流式请求（如`streamText`）有效
回显位置	流式响应的第一个 chunk，位于`debug.echo_upstream_body`字段
数据安全	用户 ID、base64 内容等敏感数据会被自动打码（redacted）

类型定义可以在这份源码中查看：src/types/openrouter-chat-settings.ts，注释里明确说明了"回显请求体并脱敏"的行为。

⚙️ 三步开启调试：从安装到看到回显

第 1 步：安装 provider

npm install @openrouter/ai-sdk-provider

当前版本线支持ai@^7.0.0，需要 Node.js 22+，详见 README.md 的安装说明。

第 2 步：在模型配置中打开 debug

import { createOpenRouter } from '@openrouter/ai-sdk-provider'; import { streamText } from 'ai'; const openrouter = createOpenRouter({ apiKey: 'your-api-key' }); const model = openrouter('anthropic/claude-3.5-sonnet', { debug: { echo_upstream_body: true, // 🎯 一行开启调试 }, });

这个配置会随请求一起发送。在 src/chat/index.ts 中可以看到，debug字段被直接并入发往 OpenRouter 的请求体。

第 3 步：用 streamText 发起流式请求，读取第一个块

const result = await streamText({ model, prompt: 'Hello, how are you?', }); for await (const chunk of result.fullStream) { // 第一个 debug chunk 的 choices 为空， // 数据在 debug.echo_upstream_body 字段中 console.log(chunk); }

调试块的特征是：choices 为空数组，同时携带debug.echo_upstream_body字段。官方示例可参考 README.md。

📦 回显内容长什么样

以测试用例 src/chat/index.test.ts 为例，开启调试后，实际发往 OpenRouter 的请求体大致如下：

{ "stream": true, "stream_options": { "include_usage": true }, "model": "anthropic/claude-3.5-sonnet", "messages": [{ "role": "user", "content": "Hello" }], "debug": { "echo_upstream_body": true } }

通过对比"我写的参数"和"回显的参数"，你可以一眼看清：

消息转换结果：prompt经过 convert-to-openrouter-chat-messages.ts 转换后变成了什么结构；
参数是否生效：temperature、top_p、seed等有没有真正进入请求体；
工具与结构化输出：tools、response_format.json_schema的最终形态是否正确。

🕵️ 典型排查场景

场景一：参数"消失"了设置了temperature: 0.7但模型表现像没设？回显里没有这个字段，说明它根本没被传递——问题出在配置层而非模型层。

场景二：工具调用不触发把tools定义和tool_choice与回显逐字段比对，能确认 schema 是否在转换中被意外修改。

场景三：验证 provider 路由配合provider.order、provider.allow_fallbacks等路由配置（定义见 src/types/openrouter-chat-settings.ts），回显可帮你确认路由偏好是否正确发出。

💡 小贴士：虽然generateText（非流式）也会把debug参数随请求发出（见 src/chat/index.test.ts），但回显数据只在流式请求中返回。需要看回显时，请改用streamText。

✅ 使用注意事项与最佳实践

仅限流式请求：这是类型注释中写明的约束，非流式调用看不到回显；
放心看日志：敏感数据（user ID、base64 图片内容等）已被打码，但仍建议不要把生产流量长期挂在调试模式上；
用完即关：调试是排障工具而非日常开关，定位问题后记得移除debug配置；
组合排查：可与usage: { include: true }的用量统计功能配合，一边看请求体一边核对 token 消耗，用法见 README.md。