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

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

このガイドでは、Weaviate クライアント v3 から weaviate-client v4（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 以降が必要です。

影響を受けるユーザー#

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

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

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

• クラウドホスト Weaviate ユーザー（Weaviate Cloud がサーバーバージョンを管理）

破壊的変更#

クライアント v4 の要件#

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

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

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

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

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

前提条件#

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

1. 現在の Weaviate バージョンを確認

   curl http://localhost:8080/v1/meta

   レスポンスで version フィールドを探します。

2. データをバックアップ

   • Weaviate データの完全バックアップを作成
   • Docker Compose を使用している場合は、Docker ボリュームをバックアップ
   • 現在の構成設定を文書化

3. システム要件を確認

   • データベース移行のための十分なディスク容量を確保
   • Dify と Weaviate 間のネットワーク接続を検証
   • 外部 Weaviate を使用している場合、gRPC ポート (50051) がアクセス可能であることを確認

4. ダウンタイムを計画

   • 移行にはサービスのダウンタイムが必要
   • 本番環境で実行している場合はユーザーに通知
   • トラフィックの少ない時間帯に移行をスケジュール

移行パス#

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

パスを選択#

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

パス 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 dockerdocker compose downdocker compose --profile up -dsleep 10

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

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

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

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

   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"]  }'

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

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

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

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

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

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

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

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

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

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

   cd dockerdocker compose downdocker compose up -dsleep 20

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

孤立した LSM データは、ホストからまたはコンテナ内で修正できます：

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

cd docker/volumes/weaviatefor 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"donecd ../../docker compose restart weaviatesleep 15

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

cd /path/to/dify/dockerdocker compose exec -it weaviate /bin/sh# コンテナ内cd /var/lib/weaviatefor 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"doneexit# Weaviate を再起動docker compose restart weaviatesleep 15

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

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

   cd /path/to/difypython3 -m venv weaviate_migration_envsource weaviate_migration_env/bin/activatepip install weaviate-client requests

2. 移行スクリプトを実行：ローカルまたは 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/dockerdocker compose exec -it worker /bin/bash# 移行スクリプトを実行（Dify 1.11.0+ の場合は --no-cache を使用）uv run --no-cache /app/api/storage/migrate_weaviate_collections.py# コンテナを終了exit
   Info

   移行スクリプトは構成に環境変数を使用するため、Docker コンテナ内での実行に適しています。Dify 1.11.0+ で uv の権限エラーが発生した場合は、代わりに uv run --no-cache を使用してください。

3. Dify サービスを再起動：

   cd dockerdocker compose restart api worker worker_beatsleep 15

4. UI で検証：Dify を開き、移行されたナレッジベースに対して取得をテストします。

   Warning

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

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

前提条件#

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

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

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

cd /path/to/dify/dockerdocker compose stop weaviate# オプション A: ホストから（ボリュームがマウントされている場合）cd volumes/weaviatefor 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/weaviatefor 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 weaviatesleep 15

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

curl -s -H "Authorization: Bearer <WEAVIATE_API_KEY>" \  "http://localhost:8080/v1/schema" | python3 -c "import sys, jsonfor 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/dockerdocker compose exec -it worker /bin/bash# 移行スクリプトを実行uv run --no-cache /app/api/storage/migrate_weaviate_collections.py# 終了してサービスを再起動exitdocker compose restart api worker worker_beat

ステップ B3：Dify で検証#

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

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

自動移行#

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

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

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

自動移行が失敗した場合は、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-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 環境変数は変更なし：

• 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=trueWEAVIATE_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. ナレッジベースの作成をテスト#

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

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

1. ナレッジベース統合を含むチャットアプリケーションを作成または開く
2. ナレッジベースから情報を取得する質問をする
3. 正しいスコアで関連する結果が返されることを確認
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"

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

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

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

解決策：

Docker インストールの場合は、正しい Dify バージョンを実行していることを確認します。docker ディレクトリで実行してください：

docker compose pulldocker compose downdocker compose up -d

ソースインストールの場合は、チェックアウトが固定しているクライアントバージョンをインストールします。docker ではなくリポジトリのルートで実行してください：

cd /path/to/difyuv sync --project api --group vdb-weaviate

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

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

解決策：

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

2. 外部 Weaviate の場合：

   # Weaviate が 50051 でリッスンしているか確認docker ps | grep weaviate# 「0.0.0.0:50051->50051/tcp」を探す# 公開されていない場合、ポートマッピングで再起動docker run -p 8080:8080 -p 50051:50051 ...

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

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

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

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

解決策：

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

   # Weaviate 認証を確認curl http://localhost:8080/v1/meta | jq '.authentication'# Dify 構成を確認docker compose exec api env | grep WEAVIATE_API_KEY

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

   # Weaviate docker-compose.yamlweaviate:  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 が有効になっていないか、正しく構成されていません。

解決策：

1. gRPC 構成を検証：

   docker compose exec api env | grep WEAVIATE_GRPC

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

   WEAVIATE_GRPC_ENABLED=trueWEAVIATE_GRPC_ENDPOINT=weaviate:50051

2. gRPC 接続をテスト：

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

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

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

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

解決策：

1. Weaviate ログで特定のエラーメッセージを確認：

   docker compose logs weaviate | tail -100

2. 現在のスキーマをリスト：

   curl http://localhost:8080/v1/schema

3. 必要に応じて、破損したコレクションを削除（⚠️ すべてのデータが削除されます）：

   # まずバックアップ！curl -X DELETE http://localhost:8080/v1/schema/YourCollectionName

4. 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/bashuv run migrate_weaviate_collections.py

ロールバック計画#

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

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

cd /path/to/dify/dockerdocker compose down

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

# 現在のボリュームを削除rm -rf volumes/weaviate# バックアップから復元tar -xvf ../weaviate-backup-TIMESTAMP.tgz

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

cd /path/to/difygit checkout <previous-version-tag>cd dockerdocker compose pull

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

docker compose up -d

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

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

# バージョンを確認docker compose exec api pip show weaviate-clientcurl http://localhost:8080/v1/meta | jq '.version'# エラーを確認docker compose logs | grep -i error

追加リソース#

公式ドキュメント#

• Weaviate 移行ガイド
• Weaviate v4 クライアントドキュメント
• Weaviate バックアップと復元
• Dify セルフホスティングガイド
• Dify 環境変数

コミュニティリソース#

• Dify GitHub リポジトリ
• Dify GitHub Issues - Weaviate
• Weaviate コミュニティフォーラム

移行ツール#

• Weaviate Python Client v4
• Weaviate バックアップツール

まとめ#

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

• パフォーマンスの向上：gRPC サポートにより、クエリとインポート速度が大幅に向上（2〜5 倍高速）

• 安定性の向上：接続処理とエラー回復の強化

• セキュリティ：Weaviate 1.19.0 では利用できないセキュリティ更新とパッチへのアクセス

• 将来性：最新の Weaviate 機能と継続的なサポートへのアクセス

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