From d0c4170710499da3b9b62d3df9391fb2e61be0a7 Mon Sep 17 00:00:00 2001 From: quicksand Date: Tue, 4 Nov 2025 11:07:39 +0800 Subject: [PATCH] docs: add Chinese translation for Weaviate v4 migration guide (#492) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude --- docs.json | 3 +- .../migration/weaviate-v4-migration.mdx | 708 ++++++++++++++++++ 2 files changed, 710 insertions(+), 1 deletion(-) create mode 100644 zh-hans/development/migration/weaviate-v4-migration.mdx diff --git a/docs.json b/docs.json index 4c943ec3..025357d0 100644 --- a/docs.json +++ b/docs.json @@ -1120,7 +1120,8 @@ { "group": "迁移", "pages": [ - "zh-hans/development/migration/migrate-to-v1" + "zh-hans/development/migration/migrate-to-v1", + "zh-hans/development/migration/weaviate-v4-migration" ] } ] diff --git a/zh-hans/development/migration/weaviate-v4-migration.mdx b/zh-hans/development/migration/weaviate-v4-migration.mdx new file mode 100644 index 00000000..1ce265bd --- /dev/null +++ b/zh-hans/development/migration/weaviate-v4-migration.mdx @@ -0,0 +1,708 @@ +--- +title: Weaviate 迁移指南：升级到客户端 v4 和服务器 1.27+ +--- + +> 本指南说明如何从 Weaviate 客户端 v3 迁移到 v4.17.0,并将 Weaviate 服务器从 1.19.0 版本升级到 1.27.0 或更高版本。此迁移适用于包含 weaviate-client v4 升级的 Dify 版本。 + +## 概述 + +从即将发布的 Dify 版本开始,weaviate-client 已从 v3 升级到 v4.17.0。此升级带来了显著的性能改进和更好的稳定性,但需要 **Weaviate 服务器版本 1.27.0 或更高**。 + + +**重大变更:**新的 weaviate-client v4 与 1.27.0 以下的 Weaviate 服务器版本不向后兼容。如果您正在运行 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 引入了几个重大变更: + +1. **最低服务器版本:**需要 Weaviate 服务器 1.27.0 或更高版本 +2. **API 变更:**新的导入结构(`weaviate.classes` 而不是 `weaviate.client`) +3. **gRPC 支持:**默认使用端口 50051 上的 gRPC 以提高性能 +4. **身份验证变更:**更新了身份验证方法和配置 + +### 为什么要升级? + +- **性能:**通过 gRPC(50051)显著加快查询和导入操作 +- **稳定性:**更好的连接处理和错误恢复 +- **未来兼容性:**访问最新的 Weaviate 功能和持续支持 +- **安全性:**Weaviate 1.19.0 已经发布一年多,不再接收安全更新 + +## 版本兼容性矩阵 + +| 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.27.0+ 可以获得性能、稳定性和功能方面的众多改进。 + + +## 先决条件 + +在开始迁移之前,完成以下步骤: + +1. **检查您当前的 Weaviate 版本** + ```bash + curl http://localhost:8080/v1/meta + ``` + 在响应中查找 `version` 字段。 + +2. **备份您的数据** + - 创建 Weaviate 数据的完整备份 + - 如果使用 Docker Compose,备份您的 Docker 卷 + - 记录您当前的配置设置 + +3. **检查系统要求** + - 确保有足够的磁盘空间用于数据库迁移 + - 验证 Dify 和 Weaviate 之间的网络连接 + - 如果使用外部 Weaviate,确认 gRPC 端口(50051)可访问 + +4. **计划停机时间** + - 迁移需要服务停机时间 + - 如果在生产环境中运行,请通知用户 + - 在低流量时段安排迁移 + +## 迁移路径 + +选择与您的部署设置匹配的迁移路径: + +### 路径 A:Docker Compose 用户(推荐) + +对于通过 Docker Compose 运行 Dify 并使用捆绑的 Weaviate 实例的用户,这是最简单的路径。 + + +如果您使用 Dify 的标准 Docker Compose 设置,升级 Dify 时 Weaviate 版本会自动更新。无需手动配置。 + + +#### 步骤 1:备份您的数据 + +导航到您的 Dify 项目目录并备份 Docker 卷: + +```bash +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 版本: + +```bash +cd /path/to/dify +git fetch origin +git checkout # 查看发布说明以获取正确版本 +cd docker +docker compose pull +docker compose up -d +``` + +更新的 Docker Compose 配置包括: +- Weaviate 服务器 1.27.0+ 镜像 +- weaviate-client v4.17.0(在 Dify 容器中自动安装) +- 正确的 gRPC 端口配置(50051) + +#### 步骤 3:监控启动 + +观察日志以确保服务正确启动: + +```bash +# 观察 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 创建完整备份: + +```bash +# 创建备份 +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 备份文档](https://weaviate.io/developers/weaviate/configuration/backups)。 + + +#### 步骤 2:停止您的 Weaviate 实例 + +```bash +# 对于 Docker 用户 +docker stop weaviate + +# 对于 systemd 用户 +sudo systemctl stop weaviate + +# 对于 Kubernetes 用户 +kubectl scale deployment weaviate --replicas=0 +``` + +#### 步骤 3:升级 Weaviate 服务器 + +**对于 Docker:** + +```bash +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 values 或 manifest: + +```yaml +image: + registry: cr.weaviate.io + repository: semitechnologies/weaviate + tag: 1.27.0 +``` + +然后应用: + +```bash +helm upgrade weaviate weaviate/weaviate -f values.yaml +# 或 +kubectl apply -f weaviate-deployment.yaml +``` + +**对于二进制安装:** + +从 [Weaviate 发布页面](https://github.com/weaviate/weaviate/releases)下载并安装新版本。 + +#### 步骤 4:验证 Weaviate 升级 + +检查 Weaviate 是否运行正确版本: + +```bash +curl http://your-weaviate-host:8080/v1/meta | jq '.version' +``` + +您应该看到 1.27.0 或更高版本。 + +#### 步骤 5:更新 Dify 配置 + +更新您的 Dify 环境变量以配置外部 Weaviate 连接: + +```bash +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 + +```bash +cd /path/to/dify +git fetch origin +git checkout +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 迁移数据: + +1. 停止 Weaviate 1.19.0 +2. 使用相同的数据目录启动 Weaviate 1.27.0 +3. Weaviate 将检测旧格式并自动迁移 +4. 监控日志以获取迁移进度和任何错误 + +### 手动迁移(如果自动失败) + +如果自动迁移失败,使用 Weaviate 的导出/导入工具: + +#### 1. 从旧版本导出数据 + +使用游标 API 或备份功能导出所有数据。对于大型数据集,使用 Weaviate 的备份 API: + +```bash +# 使用备份 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 后,恢复备份: + +```bash +curl -X POST "http://localhost:8080/v1/backups/filesystem/pre-migration-backup/restore" \ + -H "Content-Type: application/json" +``` + + +有关全面的迁移指导,特别是对于复杂的模式或大型数据集,请参阅官方 [Weaviate 迁移指南](https://weaviate.io/developers/weaviate/installation/migration)。 + + +## 配置变更 + +### 新环境变量 + +在包含 weaviate-client v4 的 Dify 版本中,提供以下新环境变量: + +#### WEAVIATE_GRPC_ENDPOINT + +**描述:**指定 Weaviate 连接的 gRPC 端点。使用 gRPC 可显著提高批量操作和查询的性能。 + +**格式:**`hostname:port`(无协议前缀) + +**默认端口:** +- 不安全:50051 +- 安全(TLS):443 + +**示例:** +```bash +# 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) + +### 完整配置示例 + +```bash +# 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 可访问并运行正确版本: + +```bash +# 检查 HTTP 端点和版本 +curl http://your-weaviate-host:8080/v1/meta | jq '.version' + +# 应该返回 1.27.0 或更高版本 +``` + +### 2. 验证 Dify 连接 + +检查 Dify 日志以确认成功连接 Weaviate: + +```bash +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"变化 + + +如果文档停留在"QUEUING"状态,请检查 Celery worker 是否正在运行:`docker compose logs worker` + + +### 4. 测试向量搜索 + +1. 创建或打开一个集成了知识库的聊天应用 +2. 提出一个应该从您的知识库中检索信息的问题 +3. 验证返回了具有正确分数的相关结果 +4. 检查引用/来源链接是否正常工作 + +### 5. 验证 gRPC 性能 + +如果启用了 gRPC,您应该看到性能提升: + +```bash +# 检查 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。 + +**解决方案:** +```bash +# 对于 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 未在其上监听。 + +**解决方案:** + +1. **对于使用捆绑 Weaviate 的 Docker Compose 用户:** + 端口在容器之间内部可用。除非从 Docker 外部连接,否则无需操作。 + +2. **对于外部 Weaviate:** + ```bash + # 检查 Weaviate 是否在 50051 上监听 + docker ps | grep weaviate + # 查找 "0.0.0.0:50051->50051/tcp" + + # 如果未暴露,请使用端口映射重启 + docker run -p 8080:8080 -p 50051:50051 ... + ``` + +3. **检查防火墙规则:** + ```bash + # Linux + sudo ufw allow 50051/tcp + + # 检查端口是否在监听 + netstat -tlnp | grep 50051 + ``` + +### 问题:身份验证错误(401 未授权) + +**原因:**API 密钥不匹配或身份验证配置问题。 + +**解决方案:** + +1. 验证 Weaviate 和 Dify 中的 API 密钥匹配: + ```bash + # 检查 Weaviate 身份验证 + curl http://localhost:8080/v1/meta | jq '.authentication' + + # 检查 Dify 配置 + docker compose exec api env | grep WEAVIATE_API_KEY + ``` + +2. 如果使用匿名访问: + ```yaml + # Weaviate docker-compose.yaml + weaviate: + environment: + AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true' + AUTHENTICATION_APIKEY_ENABLED: 'false' + ``` + + 然后从 Dify 配置中删除 `WEAVIATE_API_KEY`。 + +### 问题:文档停留在"QUEUING"状态 + +**原因:**Celery worker 未运行或未连接到 Redis。 + +**解决方案:** + +```bash +# 检查 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 配置: + ```bash + docker compose exec api env | grep WEAVIATE_GRPC + ``` + + 应该显示: + ``` + WEAVIATE_GRPC_ENABLED=true + WEAVIATE_GRPC_ENDPOINT=weaviate:50051 + ``` + +2. 测试 gRPC 连接: + ```bash + docker exec -it dify-api-1 nc -zv weaviate 50051 + # 应该返回 "succeeded" + ``` + +3. 如果仍然缓慢,检查 Dify 和 Weaviate 之间的网络延迟 + +### 问题:模式迁移错误 + +**原因:**Weaviate 版本之间不兼容的模式更改或数据损坏。 + +**解决方案:** + +1. 检查 Weaviate 日志以获取特定错误消息: + ```bash + docker compose logs weaviate | tail -100 + ``` + +2. 列出当前模式: + ```bash + curl http://localhost:8080/v1/schema + ``` + +3. 如有必要,删除损坏的集合(⚠️ 这会删除所有数据): + ```bash + # 先备份! + curl -X DELETE http://localhost:8080/v1/schema/YourCollectionName + ``` + +4. 重启 Dify 以重新创建模式: + ```bash + docker compose restart api worker + ``` + + +删除集合会移除所有数据。仅在您有备份并准备重新索引所有内容时才这样做。 + + +### 问题:Docker 卷权限错误 + +**原因:**Docker 容器中的用户 ID 不匹配。 + +**解决方案:** +```bash +# 检查 Weaviate 数据目录的所有权 +ls -la docker/volumes/weaviate/ + +# 修复权限(使用错误消息中显示的 UID) +sudo chown -R 1000:1000 docker/volumes/weaviate/ + +# 重启服务 +docker compose restart weaviate +``` + +## 回滚计划 + +如果迁移失败需要回滚: + +### 步骤 1:停止服务 + +```bash +cd /path/to/dify/docker +docker compose down +``` + +### 步骤 2:恢复备份 + +```bash +# 删除当前卷 +rm -rf volumes/weaviate + +# 从备份恢复 +tar -xvf ../weaviate-backup-TIMESTAMP.tgz +``` + +### 步骤 3:恢复 Dify 版本 + +```bash +cd /path/to/dify +git checkout +cd docker +docker compose pull +``` + +### 步骤 4:重启服务 + +```bash +docker compose up -d +``` + +### 步骤 5:验证回滚 + +检查服务是否使用旧版本运行: + +```bash +# 检查版本 +docker compose exec api pip show weaviate-client +curl http://localhost:8080/v1/meta | jq '.version' + +# 检查错误 +docker compose logs | grep -i error +``` + + +如果可能,请始终先在测试环境中测试回滚过程。在尝试重大迁移之前,维护多个备份副本。 + + +## 其他资源 + +### 官方文档 + +- [Weaviate 迁移指南](https://weaviate.io/developers/weaviate/installation/migration) +- [Weaviate v4 客户端文档](https://weaviate.io/developers/weaviate/client-libraries/python) +- [Weaviate 备份和恢复](https://weaviate.io/developers/weaviate/configuration/backups) +- [Dify 自托管指南](/zh-hans/getting-started/install-self-hosted/docker-compose) +- [Dify 环境变量](/zh-hans/getting-started/install-self-hosted/environments) + +### 社区资源 + +- [Dify GitHub 仓库](https://github.com/langgenius/dify) +- [Dify GitHub Issues - Weaviate](https://github.com/langgenius/dify/issues?q=is%3Aissue+weaviate) +- [Weaviate 社区论坛](https://forum.weaviate.io/) +- [Dify Discord 社区](https://discord.gg/dify) + +### 迁移工具 + +- [Weaviate Python Client v4](https://github.com/weaviate/weaviate-python-client) +- [Weaviate 备份工具](https://github.com/weaviate/weaviate/tree/main/tools) + +## 总结 + +此迁移为 Dify 的向量存储功能带来了重要改进: + +✅ **更好的性能:**gRPC 支持显著提高查询和导入速度(快 2-5 倍) + +✅ **改进的稳定性:**增强的连接处理和错误恢复 + +✅ **安全性:**访问 Weaviate 1.19.0 中不可用的安全更新和补丁 + +✅ **面向未来:**访问最新的 Weaviate 功能和持续支持 + +虽然这是一个需要为旧版本用户升级服务器的重大变更,但好处远远超过了迁移工作。大多数 Docker Compose 用户可以通过自动更新在 15 分钟内完成迁移。 + + +如果您遇到本指南未涵盖的任何问题,请在 [Dify GitHub Issues 页面](https://github.com/langgenius/dify/issues)上报告,并标记"weaviate"和"migration"。 + + +{/* +贡献部分 +不要编辑此部分! +它将由脚本自动生成。 +*/} + +--- + +[编辑此页面](https://github.com/langgenius/dify-docs/edit/main/zh-hans/development/migration/weaviate-v4-migration.mdx) | [报告问题](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml) \ No newline at end of file