尧图网站建设 
Cloudflare AI Gateway 实战指南为任意 AI 模型提供商统一接入缓存、限流与动态路由【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCloudflare AI Gateway 是一个面向 AI 模型提供商的通用网关位于你的应用与 OpenAI、Anthropic、Workers AI 等模型服务之间统一提供分析、缓存、限流、日志与动态路由能力。本文以本仓库中skills/.curated/cloudflare-deploy技能包内的 AI Gateway 参考文档为主体结合仓库内 ai-gateway 参考目录 下的配置、功能、路由与排障文档系统讲解从四种 SDK 接入方式、网关创建与鉴权到缓存/限流/护栏/DLP 等核心能力、动态路由编排与故障排查的完整实战方案。读完后你将能够在自己的应用中独立接入 AI Gateway并合理设计缓存策略、限流配额与模型回退路由。何时使用 AI Gateway根据仓库中的参考文档在以下场景中应优先考虑接入 AI Gateway为任意 AI 提供商OpenAI、Anthropic、Workers AI 等统一设置网关入口需要实现缓存、限流或请求重试/回退fallback能力需要配置基于 A/B 测试或模型回退的动态路由需要通过 BYOKBring Your Own Key安全地管理各提供商的 API Key需要追加安全能力如护栏Guardrails与数据防泄漏DLP需要借助日志与自定义元数据metadata建立可观测性需要对 AI Gateway 请求进行调试或对配置做优化。在本仓库的技能决策树中AI Gateway 被归类为「我需要 AI/ML」场景下的核心选项之一定位是面向任意 AI 提供商的网关缓存、路由与 workers-ai边缘推理、vectorizeRAG 向量库、agents-sdk有状态 AI Agent并列参见 SKILL.md 中的决策树。架构与关键 URL 模式AI Gateway 本质上是一个位于你的应用与 AI 提供商之间的代理Proxy在转发请求的同时旁路处理分析、缓存、限流与日志Your App → AI Gateway → AI Provider (OpenAI, Anthropic, etc.) ↓ Analytics, Caching, Rate Limiting, Logging接入时你需要拿到两个标识符Account IDCloudflare 控制台Overview页面复制Gateway IDAI Gateway 页面中的网关名称列即网关 ID。Gateway ID 的命名规范为小写字母数字 连字符例如prod-api、dev-chat。在此基础上AI Gateway 提供三类关键 URL 模式URL 模式用途https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions统一 APIOpenAI 兼容可通过模型名前缀切换提供商https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}提供商专用端点如/openai、/anthropicdynamic/{route-name}动态路由用路由名替代模型名如model: dynamic/smart-chat快速开始四种接入模式原文档按你的技术栈是什么给出了四条接入路径下文逐一展开并补充仓库内 sdk-integration.md 中的细节。Pattern 1Vercel AI SDK推荐这是最现代的接入方式使用官方ai-gateway-provider包天然支持自动回退fallback。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, }); const openai createOpenAI({ apiKey: process.env.OPENAI_API_KEY }); // 单模型 const { text } await generateText({ model: gateway(openai(gpt-4o)), prompt: Hello }); // 自动回退数组 const { text } await generateText({ model: gateway([ openai(gpt-4o), // 优先尝试 anthropic(claude-sonnet-4-5), // 回退 ]), prompt: Hello });安装依赖npm install ai-gateway-provider ai ai-sdk/openai ai-sdk/anthropiccreateAiGateway还支持可选参数apiKey: process.env.CF_API_TOKEN用于开启网关鉴权的场景并可在调用时传入每个请求的选项model: gateway(openai(gpt-4o), { cacheKey: my-key, cacheTtl: 3600, metadata: { userId: u123, team: eng }, // 最多 5 个键 retries: { maxAttempts: 3, backoff: exponential } })Pattern 2OpenAI SDKDrop-in 替换如果你已经使用 OpenAI SDK只需替换baseURL即可把流量切到 AI Gateway并通过模型名格式{provider}/{model}在多个提供商之间切换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} // 开启鉴权的网关必填 } }); // 通过模型格式切换提供商 const response await client.chat.completions.create({ model: openai/gpt-4o, // 或 anthropic/claude-sonnet-4-5 messages: [{ role: user, content: Hello! }] });对应的 Anthropic SDK 写法为const client new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/anthropic, defaultHeaders: { cf-aig-authorization: Bearer ${cfToken} } });Pattern 3Cloudflare Worker Workers AI Binding在 Worker 内部直接通过env.AI.run()调用模型并透传网关配置与元数据export default { async fetch(request, env, ctx) { const response await env.AI.run( cf/meta/llama-3-8b-instruct, { messages: [{ role: user, content: Hello! }] }, { gateway: { id: my-gateway, metadata: { userId: 123, team: engineering } } } ); return Response.json(response); } };对应的wrangler.toml配置需要声明[ai]binding 并挂载网关# wrangler.toml [ai] binding AI [[ai.gateway]] id my-gateway需要注意使用 Workers AI 时本地开发无法加载模型必须使用wrangler dev --remote运行部署则执行wrangler deploy详见 workers-ai README。Pattern 4直接 HTTP任意语言不依赖任何 SDK直接以 cURL 调用 OpenAI 兼容端点即可网关鉴权头与元数据头都放在 HTTP Header 中curl https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/chat/completions \ -H Authorization: Bearer $OPENAI_KEY \ -H cf-aig-authorization: Bearer $CF_TOKEN \ -H cf-aig-metadata: {\userId\:\123\} \ -d {model:gpt-4o,messages:[...]}框架接入LangChain / LlamaIndex使用框架时复用 OpenAI SDK 的 baseURL 替换方案即可。例如 LangChain 的ChatOpenAInew ChatOpenAI({ configuration: { baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai } });请求头快速参考Header用途示例说明cf-aig-authorization网关鉴权Bearer {token}开启鉴权的网关必填cf-aig-metadata追踪/元数据{userId:x}最多 5 个键扁平结构不可嵌套cf-aig-cache-ttl缓存时长3600秒最小 60最大 259200030 天cf-aig-skip-cache跳过缓存true—cf-aig-cache-key自定义缓存键my-key每种预期响应需使用唯一键cf-aig-collect-log跳过日志false默认true即默认采集日志cf-aig-cache-status缓存命中/未命中仅响应返回值为HIT或MISS网关创建、配置与鉴权创建网关控制台方式AI AI Gateway Create Gateway随后配置鉴权、缓存、限流、日志等选项。API 方式调用 Cloudflare 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}网关管理 API创建后可对网关做完整的增删改查# 列出网关 curl https://api.cloudflare.com/client/v4/accounts/{account_id}/ai-gateway/gateways \ -H Authorization: Bearer $CF_API_TOKEN # 获取单个网关 curl .../gateways/{gateway_id} # 更新网关配置 curl -X PUT .../gateways/{gateway_id} \ -d {cache_ttl:7200,rate_limiting_limit:200} # 删除网关 curl -X DELETE .../gateways/{gateway_id}Wrangler 集成与密钥管理在 Worker 项目中通过 wrangler 写入所需密钥wrangler secret put CF_API_TOKEN wrangler secret put OPENAI_API_KEY # 未使用 BYOK 时必填网关类型与提供商鉴权选项网关本身分两种类型未鉴权网关Unauthenticated开放访问不推荐用于生产鉴权网关Authenticated要求请求携带cf-aig-authorization头值为 Cloudflare API Token推荐。而面向各 AI 提供商的鉴权有三种可选方案方案说明接入方式Unified Billingkeyless通过 Cloudflare 统一计费支付推理费用无需提供商 API Key只带cf-aig-authorization头支持 OpenAI、Anthropic、Google AI StudioBYOKStore Keys在 Cloudflare 控制台 Provider Keys 区域存储提供商密钥代码中不出现密钥无需在代码里配置密钥Request Headers每次请求时携带提供商密钥在请求中附加提供商的鉴权头采用 Unified Billing 或 BYOK 的 TypeScript 客户端写法如下const client new OpenAI({ baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai, defaultHeaders: { cf-aig-authorization: Bearer ${cfToken} } });注意BYOK 与 Unified Billing 互斥只能二选一。需要每次请求携带提供商密钥时则使用apiKey: process.env.OPENAI_API_KEY配合相同的 baseURL 与cf-aig-authorization头。API Token 权限网关管理Gateway management需要 AI Gateway 的 Read Edit 权限网关访问Gateway access至少需要 AI Gateway 的 Read 权限。Python 示例AI Gateway 同样适用于 Python 生态替换 OpenAI SDK 的base_url即可from openai import OpenAI import os client OpenAI( api_keyos.environ.get(OPENAI_API_KEY), base_urlfhttps://gateway.ai.cloudflare.com/v1/{os.environ[CF_ACCOUNT_ID]}/{os.environ[GATEWAY_ID]}/openai, default_headers{cf-aig-authorization: fBearer {os.environ[CF_API_TOKEN]}} )配置最佳实践生产环境始终开启网关鉴权优先使用 BYOK 或 Unified Billing把密钥移出代码按环境拆分网关dev/staging/prod 各自独立设置限流防止成本失控开启日志便于用量追踪与问题排查。核心能力缓存、限流、护栏、DLP 与日志原文档的 features.md 详细列出了 AI Gateway 的进阶能力均可在控制台 Gateway → Settings 中开启。响应缓存Caching控制台开启路径Settings → Cache Responses → Enable。也可以逐请求通过请求头控制// 自定义 TTL1 小时 headers: { cf-aig-cache-ttl: 3600 } // 跳过缓存 headers: { cf-aig-skip-cache: true } // 自定义缓存键 headers: { cf-aig-cache-key: greeting-en }限制与注意TTL 取值范围为 60 秒至 30 天缓存与流式输出streaming不兼容。此外请求参数不同如 temperature 不同、或控制台未开启缓存都会导致缓存不生效可用响应头cf-aig-cache-status判断命中情况HIT/MISS。限流Rate Limiting控制台开启路径Settings → Rate-limiting → Enable。支持两种窗口算法Fixed window固定窗口按固定时间间隔重置Sliding window滑动窗口滚动窗口更精确。超过配额时返回 HTTP429。注意限流范围是按网关维度而非按用户维度若需按用户/团队细分配额应使用动态路由中的 Rate Limit 节点。护栏Guardrails控制台开启路径Settings → Guardrails → Enable。用于过滤不当内容的提示词/响应动作可选Flag仅记录或Block拒绝。数据防泄漏DLP控制台开启路径Settings → DLP → Enable。用于检测 PII邮箱、SSN、信用卡号等敏感信息动作可选Flag / Block / Redact打码。计费模式模式说明配置方式Unified Billing通过 Cloudflare 计费无需提供商密钥仅使用cf-aig-authorization头BYOK提供商密钥存储在控制台在 Provider Keys 区域添加密钥Pass-through每次请求携带提供商密钥在请求中附加提供商的鉴权头零数据保留Zero Data Retention控制台开启路径Settings → Privacy → Zero Data Retention。开启后不存储任何提示词与响应内容但请求计数与成本统计仍然保留。日志与自定义元数据控制台开启路径Settings → Logs → Enable支持最多 1000 万条日志。每条日志包含提示词、响应、提供商、模型、token 数、成本、时长、缓存状态与元数据。逐请求跳过日志// 跳过本请求的日志 headers: { cf-aig-collect-log: false }日志导出可通过Logpush推送到 S3、GCS、Datadog、Splunk 等目标。注意日志存在 3060 秒的延迟属正常现象。自定义成本追踪对不在 Cloudflare 定价库中的模型可在控制台 Gateway → Settings → Custom Costs 中配置或通过 API 设置model、input_cost、output_cost。支持的提供商22提供商统一 API 写法说明OpenAIopenai/gpt-4o完整支持Anthropicanthropic/claude-sonnet-4-5完整支持Google AIgoogle-ai-studio/gemini-2.0-flash完整支持Workers AIworkersai/cf/meta/llama-3原生支持Azure OpenAIazure-openai/*使用部署名AWS Bedrock仅提供商端点/bedrock/*Groqgroq/*快速推理Mistral、Cohere、Perplexity、xAI、DeepSeek、Cerebras完整支持—能力最佳实践对确定性提示词开启缓存设置限流防止滥用面向用户的 AI 启用护栏涉及敏感数据启用 DLP使用统一计费或 BYOK 简化密钥管理开启日志便于调试需要隐私合规时启用零数据保留。动态路由无代码变更的复杂路由编排AI Gateway 的 dynamic-routing.md 展示了如何在不改代码的前提下用路由名替代模型名完成复杂路由const response await client.chat.completions.create({ model: dynamic/smart-chat, // 控制台配置的路由名 messages: [{ role: user, content: Hello! }] });节点类型节点用途典型场景Conditional基于元数据分支付费/免费用户分流、地域路由Percentage按比例切分流量模型测试、渐进式发布Rate Limit配额控制按用户/团队限流Budget Limit成本配额按用户设置花费上限Model调用提供商路由终点元数据Metadata通过cf-aig-metadata头传递最多 5 个键、只能扁平结构、值仅限 string/number/boolean/nullheaders: { cf-aig-metadata: JSON.stringify({ userId: user-123, tier: pro, region: us-east }) }常见路由模式多模型回退Start → GPT-4 → On error: Claude → On error: Llama分级访问tiered accessConditional: tier enterprise → GPT-4 (无限制) Conditional: tier pro → Rate Limit 1000/hr → GPT-4o Conditional: tier free → Rate Limit 10/hr → GPT-4o-mini渐进式发布Percentage: 10% → 新模型, 90% → 旧模型基于成本的回退Budget Limit: $100/day per teamId 80%: GPT-4 80%: GPT-4o-mini 100%: 报错版本管理与监控变更可保存为新版本用model: dynamic/routev2指定版本进行测试通过部署上一版即可回滚监控入口Dashboard → Gateway → Dynamic Routes可查看每条路径的请求数、成功/错误率、延迟与成本。动态路由限制元数据最多 5 个键且仅限 string/number/boolean/null不支持嵌套对象路由名只能使用字母数字与连字符。故障排查与调试原文档的 troubleshooting.md 汇总了常见错误与排查路径。常见错误对照表错误原因修复401缺少cf-aig-authorization头添加携带 CF API Token 的该请求头403提供商密钥无效 / BYOK 密钥过期在控制台检查提供商密钥429超过限流调高限额或实现退避重试401 的修复方式const client new OpenAI({ baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai, defaultHeaders: { cf-aig-authorization: Bearer ${CF_API_TOKEN} } });429 的指数退避重试模式async function requestWithRetry(fn, maxRetries 3) { for (let i 0; i maxRetries; i) { try { return await fn(); } catch (e) { if (e.status 429 i maxRetries - 1) { await new Promise(r setTimeout(r, Math.pow(2, i) * 1000)); continue; } throw e; } } }常见坑Gotchas问题实际情况元数据限制最多 5 个键、仅扁平结构不可嵌套缓存键冲突每种预期响应必须使用唯一键BYOK Unified Billing互斥不可同时使用限流范围按网关而非按用户按用户请用动态路由日志延迟3060 秒属正常流式 缓存不兼容统一 API 模型名必须带提供商前缀openai/gpt-4o不能只写gpt-4o缓存不生效排查可能原因请求参数不同如 temperature、开启了流式、或控制台未启用缓存。检查方式// 检查响应头 console.log(Cache:, response.headers.get(cf-aig-cache-status)); console.log(Request ID:, response.headers.get(cf-ray));日志不出现排查确认控制台 Dashboard → Gateway → Settings 已开启日志移除cf-aig-collect-log: false请求头等待 3060 秒检查日志上限默认 1000 万条。连通性测试与分析# 测试连通性 curl -v https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/models \ -H Authorization: Bearer $OPENAI_KEY \ -H cf-aig-authorization: Bearer $CF_TOKEN分析面板入口Dashboard → AI Gateway → 选择网关。可观测指标包括请求数、token 数、延迟p50/p95/p99、缓存命中率与成本日志支持过滤表达式如status: error、provider: openai、cost 0.01、duration 1000数据可通过 Logpush 导出至 S3/GCS/Datadog/Splunk。在 Cloudflare 技术栈中的位置在本仓库的 Cloudflare Deploy 技能中AI Gateway 是 AI/ML 场景的关键一环与周边服务协同使用在 workers-ai 之上提供面向任意提供商的网关能力其 README 亦将 AI Gateway 列为缓存、限流与分析的关键配套与 agents-sdk 配合可构建有状态 AI Agent 模式与 vectorize 配合可实现基于嵌入向量的 RAG 模式。整体部署流程鉴权、wrangler使用可参考 SKILL.md 与仓库中 wrangler 相关参考文档。推荐的阅读顺序任务建议文件首次搭建README.md configuration.mdSDK 集成README.md sdk-integration.md开启缓存README.md features.md配置回退路由README.md dynamic-routing.md调试错误README.md troubleshooting.md本仓库中完整的参考文件包括sdk-integration.mdVercel AI SDK / OpenAI SDK / Workers binding 模式、configuration.md控制台配置、wrangler、API Token、features.md缓存、限流、护栏、DLP、BYOK、统一计费、dynamic-routing.md回退、A/B 测试、条件路由与 troubleshooting.md调试、错误、可观测性、常见坑。此外与 Workers AI 绑定相关的env.AI.run()细节可参考 workers-ai 参考文档。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare AI Gateway 实战指南：为任意 AI 模型提供商统一接入缓存、限流与动态路由
Cloudflare AI Gateway 实战指南为任意 AI 模型提供商统一接入缓存、限流与动态路由【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCloudflare AI Gateway 是一个面向 AI 模型提供商的通用网关位于你的应用与 OpenAI、Anthropic、Workers AI 等模型服务之间统一提供分析、缓存、限流、日志与动态路由能力。本文以本仓库中skills/.curated/cloudflare-deploy技能包内的 AI Gateway 参考文档为主体结合仓库内 ai-gateway 参考目录 下的配置、功能、路由与排障文档系统讲解从四种 SDK 接入方式、网关创建与鉴权到缓存/限流/护栏/DLP 等核心能力、动态路由编排与故障排查的完整实战方案。读完后你将能够在自己的应用中独立接入 AI Gateway并合理设计缓存策略、限流配额与模型回退路由。何时使用 AI Gateway根据仓库中的参考文档在以下场景中应优先考虑接入 AI Gateway为任意 AI 提供商OpenAI、Anthropic、Workers AI 等统一设置网关入口需要实现缓存、限流或请求重试/回退fallback能力需要配置基于 A/B 测试或模型回退的动态路由需要通过 BYOKBring Your Own Key安全地管理各提供商的 API Key需要追加安全能力如护栏Guardrails与数据防泄漏DLP需要借助日志与自定义元数据metadata建立可观测性需要对 AI Gateway 请求进行调试或对配置做优化。在本仓库的技能决策树中AI Gateway 被归类为「我需要 AI/ML」场景下的核心选项之一定位是面向任意 AI 提供商的网关缓存、路由与 workers-ai边缘推理、vectorizeRAG 向量库、agents-sdk有状态 AI Agent并列参见 SKILL.md 中的决策树。架构与关键 URL 模式AI Gateway 本质上是一个位于你的应用与 AI 提供商之间的代理Proxy在转发请求的同时旁路处理分析、缓存、限流与日志Your App → AI Gateway → AI Provider (OpenAI, Anthropic, etc.) ↓ Analytics, Caching, Rate Limiting, Logging接入时你需要拿到两个标识符Account IDCloudflare 控制台Overview页面复制Gateway IDAI Gateway 页面中的网关名称列即网关 ID。Gateway ID 的命名规范为小写字母数字 连字符例如prod-api、dev-chat。在此基础上AI Gateway 提供三类关键 URL 模式URL 模式用途https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions统一 APIOpenAI 兼容可通过模型名前缀切换提供商https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}提供商专用端点如/openai、/anthropicdynamic/{route-name}动态路由用路由名替代模型名如model: dynamic/smart-chat快速开始四种接入模式原文档按你的技术栈是什么给出了四条接入路径下文逐一展开并补充仓库内 sdk-integration.md 中的细节。Pattern 1Vercel AI SDK推荐这是最现代的接入方式使用官方ai-gateway-provider包天然支持自动回退fallback。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, }); const openai createOpenAI({ apiKey: process.env.OPENAI_API_KEY }); // 单模型 const { text } await generateText({ model: gateway(openai(gpt-4o)), prompt: Hello }); // 自动回退数组 const { text } await generateText({ model: gateway([ openai(gpt-4o), // 优先尝试 anthropic(claude-sonnet-4-5), // 回退 ]), prompt: Hello });安装依赖npm install ai-gateway-provider ai ai-sdk/openai ai-sdk/anthropiccreateAiGateway还支持可选参数apiKey: process.env.CF_API_TOKEN用于开启网关鉴权的场景并可在调用时传入每个请求的选项model: gateway(openai(gpt-4o), { cacheKey: my-key, cacheTtl: 3600, metadata: { userId: u123, team: eng }, // 最多 5 个键 retries: { maxAttempts: 3, backoff: exponential } })Pattern 2OpenAI SDKDrop-in 替换如果你已经使用 OpenAI SDK只需替换baseURL即可把流量切到 AI Gateway并通过模型名格式{provider}/{model}在多个提供商之间切换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} // 开启鉴权的网关必填 } }); // 通过模型格式切换提供商 const response await client.chat.completions.create({ model: openai/gpt-4o, // 或 anthropic/claude-sonnet-4-5 messages: [{ role: user, content: Hello! }] });对应的 Anthropic SDK 写法为const client new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/anthropic, defaultHeaders: { cf-aig-authorization: Bearer ${cfToken} } });Pattern 3Cloudflare Worker Workers AI Binding在 Worker 内部直接通过env.AI.run()调用模型并透传网关配置与元数据export default { async fetch(request, env, ctx) { const response await env.AI.run( cf/meta/llama-3-8b-instruct, { messages: [{ role: user, content: Hello! }] }, { gateway: { id: my-gateway, metadata: { userId: 123, team: engineering } } } ); return Response.json(response); } };对应的wrangler.toml配置需要声明[ai]binding 并挂载网关# wrangler.toml [ai] binding AI [[ai.gateway]] id my-gateway需要注意使用 Workers AI 时本地开发无法加载模型必须使用wrangler dev --remote运行部署则执行wrangler deploy详见 workers-ai README。Pattern 4直接 HTTP任意语言不依赖任何 SDK直接以 cURL 调用 OpenAI 兼容端点即可网关鉴权头与元数据头都放在 HTTP Header 中curl https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/chat/completions \ -H Authorization: Bearer $OPENAI_KEY \ -H cf-aig-authorization: Bearer $CF_TOKEN \ -H cf-aig-metadata: {\userId\:\123\} \ -d {model:gpt-4o,messages:[...]}框架接入LangChain / LlamaIndex使用框架时复用 OpenAI SDK 的 baseURL 替换方案即可。例如 LangChain 的ChatOpenAInew ChatOpenAI({ configuration: { baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai } });请求头快速参考Header用途示例说明cf-aig-authorization网关鉴权Bearer {token}开启鉴权的网关必填cf-aig-metadata追踪/元数据{userId:x}最多 5 个键扁平结构不可嵌套cf-aig-cache-ttl缓存时长3600秒最小 60最大 259200030 天cf-aig-skip-cache跳过缓存true—cf-aig-cache-key自定义缓存键my-key每种预期响应需使用唯一键cf-aig-collect-log跳过日志false默认true即默认采集日志cf-aig-cache-status缓存命中/未命中仅响应返回值为HIT或MISS网关创建、配置与鉴权创建网关控制台方式AI AI Gateway Create Gateway随后配置鉴权、缓存、限流、日志等选项。API 方式调用 Cloudflare 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}网关管理 API创建后可对网关做完整的增删改查# 列出网关 curl https://api.cloudflare.com/client/v4/accounts/{account_id}/ai-gateway/gateways \ -H Authorization: Bearer $CF_API_TOKEN # 获取单个网关 curl .../gateways/{gateway_id} # 更新网关配置 curl -X PUT .../gateways/{gateway_id} \ -d {cache_ttl:7200,rate_limiting_limit:200} # 删除网关 curl -X DELETE .../gateways/{gateway_id}Wrangler 集成与密钥管理在 Worker 项目中通过 wrangler 写入所需密钥wrangler secret put CF_API_TOKEN wrangler secret put OPENAI_API_KEY # 未使用 BYOK 时必填网关类型与提供商鉴权选项网关本身分两种类型未鉴权网关Unauthenticated开放访问不推荐用于生产鉴权网关Authenticated要求请求携带cf-aig-authorization头值为 Cloudflare API Token推荐。而面向各 AI 提供商的鉴权有三种可选方案方案说明接入方式Unified Billingkeyless通过 Cloudflare 统一计费支付推理费用无需提供商 API Key只带cf-aig-authorization头支持 OpenAI、Anthropic、Google AI StudioBYOKStore Keys在 Cloudflare 控制台 Provider Keys 区域存储提供商密钥代码中不出现密钥无需在代码里配置密钥Request Headers每次请求时携带提供商密钥在请求中附加提供商的鉴权头采用 Unified Billing 或 BYOK 的 TypeScript 客户端写法如下const client new OpenAI({ baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai, defaultHeaders: { cf-aig-authorization: Bearer ${cfToken} } });注意BYOK 与 Unified Billing 互斥只能二选一。需要每次请求携带提供商密钥时则使用apiKey: process.env.OPENAI_API_KEY配合相同的 baseURL 与cf-aig-authorization头。API Token 权限网关管理Gateway management需要 AI Gateway 的 Read Edit 权限网关访问Gateway access至少需要 AI Gateway 的 Read 权限。Python 示例AI Gateway 同样适用于 Python 生态替换 OpenAI SDK 的base_url即可from openai import OpenAI import os client OpenAI( api_keyos.environ.get(OPENAI_API_KEY), base_urlfhttps://gateway.ai.cloudflare.com/v1/{os.environ[CF_ACCOUNT_ID]}/{os.environ[GATEWAY_ID]}/openai, default_headers{cf-aig-authorization: fBearer {os.environ[CF_API_TOKEN]}} )配置最佳实践生产环境始终开启网关鉴权优先使用 BYOK 或 Unified Billing把密钥移出代码按环境拆分网关dev/staging/prod 各自独立设置限流防止成本失控开启日志便于用量追踪与问题排查。核心能力缓存、限流、护栏、DLP 与日志原文档的 features.md 详细列出了 AI Gateway 的进阶能力均可在控制台 Gateway → Settings 中开启。响应缓存Caching控制台开启路径Settings → Cache Responses → Enable。也可以逐请求通过请求头控制// 自定义 TTL1 小时 headers: { cf-aig-cache-ttl: 3600 } // 跳过缓存 headers: { cf-aig-skip-cache: true } // 自定义缓存键 headers: { cf-aig-cache-key: greeting-en }限制与注意TTL 取值范围为 60 秒至 30 天缓存与流式输出streaming不兼容。此外请求参数不同如 temperature 不同、或控制台未开启缓存都会导致缓存不生效可用响应头cf-aig-cache-status判断命中情况HIT/MISS。限流Rate Limiting控制台开启路径Settings → Rate-limiting → Enable。支持两种窗口算法Fixed window固定窗口按固定时间间隔重置Sliding window滑动窗口滚动窗口更精确。超过配额时返回 HTTP429。注意限流范围是按网关维度而非按用户维度若需按用户/团队细分配额应使用动态路由中的 Rate Limit 节点。护栏Guardrails控制台开启路径Settings → Guardrails → Enable。用于过滤不当内容的提示词/响应动作可选Flag仅记录或Block拒绝。数据防泄漏DLP控制台开启路径Settings → DLP → Enable。用于检测 PII邮箱、SSN、信用卡号等敏感信息动作可选Flag / Block / Redact打码。计费模式模式说明配置方式Unified Billing通过 Cloudflare 计费无需提供商密钥仅使用cf-aig-authorization头BYOK提供商密钥存储在控制台在 Provider Keys 区域添加密钥Pass-through每次请求携带提供商密钥在请求中附加提供商的鉴权头零数据保留Zero Data Retention控制台开启路径Settings → Privacy → Zero Data Retention。开启后不存储任何提示词与响应内容但请求计数与成本统计仍然保留。日志与自定义元数据控制台开启路径Settings → Logs → Enable支持最多 1000 万条日志。每条日志包含提示词、响应、提供商、模型、token 数、成本、时长、缓存状态与元数据。逐请求跳过日志// 跳过本请求的日志 headers: { cf-aig-collect-log: false }日志导出可通过Logpush推送到 S3、GCS、Datadog、Splunk 等目标。注意日志存在 3060 秒的延迟属正常现象。自定义成本追踪对不在 Cloudflare 定价库中的模型可在控制台 Gateway → Settings → Custom Costs 中配置或通过 API 设置model、input_cost、output_cost。支持的提供商22提供商统一 API 写法说明OpenAIopenai/gpt-4o完整支持Anthropicanthropic/claude-sonnet-4-5完整支持Google AIgoogle-ai-studio/gemini-2.0-flash完整支持Workers AIworkersai/cf/meta/llama-3原生支持Azure OpenAIazure-openai/*使用部署名AWS Bedrock仅提供商端点/bedrock/*Groqgroq/*快速推理Mistral、Cohere、Perplexity、xAI、DeepSeek、Cerebras完整支持—能力最佳实践对确定性提示词开启缓存设置限流防止滥用面向用户的 AI 启用护栏涉及敏感数据启用 DLP使用统一计费或 BYOK 简化密钥管理开启日志便于调试需要隐私合规时启用零数据保留。动态路由无代码变更的复杂路由编排AI Gateway 的 dynamic-routing.md 展示了如何在不改代码的前提下用路由名替代模型名完成复杂路由const response await client.chat.completions.create({ model: dynamic/smart-chat, // 控制台配置的路由名 messages: [{ role: user, content: Hello! }] });节点类型节点用途典型场景Conditional基于元数据分支付费/免费用户分流、地域路由Percentage按比例切分流量模型测试、渐进式发布Rate Limit配额控制按用户/团队限流Budget Limit成本配额按用户设置花费上限Model调用提供商路由终点元数据Metadata通过cf-aig-metadata头传递最多 5 个键、只能扁平结构、值仅限 string/number/boolean/nullheaders: { cf-aig-metadata: JSON.stringify({ userId: user-123, tier: pro, region: us-east }) }常见路由模式多模型回退Start → GPT-4 → On error: Claude → On error: Llama分级访问tiered accessConditional: tier enterprise → GPT-4 (无限制) Conditional: tier pro → Rate Limit 1000/hr → GPT-4o Conditional: tier free → Rate Limit 10/hr → GPT-4o-mini渐进式发布Percentage: 10% → 新模型, 90% → 旧模型基于成本的回退Budget Limit: $100/day per teamId 80%: GPT-4 80%: GPT-4o-mini 100%: 报错版本管理与监控变更可保存为新版本用model: dynamic/routev2指定版本进行测试通过部署上一版即可回滚监控入口Dashboard → Gateway → Dynamic Routes可查看每条路径的请求数、成功/错误率、延迟与成本。动态路由限制元数据最多 5 个键且仅限 string/number/boolean/null不支持嵌套对象路由名只能使用字母数字与连字符。故障排查与调试原文档的 troubleshooting.md 汇总了常见错误与排查路径。常见错误对照表错误原因修复401缺少cf-aig-authorization头添加携带 CF API Token 的该请求头403提供商密钥无效 / BYOK 密钥过期在控制台检查提供商密钥429超过限流调高限额或实现退避重试401 的修复方式const client new OpenAI({ baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai, defaultHeaders: { cf-aig-authorization: Bearer ${CF_API_TOKEN} } });429 的指数退避重试模式async function requestWithRetry(fn, maxRetries 3) { for (let i 0; i maxRetries; i) { try { return await fn(); } catch (e) { if (e.status 429 i maxRetries - 1) { await new Promise(r setTimeout(r, Math.pow(2, i) * 1000)); continue; } throw e; } } }常见坑Gotchas问题实际情况元数据限制最多 5 个键、仅扁平结构不可嵌套缓存键冲突每种预期响应必须使用唯一键BYOK Unified Billing互斥不可同时使用限流范围按网关而非按用户按用户请用动态路由日志延迟3060 秒属正常流式 缓存不兼容统一 API 模型名必须带提供商前缀openai/gpt-4o不能只写gpt-4o缓存不生效排查可能原因请求参数不同如 temperature、开启了流式、或控制台未启用缓存。检查方式// 检查响应头 console.log(Cache:, response.headers.get(cf-aig-cache-status)); console.log(Request ID:, response.headers.get(cf-ray));日志不出现排查确认控制台 Dashboard → Gateway → Settings 已开启日志移除cf-aig-collect-log: false请求头等待 3060 秒检查日志上限默认 1000 万条。连通性测试与分析# 测试连通性 curl -v https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/models \ -H Authorization: Bearer $OPENAI_KEY \ -H cf-aig-authorization: Bearer $CF_TOKEN分析面板入口Dashboard → AI Gateway → 选择网关。可观测指标包括请求数、token 数、延迟p50/p95/p99、缓存命中率与成本日志支持过滤表达式如status: error、provider: openai、cost 0.01、duration 1000数据可通过 Logpush 导出至 S3/GCS/Datadog/Splunk。在 Cloudflare 技术栈中的位置在本仓库的 Cloudflare Deploy 技能中AI Gateway 是 AI/ML 场景的关键一环与周边服务协同使用在 workers-ai 之上提供面向任意提供商的网关能力其 README 亦将 AI Gateway 列为缓存、限流与分析的关键配套与 agents-sdk 配合可构建有状态 AI Agent 模式与 vectorize 配合可实现基于嵌入向量的 RAG 模式。整体部署流程鉴权、wrangler使用可参考 SKILL.md 与仓库中 wrangler 相关参考文档。推荐的阅读顺序任务建议文件首次搭建README.md configuration.mdSDK 集成README.md sdk-integration.md开启缓存README.md features.md配置回退路由README.md dynamic-routing.md调试错误README.md troubleshooting.md本仓库中完整的参考文件包括sdk-integration.mdVercel AI SDK / OpenAI SDK / Workers binding 模式、configuration.md控制台配置、wrangler、API Token、features.md缓存、限流、护栏、DLP、BYOK、统一计费、dynamic-routing.md回退、A/B 测试、条件路由与 troubleshooting.md调试、错误、可观测性、常见坑。此外与 Workers AI 绑定相关的env.AI.run()细节可参考 workers-ai 参考文档。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考