> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Weaviate サーバーのアップグレード経路

> セルフホスト Weaviate サーバーをベクトルデータを失わずにマイナーバージョン間で移行する方法

> このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/self-host/deploy/troubleshooting/weaviate-server-migration-path) を参照してください。

Dify 1.17.1 では、同梱する Weaviate サーバーが `1.27.0` から `1.39.2` に更新されます。既存の Weaviate データボリュームは、この差を一度に越えられません。この手順は、Dify の既定の単一ノード Docker Compose デプロイを対象とします。新規デプロイでは、空のボリュームで新しいバージョンを起動するため、この手順は不要です。

Weaviate はマイナーバージョンの飛び越しをテストも保証もしていません。各リリースにはディスク上のデータ移行が含まれることがあり、その移行は直前のバージョンが一度は起動していることを前提とします。

サポートされる手順は、マイナーリリースを順に 1 つずつ進め、それぞれの最新パッチで止めることです。以下にその手順一覧と、作業中につまずきやすい 2 つの運用上の注意点を示します。

<Warning>
  開始前に Weaviate のデータボリュームをバックアップしてください。アップグレードが途中で失敗した場合、復旧できるのはスナップショットがあるときだけです。
</Warning>

## 現在のバージョンを確認

Dify リポジトリのルートから `docker` ディレクトリに移動し、以降も同じシェルを使用します。既定の `docker-compose.yaml` は Weaviate のホストポートを公開しません。そのため、ホスト側の `localhost` ではなく Compose ネットワーク内部で確認します。

```bash theme={null}
cd docker
docker compose exec -T weaviate \
  wget -qO- --header="Authorization: Bearer <WEAVIATE_API_KEY>" \
  http://localhost:8080/v1/meta \
  | python3 -c "import sys, json; print(json.load(sys.stdin)['version'])"
```

URL の `localhost` は Weaviate コンテナ自身のループバックであり、ホストではありません。Weaviate イメージには `curl` も Python も含まれません。そのためリクエストは busybox の `wget` で送り、JSON の整形はホスト側の Python で行います。

`1.39.2` と表示される場合、作業は不要です。`1.27.0` なら以下から開始し、一覧内の途中のバージョンならその次の段階から再開してください。`1.27.0` より前のバージョンでは、先に [Weaviate v4 移行ガイド](/ja/self-host/deploy/troubleshooting/weaviate-v4-migration) に従ってください。

## データのバックアップ

Docker デプロイでは、ボリュームをオフラインでコピーする方法が最も簡単です。まず Dify のリクエストサービスとワーカーサービスを停止し、最後の段階が完了するまで停止したままにします。

`docker-compose.yaml` に `api_websocket` が定義されていない場合は、以下のコマンドからこのサービス名を削除してください。

```bash theme={null}
docker compose stop -t 120 nginx api api_websocket worker worker_beat || exit 1
```

[各段階での確認](#各段階での確認) を一度実行し、開始時のオブジェクト数を記録して同期を確認します。続いて Weaviate を停止し、ボリュームをコピーします。

```bash theme={null}
docker compose stop -t -1 weaviate || exit 1
sudo cp -a ./volumes/weaviate ./volumes/weaviate_backup_$(date +%Y%m%d) || exit 1
```

`cp -a` は所有者、パーミッション、タイムスタンプを保持します。`sudo` で実行する通常の `cp -r` はこれらを書き換えるため、復元したボリュームを Weaviate コンテナが読めなくなることがあります。

本番環境では、S3、GCS、Azure に書き出す Weaviate の [バックアップモジュール](https://docs.weaviate.io/deploy/configuration/backups) を推奨します。ディレクトリの生コピーではなく復元可能なスナップショットを作成でき、稼働中のインスタンスに対しても実行できます。ローカルファイルシステムのバックエンドは開発用途に限られます。

## マイナーバージョンごとのアップグレード

すべてのマイナーリリースを順に進め、毎回そのマイナーの最新パッチで止めます。

| 手順    | イメージタグ                                             |
| :---- | :------------------------------------------------- |
| 0（現在） | `semitechnologies/weaviate:1.27.0`                 |
| 1     | `cr.weaviate.io/semitechnologies/weaviate:1.27.27` |
| 2     | `cr.weaviate.io/semitechnologies/weaviate:1.28.16` |
| 3     | `cr.weaviate.io/semitechnologies/weaviate:1.29.11` |
| 4     | `cr.weaviate.io/semitechnologies/weaviate:1.30.23` |
| 5     | `cr.weaviate.io/semitechnologies/weaviate:1.31.22` |
| 6     | `cr.weaviate.io/semitechnologies/weaviate:1.32.27` |
| 7     | `cr.weaviate.io/semitechnologies/weaviate:1.33.18` |
| 8     | `cr.weaviate.io/semitechnologies/weaviate:1.34.20` |
| 9     | `cr.weaviate.io/semitechnologies/weaviate:1.35.23` |
| 10    | `cr.weaviate.io/semitechnologies/weaviate:1.36.23` |
| 11    | `cr.weaviate.io/semitechnologies/weaviate:1.37.16` |
| 12    | `cr.weaviate.io/semitechnologies/weaviate:1.38.14` |
| 13    | `cr.weaviate.io/semitechnologies/weaviate:1.39.2`  |

レジストリは手順 1 で変わります。既存のデプロイは Docker Hub の `semitechnologies/weaviate` を取得しますが、この一覧では Weaviate 自身のレジストリである `cr.weaviate.io/semitechnologies/weaviate` を使います。Dify の新しい Compose ファイルもこちらを参照します。イメージは同じもので、レジストリとバージョンを意図的にまとめて変更します。

表のパッチバージョンは執筆時点の最新です。途中の手順については、開始前に新しいパッチが出ていないか確認し、あればそちらを使ってください。

<Warning>
  最後の手順は例外です。利用可能な最新パッチではなく、`docker-compose.yaml` が固定しているバージョンで止めてください。先に新しいパッチへ上げてから Dify の固定バージョンを適用すると、新しいバージョンが書き込んだボリュームに対するダウングレードになります。これは [ロールバックの注意](#失敗した段階のロールバック) で警告している状況です。
</Warning>

1 つずつ進めることで影響範囲も限定できます。ある段階で問題が起きても、戻すのは 1 バージョンだけで済み、原因となったリリースもすぐ特定できます。すべてのマイナーを一度にまたいだ切り分けは不要です。

<Info>
  最新に近い状態を保つことが修正を受け取り続ける条件です。Weaviate がサポートするのは [直近 3 つのマイナーバージョン](https://weaviate.io/weaviate-eol-policy)、つまり現行版とその前の 2 つだけです。それより古いバージョンは EOL であり、不具合修正やセキュリティ修正の提供対象ではありません。今回の移行後も定期的に確認し、その時点の最新パッチへ更新してください。
</Info>

## Docker Compose でのアップグレード

Dify は `docker/docker-compose.yaml`、`docker/docker-compose.middleware.yaml`、`docker/docker-compose-template.yaml` の 3 か所で Weaviate のイメージを固定しています。実際にデプロイに使うファイルを編集し、各段階で次の手順を繰り返します。

<Steps>
  <Step title="次のイメージタグを設定">
    `weaviate` サービスを次のマイナーの最新パッチに変更します。例：`image: cr.weaviate.io/semitechnologies/weaviate:1.28.16`
  </Step>

  <Step title="コンテナを正常に停止">
    ```bash theme={null}
    docker compose stop -t -1 weaviate || exit 1
    ```

    ここで `docker kill` や `docker rm -f` は絶対に使わないでください。強制終了の代償は [Weaviate の正常な停止](#weaviate-の正常な停止) を参照してください。
  </Step>

  <Step title="新しいバージョンを起動">
    ```bash theme={null}
    docker compose up -d weaviate
    ```
  </Step>

  <Step title="次に進む前に確認">
    続行する前に [各段階での確認](#各段階での確認) を実行します。
  </Step>
</Steps>

ソースから開発していて `docker-compose.middleware.yaml` で Weaviate を動かしている場合も同じ手順です。ファイルを明示的に指定します。

```bash theme={null}
docker compose -f docker-compose.middleware.yaml stop -t -1 weaviate || exit 1
docker compose -f docker-compose.middleware.yaml --profile weaviate up -d weaviate
```

## Weaviate の正常な停止

検索が動かなくなる原因として最も多く、しかも間違えやすいのがこの点です。

Weaviate は HNSW ベクトルインデックスをメモリ上に保持し、コミットログを通じてディスクに記録します。コンテナが強制終了されると、コミットログが不完全なまま残ります。記録前のオブジェクトはグラフから欠落します。強制終了にあたるのは `docker kill`、`docker rm -f`、メモリ不足による強制終了、Docker の猶予時間を超えた停止です。

失われるのはオブジェクトではなくグラフです。1.39.2 での実測では、合計 700 件のコレクションに 500 件を取り込んだ直後に強制終了したところ、次の状態になりました。

| 確認項目                        | 結果                  |
| :-------------------------- | :------------------ |
| オブジェクト件数                    | 700 件、正しい           |
| 全オブジェクトの一覧                  | 700 件すべて返る          |
| キーワード（BM25）検索               | 取り込んだ 500 件すべてが見つかる |
| ID 指定の取得                    | 正確なベクトルを返す          |
| `near_vector`（`limit: 700`） | **680**             |

20 件のオブジェクトはそのまま残っているのに、ベクトル検索から到達できない状態です。

危険なのは、何も知らせてくれない点です。サーバーはエラーも警告も出さず、コミットログについては一切触れません。grep すべきログ行がありません。しかも多くの人が最初に見るオブジェクト件数は、まったく正常に見えます。

自然に回復することもありません。再起動後も、正常停止して起動し直した後も、もう一度繰り返した後も、同じオブジェクトを書き直した後も、欠落しているのは同じ 20 件でした。修復するには、Dify で該当するナレッジベースを再インデックスし、コレクションを作り直します。

つまり、ここでは予防がすべてです。`docker compose stop` または `docker compose down` を使ってください。どちらも SIGTERM を送ります。プロセスが書き出しを完了するまで待ちます。タイムアウトを `-1` にすると、SIGKILL に切り替えず無期限に待機します。

```bash theme={null}
docker compose stop -t -1 weaviate || exit 1
```

すでに発生していないか確認するには、オブジェクト件数とベクトル検索が実際に到達できる件数を比べます。件数の取得コマンドは [各段階での確認](#各段階での確認) にあります。その値を `limit` に指定して `near_vector` クエリを実行してください。返る件数が少なければ、その差が到達できないオブジェクトです。

## 再起動のたびにインデックスのマウントを待つ

一覧上のどのバージョンでも、`/v1/meta` はコンテナ起動の約 2 秒後には応答を返します。コレクションのマウントはそれより遅く、1.31 以降は特に遅くなります。一覧全体で実測した、`/v1/meta` の応答開始からコレクションへのクエリが初めて成功するまでの間隔は次のとおりです。

| サーバーバージョン   | クエリが通るまでの間隔 |
| :---------- | :---------- |
| 1.27 - 1.30 | 0.3 秒未満     |
| 1.31 以降     | 4 - 9 秒     |

この時間帯に投げたクエリは「起動中」とは伝えません。データが存在しないという応答を返します。

* `GET /v1/objects?class=...` は空のボディで **404** を返します。
* GraphQL クエリは **422** と `no graphql provider present, this is most likely because no schema is present. Import a schema first!` を返します。

アップグレードの途中でこれを見ると不安になりますが、誤警報です。この時間帯は一時的なもので、待つ以外の対応は不要です。再起動のたびに 10 秒ほど見てから判断してください。ヘルスチェックをスクリプト化する場合は、`/v1/meta` だけを見るのではなく、実際のコレクションへのクエリが成功するまでポーリングします。

## 各段階での確認

データが残っていることと、検索が動くことの両方を確認します。サーバーが起動しても、インデックスが健全である証拠にはなりません。

まずキーとコレクション名を設定し、4 つの確認を実行します。Dify はナレッジベース ID のハイフンをすべてアンダースコアに置き換えて、コレクション名を付けます。手作業で組み立てず、2 つ目の確認結果から正確な名前をコピーしてください。

```bash theme={null}
KEY="<WEAVIATE_API_KEY>"
# Dify URL（/datasets/<id>/documents）のナレッジベース ID。ハイフンはアンダースコアに置換
COLLECTION="Vector_index_9f4e2b7a_1c3d_4e5f_8a9b_0c1d2e3f4a5b_Node"

# 報告されたサーバーバージョン
docker compose exec -T weaviate \
  wget -qO- --header="Authorization: Bearer $KEY" http://localhost:8080/v1/meta \
  | python3 -c "import sys, json; print('version', json.load(sys.stdin)['version'])"

# コレクションの存在
docker compose exec -T weaviate \
  wget -qO- --header="Authorization: Bearer $KEY" http://localhost:8080/v1/schema \
  | python3 -c "import sys, json; print([c['class'] for c in json.load(sys.stdin)['classes']])"

# 単一コレクションのオブジェクト数
docker compose exec -T weaviate \
  wget -qO- --header="Authorization: Bearer $KEY" \
  --header="Content-Type: application/json" \
  --post-data="{\"query\":\"{ Aggregate { $COLLECTION { meta { count } } } }\"}" \
  http://localhost:8080/v1/graphql \
  | python3 -c "import sys, json; print('count', json.load(sys.stdin)['data']['Aggregate']['$COLLECTION'][0]['meta']['count'])"

# 単一ノードのメタデータが同期済み
docker compose exec -T weaviate \
  wget -qO- --header="Authorization: Bearer $KEY" \
  http://localhost:8080/v1/cluster/statistics \
  | python3 -c "import sys, json; d=json.load(sys.stdin); assert d.get('synchronized') is True and len(d.get('statistics', [])) == 1; print('synchronized')"
```

報告されたバージョンが現在の段階と一致し、オブジェクト数が変わらず、同期確認に成功した場合にのみ続行してください。

<Warning>
  オブジェクト数の確認に `GET /v1/objects?class=...&limit=1` を使わないでください。`totalResults` フィールドが返すのは取得したページの件数であり、コレクション全体の件数ではありません。`limit=1` では常に `1` になります。上記の `Aggregate` クエリを使ってください。
</Warning>

`1.39.2` の確認後、`docker compose stop -t -1 weaviate || exit 1` を実行します。Compose を実行せずに一時的なイメージ変更だけを元に戻します。次に、Dify 1.17.1 の [Docker Compose アップグレード手順](/ja/self-host/deploy/quick-start/docker-compose#アップグレード) に従います。デプロイをサービスに戻す前にテスト検索を実行してください。チャンクが返ればベクトルインデックスが残っていると確認できます。オブジェクト数だけでは、そこまでは分かりません。

## 失敗した段階のロールバック

Dify 1.17.1 を起動する前に、Weaviate イメージを `semitechnologies/weaviate:1.27.0` に戻し、初期バックアップを復元します。

```bash theme={null}
docker compose stop -t -1 weaviate || exit 1
test -d ./volumes/weaviate_backup_YYYYMMDD || exit 1
sudo mv ./volumes/weaviate ./volumes/weaviate_failed_$(date +%Y%m%dT%H%M%S) || exit 1
sudo cp -a ./volumes/weaviate_backup_YYYYMMDD ./volumes/weaviate || exit 1
docker compose up -d weaviate
```

<Warning>
  データを復元せずにイメージタグだけを戻すのは安全ではありません。新しいバージョンが一度そのボリュームに書き込むと、古いバイナリでは読めなくなる場合があります。
</Warning>

Weaviate を確認してから元の Dify スタックを起動し、テスト検索を実行します。

## 変更されない部分

コレクションの構成は変わらないため、再インデックスは不要で、ナレッジベースもそのまま使えます。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 と切り離してアップグレードできます。

<Info>
  対象は 1.27 より古い Weaviate サーバー、およびクライアント v3 から v4 への移行です。どちらの場合も先に [Weaviate v4 移行ガイド](/ja/self-host/deploy/troubleshooting/weaviate-v4-migration) を参照してください。同ガイドは 1.19.0 から 1.26.x と、1.27 までのスキーマ移行を扱います。その後このページに戻ってください。
</Info>