本 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 數量（對於文本模型）或計算時間的持續時間（對於其他模型），提供了一種經濟高效的實用模型。