Workers AI 入門:在邊緣直接跑 AI 推論 | Cloudflare 完整教學

Cloudflare Workers AI 讓你不必自己租 GPU、不必架 GPU 伺服器,就能在全球邊緣節點直接執行機器學習推論(inference)。這一篇是 Workers AI 的第一課:我們會先講清楚什麼是「邊緣 GPU 推論」、怎麼在 wrangler.jsonc 設定 AI binding、模型目錄裡有哪些種類(LLM、embedding、影像、語音、分類)、怎麼寫出你的第一個 env.AI.run() 推論,並釐清 Neurons 計費、免費額度,以及它和 OpenAI 這類外部 API 的根本差異。

前言

前面一整條 CF-4 主線,我們把 Cloudflare 的非同步編排工具箱練得很熟:Queues 削峰扇出、Workflows 跑長流程、Durable Objects 做強一致協調。上一篇《非同步編排選型》,我們拉高視角,把三者放在同一張桌上比較,替「該用哪個原語」畫下句點。這一篇開始,我們正式踏進更上層的能力——AI 推論,也就是把前面學到的編排管線,接上真正的「智慧」。

先給一個乾淨的定義。Workers AI 是 Cloudflare 提供的**無伺服器 GPU 推論(serverless GPU inference)**服務:它把一批開源機器學習模型預先部署在 Cloudflare 全球 300+ 個邊緣資料中心的 GPU 上,讓你在 Worker 裡透過一個原生的 env.AI binding 直接呼叫,不必管理任何 GPU 基礎設施。你不用租顯卡、不用裝 CUDA、不用煩惱模型怎麼載入記憶體、更不用在流量尖峰時手動擴容——這些全部由 Cloudflare 的邊緣網路代勞。你要做的,只是選一個模型識別符、丟進去輸入、拿回結果。

打個比方。傳統上要跑 AI 推論,像是「自己在家蓋一座發電廠」:你得買發電機組(GPU)、接電網、請人維運、還要為用電尖峰預留冗餘,大部分時間機組閒置卻照樣付錢。Workers AI 則像是「插上牆上的插座就有電」:電廠(GPU 叢集)是 Cloudflare 蓋的、就近佈在你家附近的變電所(邊緣節點),你只按實際用電量(Neurons)付費,尖峰時電網自己調度,你完全不必知道電是怎麼發的。這種「把重資產抽象成一個 API 呼叫」的思路,正是無伺服器的精髓,而 Workers AI 把它延伸到了最吃資源的 GPU 推論上。

讀完你會掌握:

• 什麼是邊緣 GPU 推論——推論到底在哪裡跑、和你的 Worker 進程是什麼關係、為什麼延遲低
• AI binding 怎麼設定——wrangler.jsonc 一行宣告、TypeScript 型別、以及為什麼一定要 --remote
• 模型目錄有哪些種類——LLM、embedding、影像、語音、分類五大類與 @cf/... 命名規則
• 第一個 env.AI.run()——一段可執行的文字生成 Worker,從請求到回應完整跑通
• Neurons 計費與免費額度——怎麼算、每天免費多少、怎麼避免爆量
• 和 OpenAI 的根本差異——在哪裡跑、怎麼計費、什麼時候該選哪個

核心概念

要用好 Workers AI,得先搞懂三件事:推論在哪裡發生、模型怎麼命名分類、以及它和外部 API 的定位差異。這一節把觀念打底,下一節再動手寫程式碼。

一、什麼是邊緣 GPU 推論

先釐清「推論(inference)」這個詞。機器學習模型的生命週期分兩段:**訓練(training)**是用大量資料把模型「教會」,極度耗費算力,通常在集中的資料中心跑上幾天到幾週;推論(inference)則是拿訓練好的模型「回答問題」——你丟一段文字進去、它吐出生成結果或分類標籤。日常應用(聊天、翻譯、embedding、影像生成)幾乎都是推論。Workers AI 做的就是推論,模型已經幫你訓練好、部署好,你只管呼叫。

關鍵是「在哪裡」推論。傳統雲端 AI,推論集中在少數幾個大型資料中心;而 Workers AI 把模型部署到 Cloudflare 遍布全球的 300+ 個邊緣節點,請求落在哪個城市,就近在最近的 GPU 上跑推論,不必把資料繞到遙遠的中央機房再繞回來。這就是「邊緣推論」低延遲的來源。

有一點很容易誤會,一定要講清楚:推論並不是在你的 Worker 進程裡跑的。你的 Worker 程式碼跑在 V8 隔離區(isolate),那裡沒有 GPU。當你呼叫 env.AI.run(),這個 binding 其實是一個代理,它把你的請求路由到 Cloudflare 的 GPU 網路,由專門的 GPU 節點執行推論,再把結果回傳給你的 Worker。整條路徑大致是:

使用者請求
    │
    ▼
你的 Worker(V8 isolate,無 GPU)
    │  env.AI.run(model, input)  ← binding 只是代理
    ▼
Cloudflare GPU 網路(就近的邊緣 GPU 節點)
    │  實際載入模型、執行推論
    ▼
模型回應 → 回到你的 Worker

因為推論在獨立的 GPU 網路,有一個實務後果:模型首次載入有冷啟動(cold start),約 1–3 秒;之後模型快取在 GPU 記憶體裡,後續請求約 100–500ms。這跟 Worker 本身的冷啟動是兩回事,設計高延遲敏感的應用時要把它算進去。

二、模型目錄:@cf/... 命名與五大任務類型

Workers AI 提供 50+ 個開源模型,涵蓋各種任務。模型識別符(model ID)有固定格式:

@{provider}/{model-name}

例如 @cf/meta/llama-3.1-8b-instruct 代表 Cloudflare(cf)托管的 Meta Llama 模型;@hf/nousresearch/hermes-2-pro-mistral-7b 則來自 HuggingFace(hf)。這個字串要一字不差——打錯一個字,呼叫就會回錯誤碼 7502,這是新手最常踩的坑,後面會再提。

模型大致分成五大任務類型,下表列出每類的代表性模型(以你確定會用到的常見模型為主,完整清單以官方模型目錄為準):

理解這張表最有用的方式,是記住每一類的「輸入/輸出形狀」不同:LLM 吃 messages 或 prompt、吐文字;embedding 吃 text、吐向量陣列;影像生成吃 prompt、吐二進位圖片;語音辨識吃音訊、吐文字。也就是說,每個模型的 input 物件長什麼樣,取決於它的任務類型——這是下一節寫程式碼時的關鍵直覺。

這一篇是 Workers AI 首篇,我們只用文字生成 LLM 當作「第一個推論」的示範;embedding、影像、語音各自的細節與 AI.run() 的完整用法,留給後續文章專門展開。

三、和外部 API(OpenAI)的差異

很多人第一個問題是:「我已經會用 OpenAI API 了,為什麼還要 Workers AI?」把定位差異攤開來比,就清楚了:

一句話總結取捨:要「就近、低延遲、開源、免管理基礎設施、成本可控」的推論,選 Workers AI;要「特定閉源前沿模型的最高品質」,呼叫外部 API。 兩者不是二選一——實務上常常混用,而且 Cloudflare 還有 AI Gateway 這一層,可以同時代理 Workers AI 和 OpenAI/Anthropic 等外部供應商,加上快取、限流、可觀測性(這是後面的主題,本篇先按下不表)。

四、關鍵術語

先統一這一篇會反覆用到的名詞:

實作範例

觀念打底完成,我們動手寫出第一個 Workers AI 推論——一個接收 prompt 查詢參數、用 Llama 3.1 生成回答的 Worker。從設定 binding 到跑起來,完整走一遍。

以下範例以 TypeScript 撰寫,型別 Ai 與 ExportedHandler 來自 @cloudflare/workers-types。重點在「最小可跑通的第一個推論」,進階用法後續再談。

1. 設定 AI binding(wrangler.jsonc)

要在 Worker 裡拿到 env.AI,先在 wrangler.jsonc 宣告 AI binding。只要一個 ai 區塊:

// wrangler.jsonc
{
  "name": "my-ai-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23",
  "ai": {
    "binding": "AI"
  }
}

"binding": "AI" 的意思是「把這個 AI 能力綁定到 env.AI 這個名字上」。你也可以取別的名字(如 "MY_AI"),那 Worker 裡就用 env.MY_AI。慣例上大家都叫 AI,本文沿用。

若你用 wrangler.toml 而非 .jsonc,等價寫法是:

[ai]
binding = "AI"

2. TypeScript 型別設定

安裝官方型別,env.AI 才有正確的 Ai 型別提示:

# 安裝 Workers 型別定義
npm install --save-dev @cloudflare/workers-types

在 Worker 裡定義 Env 介面,把 AI 標成 Ai 型別:

// src/index.ts
export interface Env {
  AI: Ai; // 型別來自 @cloudflare/workers-types
}

3. 你的第一個 env.AI.run() 推論

核心 API 就一個方法:env.AI.run(model, input)。第一個參數是模型識別符,第二個是該模型的輸入物件。對文字生成 LLM,輸入用 Chat 格式的 messages 陣列最直覺:

// src/index.ts
export interface Env {
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // 從 ?prompt=... 取出使用者問題,沒有就給預設值
    const { searchParams } = new URL(request.url);
    const prompt = searchParams.get("prompt") ?? "用一句話介紹 Cloudflare Workers";

    // 【第一個推論】呼叫 Llama 3.1 8B 生成回答
    const result = await env.AI.run(
      "@cf/meta/llama-3.1-8b-instruct", // 模型識別符(一字不差!)
      {
        messages: [
          { role: "system", content: "你是一位技術助理,只用繁體中文簡潔回答。" },
          { role: "user", content: prompt },
        ],
        max_tokens: 512, // 最大輸出 token 數
      }
    );

    // 文字生成的回應在 result.response(字串)
    return Response.json({ answer: result.response });
  },
} satisfies ExportedHandler<Env>;

三個要點:第一,messages 用 system + user 的角色分工,system 定調、user 是實際問題,這是 Chat 模型的標準用法。第二,文字生成的回傳結果是一個物件,答案在 result.response(字串)——不同任務類型的回傳形狀不同(embedding 在 result.data、影像是二進位),別記混。第三,max_tokens 控制輸出長度,避免模型話太長吃掉配額。

4. 跑起來:一定要 --remote

寫完就能跑,但有個非踩不可的關卡:Workers AI 必須用 --remote 開發。

# 用 C3 建立新專案(選 Hello World → TypeScript)
npm create cloudflare@latest -- my-ai-worker
cd my-ai-worker

# 本地開發:一定要加 --remote!
# 本機沒有 GPU,推論需轉送到 Cloudflare 遠端 GPU 網路執行
npx wrangler dev --remote

# 部署到正式環境
npx wrangler deploy

跑起來後,開瀏覽器打 http://localhost:8787/?prompt=什麼是邊緣運算,就會看到 Llama 生成的 JSON 回應。恭喜,這就是你的第一個邊緣 AI 推論。

為什麼非 --remote 不可? 因為推論要真正的 GPU,而你的本機沒有 Cloudflare 的 GPU 節點,wrangler 無法在本地模擬。加上 --remote 後,AI 請求會轉送到遠端 GPU 實際執行。代價是:開發階段的推論一樣消耗 Neurons、計入每日配額,所以別在迴圈裡狂打模型除錯。

5. 從非 Worker 環境呼叫(REST API)

如果推論來源不是 Worker(例如你的 Node.js 後端或 CLI 腳本),Workers AI 也提供 REST API,用標準 HTTP 帶上 Account ID 與 API Token 即可:

# 從任何環境用 curl 呼叫同一個模型
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai/run/@cf/meta/llama-3.1-8b-instruct \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "用一句話說明什麼是邊緣推論" }
    ]
  }'

在 Worker 裡首選 env.AI binding(零金鑰、零額外跳躍);只有在 Worker 以外的環境才用 REST API。

常見錯誤與最佳實踐

Workers AI 入門階段最容易踩的坑,幾乎都不是 API 不會用,而是幾個觀念沒轉過來。以下是最高頻的幾個。

坑一:模型 ID 打錯一個字。

模型識別符是一長串精確字串,少一個 -、把 3.1 寫成 3-1、或漏掉 -instruct,呼叫就會失敗(常見錯誤碼 7502:模型名稱錯誤)。這是新手第一天最常見的錯。

// ❌ 錯誤:model ID 拼錯(少了 -instruct、版本寫錯)
await env.AI.run("@cf/meta/llama-3.1-8b", { messages });

// ✅ 正確:到官方模型目錄複製,一字不差
await env.AI.run("@cf/meta/llama-3.1-8b-instruct", { messages });

最佳實踐:把常用 model ID 抽成常數,別在多處手打;需要時直接從官方模型目錄複製貼上。

坑二:忘了 --remote,或 env.AI 是 undefined。

兩個症狀常一起出現。若沒加 --remote,本地無法跑推論;若 wrangler.jsonc 少了 ai binding,env.AI 會是 undefined,呼叫時報 Cannot read properties of undefined (reading 'run')。

// ✅ 確認 wrangler.jsonc 有這一段,env.AI 才存在
{ "ai": { "binding": "AI" } }

# ✅ 開發一律加 --remote
npx wrangler dev --remote

坑三:以為免費額度=無限、把它當通用大模型狂打。

Free 方案每天 10,000 Neurons 免費(UTC 00:00 重置),但不是無限。不同任務吃的 Neurons 天差地別:一次 embedding 只吃幾到二十個、一次 8B 對話約數百個,而一張影像生成可能一口氣吃掉上萬個——拿免費額度生圖,可能一天一兩張就見底。而且開發階段的推論同樣扣配額。

// ❌ 反模式:簡單分類卻動用 70B 大模型,又貴又慢
await env.AI.run("@cf/meta/llama-3.1-70b-instruct", { messages: classifyMsg });

// ✅ 正確:分類就用專用輕量模型,省 Neurons、又更快
await env.AI.run("@cf/huggingface/distilbert-sst-2-int8", { text: inputText });

最佳實踐:選最小夠用的模型;embedding 用批次(一次 text: [...] 送多筆)而非迴圈逐筆;上線後到 Dashboard 看 Neurons 用量趨勢;超量再考慮升 Workers Paid($0.011 / 1,000 Neurons)。

坑四:把 Workers AI 當成 OpenAI 的完全替代品。

Workers AI 跑的是開源模型,品質與能力邊界跟 GPT-4o 這類閉源前沿模型不完全相同。若你的任務對品質極度敏感(複雜推理、長篇創作),Llama 3.1 8B 未必夠;這時該用 70B、或直接呼叫外部 API。判準:先用小模型跑,品質不足再往上換,而不是一開始就假設「Workers AI 什麼都能替代 OpenAI」。

坑五:忽略冷啟動,把它塞進極度延遲敏感的同步路徑。

模型首次載入約 1–3 秒。若你把 AI 推論擺在使用者「按下按鈕就要立刻有結果」的關鍵路徑上,首個請求可能明顯卡頓。最佳實踐:延遲敏感場景可用串流(讓使用者先看到開頭)、或把推論丟到背景(還記得前一篇的編排原語嗎?用 Queue/Workflow 非同步處理),而非硬要同步等完。

最佳實踐小結:model ID 從官方目錄複製、抽成常數;開發一律 --remote 並確認 ai binding 存在;選最小夠用的模型、embedding 批次化、盯著 Neurons 用量;把 Workers AI 定位成「就近低延遲的開源推論」,而非 OpenAI 的萬能替身;延遲敏感就串流或非同步化。

小結

上一篇《非同步編排選型》,我們把 Queues、Workflows、Durable Objects 三大原語放在同一張桌上做選型,替 CF-4 這條非同步主線收尾。這一篇,我們正式跨進 CF-5 的 AI 層,把 Workers AI 的地基打好:

• 邊緣 GPU 推論——Workers AI 是無伺服器 GPU 推論服務,模型部署在全球 300+ 邊緣節點;推論不在你的 Worker 進程跑,而是由 env.AI binding 代理到 GPU 網路,就近執行、延遲低,但有 1–3 秒冷啟動。
• AI binding——wrangler.jsonc 一行 "ai": { "binding": "AI" } 就拿到 env.AI;搭配 @cloudflare/workers-types 取得 Ai 型別;開發必須 --remote。
• 模型目錄——@{provider}/{model-name} 格式,涵蓋 LLM、embedding、影像、語音、分類五大類;每類的輸入/輸出形狀不同。
• 第一個推論——env.AI.run(model, input),文字生成用 messages、答案在 result.response。
• Neurons 計費——GPU 計算量的抽象單位,Free 方案每天 10,000 Neurons 免費、UTC 重置,超出 $0.011 / 1,000 Neurons;影像生成特別吃額度。
• 和 OpenAI 的差異——就近開源 vs 中央閉源;免管理、免金鑰、Neurons 計費 vs 需金鑰、按 token;不是二選一,常混用。

至此,你已經能在邊緣跑通第一個 AI 推論了。但 env.AI.run() 遠不只文字生成這一招——下一篇《AI.run() 與常見任務》,我們會深入這個方法本身,把文字生成的進階參數、embedding、影像、語音等常見任務的呼叫方式各自跑一遍,讓你真正把整個模型目錄用起來。

想隨時查閱完整的模型清單與各模型的輸入格式,可以參考 Cloudflare Workers AI 模型目錄。把「第一個推論」跑通了,後面每一種 AI 能力都只是換個模型、換個輸入而已,我們下一篇《AI.run() 與常見任務》見。