cloudflare-vectorize

Cloudflare Vectorize

Cloudflare Workers を使用してセマンティック検索、RAG（検索拡張生成）、AI 活用アプリケーションを構築するための、世界中に分散されたベクトルデータベースである Cloudflare Vectorize の完全な実装ガイドです。

ステータス：本番環境で利用可能 ✅ 最終更新日：2025-10-21 依存関係：cloudflare-worker-base（Worker のセットアップ用）、cloudflare-workers-ai（埋め込み用） 最新バージョン：[email protected]、@cloudflare/[email protected] トークン削減率：約 65% 防止できるエラー数：8 開発時間の削減：約 3 時間

このスキルでできること

主な機能

• ✅ インデックス管理：ベクトルインデックスの作成、設定、管理
• ✅ ベクトル操作：ベクトルの挿入、アップサート、クエリ、削除、一覧表示
• ✅ メタデータフィルタリング：インデックスごとに 10 個のメタデータインデックスを使用した高度なフィルタリング
• ✅ セマンティック検索：コサイン、ユークリッド、内積の各メトリクスを使用して類似ベクトルを検索
• ✅ RAG パターン：検索拡張生成ワークフロー一式
• ✅ Workers AI との統合：@cf/baai/bge-base-en-v1.5 を使用したネイティブな埋め込み生成
• ✅ OpenAI との統合：text-embedding-3-small/large モデルをサポート
• ✅ ドキュメント処理：テキストのチャンク化と一括取り込みパイプライン

含まれるテンプレート

1. basic-search.ts - Workers AI を使用したシンプルなベクトル検索
2. rag-chat.ts - コンテキスト取得機能を備えた RAG チャットボット一式
3. document-ingestion.ts - ドキュメントのチャンク化と埋め込みパイプライン
4. metadata-filtering.ts - 高度なフィルタリングパターン

---

⚠️ Vectorize V2 の破壊的変更（2024 年 9 月）

重要：Vectorize V2 は、重大な破壊的変更とともに 2024 年 9 月に一般提供（GA）となりました。

V2 での変更点

パフォーマンスの改善：

• インデックス容量：インデックスあたり 200,000 → 500 万ベクトル
• クエリレイテンシ：中央値 549ms → 31ms（18 倍高速）
• TopK の上限：クエリあたり 20 → 100 件の結果
• スケール上限：アカウントあたり 100 → 50,000 インデックス
• ネームスペースの上限：インデックスあたり 100 → 50,000 ネームスペース

API の破壊的変更：

1. 非同期ミューテーション - すべてのミューテーションが非同期になりました：

   // V2: Returns mutationId
   const result = await env.VECTORIZE_INDEX.insert(vectors);
   console.log(result.mutationId); // "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   
   // Vector inserts/deletes may take a few seconds to be reflected
   

2. returnMetadata パラメーター - Boolean から文字列の列挙型に変更：

   // ❌ V1 (deprecated)
   { returnMetadata: true }
   
   // ✅ V2 (required)
   { returnMetadata: 'all' | 'indexed' | 'none' }
   

3. 挿入前にメタデータインデックスの作成が必須：

   • V2 では、ベクトルを挿入する前にメタデータインデックスを作成する必要があります
   • メタデータインデックスの作成前に追加されたベクトルはインデックス化されません
   • メタデータインデックスの作成後にベクトルを再度アップサートする必要があります

V1 の非推奨化スケジュール：

• 2024 年 12 月：V1 インデックスを新規作成できなくなります
• 既存の V1 インデックス：引き続き動作します（ほかの操作には影響しません）
• 移行：V1 の操作には wrangler vectorize --deprecated-v1 フラグを使用してください

必要な Wrangler バージョン：

• 最小バージョン：V2 コマンドには [email protected] が必要です
• 推奨バージョン：[email protected] 以降（最新）

ミューテーションのステータスを確認する

// Get index info to check last mutation processed
const info = await env.VECTORIZE_INDEX.describe();
console.log(info.mutationId); // Last mutation ID
console.log(info.processedUpToMutation); // Last processed timestamp

---

重要なセットアップルール

⚠️ ベクトルを挿入する前に必ず行うこと

# 1. Create the index with FIXED dimensions and metric
npx wrangler vectorize create my-index \
  --dimensions=768 \
  --metric=cosine

# 2. Create metadata indexes IMMEDIATELY (before inserting vectors!)
npx wrangler vectorize create-metadata-index my-index \
  --property-name=category \
  --type=string

npx wrangler vectorize create-metadata-index my-index \
  --property-name=timestamp \
  --type=number

理由：ベクトルを挿入する前に、メタデータインデックスが存在している必要があります。メタデータインデックスの作成前に追加されたベクトルは、そのプロパティでフィルタリングできません。

インデックスの設定（後から変更できません）

# Dimensions MUST match your embedding model output:
# - Workers AI @cf/baai/bge-base-en-v1.5: 768 dimensions
# - OpenAI text-embedding-3-small: 1536 dimensions
# - OpenAI text-embedding-3-large: 3072 dimensions

# Metrics determine similarity calculation:
# - cosine: Best for normalized embeddings (most common)
# - euclidean: Absolute distance between vectors
# - dot-product: For non-normalized vectors

Wrangler の設定

wrangler.jsonc：

{
  "name": "my-vectorize-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-21",
  "vectorize": [
    {
      "binding": "VECTORIZE_INDEX",
      "index_name": "my-index"
    }
  ],
  "ai": {
    "binding": "AI"
  }
}

TypeScript の型

export interface Env {
  VECTORIZE_INDEX: VectorizeIndex;
  AI: Ai;
}

interface VectorizeVector {
  id: string;
  values: number[] | Float32Array | Float64Array;
  namespace?: string;
  metadata?: Record<string, string | number | boolean | string[]>;
}

interface VectorizeMatches {
  matches: Array<{
    id: string;
    score: number;
    values?: number[];
    metadata?: Record<string, any>;
    namespace?: string;
  }>;
  count: number;
}

メタデータフィルターの演算子（V2）

Vectorize V2 は、範囲クエリを使用した高度なメタデータフィルタリングをサポートしています。

// Equality (implicit $eq)
{ category: "docs" }

// Not equals
{ status: { $ne: "archived" } }

// In/Not in arrays
{ category: { $in: ["docs", "tutorials"] } }
{ category: { $nin: ["deprecated", "draft"] } }

// Range queries (numbers) - NEW in V2
{ timestamp: { $gte: 1704067200, $lt: 1735689600 } }

// Range queries (strings) - prefix searching
{ url: { $gte: "/docs/workers", $lt: "/docs/workersz" } }

// Nested metadata with dot notation
{ "author.id": "user123" }

// Multiple conditions (implicit AND)
{ category: "docs", language: "en", "metadata.published": true }

メタデータのベストプラクティス

1. カーディナリティに関する考慮事項

カーディナリティが低い場合（$eq フィルターに適しています）：

// Few unique values - efficient filtering
metadata: {
  category: "docs",        // ~10 categories
  language: "en",          // ~5 languages
  published: true          // 2 values (boolean)
}

カーディナリティが高い場合（範囲クエリでは避けてください）：

// Many unique values - avoid large range scans
metadata: {
  user_id: "uuid-v4...",         // Millions of unique values
  timestamp_ms: 1704067200123    // Use seconds instead
}

2. メタデータの上限

• メタデータインデックスの最大数：Vectorize インデックスあたり 10 個
• メタデータの最大サイズ：ベクトルあたり 10 KiB
• 文字列インデックス：先頭 64 バイト（UTF-8）
• 数値インデックス：Float64 精度
• フィルターの最大サイズ：2048 バイト（コンパクトな JSON）

3. キーの制約

// ❌ INVALID metadata keys
metadata: {
  "": "value",              // Empty key
  "user.name": "John",      // Contains dot (reserved for nesting)
  "$admin": true,           // Starts with $
  "key\"with\"quotes": 1    // Contains quotes
}

// ✅ VALID metadata keys
metadata: {
  "user_name": "John",
  "isAdmin": true,
  "nested": { "allowed": true }  // Access as "nested.allowed" in filters
}

よくあるエラーと解決方法

エラー 1：ベクトルの挿入後にメタデータインデックスを作成した

Problem: Filtering doesn't work on existing vectors
Solution: Delete and re-insert vectors OR create metadata indexes BEFORE inserting

エラー 2：次元数が一致しない

Problem: "Vector dimensions do not match index configuration"
Solution: Ensure embedding model output matches index dimensions:
  - Workers AI bge-base: 768
  - OpenAI small: 1536
  - OpenAI large: 3072

エラー 3：無効なメタデータキー

Problem: "Invalid metadata key"
Solution: Keys cannot:
  - Be empty
  - Contain . (dot)
  - Contain " (quote)
  - Start with $ (dollar sign)

エラー 4：フィルターが大きすぎる

Problem: "Filter exceeds 2048 bytes"
Solution: Simplify filter or split into multiple queries

エラー 5：カーディナリティの高い範囲クエリ

Problem: Slow queries or reduced accuracy
Solution: Use lower cardinality fields for range queries, or use seconds instead of milliseconds for timestamps

エラー 6：Insert と Upsert の混同

Problem: Updates not reflecting in index
Solution: Use upsert() to overwrite existing vectors, not insert()

エラー 7：バインディングの不足

Problem: "VECTORIZE_INDEX is not defined"
Solution: Add [[vectorize]] binding to wrangler.jsonc

エラー 8：名前空間とメタデータの混同

Problem: Unclear when to use namespace vs metadata filtering
Solution:
  - Namespace: Partition key, applied BEFORE metadata filters
  - Metadata: Flexible key-value filtering within namespace

エラー 9：V2 の非同期ミューテーションのタイミング（V2 の新機能）

Problem: Inserted vectors not immediately queryable
Solution: V2 mutations are asynchronous - vectors may take a few seconds to be reflected
  - Use mutationId to track mutation status
  - Check env.VECTORIZE_INDEX.describe() for processedUpToMutation timestamp

エラー 10：V1 の returnMetadata ブール値（V2 で破壊的変更）

Problem: "returnMetadata must be 'all', 'indexed', or 'none'"
Solution: V2 changed returnMetadata from boolean to string enum:
  - ❌ V1: { returnMetadata: true }
  - ✅ V2: { returnMetadata: 'all' }

---

V2 への移行チェックリスト

V1 から V2 に移行する場合：

1. ✅ wrangler を 3.71.0 以降に更新します（npm install -g wrangler@latest）
2. ✅ 新しい V2 インデックスを作成します（V1 から V2 へのアップグレードはできません）
3. ✅ ベクトルを挿入する前に、メタデータインデックスを作成します
4. ✅ returnMetadata のブール値を文字列の列挙値（'all'、'indexed'、'none'）に更新します
5. ✅ 非同期ミューテーションに対応します（レスポンスに mutationId が含まれることを想定します）
6. ✅ V2 の上限値でテストします（topK は最大 100、インデックスあたり最大 500 万ベクトル）
7. ✅ 非同期動作に合わせてエラー処理を更新します

V1 の非推奨化：

• 2024 年 12 月以降：新しい V1 インデックスは作成できません
• 既存の V1 インデックス：引き続き動作します
• V1 の操作には wrangler vectorize --deprecated-v1 を使用します

---

公式ドキュメント

• Vectorize V2 ドキュメント：https://developers.cloudflare.com/vectorize/
• V2 の変更履歴：https://developers.cloudflare.com/vectorize/platform/changelog/
• V1 から V2 への移行：https://developers.cloudflare.com/vectorize/reference/transition-vectorize-legacy/
• メタデータのフィルタリング：https://developers.cloudflare.com/vectorize/reference/metadata-filtering/
• Workers AI モデル：https://developers.cloudflare.com/workers-ai/models/

---

ステータス：本番環境で利用可能 ✅（Vectorize V2 GA — 2024 年 9 月） 最終更新日：2025-11-22 トークン削減率：約 70% 防止したエラー：10 件（V2 の破壊的変更を含む）