cloudflare-vectorize

Cloudflare Vectorize

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

ステータス：本番環境対応 ✅ 最終更新日：2025-11-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 - 高度なフィルタリングの例

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

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

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

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

bunx 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;
}

よく使う操作

クイックリファレンス

操作	メソッド	要点
挿入	insert([...])	ID が存在する場合は最初の値を保持
アップサート	upsert([...])	ID が存在する場合は上書き（更新時に使用）
クエリ	query(vector, { topK, filter })	類似ベクトルを返す
削除	deleteByIds([...])	ID の配列を指定して削除
取得	getByIds([...])	指定したベクトルを取得

フィルター演算子

演算子	例	説明
$eq	{ category: "docs" }	等しい（暗黙的）
$ne	{ status: { $ne: "archived" } }	等しくない
$in	{ category: { $in: ["a", "b"] } }	配列に含まれる
$nin	{ category: { $nin: ["x"] } }	配列に含まれない
$gte/$lt	{ timestamp: { $gte: 123 } }	範囲クエリ

📄 操作ガイド全文：references/vector-operations.md を読み込むと、挿入／アップサート／クエリ／削除のコード例を含む完全なガイドを確認できます。

埋め込みの生成

モデル	プロバイダー	次元数	最適な用途
@cf/baai/bge-base-en-v1.5	Workers AI	768	無料、汎用
text-embedding-3-small	OpenAI	1536	品質とコストのバランス
text-embedding-3-large	OpenAI	3072	最高品質

📄 統合ガイド：

• Workers AI のセットアップについては、references/integration-workers-ai-bge-base.md を読み込みます
• OpenAI との統合については、references/integration-openai-embeddings.md を読み込みます

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

主な制限

制限	値
メタデータインデックスの最大数	インデックスあたり10
メタデータの最大サイズ	ベクトルあたり10 KiB
文字列インデックス	先頭64バイト（UTF-8）
フィルターサイズ	最大2048バイト

使用できないキー文字

キーは空にできません。また、.（ネスト用に予約）、" を含めること、$ で始めることはできません。

📄 メタデータガイド全文：references/metadata-guide.md を読み込むと、カーディナリティのベストプラクティス、ネストされたメタデータ、高度なフィルタリングパターンを確認できます。

RAG パターン（完全な例）

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { question } = await request.json();

    // 1. Generate embedding for user question
    const questionEmbedding = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
      text: question
    });

    // 2. Search vector database for similar content
    const results = await env.VECTORIZE_INDEX.query(
      questionEmbedding.data[0],
      {
        topK: 3,
        returnMetadata: 'all',
        filter: { type: "documentation" }
      }
    );

    // 3. Build context from retrieved documents
    const context = results.matches
      .map(m => m.metadata.content)
      .join('\n\n---\n\n');

    // 4. Generate answer with LLM using context
    const answer = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
      messages: [
        {
          role: "system",
          content: `Answer based on this context:\n\n${context}`
        },
        {
          role: "user",
          content: question
        }
      ]
    });

    return Response.json({
      answer: answer.response,
      sources: results.matches.map(m => m.metadata.title)
    });
  }
};

ドキュメントのチャンク分割戦略

推奨チャンクサイズ：意味の一貫性を保つため、300～500 文字です。

チャンクの主なメタデータ：

• doc_id：親ドキュメントの ID
• chunk_index：ドキュメント内の位置
• content：検索結果表示用のテキスト

📄 チャンク分割の実装全体：チャンク分割パイプラインの全体については、templates/document-ingestion.ts を参照してください。

よくあるエラーと解決策

エラー 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

Wrangler CLI リファレンス

必須コマンド：

# Create index (dimensions/metric are PERMANENT)
bunx wrangler vectorize create <name> --dimensions=768 --metric=cosine

# Create metadata index (MUST be before inserting vectors!)
bunx wrangler vectorize create-metadata-index <name> --property-name=category --type=string

# Get index info
bunx wrangler vectorize info <name>

📄 CLI リファレンス全体：Vectorize の全コマンドについては、references/wrangler-commands.md を読み込んでください。

パフォーマンスのヒント

1. バッチ操作：100～1000 個のベクトルをまとめて Insert/Upsert します
2. 選択的な返却：必要な場合にのみ returnValues: true を使用します（帯域幅を節約できます）
3. メタデータのカーディナリティ：範囲クエリで使うインデックス付きメタデータフィールドのカーディナリティは低く保ちます
4. 名前空間のフィルタリング：メタデータフィルターより先に名前空間フィルターを適用します（最初に処理されます）
5. クエリの最適化：レイテンシーを最小限に抑えるには、topK=3～10 を使用します（値を大きくすると検索時間が長くなります）

このスキルを使用する場面

✅ 次の場合は Vectorize を使用します：

• ドキュメント、製品、コンテンツを対象にセマンティック検索を構築する
• コンテキスト検索機能を備えた RAG チャットボットを実装する
• 類似性に基づくレコメンデーションエンジンを作成する
• マルチテナントアプリケーションを構築する（名前空間を使用します）
• グローバルな分散と低レイテンシーが必要である

❌ 次の場合は Vectorize を使用しないでください：

• 従来型のリレーショナルデータ（D1 を使用します）
• キーと値の検索（KV を使用します）
• 大容量ファイルのストレージ（R2 を使用します）
• リアルタイムの共同作業状態（Durable Objects を使用します）

リファレンスを読み込む場面

リファレンスファイル	読み込む場面
references/vector-operations.md	Insert/Upsert/Query/Delete のコード例全体が必要な場合
references/metadata-guide.md	メタデータインデックスの設定やフィルタリングのベストプラクティスが必要な場合
references/wrangler-commands.md	Vectorize CLI コマンドを使用する場合
references/integration-workers-ai-bge-base.md	Workers AI の埋め込みを統合する場合
references/integration-openai-embeddings.md	OpenAI の埋め込みを統合する場合
references/embedding-models.md	埋め込みモデルの選択肢を比較する場合
references/index-operations.md	インデックスのライフサイクルを管理する場合

テンプレート

テンプレート	用途
templates/basic-search.ts	シンプルなベクトル検索
templates/rag-chat.ts	完全な RAG チャットボット
templates/document-ingestion.ts	ドキュメントのチャンク分割パイプライン
templates/metadata-filtering.ts	高度なフィルタリング

安全なインストール

ベクトルデータベースのパッケージをインストールする際は、サプライチェーンセキュリティのベストプラクティスに従ってください。

• インストール後のスクリプトをブロックする — npm config set ignore-scripts true（または Bun：デフォルトで無効）
• クールダウン期間 — 新しいパッケージバージョンがコミュニティによって審査されるまで、7 日間待ちます
• インストール前に監査する — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使用してパッケージを確認します

Socket CLI の統合、クールダウンの設定、ロックファイルの検証、CI による適用を含むセキュリティ設定全体については、dependency-upgrade スキルを読み込んでください。

公式ドキュメント

• Vectorize のドキュメント
• Workers AI モデル
• RAG チュートリアル

---

バージョン：1.0.0 ステータス：本番環境で利用可能 ✅ トークン削減率：約 65% 防止できるエラー：主な 8 カテゴリー 開発時間の節約：実装あたり約 2.5 時間