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

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

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

概要

今後のリリースで、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.32.11 までテスト済み）

*weaviate-client v4 を含む正確な Dify バージョンは異なる場合があります。特定のバージョンのリリースノートを確認してください。この移行は、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) がアクセス可能であることを確認
ダウンタイムを計画
- 移行にはサービスのダウンタイムが必要
- 本番環境で実行している場合はユーザーに通知
- トラフィックの少ない時間帯に移行をスケジュール

移行パス

デプロイメント設定に一致する移行パスを選択してください：

パス A：Docker Compose ユーザー（推奨）

これは、Docker Compose を介して Dify を実行し、バンドルされた Weaviate インスタンスを使用しているユーザーにとって最も簡単なパスです。

Dify の標準 Docker Compose セットアップを使用している場合、Dify をアップグレードすると Weaviate バージョンが自動的に更新されます。手動構成は不要です。

ステップ 1：データをバックアップ

Dify プロジェクトディレクトリに移動し、Docker ボリュームをバックアップします：

cd /path/to/dify/docker
docker compose down
tar -cvf ../weaviate-backup-$(date +%s).tgz volumes/weaviate

バックアップファイルをプロジェクトディレクトリ外の安全な場所に保存してください。移行が失敗してロールバックする必要がある場合に必要になります。

ステップ 2：Dify を更新

weaviate-client v4 と Weaviate 1.27.0+ を含む最新の Dify バージョンをプル：

cd /path/to/dify
git fetch origin
git checkout <version-with-weaviate-v4>  # 正しいバージョンはリリースノートを確認
cd docker
docker compose pull
docker compose up -d

更新された Docker Compose 構成には以下が含まれます：

Weaviate サーバー 1.27.0+ イメージ
weaviate-client v4.17.0（Dify コンテナに自動インストール）
適切な gRPC ポート構成 (50051)

ステップ 3：起動を監視

ログを確認してサービスが正しく起動することを確認：

# Weaviate の起動を監視
docker compose logs -f weaviate

# Dify API の起動を監視
docker compose logs -f api

Weaviate が「ready to serve requests」を表示し、Dify API が正常に接続するまで待ちます。

ステップ 4：移行を検証

以下の検証手順セクションを参照してください。

パス B：外部/自己ホスト Weaviate

別のサーバー、マネージドインスタンス、または Weaviate Cloud で Weaviate を実行しているユーザー向け。

このパスは、Dify とは別に独自の Weaviate インスタンスを管理しているユーザー向けです。Docker Compose を介して Dify にバンドルされた Weaviate を使用している場合は、代わりにパス A を使用してください。

ステップ 1：Weaviate データをバックアップ

Weaviate のバックアップ API を使用して完全バックアップを作成：

# バックアップを作成
curl -X POST \
  "http://your-weaviate-host:8080/v1/backups/filesystem" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "dify-backup-'$(date +%s)'",
    "include": ["*"]
  }'

# バックアップステータスを確認
curl "http://your-weaviate-host:8080/v1/backups/filesystem/{backup-id}"

詳細なバックアップ手順については、Weaviate バックアップドキュメントを参照してください。

ステップ 2：Weaviate インスタンスを停止

# Docker ユーザーの場合
docker stop weaviate

# systemd ユーザーの場合
sudo systemctl stop weaviate

# Kubernetes ユーザーの場合
kubectl scale deployment weaviate --replicas=0

ステップ 3：Weaviate サーバーをアップグレード

Docker の場合：

docker pull cr.weaviate.io/semitechnologies/weaviate:1.27.0
docker run -d \
  --name weaviate \
  -p 8080:8080 \
  -p 50051:50051 \
  -v /path/to/data:/var/lib/weaviate \
  -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=false \
  -e AUTHENTICATION_APIKEY_ENABLED=true \
  -e AUTHENTICATION_APIKEY_ALLOWED_KEYS=your-secret-key \
  -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
  -e QUERY_DEFAULTS_LIMIT=20 \
  -e DEFAULT_VECTORIZER_MODULE=none \
  cr.weaviate.io/semitechnologies/weaviate:1.27.0

Kubernetes の場合： Helm 値またはマニフェストを更新：

image:
  registry: cr.weaviate.io
  repository: semitechnologies/weaviate
  tag: 1.27.0

次に適用：

helm upgrade weaviate weaviate/weaviate -f values.yaml
# または
kubectl apply -f weaviate-deployment.yaml

バイナリインストールの場合： Weaviate リリースページから新しいバージョンをダウンロードしてインストールします。

ステップ 4：Weaviate アップグレードを検証

Weaviate が正しいバージョンで実行されていることを確認：

curl http://your-weaviate-host:8080/v1/meta | jq '.version'

バージョン 1.27.0 以降が表示されるはずです。

ステップ 5：Dify 構成を更新

外部 Weaviate 接続を構成するために Dify 環境変数を更新：

VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://your-weaviate-host:8080
WEAVIATE_API_KEY=your-api-key
WEAVIATE_GRPC_ENABLED=true
WEAVIATE_GRPC_ENDPOINT=your-weaviate-host:50051

WEAVIATE_GRPC_ENDPOINT は、プロトコルプレフィックスなしの hostname:port 形式である必要があります（grpc:// または http:// なし）。

ステップ 6：Dify を更新

cd /path/to/dify
git fetch origin
git checkout <version-with-weaviate-v4>
cd docker
docker compose pull
docker compose up -d

ステップ 7：移行を検証

以下の検証手順セクションを参照してください。

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

Weaviate 1.19.0 から 1.27.0+ にアップグレードする場合、バージョンギャップが大きくなります。通常、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

ロールバック計画

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

ステップ 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」ラベルを付けて報告してください。

クイックスタート

高度なデプロイ

設定

プラットフォームガイド

トラブルシューティング

​概要

​影響を受けるユーザー

​破壊的変更

​クライアント v4 の要件

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

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

​前提条件

​移行パス

​パス A：Docker Compose ユーザー（推奨）

​ステップ 1：データをバックアップ

​ステップ 2：Dify を更新

​ステップ 3：起動を監視

​ステップ 4：移行を検証

​パス B：外部/自己ホスト Weaviate

​ステップ 1：Weaviate データをバックアップ

​ステップ 2：Weaviate インスタンスを停止

​ステップ 3：Weaviate サーバーをアップグレード

​ステップ 4：Weaviate アップグレードを検証

​ステップ 5：Dify 構成を更新

​ステップ 6：Dify を更新

​ステップ 7：移行を検証

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

​自動移行

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

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

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

​構成の変更

​新しい環境変数

​WEAVIATE_GRPC_ENDPOINT

​更新された環境変数

​完全な構成例

​検証手順

​1. Weaviate 接続を確認

​2. Dify 接続を検証

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

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

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

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

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

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

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

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

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

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

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

​ロールバック計画

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

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

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

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

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

​追加リソース

​公式ドキュメント

​コミュニティリソース

​移行ツール

​まとめ

概要

影響を受けるユーザー

破壊的変更

クライアント v4 の要件

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

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

前提条件

移行パス

パス A：Docker Compose ユーザー（推奨）

ステップ 1：データをバックアップ

ステップ 2：Dify を更新

ステップ 3：起動を監視

ステップ 4：移行を検証

パス B：外部/自己ホスト Weaviate

ステップ 1：Weaviate データをバックアップ

ステップ 2：Weaviate インスタンスを停止

ステップ 3：Weaviate サーバーをアップグレード

ステップ 4：Weaviate アップグレードを検証

ステップ 5：Dify 構成を更新

ステップ 6：Dify を更新

ステップ 7：移行を検証

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

自動移行

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

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

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

構成の変更

新しい環境変数

WEAVIATE_GRPC_ENDPOINT

更新された環境変数

完全な構成例

検証手順

1. Weaviate 接続を確認

2. Dify 接続を検証

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

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

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

トラブルシューティング

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

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

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

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

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

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

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

ロールバック計画

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

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

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

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

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

追加リソース

公式ドキュメント

コミュニティリソース

移行ツール

まとめ