Weaviate 移行ガイド：クライアント v4 とサーバー 1.27+ へのアップグレード

このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版を参照してください。

このガイドでは、Weaviate クライアント v3 から v4.17.0 への移行と、Weaviate サーバーをバージョン 1.19.0 から 1.27.0 以降にアップグレードする方法について説明します。この移行は、weaviate-client v4 アップグレードを含む Dify バージョンに必要です。

概要

Dify v1.9.2 以降、weaviate-client が v3 から v4.17.0 にアップグレードされました。このアップグレードにより、パフォーマンスが大幅に向上し、安定性が向上しますが、Weaviate サーバーバージョン 1.27.0 以降が必要です。

破壊的変更：新しい weaviate-client v4 は、Weaviate サーバーバージョン 1.27.0 未満との後方互換性がありません。バージョン 1.19.0 以前のセルフホスト Weaviate インスタンスを実行している場合は、Dify をアップグレードする前に Weaviate サーバーをアップグレードする必要があります。

影響を受けるユーザー

この移行の影響を受けるのは：

1.27.0 未満のバージョンでセルフホスト Weaviate インスタンスを実行しているセルフホスト Dify ユーザー
現在 Weaviate サーバーバージョン 1.19.0-1.26.x を使用しているユーザー
weaviate-client v4 を含む Dify バージョンにアップグレードするユーザー

影響を受けないユーザー：

クラウドホスト Weaviate ユーザー（Weaviate Cloud がサーバーバージョンを管理）
すでに Weaviate 1.27.0+ を使用しているユーザーは、追加の手順なしで Dify をアップグレードできます
Dify のデフォルト Docker Compose セットアップを実行しているユーザー（Weaviate バージョンは自動的に更新されます）

破壊的変更

クライアント v4 の要件

weaviate-client v4 では、いくつかの破壊的変更が導入されています：

最小サーバーバージョン：Weaviate サーバー 1.27.0 以降が必要
API 変更：新しいインポート構造（weaviate.client ではなく weaviate.classes）
gRPC サポート：パフォーマンス向上のため、デフォルトでポート 50051 で gRPC を使用
認証の変更：更新された認証方法と構成

なぜアップグレードするのか？

パフォーマンス：gRPC (50051) により、クエリおよびインポート操作が大幅に高速化
安定性：接続処理とエラー回復の改善
将来の互換性：最新の Weaviate 機能と継続的なサポートへのアクセス
セキュリティ：Weaviate 1.19.0 は 1 年以上前のもので、セキュリティアップデートを受け取っていません

バージョン互換性マトリックス

Dify バージョン	Weaviate-client バージョン	互換性のある Weaviate サーバーバージョン
≤ 1.9.1	v3.x	1.19.0 - 1.26.x
≥ 1.9.2	v4.17.0	1.27.0+（1.33.1 までテスト済み）

この移行は、weaviate-client v4.17.0 以降を使用するすべての Dify バージョンに適用されます。

Weaviate サーバーバージョン 1.19.0 は 1 年以上前にリリースされ、現在は古くなっています。1.27.0+ にアップグレードすると、パフォーマンス、安定性、機能の数多くの改善にアクセスできます。

前提条件

移行を開始する前に、次の手順を完了してください：

現在の Weaviate バージョンを確認
curl http://localhost:8080/v1/meta
レスポンスで version フィールドを探します。
データをバックアップ
- Weaviate データの完全バックアップを作成
- Docker Compose を使用している場合は、Docker ボリュームをバックアップ
- 現在の構成設定を文書化
システム要件を確認
- データベース移行のための十分なディスク容量を確保
- Dify と Weaviate 間のネットワーク接続を検証
- 外部 Weaviate を使用している場合、gRPC ポート (50051) がアクセス可能であることを確認
ダウンタイムを計画
- 移行にはサービスのダウンタイムが必要
- 本番環境で実行している場合はユーザーに通知
- トラフィックの少ない時間帯に移行をスケジュール

移行パス

デプロイメント設定と現在の Weaviate バージョンに一致する移行パスを選択してください。

パスを選択

パス A – バックアップを使用した移行（1.19 から）：まだ Weaviate 1.19 を使用している場合に推奨されます。バックアップを作成し、1.27+ にアップグレードし、孤立したデータを修復してから、スキーマを移行します。
パス B – 直接リカバリ（すでに 1.27+ の場合）：すでに 1.27+ にアップグレードしてナレッジベースが動作しなくなった場合に使用します。このパスはデータレイアウトの修復とスキーマ移行の実行に焦点を当てています。

1.19 へのダウングレードを試みないでください。スキーマ形式に互換性がなく、データ損失につながります。

パス A：バックアップを使用した移行（1.19 から）

最も安全なパスです。アップグレード前にバックアップを作成するため、問題が発生した場合に復元できます。

前提条件

現在 Weaviate 1.19 を実行中
Docker + Docker Compose がインストール済み
スキーマ移行スクリプト用に Python 3.12

ステップ A1：Weaviate 1.19 でバックアップモジュールを有効化

docker/docker-compose.yaml を編集して、weaviate サービスにバックアップ構成を含めます：

weaviate:
  image: semitechnologies/weaviate:1.19.0
  volumes:
    - ./volumes/weaviate:/var/lib/weaviate
    - ./volumes/weaviate_backups:/var/lib/weaviate/backups
  ports:
    - "8080:8080"
    - "50051:50051"
  environment:
    ENABLE_MODULES: backup-filesystem
    BACKUP_FILESYSTEM_PATH: /var/lib/weaviate/backups
    # ... 残りの環境変数

Weaviate を再起動して変更を適用：

cd docker
docker compose down
docker compose --profile up -d
sleep 10

ステップ A2：バックアップを作成

コレクションを一覧表示：

curl -s -H "Authorization: Bearer <WEAVIATE_API_KEY>" \
  "http://localhost:8080/v1/schema" | \
  python3 -c "
import json, sys
data = json.load(sys.stdin)
print("Collections:")
for cls in data.get('classes', []):
    print(f\"  - {cls['class']}\")
"

バックアップをトリガー：必要に応じて特定のコレクション名を含めます。

curl -X POST \
  -H "Authorization: Bearer <WEAVIATE_API_KEY>" \
  -H "Content-Type: application/json" \
  "http://localhost:8080/v1/backups/filesystem" \
  -d '{
    "id": "kb-backup",
    "include": ["Vector_index_COLLECTION1_Node", "Vector_index_COLLECTION2_Node"]
  }'

バックアップステータスを確認：

sleep 5
curl -s -H "Authorization: Bearer <WEAVIATE_API_KEY>" \
  "http://localhost:8080/v1/backups/filesystem/kb-backup" | \
  python3 -m json.tool | grep status

バックアップファイルの存在を確認：

ls -lh docker/volumes/weaviate_backups/kb-backup/

ステップ A3：Weaviate 1.27+ にアップグレード

Weaviate 1.27+ を同梱する Dify バージョンにアップグレード：

cd /path/to/dify
git fetch origin
git checkout main  # またはアップグレードを含むタグ付きリリース

新しい Weaviate イメージを確認：

grep "image: semitechnologies/weaviate" docker/docker-compose.yaml

新しいバージョンで再起動：

cd docker
docker compose down
docker compose up -d
sleep 20

ステップ A4：孤立した LSM データを修正（存在する場合）

孤立した LSM データは、ホストからまたはコンテナ内で修正できます： オプション A: ホストから（ボリュームがマウントされている場合）：

cd docker/volumes/weaviate

for dir in vector_index_*_node_*_lsm; do
  [ -d "$dir" ] || continue

  index_id=$(echo "$dir" | sed -n 's/vector_index_\([^_]*_[^_]*_[^_]*_[^_]*_[^_]*\)_node_.*/\1/p')
  shard_id=$(echo "$dir" | sed -n 's/.*_node_\([^_]*\)_lsm/\1/p')

  mkdir -p "vector_index_${index_id}_node/$shard_id/lsm"
  cp -a "$dir/"* "vector_index_${index_id}_node/$shard_id/lsm/"

  echo "✓ Copied $dir"
done

cd ../../
docker compose restart weaviate
sleep 15

オプション B: Weaviate コンテナ内（推奨）：

cd /path/to/dify/docker
docker compose exec -it weaviate /bin/sh

# コンテナ内
cd /var/lib/weaviate
for dir in vector_index_*_node_*_lsm; do
  [ -d "$dir" ] || continue

  index_id=$(echo "$dir" | sed -n 's/vector_index_\([^_]*_[^_]*_[^_]*_[^_]*_[^_]*\)_node_.*/\1/p')
  shard_id=$(echo "$dir" | sed -n 's/.*_node_\([^_]*\)_lsm/\1/p')

  mkdir -p "vector_index_${index_id}_node/$shard_id/lsm"
  cp -a "$dir/"* "vector_index_${index_id}_node/$shard_id/lsm/"

  echo "✓ Copied $dir"
done
exit

# Weaviate を再起動
docker compose restart weaviate
sleep 15

ステップ A5：スキーマを移行

依存関係をインストール（一時的な virtualenv で問題ありません）：

cd /path/to/dify
python3 -m venv weaviate_migration_env
source weaviate_migration_env/bin/activate
pip install weaviate-client requests

移行スクリプトを実行：ローカルまたは Worker コンテナ内で実行できます。
オプション A: ローカルで実行（Python 3.12 と依存関係がインストールされている場合）：
python3 migrate_weaviate_collections.py
オプション B: Worker コンテナ内で実行（Docker セットアップに推奨）：
# スクリプトをストレージディレクトリにコピー cp migrate_weaviate_collections.py /path/to/dify/docker/volumes/app/storage/ # worker コンテナに入る cd /path/to/dify/docker docker compose exec -it worker /bin/bash # 移行スクリプトを実行（Dify 1.11.0+ の場合は --no-cache を使用） uv run --no-cache /app/api/storage/migrate_weaviate_collections.py # コンテナを終了 exit
移行スクリプトは構成に環境変数を使用するため、Docker コンテナ内での実行に適しています。Dify 1.11.0+ で uv の権限エラーが発生した場合は、代わりに uv run --no-cache を使用してください。

Dify サービスを再起動：

cd docker
docker compose restart api worker worker_beat
sleep 15

UI で検証：Dify を開き、移行されたナレッジベースに対して取得をテストします。
大規模なコレクション（10,000 オブジェクト以上）の場合、古いコレクションと新しいコレクション間でオブジェクト数が一致することを確認してください。移行スクリプトは検証カウントを自動的に表示します。

正常な移行を確認した後、weaviate_migration_env とバックアップファイルを削除してディスク容量を回復できます。

パス B：直接リカバリ（すでに 1.27+ の場合）

このパスは、すでに 1.27+ にアップグレードしてナレッジベースが動作しなくなった場合にのみ使用してください。1.19 のバックアップはもう作成できないため、データをその場で修復する必要があります。

前提条件

現在 Weaviate 1.27+（1.33 を含む）を実行中
Docker + Docker Compose がインストール済み
移行スクリプト用に Python 3.12

ステップ B1：孤立した LSM データを修復

Weaviate を停止して孤立した LSM データを修正：

cd /path/to/dify/docker
docker compose stop weaviate

# オプション A: ホストから（ボリュームがマウントされている場合）
cd volumes/weaviate

for dir in vector_index_*_node_*_lsm; do
  [ -d "$dir" ] || continue

  index_id=$(echo "$dir" | sed -n 's/vector_index_\([^_]*_[^_]*_[^_]*_[^_]*_[^_]*\)_node_.*/\1/p')
  shard_id=$(echo "$dir" | sed -n 's/.*_node_\([^_]*\)_lsm/\1/p')

  mkdir -p "vector_index_${index_id}_node/$shard_id/lsm"
  cp -a "$dir/"* "vector_index_${index_id}_node/$shard_id/lsm/"

  echo "✓ Copied $dir"
done

# オプション B: コンテナ内（推奨）
docker compose run --rm --entrypoint /bin/sh weaviate -c "
cd /var/lib/weaviate
for dir in vector_index_*_node_*_lsm; do
  [ -d \"\$dir\" ] || continue
  index_id=\$(echo \"\$dir\" | sed -n 's/vector_index_\([^_]*_[^_]*_[^_]*_[^_]*_[^_]*\)_node_.*/\1/p')
  shard_id=\$(echo \"\$dir\" | sed -n 's/.*_node_\([^_]*\)_lsm/\1/p')
  mkdir -p \"vector_index_\${index_id}_node/\$shard_id/lsm\"
  cp -a \"\$dir/\"* \"vector_index_\${index_id}_node/\$shard_id/lsm/\"
  echo \"✓ Copied \$dir\"
done
"

Weaviate を再起動：

docker compose start weaviate
sleep 15

コレクションを一覧表示し、オブジェクト数がゼロでないことを確認：

curl -s -H "Authorization: Bearer <WEAVIATE_API_KEY>" \
  "http://localhost:8080/v1/schema" | python3 -c "
import sys, json
for cls in json.load(sys.stdin).get('classes', []):
    if cls['class'].startswith('Vector_index_'):
        print(cls['class'])
"

curl -s -H "Authorization: Bearer <WEAVIATE_API_KEY>" \
  "http://localhost:8080/v1/objects?class=YOUR_COLLECTION_NAME&limit=0" | \
  python3 -c "import sys, json; print(json.load(sys.stdin).get('totalResults', 0))"

ステップ B2：スキーマ移行を実行

ステップ A5 と同じコマンドに従います。スクリプトはローカルまたは Worker コンテナ内で実行できます： Worker コンテナ内で実行する場合：

# スクリプトをストレージディレクトリにコピー
cp migrate_weaviate_collections.py /path/to/dify/docker/volumes/app/storage/

# worker コンテナに入る
cd /path/to/dify/docker
docker compose exec -it worker /bin/bash

# 移行スクリプトを実行
uv run --no-cache /app/api/storage/migrate_weaviate_collections.py

# 終了してサービスを再起動
exit
docker compose restart api worker worker_beat

移行スクリプトはカーソルベースのページネーションを使用して、大規模なコレクションを安全に処理します。移行完了後にオブジェクト数が一致することを確認してください。

ステップ B3：Dify で検証

Dify のナレッジベース UI を開きます。
取得テストを使用して、クエリが結果を返すことを確認します。
エラーが続く場合は、docker compose logs weaviate を確認して追加の修復手順を確認してください（トラブルシューティングを参照）。

レガシーバージョンのデータ移行

重要：データ移行が必要です移行なしではアップグレード後に既存のナレッジベースは動作しません！移行が必要な理由：

古いデータ：Weaviate v3 クライアントで作成（シンプルなスキーマ）
新しいコード：Weaviate v4 形式が必要（拡張スキーマ）
互換性なし：古いデータに必要なプロパティがない

移行オプション：

オプション A：Weaviate バックアップ/復元を使用
オプション B：元のドキュメントから再インデックス
オプション C：古い Weaviate を維持（まだアップグレードしない）ダウンタイムやデータ損失を許容できない場合。

自動移行

ほとんどの場合、Weaviate 1.27.0 は 1.19.0 からデータを自動的に移行します：

Weaviate 1.19.0 を停止
同じデータディレクトリで Weaviate 1.27.0 を起動
Weaviate は古い形式を検出し、自動的に移行
ログを監視して移行の進行状況とエラーを確認

手動移行（自動移行が失敗した場合）

自動移行が失敗した場合は、Weaviate のエクスポート/インポートツールを使用：

1. 旧バージョンからデータをエクスポート

Cursor API またはバックアップ機能を使用してすべてのデータをエクスポートします。大規模なデータセットの場合は、Weaviate のバックアップ API を使用：

# バックアップ API を使用（推奨）
curl -X POST "http://localhost:8080/v1/backups/filesystem" \
  -H "Content-Type: application/json" \
  -d '{"id": "pre-migration-backup"}'

2. 新しいバージョンにデータをインポート

Weaviate 1.27.0 にアップグレードした後、バックアップを復元：

curl -X POST "http://localhost:8080/v1/backups/filesystem/pre-migration-backup/restore" \
  -H "Content-Type: application/json"

複雑なスキーマや大規模なデータセットの場合の包括的な移行ガイダンスについては、公式の Weaviate 移行ガイドを参照してください。

構成の変更

新しい環境変数

weaviate-client v4 を含む Dify バージョンで利用可能な新しい環境変数：

WEAVIATE_GRPC_ENDPOINT

説明：Weaviate 接続の gRPC エンドポイントを指定します。gRPC を使用すると、バッチ操作とクエリのパフォーマンスが大幅に向上します。形式：hostname:port（プロトコルプレフィックスなし） デフォルトポート：

非セキュア：50051
セキュア (TLS)：443

例：

# Docker Compose（内部ネットワーク）
WEAVIATE_GRPC_ENDPOINT=weaviate:50051

# 外部サーバー（非セキュア）
WEAVIATE_GRPC_ENDPOINT=192.168.1.100:50051

# カスタムポートの外部サーバー
WEAVIATE_GRPC_ENDPOINT=weaviate.example.com:9090

# Weaviate Cloud（ポート 443 のセキュア/TLS）
WEAVIATE_GRPC_ENDPOINT=your-instance.weaviate.cloud:443

WEAVIATE_GRPC_ENDPOINT 値に grpc:// や http:// などのプロトコルプレフィックスを含めないでください。hostname:port のみを使用してください。

更新された環境変数

既存のすべての Weaviate 環境変数は変更なし：

WEAVIATE_ENDPOINT：Weaviate の HTTP エンドポイント（例：http://weaviate:8080）
WEAVIATE_API_KEY：認証用の API キー（有効な場合）
WEAVIATE_BATCH_SIZE：インポートのバッチサイズ（デフォルト：100）
WEAVIATE_GRPC_ENABLED：gRPC の有効化/無効化（v4 のデフォルト：true）

完全な構成例

# docker/.env または環境構成
VECTOR_STORE=weaviate

# HTTP エンドポイント（必須）
WEAVIATE_ENDPOINT=http://weaviate:8080

# 認証（Weaviate インスタンスで有効な場合）
WEAVIATE_API_KEY=your-secret-api-key

# gRPC 構成（パフォーマンス向上のため推奨）
WEAVIATE_GRPC_ENABLED=true
WEAVIATE_GRPC_ENDPOINT=weaviate:50051

# バッチインポート設定
WEAVIATE_BATCH_SIZE=100

検証手順

移行完了後、すべてが正常に動作していることを検証：

1. Weaviate 接続を確認

Weaviate がアクセス可能で正しいバージョンで実行されていることを確認：

# HTTP エンドポイントとバージョンを確認
curl http://your-weaviate-host:8080/v1/meta | jq '.version'

# 1.27.0 以降を返すはず

2. Dify 接続を検証

Dify ログを確認して Weaviate への接続が成功していることを確認：

docker compose logs api | grep -i weaviate

「No module named ‘weaviate.classes’」エラーなしで接続成功を示すメッセージを探します。

3. ナレッジベースの作成をテスト

Dify インスタンスにログイン
ナレッジベースセクションに移動
新しいナレッジベースを作成
テストドキュメント（PDF、TXT、または MD）をアップロード
インデックス作成が完了するまで待つ
ステータスが「QUEUING」→「INDEXING」→「AVAILABLE」に変わることを確認

ドキュメントが「QUEUING」ステータスで止まっている場合は、Celery worker が実行されているか確認：docker compose logs worker

4. ベクトル検索をテスト

ナレッジベース統合を含むチャットアプリケーションを作成または開く
ナレッジベースから情報を取得する質問をする
正しいスコアで関連する結果が返されることを確認
引用/ソースリンクが正しく機能することを確認

5. gRPC パフォーマンスを検証

gRPC が有効になっている場合、パフォーマンスの向上が見られるはずです：

# gRPC ポートがアクセス可能か確認
docker exec -it dify-api-1 nc -zv weaviate 50051

# ログでクエリ時間を監視
docker compose logs -f api | grep -i "query_time\|duration"

gRPC が適切に構成されている場合、ベクトル検索クエリは HTTP のみの接続と比較して 2〜5 倍高速になるはずです。

トラブルシューティング

問題：「No module named ‘weaviate.classes’」

原因：weaviate-client v4 がインストールされていないか、v3 がまだ使用されています。 解決策：

# Docker インストールの場合、正しい Dify バージョンを実行していることを確認
docker compose pull
docker compose down
docker compose up -d

# ソースインストールの場合
pip uninstall weaviate-client
pip install weaviate-client==4.17.0

問題：gRPC ポート (50051) で接続拒否

原因：ポート 50051 が公開されていない、アクセスできない、または Weaviate がリッスンしていません。 解決策：

バンドルされた Weaviate を使用する Docker Compose ユーザーの場合：ポートはコンテナ間で内部的に利用可能です。Docker 外部から接続しない限り、アクションは不要です。

外部 Weaviate の場合：

# Weaviate が 50051 でリッスンしているか確認
docker ps | grep weaviate
# 「0.0.0.0:50051->50051/tcp」を探す

# 公開されていない場合、ポートマッピングで再起動
docker run -p 8080:8080 -p 50051:50051 ...

ファイアウォールルールを確認：

# Linux
sudo ufw allow 50051/tcp

# ポートがリッスンしているか確認
netstat -tlnp | grep 50051

問題：認証エラー（401 未承認）

原因：API キーの不一致または認証構成の問題。 解決策：

Weaviate と Dify の API キーが一致することを確認：

# Weaviate 認証を確認
curl http://localhost:8080/v1/meta | jq '.authentication'

# Dify 構成を確認
docker compose exec api env | grep WEAVIATE_API_KEY

匿名アクセスを使用している場合：

# Weaviate docker-compose.yaml
weaviate:
  environment:
    AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: "true"
    AUTHENTICATION_APIKEY_ENABLED: "false"

次に、Dify 構成から WEAVIATE_API_KEY を削除します。

問題：ドキュメントが「QUEUING」ステータスで止まる

原因：Celery worker が実行されていないか、Redis に接続されていません。 解決策：

# worker が実行されているか確認
docker compose ps worker

# worker ログを確認
docker compose logs worker | tail -50

# Redis 接続を確認
docker compose exec api redis-cli -h redis -p 6379 -a difyai123456 ping
# 「PONG」を返すはず

# worker を再起動
docker compose restart worker

問題：移行後のパフォーマンス低下

原因：gRPC が有効になっていないか、正しく構成されていません。 解決策：

gRPC 構成を検証：

docker compose exec api env | grep WEAVIATE_GRPC

次のように表示されるはずです：

WEAVIATE_GRPC_ENABLED=true
WEAVIATE_GRPC_ENDPOINT=weaviate:50051

gRPC 接続をテスト：

docker exec -it dify-api-1 nc -zv weaviate 50051
# 「succeeded」を返すはず

それでも遅い場合は、Dify と Weaviate 間のネットワーク遅延を確認

問題：スキーマ移行エラー

原因：Weaviate バージョン間の互換性のないスキーマ変更またはデータの破損。 解決策：

Weaviate ログで特定のエラーメッセージを確認：
docker compose logs weaviate | tail -100
現在のスキーマをリスト：
curl http://localhost:8080/v1/schema
必要に応じて、破損したコレクションを削除（⚠️ すべてのデータが削除されます）：
# まずバックアップ！ curl -X DELETE http://localhost:8080/v1/schema/YourCollectionName
Dify を再起動してスキーマを再作成：
docker compose restart api worker

コレクションを削除するとすべてのデータが削除されます。バックアップがあり、すべてのコンテンツを再インデックスする準備ができている場合にのみ実行してください。

問題：Docker ボリュームの権限エラー

原因：Docker コンテナのユーザー ID の不一致。 解決策：

# Weaviate データディレクトリの所有権を確認
ls -la docker/volumes/weaviate/

# 権限を修正（エラーメッセージに表示された UID を使用）
sudo chown -R 1000:1000 docker/volumes/weaviate/

# サービスを再起動
docker compose restart weaviate

問題：移行スクリプト実行時の権限拒否（Dify 1.11.0+）

原因：新しい Dify バージョンでは /home/dify ディレクトリが存在しない可能性があり、uv キャッシュの作成に失敗します。 解決策：

# オプション 1: --no-cache フラグを使用（推奨）
uv run --no-cache migrate_weaviate_collections.py

# オプション 2: root ユーザーとして実行
docker compose exec -u root worker /bin/bash
uv run migrate_weaviate_collections.py

ロールバック計画

移行が失敗してロールバックする必要がある場合：

ステップ 1：サービスを停止

cd /path/to/dify/docker
docker compose down

ステップ 2：バックアップを復元

# 現在のボリュームを削除
rm -rf volumes/weaviate

# バックアップから復元
tar -xvf ../weaviate-backup-TIMESTAMP.tgz

ステップ 3：Dify バージョンを元に戻す

cd /path/to/dify
git checkout <previous-version-tag>
cd docker
docker compose pull

ステップ 4：サービスを再起動

docker compose up -d

ステップ 5：ロールバックを検証

サービスが古いバージョンで実行されていることを確認：

# バージョンを確認
docker compose exec api pip show weaviate-client
curl http://localhost:8080/v1/meta | jq '.version'

# エラーを確認
docker compose logs | grep -i error

可能であれば、常にステージング環境でロールバック手順を最初にテストしてください。大規模な移行を試みる前に、複数のバックアップコピーを保持してください。

追加リソース

公式ドキュメント

コミュニティリソース

移行ツール

まとめ

この移行により、Dify のベクトルストレージ機能に重要な改善がもたらされます：

パフォーマンスの向上：gRPC サポートにより、クエリとインポート速度が大幅に向上（2〜5 倍高速）
安定性の向上：接続処理とエラー回復の強化
セキュリティ：Weaviate 1.19.0 では利用できないセキュリティ更新とパッチへのアクセス
将来性：最新の Weaviate 機能と継続的なサポートへのアクセス

これは古いバージョンのユーザーにサーバーアップグレードを必要とする破壊的変更ですが、その利点は移行作業を大きく上回ります。ほとんどの Docker Compose ユーザーは、自動更新により 15 分以内に移行を完了できます。

このガイドでカバーされていない問題が発生した場合は、Dify GitHub Issues ページで「weaviate」および「migration」ラベルを付けて報告してください。

最終更新日 2026年6月23日

ストレージとマイグレーション

​概要

​影響を受けるユーザー

​破壊的変更

​クライアント v4 の要件

​なぜアップグレードするのか？

​バージョン互換性マトリックス

​前提条件

​移行パス

​パスを選択

​パス A：バックアップを使用した移行（1.19 から）

​前提条件

​ステップ A1：Weaviate 1.19 でバックアップモジュールを有効化

​ステップ A2：バックアップを作成

​ステップ A3：Weaviate 1.27+ にアップグレード

​ステップ A4：孤立した LSM データを修正（存在する場合）

​ステップ A5：スキーマを移行

​パス B：直接リカバリ（すでに 1.27+ の場合）

​前提条件

​ステップ B1：孤立した LSM データを修復

​ステップ B2：スキーマ移行を実行

​ステップ B3：Dify で検証

​レガシーバージョンのデータ移行

​自動移行

​手動移行（自動移行が失敗した場合）

​1. 旧バージョンからデータをエクスポート

​2. 新しいバージョンにデータをインポート

​構成の変更

​新しい環境変数

​WEAVIATE_GRPC_ENDPOINT

​更新された環境変数

​完全な構成例

​検証手順

​1. Weaviate 接続を確認

​2. Dify 接続を検証

​3. ナレッジベースの作成をテスト

​4. ベクトル検索をテスト

​5. gRPC パフォーマンスを検証

​トラブルシューティング

​問題：「No module named ‘weaviate.classes’」

​問題：gRPC ポート (50051) で接続拒否

​問題：認証エラー（401 未承認）

​問題：ドキュメントが「QUEUING」ステータスで止まる

​問題：移行後のパフォーマンス低下

​問題：スキーマ移行エラー

​問題：Docker ボリュームの権限エラー

​問題：移行スクリプト実行時の権限拒否（Dify 1.11.0+）

​ロールバック計画

​ステップ 1：サービスを停止

​ステップ 2：バックアップを復元

​ステップ 3：Dify バージョンを元に戻す

​ステップ 4：サービスを再起動

​ステップ 5：ロールバックを検証

​追加リソース

​公式ドキュメント

​コミュニティリソース

​移行ツール

​まとめ

概要

影響を受けるユーザー

破壊的変更

クライアント v4 の要件

なぜアップグレードするのか？

バージョン互換性マトリックス

前提条件

移行パス

パスを選択

パス A：バックアップを使用した移行（1.19 から）

前提条件

ステップ A1：Weaviate 1.19 でバックアップモジュールを有効化

ステップ A2：バックアップを作成

ステップ A3：Weaviate 1.27+ にアップグレード

ステップ A4：孤立した LSM データを修正（存在する場合）

ステップ A5：スキーマを移行

パス B：直接リカバリ（すでに 1.27+ の場合）

前提条件

ステップ B1：孤立した LSM データを修復

ステップ B2：スキーマ移行を実行

ステップ B3：Dify で検証

レガシーバージョンのデータ移行

自動移行

手動移行（自動移行が失敗した場合）

1. 旧バージョンからデータをエクスポート

2. 新しいバージョンにデータをインポート

構成の変更

新しい環境変数

WEAVIATE_GRPC_ENDPOINT

更新された環境変数

完全な構成例

検証手順

1. Weaviate 接続を確認

2. Dify 接続を検証

3. ナレッジベースの作成をテスト

4. ベクトル検索をテスト

5. gRPC パフォーマンスを検証

トラブルシューティング

問題：「No module named ‘weaviate.classes’」

問題：gRPC ポート (50051) で接続拒否

問題：認証エラー（401 未承認）

問題：ドキュメントが「QUEUING」ステータスで止まる

問題：移行後のパフォーマンス低下

問題：スキーマ移行エラー

問題：Docker ボリュームの権限エラー

問題：移行スクリプト実行時の権限拒否（Dify 1.11.0+）

ロールバック計画

ステップ 1：サービスを停止

ステップ 2：バックアップを復元

ステップ 3：Dify バージョンを元に戻す

ステップ 4：サービスを再起動

ステップ 5：ロールバックを検証

追加リソース

公式ドキュメント

コミュニティリソース

移行ツール

まとめ