企业官网建设流程全解析

导读

Cloudflare AI Gateway 是一个面向 AI 模型提供商的统一网关，在应用与 OpenAI、Anthropic、Google AI Studio、Workers AI 等上游模型之间提供代理层，统一承载缓存、限流、动态路由、日志与观测能力。本文以 autoskills 仓库中 AI Gateway SDK 集成参考 为骨架，系统讲解 Vercel AI SDK、OpenAI SDK、Anthropic SDK、Workers AI Binding、LangChain/LlamaIndex 以及裸 HTTP 六种接入方式，并深入剖析网关 URL 结构、认证机制、控制头与常见故障。读完本文，你将能在一小时内把任意主流 AI 应用改造成走 Cloudflare AI Gateway，并直接复用 配置参考 与 故障排查参考 中的生产级实践。

为什么需要 AI Gateway：一条通往所有模型提供商的统一通道

在 autoskills 的 Cloudflare 平台技能中，AI Gateway 被定位为"任何 AI 提供商的网关（缓存、路由）"，与 Workers AI、Vectorize、Agents SDK 并列构成 Cloudflare 的 AI 能力矩阵（见 SKILL.md 中的 "Need AI?" 决策树）。它解决的问题很直接：当你的应用需要调用多家模型（GPT、Claude、Llama、Gemini…）时，不再为每家 SDK 分别维护客户端、密钥与重试逻辑，而是统一收敛到一条网关地址：

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

网关暴露三类 URL 模式（详见 README.md）：

所有 SDK 集成的本质，都是把baseURL（或等价配置）指向上述某个端点，再通过cf-aig-*系列请求头把网关级能力（认证、缓存、元数据）传递给网关。

方式一：Vercel AI SDK（官方推荐路径）

Vercel AI SDK 是本文档标注的 Recommended 方案，使用官方ai-gateway-provider包，它把网关包装成 Vercel AI SDK 的LanguageModel提供商，从而无缝接入generateText、streamText等核心 API。

安装依赖：

npm install ai-gateway-provider ai @ai-sdk/openai @ai-sdk/anthropic

初始化与单模型调用：

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, apiKey: process.env.CF_API_TOKEN // Optional for auth gateways }); const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY }); // Single model const { text } = await generateText({ model: gateway(openai('gpt-4o')), prompt: 'Hello' });

自动回退数组：一次调用，多重保障

gateway()接受模型数组，网关会自动按顺序尝试：主模型失败时回退到下一个模型，实现零代码的多模型容灾：

// Automatic fallback array const { text } = await generateText({ model: gateway([ openai('gpt-4o'), anthropic('claude-sonnet-4-5'), openai('gpt-4o-mini') ]), prompt: 'Complex task' });

配合 动态路由参考 中的"多模型回退"模式（Start → GPT-4 → On error: Claude → On error: Llama），你可以在 SDK 侧（代码内回退数组）与网关侧（dashboard 动态路由）两层分别实现故障转移。

每请求级 Options

gateway()的第二个参数支持按请求粒度覆盖缓存与重试行为：

model: gateway(openai('gpt-4o'), { cacheKey: 'my-key', cacheTtl: 3600, metadata: { userId: 'u123', team: 'eng' }, // Max 5 entries retries: { maxAttempts: 3, backoff: 'exponential' } })

参数说明（对应底层cf-aig-*头，详见文末 Headers Reference）：

值得注意的是，网关缓存不支持流式响应（streaming 与 caching 不兼容，见 troubleshooting.md 的 Gotchas 表），若你的场景需要streamText请关闭缓存或跳过缓存键。

方式二：OpenAI SDK（多提供商统一 API）

OpenAI SDK 是"换汤不换药"的接入方式：保持 SDK 不变，仅改baseURL指向网关的 OpenAI 兼容端点，并附加网关认证头：

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`, defaultHeaders: { 'cf-aig-authorization': `Bearer ${cfToken}` } }); // Unified API - switch providers via model name model: 'openai/gpt-4o' // or 'anthropic/claude-sonnet-4-5'

关键要点：

• 模型名必须带提供商前缀：统一 API 下必须写openai/gpt-4o而不是gpt-4o，前缀决定了请求被路由到哪家上游（这是 troubleshooting.md Gotchas 表中明确标注的常见坑）。
• 切换提供商零代码改动：把model从openai/gpt-4o换成anthropic/claude-sonnet-4-5即可在 OpenAI 与 Anthropic 之间切换，客户端本身无需重建。
• apiKey 与网关认证是两回事：apiKey用于上游提供商鉴权，cf-aig-authorization用于网关鉴权。若开启 Unified Billing（keyless 模式），甚至可以省略提供商密钥。

方式三：Anthropic SDK

Anthropic 官方 SDK 同样支持通过baseURL指向网关的 Anthropic 原生端点：

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}` } });

URL 中的路径段/anthropic即上一节 URL 模式表中的"提供商原生端点"，网关会原样代理到 Anthropic API。除 TypeScript 外，configuration.md 还给出了等价的 Python 示例，使用openai客户端 +base_url指向/openai端点，配合default_headers={"cf-aig-authorization": ...}，因此该模式在 Python 生态同样成立。

方式四：Workers AI Binding（Cloudflare Workers 原生集成）

如果你的推理目标是 Cloudflare 自家的 Workers AI 模型（如@cf/meta/llama-3-8b-instruct），无需自定义 HTTP 客户端——直接在wrangler.toml声明 AI binding 与网关关联：

# wrangler.toml [ai] binding = "AI" [[ai.gateway]] id = "my-gateway"

然后在 Worker 中通过env.AI.run()调用，并把网关选项作为第三参数传入：

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

该模式与 SKILL.md 决策树中的"Run inference → workers-ai/" 路径衔接——autoskills 检测到wrangler、wrangler.toml、@astrojs/cloudflare或@cloudflare/ai（AI binding）时会为项目安装 Cloudflare 技能，其中就包含本 AI Gateway 参考（见 autoskills README.md 的 Cloud & Deploy 检测表）。需要注意，Workers AI 在网关中的统一 API 前缀为workersai/@cf/meta/llama-3（见 features.md 的提供商列表）。

方式五：LangChain / LlamaIndex

LangChain 等框架没有专属网关适配器，但因其底层普遍支持 OpenAI 兼容接口，直接复用"OpenAI SDK 模式 + 自定义 baseURL"即可：

// Use OpenAI SDK pattern with custom baseURL new ChatOpenAI({ configuration: { baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai` } });

配合统一 API 的{provider}/{model}命名（openai/gpt-4o、anthropic/claude-sonnet-4-5、google-ai-studio/gemini-2.0-flash等），LangChain 链路也能享受网关的缓存、限流与日志能力。

方式六：HTTP / cURL（任意语言直连）

任何语言、任何 HTTP 客户端都可以直接调用网关，适合脚本验证、无 SDK 环境或边缘调试：

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":[...]}'

三个请求头分别对应：上游提供商密钥（Authorization）、网关认证令牌（cf-aig-authorization）、追踪元数据（cf-aig-metadata）。这也是 troubleshooting.md 推荐的连通性验证方式：curl -v .../openai/models可快速区分 401（网关认证失败）与 403（提供商密钥问题）。

请求头参考

所有 SDK 方式最终都映射到同一组网关控制头。以下是 sdk-integration.md 与 README.md 中请求头参考表的合并完整版：

其中cf-aig-cache-status是排查"缓存不生效"的首要工具：在响应头读到MISS时，依次检查请求参数是否一致（如 temperature 不同）、是否开启流式、网关设置里缓存是否启用（见 troubleshooting.md 的 "Cache Not Working" 一节）。

认证模型：网关认证 × 提供商认证

集成时最易混淆的是两层认证。网关本身分两类（README.md）：

1. 未认证网关（Unauthenticated）：开放访问，官方不建议用于生产；
2. 认证网关（Authenticated）：要求cf-aig-authorization: Bearer {Cloudflare API Token}，生产环境推荐。

提供商侧则有三选一的认证模式（configuration.md）：

注意：BYOK 与 Unified Billing互斥（见 Gotchas 表）。管理网关所需 API Token 权限为"AI Gateway - Read + Edit"（管理）或"AI Gateway - Read"（访问，最小权限）。网关的增删改查也可通过 Cloudflare 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}'

网关 ID 命名规则为小写字母数字加连字符（如prod-api、dev-chat）；Account ID 在 Dashboard 概览页获取，Gateway ID 在 AI Gateway 列表的网关名列获取。

进阶能力速览：让集成立刻具备生产级水位

完成 SDK 接入后，以下能力均在网关侧开箱即用，无需改动应用代码（详见 features.md）：

• 缓存（Caching）：Dashboard 开启后，对确定性 prompt 收益最大；支持自定义 TTL 与缓存键，但不适用于流式。
• 限流（Rate Limiting）：固定窗口 / 滑动窗口两种算法，超限返回429；注意限流是按网关维度而非按用户维度——需要 per-user 配额时应在动态路由里用 Rate Limit / Budget Limit 节点实现。
• Guardrails 与 DLP：内容安全过滤（Flag/Block）与 PII 检测（邮箱、SSN、信用卡，可 Flag/Block/Redact），面向用户的 AI 应用建议开启。
• 零数据保留（Zero Data Retention）：不存储任何 prompt/response，仍保留请求数与成本统计。
• 日志与观测：默认开启，每条日志含 prompt、response、provider、model、tokens、cost、duration、cache status、metadata；可在 Dashboard 按status: error、provider: openai、cost > 0.01、duration > 1000过滤，并可通过 Logpush 导出至 S3、GCS、Datadog、Splunk。
• 动态路由（Dynamic Routing）：用model: 'dynamic/smart-chat'引用 dashboard 中的路由名，即可实现按 tier 分流、百分比 A/B、预算回退等模式（dynamic-routing.md）。

常见故障速查

集成完成后若遇异常，优先对照 troubleshooting.md 的错误表：

对于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; } } }

调试时记得检查响应头：cf-aig-cache-status判断缓存命中，cf-ray获取请求 ID 用于日志关联。日志延迟 30–60 秒属正常现象，若长期不出现，先确认日志开关、移除cf-aig-collect-log: false头，再检查 10M 默认日志上限。

总结：一条接入路径覆盖全部 SDK 生态

本文围绕 sdk-integration.md 的六种接入方式展开：Vercel AI SDK 提供最现代的createAiGateway封装与自动回退数组；OpenAI / Anthropic SDK 通过替换baseURL即可完成迁移并借助统一 API 自由切换提供商；Workers AI Binding 让 Worker 内的env.AI.run()原生获得网关能力；LangChain 与裸 HTTP 则保证了框架与语言无关的覆盖面。所有方式共享同一组cf-aig-*控制头与网关 URL 结构，生产部署时遵循"认证网关 + BYOK/Unified Billing + 环境隔离网关 + 限流 + 日志"五条最佳实践（configuration.md），即可在缓存、限流、观测、容灾四个维度上一步到位。