Dify本地知识库搭建入门教程

基础配置

配置文件示例

def detailed_env_config():
    """
    详细的环境变量配置示例
    """
    print("\n=== 详细环境变量配置示例 ===\n")
    
    env_example = """
### PostgreSQL配置
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=dify

### Redis配置  
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_DB=0

### 安全配置
SECRET_KEY=your_32_character_secret_key_here
ENCRYPTION_KEY=your_32_character_encryption_key

### 服务URL配置
CONSOLE_API_URL=http://localhost:3000
WEB_API_URL=http://localhost:5001
FILES_URL=http://localhost:5001

### 向量存储配置
VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_API_KEY=

### 嵌入模型配置
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_ENDPOINT=

### 文件上传配置
FILES_ACCESS_TIMEOUT=300
"""
    
    print("docker/.env 文件内容示例：")
    print(env_example)
    
    print("\n生成安全密钥的命令：")
    print("```bash")
    print("# 生成SECRET_KEY")
    print("openssl rand -hex 32")
    print()
    print("# 生成ENCRYPTION_KEY")  
    print("openssl rand -hex 32")
    print("```")

### 执行教程
if __name__ == "__main__":
    dify_local_knowledge_base_tutorial()
    detailed_env_config()

📋 系统要求

• 操作系统：Linux/macOS/Windows (WSL2推荐)
• 内存：至少4GB，推荐8GB+
• 存储：至少10GB可用空间
• 软件依赖：Docker 20.10+，Docker Compose 2.0+

🔧 详细安装步骤

1️⃣ 安装Docker环境

Ubuntu/Debian:

sudo apt update
sudo apt install docker.io docker-compose -y
sudo usermod -aG docker $USER
# 重新登录或执行：newgrp docker

CentOS/RHEL:

sudo yum install -y docker docker-compose
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

macOS:

# 安装Docker Desktop
brew install --cask docker
brew install docker-compose

2️⃣ 部署Dify

# 克隆源码
git clone https://github.com/langgenius/dify.git
cd dify

# 切换到稳定版本
git checkout v0.6.10

# 配置环境变量
cp .env.example .env
cp docker/.env.example docker/.env

# 编辑docker/.env，设置密码和密钥
vim docker/.env

# 启动服务
cd docker
docker-compose up -d

3️⃣ 环境变量配置要点

关键配置项：

• POSTGRES_PASSWORD：PostgreSQL数据库密码
• REDIS_PASSWORD：Redis密码
• SECRET_KEY：32位随机字符串（使用openssl rand -hex 32生成）
• CONSOLE_API_URL：设置为http://localhost:3000
• WEB_API_URL：设置为http://localhost:5001

4️⃣ 服务验证

# 检查服务状态
docker-compose ps

# 查看日志
docker-compose logs -f api

# 预期端口：
# 3000 - Web控制台
# 5001 - API服务

📚 知识库创建流程

1️⃣ 访问控制台

• 浏览器打开：http://localhost:3000
• 首次访问需要注册管理员账号

2️⃣ 创建知识库

1. 左侧菜单选择"知识库"
2. 点击"新建知识库"
3. 填写名称和描述
4. 选择检索方式（推荐向量检索）
5. 点击"创建"

3️⃣ 上传文档

支持格式：

• PDF、Word、Excel、PPT
• Markdown、Text、HTML

上传步骤：

1. 在知识库详情页点击"上传文件"
2. 选择本地文件
3. 等待处理完成（状态变为"已处理"）

4️⃣ 文档处理机制

• 文本提取：从各种格式中提取纯文本
• 分段处理：按配置的分段策略分割文本
• 向量化：使用嵌入模型生成向量
• 存储索引：存入向量数据库供检索使用

⚙️ 模型配置选项

默认配置（推荐）

• 嵌入模型：sentence-transformers/all-MiniLM-L6-v2
• 向量数据库：Weaviate（内置）
• 无需API密钥，完全本地运行

高级配置

• OpenAI嵌入：需要API密钥，效果更好
• 自定义模型：可集成其他开源嵌入模型
• 外部向量库：支持Qdrant、Milvus等

🤖 应用集成

创建RAG应用

1. 在"应用"菜单创建新应用
2. 选择"对话型应用"
3. 在"上下文"设置中启用RAG
4. 选择已创建的知识库
5. 保存并发布应用

API调用示例

import requests

# 配置
API_KEY = "your_api_key_from_console"
APP_ID = "your_app_id"
URL = "http://localhost:5001/v1/chat-messages"

# 发送请求
headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

data = {
    'inputs': {},
    'query': '根据知识库内容回答问题',
    'response_mode': 'blocking',
    'conversation_id': ''
}

response = requests.post(URL, headers=headers, json=data)
print(response.json()['answer'])

🔧 常见问题解决

服务启动问题

• 端口冲突：修改docker-compose.yml中的端口映射
• 内存不足：关闭不必要的服务，增加系统内存
• 权限问题：确保Docker用户组权限正确

文档处理问题

• 处理卡住：检查worker服务状态，查看日志
• 格式不支持：转换为支持的格式再上传
• 分段效果差：调整分段设置（长度、重叠）

检索效果优化

• 调整分段策略：根据文档特点设置合适的分段长度
• 更换嵌入模型：使用更强大的模型提升检索精度
• 增加上下文：在应用设置中增加检索结果数量

🚀 性能优化建议

硬件优化

• 使用SSD存储提升I/O性能
• 增加内存容量支持更大知识库
• 多核CPU提升并发处理能力

配置优化

• 合理设置文档分段参数
• 定期清理无用文档释放空间
• 监控系统资源使用情况

模型优化

• 根据应用场景选择合适的嵌入模型
• 考虑使用量化模型减少资源消耗
• 对于专业领域，可微调专用嵌入模型

🔄 维护和升级

数据备份

# 备份数据库
docker exec dify-db-1 pg_dump -U postgres dify > backup.sql

# 备份上传文件
docker cp dify-nginx-1:/app/api/storage ./storage_backup

版本升级

cd dify
git pull
git checkout 新版本号
cd docker
docker-compose down
docker-compose pull
docker-compose up -d