Cloudflare AI Gateway 动态路由Dynamic Routing实战用路由名编排流量、回退与限额【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills动态路由Dynamic Routing是 Cloudflare AI Gateway 提供的流量编排能力你可以在控制台Dashboard中把复杂的路由规则分支、比例分流、限流、预算、模型调度配置成一条命名的路由而应用代码只需要通过dynamic/{route-name}引用路由名无需任何代码改动即可调整线上策略。读完本文你将掌握动态路由的节点类型、元数据透传、四大典型编排模式多模型回退、分级访问、渐进发布、成本回退以及版本管理与监控的最佳实践。动态路由的核心思想路由名替代模型名AI Gateway 本身充当你的应用 → AI Gateway → 各大模型供应商之间的代理并在链路中叠加分析、缓存、限流与日志能力见 AI Gateway 参考总览 中的架构说明。动态路由在此基础上更进一步把选哪个模型、何时回退、如何限流等策略从代码中剥离全部收拢到 Dashboard 中声明式配置。从 AI Gateway 参考总览 的 URL 模式可以看到三类典型用法统一 APIOpenAI 兼容https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions供应商专属端点https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}动态路由用路由名替代模型名即dynamic/{route-name}也就是说客户端请求的model字段写的是路由名而真正路由到哪个模型由 Dashboard 中配置的节点图决定。运营人员改路由配置时应用代码一行都不用动。快速上手在代码中引用路由在原文档的 动态路由文档 中给出了最直接的 OpenAI SDK 用法——把model字段指向路由名const response await client.chat.completions.create({ model: dynamic/smart-chat, // Route name from dashboard messages: [{ role: user, content: Hello! }] });其中smart-chat是你在 Dashboard 中创建的路由名。请求发出后Gateway 会依据路由配置里的节点图决定实际调用的供应商与模型。如果你的客户端走 OpenAI 兼容协议可参考 SDK 集成文档 配置baseURL将 Gateway 作为 OpenAI 客户端的替换底座import OpenAI from openai; const client new OpenAI({ apiKey: process.env.OPENAI_API_KEY, baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/compat, defaultHeaders: { cf-aig-authorization: Bearer ${cfToken} // 认证网关必需 } });使用 Vercel AI SDK 时createAiGateway同样可以包装任意模型并应用动态路由更完整的接入方式见 AI Gateway SDK 集成 与 配置与安装。节点类型路由编排的基本单元路由本质是一张由节点组成的流程图每个节点承担一种职责。原文档给出的五类节点如下节点用途典型场景Conditional条件依据元数据metadata分支付费用户 vs 免费用户、地理路由geo routingPercentage百分比按比例分流流量模型测试A/B 测试、渐进式发布Rate Limit限流强制配额按用户/团队限制请求频率Budget Limit预算成本配额按用户设置消费上限Model模型调用供应商路由的最终终点理解这五类节点就能组合出几乎所有的流量治理策略Conditional 决定谁走哪条路Percentage 决定新老模型各分多少流量Rate Limit 与 Budget Limit 兜住滥用与超支Model 是终点的实际推断调用。值得一提的是限流的粒度问题与动态路由密切相关故障排查文档 明确指出网关级别的 Rate Limiting 是按网关生效、而非按用户生效要做到按用户/团队限流正是借助动态路由中的 Conditional Rate Limit 节点组合实现。这是把配额落到人头上per-user/team limits的标准手段。元数据Metadata路由分支的判断依据Conditional 节点需要数据来做判断这份数据通过请求头cf-aig-metadata透传。原文档要求最多 5 个条目、仅支持扁平结构flat onlyheaders: { cf-aig-metadata: JSON.stringify({ userId: user-123, tier: pro, region: us-east }) }上述示例同时演示了三种最常用的元数据维度用户标识userId用于按用户限流、会员等级tier用于分级访问、地域region用于地理路由。在 SDK 集成文档 中Vercel AI SDK 场景也可以直接在模型包装器上声明元数据model: gateway(openai(gpt-4o), { cacheKey: my-key, cacheTtl: 3600, metadata: { userId: u123, team: eng }, // Max 5 entries retries: { maxAttempts: 3, backoff: exponential } })常见路由模式Common Patterns原文档给出了四个可直接复用的编排模式它们组合了上述节点覆盖了生产环境最高频的诉求。多模型故障回退Multi-model fallback一条直线串联多个 Model 节点上游出错时自动落到下一个模型Start → GPT-4 → On error: Claude → On error: Llama这解决了单一供应商故障时的可用性问题无需在应用层编写任何重试/降级逻辑。分级访问Tiered access用 Conditional 节点按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企业级不设限、专业版每小时 1000 次、免费版每小时 10 次——配额与模型档次同时差异化既控制成本又保证付费体验。渐进式发布Gradual rollout用 Percentage 节点按比例切流量适合新模型灰度上线Percentage: 10% → New model, 90% → Old model先放 10% 流量观察新模型的质量与延迟确认无误后再逐步调高比例风险可控。这也可以理解成模型层面的 A/B 测试。基于成本的回退Cost-based fallback用 Budget Limit 节点按预算消耗切换廉价模型Budget Limit: $100/day per teamId 80%: GPT-4 80%: GPT-4o-mini 100%: Error预算消耗低于 80% 时用 GPT-4 保证质量超过 80% 自动降级到 GPT-4o-mini 控制成本达到 100% 直接报错止损。这里per teamId说明预算限制同样可以按元数据维度如团队 ID圈定范围。版本管理路由的安全演进路由配置的每次修改都应保存为新版本而非直接覆盖线上修改完成后保存为新版本new version用model: dynamic/routev2显式指定版本进行测试验证行为符合预期确认无误后切换到新版本出现问题则回滚到上一版本roll back by deploying previous version这套版本化 显式指定 可回滚的流程让动态路由像普通软件发布一样具备可审计、可回退的能力特别适合多环境dev/staging/prod共用同一 Gateway 的团队。关于环境隔离等更广泛的配置实践可参考 配置与安装 中的最佳实践清单。监控按路径观测路由表现Dashboard → Gateway → Dynamic Routes 提供针对每一条路由路径的观测视图请求数Request count per path判断各路径流量分布是否符合预期成功率/错误率Success/error rates及时发现某条路径回退异常或报错延迟与成本Latency/cost by path评估每个分支的性价比在更细的层面故障排查文档 补充了通用分析能力AI Gateway 分析页支持请求数、Token 数、p50/p95/p99 延迟、缓存命中率、成本等指标并支持status: error、provider: openai、cost 0.01、duration 1000这类筛选条件以及通过 Logpush 导出到 S3、GCS、Datadog、Splunk 等下游系统。将按路径的视图与全局指标结合可以精确定位问题出在哪条分支上。限制与注意事项原文档明确列出了动态路由的边界接入前务必确认元数据最多 5 条Max 5 metadata entries超出即无法完整表达分支条件值类型仅限字符串/数字/布尔/nullstring/number/boolean/null only不支持数组等复杂类型不支持嵌套对象No nested objects必须保持扁平结构路由命名规则仅允许字母数字与连字符alphanumeric hyphens例如smart-chat、prod-api-v2此外从 故障排查文档 可以交叉确认两类相关约束缓存与流式响应不兼容动态路由涉及流式请求时需注意统一 API 下模型名必须带供应商前缀如openai/gpt-4o而非gpt-4o而动态路由场景则以dynamic/{route-name}引用。若请求返回 429限流触发可参考该文档中的指数退避重试模式处理。小结动态路由把模型选择、回退、限流、预算全部抽象成 Dashboard 中的可视化编排应用侧只需引用路由名。配合 功能与能力缓存、限流、防护、日志和 SDK 集成Vercel AI SDK、OpenAI SDK、Workers AI Binding、HTTP/cURL动态路由是构建生产级多模型 AI 应用的流量治理核心。对于需要将 Gateway 部署到 Cloudflare 平台的完整流程可继续阅读 cloudflare-deploy 技能说明。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare AI Gateway 动态路由（Dynamic Routing）实战：用路由名编排流量、回退与限额
Cloudflare AI Gateway 动态路由Dynamic Routing实战用路由名编排流量、回退与限额【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills动态路由Dynamic Routing是 Cloudflare AI Gateway 提供的流量编排能力你可以在控制台Dashboard中把复杂的路由规则分支、比例分流、限流、预算、模型调度配置成一条命名的路由而应用代码只需要通过dynamic/{route-name}引用路由名无需任何代码改动即可调整线上策略。读完本文你将掌握动态路由的节点类型、元数据透传、四大典型编排模式多模型回退、分级访问、渐进发布、成本回退以及版本管理与监控的最佳实践。动态路由的核心思想路由名替代模型名AI Gateway 本身充当你的应用 → AI Gateway → 各大模型供应商之间的代理并在链路中叠加分析、缓存、限流与日志能力见 AI Gateway 参考总览 中的架构说明。动态路由在此基础上更进一步把选哪个模型、何时回退、如何限流等策略从代码中剥离全部收拢到 Dashboard 中声明式配置。从 AI Gateway 参考总览 的 URL 模式可以看到三类典型用法统一 APIOpenAI 兼容https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions供应商专属端点https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}动态路由用路由名替代模型名即dynamic/{route-name}也就是说客户端请求的model字段写的是路由名而真正路由到哪个模型由 Dashboard 中配置的节点图决定。运营人员改路由配置时应用代码一行都不用动。快速上手在代码中引用路由在原文档的 动态路由文档 中给出了最直接的 OpenAI SDK 用法——把model字段指向路由名const response await client.chat.completions.create({ model: dynamic/smart-chat, // Route name from dashboard messages: [{ role: user, content: Hello! }] });其中smart-chat是你在 Dashboard 中创建的路由名。请求发出后Gateway 会依据路由配置里的节点图决定实际调用的供应商与模型。如果你的客户端走 OpenAI 兼容协议可参考 SDK 集成文档 配置baseURL将 Gateway 作为 OpenAI 客户端的替换底座import OpenAI from openai; const client new OpenAI({ apiKey: process.env.OPENAI_API_KEY, baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/compat, defaultHeaders: { cf-aig-authorization: Bearer ${cfToken} // 认证网关必需 } });使用 Vercel AI SDK 时createAiGateway同样可以包装任意模型并应用动态路由更完整的接入方式见 AI Gateway SDK 集成 与 配置与安装。节点类型路由编排的基本单元路由本质是一张由节点组成的流程图每个节点承担一种职责。原文档给出的五类节点如下节点用途典型场景Conditional条件依据元数据metadata分支付费用户 vs 免费用户、地理路由geo routingPercentage百分比按比例分流流量模型测试A/B 测试、渐进式发布Rate Limit限流强制配额按用户/团队限制请求频率Budget Limit预算成本配额按用户设置消费上限Model模型调用供应商路由的最终终点理解这五类节点就能组合出几乎所有的流量治理策略Conditional 决定谁走哪条路Percentage 决定新老模型各分多少流量Rate Limit 与 Budget Limit 兜住滥用与超支Model 是终点的实际推断调用。值得一提的是限流的粒度问题与动态路由密切相关故障排查文档 明确指出网关级别的 Rate Limiting 是按网关生效、而非按用户生效要做到按用户/团队限流正是借助动态路由中的 Conditional Rate Limit 节点组合实现。这是把配额落到人头上per-user/team limits的标准手段。元数据Metadata路由分支的判断依据Conditional 节点需要数据来做判断这份数据通过请求头cf-aig-metadata透传。原文档要求最多 5 个条目、仅支持扁平结构flat onlyheaders: { cf-aig-metadata: JSON.stringify({ userId: user-123, tier: pro, region: us-east }) }上述示例同时演示了三种最常用的元数据维度用户标识userId用于按用户限流、会员等级tier用于分级访问、地域region用于地理路由。在 SDK 集成文档 中Vercel AI SDK 场景也可以直接在模型包装器上声明元数据model: gateway(openai(gpt-4o), { cacheKey: my-key, cacheTtl: 3600, metadata: { userId: u123, team: eng }, // Max 5 entries retries: { maxAttempts: 3, backoff: exponential } })常见路由模式Common Patterns原文档给出了四个可直接复用的编排模式它们组合了上述节点覆盖了生产环境最高频的诉求。多模型故障回退Multi-model fallback一条直线串联多个 Model 节点上游出错时自动落到下一个模型Start → GPT-4 → On error: Claude → On error: Llama这解决了单一供应商故障时的可用性问题无需在应用层编写任何重试/降级逻辑。分级访问Tiered access用 Conditional 节点按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企业级不设限、专业版每小时 1000 次、免费版每小时 10 次——配额与模型档次同时差异化既控制成本又保证付费体验。渐进式发布Gradual rollout用 Percentage 节点按比例切流量适合新模型灰度上线Percentage: 10% → New model, 90% → Old model先放 10% 流量观察新模型的质量与延迟确认无误后再逐步调高比例风险可控。这也可以理解成模型层面的 A/B 测试。基于成本的回退Cost-based fallback用 Budget Limit 节点按预算消耗切换廉价模型Budget Limit: $100/day per teamId 80%: GPT-4 80%: GPT-4o-mini 100%: Error预算消耗低于 80% 时用 GPT-4 保证质量超过 80% 自动降级到 GPT-4o-mini 控制成本达到 100% 直接报错止损。这里per teamId说明预算限制同样可以按元数据维度如团队 ID圈定范围。版本管理路由的安全演进路由配置的每次修改都应保存为新版本而非直接覆盖线上修改完成后保存为新版本new version用model: dynamic/routev2显式指定版本进行测试验证行为符合预期确认无误后切换到新版本出现问题则回滚到上一版本roll back by deploying previous version这套版本化 显式指定 可回滚的流程让动态路由像普通软件发布一样具备可审计、可回退的能力特别适合多环境dev/staging/prod共用同一 Gateway 的团队。关于环境隔离等更广泛的配置实践可参考 配置与安装 中的最佳实践清单。监控按路径观测路由表现Dashboard → Gateway → Dynamic Routes 提供针对每一条路由路径的观测视图请求数Request count per path判断各路径流量分布是否符合预期成功率/错误率Success/error rates及时发现某条路径回退异常或报错延迟与成本Latency/cost by path评估每个分支的性价比在更细的层面故障排查文档 补充了通用分析能力AI Gateway 分析页支持请求数、Token 数、p50/p95/p99 延迟、缓存命中率、成本等指标并支持status: error、provider: openai、cost 0.01、duration 1000这类筛选条件以及通过 Logpush 导出到 S3、GCS、Datadog、Splunk 等下游系统。将按路径的视图与全局指标结合可以精确定位问题出在哪条分支上。限制与注意事项原文档明确列出了动态路由的边界接入前务必确认元数据最多 5 条Max 5 metadata entries超出即无法完整表达分支条件值类型仅限字符串/数字/布尔/nullstring/number/boolean/null only不支持数组等复杂类型不支持嵌套对象No nested objects必须保持扁平结构路由命名规则仅允许字母数字与连字符alphanumeric hyphens例如smart-chat、prod-api-v2此外从 故障排查文档 可以交叉确认两类相关约束缓存与流式响应不兼容动态路由涉及流式请求时需注意统一 API 下模型名必须带供应商前缀如openai/gpt-4o而非gpt-4o而动态路由场景则以dynamic/{route-name}引用。若请求返回 429限流触发可参考该文档中的指数退避重试模式处理。小结动态路由把模型选择、回退、限流、预算全部抽象成 Dashboard 中的可视化编排应用侧只需引用路由名。配合 功能与能力缓存、限流、防护、日志和 SDK 集成Vercel AI SDK、OpenAI SDK、Workers AI Binding、HTTP/cURL动态路由是构建生产级多模型 AI 应用的流量治理核心。对于需要将 Gateway 部署到 Cloudflare 平台的完整流程可继续阅读 cloudflare-deploy 技能说明。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考