autoskills 之 Cloudflare AI Gateway 动态路由（Dynamic Routing）实战指南：无需改代码的模型路由编排-平芜编程栈

【免费下载链接】autoskills

One command. Your entire AI skill stack. Installed.

项目地址：https://gitcode.com/gh_mirrors/au/autoskills

导读

本文基于 autoskills 仓库中 Cloudflare AI Gateway 参考文档展开，聚焦其核心能力之一——动态路由（Dynamic Routing）。动态路由允许你在 Cloudflare 控制台的可视化画布中编排复杂的请求分发逻辑（条件分支、流量切分、限流、预算控制与最终模型调用），应用侧只需把model字段替换为路由名称即可，完全不需要代码变更。读完本文，你将掌握动态路由的五种节点类型、元数据传递方式、四大典型路由模式（多模型回退、分级访问、灰度发布、成本回退）、版本管理与监控手段，以及其边界限制，可直接用于生产级 AI 应用的流量治理。

动态路由是什么：用路由名替代模型名

Cloudflare AI Gateway 是位于应用与各 AI 提供商之间的统一网关，负责代理请求并附加分析、缓存、限流与日志能力（架构见 README）：

Your App → AI Gateway → AI Provider (OpenAI, Anthropic, etc.) ↓ Analytics, Caching, Rate Limiting, Logging

动态路由（Dynamic Routing）是该网关的进阶能力：你不再直接指定model，而是指定一个在控制台中配置好的路由名称（Route Name），由网关根据路由画布中编排好的节点逻辑决定请求最终打到哪个模型、走哪条分支。这意味着复杂的流量分发策略可以在 dashboard 中随时调整，而无需改动任何代码。

在 OpenAI SDK 兼容调用中，用法如下：

const response = await client.chat.completions.create({ model: 'dynamic/smart-chat', // Route name from dashboard messages: [{ role: 'user', content: 'Hello!' }] });

URL 层面的对应关系在 README 的 URL 模式中也有体现：统一 API 使用.../compat/chat/completions，提供商专属使用.../{provider}/{endpoint}，而动态路由则是dynamic/{route-name}形式。此外，如果使用 Vercel AI SDK（官方推荐的ai-gateway-provider包），你甚至可以把模型数组传给gateway()，由 SDK 在客户端实现自动回退：

import { createAiGateway } from 'ai-gateway-provider'; import { createOpenAI } from '@ai-sdk/openai'; import { generateText } from 'ai'; const gateway = createAiGateway({ accountId: process.env.CF_ACCOUNT_ID, gateway: process.env.CF_GATEWAY_ID, }); // Automatic fallback array const { text } = await generateText({ model: gateway([ openai('gpt-4o'), // Try first anthropic('claude-sonnet-4-5'), // Fallback ]), prompt: 'Hello' });

注意区分两层回退：SDK 层回退是客户端行为，而动态路由的模型回退在网关侧完成，二者可以叠加使用。

五种节点类型：动态路由的积木

动态路由本质上是一个有向流程图，图中每个节点承担一种职责。下表是 dynamic-routing.md 定义的五种核心节点：

节点	用途	典型场景
Conditional（条件）	基于元数据（metadata）分支	付费用户 vs 免费用户、按地域路由
Percentage（百分比）	按比例切分流量	A/B 测试、渐进式发布
Rate Limit（速率限制）	执行配额	每用户/每团队调用上限
Budget Limit（预算限制）	成本配额	每用户消费上限
Model（模型）	调用提供商	路由的最终目的地

这五种节点是构建一切复杂路由策略的基本单元。Conditional是控制流的枢纽，Percentage用于随机切分，Rate Limit与Budget Limit是两道防护闸门，Model节点才是真正的终点——网关最终把请求转发给对应提供商执行推理。

传递元数据：路由分支的判断依据

条件节点和部分限流节点需要依据请求附带的元数据做判断。元数据通过 HTTP 头cf-aig-metadata传递，最多 5 个键，且必须是扁平结构（flat only，不支持嵌套对象）：

headers: { 'cf-aig-metadata': JSON.stringify({ userId: 'user-123', tier: 'pro', region: 'us-east' }) }

元数据的完整限制如下（来自原文档 Limitations）：

最多 5 个元数据条目；
值类型仅限string/number/boolean/null；
不允许嵌套对象；
路由名称只能包含字母数字与连字符（alphanumeric + hyphens）。

如果你使用的是 Vercel AI SDK，元数据可以直接通过第二个参数传入，效果等价：

model: gateway(openai('gpt-4o'), { metadata: { userId: 'u123', team: 'eng' }, // Max 5 entries })

而在 Workers AI Binding 场景中，元数据则放在gateway.metadata字段：

await env.AI.run( '@cf/meta/llama-3-8b-instruct', { messages: [{ role: 'user', content: 'Hello!' }] }, { gateway: { id: 'my-gateway', metadata: { userId: '123', team: 'engineering' } } } );

一个重要的实践提示来自 troubleshooting.md 的 Gotchas 表：网关级速率限制是"按网关"作用域，而非"按用户"作用域；要实现按用户/按团队限流，必须借助动态路由中的 Rate Limit 节点配合元数据完成——这正是动态路由不可替代的价值之一。

四大实战模式

原文档给出了四个开箱即用的路由模式，可直接在 dashboard 画布中复刻。

模式一：多模型回退（Multi-model Fallback）

主模型失败时依次切换到备用模型，最大限度保证可用性：

Start → GPT-4 → On error: Claude → On error: Llama

模式二：分级访问（Tiered Access）

按用户等级（tier）分流，不同等级享受不同的模型与配额：

Conditional: tier == 'enterprise' → GPT-4 (no limit) Conditional: tier == 'pro' → Rate Limit 1000/hr → GPT-4o Conditional: tier == 'free' → Rate Limit 10/hr → GPT-4o-mini

模式三：渐进式发布 / A/B 测试（Gradual Rollout）

按百分比把流量切给新旧模型，常用于模型灰度：

Percentage: 10% → New model, 90% → Old model

模式四：成本回退（Cost-based Fallback）

以预算消耗为阈值，成本逼近上限时自动降级到更便宜的模型，耗尽则直接报错：

Budget Limit: $100/day per teamId < 80%: GPT-4 >= 80%: GPT-4o-mini >= 100%: Error

这四个模式可以组合嵌套（例如"分级访问"内再套"成本回退"），构成完整的生产级流量治理链路。

版本管理：安全迭代路由

路由配置本身也需要像代码一样受控地演进。原文档 Version Management 给出了三条规则：

每次修改保存为新版本（Save changes as new version），而不是直接覆盖；
在代码中通过版本号后缀测试特定版本：model: 'dynamic/route@v2'；
需要回滚时，重新部署上一个版本即可，应用代码无需改动。

这条机制让路由配置具备可追溯、可回滚的特性，灰度验证某个版本时无需为每个版本新建路由。

监控：Dashboard → Gateway → Dynamic Routes

路由上线后，在控制台Dashboard → Gateway → Dynamic Routes中按路径维度观察运行状况：

每个路径的请求数（Request count per path）；
成功率 / 错误率（Success/error rates）；
按路径统计的延迟与成本（Latency/cost by path）。

结合 troubleshooting.md 的 Analytics 部分，你还可以用日志过滤器做更细的排查，例如status: error、provider: openai、cost > 0.01、duration > 1000，并把日志通过 Logpush 导出到 S3/GCS/Datadog/Splunk。若发现动态路由没有按预期工作，可通过响应头快速定位问题，例如用cf-aig-cache-status判断缓存命中（注意缓存与流式请求不兼容，见 features.md）。

使用前置条件与限制汇总

动态路由依赖 AI Gateway 本身，因此需要先完成网关的创建与鉴权配置。可参考同目录下的 configuration.md：在 dashboard 的AI > AI Gateway > Create Gateway创建，或通过 REST API 创建：

curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/ai-gateway/gateways \ -H "Authorization: Bearer $CF_API_TOKEN" -H "Content-Type: application/json" \ -d '{"id":"my-gateway","cache_ttl":3600,"rate_limiting_interval":60,"rate_limiting_limit":100,"collect_logs":true}'

网关命名遵循小写字母数字 + 连字符规则（如prod-api、dev-chat），这与动态路由名称的字符约束保持一致。生产环境建议启用网关鉴权（cf-aig-authorization头携带 Cloudflare API Token），并优先采用 BYOK 或统一计费（Unified Billing）以避免在代码中硬编码提供商密钥（详见 configuration.md 的 Best Practices）。

动态路由的完整限制清单（原文档 Limitations）：