cloudflare-workers-ai

Cloudflare Workers AI - 完全リファレンス

Cloudflare Workers AI を使用して AI 搭載アプリケーションを構築するための、本番環境対応のナレッジドメインです。

ステータス: 本番環境対応 ✅ 最終更新日: 2025-11-21 依存関係: cloudflare-worker-base（Worker のセットアップ用） 最新バージョン: [email protected], @cloudflare/[email protected]

---

目次

1. クイックスタート（5 分）
2. Workers AI API リファレンス
3. モデル選択ガイド
4. 一般的なパターン
5. AI Gateway の統合
6. レート制限と料金
7. 本番環境チェックリスト

---

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

1. AI バインディングを追加する

wrangler.jsonc:

{
  "ai": {
    "binding": "AI"
  }
}

2. 最初のモデルを実行する

export interface Env {
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
      prompt: 'What is Cloudflare?',
    });

    return Response.json(response);
  },
};

3. ストリーミングを追加する（推奨）

const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true, // Always use streaming for text generation!
});

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

ストリーミングを使う理由

• 大きなレスポンスがメモリにバッファリングされるのを防ぎます
• 最初のトークンが届くまでの時間を短縮します
• 長文コンテンツでのユーザー体験が向上します
• Worker のタイムアウト問題を回避できます

---

Workers AI API リファレンス

コア API: env.AI.run()

const response = await env.AI.run(model, inputs, options?);

パラメーター	型	説明
model	string	モデル ID（例: @cf/meta/llama-3.1-8b-instruct）
inputs	object	モデル固有の入力（下記のモデルタイプを参照）
options.gateway.id	string	キャッシュ／ログ記録用の AI Gateway ID
options.gateway.skipCache	boolean	AI Gateway のキャッシュをスキップします

戻り値: Promise<ModelOutput>（非ストリーミング）または ReadableStream（ストリーミング）

モデルカテゴリ別の入力タイプ

カテゴリ	主な入力	出力
テキスト生成	messages[], stream, max_tokens, temperature	{ response: string }
埋め込み	text: string | string[]	{ data: number[][], shape: number[] }
画像生成	prompt, num_steps, guidance	バイナリ PNG
ビジョン	messages[].content[].image_url	{ response: string }

📄 モデルの詳細: モデルの完全な一覧、パラメーター、レート制限については、references/models-catalog.md を読み込んでください。

---

モデル選択ガイド

テキスト生成（LLM）

モデル	最適な用途	レート制限	サイズ
@cf/meta/llama-3.1-8b-instruct	汎用、高速	300/min	8B
@cf/meta/llama-3.2-1b-instruct	超高速、単純なタスク	300/min	1B
@cf/qwen/qwen1.5-14b-chat-awq	高品質、複雑な推論	150/min	14B
@cf/deepseek-ai/deepseek-r1-distill-qwen-32b	コーディング、技術コンテンツ	300/min	32B
@hf/thebloke/mistral-7b-instruct-v0.1-awq	高速、効率的	400/min	7B

テキスト埋め込み

モデル	次元数	最適な用途	レート制限
@cf/baai/bge-base-en-v1.5	768	汎用 RAG	3000/min
@cf/baai/bge-large-en-v1.5	1024	高精度検索	1500/min
@cf/baai/bge-small-en-v1.5	384	高速、低ストレージ使用量	3000/min

画像生成

モデル	最適な用途	レート制限	速度
@cf/black-forest-labs/flux-1-schnell	高品質、フォトリアル	720/min	高速
@cf/stabilityai/stable-diffusion-xl-base-1.0	汎用	720/min	中速
@cf/lykon/dreamshaper-8-lcm	アーティスティック、様式化	720/min	高速

ビジョンモデル

モデル	最適な用途	レート制限
@cf/meta/llama-3.2-11b-vision-instruct	画像理解	720/min
@cf/unum/uform-gen2-qwen-500m	高速な画像キャプション生成	720/min

---

一般的なパターン

パターン 1: ストリーミングを使ったチャット

app.post('/chat', async (c) => {
  const { messages } = await c.req.json<{ messages: Array<{ role: string; content: string }> }>();
  const stream = await c.env.AI.run('@cf/meta/llama-3.1-8b-instruct', { messages, stream: true });
  return new Response(stream, { headers: { 'content-type': 'text/event-stream' } });
});

パターン 2: RAG（検索拡張生成）

// 1. Generate embedding for query
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 });
// 3. Build context
const context = matches.matches.map((m) => m.metadata.text).join('\n\n');
// 4. Generate with context
const stream = 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,
});
return new Response(stream, { headers: { 'content-type': 'text/event-stream' } });

📄 その他のパターン: 構造化出力、画像生成、複数モデルの合意形成、本番環境向けパターンについては、references/best-practices.md を読み込んでください。

---

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 },
});

メリット：コスト追跡、レスポンスのキャッシュ（繰り返しのクエリで 50～90% のコスト削減）、リクエストのログ記録、レート制限、分析。

---

レート制限と料金

最終確認日：2025-01-14

レート制限と料金はモデルによって大きく異なります。最新情報は、必ず公式ドキュメントで確認してください：

• レート制限：https://developers.cloudflare.com/workers-ai/platform/limits/
• 料金：https://developers.cloudflare.com/workers-ai/platform/pricing/

無料枠：1 日あたり 10,000 neurons 有料枠：1,000 neurons あたり $0.011

📄 モデルごとの詳細：各モデルの具体的なレート制限と料金については、references/models-catalog.md を参照してください。

---

本番環境へのデプロイチェックリスト

デプロイ前に必ず確認してください：

• コスト追跡のために AI Gateway を有効にする
• テキスト生成にストリーミングを実装する
• 指数バックオフによるレート制限時の再試行を追加する
• 入力の長さを検証する（トークン制限エラーを防止）
• 入力のサニタイズを追加する（プロンプトインジェクションを防止）

📄 完全版チェックリスト：本番環境への完全なチェックリスト、エラー処理のパターン、モニタリング、コスト最適化については、references/best-practices.md を読み込んでください。

---

外部 SDK との統合

Workers AI は OpenAI SDK との互換性と Vercel AI SDK をサポートしています：

// OpenAI SDK - use same patterns with Workers AI models
const openai = new OpenAI({
  apiKey: env.CLOUDFLARE_API_KEY,
  baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/ai/v1`,
});

// Vercel AI SDK - native integration
import { createWorkersAI } from 'workers-ai-provider';
const workersai = createWorkersAI({ binding: env.AI });

📄 統合ガイドの完全版：OpenAI SDK、Vercel AI SDK、REST API の例については、references/integrations.md を読み込んでください。

---

制限の概要

機能	制限
同時リクエスト数	固定の上限なし（レート制限が適用されます）
入力トークンの最大数	モデルによって異なります（通常 2K～128K）
出力トークンの最大数	モデルによって異なります（通常 512～2048）
ストリーミングのチャンクサイズ	約 1 KB
画像サイズ（出力）	約 5 MB
リクエストのタイムアウト	Workers のタイムアウトが適用されます（デフォルト 30s、最大 CPU 時間 5m）
1 日あたりの無料 neurons	10,000
レート制限	「レート制限と料金」セクションを参照

---

リファレンスを読み込むタイミング

リファレンスファイル	読み込むタイミング
references/models-catalog.md	モデルの選択、レート制限の確認、モデルの機能の比較
references/best-practices.md	本番環境へのデプロイ、エラー処理、コスト最適化、セキュリティ
references/integrations.md	ネイティブバインディングの代わりに OpenAI SDK、Vercel AI SDK、REST API を使用する場合

---

参考資料

• Workers AI ドキュメント
• モデルカタログ
• AI Gateway
• 料金