企业官网建设流程全解析

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 模式可以看到三类典型用法：

• 统一 API（OpenAI 兼容）：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 决定"谁走哪条路"，Percentage 决定"新老模型各分多少流量"，Rate Limit 与 Budget Limit 兜住"滥用与超支"，Model 是终点的实际推断调用。

值得一提的是，限流的粒度问题与动态路由密切相关：故障排查文档 明确指出，网关级别的 Rate Limiting 是按网关生效、而非按用户生效；要做到按用户/团队限流，正是借助动态路由中的 Conditional + Rate Limit 节点组合实现。这是把"配额"落到人头上（per-user/team limits）的标准手段。

元数据（Metadata）：路由分支的判断依据

Conditional 节点需要数据来做判断，这份数据通过请求头cf-aig-metadata透传。原文档要求最多 5 个条目、仅支持扁平结构（flat only）：

headers: { '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/route@v2'显式指定版本进行测试，验证行为符合预期
• 确认无误后切换到新版本；出现问题则回滚到上一版本（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），超出即无法完整表达分支条件
• 值类型仅限字符串/数字/布尔/null（string/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