qdrant-version-upgrade

Qdrant のバージョンアップグレード

Qdrant には、バージョン互換性に関して次の保証があります。

• Qdrant と SDK のメジャーバージョンおよびマイナーバージョンは、一致することが想定されています。たとえば、Qdrant 1.17.x は SDK 1.17.x と互換性があります。

• クライアント SDK は、Qdrant の最新 3 マイナーバージョンとの後方互換性がテストされています。たとえば、SDK 1.17.x は Qdrant 1.15.x から 1.17.x で動作します。ただし、サーバーバージョンがサポートする機能に限られます。アップグレード

• 次のマイナーバージョンへの移行では、まず SDK を次のマイナーバージョンにアップグレードしてから、Qdrant サーバーをアップグレードすることを推奨します。

• ストレージの互換性が保証されるのは、1 マイナーバージョン分のみです。たとえば、Qdrant 1.16.x で保存したデータは、Qdrant 1.17.x との互換性が想定されています。2 つ以上先のマイナーバージョンに移行する場合は、マイナーバージョンごとに段階的にアップグレードする必要があります。たとえば、1.15.x から 1.17.x に移行するには、まず 1.16.x にアップグレードしてから 1.17.x にアップグレードする必要があります。注：Qdrant Cloud ではこのプロセスが自動化されているため、中間の手順を挟まずに 1.15.x から 1.17.x に直接アップグレードできます。

• レプリケーション係数が 2 以上の Qdrant クラスターは、ローリングアップグレードを実行することで、ダウンタイムなしでアップグレードできます。これは、他のノードがリクエストを処理し続ける間に、ノードを 1 つずつアップグレードできるということです。これにより、アップグレード中もアプリケーションの可用性を維持できます。レプリケーション係数の詳細：レプリケーション係数

Qdrant Cloud で Qdrant のバージョンアップグレードを管理するには、qcloud CLI ツールを使用できます。

アップグレード前のチェックリスト

1. まずバックアップを取ります。ロールバックできるように、更新前にバックアップまたはスナップショットを作成することを推奨します。アップグレードに失敗した場合や元に戻す必要がある場合は、アップグレード前のスナップショットを復元できます。Qdrant Cloud ではアップグレード中にデータ移行が行われるため、稼働中にダウングレードすることはできません。スナップショット Cloud バックアップ

2. 非推奨化だけでなく、デフォルトや動作の変更についてもリリースノートを確認してください。バージョンアップグレードによって、API に互換性が保たれていても、既存のワークロードに影響するデフォルト設定、検証ルール、クエリ動作の変更が導入される場合があります。

3. まず本番環境以外で、対象のサーバーバージョンに対してクライアントアプリをテストしてください。また、切り替える前に、非推奨または削除されたメソッドについて SDK のリリースノートを確認してください。

4. ノードごとに少なくとも 2 個の CPU コアを使用することを推奨します。アップグレード中、Qdrant は通常の処理を続けながら、バックグラウンドで最適化を実行することがあります。コアが 1 個しかない場合、これらのタスクが CPU リソースを奪い合い、アップグレード処理が大幅に遅くなる可能性があります。

5. ダウンタイムなしのローリングアップグレードが必要な場合は、レプリケーション係数を 2 以上にしてください。レプリケーション係数が 1 の場合、アップグレードにはダウンタイムが必要です。

複数のマイナーバージョンをまたぐアップグレード

次の場合に使用します：稼働中のバージョンが、対象のバージョンより2つ以上古いマイナーバージョンの場合。

• セルフホスト環境：中間のマイナーバージョンをすべて順に経由し、次に進む前に各バージョンの最新パッチ版へアップグレードします。1.15から1.17へアップグレードする場合、まず最新の1.16.xにしてから、1.17.xにします。Qdrant のアップグレード
• 各ステップで個別にローリング再起動が行われるため、所要時間は単一バージョンのアップグレードを複数回行う場合と同じになります。単一バージョンのアップグレードより時間がかかるため、計画を立て、ピーク時間を避けて実施してください。
• Qdrant Cloud では中間のアップデートが自動で適用されるため、1.15.xから1.17.xへのアップグレードは1回の操作で完了します。Qdrant Cloud クラスターのアップデート
• 今後のアップグレードでまたぐマイナーバージョンを1つに抑えられるよう、定期的にアップグレードしてください。定期的なアップグレードにより、大幅なバージョンアップを避け、将来の移行の複雑さも軽減できます。

アップグレード後の動作の変化に関するトラブルシューティング

次の場合に使用します：新しいバージョンの稼働後に、結果、スコア、またはレイテンシが異なって見える場合。

• アップグレード後のバグや予期しない動作を調査する際は、ソースバージョンから対象バージョンまでのリリースノート／変更履歴を確認し、ワークロードに影響する可能性のある非推奨化、デフォルト値の変更、動作の変更を調べてください。

• 絶対的なスコア値ではなく、アップグレード前のベースラインと比較した相対的な順位付けと再現率を確認してください。スコアリングの内部処理はバージョン間で変更されることがありますが、それでも正しい場合があります。

やってはいけないこと

• バージョン間で絶対スコアが同一であることを、合格基準にする
• 対象バージョンのノートだけを読み、中間のマイナーリリースやパッチリリースを確認しない
• セルフホスト環境で、複数のマイナーバージョンを一度に飛ばしてアップグレードする
• すべてのノードが対象バージョンを報告していることを確認せずに、ローリングアップグレードが完了したと判断する