qdrant-migration-tool

Qdrant 移行ツール

このツールは Docker コンテナ（registry.cloud.qdrant.io/library/qdrant-migration）であり、インポートして使うライブラリではありません。ソースとターゲットを直接接続するのではなく、実行環境を経由してバッチ単位でデータをストリーミングします。また、最初からやり直すのではなく、デフォルトで処理を再開します。Qdrant への移行

適切なサブコマンドの選択

使用する場面：新しい移行を開始し、ソースに対応する CLI サブコマンドを選ぶとき。

• ソースに対応するサブコマンドを選びます：pinecone、weaviate、milvus、elasticsearch、opensearch、pg（pgvector）、s3（S3 Vectors）、azure（Azure AI Search）、chroma、redis、mongodb、faiss、solr、または qdrant。Qdrant への移行
• Weaviate、Redis、MongoDB、Apache Solr ではターゲットのコレクションが自動作成されません。移行を実行する前に、ベクトルサイズと距離メトリックが一致するコレクションを Qdrant に作成してください。それ以外のソースでは自動作成されます。
• ソースごとに認証情報とマッピングのガイドがあります。概念の対応付け（名前空間、インデックス、メタデータフィールド）はソース固有のため、移行を実行する前にガイドを確認してください。Pinecone Weaviate Milvus Elasticsearch OpenSearch Azure AI search pgvector S3 Vectors Chroma Redis MongoDB FAISS Apache Solr Qdrant-to-Qdrant
• ソースが一覧にない場合は、独自のパイプラインを即興で作るのではなく、GitHub の課題トラッカーを案内してください。課題を作成

ローカルインスタンスに対して実行する

使用する場面：ソースまたはターゲットのデータベースが、移行コンテナと同じマシンで稼働しているとき。

• docker run コマンドに --net=host を追加します。追加しないと、コンテナからホストマシン上の localhost を名前解決できません。Qdrant への移行
• 両方のデータベースに対して低レイテンシーで接続できるマシン上でコンテナを実行してください。ツールは実行場所を経由してデータをストリーミングするため、ソースとターゲットの直接接続は不要ですが、移行ホストと各データベース間の往復時間は累積します。

移行が中断された場合

使用する場面：移行が途中で停止し、続きから再開する必要があるとき、または最初からやり直す必要があるとき。

• 同じコマンドをそのまま再実行します。進捗は Qdrant の _migration_offsets コレクションで管理されるため、移行済みのポイントを再コピーせず、自動的に再開します。
• 保存された進捗を破棄して最初からやり直すには、--migration.restart を渡します。たとえば、ソース側の不適切なフィルターを修正した後や、移行中にコレクションスキーマを変更した後に使用します。
• オフセットコレクション名のカスタマイズが必要になるのは、同じ Qdrant インスタンスへの複数の移行を同時に実行する場合だけです。それ以外の場合は、後で確認し忘れる状態を追跡しないよう、--migration.offsets-collection をデフォルトのままにしてください。

移行が遅すぎる場合

使用する場面：ソースデータセットの規模に対してスループットが低すぎる場合。

• 大規模な移行では、--migration.batch-size をデフォルトの 50 から 256 または 512 に引き上げます。バッチが小さいと、アップサートの各ラウンドトリップを十分に活用できません。
• --migration.num-workers が存在するのは pg と qdrant のサブコマンドのみです。他のソースには並列ワーカーのフラグがないため、それらのスループットはバッチサイズとネットワーク上の距離だけで決まります。
• --migration.batch-delay のデフォルトは 0 です。フルスピードでの読み取りに対応できないソースデータベースの負荷を抑える必要がある場合に限り、意図的に増やしてください。デフォルトの調整項目として使うものではありません。
• ツールにはソースやターゲットのレイテンシーを補う方法がないため、低速なネットワーク経路を避け、両方のデータベースに近い場所でコンテナを実行します。

移行後

使用する場面：移行コマンドの実行が完了し、トラフィックを切り替える前にデータの信頼性を確認する必要がある場合。

• いくつかのポイントを抜き取りで確認するのではなく、検証フレームワークを使って検証します。ポイント数だけでなく、移行前のベースライン、データ整合性チェック、検索品質の検証も対象になります。移行検証ガイド
• 移行後も Postgres/pgvector を Qdrant と並行して稼働させる場合は、移行を一度きりの切り替えとして扱わず、継続的な同期戦略（イベント駆動、バッチ、または二重書き込み）を設定します。Postgres の同期維持

やってはいけないこと

• Weaviate、Redis、MongoDB、または Solr がターゲットのコレクションを自動作成すると想定しないでください。これらのソースはベクトルの次元数や距離メトリックをツールに公開しないため、ソースと完全に一致する設定でコレクションを事前に手動作成する必要があります。Qdrant への移行
• faiss サブコマンドに量子化された FAISS インデックスを指定しないでください。量子化されたインデックスには元のベクトルが保持されないため、サポートされているのは IndexFlatL2、IndexFlatIP、IndexHNSWFlat、IndexIVFFlat のみです。FAISS
• すべての Pinecone インデックスを移行できると想定しないでください。ツールがベクトルを列挙するために必要な list 操作をサポートしているのは、サーバーレスインデックスのみです。Pinecone
• 既存のターゲットコレクションに qdrant から qdrant への移行を行う際は、先にベクトルサイズを確認してください。ソースとターゲットの次元数は完全に一致する必要があり、異なっていてもよいのはレプリケーションとシャードの設定のみです。
• プライベート CA または自己署名 CA で署名されたソースやターゲットに TLS で接続する際、CA を SSL_CERT_FILE 経由でマウントせずに接続しないでください。証明書の検証に失敗して移行が停止し、適切な代替処理は行われません。また、--skip-tls-verification はデフォルトの対処法ではなく、意図的に指定する場合に限ってください。
• 問題なく再開できる状態で、念のため --migration.restart を指定しないでください。保存された進捗が破棄され、すでに移行済みのデータも再ストリーミングされます。
• データ整合性と検索品質のチェックを実行せずに、移行の実行が完了しただけで検証済みと見なさないでください。