Vectorize

解決する課題

• テキストや画像を埋め込みベクトルに変換した後、意味的に近いものを高速に検索したいが、総当たりの比較では件数が増えると遅くなる
• 生成AIに自社の文書やナレッジを根拠として参照させたい（検索拡張生成、RAG）。質問に関連する文書の断片を瞬時に取り出す仕組みが要る
• 推薦・類似画像検索・重複検出・異常検知などで、大量のベクトルに対して低レイテンシで近傍を返したい
• ベクトル検索基盤を自前で構築・運用すると、インデックスの管理やスケーリングの作り込みが重く、マネージドに任せたい
• Cloudflare Workers上で完結するアプリケーションに、外部のベクトルデータベースを別途契約せず組み込みたい

主要概念と用語

• インデックス: 検索対象のベクトル群を格納する単位。次元数と距離指標を作成時に指定し、以後は変更できない
• 埋め込みベクトル: テキストや画像などを意味を保ったまま数値の配列に変換したもの。意味が近い内容ほどベクトル空間上でも近い位置に置かれる
• 次元数: 埋め込みベクトルの要素数。使用する埋め込みモデルの出力次元に合わせてインデックスを作成する
• 距離指標: ベクトル間の近さの測り方。コサイン類似度・ユークリッド距離・内積のいずれかを選ぶ
• 近似最近傍探索: 全件を厳密に比較せず、十分な精度を保ちながら近い候補を高速に返す検索手法
• メタデータ: 各ベクトルに付随させる属性情報（カテゴリ、タイムスタンプなど）。フィルタリングの条件として使う
• メタデータインデックス: メタデータの特定プロパティに対して絞り込み検索を可能にするための索引。ベクトル投入前に作成しておく必要がある
• 名前空間: インデックス内でベクトルを論理的に分割する仕組み。マルチテナントでテナントごとに検索範囲を分離する用途に使う
• topK: クエリに対して返す近傍ベクトルの件数
• バインディング: Cloudflare Workersのコードからインデックスへ直接アクセスするための接続設定

仕様・制限・クォータ

• インデックスは次元数と距離指標を作成時に固定する。埋め込みモデルを変更して出力次元が変わる場合は、原則としてインデックスを作り直す
• 1インデックスに格納できるベクトル数には上限があり、大規模なコレクションを扱う場合は分割や運用計画が必要になる
• 1回の書き込み（挿入・更新）で送れるベクトル件数にはバッチ上限があり、上限を超える場合は複数回に分けて呼び出す
• 挿入・更新・削除は非同期に反映されるため、書き込み直後は検索結果に即座には現れないことがある
• メタデータ文字列は索引化される長さに上限があり、長い文字列は先頭部分のみが索引の対象になる
• メタデータインデックスは1インデックスあたり作成できる数に上限があり、既存のベクトルに対して後から遡って索引化はされないため、投入前に作成しておく必要がある
• 名前空間の数にも上限があり、アカウントのプランによって扱える上限が異なる
• 具体的な数値やレスポンス件数の上限は変更されうるため、実装前に公式ドキュメントで最新値を確認する

内部の仕組み

Vectorizeは、挿入されたベクトル群から検索用のインデックス構造を構築し、クエリベクトルに対して全件を線形に比較せず近い候補だけを効率的に辿れるようにします。これにより、件数が多くても低レイテンシで近傍を返せます。

クエリを投げると、指定した距離指標（コサイン類似度・ユークリッド距離・内積のいずれか）に基づいて近い順にベクトルのIDと類似度スコアが返ります。ベクトル本体の元データ（原文や画像そのもの）は返らないのが基本で、返ってきたIDやメタデータを手がかりに、別のデータストア（Workers KV、D1、R2など）から実体を取得する構成が一般的です。

書き込み（挿入・更新・削除）は受け付けた時点ではすぐに完了扱いになりますが、検索インデックスへの反映には多少の時間差があります。速い一貫性が必須な用途では、この非同期性を踏まえた設計が必要です。

設計パターン / ベストプラクティス

• RAGのリトリーバル層として使う: 文書をチャンクに分割して埋め込み、クエリの埋め込みとの近傍検索で関連チャンクを取得し、その内容を大規模言語モデルへ渡して回答を生成させる
• Workers AIと組み合わせる: 埋め込みの生成にWorkers AIのテキスト埋め込みモデルを使うと、埋め込み生成から検索までを同じCloudflareの基盤内で完結できる
• IDでデータを引く構成にする: Vectorizeには近傍探索に必要な最小限のメタデータのみを持たせ、本文やファイルは別のストレージに置いて連携する
• 名前空間でテナントを分離する: マルチテナントのSaaSなどでは、テナントごとに名前空間を分けることで検索範囲を確実に分離できる。テナント数が非常に多い場合はメタデータフィルタとの使い分けを検討する
• メタデータインデックスは投入前に作る: 絞り込み検索をしたいプロパティは、ベクトルを投入する前にメタデータインデックスとして定義しておく
• バッチで書き込む: 挿入・更新は1件ずつ呼ぶよりまとめて送るほうがスループットが大きく上がるため、上限件数を踏まえてバッチ化する
• 高カーディナリティな値はバケット化する: ミリ秒単位のタイムスタンプなどをそのままメタデータにすると検索性能が落ちやすいため、一定の粒度に丸めてから格納する

運用・監視

• ダッシュボードや監視の仕組みから、クエリ数・レイテンシ・エラー率などの利用状況を確認する
• 書き込み直後は検索結果に反映されるまで時間差があることを踏まえ、反映待ちを前提としたテスト・監視を行う
• 検索結果が想定と異なる場合は、次元数の不一致、名前空間の指定ミス、メタデータインデックス未作成、書き込み直後の反映待ちなどを順に切り分ける
• 埋め込みモデルを変更した場合は、インデックスの再作成とデータの再投入をセットで計画し、切り替え中の挙動（旧インデックスの並行稼働など）を検討する
• 大規模な入れ替えを行う際は、新旧インデックスを一定期間並行運用してから切り替えると安全性が高い

コスト

課金は主に、保存しているベクトルの件数（次元数を含む）と、クエリ・書き込みの操作数に応じて発生します。ベクトルの次元数が大きいほど1件あたりの保存コストは増えるため、埋め込みモデルの次元数選定はコストにも影響します。具体的な単価や無料枠は変動するため、最新の料金ページで確認してください。

セキュリティ

• インデックスへのアクセスは、Cloudflare WorkersからのバインディングやAPIトークンを通じて行い、認証情報をコードに直書きしない
• APIトークンには必要な操作範囲だけを持たせ、最小権限の原則に従ってスコープを絞る
• マルチテナント構成では、名前空間やメタデータフィルタを使ってテナント間の検索結果が混在しないように設計する
• 機微なデータを埋め込みやメタデータに含める場合は、アクセス制御の設計（誰がどの名前空間・フィルタ条件で検索できるか）を検索層にも組み込む
• 通信はTLSで保護され、Cloudflareの基盤内で完結する構成を取りやすい

関連サービス・比較

Cloudflareでベクトル検索を行う場合、埋め込みの生成にはWorkers AIのテキスト埋め込みモデルを組み合わせるのが一般的です。Vectorizeは検索専用のマネージドサービスとして、Workers・Workers AIと密に連携する点が特徴です。他クラウドで近い位置づけにあるのが、Vertex AI Vector SearchやAmazon OpenSearchのベクトル検索機能です。

ハンズオン / CLI例

# 1) インデックスを作成（次元数と距離指標を指定）
npx wrangler vectorize create my-index --dimensions=768 --metric=cosine

# 2) 絞り込み検索に使うメタデータインデックスを事前に作成
npx wrangler vectorize create-metadata-index my-index \
  --property-name=category --type=string

# 3) ベクトルをNDJSONファイルからまとめて挿入
#    例: {"id": "1", "values": [0.1, 0.2, ...], "metadata": {"category": "docs"}}
npx wrangler vectorize insert my-index --file=embeddings.ndjson

# 4) インデックスの情報を確認
npx wrangler vectorize info my-index

# 5) IDを指定してベクトルを取得
npx wrangler vectorize get my-index --ids=1,2

# 6) 不要になったベクトルを削除
npx wrangler vectorize delete-by-ids my-index --ids=1