本 Cloudflare Workers AI 教程将向您展示如何直接在 Cloudflare 的全球边缘网络上部署和运行机器学习模型。借助 Cloudflare Workers AI ，您可以在靠近用户的地方执行大型语言模型（LLMs）、文本翻译、图像生成和语音转文字，而无需管理复杂的 GPU 服务器。以下步骤涵盖了如何配置 Wrangler、编写 fetch 处理程序、运行 Llama 模型以及优化边缘 API 成本。

TL;DR

  • 无服务器运行 AI 模型；Cloudflare Workers AI 管理底层 GPU 基础设施，仅按活跃计算量计费。
  • 在 wrangler.toml 中配置绑定（bindings）；直接将您的 worker 链接到 AI 绑定，无需管理 API 密钥。
  • 编写 fetch 处理程序以接收用户请求、执行模型并以流式传输 JSON 响应。
  • 选择经过优化的模型从 Cloudflare 的目录中（例如 Llama 3、Whisper 或 Stable Diffusion）以平衡速度和准确性。
  • 限制计费和速率限制，以防止您的端点在生产环境中受到高 token 成本滥用。

为什么要在边缘运行 AI 模型？

传统上，集成 AI 功能需要调用外部 API（例如 OpenAI）或在昂贵的云服务器上托管开源模型。

调用外部 API 存在延迟和数据隐私问题。运行您自己的 GPU 服务器会带来维护挑战且扩展性差。Cloudflare Workers AI 解决了这一难题。该平台在部署于 Cloudflare 全球网络的 GPU 上托管开源模型。您的代码作为一个轻量级的 Worker 运行，在靠近用户的地方执行模型，延迟几乎为零。有关构建基础边缘结构的介绍，请阅读我们关于使用 Cloudflare Workers 构建无服务器 API 的指南。

前提条件

在开始之前，请确保您具备以下条件：

  • 一个 Cloudflare 帐户并已启用 Workers。免费计划包含每日推理额度，这对于跟随本指南已绰绰有余。
  • Node.js 18 或更高版本已安装在本地，以便您可以运行工具和本地开发服务器。
  • **已安装并认证 Wrangler（Workers CLI）。**使用 npm install -g wrangler 进行安装，然后运行 wrangler login 将其链接到您的帐户。
  • 熟悉 JavaScript 基本语法以及每个 Worker 赖以构建的 fetch 请求/响应模型。

如果您是从零开始，请使用 create-cloudflare (C3) 工具搭建项目。它会生成一个可部署的 Worker、一个 wrangler.toml 和一个合理的 compatibility_date：

1npm create cloudflare@latest my-edge-ai
2cd my-edge-ai

在提示时选择 “Hello World” Worker 模板。这将为您提供一个干净的起点，您可以在下一步中向其添加 AI 绑定。

步骤 1：配置 wrangler.toml

要访问 AI 模型，您首先需要在项目的配置文件中定义 AI 绑定。

打开您的 wrangler.toml（或 wrangler.json）并添加以下块：

1[ai]
2binding = "AI"

此绑定使 AI 服务在您的 worker 代码中的环境参数（env.AI）上可用。您无需管理 API 密钥、配置端点或处理连接字符串。Wrangler 会在您部署时自动处理身份验证。

此项目的完整 wrangler.toml 如下所示：

1name = "my-edge-ai"
2main = "src/index.js"
3compatibility_date = "2025-01-01"
4
5[ai]
6binding = "AI"

compatibility_date 很重要：它锁定了运行时行为，因此未来的平台更改不会悄悄改变您的 Worker 运行方式。遗漏它，部署就会因配置错误而失败，这是最常见的初次运行挫折之一。

步骤 2：编写 Worker 代码

配置好绑定后，您就可以从 fetch 处理程序中调用 AI 服务了。下面的示例展示了如何接收包含用户提示的 JSON 负载，并使用 Llama 3 生成文本补全。

 1export default {
 2  async fetch(request, env) {
 3    if (request.method !== "POST") {
 4      return new Response("Method not allowed", { status: 405 });
 5    }
 6
 7    try {
 8      const { prompt } = await request.json();
 9      if (!prompt) {
10        return Response.json({ error: "Missing prompt" }, { status: 400 });
11      }
12
13      // Call the model using the AI binding
14      const response = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
15        prompt: prompt,
16        max_tokens: 256
17      });
18
19      return Response.json(response);
20    } catch (err) {
21      return Response.json({ error: err.message }, { status: 500 });
22    }
23  }
24};

这种简单的结构允许您构建文本摘要器、情感分析工具或内容生成器。如果您想将这些功能连接到您的数据库，可以绑定到无服务器 SQL 数据库；详情请参阅 Cloudflare D1 数据库设置 。

使用对话消息格式

prompt 字段便于单次补全，但对话模型在使用结构化的 messages 数组时表现最佳。这允许您设置决定模型语气的系统指令，并将其与用户的输入区分开来：

 1const messages = [
 2  { role: "system", content: "You are a concise technical assistant." },
 3  { role: "user", content: prompt }
 4];
 5
 6const response = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
 7  messages,
 8  max_tokens: 512
 9});
10
11// Text models return the generated text on the `response` property
12return Response.json({ answer: response.response });

请注意，文本生成模型将其输出包裹在 response 字段中，因此补全的文本位于 response.response 而不是顶级。这难倒了许多初次使用的用户，他们记录原始对象并看到了意想不到的结构。

选择合适的模型

Cloudflare 的目录包含数十种模型，选择合适的模型需要在速度、质量和成本之间进行权衡。较小的模型回复更快，消耗的资源更少；较大的模型推理更好，但每次请求的成本更高。下表对比了几种流行的文本生成模型。

模型最适合相对速度相对成本
@cf/meta/llama-3-8b-instruct通用对话、摘要快低
@cf/meta/llama-3.1-70b-instruct复杂推理、长篇回答较慢较高
@cf/mistral/mistral-7b-instruct-v0.2轻量指令、草稿快低
@cf/meta/llama-guard-3-8b审核和分类内容快低

作为经验法则，先从 8B 模型开始，如 Llama 3 8B Instruct。它能够以 70B 模型几分之一的延迟和成本处理大部分摘要、分类和对话工作流。只有当您自己的评估表明较小的模型确实无法满足需求时，才升级到更大的模型。

步骤 3：流式传输响应以获得更好的用户体验

对于聊天应用，等待生成完整响应可能会导致糟糕的用户体验。

您可以配置 AI 绑定，以便在生成响应时逐个 token 地进行流式传输。为此，请在请求选项中传递 stream: true。worker 将返回一个 ReadableStream，您可以将其直接转发给浏览器客户端，从而创建一个快速的交互式聊天界面。要将此边缘运行时方法与传统云托管进行对比，请阅读我们对 Cloudflare Workers 与 AWS Lambda 的对比。

这是一个完整的流式传输处理程序。您不需要返回解析后的 JSON，而是以正确的 content-type 将流转发给客户端，以便浏览器可以将其作为 Server-Sent Events 进行消费：

 1export default {
 2  async fetch(request, env) {
 3    const { prompt } = await request.json();
 4
 5    const stream = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
 6      prompt,
 7      max_tokens: 512,
 8      stream: true
 9    });
10
11    return new Response(stream, {
12      headers: { "content-type": "text/event-stream" }
13    });
14  }
15};

与非流式传输版本的主要区别在于响应本身：您直接将流传入 new Response() 并将 content-type 设置为 text/event-stream。如果将流包裹在 Response.json() 中，它将无法正确序列化，客户端将收到一个空的主体。

测试和部署您的 Worker

配置好绑定和处理程序后，在发布之前在本地运行 Worker：

1npx wrangler dev

由于推理运行在 Cloudflare 的 GPU 上，而不是您的本地机器上，因此即使在本地开发期间，AI 绑定也会访问网络。Wrangler 会为您管理这一点，但这意味着本地测试需要网络连接和有效的登录信息才能运行。

在 wrangler dev 运行时使用 curl 发送测试请求：

1curl -X POST http://localhost:8787 \
2  -H "Content-Type: application/json" \
3  -d '{"prompt": "Summarise the benefits of edge computing in one sentence."}'

一旦您对输出满意，就部署到全球网络：

1npx wrangler deploy

Wrangler 会上传您的 Worker 并返回一个 *.workers.dev URL。您的端点现已在每个 Cloudflare 数据中心上线，每个请求都会被自动路由到离用户最近的位置。

常见陷阱和疑难解答

团队首次在边缘部署推理时，会反复遇到一些问题。提前知道解决办法可以节省数小时的调试时间。

  • Cannot read properties of undefined (reading 'run') —— env.AI 绑定未定义。这几乎总是意味着 wrangler.toml 中遗漏了 [ai] 块，或者您编辑了文件但没有重启 wrangler dev（或重新部署）。确认绑定名称完全匹配。
  • No such model 或 run 时出现 400 错误 —— 模型标识符错误。模型名称区分大小写，且必须包含完整路径，例如 @cf/meta/llama-3-8b-instruct。请从模型目录中复制它们，而不是凭记忆输入。
  • 空或格式错误的流式传输响应 —— 您通过 Response.json() 返回了流，而不是 new Response(stream, ...)。流必须转发，不能序列化。
  • 负载下的容量或 429 错误 —— 模型暂时饱和，或者您已达到帐户限制。添加带有退避（back-off）的短重试，并考虑使用较小的模型应对突发流量。
  • 截断的回答 —— 由于 max_tokens 太低，回复在句子中途停止。调高限制，但请记住，较大的值会增加延迟和成本。

如果请求静默失败，在发送测试请求时使用 npx wrangler tail 观察实时日志。它会从部署的 Worker 流式传输运行时错误和 console.log 输出。

优化生产成本和安全

虽然 Workers AI 极具性价比，但在生产环境中运行模型推理需要仔细控制。

  • 实施速率限制：限制客户端调用端点的频率。GPU 计算成本随使用量增加而增加。
  • 清理提示词：验证输入以防止提示注入攻击，并确保模型输出符合品牌形象。
  • 限制上下文大小：保持提示历史简短。在每次调用中发送庞大的上下文缓存会增加 token 处理成本。

有关上下文管理的详细了解，请参阅我们关于构建 OpenAI API 聊天机器人 的指南。

核心要点

  • Cloudflare Workers AI 提供了对开源模型的无服务器访问，无需维护 GPU。
  • 通过在 wrangler.toml 中添加 [ai] 绑定块来配置访问。
  • 编写 fetch 处理程序，直接在边缘执行文本生成、翻译或图像任务。
  • 通过设置 stream: true 启用 token 流式传输，以优化移动和聊天体验。
  • 实施速率限制和提示词清洗，以在生产中保护您的边缘端点。

在边缘构建您的 AI 应用

构建可靠的 AI 集成需要无服务器架构方面的专家知识。Mecanik 专注于通过我们的 OpenAI API 集成服务 提供专业的 AI 集成服务 和定制 API 设置。我们构建能无缝扩展的边缘原生工具，优化成本和用户体验。今天就联系我们的安全专家讨论您的项目需求。

常见问题（FAQ）

什么是 Cloudflare Workers AI？ 它是一个无服务器平台，允许您在 Cloudflare 的全球 GPU 网络上运行机器学习模型（文本生成、翻译、语音转文字、图像生成）。

我需要 API 密钥来使用 Workers AI 吗？ 不需要。一旦您在 wrangler.toml 文件中声明了 AI 绑定，Cloudflare 就会在内部处理凭据，使该服务可以通过 env.AI 访问。

Cloudflare Workers AI 上有哪些模型可用？ 该平台托管了流行的开源模型，包括 Meta Llama、Mistral、OpenAI Whisper 和 Stable Diffusion，这些模型会定期在其模型目录中更新。

我可以从 Workers AI 流式传输文本响应吗？ 可以。通过在 env.AI.run 调用的参数中设置 stream: true，worker 会返回一个标准的 ReadableStream 以将文本流式传输到浏览器。

Workers AI 的计费是如何工作的？ 计费基于处理的 token 数量（对于文本模型）或计算时间的持续时间（对于其他模型），提供了一种经济高效的实用模型。