
このガイドでは、Cloudflare Workers、D1、Vectorize を活用した、コールドスタートゼロのサーバーレスエッジ AI アプリケーションの構築について詳しく説明します。Workers AI と Gemini を利用し、リアルタイムの検索拡張生成(RAG)システムを実装し、50ms 未満のレイテンシーでクライアントブラウザに直接ストリーミング応答を行います。本番環境レベルのアーキテクチャ、スキーマ移行、パフォーマンスに関する考慮事項に焦点を当てます。
提案するアーキテクチャは、Cloudflare のグローバルネットワークを統合し、低レイテンシーの AI 推論とデータアクセスを実現します。
この設計により、データの局所性が確保され、ネットワークホップが最小限に抑えられ、Cloudflare のサーバーレスサービスを活用してスケーラビリティとコスト効率が向上します。
wrangler がインストールされ、設定されていることを確認してください。
npm install -g wrangler
wrangler login
ドキュメントのメタデータを保存するための D1 データベースを作成します。
wrangler d1 create my-rag-metadata
# Output will include a binding name, e.g., D1_BINDING_NAME
D1 バインディングを wrangler.toml に追加します。
# wrangler.toml
name = "edge-rag-worker"
main = "src/index.ts"
compatibility_date = "2024-10-27"
compatibility_flags = ["nodejs_compat"]
[[d1_databases]]
binding = "DB" # This is the binding name you'll use in your Worker
database_name = "my-rag-metadata"
database_id = "<YOUR_D1_DATABASE_ID>" # From `wrangler d1 create` output
ドキュメントチャンクにはシンプルなスキーマを使用します。
-- migrations/0001_initial_schema.sql
CREATE TABLE IF NOT EXISTS document_chunks (
id TEXT PRIMARY KEY,
document_id TEXT NOT NULL,
chunk_text TEXT NOT NULL,
metadata JSON,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX IF NOT EXISTS idx_document_id ON document_chunks (document_id);
移行を適用します。
wrangler d1 migrations apply my-rag-metadata --local --env production
埋め込みを保存するための Vectorize インデックスを作成します。
wrangler vectorize create my-rag-vectors --dimensions=768 --metric=cosine
# Output will include a binding name, e.g., VECTORIZE_BINDING_NAME
Vectorize バインディングを wrangler.toml に追加します。
# wrangler.toml (continued)
[[vectorize]]
binding = "VECTORIZE_INDEX" # This is the binding name you'll use in your Worker
index_name = "my-rag-vectors"
まず、ドキュメントとその埋め込みを追加するためのインジェストロジックを定義しましょう。これは通常、内部エンドポイントまたは別の Worker になります。
// src/ingest.ts
import { Hono } from 'hono';
import { env } from 'hono/adapter';
import { Bindings } from './types'; // Define your Bindings interface
const ingestApp = new Hono();
// Helper to chunk text (simplified for brevity)
function chunkText(text: string, chunkSize: number = 512, overlap: number = 50): string[] {
const chunks: string[] = [];
let i = 0;
while (i < text.length) {
const end = Math.min(i + chunkSize, text.length);
chunks.push(text.substring(i, end));
i += chunkSize - overlap;
if (i < 0) i = 0; // Prevent negative index if overlap > chunkSize
}
return chunks;
}
ingestApp.post('/ingest', async (c) => {
const { DB, VECTORIZE_INDEX, AI } = env<Bindings>(c);
const { documentId, text, metadata } = await c.req.json();
if (!documentId || !text) {
return c.json({ error: 'documentId and text are required' }, 400);
}
const chunks = chunkText(text);
const vectorsToInsert: { id: string; values: number[]; metadata: Record<string, any> }[] = [];
const dbInserts: { id: string; document_id: string; chunk_text: string; metadata: string }[] = [];
for (const chunk of chunks) {
// Generate embedding using Workers AI
const { data } = await AI.run('@cf/baai/bge-small-en-v1.5', { text: chunk });
const embedding = data[0];
const chunkId = crypto.randomUUID(); // Unique ID for each chunk
vectorsToInsert.push({
id: chunkId,
values: embedding,
metadata: { documentId, ...metadata }, // Store relevant metadata with vector
});
dbInserts.push({
id: chunkId,
document_id: documentId,
chunk_text: chunk,
metadata: JSON.stringify({ documentId, ...metadata }),
});
}
// Insert into Vectorize
const vectorizeResult = await VECTORIZE_INDEX.upsert(vectorsToInsert);
// Insert into D1
const stmt = DB.prepare(
'INSERT INTO document_chunks (id, document_id, chunk_text, metadata) VALUES (?, ?, ?, ?)'
);
const dbResult = await DB.batch(dbInserts.map((d) => stmt.bind(d.id, d.document_id, d.chunk_text, d.metadata)));
return c.json({
message: `Ingested ${chunks.length} chunks for document ${documentId}`,
vectorizeResult,
dbResult,
});
});
export default ingestApp;
これは、クライアントリクエストを処理するコア RAG Worker です。
// src/index.ts
import { Hono } from 'hono';
import { streamText, streamSSE } from 'hono/streaming';
import { env } from 'hono/adapter';
import { Bindings } from './types'; // Define your Bindings interface
const app = new Hono();
// Define the Bindings interface for better type safety
export interface Bindings {
DB: D1Database;
VECTORIZE_INDEX: VectorizeIndex;
AI: Ai;
GOOGLE_GEMINI_API_KEY?: string; // Optional for Gemini direct access
}
app.get('/', (c) => c.text('Edge RAG Worker is running!'));
app.post('/ask', async (c) => {
const { DB, VECTORIZE_INDEX, AI, GOOGLE_GEMINI_API_KEY } = env<Bindings>(c);
const { query } = await c.req.json();
if (!query) {
return c.json({ error: 'Query is required' }, 400);
}
return streamSSE(c, async (stream) => {
try {
await stream.writeSSE({ event: 'status', data: 'Generating query embedding...' });
// 1. Generate embedding for the query
const { data: queryEmbedding } = await AI.run('@cf/baai/bge-small-en-v1.5', { text: query });
const embedding = queryEmbedding[0];
await stream.writeSSE({ event: 'status', data: 'Searching Vectorize...' });
// 2. Search Vectorize for similar document chunks
const searchResults = await VECTORIZE_INDEX.query(embedding, { topK: 5, returnMetadata: true });
if (!searchResults.matches || searchResults.matches.length === 0) {
await stream.writeSSE({ event: 'error', data: 'No relevant documents found.' });
await stream.close();
return;
}
await stream.writeSSE({ event: 'status', data: 'Retrieving context from D1...' });
// 3. Retrieve full chunk text from D1 using the IDs
const chunkIds = searchResults.matches.map((match) => match.id);
const { results: dbResults } = await DB.prepare(
`SELECT chunk_text FROM document_chunks WHERE id IN (${chunkIds.map(() => '?').join(',')})`
)
.bind(...chunkIds)
.all<{ chunk_text: string }>();
const context = dbResults.map((row) => row.chunk_text).join('\n\n');
await stream.writeSSE({ event: 'status', data: 'Generating answer with LLM...' });
// 4. Assemble prompt for LLM
const prompt = `You are a helpful AI assistant. Use the following context to answer the question. If you don't know the answer, state that you don't know.
Context:
${context}
Question: ${query}
Answer:`;
// 5. Stream LLM response
// Option A: Workers AI (recommended for simplicity and edge performance)
const response = await AI.run('@cf/mistral/mistral-7b-instruct-v0.1', {
prompt,
stream: true,
});
// Option B: Google Gemini (requires API key and direct fetch)
// if (GOOGLE_GEMINI_API_KEY) {
// const geminiResponse = await fetch('https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:streamGenerateContent', {
// method: 'POST',
// headers: {
// 'Content-Type': 'application/json',
// 'x-goog-api-key': GOOGLE_GEMINI_API_KEY,
// },
// body: JSON.stringify({
// contents: [{ parts: [{ text: prompt }] }],
// generationConfig: {
// stream: true,
// },
// }),
// });
// if (!geminiResponse.ok) {
// throw new Error(`Gemini API error: ${geminiResponse.statusText}`);
// }
// // Parse and stream Gemini's SSE-like response
// const reader = geminiResponse.body?.getReader();
// if (!reader) throw new Error('Failed to get reader from Gemini response');
// const decoder = new TextDecoder();
// while (true) {
// const { done, value } = await reader.read();
// if (done) break;
// const chunk = decoder.decode(value, { stream: true });
// // Gemini's streaming format is complex, often JSON objects per line.
// // This is a simplified parse. Production code needs robust parsing.
// const lines = chunk.split('\n').filter(Boolean);
// for (const line of lines) {
// try {
// const json = JSON.parse(line);
// if (json.candidates && json.candidates[0] && json.candidates[0].content && json.candidates[0].content.parts) {
// const textPart = json.candidates[0].content.parts[0].text;
// await stream.writeSSE({ event: 'data', data: textPart });
// }
// } catch (e) {
// console.error('Failed to parse Gemini stream chunk:', e, chunk);
// }
// }
// }
// await stream.writeSSE({ event: 'status', data: 'Stream complete.' });
// await stream.close();
// return;
// }
// Workers AI streaming
const reader = response.body?.getReader();
if (!reader) throw new Error('Failed to get reader from AI response');
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value, { stream: true });
await stream.writeSSE({ event: 'data', data: chunk });
}
await stream.writeSSE({ event: 'status', data: 'Stream complete.' });
await stream.close();
} catch (error: any) {
console.error('RAG stream error:', error);
await stream.writeSSE({ event: 'error', data: `An error occurred: ${error.message}` });
await stream.close();
}
});
});
export default app;
ingestApp と app を単一の Worker で使用するには、Hono の app.route() を使用して結合するか、個別の Worker としてエクスポートできます。簡潔にするために、src/index.ts に RAG クエリロジックが含まれており、src/ingest.ts が個別の Worker または内部エンドポイントであると仮定します。
src/index.ts Worker の場合、wrangler.toml に AI バインディングがあることを確認してください。
# wrangler.toml (continued)
[ai]
binding = "AI" # This is the binding name you'll use in your Worker
Gemini を直接使用する場合:
# wrangler.toml (continued)
[vars]
GOOGLE_GEMINI_API_KEY = "<YOUR_GEMINI_API_KEY>" # Set this in production via `wrangler secret put`
クライアント側では、EventSource を使用して SSE ストリームを消費します。
<!-- public/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Edge RAG Chat</title>
<style>
body { font-family: sans-serif; margin: 20px; }
#chat-container { max-width: 800px; margin: auto; border: 1px solid #ccc; padding: 15px; border-radius: 8px; }
#messages { height: 400px; overflow-y: scroll; border: 1px solid #eee; padding: 10px; margin-bottom: 10px; background-color: #f9f9f9; }
.message { margin-bottom: 8px; }
.user-message { text-align: right; color: blue; }
.ai-message { text-align: left; color: green; }
#query-input { width: calc(100% - 80px); padding: 8px; border: 1px solid #ccc; border-radius: 4px; }
#send-button { width: 70px; padding: 8px; margin-left: 5px; background-color: #007bff; color: white; border: none; border-radius: 4px; cursor: pointer; }
#send-button:disabled { background-color: #cccccc; cursor: not-allowed; }
</style>
</head>
<body>
<div id="chat-container">
<h1>Edge RAG Chat</h1>
<div id="messages"></div>
<input type="text" id="query-input" placeholder="Ask me anything...">
<button id="send-button">Send</button>
</div>
<script>
const queryInput = document.getElementById('query-input');
const sendButton = document.getElementById('send-button');
const messagesDiv = document.getElementById('messages');
async function sendMessage() {
const query = queryInput.value.trim();
if (!query) return;
appendMessage('user', query);
queryInput.value = '';
sendButton.disabled = true;
const aiMessageDiv = appendMessage('ai', 'Thinking...');
let fullResponse = '';
try {
const eventSource = new EventSource('/ask'); // Adjust endpoint if needed
eventSource.onopen = () => {
console.log('SSE connection opened.');
// Send the query immediately after connection opens
fetch('/ask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query }),
}).catch(error => {
console.error('Error sending query:', error);
eventSource.close();
aiMessageDiv.textContent = `Error: ${error.message}`;
sendButton.disabled = false;
});
};
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.event === 'data') {
fullResponse += data.data;
aiMessageDiv.textContent = fullResponse;
messagesDiv.scrollTop = messagesDiv.scrollHeight; // Scroll to bottom
} else if (data.event === 'status') {
console.log('Status:', data.data);
// Optionally update a status indicator
} else if (data.event === 'error') {
console.error('Worker Error:', data.data);
aiMessageDiv.textContent = `Error: ${data.data}`;
eventSource.close();
} else if (data.event === 'stream_complete') {
console.log('Stream complete.');
eventSource.close();
}
};
eventSource.onerror = (error) => {
console.error('SSE Error:', error);
eventSource.close();
if (aiMessageDiv.textContent === 'Thinking...') {
aiMessageDiv.textContent = 'Error: Failed to connect or stream.';
}
sendButton.disabled = false;
};
// Note: EventSource doesn't support POST directly.
// The above `fetch` call is a workaround to send the initial POST data.
// For a true SSE POST, you'd need a custom fetch-based streaming solution
// or pass the query in the URL for GET (less secure/flexible).
// Cloudflare Workers can handle the POST and then initiate SSE.
// The current setup assumes the Worker will process the POST and then
// use the established SSE connection for streaming. This is a common pattern.
} catch (error) {
console.error('Fetch error:', error);
aiMessageDiv.textContent = `Error: ${error.message}`;
} finally {
sendButton.disabled = false;
}
}
function appendMessage(sender, text) {
const messageDiv = document.createElement('div');
messageDiv.classList.add('message', `${sender}-message`);
messageDiv.textContent = text;
messagesDiv.appendChild(messageDiv);
messagesDiv.scrollTop = messagesDiv.scrollHeight;
return messageDiv; // Return the div to update it later
}
sendButton.addEventListener('click', sendMessage);
queryInput.addEventListener('keypress', (e) => {
if (e.key === 'Enter') {
sendMessage();
}
});
</script>
</body>
</html>
クライアント側の SSE と POST に関する重要な注意点: EventSource API は本質的に GET リクエストを使用します。クエリを伴う POST リクエストを送信し、その後 SSE を受信するには、上記のクライアント側コードは一般的な回避策を使用します。つまり、EventSource を開始し(GET を行います)、その後すぐにクエリを伴う fetch POST リクエストを送信します。Cloudflare Worker はこれを処理するように設計されている必要があります。POST を受信し、クエリを処理し、既存の EventSource 接続(クライアントの接続によって識別されます)を使用してデータをストリーミングバックします。これには、Worker 側での慎重な状態管理、またはより高度なストリーミングライブラリが必要です。
EventSource のよりシンプルで堅牢なアプローチは、GET リクエストのクエリを URL パラメータとして渡すか、POST とストリーミングを完全に制御するために ReadableStream を fetch と直接使用することです。このガイドでは、Worker が POST と SSE 接続を関連付けることができると仮定します。
Cloudflare のエッジネイティブな Vectorize と D1 を、従来のオリジンホスト型ソリューションと比較します。
| 機能 / メトリック | Cloudflare Vectorize + D1 (エッジ) | 自己ホスト型 Faiss/PgVector + PostgreSQL (オリジン) | マネージドベクトル DB (例: Pinecone) + マネージド SQL (オリジン) |
|---|---|---|---|
| デプロイモデル | サーバーレス、エッジネイティブ | 自己管理、オリジンホスト型 | マネージドサービス、オリジンホスト型 |
| コールドスタートレイテンシー | ~0ms (Workers) | 100ms - 500ms (コンテナ起動、DB 接続) | 50ms - 200ms (API ゲートウェイ、DB 接続) |
| クエリレイテンシー (P95) | < 50ms (LLM 推論を含むグローバル平均) | 150ms - 500ms (オリジンへのネットワーク、DB クエリ、LLM 推論) | 100ms - 400ms (オリジンへのネットワーク、API コール、LLM 推論) |
| データ局所性 | グローバル分散、最寄りの PoP からデータを提供 | 単一リージョン (マルチリージョン設定でない限り) | 単一リージョン (マルチリージョン設定でない限り) |
| スケーラビリティ | 自動、弾力的 | 手動スケーリング、複雑 | 自動、ただし階層化/高価な場合が多い |
| コストモデル | 使用量ベース (リクエスト、データストレージ) | 固定インフラストラクチャ + 使用量 | 使用量ベース (ベクトル、クエリ、ポッド) |
| 開発者体験 | Workers と統合、wrangler CLI | 手動セットアップ、インフラストラクチャ管理 | API 駆動、個別のサービス管理 |
| データ一貫性 | 結果整合性 (Vectorize)、強力 (D1) | 強力 | 強力 (通常) |
| ベクトル次元 | 最大 768 (@cf/baai/bge-small-en-v1.5 の現在の制限) | 柔軟 | 柔軟 |
| 最大ベクトル数 | 数十億 (スケーラブル) | インスタンスサイズによって制限される | 数十億 (スケーラブル、ただしコストが増加) |
Error: D1_ERROR: no such column: ... または D1_ERROR: table document_chunks has no column named ...wrangler d1 migrations apply <DB_NAME> --env production を使用します。ローカル開発には --local を使用します。手動で変更を加えた場合は、wrangler d1 reset(危険: すべてのデータを削除します)を検討し、再適用します。Error: Vectorize index 'my-rag-vectors' not found または Unauthorized to access Vectorize index。wrangler.toml の index_name が実際のインデックス名と一致しないか、Worker トークンに権限がありません。wrangler.toml と wrangler vectorize list の出力を再確認します。Cloudflare API トークン(wrangler で使用)に「Workers KV Storage Write」と「Workers AI」の権限があることを確認します。これには Vectorize が暗黙的に含まれます。Error: Workers AI: Rate limit exceeded または Error: Workers AI: Model '@cf/baai/bge-small-en-v1.5' not found。EventSource vs. Worker streamSSE):
EventSource が onmessage をトリガーしない。EventSource は GET リクエストのみをサポートします。Worker が初期クエリに POST を期待している場合、EventSource 接続が POST データと正しく関連付けられない可能性があります。また、Worker からの不適切な Content-Type または Transfer-Encoding ヘッダーが SSE を破損する可能性があります。EventSource の場合: Worker を設計して、GET リクエストの URL パラメータ(例: /ask?query=...)を介してクエリを受け入れるようにします。これは EventSource を使用する最も堅牢な方法です。fetch を ReadableStream とともに使用します。Worker は new ReadableStream() を伴う Response を返します。これにより完全な制御が可能になりますが、より多くのクライアント側コードが必要です。Content-Type: text/event-stream と Cache-Control: no-cache を設定していることを確認します。hono/streaming はこれを正しく処理します。SELECT ... WHERE id IN (...)。IN 句の ID が多すぎる、またはインデックスがない。CREATE INDEX IF NOT EXISTS idx_document_id ON document_chunks (document_id);)が作成されていることを確認します。非常に大きな IN 句の場合は、D1 ルックアップをバッチ処理するか、より少なく、より関連性の高い結果を返すようにベクトル検索を最適化することを検討してください。記述されたServerless Edge AIアーキテクチャにおいて、Vectorizeでベクトル検索を実行した*後*にCloudflare D1からメタデータをフェッチする主な理由は何ですか?Vectorize内に必要なすべてのメタデータを直接保存するのではなく。
Cloudflare Vectorize は Pinecone や Weaviate のような専用のベクトルデータベースと比較してどうですか? Vectorize は、Cloudflare ネットワークに直接統合されたエッジネイティブなサーバーレスベクトルデータベースです。その主な利点は、コールドスタートゼロのレイテンシーとデータの局所性であり、最寄りの PoP からクエリを提供します。専用サービスは、より高度な機能(例: フィルタリング、複雑なインデックスアルゴリズム、ハイブリッド検索)や、非常に大規模なデータセット向けのより高い次元/スケールを提供することがよくありますが、通常、オリジンホスティングとネットワークホップのためにレイテンシーが高くなります。ほとんどの RAG アプリケーションにとって、Vectorize のパフォーマンスと Workers AI との統合は魅力的です。
Workers AI で @cf/baai/bge-small-en-v1.5 以外の埋め込みモデルを使用できますか?
はい、Workers AI は増え続ける埋め込みモデルのリストをサポートしています。最新の利用可能なモデルとその次元については、Cloudflare Workers AI ドキュメントを確認できます。選択した埋め込みモデルと一致する正しい dimensions で Vectorize インデックスが作成されていることを確認してください。
RAG コンテキストを保存するための Cloudflare D1 の制限は何ですか? D1 はサーバーレス SQLite データベースです。強力な一貫性を提供し、構造化されたメタデータには優れていますが、従来のリレーショナルデータベースと比較して制限があります。非常に大規模で複雑な結合や、ペタバイト規模のデータに対する分析クエリ向けには設計されていません。RAG の場合、チャンクテキストとメタデータの保存は、その機能の範囲内です。非常に大規模なアプリケーションの場合、最大データベースサイズとクエリの複雑さを考慮する必要があります。非常に大きなテキストブロブの場合は、R2 に保存し、D1 には R2 キーのみを保存することを検討してください。
RAG システムが常に最新のデータを提供することをどのように保証できますか?
インジェストパイプラインが鍵です。ドキュメントを定期的に更新または再インジェストするための堅牢なプロセスを実装してください。リアルタイム更新の場合、ソースデータが変更されるたびに、Webhook またはメッセージキューを介してインジェスト Worker をトリガーすることができます。Vectorize は upsert 操作をサポートしており、ID で既存のベクトルを更新できます。D1 もメタデータに UPSERT または INSERT OR REPLACE をサポートしています。
Workers AI の外部でホストされているカスタム LLM を使用することは可能ですか?
はい。Gemini の例で示したように、Cloudflare Worker から外部 LLM API に fetch リクエストを行うことができます。これにより柔軟性が得られますが、外部ネットワークのレイテンシーと依存関係が発生します。最適なパフォーマンスとエッジの利点を得るには、利用可能でユースケースに適している場合は、Workers AI モデルを使用することが一般的に推奨されます。本番環境では、wrangler secret put を使用して API キーを安全に処理するようにしてください。
AI CLIログの整形、Cron式の作成、JWTの解析、chmod権限の計算をオフラインで実行。

CloudflareWorkers、KV、DurableObjectsで本番MCPサーバーを構築するための、本番環境レベルのアーキテクチャとコード例を含む包括的なガイドです。
続きを読む
ステートフルなAgentic RAGについて、グラフステートマシン、自己修正ループ、フォールバックルーティングを、本番環境レベルのアーキテクチャとコード例で網羅的に解説するガイドです。
続きを読む
本番RAGパイプライン向けにPinecone、Qdrant、Milvus、pgvectorのアーキテクチャを、HNSW vs IVFFlatインデックス、単段フィルタリング検索、p95レイテンシ、メモリフットプリントでベンチマークします。
続きを読む