Flue + Cloudflare Workers AI：免API Key的内置AI网关详解

Flue + Cloudflare Workers AI：免API Key的内置AI网关详解

【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue

Flue 是运行在 Cloudflare Workers 上的 AI Agent 框架，它的杀手级特性是：内置 AI 网关，全程免 API Key。你不需要向任何模型厂商申请密钥、不需要在配置里存放秘密——一行代码声明模型，所有 AI 调用就自动走 Cloudflare 自家的 Workers AI 与 AI Gateway，授权和计费直接跟随你的 Workers 账号，还有每日免费额度可用。

为什么可以跳过 API Key？

传统做法是：注册模型厂商账号 → 申请 API Key → 存入环境变量或密钥管理服务 → 代码里读密钥发起 HTTP 调用。任何一步出错，Agent 就跑不起来。

Flue 在 Cloudflare 目标环境下走了一条完全不同的路：

• 自动注册cloudflare内置 provider：当你的项目部署到 Cloudflare 时，cloudflare/...这类模型前缀开箱即用，无需任何额外配置；
• 不经过 HTTP，走 Workers AI 绑定：模型调用通过 Worker 环境的env.AI.run(...)完成，绑定本身就是一份"凭证"——授权和计费跟随 Worker 本体（详见 workers-ai-provider.ts 中"Keyless: the binding itself is the credential"的设计）；
• 没有密钥，就没有密钥泄露：不需要配置 secret、不需要担心.env泄露、团队协作零门槛。

计费按 Workers AI 的 Neurons 单位、跟随你的 Cloudflare 账号结算，并带有每日免费额度，对新手非常友好。

快速上手：三步配置方法

第 1 步：声明 AI 绑定

在项目根目录的wrangler.jsonc中加一段配置即可，参考示例项目 wrangler.jsonc：

{ "ai": { "binding": "AI" } }

第 2 步：一行代码声明模型

一个 Flue Agent 就是一个带'use agent'指令的普通 TypeScript 函数，参考 with-cloudflare-binding.ts：

'use agent'; import { useModel } from '@flue/runtime'; export function Assistant() { useModel('cloudflare/@cf/moonshotai/kimi-k2.6'); return 'You process direct requests using a Cloudflare Workers AI binding.'; }

cloudflare/之后的一切都会原样作为模型 ID 传给 Workers AI——既可以是@cf/...的托管模型，也可以是网关模型 ID（如openai/gpt-5.5）。

第 3 步：本地开发与部署

npx vite dev # 本地 workerd 运行 npx vite build # 构建 npx wrangler deploy # 部署

全程无需wrangler secret put，因为你根本没有任何密钥可存。

内置 AI 网关：免费获得的三大能力

默认情况下，每一次cloudflare/...调用都会自动经过 Cloudflare 的 AI Gateway（网关 ID 为default），你零配置就获得了：

如果你需要更精细的调优，可以在app.ts中用 cloudflareBindingProvider 覆盖默认网关（用户注册优先于生成的默认配置）：

setProvider( cloudflareBindingProvider({ binding: env.AI, gateway: { id: 'my-gateway', cacheTtl: 300, metadata: { tenant: 'acme' } }, // ...或 gateway: false 完全绕过 AI 网关 }), );

网关支持的选项（完整定义见 gateway.ts）：

• id：指定网关 ID；
• skipCache/cacheTtl/cacheKey：缓存行为控制；
• metadata/collectLog/eventId：日志与关联标识；
• requestTimeoutMs：对首个响应分片的时限约束（通过cf-aig-request-timeout头下发）。

模型怎么选？两种前缀的差别

一个容易混淆的点：cloudflare/openai/gpt-5.5是通过 Cloudflare 计费的，而openai/gpt-5.5走的是你自己的 OpenAI 密钥——写法只差一个前缀，账单归属完全不同。

生产级可靠性：框架替你兜底

Flue 的 Workers AI 通道内置了多项稳定性机制，新手无需感知细节：

• ⏱️流空闲超时：模型流超过 5 分钟（默认）没有吐出一个字节，请求会失败并按可重试错误自动重试，避免"返回 200 后再也不说话"的悬挂流；
• 🔄截断即重试：SSE 流异常中断（无结束帧）会被识别为传输层瞬时故障，安全重试而不是污染会话；
• 📌会话亲和：通过x-session-affinity头把同一会话的请求钉在相同模型实例上，让厂商侧的前缀缓存生效；
• 🔍精确的网关日志关联：每条响应读取自身的cf-aig-log-id头，并发下也不会把日志记错请求。

小结

一句话总结：Flue 把"连接 AI"这件事从密钥管理问题降级成了一个字符串前缀——在 Cloudflare 上部署 Agent，模型调用天然自带网关、缓存、日志与免费额度。

进一步阅读：

• 模型选择与 provider 机制：models.md
• Cloudflare 部署完整指南：deploy/cloudflare.md
• Cloudflare 官方示例项目：examples/cloudflare/
• 内置 provider 源码：packages/runtime/src/cloudflare/

【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue