このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。Dify 1.17.1 では、同梱する Weaviate サーバーが
1.27.0 から 1.39.2 に更新されます。既存の Weaviate データボリュームは、この差を一度に越えられません。この手順は、Dify の既定の単一ノード Docker Compose デプロイを対象とします。新規デプロイでは、空のボリュームで新しいバージョンを起動するため、この手順は不要です。
Weaviate はマイナーバージョンの飛び越しをテストも保証もしていません。各リリースにはディスク上のデータ移行が含まれることがあり、その移行は直前のバージョンが一度は起動していることを前提とします。
サポートされる手順は、マイナーリリースを順に 1 つずつ進め、それぞれの最新パッチで止めることです。以下にその手順一覧と、作業中につまずきやすい 2 つの運用上の注意点を示します。
現在のバージョンを確認
Dify リポジトリのルートからdocker ディレクトリに移動し、以降も同じシェルを使用します。既定の docker-compose.yaml は Weaviate のホストポートを公開しません。そのため、ホスト側の localhost ではなく Compose ネットワーク内部で確認します。
localhost は Weaviate コンテナ自身のループバックであり、ホストではありません。Weaviate イメージには curl も Python も含まれません。そのためリクエストは busybox の wget で送り、JSON の整形はホスト側の Python で行います。
1.39.2 と表示される場合、作業は不要です。1.27.0 なら以下から開始し、一覧内の途中のバージョンならその次の段階から再開してください。1.27.0 より前のバージョンでは、先に Weaviate v4 移行ガイド に従ってください。
データのバックアップ
Docker デプロイでは、ボリュームをオフラインでコピーする方法が最も簡単です。まず Dify のリクエストサービスとワーカーサービスを停止し、最後の段階が完了するまで停止したままにします。docker-compose.yaml に api_websocket が定義されていない場合は、以下のコマンドからこのサービス名を削除してください。
cp -a は所有者、パーミッション、タイムスタンプを保持します。sudo で実行する通常の cp -r はこれらを書き換えるため、復元したボリュームを Weaviate コンテナが読めなくなることがあります。
本番環境では、S3、GCS、Azure に書き出す Weaviate の バックアップモジュール を推奨します。ディレクトリの生コピーではなく復元可能なスナップショットを作成でき、稼働中のインスタンスに対しても実行できます。ローカルファイルシステムのバックエンドは開発用途に限られます。
マイナーバージョンごとのアップグレード
すべてのマイナーリリースを順に進め、毎回そのマイナーの最新パッチで止めます。
レジストリは手順 1 で変わります。既存のデプロイは Docker Hub の
semitechnologies/weaviate を取得しますが、この一覧では Weaviate 自身のレジストリである cr.weaviate.io/semitechnologies/weaviate を使います。Dify の新しい Compose ファイルもこちらを参照します。イメージは同じもので、レジストリとバージョンを意図的にまとめて変更します。
表のパッチバージョンは執筆時点の最新です。途中の手順については、開始前に新しいパッチが出ていないか確認し、あればそちらを使ってください。
1 つずつ進めることで影響範囲も限定できます。ある段階で問題が起きても、戻すのは 1 バージョンだけで済み、原因となったリリースもすぐ特定できます。すべてのマイナーを一度にまたいだ切り分けは不要です。
最新に近い状態を保つことが修正を受け取り続ける条件です。Weaviate がサポートするのは 直近 3 つのマイナーバージョン、つまり現行版とその前の 2 つだけです。それより古いバージョンは EOL であり、不具合修正やセキュリティ修正の提供対象ではありません。今回の移行後も定期的に確認し、その時点の最新パッチへ更新してください。
Docker Compose でのアップグレード
Dify はdocker/docker-compose.yaml、docker/docker-compose.middleware.yaml、docker/docker-compose-template.yaml の 3 か所で Weaviate のイメージを固定しています。実際にデプロイに使うファイルを編集し、各段階で次の手順を繰り返します。
1
次のイメージタグを設定
weaviate サービスを次のマイナーの最新パッチに変更します。例:image: cr.weaviate.io/semitechnologies/weaviate:1.28.162
コンテナを正常に停止
docker kill や docker rm -f は絶対に使わないでください。強制終了の代償は Weaviate の正常な停止 を参照してください。3
新しいバージョンを起動
4
次に進む前に確認
続行する前に 各段階での確認 を実行します。
docker-compose.middleware.yaml で Weaviate を動かしている場合も同じ手順です。ファイルを明示的に指定します。
Weaviate の正常な停止
検索が動かなくなる原因として最も多く、しかも間違えやすいのがこの点です。 Weaviate は HNSW ベクトルインデックスをメモリ上に保持し、コミットログを通じてディスクに記録します。コンテナが強制終了されると、コミットログが不完全なまま残ります。記録前のオブジェクトはグラフから欠落します。強制終了にあたるのはdocker kill、docker rm -f、メモリ不足による強制終了、Docker の猶予時間を超えた停止です。
失われるのはオブジェクトではなくグラフです。1.39.2 での実測では、合計 700 件のコレクションに 500 件を取り込んだ直後に強制終了したところ、次の状態になりました。
20 件のオブジェクトはそのまま残っているのに、ベクトル検索から到達できない状態です。
危険なのは、何も知らせてくれない点です。サーバーはエラーも警告も出さず、コミットログについては一切触れません。grep すべきログ行がありません。しかも多くの人が最初に見るオブジェクト件数は、まったく正常に見えます。
自然に回復することもありません。再起動後も、正常停止して起動し直した後も、もう一度繰り返した後も、同じオブジェクトを書き直した後も、欠落しているのは同じ 20 件でした。修復するには、Dify で該当するナレッジベースを再インデックスし、コレクションを作り直します。
つまり、ここでは予防がすべてです。
docker compose stop または docker compose down を使ってください。どちらも SIGTERM を送ります。プロセスが書き出しを完了するまで待ちます。タイムアウトを -1 にすると、SIGKILL に切り替えず無期限に待機します。
limit に指定して near_vector クエリを実行してください。返る件数が少なければ、その差が到達できないオブジェクトです。
再起動のたびにインデックスのマウントを待つ
一覧上のどのバージョンでも、/v1/meta はコンテナ起動の約 2 秒後には応答を返します。コレクションのマウントはそれより遅く、1.31 以降は特に遅くなります。一覧全体で実測した、/v1/meta の応答開始からコレクションへのクエリが初めて成功するまでの間隔は次のとおりです。
この時間帯に投げたクエリは「起動中」とは伝えません。データが存在しないという応答を返します。
GET /v1/objects?class=...は空のボディで 404 を返します。- GraphQL クエリは 422 と
no graphql provider present, this is most likely because no schema is present. Import a schema first!を返します。
/v1/meta だけを見るのではなく、実際のコレクションへのクエリが成功するまでポーリングします。
各段階での確認
データが残っていることと、検索が動くことの両方を確認します。サーバーが起動しても、インデックスが健全である証拠にはなりません。 まずキーとコレクション名を設定し、4 つの確認を実行します。Dify はナレッジベース ID のハイフンをすべてアンダースコアに置き換えて、コレクション名を付けます。手作業で組み立てず、2 つ目の確認結果から正確な名前をコピーしてください。1.39.2 の確認後、docker compose stop -t -1 weaviate || exit 1 を実行します。Compose を実行せずに一時的なイメージ変更だけを元に戻します。次に、Dify 1.17.1 の Docker Compose アップグレード手順 に従います。デプロイをサービスに戻す前にテスト検索を実行してください。チャンクが返ればベクトルインデックスが残っていると確認できます。オブジェクト数だけでは、そこまでは分かりません。
失敗した段階のロールバック
Dify 1.17.1 を起動する前に、Weaviate イメージをsemitechnologies/weaviate:1.27.0 に戻し、初期バックアップを復元します。
変更されない部分
コレクションの構成は変わらないため、再インデックスは不要で、ナレッジベースもそのまま使えます。Dify は各データセットをVector_index_<dataset_id>_Node コレクションとして保存します。ID のハイフンはアンダースコアに置き換えられ、自前で指定する名前付きベクトル default が使われます。Dify は距離指標を設定しないため、コレクションはサーバー既定のコサイン距離になります。この構造はアップグレードの前後で同一です。
Python の weaviate-client についても対応は不要です。利用中の Dify リリースが固定しているバージョンを使ってください。Dify 1.14.0 から 1.16.1 は 4.20.5、1.17.0 から 1.17.1 は 4.22.0 です。どちらも一覧のすべてのサーバーバージョンで動作するため、サーバーだけを Dify と切り離してアップグレードできます。
対象は 1.27 より古い Weaviate サーバー、およびクライアント v3 から v4 への移行です。どちらの場合も先に Weaviate v4 移行ガイド を参照してください。同ガイドは 1.19.0 から 1.26.x と、1.27 までのスキーマ移行を扱います。その後このページに戻ってください。