CloudflareのWorkersAIの使い方｜失敗を防ぐ

こんにちは。Osukeラーニング、運営者の「osuke」です。

WebアプリへAIを入れたいものの、「API keyの管理が難しそう」「無料枠を超えて高額請求にならないか」「どのmodelを選べばよいか」と迷っていませんか。Cloudflare Workers AIなら、WorkerからAI Bindingを通じて文章生成、分類、画像認識、音声処理などを呼び出せます。ただし、1回動いたcodeをそのまま公開すると、botの連打、長すぎる入力、model変更、構造化出力の崩れで止まりかねません。

結論からいうと、最初は1機能・1model・短い入力に絞り、AI Bindingで最小の推論を動かします。その後にtimeout、入力上限、rate limit、利用量監視、fallbackを加えてから公開するのが安全です。外部のAI API keyをclientへ置かず、推論と防御をWorker側へ集められる点が、個人開発での大きな利点です。

この記事はosuke本人の利用体験としては書かず、2026年8月30日時点のCloudflare公式資料15件と、Xで公開された8件の導入・速度比較・model比較・データ送信事例を照合しました。Xの数値は投稿者固有の環境に限られるため、料金・上限・data policyは公式資料を優先します。Cloudflare全体が初めてならCloudflareの無料範囲と機能の全体像から確認してください。

記事のポイント

• 既存WorkerにはAI Binding、新規検証や外部systemにはREST APIを選ぶ
• 無料枠は1日10,000 Neuronsで、UTC 00:00にresetされる
• model名を固定するだけでなく、廃止・遅延・出力崩れを想定する
• AI Gatewayでrequest、token、cost、errorを監視し、rate limitを置く

Cloudflare Workers AIの仕組みと料金

Workers AIは「Cloudflare上のmodelを呼ぶ推論service」、Workerは「requestを受けて処理を組み立てる実行環境」です。まず機能、接続方法、model、料金、制限を分けて理解すると、無料という言葉だけで本番公開する失敗を避けられます。

Workers AIでできることと向く用途

Cloudflare公式Model Catalogには、text generationだけでなく、embedding、text-to-image、speech recognition、text-to-speech、translation、image classificationなど複数のtask typeがあります。2026年8月12日時点のcatalog表示は85 modelsで、用途とcapabilityから絞り込めます。1つの万能chatbotを作るより、「問い合わせ分類」「要約」「画像の説明」のように入出力を限定した方が検証しやすくなります。

XではRegister My SiteがCloudflareのchat app templateを改変し、Workers AIを使うSVG image generatorをdeployしたと報告しています。templateをそのまま大規模serviceへ広げるのではなく、画像生成という1用途へ絞った例です。初心者も「自由会話」より、商品説明を3案出す、文章を120字へ要約するなど、合格条件を数えられる機能から始めると失敗を判断できます。

Workers AIはdatabaseやstorageではありません。会話履歴を残すならD1やDurable Objects、画像や音声を保存するならR2、意味検索ならVectorizeなどを別に組み合わせます。最初からすべてを接続すると原因箇所が増えるため、固定promptを1回実行し、responseを画面へ返すだけの最小構成で推論serviceとapplication logicを切り分けます。

AI BindingとREST APIを使い分ける

公式Getting startedにはWorkers Bindings、REST API、Dashboardの3つの開始方法があります。Cloudflare Worker内で呼ぶならAI Bindingが第一候補です。Wrangler設定へbinding名を追加すると、code側ではenv.AIとして使え、Account IDやAPI tokenをrequestごとに組み立てずに済みます。

公式REST API手順は、Cloudflare外のserver、batch処理、curlでの事前検証に向きます。API tokenにはWorkers AI ReadとEditの権限が必要で、browser JavaScriptへtokenを置いてはいけません。clientから直接REST endpointを呼ばず、自分のWorkerやbackendを1枚挟み、認証、入力validation、rate limitを実行します。

Xでは個人開発者がWorkers AI Bindingを「AI」という名前で追加できた後、mobile code editorのclipboard errorへ遭遇したと投稿しています。Binding設定の成功とeditor側の問題は別です。env.AIが未定義ならWrangler設定とtype生成、pasteできないならeditor、推論が失敗するならmodel名や入力というように、1段ずつ切り分けます。

Model Catalogから用途別に選ぶ

modelは知名度ではなく、task type、入力上限、出力形式、速度、価格、licenseで選びます。短い分類なら小型model、画像も読むならvision対応、tool実行ならfunction calling対応が必要です。2026年8月26日の公式changelogではGLM-5.3 Flashがmultimodal、function calling、reasoning対応で追加されましたが、Workers Paidまたはprepaid AI Gateway creditsが必要です。

泉水亮介氏はGLM-5.3の100万token超のcontext、function calling、reasoning、structured outputを紹介しています。一方、contextが大きいほど毎回大量入力すべきとは限りません。長いdocumentを丸ごと渡す前に分割・検索し、関係する箇所だけを送ると、cost、latency、誤回答の調査範囲を小さくできます。

XではNick Gray氏が実際のspam 6件と正当なsite 4件を使い、7 modelsを比較したと報告しています。benchmark上位でも自分の文章、言語、禁止事項で正しく分類できるとは限りません。個人情報を除いた10〜50件のtest setを用意し、正解率、平均時間、最悪時間、1件costを同じ表で比べて選びます。

1日1万Neuronsと料金を把握する

公式Pricingによると、2026年8月30日時点でWorkers FreeとPaidはいずれも1日10,000 Neuronsの無料allocationがあり、UTC 00:00にresetされます。Freeで超えると追加推論はerrorになり、自動課金はされません。Paidは無料分を超えると1,000 Neuronsあたり0.011米ドルで、Workers Paid自体にも最低5米ドル/月があります。

NeuronはmodelごとのGPU計算量を共通化した単位です。同じ1,000 input tokensでもmodelによってNeuron数が違い、出力は入力より高いmodelが多いため、request数だけではcostを予測できません。たとえば長い回答を1回返す機能は、短い分類を数回行う機能よりNeuronを多く使う可能性があります。Dashboardでmodel別usageを確認し、入力文字数と最大出力tokensをcodeでも制限します。

さらに、Kimi K2.6、GLM-5.2、GLM-5.3 Flashなど一部modelはbilling methodが必要です。「1日10,000 Neuronsが無料だから全modelをcardなしで試せる」とは限りません。まずFreeで使える小型modelと100件程度の上限で始め、Paidへ移る前に1件あたりのNeuron、1日の見込み件数、最悪時の月額を計算します。Workers全体の費用はCloudflare Workersの無料枠と課金条件も合わせて確認してください。

制限・遅延・model変更へ備える

公式Limitsでは、標準のtext generationは300 requests/minute、text embeddingsは3,000 requests/minuteなどtask別rate limitが示されています。frontier modelsにはaccount・model単位で20 requests/minute、prepaid AI Gateway creditsでは50 requests/minuteとなる例もあります。localのWrangler推論も同じlimitへ数えられるため、負荷testを無制限に回さないでください。

Xの個別計測では、Gemini 3.5 Flash-Liteが0.6〜1.0秒、Workers AIのGLM-5.3 Flashが6〜28秒だったと報告されています。この差はすべての環境を代表しませんが、平均値だけでUIを設計できないことは分かります。15秒でtimeout、処理中表示、再試行、別modelへのfallbackを用意し、同じrequestの二重課金を防ぐrequest IDも記録します。

公式のplanned model deprecationsでは、古いmodelが廃止または別modelへaliasされ、置換先で価格が上がる例が示されています。model IDを1か所の設定へまとめ、月1回catalogとchangelogを確認し、stagingで置換先を比較してから切り替えます。応答schema、禁止語、速度、costの回帰testを残せば、model更新を「動いたか」だけで判断せずに済みます。

Cloudflare Workers AIの使い方と公開手順

ここからはWorker projectへAI Bindingを追加し、最小推論、出力形式、監視、privacyの順で仕上げます。最初の目標は高機能なchat画面ではなく、1 requestが安全に成功し、失敗理由とNeuron usageを確認できる状態です。

WorkerへAI Bindingを追加する

既存projectがなければCloudflareの作成toolでWorkerを1つ用意し、先にHello Worldをdeployします。Workers自体の作成、local確認、deployの流れはCloudflare Workersの始め方で確認できます。AI追加とWorker作成を同時に行わず、通常responseが返る状態を基準点にすると、Binding後のerrorを追いやすくなります。

公式Workers Bindingsに沿い、wrangler.jsoncへAI bindingを追加します。Cloudflareは新しいprojectにJSON設定を推奨しており、binding名AIはcodeのenv.AIと一致させます。TypeScriptなら設定変更後にnpx wrangler typesを実行し、envのtypeを更新します。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "workers-ai-demo",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-30",
  "ai": { "binding": "AI" }
}

Dashboardから追加する場合も、productionとstagingのどちらへbindingしたかを確認します。Wranglerのenvironmentを使うとbindingは自動継承されないため、env.stagingへ必要な設定を明示します。localだけ成功してproductionでAI is undefinedになる場合は、deploy先、environment名、binding名の3点を確認してください。

env.AI.runで最小の推論を動かす

最小実装はenv.AI.run(model, input)です。下の例はPOST bodyのtextを受け、200文字以下の要約を返します。公開前は認証を追加し、本文sizeを先に検査してください。例では現在catalogに残る高速版Llamaを使いますが、利用時にはmodel pageでavailabilityとpriceを再確認します。

export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method Not Allowed", { status: 405 });
    }

    const { text = "" } = await request.json();
    if (typeof text !== "string" || text.length < 1 || text.length > 4000) {
      return Response.json({ error: "text must be 1-4000 characters" }, { status: 400 });
    }

    const result = await env.AI.run("@cf/meta/llama-3.1-8b-instruct-fast", {
      messages: [
        { role: "system", content: "次の文章を日本語200字以内で要約してください。" },
        { role: "user", content: text }
      ]
    });

    return Response.json({ summary: result.response });
  }
};

system指示とuser入力を分け、user入力を命令文へ文字列結合しないのが基本です。それでもprompt injectionを完全には防げないため、AI出力をSQL、HTML、送金、削除、email送信へ直結させません。出力は文字列としてescapeし、許可した操作だけをserver側のruleで実行します。AIの回答は「候補」であり「権限」ではありません。

まず固定した10件で結果とusageを記録し、次に空文字、4,001文字、壊れたJSON、連続request、model errorを試します。成功時だけでなく400、405、429、500のresponse形式を揃えると、frontendの分岐が簡単です。error本文へprompt、token、個人情報をそのまま返さず、追跡用request IDだけを利用者へ示します。

StreamingとJSON出力を分けて実装する

公式Binding methodsでは、入力へstream:trueを指定すると結果を順次受け取り、text/event-streamで返せます。長い回答の待ち時間を短く感じさせるのに向きますが、途中で切れた文章を完成扱いしないUIが必要です。Stop button、再接続、生成中表示、最大時間を用意します。

公式JSON Modeは、自然文ではなく指定schemaのobjectを求める機能です。商品名、category、scoreのようにprogramで使う出力へ向きます。ただしCloudflareはschema準拠を保証しておらず、JSON Mode couldn't be metを処理する必要があります。responseを再validationし、欠落fieldや範囲外scoreは不正として扱います。

JSON Modeは現時点でstreamingと併用できません。chat表示ならstreaming、databaseへ保存する分類ならJSON Modeというように、体験と機械処理を分けてください。両方必要なら、最初にstreamingで説明を見せ、確定操作の前に別requestでJSONを生成・validationする2段階にします。1回のmodel responseへ画面表示と自動処理を背負わせない設計です。2つのrequest IDを関連付けてlogへ残すと、どちらで失敗したかも追跡できます。

AI Gatewayで利用量と異常を監視する

Cloudflare公式AI Gateway概要では、request、token、cost、errorの可視化に加え、caching、rate limiting、retry、model fallbackなどを提供しています。Workers AIは推論を実行するservice、AI GatewayはAI trafficを観測・制御する層です。名前が似ていますが、同じものではありません。

XではJames Doyle氏がWorkers AIとAI Gateway、creditsとWorkers planの関係が分かりにくいと指摘しています。2026年8月時点では、prepaid AI Gateway creditsをWorkers AI推論へ使うにはGatewayのWorkers AI billingをUnified billingへし、そのgatewayをBindingまたはREST requestで指定します。標準Workers AI billingと混ぜて考えず、どの経路へ課金されるかをDashboardで確認します。

公式Analyticsではrequests、token usage、cost、errors、cached responsesを時間で絞れます。公式Rate limitingの例のように100 requests/60秒などの窓を設定し、匿名IP、login user、機能別にもapplication側で上限を重ねます。固定promptへの同一requestが多い場合だけcachingを使い、個人別回答を誤って共有しないようcache keyと対象を限定します。

個人情報を守って本番公開する

公式Data usageでは、入力、出力、embedding、training dataはCustomer Contentです。Cloudflareは他customerへ提供せず、明示的な同意なしにWorkers AI modelのtrainingやCloudflare・third-party serviceの改善へ使わないと説明しています。ただし、推論するには入力がCloudflareへ送信されます。privacy policyが「学習しない」ことと「外部へ送信しない」ことを同じにしないでください。

Xの公開例では、通常のCSV判定は端末内、AI判定時だけ列名と短いsample値を送信し、passwordやlogin IDと判断した列を除外する設計が説明されています。さらにAI処理のためCloudflareへ送信される事実は残るとも補足されています。送信前の最小化と利用者への説明をセットにする具体例です。

本番ではpassword、API key、credit card、medical情報、未公開documentをpromptへ入れないruleを作り、server側でもpattern検知・maskingを行います。AI Gatewayのrequest/response loggingを有効にする場合は、promptがlogへ残る前提でretentionと閲覧権限を確認します。公開前に、同意文、削除手順、data保存先、incident時の停止switch、model停止時の通常機能へのfallbackまで記録してください。

Cloudflare Workers AIの使い方は、Bindingを追加してenv.AI.run()を呼ぶだけなら短いcodeで始められます。難しいのは公開後も安全・予算内・一定品質で動かす部分です。今日の1stepは、Freeで使える小型modelを1つ選び、固定promptを1回実行して、response、所要時間、Neuron usageの3つを記録することです。

その1回が確認できたら、入力上限、rate limit、10〜20件のtest set、AI Gatewayの監視を順番に追加してください。高性能modelへの変更は最後で構いません。小さく測れる状態を先に作ることが、model廃止や料金改定が起きても作り直しを減らす最短ルートです。