ngskcloud
/
gcgj-dify-1.7.0
17
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add comprehensive user guide for Clickzetta vector database integration

Browse Source 
- Add USER_GUIDE.md with detailed configuration instructions
- Add INDEX.md explaining relationship between core integration and plugin tools
- Update README.md to reference new user guide
- Cover Docker Compose setup, environment variables, and troubleshooting
- Include performance optimization and monitoring guidelines

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
pull/22551/head
yunqiqiliang 10 months ago
parent f36fe2f9db
commit aa86546c14
3 changed files with 412 additions and 1 deletions
Show Stats Download Patch File Download Diff File

70
clickzetta/INDEX.md
Unescape Escape View File

@ -0,0 +1,70 @@
# Clickzetta Lakehouse & Dify 集成方案
## 项目关系
本目录包含Clickzetta Lakehouse与Dify集成的两种方案：
### 1. 核心向量数据库集成 (当前目录)
- **位置**: `/Users/liangmo/Documents/GitHub/dify/clickzetta/`
- **类型**: Dify核心功能集成
- **用途**: 将Clickzetta Lakehouse作为Dify的底层向量数据库
- **目标用户**: Dify部署管理员
- **文档**: `USER_GUIDE.md`
### 2. 插件工具集成 (独立项目)
- **位置**: `/Users/liangmo/Documents/GitHub/clickzetta_dify/`
- **类型**: Dify插件工具
- **用途**: 提供Clickzetta相关的工具供Dify工作流使用
- **目标用户**: Dify应用开发者
- **GitHub**: https://github.com/yunqiqiliang/clickzetta_dify
- **文档**: 插件项目中的`docs/INSTALLATION_GUIDE.md`
## 使用场景对比
| 特性 | 核心集成 | 插件工具 |
|------|----------|----------|
| **安装方式** | 配置环境变量 | 安装插件包 |
| **使用对象** | Dify系统管理员 | Dify应用开发者 |
| **功能范围** | 底层向量存储 | 工作流工具 |
| **配置复杂度** | 中等 | 简单 |
| **适用场景** | 替换默认向量数据库 | 灵活的数据操作 |
## 推荐使用方案
### 场景1: 企业级部署
- **使用**: 核心向量数据库集成
- **优势**: 统一的数据存储，更好的性能和管理
- **配置**: 参考 `USER_GUIDE.md`
### 场景2: 应用开发
- **使用**: 插件工具集成
- **优势**: 灵活的工具使用，无需系统级配置
- **配置**: 参考插件项目的安装指南
### 场景3: 混合使用
- **使用**: 同时使用两种方案
- **优势**: 既有统一的底层存储，又有灵活的工具操作
- **注意**: 确保两种方案使用相同的Clickzetta实例和配置
## 快速开始
### 核心集成配置
```bash
# 设置环境变量
export VECTOR_STORE=clickzetta
export CLICKZETTA_USERNAME=your_username
export CLICKZETTA_PASSWORD=your_password
export CLICKZETTA_INSTANCE=your_instance
# ... 其他配置
# 重启Dify服务
docker-compose restart
```
### 插件工具安装
1. 从GitHub下载插件包
2. 在Dify中安装插件
3. 配置连接信息
4. 在工作流中使用工具
详细说明请参考各自的文档。

6
clickzetta/README.md
Unescape Escape View File

@ -14,6 +14,7 @@ This directory contains the implementation and testing materials for integrating
- `test_clickzetta_integration.py` - Comprehensive integration test suite with Dify framework - `test_clickzetta_integration.py` - Comprehensive integration test suite with Dify framework
- `TESTING_GUIDE.md` - Testing instructions and methodology - `TESTING_GUIDE.md` - Testing instructions and methodology
- `PR_SUMMARY.md` - Complete PR preparation summary - `PR_SUMMARY.md` - Complete PR preparation summary
- `USER_GUIDE.md` - **NEW**: Complete user guide for configuring Clickzetta in Dify
## Quick Start ## Quick Start
@ -42,7 +43,10 @@ python test_clickzetta_integration.py
cat TESTING_GUIDE.md cat TESTING_GUIDE.md
``` ```
### 3. PR Status ### 3. User Guide
For detailed configuration and usage instructions, see `USER_GUIDE.md`.
### 4. PR Status
See `PR_SUMMARY.md` for complete PR preparation status and submission strategy. See `PR_SUMMARY.md` for complete PR preparation status and submission strategy.
## Technical Highlights ## Technical Highlights

337
clickzetta/USER_GUIDE.md
Unescape Escape View File

@ -0,0 +1,337 @@
# Dify中配置Clickzetta Lakehouse作为向量数据库指南
## 概述
Clickzetta Lakehouse是一个统一的数据湖仓平台，支持向量数据存储和高性能搜索。本指南将帮助您在Dify中配置Clickzetta作为向量数据库，替代默认的向量数据库选项。
## 前置条件
### 1. 系统要求
- Dify 平台已部署并运行
- Python 3.11+ 环境
- 可访问的Clickzetta Lakehouse实例
### 2. 必需的连接信息
在开始配置之前，请确保您有以下Clickzetta Lakehouse连接信息：
| 参数 | 说明 | 示例 |
|------|------|------|
| `username` | Clickzetta用户名 | `your_username` |
| `password` | Clickzetta密码 | `your_password` |
| `instance` | Clickzetta实例ID | `your_instance_id` |
| `service` | 服务端点 | `api.clickzetta.com` |
| `workspace` | 工作空间名称 | `quick_start` |
| `vcluster` | 虚拟集群名称 | `default_ap` |
| `schema` | 数据库模式 | `dify` |
## 配置步骤
### 1. 环境变量配置
在Dify部署环境中设置以下环境变量：
```bash
# Clickzetta Lakehouse连接配置
export VECTOR_STORE=clickzetta
export CLICKZETTA_USERNAME=your_username
export CLICKZETTA_PASSWORD=your_password
export CLICKZETTA_INSTANCE=your_instance_id
export CLICKZETTA_SERVICE=api.clickzetta.com
export CLICKZETTA_WORKSPACE=quick_start
export CLICKZETTA_VCLUSTER=default_ap
export CLICKZETTA_SCHEMA=dify
# 可选的高级配置
export CLICKZETTA_BATCH_SIZE=100
export CLICKZETTA_ENABLE_INVERTED_INDEX=true
export CLICKZETTA_ANALYZER_TYPE=chinese
export CLICKZETTA_ANALYZER_MODE=smart
export CLICKZETTA_VECTOR_DISTANCE_FUNCTION=cosine_distance
```
### 2. Docker Compose配置
如果使用Docker Compose部署Dify，请在`docker-compose.yml`中添加环境变量：
```yaml
version: '3'
services:
api:
image: langgenius/dify-api:latest
environment:
# ... 其他配置
# Clickzetta向量数据库配置
VECTOR_STORE: clickzetta
CLICKZETTA_USERNAME: ${CLICKZETTA_USERNAME}
CLICKZETTA_PASSWORD: ${CLICKZETTA_PASSWORD}
CLICKZETTA_INSTANCE: ${CLICKZETTA_INSTANCE}
CLICKZETTA_SERVICE: ${CLICKZETTA_SERVICE:-api.clickzetta.com}
CLICKZETTA_WORKSPACE: ${CLICKZETTA_WORKSPACE:-quick_start}
CLICKZETTA_VCLUSTER: ${CLICKZETTA_VCLUSTER:-default_ap}
CLICKZETTA_SCHEMA: ${CLICKZETTA_SCHEMA:-dify}
# 可选的高级配置
CLICKZETTA_BATCH_SIZE: ${CLICKZETTA_BATCH_SIZE:-100}
CLICKZETTA_ENABLE_INVERTED_INDEX: ${CLICKZETTA_ENABLE_INVERTED_INDEX:-true}
CLICKZETTA_ANALYZER_TYPE: ${CLICKZETTA_ANALYZER_TYPE:-chinese}
CLICKZETTA_ANALYZER_MODE: ${CLICKZETTA_ANALYZER_MODE:-smart}
CLICKZETTA_VECTOR_DISTANCE_FUNCTION: ${CLICKZETTA_VECTOR_DISTANCE_FUNCTION:-cosine_distance}
```
### 3. 配置文件设置
如果使用配置文件方式，请在Dify配置文件中添加：
```python
# config.py
class Config:
# ... 其他配置
# 向量数据库配置
VECTOR_STORE = "clickzetta"
# Clickzetta连接配置
CLICKZETTA_USERNAME = os.getenv("CLICKZETTA_USERNAME")
CLICKZETTA_PASSWORD = os.getenv("CLICKZETTA_PASSWORD")
CLICKZETTA_INSTANCE = os.getenv("CLICKZETTA_INSTANCE")
CLICKZETTA_SERVICE = os.getenv("CLICKZETTA_SERVICE", "api.clickzetta.com")
CLICKZETTA_WORKSPACE = os.getenv("CLICKZETTA_WORKSPACE", "quick_start")
CLICKZETTA_VCLUSTER = os.getenv("CLICKZETTA_VCLUSTER", "default_ap")
CLICKZETTA_SCHEMA = os.getenv("CLICKZETTA_SCHEMA", "dify")
# 高级配置
CLICKZETTA_BATCH_SIZE = int(os.getenv("CLICKZETTA_BATCH_SIZE", "100"))
CLICKZETTA_ENABLE_INVERTED_INDEX = os.getenv("CLICKZETTA_ENABLE_INVERTED_INDEX", "true").lower() == "true"
CLICKZETTA_ANALYZER_TYPE = os.getenv("CLICKZETTA_ANALYZER_TYPE", "chinese")
CLICKZETTA_ANALYZER_MODE = os.getenv("CLICKZETTA_ANALYZER_MODE", "smart")
CLICKZETTA_VECTOR_DISTANCE_FUNCTION = os.getenv("CLICKZETTA_VECTOR_DISTANCE_FUNCTION", "cosine_distance")
```
## 验证配置
### 1. 连接测试
启动Dify后，可以通过以下方式验证Clickzetta连接：
1. **查看日志**：
```bash
# 查看Dify API日志
docker logs dify-api
# 查找Clickzetta相关日志
docker logs dify-api | grep -i clickzetta
```
2. **创建知识库测试**：
- 登录Dify管理界面
- 创建新的知识库
- 上传测试文档
- 观察是否成功创建向量索引
### 2. 功能验证
在Dify中验证以下功能：
- ✅ **知识库创建**：能否成功创建知识库
- ✅ **文档上传**：能否上传和处理文档
- ✅ **向量化存储**：文档是否被正确向量化并存储
- ✅ **相似度搜索**：搜索功能是否正常工作
- ✅ **问答功能**：基于知识库的问答是否准确
## 使用指南
### 1. 知识库管理
#### 创建知识库
1. 登录Dify管理界面
2. 点击「知识库」→「创建知识库」
3. 填写知识库名称和描述
4. 选择嵌入模型（推荐使用支持中文的模型）
5. 点击「保存并处理」
#### 上传文档
1. 在知识库中点击「上传文档」
2. 选择支持的文件格式（PDF、Word、TXT等）
3. 配置文档分块规则
4. 点击「保存并处理」
5. 等待文档处理完成
#### 管理向量数据
- **查看统计**：在知识库详情页查看向量数量和存储统计
- **更新文档**：可以更新或删除已上传的文档
- **搜索测试**：使用搜索功能测试向量检索效果
### 2. 应用开发
#### 在聊天应用中使用
1. 创建新的聊天应用
2. 在「提示词编排」中关联知识库
3. 配置检索设置：
- **TopK值**：建议3-5
- **相似度阈值**：建议0.3-0.7
- **重排序**：可选启用
4. 测试问答效果
#### 在工作流中使用
1. 创建工作流应用
2. 添加「知识检索」节点
3. 配置检索参数：
- **查询变量**：`{{sys.query}}`
- **知识库**：选择目标知识库
- **检索设置**：TopK和相似度阈值
4. 将检索结果传递给LLM节点
## 性能优化
### 1. 向量索引优化
Clickzetta自动为向量字段创建HNSW索引，您可以通过以下方式优化：
```python
# 在配置中调整索引参数
CLICKZETTA_VECTOR_DISTANCE_FUNCTION = "cosine_distance" # 适合文本嵌入
# 或
CLICKZETTA_VECTOR_DISTANCE_FUNCTION = "l2_distance" # 适合图像嵌入
```
### 2. 批处理优化
```python
# 调整批处理大小
CLICKZETTA_BATCH_SIZE = 200 # 增加批处理大小可提高吞吐量
```
### 3. 全文搜索优化
```python
# 启用倒排索引以支持全文搜索
CLICKZETTA_ENABLE_INVERTED_INDEX = true
CLICKZETTA_ANALYZER_TYPE = "chinese" # 中文分词
CLICKZETTA_ANALYZER_MODE = "smart" # 智能分词模式
```
## 监控和维护
### 1. 性能监控
监控以下关键指标：
- **连接状态**：数据库连接是否正常
- **查询延迟**：向量搜索响应时间
- **吞吐量**：每秒处理的向量查询数
- **存储使用**：向量数据存储空间使用情况
### 2. 日志分析
关注以下日志信息：
```bash
# 连接日志
INFO - Clickzetta connection established successfully
# 向量操作日志
INFO - Vector insert completed: 1000 vectors in 2.3s
INFO - Vector search completed: 5 results in 120ms
# 错误日志
ERROR - Clickzetta connection failed: ...
WARNING - Vector search timeout: ...
```
### 3. 数据备份
定期备份重要的向量数据：
```sql
-- 查看向量集合
SHOW TABLES IN dify;
-- 备份向量数据
CREATE TABLE dify.backup_vectors AS
SELECT * FROM dify.knowledge_base_vectors;
-- 查看数据统计
SELECT COUNT(*) FROM dify.knowledge_base_vectors;
```
## 故障排除
### 常见问题
#### Q1: 连接失败
**症状**: Dify启动时报Clickzetta连接错误
**解决方案**:
1. 检查网络连接
2. 验证用户名和密码
3. 确认实例ID正确
4. 检查防火墙设置
#### Q2: 向量搜索性能差
**症状**: 搜索响应时间过长
**解决方案**:
1. 检查是否创建了向量索引
2. 调整TopK值
3. 优化查询条件
4. 考虑增加计算资源
#### Q3: 文档处理失败
**症状**: 文档上传后处理失败
**解决方案**:
1. 检查文档格式是否支持
2. 验证文档大小限制
3. 查看详细错误日志
4. 检查向量化模型状态
#### Q4: 中文搜索效果差
**症状**: 中文文档搜索结果不准确
**解决方案**:
1. 启用中文分词器
2. 调整相似度阈值
3. 使用支持中文的嵌入模型
4. 检查文档分块设置
## 迁移指南
### 从其他向量数据库迁移
如果您从其他向量数据库（如Pinecone、Weaviate等）迁移到Clickzetta：
1. **备份现有数据**：
```bash
# 导出现有向量数据
python export_vectors.py --source=pinecone --output=vectors.json
```
2. **更新配置**：
- 修改环境变量
- 重启Dify服务
3. **数据导入**：
```bash
# 导入向量数据到Clickzetta
python import_vectors.py --source=vectors.json --target=clickzetta
```
4. **验证迁移**：
- 测试搜索功能
- 验证数据完整性
- 检查性能指标
## 技术支持
### 获取帮助
如遇到问题，请：
1. 查看Dify系统日志
2. 检查Clickzetta连接状态
3. 参考本指南的故障排除部分
4. 联系技术支持团队
### 有用的资源
- **Dify官方文档**: https://docs.dify.ai
- **Clickzetta文档**: https://docs.clickzetta.com
- **GitHub Issues**: https://github.com/langgenius/dify/issues
- **社区论坛**: https://community.dify.ai
---
*本指南基于Dify v0.8.0+ 和 Clickzetta Lakehouse v1.0.0+*
Write Preview
Loading…
Cancel
Save