qdrant-model-migration

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

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

• 方法を選ぶ前に、コレクションエイリアスについて理解してください［コレクションエイリアス］(https://search.qdrant.tech/md/documentation/manage-data/collections/?s=collection-aliases)

再埋め込みを避けられますか？

使用する場面：全面的な移行を決める前に、手軽な方法を探している場合。

次の場合は、必ず再埋め込みが必要です：モデルプロバイダーの変更（OpenAI から Cohere への変更）、アーキテクチャの変更（CLIP から BGE への変更）、異なるモデル間での次元数の互換性がない場合、または密ベクトルのみのコレクションに疎ベクトルを追加する場合。

次の場合は、再埋め込みを避けられます：Matryoshka モデルを使用する場合（dimensions パラメーターで低次元の埋め込みを出力する方法、サンプルデータから線形変換を学習する方法があります。再現率は多少低下しますが、1 億件以上のデータセットに適しています）。または、量子化を変更する場合（二値からスカラーへ）：Qdrant が自動的に再量子化します。［量子化］(https://search.qdrant.tech/md/documentation/manage-data/quantization/)

ダウンタイムをゼロにする必要がありますか（エイリアスの切り替え）

使用する場面：本番環境を利用可能な状態に保つ必要がある場合。大規模なモデル置き換えに推奨されます。

• 新しいモデルの次元数と距離メトリックを使用して、新しいコレクションを作成します
• バックグラウンドで、すべてのデータを新しいコレクションに再埋め込みします
• コレクション名を直接指定する代わりに、コレクションエイリアスを参照するようアプリケーションを設定します
• エイリアスを新しいコレクションにアトミックに切り替えます［コレクションの切り替え］(https://search.qdrant.tech/md/documentation/manage-data/collections/?s=switch-collection)
• 検索品質を確認してから、古いコレクションを削除します

注意してください。エイリアスの切り替えでリダイレクトされるのはクエリのみです。ペイロードは別途再アップロードする必要があります。

両方のモデルを同時に稼働させる必要がありますか（並行運用）

使用する場面：モデルの A/B テスト、マルチモーダル（密ベクトルと疎ベクトル）、または新しいモデルの採用を決める前の評価を行う場合。

既存のコレクションに名前付きベクトルを追加することはできません。両方のベクトルフィールドをあらかじめ定義した新しいコレクションを作成してください。

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

大きなマルチベクトル（特に ColBERT）を密ベクトルと同じ場所に配置すると、密ベクトルのみを使うクエリも含め、すべてのクエリのパフォーマンスが低下します。数百万件のポイントを扱う環境では、ColBERT を削除したことでレイテンシが 13 秒から 2 秒に短縮されたという報告があります。並行移行中は、大きなベクトルをディスクに保存してください。

今後モデルを移行する可能性がある場合は、コレクションの作成時に両方のベクトルフィールドをあらかじめ定義してください。

密検索からハイブリッド検索への移行

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

既存の密ベクトルのみのコレクションに疎ベクトルを追加することはできません。コレクションを作り直す必要があります。

• 密ベクトルと疎ベクトルの両方の設定を定義した新しいコレクションを作成します
• すべてのデータを、密ベクトルモデルと疎ベクトルモデルの両方を使って再埋め込みします
• ペイロードを移行し、エイリアスを切り替えます

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

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

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

• 安全で冪等な移行には、update_mode: insert（v1.17 以降）を使用します［更新モード］(https://search.qdrant.tech/md/documentation/manage-data/points/?s=update-mode)
• 古いコレクションを with_vectors=False でスクロールし、バッチ単位で再埋め込みして、新しいコレクションにアップサートします
• 並列バッチでアップロードします（リクエストあたり64〜256ポイント、並列ストリーム2〜4本）［一括アップロード］(https://search.qdrant.tech/md/documentation/tutorials-develop/bulk-upload/)
• 一括読み込み中はHNSWを無効にします（indexing_threshold_kb を非常に大きな値に設定し、完了後に元に戻します）
• Qdrant Cloudの推論では、モデルの切り替えはパイプラインの変更ではなく、設定の変更です［推論ドキュメント］(https://search.qdrant.tech/md/documentation/inference/)

400GBを超えるデータセットでは、数日かかることを想定してください。小規模なデータセット（25MB未満）では、移行ツールを使うより、ソースから再インデックスするほうが高速です。

やってはいけないこと

• 既存のコレクションに名前付きベクトルを追加できると思い込むこと（作成時に定義する必要があります）
• 新しいコレクションを検証する前に古いコレクションを削除すること
• アプリケーションコード内のクエリ埋め込みモデルの更新を忘れること
• エイリアスの切り替え時にペイロードの移行を省略すること（エイリアスはクエリの転送先を変更するだけで、データはコピーしません）
• 長期の移行中に、ColBERTベクトルを密ベクトルと同じ場所に置き続けること（I/Oコストにより、すべてのクエリの性能が低下します）
• チャンク単位でのBM25の品質をテストせずに、ハイブリッド検索に移行すること