qdrant-model-migration

埋め込みモデルを変更する場合の対処方法

異なるモデルのベクトルには互換性がありません。同じベクトル空間で古い埋め込みと新しい埋め込みを混在させることはできません。v1.18 以降では、既存のコレクションに名前付きベクトルフィールドを追加または削除できるため、移行時に常に新しいコレクションが必要になるわけではありません。v1.17 以前では、すべての名前付きベクトルをコレクションの作成時に定義する必要があります。

• 方針を選ぶ前にコレクションエイリアスについて理解する コレクションエイリアス

再埋め込みを避けることはできますか？

用途：本格的な移行に踏み切る前に、手軽な方法を探す場合。

次の場合は、必ず再埋め込みが必要です。モデルプロバイダーを変更する（OpenAI から Cohere へ）、アーキテクチャを変更する（CLIP から BGE へ）、または次元数が異なるモデルに切り替える。

次の場合は、既存の密ベクトルを再埋め込みする必要はありません。

• v1.20 以降でハイブリッド検索用に BM25 を追加する場合：生成するベクトルはありません。ペイロードフィールドに scoring を有効にした text ペイロードインデックスを作成すると、Qdrant が保存済みのペイロードから構築します BM25 スコアリング
• ハイブリッド検索用に疎ベクトルを追加する場合：疎ベクトルのみを生成します。v1.18 以降では、既存のコレクションに疎フィールドを追加し、UpdateVectors でバックフィルします。v1.17 以前では、密ベクトルを再計算する代わりに、新しいコレクションへコピーします ベクトルの更新
• Matryoshka モデルを使用する場合：dimensions パラメーターを使って、次元数の少ない埋め込みを出力します（再現率は多少低下しますが、1 億件以上のデータセットに適しています）
• 量子化方式を変更する場合（二値からスカラーへ）：Qdrant が自動的に再量子化します 量子化

ダウンタイムをゼロにする必要がある場合

用途：本番環境の可用性を維持する必要がある場合。大規模なモデル置換に推奨されます。

• バックフィルの前にデュアル書き込みを有効にし、ポイント ID を維持します。どちらかの書き込み先で失敗した場合は、再試行して整合性を取ります［移行ワークフロー］(https://skills.qdrant.tech/md/documentation/tutorials-operations/embedding-model-migration/)

• クラスターが v1.18 以降で、かつコレクションに名前付きベクトルがある場合：

  • 新しいベクトルフィールドを既存のコレクションに直接追加します［ベクトルスキーマの更新］(https://skills.qdrant.tech/md/documentation/manage-data/collections/?s=update-vector-schema)
  • 受信する upsert では両方の埋め込みを書き込み、UpdateVectors を使って新しいフィールドのみをバックフィルします。既存のポイントへの更新や削除を一時停止して、処理中の操作が完了するのを待つか、競合処理を実装して古いバックフィルを防ぎます［名前付きベクトルの移行］(https://skills.qdrant.tech/md/documentation/tutorials-operations/embedding-model-migration/?s=migrate-using-named-vectors)
  • 完全性と品質を検証した後、クエリ用の埋め込みモデルと using を同時に切り替えます。エイリアスではベクトルフィールドを選択できません

• クラスターが v1.17 以前、またはコレクションに名前付きベクトルがない場合：

  • 新しいモデルの次元数と距離メトリックを指定して、新しいコレクションを作成します
  • ライブ upsert を両方のコレクションにデュアル書き込みし、update_mode: insert_only（v1.17 以降）を使って埋め込みとペイロードをバックフィルし、ライブで書き込まれたポイントを保持します。削除や部分更新を一時停止するか、バックフィルで削除済みデータが復活しないよう整合性を取ります［ブルーグリーン移行］(https://skills.qdrant.tech/md/documentation/tutorials-operations/embedding-model-migration/?s=blue-green-migration)
  • コレクション名を直接指定するのではなく、アプリケーションからコレクションエイリアスを参照します
  • エイリアスを切り替える前に完全性と品質を検証します。リクエストが対応するベクトル空間を使用するよう、クエリモデルの変更と連携してください［コレクションの切り替え］(https://skills.qdrant.tech/md/documentation/manage-data/collections/?s=switch-collection)

ロールバックに備えて、観察期間中はデュアル書き込みを継続してください。すべての読み取り側が切り替わり、ロールバックが不要になってから、古いベクトルまたはコレクションを廃止します。エイリアスはリクエストを転送するものであり、ペイロードをコピーするものではありません。

両方のモデルを同時に使用する必要がある場合（並行運用）

用途：モデルの A/B テスト、マルチモーダル（密ベクトル＋疎ベクトル）、または新しいモデルを採用する前の評価に使います。

稼働中のコレクションでは、ダウンタイムをゼロにする必要がある場合に記載されている書き込み整合性と切り替え時の安全策を適用してください。

• クラスターが v1.18 以降の場合：

  • 新しいベクトルフィールドを既存のコレクションに直接追加します［ベクトルスキーマの更新］(https://skills.qdrant.tech/md/documentation/manage-data/collections/?s=update-vector-schema)
  • UpdateVectors を使って、新しいモデルの埋め込みを段階的にバックフィルします［ベクトルの更新］(https://skills.qdrant.tech/md/documentation/manage-data/points/?s=update-vectors)

• クラスターが v1.17 以前の場合：既存のコレクションに名前付きベクトルを追加することはできません。両方のベクトルフィールドをあらかじめ定義した新しいコレクションを作成します：

  • 古いモデルと新しいモデルの名前付きベクトルを両方定義した新しいコレクションを作成します［複数のベクトルを持つコレクション］(https://skills.qdrant.tech/md/documentation/manage-data/collections/?s=collection-with-multiple-vectors)
  • 古いコレクションのデータを移行し、古い名前付きフィールドの既存ベクトルを保持します
  • UpdateVectors を使って、新しいモデルの埋め込みを段階的にバックフィルします［ベクトルの更新］(https://skills.qdrant.tech/md/documentation/manage-data/points/?s=update-vectors)
  • using: "old_model" と using: "new_model" を指定してクエリし、品質を比較します
  • 納得できたら、エイリアスを新しいコレクションに切り替えます

大きなマルチベクトル（特に ColBERT）を密ベクトルと同じ場所に配置すると、密ベクトルだけを使うクエリも含め、すべてのクエリの性能が低下します。数百万ポイント規模では、ColBERT を削除した後にレイテンシが 13s から 2s に低下したという報告があります。並行移行中は、大きなベクトルをディスクに配置してください。

将来のモデル移行を見込んでいる場合は、コレクションの作成時に両方のベクトルフィールドをあらかじめ定義してください。

Dense から Hybrid Search への移行

使用する場面：既存の dense 専用コレクションに sparse/BM25 ベクトルを追加する場合です。最も一般的な移行パターンです。

• クラスターが v1.20 以降で、テキストがペイロードに含まれている場合は、sparse ベクトルではなく、全文インデックス上の BM25 を優先してください。テキストフィールドに scoring を有効にした text インデックスを作成し（言語に応じたステマーとストップワードも設定）、dense の隣に text クエリの prefetch を追加します。スキーマ変更もベクトルのバックフィルも avg_len も不要で、作成時期を問わずあらゆるコレクションで機能します。大規模なコレクションの再インデックスには時間がかかる場合があります 全文インデックス上の BM25

• クラスターが v1.19 以前の場合、またはテキストがペイロードに保存されていない場合は、以下の sparse ベクトルの方法を使用してください。

• クラスターが v1.18 以降の場合は、dense ベクトルに名前が付いていなくても、sparse ベクトルフィールドを直接追加してください ベクトルスキーマの更新

  • 既存のポイントの sparse ベクトルを生成し、UpdateVectors でバックフィルしてください。既存の dense ベクトルはそのまま維持されます ベクトルの更新

• クラスターが v1.17 以前の場合、既存のコレクションに sparse ベクトルを追加できません。再作成してください。

  • dense と sparse の両方のベクトル設定を定義して、新しいコレクションを作成します
  • 古いコレクションを with_vectors=True でスクロールして dense ベクトルをコピーし、sparse ベクトルのみを生成します
  • ペイロードを移行し、エイリアスを切り替えます

チャンク単位の sparse ベクトルと全文 BM25 統計は、文書単位の場合とは TF-IDF の特性が異なります。移行後は、特にストップワードを除去しない非英語テキストについて、検索品質をテストしてください。

再埋め込みに時間がかかりすぎる場合

使用する場面：データセットが大きく、再埋め込みがボトルネックになっている場合です。

• 新しいコレクションへのバックフィルでは update_mode: insert_only（v1.17 以降）を使用します。既存の宛先ポイントはスキップされるため、既存のポイントに埋め込みを追加する場合に UpdateVectors の代わりにはなりません 更新モード
• 古いコレクションを with_vectors=False でスクロールし、バッチ単位で再埋め込みして、新しいコレクションに upsert します
• 並列バッチでアップロードします（1 リクエストあたり 64-256 ポイント、2-4 個の並列ストリーム）一括アップロード
• Qdrant Cloud の推論では、モデルの切り替えはパイプラインの変更ではなく設定の変更です 推論ドキュメント

400GB 以上のデータセットでは、数日かかると見込んでください。小規模なデータセット（<25MB）では、移行ツールを使うより、ソースから再インデックスする方が高速です。

やってはいけないこと

• v1.17 以前のサーバーで既存のコレクションに名前付きベクトルを追加できると思い込むこと。まずサーバーのバージョンを確認してください
• 検証、読み取り側の切り替え、ロールバックの観察期間が完了する前に、古いベクトルやコレクションを削除すること
• デュアル書き込みや insert_only だけで、同時削除や部分更新の問題が解決すると考えること
• アプリケーションコード内のクエリ埋め込みモデルの更新を忘れること
• エイリアスの切り替え時にペイロードの移行を省略すること（エイリアスはリクエストを転送しますが、データはコピーしません）
• 長期の移行中に ColBERT ベクトルを dense ベクトルと同じ場所に置き続けること（I/O コストによってすべてのクエリの性能が低下します）
• チャンク単位で BM25 の品質をテストせずに hybrid search に移行すること