AI Gateway:替所有 AI 請求加上快取、限流與可觀測 | Cloudflare 完整教學

2026/09/05
cloudflare ai-gateway ai
AI Gateway:替所有 AI 請求加上快取、限流與可觀測 | Cloudflare 完整教學

上一篇《AI.run() 與常見任務》,我們用同一個 env.AI.run() 跑遍了文字、向量、影像、語音與工具呼叫。但當這些 AI 呼叫進到生產環境,新的煩惱就浮現:重複的 prompt 每次都重算很浪費、成本無從觀測、失敗沒重試、還可能想同時代理 Workers AI 與 OpenAI/Anthropic。這一篇的主角 AI Gateway——一層架在應用程式與 AI 供應商之間的統一閘道——正是來解決這些問題的。我們會替所有 AI 請求加上快取、限流(rate limiting)、重試 / fallback、可觀測(logs / analytics / costs)與多供應商路由。

前言

上一篇《AI.run() 與常見任務》結尾我們留了一個懸念:env.AI.run() 能把 AI 任務跑得很順,但那還只是「能跑」。真正上線後,你會遇到一連串「能跑」之外的問題——同一句常見問題被問一百次、每次都花錢重算;老闆問這個月 AI 花了多少、你答不上來;供應商偶爾抽風回 503、你的請求就直接掛掉;想從 Workers AI 切換到 OpenAI 做 A/B,卻得改一堆程式碼。

AI Gateway 就是為這些「上線後的問題」而生。它是 Cloudflare 提供的一層 AI 請求代理(proxy),位置很明確:架在你的應用程式與各家 AI 供應商之間。你的請求不再直接打給模型,而是先經過這道閘門,由它替你加上一整排「橫切」能力:快取、限流、重試、可觀測、安全防護、統一帳單。而它幾乎不侵入你的程式碼——對 Workers AI 來說,常常只是在 env.AI.run() 多傳一個 gateway 參數而已。

打個比方。如果說 env.AI.run() 是你家「用電的插座」,那 AI Gateway 就是整棟大樓的「總電錶配電箱」:所有電流(AI 請求)都先流經它,它負責計量(可觀測)、跳電保護(限流)、電池備援(快取 / 重試),甚至可以決定哪一路電走市電、哪一路走太陽能(多供應商路由)。你家裡的電器一個都不用改線,但整棟樓的用電從此「看得見、控得住、省得下」。

讀完你會掌握:

  • AI Gateway 是什麼——它在請求路徑上的角色,以及六大橫切功能(快取、限流、重試 / fallback、可觀測、安全、統一帳單)。
  • 在 Workers AI 前掛 Gateway——只加一個 gateway 參數,就讓推論享有全部能力。
  • 串接外部供應商——用 Gateway 的 URL / 通用端點代理 OpenAI、Anthropic 等,程式碼幾乎不改。
  • 看得懂 Logs 與 Analytics——快取命中率、token 用量、費用、延遲百分位,一頁看盡。

核心概念

先把「AI Gateway 在請求路徑上的角色」這張圖畫清楚,再逐一拆解它的功能。理解 Gateway 的關鍵只有一句話:它是一層代理,你只是把請求的目的地從「供應商」改成「Gateway」,其餘由它接手。

一、AI Gateway 在請求路徑上的位置

沒有 Gateway 時,你的應用直接打給供應商;有了 Gateway,中間插入一層代理:

你的應用程式
    │
    ▼
AI Gateway（代理層）
    ├── 快取（Cache）——命中就不打供應商,直接回上次結果
    ├── 速率限制（Rate Limiting）——超量回 429,保護你的成本與供應商配額
    ├── 重試 / 降級（Retry / Fallback）——供應商抽風時自動重試或換一家
    ├── 可觀測性（Logs / Analytics）——每筆請求的 prompt、費用、延遲、快取狀態
    ├── 安全防護（Guardrails / DLP）——內容過濾、遮蔽 PII
    └── 供應商金鑰管理（統一帳單 / BYOK）
    │
    ▼
AI 供應商（Workers AI / OpenAI / Anthropic / Google …）

這層代理有兩個重要特性要先記住:

  1. 對程式碼幾乎零侵入。 對 Workers AI,你只是在 AI.run() 多傳一個 gateway 參數;對外部供應商,你只是把 SDK 的 baseURL 指到 Gateway。業務邏輯一行都不用改。
  2. 適用所有方案,基本功能免費。 從 Free 到 Enterprise 都能用 AI Gateway,快取、限流、可觀測這些核心功能免費開放,沒有理由不掛。

二、六大橫切功能對照

Gateway 的價值在於把一堆原本要「自己刻」的橫切關注點(cross-cutting concern)集中在一處。逐條看它們各自解決什麼問題:

功能解決什麼問題帶來的效益
快取(Cache)相同請求重複打、重複計費命中就不打供應商 → 省成本 + 加速(HIT 幾乎零延遲)
限流(Rate Limiting)暴衝流量燒錢、撞供應商配額超量回 HTTP 429,保護成本與穩定性
重試 / Fallback供應商偶發 5xx / 503、單一供應商故障自動重試;甚至自動換另一家供應商
可觀測(Observability)成本與用量是黑箱、出錯難追Logs + Analytics:prompt、token、費用、延遲、快取率一覽
安全防護prompt / 回應含不當內容或 PIIGuardrails 內容過濾、DLP 遮蔽個資
統一帳單 / BYOK各家金鑰散落程式碼、帳單分散用 Cloudflare 帳號統一付費,或集中管理供應商金鑰

一句話總結這張表:Gateway 把「AI 請求的營運層」外包給 Cloudflare,你只需專注寫業務邏輯。

三、快取的運作原理(最需要先懂的一環)

快取是 Gateway 最直接省錢的功能,但也最容易用錯,所以先講清楚它「怎麼判斷命中」。

AI Gateway 的快取是基於請求內容的 SHA-256 雜湊:它把「供應商 + 端點 + 模型 + 認證 + 完整 request body」一起算成一個雜湊值當作快取鍵,只有整個請求一模一樣(雜湊相同)才會命中(HIT),否則就是 MISS、照常打供應商並把結果存起來。

這帶來兩個必須內化的直覺:

  • body 裡任何一字不同 → 快取失效。 這是設計使然,不是 bug。
  • body 裡若含「每次都變」的內容(時間戳、亂數、session token),快取永遠 MISS。 等於白開。這正是下一節「常見錯誤」的第一坑。

回應會帶一個 cf-aig-cache-status 標頭,值是 HIT 或 MISS,除錯快取問題時第一件事就是看它。

四、關鍵術語與請求標頭

Gateway 的行為大多可用請求標頭(header)即時控制,不必改 Dashboard 設定。以下是最常用的幾個:

標頭作用
cf-aig-authorizationGateway 認證,值為 Bearer {CF_API_TOKEN}
cf-aig-cache-ttl快取存活時間(秒,60–2,592,000)
cf-aig-skip-cache設 true 略過快取,強制打供應商
cf-aig-cache-key自訂快取鍵(解決「內容會變」問題的利器)
cf-aig-metadata自訂 metadata(JSON,最多 5 個 key)
cf-aig-collect-log設 false 停用此請求的日誌記錄
cf-aig-cache-status(回應)HIT 或 MISS

先把 cf-aig-cache-ttl、cf-aig-cache-key、cf-aig-cache-status 這三個記牢,快取的日常操作幾乎都靠它們。

實作範例

觀念清楚後,把最常見的三種用法各跑一遍:(1) 在 Workers AI 前掛 Gateway、(2) 透過 Gateway 串接外部供應商(OpenAI / Anthropic)、(3) 讀懂 Logs。所有範例以 TypeScript 撰寫,型別 Ai、ExportedHandler 來自 @cloudflare/workers-types。

1. 在 Workers AI 前掛 Gateway:只加一個 gateway 參數

這是最輕量的做法。先在 Dashboard 建一個 Gateway(AI → AI Gateway → Create Gateway,取個小寫名字如 prod-chat),然後在 env.AI.run() 的第三個參數傳入 gateway:

export interface Env {
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const result = await env.AI.run(
      "@cf/meta/llama-3.1-8b-instruct",
      {
        messages: [{ role: "user", content: "什麼是 Cloudflare Workers?" }],
        max_tokens: 512,
      },
      {
        // ← 就是這個 options.gateway,一掛上就享有快取 / 限流 / 重試 / 可觀測
        gateway: {
          id: "prod-chat", // 你在 Dashboard 建立的 Gateway 名稱
          metadata: { userId: "u-123", tier: "pro" }, // 選填:自訂欄位,之後可在 Logs 分析
        },
      }
    );

    return Response.json({ response: result.response });
  },
} satisfies ExportedHandler<Env>;

就這樣。這一次推論就會經過 prod-chat 這道閘門:相同 prompt 命中快取、超量觸發限流、供應商抽風時重試,而且每一筆都被記進 Logs。metadata 裡帶的 userId、tier,之後在 Logs 與 Analytics 就能拿來過濾、分組,甚至餵給動態路由做分流。

若你嫌每次都手寫 id 麻煩,也可以在 wrangler.jsonc 用 ai_gateway binding 宣告(選配):

// wrangler.jsonc
{
  "ai": { "binding": "AI" },
  "ai_gateway": {
    "binding": "AI_GATEWAY",
    "id": "prod-chat"
  }
}

記住:掛 Gateway 不強制要設 binding——只用 gateway 參數就能運作。binding 只是讓你把 Gateway id 統一管理、方便多處共用。

2. 用快取標頭省成本:設定 TTL 與自訂快取鍵

想讓「常見問題」的相同 prompt 只計費一次?開啟快取後,透過 cf-aig-cache-ttl 設定存活時間即可。以下用 Workers AI 的 OpenAI 相容端點示範帶標頭(注意:串流不支援快取,這裡用非串流):

// 透過 fetch 直接打 Gateway,並帶上快取標頭
async function cachedAsk(env: Env, question: string): Promise<Response> {
  const url = `https://gateway.ai.cloudflare.com/v1/${env.CF_ACCOUNT_ID}/prod-chat/workers-ai/@cf/meta/llama-3.1-8b-instruct`;

  return fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "cf-aig-authorization": `Bearer ${env.CF_API_TOKEN}`,
      "cf-aig-cache-ttl": "3600", // 快取 1 小時(最小 60,最大 2,592,000)
      // 關鍵:用穩定的自訂快取鍵,避免因 body 微小差異而 MISS
      "cf-aig-cache-key": `faq:${question.trim().toLowerCase()}`,
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: question }],
      max_tokens: 512,
    }),
  });
}

重點在 cf-aig-cache-key:預設快取鍵是「整個 body 的雜湊」,只要 body 有一字不同就 MISS。當你明確知道某些變動(例如多餘空白、大小寫)不該影響快取,就用自訂快取鍵把「正規化後的問題文字」當 key,大幅提高命中率。除錯時讀回應的 cf-aig-cache-status:

const resp = await cachedAsk(env, "什麼是邊緣運算?");
console.log(resp.headers.get("cf-aig-cache-status")); // "HIT" 或 "MISS"

3. 透過 Gateway 串接外部供應商(OpenAI / Anthropic)

AI Gateway 不綁 Workers AI——它是多供應商的統一閘道。要代理 OpenAI,你只要把原本的請求目的地,從 OpenAI 官方 URL 改成 Gateway 的 URL:

https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}

因為多數 SDK 允許自訂 baseURL,實務上把 OpenAI SDK 的 baseURL 指過去、再帶上 cf-aig-authorization 就完成了,業務邏輯一行不改:

import OpenAI from "openai";

// 把 OpenAI SDK 的 baseURL 指到 Gateway 的 openai 路徑
const client = new OpenAI({
  apiKey: env.OPENAI_API_KEY, // BYOK:仍用你自己的 OpenAI 金鑰
  baseURL: `https://gateway.ai.cloudflare.com/v1/${env.CF_ACCOUNT_ID}/prod-chat/openai`,
  defaultHeaders: {
    "cf-aig-authorization": `Bearer ${env.CF_API_TOKEN}`, // Gateway 認證
    "cf-aig-cache-ttl": "3600", // 外部供應商一樣享有快取
  },
});

// 呼叫方式與平常用 OpenAI 完全一樣——但已經過 Gateway 代理
const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "用一句話解釋什麼是統一閘道" }],
});
console.log(completion.choices[0].message.content);

Anthropic、Google AI Studio、Groq、Mistral 等供應商同理,只要把 URL 裡的 {provider} 換掉、{endpoint} 沿用該供應商原本的路徑(例如 Anthropic 是 anthropic/v1/messages)。

更進一步:通用(相容)端點做 fallback。 Gateway 提供一個 compat 端點,讓你用同一套 OpenAI 格式、只換 model 字串裡的 {provider}/{model} 就切換供應商,非常適合做多供應商 fallback:

// 通用端點:一套格式代理所有供應商,靠 model 字串切換
const client = new OpenAI({
  apiKey: env.CF_API_TOKEN,
  baseURL: `https://gateway.ai.cloudflare.com/v1/${env.CF_ACCOUNT_ID}/prod-chat/compat`,
  defaultHeaders: { "cf-aig-authorization": `Bearer ${env.CF_API_TOKEN}` },
});

async function askWithFallback(prompt: string) {
  // 依序嘗試不同供應商,前一個失敗才用下一個
  const models = [
    "openai/gpt-4o",               // 首選
    "anthropic/claude-sonnet-4-5", // 備用(供應商 + 模型以 {provider}/{model} 指定)
    "workers-ai/@cf/meta/llama-3.1-8b-instruct", // 最後防線:Workers AI
  ];

  for (const model of models) {
    try {
      const res = await client.chat.completions.create({
        model,
        messages: [{ role: "user", content: prompt }],
      });
      return res.choices[0].message.content;
    } catch (err) {
      continue; // 這家失敗,換下一家
    }
  }
  throw new Error("所有供應商都失敗");
}

這段程式碼把「多供應商 fallback」寫在應用層;若你想更省事,也可以在 Dashboard 的動態路由(Dynamic Routing)用 Conditional / Percentage / Budget Limit 等節點,把分流、A/B、預算控管設定在 Gateway 上、無需改程式碼。兩種做法可依團隊習慣擇一。

4. 讀懂 Logs 與 Analytics

掛上 Gateway 後,真正的回報在可觀測。到 Dashboard → AI Gateway → Logs,每一筆請求都會記錄下列欄位:

欄位說明
request.body / response.body完整 prompt 與回應內容
provider / model走了哪家供應商、哪個模型
tokens.input / tokens.output輸入 / 輸出 token 數
cost估算費用
duration_ms請求耗時(毫秒)
cache_statusHIT 或 MISS
metadata你在 gateway.metadata 帶的自訂欄位

到 Analytics 頁則能看聚合指標:總請求數與錯誤率、token 用量趨勢、費用分析、快取命中率、延遲百分位(p50 / p95 / p99)、各供應商 / 模型的用量分佈。這正是回答「這個月 AI 花了多少、慢在哪、快取幫我省了多少」的地方。

若某些請求(如健康檢查)不想留紀錄,帶上 cf-aig-collect-log: false 即可略過;需要把日誌送到外部(S3、Datadog、Splunk 等)則用 Logpush,Gateway 也支援 OpenTelemetry 標準匯出。

常見錯誤與最佳實踐

Gateway 掛起來很簡單,但幾個坑會讓它「看起來有裝、實際沒效果」。以下是最高頻的。

坑一:快取鍵含「每次都變」的內容,快取永遠 MISS。

這是最隱蔽的坑。你開了快取、TTL 也設了,但命中率始終是 0——原因往往是 prompt 或 body 裡塞了時間戳、request ID、亂數或使用者 session token,導致每次的 body 雜湊都不同。因為預設快取鍵是「完整 body 的 SHA-256」,body 一變就 MISS。

// ❌ prompt 含當下時間 → body 每次都變 → 永遠 MISS
messages: [{ role: "user", content: `現在是 ${Date.now()},請回答:什麼是邊緣運算?` }]

// ✅ 把會變動、且不影響語意的內容移出;必要時用穩定的自訂快取鍵
headers: { "cf-aig-cache-key": "faq:what-is-edge-computing" }

坑二:限流(Rate Limiting)設得太鬆,等於沒設。

限流是用來保護成本與供應商配額的閘門,若上限設得比實際尖峰流量還高,它永遠不會觸發,防護形同虛設。應該依「你願意承受的最大成本 / 供應商配額」來設,而不是拍腦袋給個大數。演算法可選固定視窗(Fixed Window) 或更精確防爆衝的滑動視窗(Sliding Window);超量會回 HTTP 429,記得在應用端優雅處理(退避重試或提示使用者稍候)。

# 建立 Gateway 時就把限流設成貼近真實尖峰的值
curl -X POST ".../ai-gateway/gateways" \
  -d '{
    "id": "prod-chat",
    "rate_limiting_interval": 60,
    "rate_limiting_limit": 100,
    "rate_limiting_technique": "sliding"
  }'

坑三:掛了 Gateway 卻沒接可觀測,浪費了最大價值。

很多人掛 Gateway 只為了快取,卻沒去看 Logs / Analytics——這等於買了儀表板卻不看儀表。可觀測是 Gateway 幾乎「免費附送」的最大價值:開啟日誌、善用 metadata 分組、定期看 Analytics,你才能回答成本、延遲、快取率這些關鍵營運問題。建議在 gateway.metadata 一律帶上 userId、tier、feature 等維度,之後分析才切得開。

坑四:對串流開快取,然後納悶為何不生效。

再強調一次:AI Gateway 的快取不支援串流(stream: true)。如果你的端點是串流輸出,快取就不會作用。若這條路徑很吃「相同 prompt 重複打」,可考慮改用非串流呼叫以換取快取;若體驗上非串流不可,就別指望快取省成本,改從限流與模型選型下手。

最佳實踐小結: 建 Gateway 後先確認快取鍵不含變動內容(必要時用 cf-aig-cache-key);限流設成貼近真實尖峰、優先用 sliding;每筆請求都帶結構化 metadata,並定期看 Analytics;串流路徑不要依賴快取;外部供應商優先用 BYOK 或統一帳單集中管理金鑰;需要多供應商 fallback 時,應用層用 compat 端點或 Dashboard 用動態路由,擇一即可。

小結

上一篇《AI.run() 與常見任務》我們把 env.AI.run() 這個統一入口攤開,用它跑遍了文字、向量、影像、語音與工具呼叫——那是「把 AI 跑起來」。這一篇,我們把 AI Gateway 這層代理掛上,替所有 AI 請求補齊了「上線後」需要的營運能力:

  • AI Gateway 是一層代理——架在應用與供應商之間,把快取、限流、重試 / fallback、可觀測、安全、統一帳單這些橫切能力集中一處,對程式碼幾乎零侵入,適用所有方案且基本功能免費。
  • 快取——基於「完整請求內容」的 SHA-256 雜湊命中,相同請求才 HIT;串流不支援快取;用 cf-aig-cache-ttl 設 TTL、cf-aig-cache-key 自訂鍵、cf-aig-cache-status 除錯。
  • 在 Workers AI 前掛 Gateway——只要在 env.AI.run() 第三個參數傳 { gateway: { id, metadata } },零改動業務邏輯。
  • 串接外部供應商——把 SDK 的 baseURL 指到 Gateway 的 {provider}/{endpoint} URL、帶 cf-aig-authorization;或用 compat 通用端點靠 {provider}/{model} 切換供應商做 fallback。
  • 可觀測——Logs 記錄 prompt / 費用 / 延遲 / 快取狀態,Analytics 看快取命中率、費用與延遲百分位,善用 metadata 分組。

到這裡,Workers AI 這條主線就告一段落了:從第 034 篇《Workers AI 入門》認識邊緣推論、第 035 篇《AI.run() 與常見任務》跑遍模型目錄,到本篇替所有 AI 請求掛上營運層,你的邊緣 AI 已經從「能跑」邁向「可上線」。

但還記得前面反覆出現的 embedding 與 RAG 嗎?我們一直說「把文字轉成向量、做語意搜尋」,卻還沒好好談那些向量該存在哪、怎麼查最快。下一篇《Vectorize 向量資料庫入門》,我們就正式進入 Cloudflare 的向量資料庫——看它如何專為 Workers AI 的 embedding 而生,讓 RAG 從「範例程式碼」變成「生產級知識庫」。

想隨時查閱 AI Gateway 的完整功能與各供應商路徑,可以參考 Cloudflare AI Gateway 官方文件。掛上這道閘門後,你的每一筆 AI 請求都變得「看得見、控得住、省得下」,我們下一篇《Vectorize 向量資料庫入門》見。

BenZ Software Developer

熱愛技術的軟體開發者，在這裡分享程式開發經驗與學習筆記。

本週主打

AI 自動化入門包

你每天手動在做的那些煩事,其實 AI 可以自己跑。這份給你 10 個照著做就會的自動化工作流 + 50 個複製即用的提示詞,不用會寫程式。

看看這個產品 →