centersl/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-03-26 13:18:34 +07:00
Code Issues Packages Projects Releases Wiki Activity

docs: add Chinese translation for Weaviate v4 migration guide (#492)

Browse Source 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
quicksand
2025-11-04 11:07:39 +08:00
committed by GitHub
parent 9b6203f3e5
commit d0c4170710
2 changed files with 710 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs.json
View File

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

708
zh-hans/development/migration/weaviate-v4-migration.mdx Normal file
View File

@@ -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 或更高**。
<Warning>
**重大变更:**新的 weaviate-client v4 与 1.27.0 以下的 Weaviate 服务器版本不向后兼容。如果您正在运行 1.19.0 或更旧版本的自托管 Weaviate 实例,则必须在升级 Dify 之前升级您的 Weaviate 服务器。
</Warning>
### 谁会受到影响?
此迁移会影响:
- 运行低于 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) |
<Info>
*具体包含 weaviate-client v4 的 Dify 版本可能会有所不同。请查看您特定版本的发布说明。此迁移适用于任何使用 weaviate-client v4.17.0 或更高版本的 Dify 版本。
</Info>
<Info>
Weaviate 服务器版本 1.19.0 是一年多前发布的,现在已经过时。升级到 1.27.0+ 可以获得性能、稳定性和功能方面的众多改进。
</Info>
## 先决条件
在开始迁移之前,完成以下步骤:
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 实例的用户,这是最简单的路径。
<Info>
如果您使用 Dify 的标准 Docker Compose 设置,升级 Dify 时 Weaviate 版本会自动更新。无需手动配置。
</Info>
#### 步骤 1:备份您的数据
导航到您的 Dify 项目目录并备份 Docker 卷:
```bash
cd /path/to/dify/docker
docker compose down
tar -cvf ../weaviate-backup-$(date +%s).tgz volumes/weaviate
```
<Info>
将备份文件存储在项目目录之外的安全位置。如果迁移失败需要回滚,您将需要它。
</Info>
#### 步骤 2:更新 Dify
拉取包含 weaviate-client v4 和 Weaviate 1.27.0+ 的最新 Dify 版本:
```bash
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:监控启动
观察日志以确保服务正确启动:
```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 的用户。
<Warning>
此路径适用于独立于 Dify 管理自己的 Weaviate 实例的用户。如果您通过 Docker Compose 使用 Dify 捆绑的 Weaviate,请改用路径 A。
</Warning>
#### 步骤 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}"
```
<Info>
有关详细的备份说明,请参阅 [Weaviate 备份文档](https://weaviate.io/developers/weaviate/configuration/backups)。
</Info>
#### 步骤 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
```
<Info>
`WEAVIATE_GRPC_ENDPOINT` 应该采用 `hostname:port` 格式,不带任何协议前缀(没有 `grpc://` 或 `http://`)。
</Info>
#### 步骤 6:更新 Dify
```bash
cd /path/to/dify
git fetch origin
git checkout <version-with-weaviate-v4>
cd docker
docker compose pull
docker compose up -d
```
#### 步骤 7:验证迁移
请参阅下面的[验证步骤](#验证步骤)部分。
## 旧版本的数据迁移
<Warning>
如果从 Weaviate 1.19.0 升级到 1.27.0+,版本差距很大。虽然 Weaviate 通常会自动处理模式迁移,但您应该仔细监控升级并准备好备份。
</Warning>
### 自动迁移
在大多数情况下,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"
```
<Info>
有关全面的迁移指导,特别是对于复杂的模式或大型数据集,请参阅官方 [Weaviate 迁移指南](https://weaviate.io/developers/weaviate/installation/migration)。
</Info>
## 配置变更
### 新环境变量
在包含 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
```
<Warning>
不要在 WEAVIATE_GRPC_ENDPOINT 值中包含协议前缀,如 `grpc://` 或 `http://`。仅使用 `hostname:port`。
</Warning>
### 更新的环境变量
所有现有的 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"变化
<Info>
如果文档停留在"QUEUING"状态,请检查 Celery worker 是否正在运行:`docker compose logs worker`
</Info>
### 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"
```
<Info>
正确配置 gRPC 后,向量搜索查询应该比仅 HTTP 连接快 2-5 倍。
</Info>
## 故障排除
### 问题:"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
```
<Warning>
删除集合会移除所有数据。仅在您有备份并准备重新索引所有内容时才这样做。
</Warning>
### 问题: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 <previous-version-tag>
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
```
<Info>
如果可能,请始终先在测试环境中测试回滚过程。在尝试重大迁移之前,维护多个备份副本。
</Info>
## 其他资源
### 官方文档
- [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 分钟内完成迁移。
<Info>
如果您遇到本指南未涵盖的任何问题,请在 [Dify GitHub Issues 页面](https://github.com/langgenius/dify/issues)上报告,并标记"weaviate"和"migration"。
</Info>
{/*
贡献部分
不要编辑此部分!
它将由脚本自动生成。
*/}
---
[编辑此页面](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)