Roo Code 使用 Vercel AI Gateway 实战指南统一接入 100 模型、提示缓存与 BYOK 配置【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-CodeRoo Code 内置了名为vercel-ai-gateway的 API 提供商Provider通过它你可以使用一个 Vercel AI Gateway API Key 与一个统一端点即可访问来自 Anthropic、OpenAI、Google、Meta、Mistral 等多家厂商的数百个语言模型。本文以 apps/docs/docs/providers/vercel-ai-gateway.md 为骨架结合 Roo Code 仓库源码完整讲解 API Key 获取、Provider 配置、模型自动发现机制、提示缓存Prompt Caching的底层实现、温度参数与 BYOK 计费等实战要点让你在 Roo Code 中最大化发挥 Vercel AI Gateway 的价值。为什么选择 Vercel AI GatewayAI Gateway 的核心价值在于统一入口它把数百个模型收敛到一个单一 API 端点上层应用只需对接一套 OpenAI 兼容接口即可按需切换任意底层模型。除了模型汇聚它还提供预算与用量监控set budgets、monitor usage在 Vercel 控制台统一查看各模型的调用量、Token 消耗与费用负载均衡load-balance requests按权重在多模型/多上游之间分发请求故障回退manage fallbacks上游模型不可用时自动切换到备用模型。在 Roo Code 中接入 AI Gateway意味着同一个 Agent 会话可以自由切换不同厂商的模型而不需要为每家厂商单独申请 API Key、单独做 Provider 配置。文档原文见 vercel-ai-gateway.mdVercel 官方团队控制台、模型目录与文档链接在原文中有说明此处不再赘述。第一步获取 Vercel AI Gateway API Key使用 AI Gateway 需要一个 API Key 用于认证步骤如下登录 Vercel前往 Vercel 官网vercel.com完成注册或登录创建 Key进入 AI Gateway 标签页中的 API Key 页面创建一个新的 API Key复制保存复制生成的 API Key稍后粘贴到 Roo Code 中。在 Roo Code 的配置层面该 Key 对应设置项vercelAiGatewayApiKey类型为可选字符串见 packages/types/src/provider-settings.ts即 API Key 并非强制必填项——你可以在后续需要鉴权时再补全。第二步在 Roo Code 中配置 Vercel AI Gateway配置入口与普通 Provider 完全一致打开 Roo Code 设置点击 Roo Code 面板上的齿轮图标Codicon gear选择 Provider在 API Provider 下拉框中选择Vercel AI Gateway填入 API Key将上一步复制的 Key 粘贴到 Vercel AI Gateway API Key 输入框中选择模型在 Model 下拉框中选择你需要的模型。配置完成后Roo Code 会通过 OpenAI 兼容接口向https://ai-gateway.vercel.sh/v1发起请求。这一点在源码中可以直接验证src/api/providers/vercel-ai-gateway.ts 中的VercelAiGatewayHandler构造函数将baseURL固定为https://ai-gateway.vercel.sh/v1并使用options.vercelAiGatewayApiKey作为 API Key。单测 src/api/providers/tests/vercel-ai-gateway.spec.ts 还验证了客户端初始化时会带上默认请求头包括HTTP-Referer、X-Title: Roo Code以及形如RooCode/version的User-Agent便于网关侧识别调用来源。模型自动发现Roo Code 如何拉取数百个模型你不需要手工维护模型清单——Roo Code 会自动从 Vercel AI Gateway 的 API 拉取全部可用模型并实时填充到模型下拉框中。这背后的实现链路值得展开1. 模型清单抓取与解析抓取逻辑位于 src/api/providers/fetchers/vercel-ai-gateway.ts 的getVercelAiGatewayModels()请求https://ai-gateway.vercel.sh/v1/models返回模型列表使用 Zod schemavercelAiGatewayModelSchema对响应做运行时校验包含id、context_window、max_tokens、type、pricing等字段仅保留type language的语言模型参与对话推理图像模型如 DALL-E和 Embedding 模型会被过滤其中 Embedding 模型在 Roo Code 中由静态的embeddingModels.ts维护每个模型被转换为统一的ModelInfo结构maxTokens、contextWindow、supportsImages、supportsPromptCache、inputPrice、outputPrice、cacheWritesPrice、cacheReadsPrice、description。2. 双层缓存内存 磁盘模型清单不会每次都实时请求。缓存管理在 src/api/providers/fetchers/modelCache.ts 中实现内存缓存NodeCache实例stdTTL为 5 分钟磁盘缓存写入全局存储目录下的${provider}_models.json即vercel-ai-gateway_models.json供冷启动时同步读取避免启动时回退到硬编码默认值后台预刷新扩展激活后约 2 秒initializeModelCacheRefresh()会对无需 API Key 的公共 Provideropenrouter 与 vercel-ai-gateway静默执行refreshModels刷新间隔 500ms失败时静默降级、继续使用旧缓存见 modelCache.ts。需要说明的是模型清单拉取本身不需要 API Keyfetcher 未传递 key但实际发起对话请求时仍需有效的 API Key 完成鉴权。3. 能力标签视觉与工具调用从网关拉取到的模型其能力是否支持图片、是否支持工具调用无法完全从/models响应推断因此仓库用两组静态集合兜底定义在 packages/types/src/providers/vercel-ai-gateway.tsVERCEL_AI_GATEWAY_VISION_ONLY_MODELS仅支持视觉输入如anthropic/claude-3.5-haiku、google/gemini-2.0-flash-thinkingVERCEL_AI_GATEWAY_VISION_AND_TOOLS_MODELS同时支持视觉与工具调用如anthropic/claude-sonnet-4、openai/gpt-4o、google/gemini-2.5-pro、meta/llama-4-maverick、moonshotai/kimi-k2等。parseVercelAiGatewayModel()会合并这两组集合判断supportsImages。对应的 fetcher 单测覆盖了这两种分类的识别见 src/api/providers/fetchers/tests/vercel-ai-gateway.spec.ts。提示缓存Prompt Caching省钱的关键机制Vercel AI Gateway 对包括 Anthropic Claude 与 OpenAI GPT 在内的部分模型支持自动提示缓存频繁重复使用的系统提示与对话前缀会被缓存命中缓存时按远低于输入价的缓存读取价计费从而显著降低长期会话成本。Roo Code 侧的缓存处理分为“判定”与“注入”两个阶段阶段一判定模型是否支持缓存网关侧parseVercelAiGatewayModel中当模型定价同时包含input_cache_write与input_cache_read时supportsPromptCache被置为true见 fetchers/vercel-ai-gateway.ts。测试用例handles partial cache pricing证明只有写入、缺少读取价时同样判定为不支持缓存本地侧仓库维护了VERCEL_AI_GATEWAY_PROMPT_CACHING_MODELS集合见 packages/types/src/providers/vercel-ai-gateway.ts覆盖anthropic/claude-3.5-haiku、anthropic/claude-sonnet-4、anthropic/claude-opus-4.x、openai/gpt-4.1系列、openai/gpt-4o、openai/gpt-5系列、openai/o1/o3/o4-mini等模型。阶段二注入缓存断点cache breakpoints只有当模型 ∈ VERCEL_AI_GATEWAY_PROMPT_CACHING_MODELS且模型信息supportsPromptCache true时createMessage()才会调用addCacheBreakpoints()见 src/api/providers/vercel-ai-gateway.ts。断点注入逻辑实现在 src/api/transform/caching/vercel-ai-gateway.ts系统消息断点为第一条 system 消息附加cache_control: { type: ephemeral }保证系统提示始终处于缓存前缀中最近两条用户消息断点过滤出对话中最后两条非空 user 消息在其最后一个文本段text part上附加同样的cache_control: { type: ephemeral }。由于对话历史采用前缀匹配缓存断点标记在“最近的用户消息”上可以最大化缓存前缀的命中范围又不会让缓存无限增长。缓存的用量与费用回报流式响应的最后一个 chunk 会携带完整用量信息。VercelAiGatewayHandler扩展了 OpenAI 的CompletionUsage额外识别 Vercel 特有的cache_creation_input_tokens缓存写入 Token与cost字段并连同prompt_tokens_details.cached_tokens缓存读取 Token一起回传给 Roo Code 的用量统计见 src/api/providers/vercel-ai-gateway.ts。单测 vercel-ai-gateway.spec.ts 验证了这一行为cacheWriteTokens: 2、cacheReadTokens: 3、totalCost: 0.005会被原样汇总到 usage chunk。提示缓存是否真正生效、以何种价格计费取决于底层模型与网关侧的定价策略Roo Code 的作用是把缓存断点和用量数据正确传递出去。温度参数与请求体细节文档明确默认温度为0.7且可按模型配置。这一默认值在源码中定义为常量VERCEL_AI_GATEWAY_DEFAULT_TEMPERATURE 0.7见 packages/types/src/providers/vercel-ai-gateway.ts。在createMessage()中温度取值逻辑为temperature: this.supportsTemperature(modelId) ? (this.options.modelTemperature ?? VERCEL_AI_GATEWAY_DEFAULT_TEMPERATURE) : undefined,也就是说用户在设置中配置的modelTemperature优先未配置则回落到 0.7对于不支持温度参数的模型则不传temperature字段。相关测试分别验证了自定义温度如 0.5、0.9与默认温度的传递行为vercel-ai-gateway.spec.ts。除温度外请求体还包含以下关键参数src/api/providers/vercel-ai-gateway.ts参数说明model从模型缓存解析出的模型 IDmax_completion_tokens取自模型元数据info.maxTokensstream: true始终使用流式输出逐 chunk 返回文本与工具调用片段stream_options: { include_usage: true }流式结束时回传完整用量tools/tool_choice由 Roo Code 工具定义转换而来实现原生工具调用parallel_tool_calls默认true允许并行发起多个工具调用completePrompt()单次补全stream: false同样遵循温度与max_completion_tokens逻辑并在出错时抛出带Vercel AI Gateway completion error:前缀的错误信息见 src/api/providers/vercel-ai-gateway.ts。默认模型与配置校验当你在模型下拉框中未做选择或配置为空时Roo Code 会回落到默认模型。当前仓库的默认值为默认模型 IDanthropic/claude-sonnet-4见 packages/types/src/providers/vercel-ai-gateway.ts默认模型元数据maxTokens: 64000、contextWindow: 200000、supportsImages: true、supportsPromptCache: true、输入价 $3/M、输出价 $15/M、缓存写入 $3.75/M、缓存读取 $0.30/M同一文件 L94-L105。fetchModel()的测试覆盖了这一回退路径未提供模型时返回默认 ID 且supportsPromptCache truevercel-ai-gateway.spec.ts。在设置持久化层面vercelAiGatewayApiKey与vercelAiGatewayModelId均为可选字段并通过z.literal(vercel-ai-gateway)与apiProvider建立类型绑定确保配置结构合法见 packages/types/src/provider-settings.ts 与 L416。计费、限制与 Tips定价与 BYOK计费方式Vercel AI Gateway 按底层模型自身定价计费包括缓存的提示词成本。具体价格请以网关侧的模型目录为准文档中给出了 Models 页面链接详见 vercel-ai-gateway.mdBYOKBring Your Own Key如果底层服务使用你自己的 API KeyVercel AI Gateway不加价no markup费用与直连上游一致新账户优惠Vercel 文档说明新账户在首次付费前每 30 天可获得 $5 额度可用于低成本试用。速率限制Vercel AI Gateway 本身不额外施加速率限制但上游提供商可能有自己的限流策略实际可用频率取决于底层模型供应商。模型选择建议网关模型池覆盖面广数百个且不同模型在编码、推理、成本上差异明显。建议编码/长任务优先考虑 Claude Sonnet/Opus 系列或 GPT-4.1/GPT-5 系列需要视觉输入的任务选择VERCEL_AI_GATEWAY_VISION_AND_TOOLS_MODELS或VISION_ONLY_MODELS中的模型能力标签由仓库静态集合兜底可随时查阅 packages/types/src/providers/vercel-ai-gateway.ts追求低延迟高性价比时尝试anthropic/claude-3.5-haiku或openai/gpt-4o-mini等轻量模型频繁复用的会话优先选择VERCEL_AI_GATEWAY_PROMPT_CACHING_MODELS集合内的模型以利用缓存降低成本。小结与速查在 Roo Code 中使用 Vercel AI Gateway 的完整路径在 Vercel 创建 AI Gateway API KeyRoo Code 设置中切换到 Vercel AI Gateway Provider粘贴 Key 并选择模型Roo Code 自动从https://ai-gateway.vercel.sh/v1/models拉取模型清单经内存 磁盘双层缓存后填充下拉框对 Claude/GPT 等支持缓存的模型Roo Code 自动在系统消息与最近两条用户消息上注入cache_control: ephemeral断点并回传缓存写入/读取 Token 与费用温度默认 0.7可在设置中按模型覆盖未指定模型时回落anthropic/claude-sonnet-4。关键实现文件速查Provider 主实现src/api/providers/vercel-ai-gateway.ts模型抓取与解析src/api/providers/fetchers/vercel-ai-gateway.ts模型缓存管理src/api/providers/fetchers/modelCache.ts缓存断点注入src/api/transform/caching/vercel-ai-gateway.ts模型常量与默认值packages/types/src/providers/vercel-ai-gateway.ts配置 Schemapackages/types/src/provider-settings.tsProvider 单测src/api/providers/tests/vercel-ai-gateway.spec.ts、src/api/providers/fetchers/tests/vercel-ai-gateway.spec.ts【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考