cloudflare-workers-ai

Cloudflare Workers AI

ステータス：本番環境で利用可能 ✅ 最終更新日：2026-01-21 依存関係：cloudflare-worker-base（Worker のセットアップ用） 最新バージョン：[email protected]、@cloudflare/[email protected]、[email protected]

最近の更新（2025）：

• 2025 年 4 月 — パフォーマンス：Llama 3.3 70B が 2～4 倍高速化（投機的デコーディング、プレフィックスキャッシュ）、BGE エンベディングが 2 倍高速化
• 2025 年 4 月 — 破壊的変更：max_tokens のデフォルトが正しく 256 になりました（以前は適用されていませんでした）。BGE の pooling パラメーター（cls は mean と下位互換性がありません）
• 2025 年 — 新しいモデル（14 種）：Mistral 3.1 24B（ビジョン＋ツール）、Gemma 3 12B（128K コンテキスト）、EmbeddingGemma 300M、Llama 4 Scout、GPT-OSS 120B/20B、Qwen モデル（QwQ 32B、Coder 32B）、Leonardo 画像生成、Deepgram Aura 2、Whisper v3 Turbo、IBM Granite、Nova 3
• 2025 年 — プラットフォーム：コンテキストウィンドウ API の変更（文字数ではなくトークン数）、モデルごとに細分化されたユニットベースの料金体系、workers-ai-provider v3.0.2（AI SDK v5）、LoRA ランクの上限が 32 に（以前は 8）、アカウントごとに 100 個のアダプター
• 2025 年 10 月：モデルの非推奨化（代わりに Llama 4、GPT-OSS を使用）

---

クイックスタート（5 分）

// 1. Add AI binding to wrangler.jsonc
{ "ai": { "binding": "AI" } }

// 2. Run model with streaming (recommended)
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
      messages: [{ role: 'user', content: 'Tell me a story' }],
      stream: true, // Always stream for text generation!
    });

    return new Response(stream, {
      headers: { 'content-type': 'text/event-stream' },
    });
  },
};

ストリーミングを使う理由：メモリ内でのバッファリングを防ぎ、最初のトークンが届くまでの時間を短縮し、Worker のタイムアウト問題を回避できます。

---

既知の問題の防止

このスキルでは、文書化されている 7 件の問題を防止します。

問題 #1：コンテキストウィンドウの検証がトークン数に変更（2025 年 2 月）

エラー：モデルがより大きなコンテキストに対応しているにもかかわらず、"Exceeded character limit" が発生する 出典：Cloudflare の変更履歴 発生する理由：2025 年 2 月以前は、Workers AI は Mistral のようにトークンベースのコンテキストウィンドウがより大きいモデル（32K トークンなど）でも、ハード上限の 6144 文字でプロンプトを検証していました。更新後、検証はトークン数に基づく方式に切り替わりました。 防止策：コンテキストウィンドウの上限を確認する際は、文字数ではなくトークン数を計算してください。

import { encode } from 'gpt-tokenizer'; // or model-specific tokenizer

const tokens = encode(prompt);
const contextWindow = 32768; // Model's max tokens (check docs)
const maxResponseTokens = 2048;

if (tokens.length + maxResponseTokens > contextWindow) {
  throw new Error(`Prompt exceeds context window: ${tokens.length} tokens`);
}

const response = await env.AI.run('@cf/mistral/mistral-7b-instruct-v0.2', {
  messages: [{ role: 'user', content: prompt }],
  max_tokens: maxResponseTokens,
});

問題 #2：ダッシュボードのニューロン消費量の不一致

エラー：ダッシュボードに表示されるニューロン使用量が、トークン数に基づく予測を大幅に上回る 出典：Cloudflare コミュニティのディスカッション 発生する理由：特に AutoRAG 機能や特定のモデルで、K レベルのトークン使用量に対してダッシュボードに数億レベルのニューロン消費量が表示されるという報告があります。料金ドキュメントに基づく予測値と、ダッシュボードの実際の指標との不一致は、十分に文書化されていません。 防止策：AI Gateway のログでニューロン使用量を監視し、リクエストと照合してください。消費量が予想を大幅に上回る場合は、サポートチケットを提出してください。

// Use AI Gateway for detailed request logging
const response = await env.AI.run(
  '@cf/meta/llama-3.1-8b-instruct',
  { messages: [{ role: 'user', content: query }] },
  { gateway: { id: 'my-gateway' } }
);

// Monitor dashboard at: https://dash.cloudflare.com → AI → Workers AI
// Compare neuron usage with token counts
// File support ticket with details if discrepancy persists

問題 #3：ローカル開発で AI バインディングを使うにはリモートまたは最新のツールが必要

エラー："MiniflareCoreError: wrapped binding module can't be resolved (internal modules only)" 出典：GitHub の Issue #6796 発生する理由：ローカル開発で Miniflare と Workers AI バインディングを使用する場合（特にカスタム Vite プラグインを使用する場合）、AI バインディングには外部 Worker が必要ですが、古い unstable_getMiniflareWorkerOptions では適切に公開されません。このエラーは、Miniflare が内部 AI Worker モジュールを解決できない場合に発生します。 防止策：ローカル開発では AI にリモートバインディングを使用するか、最新の @cloudflare/vite-plugin に更新してください。

// wrangler.jsonc - Option 1: Use remote AI binding in local dev
{
  "ai": { "binding": "AI" },
  "dev": {
    "remote": true // Use production AI binding locally
  }
}

# Option 2: Update to latest tooling
npm install -D @cloudflare/vite-plugin@latest

# Option 3: Use wrangler dev instead of custom Miniflare
npm run dev

Issue #4：Flux 画像生成における NSFW フィルターの誤検知

エラー：問題のないプロンプトでも "AiError: Input prompt contains NSFW content (code 3030)" が発生します 発生元：Cloudflare コミュニティのディスカッション 発生する理由：Flux 画像生成モデル（@cf/black-forest-labs/flux-1-schnell）では、「hamburger」のような無害な単語だけのプロンプトでも、NSFW コンテンツの誤検知エラーが発生することがあります。コンテキストがないと、NSFW フィルターが過度に敏感に反応する場合があります。 防止策：単語だけのプロンプトを使うのではなく、誤検知を引き起こす可能性のある単語の前後に説明的なコンテキストを加えてください。

// ❌ May trigger error 3030
const response = await env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
  prompt: 'hamburger', // Single word triggers filter
});

// ✅ Add context to avoid false positives
const response = await env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
  prompt: 'A photo of a delicious large hamburger on a plate with lettuce and tomato',
  num_steps: 4,
});

Issue #5：num_steps パラメーターがない場合の画像生成エラー 1000

エラー："Error: unexpected type 'int32' with value 'undefined' (code 1000)" 発生元：Cloudflare コミュニティのディスカッション 発生する理由：ドキュメントでは省略可能とされていますが、num_steps パラメーターを指定しないと、画像生成 API 呼び出しでエラーコード 1000 が返されます。実際には、ほとんどの Flux モデルでこのパラメーターが必須です。 防止策：画像生成モデルでは常に num_steps: 4 を指定してください（Flux Schnell では通常 4 です）。

// ✅ Always include num_steps for image generation
const image = await env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
  prompt: 'A beautiful sunset over mountains',
  num_steps: 4, // Required - typically 4 for Flux Schnell
});

// Note: FLUX.2 [klein] 4B has fixed steps=4 (cannot be adjusted)

Issue #6：構造化出力ツールにおける Zod v4 との非互換性

エラー：Stagehand で Zod v4 を使用すると、構文エラーとトランスパイルの失敗が発生します 発生元：GitHub Issue #10798 発生する理由：Stagehand（ブラウザー自動化）と、Workers AI の一部の構造化出力の例は、Zod v4（現在のデフォルト）では動作しません。基盤となる zod-to-json-schema ライブラリがまだ Zod v4 をサポートしていないため、トランスパイルに失敗します。 防止策：zod-to-json-schema が v4 をサポートするまでは、Zod を v3 に固定してください。

# Install Zod v3 specifically
npm install zod@3

# Or pin in package.json
{
  "dependencies": {
    "zod": "~3.23.8" // Pin to v3 for compatibility
  }
}

Issue #7：リクエストごとに制御する AI Gateway のキャッシュヘッダー

エラーではありませんが、重要な機能です：AI Gateway は HTTP ヘッダーを使ったリクエスト単位のキャッシュ制御に対応しており、ダッシュボードのデフォルト設定に加えて、カスタム TTL、キャッシュのバイパス、カスタムキャッシュキーを利用できます。 発生元：AI Gateway のキャッシュに関するドキュメント 使用する場面：リクエストごとに異なるキャッシュ動作が必要な場合（例：負荷の高いクエリには 1 時間のキャッシュを適用し、リアルタイムデータではキャッシュをスキップする）。 実装：ヘッダーの使用方法については、以下の「AI Gateway Integration」セクションを参照してください。

---

API リファレンス

env.AI.run(
  model: string,
  inputs: ModelInputs,
  options?: { gateway?: { id: string; skipCache?: boolean } }
): Promise<ModelOutput | ReadableStream>

---

モデル選択ガイド（2025 年更新）

テキスト生成（LLM）

モデル	最適な用途	レート制限	サイズ	備考
2025 年のモデル
@cf/meta/llama-4-scout-17b-16e-instruct	最新の Llama、汎用	300/min	17B	2025 年新登場
@cf/openai/gpt-oss-120b	最大規模のオープンソース GPT	300/min	120B	2025 年新登場
@cf/openai/gpt-oss-20b	小型のオープンソース GPT	300/min	20B	2025 年新登場
@cf/google/gemma-3-12b-it	128K コンテキスト、140 以上の言語	300/min	12B	2025 年新登場、ビジョン対応
@cf/mistralai/mistral-small-3.1-24b-instruct	ビジョン＋ツール呼び出し	300/min	24B	2025 年新登場
@cf/qwen/qwq-32b	推論、複雑なタスク	300/min	32B	2025 年新登場
@cf/qwen/qwen2.5-coder-32b-instruct	コーディングに特化	300/min	32B	2025 年新登場
@cf/qwen/qwen3-30b-a3b-fp8	高速な量子化モデル	300/min	30B	2025 年新登場
@cf/ibm-granite/granite-4.0-h-micro	小型、高効率	300/min	Micro	2025 年新登場
パフォーマンス（2025 年）
@cf/meta/llama-3.3-70b-instruct-fp8-fast	2～4 倍高速（2025 年の更新）	300/min	70B	投機的デコーディング
@cf/meta/llama-3.1-8b-instruct-fp8-fast	高速な 8B バリアント	300/min	8B	-
標準モデル
@cf/meta/llama-3.1-8b-instruct	汎用	300/min	8B	-
@cf/meta/llama-3.2-1b-instruct	超高速、単純なタスク	300/min	1B	-
@cf/deepseek-ai/deepseek-r1-distill-qwen-32b	コーディング、技術関連	300/min	32B	-

テキスト埋め込み（2 倍高速 — 2025 年）

モデル	次元数	最適な用途	レート制限	備考
@cf/google/embeddinggemma-300m	768	クラス最高の RAG	3000/min	2025 年新登場
@cf/baai/bge-base-en-v1.5	768	汎用 RAG（2 倍高速）	3000/min	pooling: "cls" を推奨
@cf/baai/bge-large-en-v1.5	1024	高精度（2 倍高速）	1500/min	pooling: "cls" を推奨
@cf/baai/bge-small-en-v1.5	384	高速、ストレージ使用量が少ない（2 倍高速）	3000/min	pooling: "cls" を推奨
@cf/qwen/qwen3-embedding-0.6b	768	Qwen の埋め込み	3000/min	2025 年新登場

重要（2025 年）：BGE モデルは pooling: "cls" パラメーターに対応しました（推奨）。ただし、pooling: "mean"（デフォルト）との下位互換性はありません。

画像生成

モデル	最適な用途	レート制限	備考
@cf/black-forest-labs/flux-1-schnell	高品質、フォトリアル	720/min	⚠️ 以下の警告を参照
@cf/leonardo/lucid-origin	Leonardo AI スタイル	720/min	2025 年新登場、num_steps が必要
@cf/leonardo/phoenix-1.0	Leonardo AI のバリエーション	720/min	2025 年新登場、num_steps が必要
@cf/stabilityai/stable-diffusion-xl-base-1.0	汎用	720/min	num_steps が必要

⚠️ 画像生成でよくある問題：

• エラー 1000：ドキュメントでは省略可能とされていますが、必須の num_steps: 4 パラメーターを必ず指定してください
• エラー 3030（NSFW フィルター）：「ハンバーガー」などの単語だけで誤検知されることがあります。プロンプトに説明的な文脈を追加してください

// ✅ Correct pattern for image generation
const image = await env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
  prompt: 'A photo of a delicious hamburger on a plate with fresh vegetables',
  num_steps: 4, // Required to avoid error 1000
});
// Descriptive context helps avoid NSFW false positives (error 3030)

ビジョンモデル

モデル	最適な用途	レート制限	備考
@cf/meta/llama-3.2-11b-vision-instruct	画像の理解	720/min	-
@cf/google/gemma-3-12b-it	ビジョン＋テキスト（128K コンテキスト）	300/min	2025 年新登場

音声モデル（2025 年）

モデル	種類	レート制限	備考
@cf/deepgram/aura-2-en	テキスト読み上げ（英語）	720/min	2025 年新登場
@cf/deepgram/aura-2-es	テキスト読み上げ（スペイン語）	720/min	2025 年新登場
@cf/deepgram/nova-3	音声テキスト変換（＋WebSocket）	720/min	2025 年新登場
@cf/openai/whisper-large-v3-turbo	音声テキスト変換（高速）	720/min	2025 年新登場

---

よくあるパターン

RAG（検索拡張生成）

// 1. Generate embeddings
const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [userQuery] });

// 2. Search Vectorize
const matches = await env.VECTORIZE.query(embeddings.data[0], { topK: 3 });
const context = matches.matches.map((m) => m.metadata.text).join('\n\n');

// 3. Generate with context
const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [
    { role: 'system', content: `Answer using this context:\n${context}` },
    { role: 'user', content: userQuery },
  ],
  stream: true,
});

---

Zod による構造化出力

import { z } from 'zod';

const Schema = z.object({ name: z.string(), items: z.array(z.string()) });

const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [{
    role: 'user',
    content: `Generate JSON matching: ${JSON.stringify(Schema.shape)}`
  }],
});

const validated = Schema.parse(JSON.parse(response.response));

---

AI Gateway の統合

AI リクエスト向けに、キャッシュ、ログ記録、コスト追跡、分析機能を提供します。

Gateway の基本的な使い方

const response = await env.AI.run(
  '@cf/meta/llama-3.1-8b-instruct',
  { prompt: 'Hello' },
  { gateway: { id: 'my-gateway', skipCache: false } }
);

// Access logs and send feedback
const gateway = env.AI.gateway('my-gateway');
await gateway.patchLog(env.AI.aiGatewayLogId, {
  feedback: { rating: 1, comment: 'Great response' },
});

リクエストごとのキャッシュ制御（上級）

HTTP ヘッダーを使ってデフォルトのキャッシュ動作を上書きし、きめ細かく制御できます。

// Custom cache TTL (1 hour for expensive queries)
const response = await fetch(
  `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/workers-ai/@cf/meta/llama-3.1-8b-instruct`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${env.CLOUDFLARE_API_KEY}`,
      'Content-Type': 'application/json',
      'cf-aig-cache-ttl': '3600', // 1 hour in seconds (min: 60, max: 2592000)
    },
    body: JSON.stringify({
      messages: [{ role: 'user', content: prompt }],
    }),
  }
);

// Skip cache for real-time data
const response = await fetch(gatewayUrl, {
  headers: {
    'cf-aig-skip-cache': 'true', // Bypass cache entirely
  },
  // ...
});

// Check if response was cached
const cacheStatus = response.headers.get('cf-aig-cache-status'); // "HIT" or "MISS"

利用可能なキャッシュヘッダー：

• cf-aig-cache-ttl：秒単位でカスタム TTL を設定します（60 秒〜1 か月）
• cf-aig-skip-cache：キャッシュを完全にバイパスします（'true'）
• cf-aig-cache-key：きめ細かな制御のためのカスタムキャッシュキー
• cf-aig-cache-status：「HIT」または「MISS」を示すレスポンスヘッダー

**メリット：**コスト追跡、キャッシュ（推論の重複を削減）、ログ記録、レート制限、分析、リクエストごとのキャッシュカスタマイズ。

---

レート制限と料金（2025 年更新）

レート制限（分あたり）

タスクの種類	デフォルトの制限	備考
テキスト生成	300/min	一部の高速モデル：400-1500/min
テキスト埋め込み	3000/min	BGE-large：1500/min
画像生成	720/min	すべての画像モデル
ビジョンモデル	720/min	画像の理解
音声（TTS/STT）	720/min	Deepgram、Whisper
翻訳	720/min	M2M100、Opus MT
分類	2000/min	テキスト分類

料金（ユニット制、ニューロンで請求 — 2025年）

無料枠：

• 1日あたり10,000ニューロン
• 毎日00:00 UTCにリセット

有料枠（1,000ニューロンあたり$0.011）：

• 1日あたり10,000ニューロンを含む
• 無料枠を超える利用は無制限

2025年のモデル料金（100万トークンあたり）：

モデル	入力	出力	備考
2025年モデル
Llama 4 Scout 17B	$0.270	$0.850	2025年新登場
GPT-OSS 120B	$0.350	$0.750	2025年新登場
GPT-OSS 20B	$0.200	$0.300	2025年新登場
Gemma 3 12B	$0.345	$0.556	2025年新登場
Mistral 3.1 24B	$0.351	$0.555	2025年新登場
Qwen QwQ 32B	$0.660	$1.000	2025年新登場
Qwen Coder 32B	$0.660	$1.000	2025年新登場
IBM Granite Micro	$0.017	$0.112	2025年新登場
EmbeddingGemma 300M	$0.012	N/A	2025年新登場
Qwen3 Embedding 0.6B	$0.012	N/A	2025年新登場
パフォーマンス（2025年）
Llama 3.3 70B Fast	$0.293	$2.253	2～4倍高速
Llama 3.1 8B FP8 Fast	$0.045	$0.384	高速版
標準モデル
Llama 3.2 1B	$0.027	$0.201	-
Llama 3.1 8B	$0.282	$0.827	-
Deepseek R1 32B	$0.497	$4.881	-
BGE-base（2倍高速）	$0.067	N/A	2025年に高速化
BGE-large（2倍高速）	$0.204	N/A	2025年に高速化
画像モデル（2025年）
Flux 1 Schnell	512x512タイルあたり$0.0000528	-
Leonardo Lucid	512x512タイルあたり$0.006996	2025年新登場
Leonardo Phoenix	512x512タイルあたり$0.005830	2025年新登場
音声モデル（2025年）
Deepgram Aura 2	1,000文字あたり$0.030	2025年新登場
Deepgram Nova 3	音声1分あたり$0.0052	2025年新登場
Whisper v3 Turbo	音声1分あたり$0.0005	2025年新登場

---

リトライを伴うエラー処理

async function runAIWithRetry(
  env: Env,
  model: string,
  inputs: any,
  maxRetries = 3
): Promise<any> {
  let lastError: Error;

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await env.AI.run(model, inputs);
    } catch (error) {
      lastError = error as Error;

      // Rate limit - retry with exponential backoff
      if (lastError.message.toLowerCase().includes('rate limit')) {
        await new Promise((resolve) => setTimeout(resolve, Math.pow(2, i) * 1000));
        continue;
      }

      throw error; // Other errors - fail immediately
    }
  }

  throw lastError!;
}

---

OpenAI との互換性

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: env.CLOUDFLARE_API_KEY,
  baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/ai/v1`,
});

// Chat completions
await openai.chat.completions.create({
  model: '@cf/meta/llama-3.1-8b-instruct',
  messages: [{ role: 'user', content: 'Hello!' }],
});

エンドポイント： /v1/chat/completions、/v1/embeddings

---

Vercel AI SDK との統合（workers-ai-provider v3.0.2）

import { createWorkersAI } from 'workers-ai-provider'; // v3.0.2 with AI SDK v5
import { generateText, streamText } from 'ai';

const workersai = createWorkersAI({ binding: env.AI });

// Generate or stream
await generateText({
  model: workersai('@cf/meta/llama-3.1-8b-instruct'),
  prompt: 'Write a poem',
});

---

コミュニティのヒント

注記：これらのヒントは、コミュニティでの議論や実運用の経験に基づいています。

Hono フレームワークでのストリーミングパターン

Hono で Workers AI のストリーミングを使用する場合は、ストリームを Hono のストリーミングユーティリティ経由ではなく、Response として直接返してください。

import { Hono } from 'hono';

type Bindings = { AI: Ai };
const app = new Hono<{ Bindings: Bindings }>();

app.post('/chat', async (c) => {
  const { prompt } = await c.req.json();

  const stream = await c.env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
    messages: [{ role: 'user', content: prompt }],
    stream: true,
  });

  // Return stream directly (not c.stream())
  return new Response(stream, {
    headers: {
      'content-type': 'text/event-stream',
      'cache-control': 'no-cache',
      'connection': 'keep-alive',
    },
  });
});

出典：Hono Discussion #2409

原因不明の AI バインディング障害のトラブルシューティング

原因不明の Workers AI の障害が発生する場合：

# 1. Check wrangler version
npx wrangler --version

# 2. Clear wrangler cache
rm -rf ~/.wrangler

# 3. Update to latest stable
npm install -D wrangler@latest

# 4. Check local network/firewall settings
# Some corporate firewalls block Workers AI endpoints

注記：「バージョンの互換性」の問題の多くは、実際にはネットワーク設定の問題です。

---

参考資料

• Workers AI ドキュメント
• モデルカタログ
• AI Gateway
• 料金
• 変更履歴
• LoRA アダプター
• MCP ツール：最新のドキュメントには mcp__cloudflare-docs__search_cloudflare_documentation を使用してください