Dify 完全指南:从安装到实战的开源 LLM 应用开发平台
摘要:本文详细介绍开源 LLM 应用开发平台 Dify 的完整使用流程,包括本地部署、API 配置、工作流编排、知识库管理,以及跨境电商客服和 Text2SQL 两个实战案例。
目录
- [Dify 简介](#Dify 简介)
- 本地部署指南
- [API 配置与集成](#API 配置与集成)
- 自定义工具开发
- 工作流类型详解
- 知识库管理
- 实战案例:跨境电商客服
- [实战案例:Text2SQL 数据库查询](#实战案例:Text2SQL 数据库查询)
- 网页集成方案
- 总结与建议
1. Dify 简介
1.1 什么是 Dify?
Dify 是一个开源的 LLM(大语言模型)应用开发平台,旨在降低 AI 应用开发的门槛。它提供了:
- 可视化工作流编排:拖拽式界面,无需编码即可构建复杂 AI 应用
- 知识库管理**:支持多种数据源,自动文本分段与向量化
- 丰富的工具集成:内置多种工具,支持自定义 API 接入
- 一键部署:Docker Compose 快速启动,生产就绪
1.2 核心概念
| 概念 | 说明 |
|---|---|
| Workflow(工作流) | 面向任务的自动化流程,适合批量处理 |
| Chatflow(对话流) | 面向对话的交互流程,适合客服场景 |
| 知识库 | 私有数据向量化存储,支持 RAG 检索增强 |
| 工具 | 外部 API 或函数,可扩展 AI 能力边界 |
工作流 vs 智能体:

1.3 适用场景
- 智能客服系统
- 企业知识问答
- 数据分析助手
- 内容生成工具
- 自动化工作流
2. 本地部署指南
2.1 环境要求
- Docker 20.10+
- Docker Compose 2.0+
- 至少 4GB 可用内存
- 20GB 可用磁盘空间
2.2 安装步骤
步骤 1:克隆仓库
bash
git clone https://github.com/langgenius/dify.git
cd dify
步骤 2:配置环境变量
bash
cd docker
cp .env.example .env #dokcer目录下的.env.example文件夹名改成.env
提示 :可根据需要修改
.env文件中的配置,如数据库密码、服务端口等。
步骤 3:启动服务
bash
docker compose up -d

步骤 4:验证部署
bash
docker compose ps
所有服务应显示为 running 状态。
2.3 初始配置
- 浏览器访问
http://localhost - 设置管理员邮箱、用户名和密码
- 完成初始化设置
2.4 服务架构
┌─────────────────────────────────────────────────────┐
│ Dify │
├─────────────┬─────────────┬─────────────┬───────────┤
│ Web UI │ API Server│ Worker │ Database │
│ (Next.js) │ (Flask) │ (Celery) │ (PostgreSQL)│
├─────────────┼─────────────┼─────────────┼───────────┤
│ Redis │ Weaviate │ Sandbox │ Nginx │
│ (Cache) │ (Vector DB)│ (Code Exec)│ (Proxy) │
└─────────────┴─────────────┴─────────────┴───────────┘
2.5 常见问题
Q: 启动失败怎么办?
bash
# 查看日志
docker compose logs -f
# 重启服务
docker compose down && docker compose up -d
Q: 如何重置管理员密码?
bash
docker compose exec api flask reset-password admin@example.com
3. API 配置与集成
3.1 获取 API Key
- 登录 Dify 控制台
- 进入「设置」→「API 访问」
- 点击「创建密钥」
- 复制并妥善保存 API Key
3.2 API 调用示例
Python SDK
python
from dify import DifyClient
client = DifyClient(api_key="your-api-key")
# 发送对话请求
response = client.chat_messages(
inputs={"query": "你好"},
user="user-123"
)
print(response.json())
cURL 示例
bash
curl -X POST https://your-dify-instance.com/v1/chat-messages \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"inputs": {"query": "你好"},
"user": "user-123"
}'
3.3 API 限流与配额
| 计划 | QPS | 月配额 |
|---|---|---|
| 免费版 | 2 | 10,000 |
| 专业版 | 10 | 100,000 |
| 企业版 | 自定义 | 自定义 |
4. 自定义工具开发
4.1 为什么需要自定义工具?
Dify 内置工具可能无法满足所有需求。当需要:
- 访问企业内部 API
- 调用第三方服务
- 执行特定业务逻辑
这时就需要开发自定义工具。
4.2 本地 API 公网穿透
由于 Dify 云端服务无法直接访问本地 API,需要使用穿透工具。
安装 localtunnel
bash
npm install -g localtunnel
启动穿透服务
bash
lt --port 8081
输出示例:
your url is: https://random-name-123.local.lt
安全加固
bash
# 添加基本认证
lt --port 8081 --basic_auth username:password
4.3 工具配置步骤
-
创建 API 端点
pythonfrom flask import Flask, request, jsonify app = Flask(__name__) @app.route('/api/custom-tool', methods=['POST']) def custom_tool(): data = request.json # 处理逻辑 return jsonify({"result": "success"}) if __name__ == '__main__': app.run(port=8081) -
在 Dify 中添加工具
- 进入「工具」→「自定义工具」
- 填写 API URL(使用穿透后的地址)
- 配置请求方法和参数
- 设置鉴权方式(如需要)
-
测试工具
- 使用「测试」功能验证连接
- 检查响应格式是否符合预期
4.4 鉴权配置
Dify 支持多种鉴权方式:
| 类型 | 说明 | 适用场景 |
|---|---|---|
| None | 无需鉴权 | 公开 API |
| API Key | Header 中携带密钥 | 大多数服务 |
| Bearer Token | JWT/OAuth 令牌 | 用户认证 |
| Basic Auth | 用户名密码 | 内部服务 |
5. 工作流类型详解
5.1 Workflow(工作流)
特点:
- 面向任务处理
- 批量执行
- 无状态或弱状态
- 适合数据处理、内容生成等场景
典型流程:
输入 → 预处理 → LLM 处理 → 后处理 → 输出
适用场景:
- 文章摘要生成
- 数据清洗与转换
- 批量内容创作
- 报告自动生成
5.2 Chatflow(对话流)
特点:
- 面向对话交互
- 保持上下文状态
- 支持多轮对话
- 适合客服、助手等场景
典型流程:
用户输入 → 意图识别 → 知识库检索 → LLM 生成 → 回复用户
↓
多轮记忆
适用场景:
- 智能客服
- 个人助手
- 咨询问答
- 情感陪伴
5.3 Workflow vs Chatflow 对比
| 维度 | Workflow | Chatflow |
|---|---|---|
| 交互模式 | 单次任务 | 多轮对话 |
| 状态管理 | 无状态 | 有状态 |
| 上下文 | 不保留 | 保留历史 |
| 适用场景 | 批量处理 | 实时交互 |
| 延迟要求 | 较低 | 较高 |
5.4 选择建议
- 选择 Workflow:当你需要处理一批数据、生成固定格式内容、或执行自动化任务时
- 选择 Chatflow:当你需要与用户进行自然对话、保持上下文、或提供个性化服务时
6. 知识库管理
6.1 知识库的作用
知识库是 Dify 的 RAG(检索增强生成)核心,通过向量化存储私有数据,让 AI 能够:
- 回答基于企业内部文档的问题
- 提供准确的产品信息
- 避免大模型的幻觉问题
6.2 创建知识库流程
步骤 1:选择数据源
支持的数据源类型:
| 类型 | 格式 | 说明 |
|---|---|---|
| 文本文件 | .txt, .md | 纯文本内容 |
| 文档 | .pdf, .docx | Office 文档 |
| 网页 | URL | 自动抓取网页内容 |
| CSV/Excel | .csv, .xlsx | 结构化数据 |
| Notion | Notion 页面 | 需授权访问 |
步骤 2:文本分段与清洗
分段策略:
| 策略 | 说明 | 适用场景 |
|---|---|---|
| 自动分段 | AI 智能识别段落边界 | 通用场景 |
| 固定长度 | 按字符数分段 | 技术文档 |
| 按分隔符 | 按指定符号分段 | 结构化文本 |
清洗选项:
- 去除 HTML 标签
- 去除特殊字符
- 标准化空白字符
- 去除页眉页脚
步骤 3:向量化处理
Dify 使用嵌入模型将文本转换为向量:
文本 → [嵌入模型] → 向量 → [向量数据库] → 可检索
支持的嵌入模型:
- OpenAI text-embedding-ada-002
- 本地部署的 BGE/M3E
- 其他兼容模型
步骤 4:完成索引
等待向量化完成后,知识库即可用于检索。
6.3 检索配置
| 参数 | 说明 | 推荐值 |
|---|---|---|
| Top K | 返回的文档片段数量 | 3-5 |
| 相似度阈值 | 最低相似度要求 | 0.5-0.7 |
| 重排序 | 是否启用重排序模型 | 开启 |
6.4 最佳实践
- 文档质量优先:确保源文档清晰、准确、无歧义
- 合理分段:避免过长或过短的分段
- 定期更新:及时同步最新的企业知识
- 权限控制:敏感信息需要访问控制
7. 实战案例:跨境电商客服
7.1 场景描述
构建一个跨境电商智能客服系统,能够:
- 自动识别用户意图
- 处理常见问候和礼貌用语
- 转接人工服务
- 基于知识库回答专业问题
7.2 系统架构
用户输入
↓
[意图识别节点]
├─→ 打招呼 → 固定回复
├─→ 感谢语 → 礼貌回复
├─→ 告别语 → 告别回复
├─→ 人工服务 → 转接链接
└─→ 其他问题 → RAG 检索 → LLM 生成
7.3 意图识别代码实现
python
import random
import re
def main(query: str) -> dict:
"""
基于固定短语匹配的跨境电商问答处理器
Args:
query: 用户输入的问题
Returns:
Dict: 包含回复类型、回复内容等信息的字典
"""
# 去除首尾空格
query = query.strip()
# 打招呼相关的固定短语
greeting_phrases = {
# 基本问候
"你好", "您好", "hi", "hello", "嗨", "哈喽", "哈罗",
"早上好", "下午好", "晚上好", "上午好", "中午好", "晚安",
"早", "午安", "good morning", "good afternoon", "good evening",
# 询问身份
"你是谁", "你是什么", "你叫什么", "你的名字", "介绍一下自己",
"自我介绍", "你是什么东西", "你是哪个", "你是啥",
# 询问状态
"你好吗", "怎么样", "还好吗", "你还好吗", "最近怎么样",
"你在吗", "在不在", "还在吗", "在线吗", "你在线吗",
# 询问能力
"你能干什么", "你会做什么", "你能做什么", "你的功能",
"你有什么用", "你的作用", "你的职责", "你的用途",
"你能帮我什么", "你可以做什么", "你会什么", "你懂什么",
"能力介绍", "功能介绍", "你的能力", "你有什么功能",
# 开始对话
"开始", "开始咨询", "开始对话", "开始聊天", "我想咨询",
"我有问题", "我想问问题", "我想了解", "咨询一下",
# 测试类
"测试", "试试", "试一试", "test", "testing", "试试看",
"测试一下", "看看", "检查一下"
}
# 固定回复
greeting_response = "你好,很高兴为您服务!我是您的跨境电商学习小助手,专业为您答疑解惑。"
# 礼貌用语
thank_phrases = {
"谢谢", "感谢", "多谢", "谢了", "thanks", "thank you",
"thx", "3q", "3x", "谢谢你", "感谢你", "多谢了",
"非常感谢", "十分感谢", "万分感谢", "太感谢了"
}
goodbye_phrases = {
"再见", "拜拜", "bye", "byebye", "goodbye", "88", "走了", "告辞",
"先走了", "下次见", "回头见", "有空再聊", "改天聊",
"see you", "拜", "溜了", "闪了", "slip away"
}
polite_responses = {
"thank": [
"不用客气,随时为您服务!",
"很高兴能帮助到您!",
"这是我应该做的,有问题随时找我哦!",
"客气了,有什么问题尽管问!",
"不客气,祝您跨境电商生意兴隆!"
],
"goodbye": [
"再见!期待下次为您服务!",
"祝您生活愉快,有问题随时来找我!",
"再见!祝您跨境电商生意兴隆!",
"拜拜!有问题随时回来咨询!",
"再见!祝您学习愉快!"
]
}
# 人工服务相关短语
human_service_phrases = {
# 直接要求人工服务
"人工服务", "人工客服", "人工坐席", "人工咨询", "人工帮助",
"人工支持", "人工答疑", "人工解答", "人工回复", "人工对话",
# 转接相关
"转人工", "找人工", "要人工", "转接人工", "转接客服",
"切换人工", "接入人工", "联系人工", "答疑入口",
# 真人服务
"真人服务", "真人客服", "真人咨询", "真人对话", "真人帮助",
"活人", "真人", "人类", "人工", "真的人",
# 客服相关
"客服", "在线客服", "联系客服", "找客服", "客服电话",
"客服微信", "客服 qq", "官方客服",
# 老师/导师
"联系老师", "找老师", "咨询老师", "请教老师", "老师帮忙",
"专业老师", "课程老师", "指导老师",
# 专业服务
"专人服务", "专人客服", "专业咨询", "专业服务", "专家咨询",
"顾问咨询", "一对一服务", "专属服务",
# 投诉和问题
"投诉", "举报", "反馈问题", "意见反馈", "服务投诉",
"质量问题", "服务问题", "系统问题",
# 售后相关
"退款", "退货", "售后", "售后服务", "退换货", "申请退款",
"退费", "取消订单", "订单问题",
# 不满意
"不满意", "有问题", "出问题", "不行", "太差了", "服务差",
"回答不对", "答非所问", "听不懂", "不准确"
}
human_service_response = "同学,点击 https://www.123.com 可进入人工答疑"
def normalize_text(text: str) -> str:
"""标准化文本:去除标点符号,转换为小写"""
cleaned = re.sub(r'[^\w\u4e00-\u9fff]', '', text.lower().strip())
return cleaned
def exact_match_check(query_text: str, phrase_set) -> bool:
"""精确匹配检查"""
normalized_query = normalize_text(query_text)
for phrase in phrase_set:
normalized_phrase = normalize_text(phrase)
if normalized_phrase == normalized_query:
return True
return False
def contains_match_check(query_text: str, phrase_set) -> bool:
"""包含匹配检查(用于短查询中包含关键短语的情况)"""
normalized_query = normalize_text(query_text)
# 只有当查询很短时才使用包含匹配(避免误匹配)
if len(normalized_query) <= 10:
for phrase in phrase_set:
normalized_phrase = normalize_text(phrase)
if normalized_phrase in normalized_query or normalized_query in normalized_phrase:
return True
return False
# 处理输入
query = query.strip()
if not query:
return {
"type": "error",
"response": "请输入您的问题。",
"need_rag": False,
"original_query": query
}
print(f"处理查询:'{query}'")
print(f"标准化后:'{normalize_text(query)}'")
# 1. 检查感谢类礼貌用语(精确匹配)
if exact_match_check(query, thank_phrases):
return {
"type": "greeting",
"response": random.choice(polite_responses["thank"]),
"need_rag": False,
"original_query": query
}
# 2. 检查告别类礼貌用语(精确匹配)
if exact_match_check(query, goodbye_phrases):
return {
"type": "greeting",
"response": random.choice(polite_responses["goodbye"]),
"need_rag": False,
"original_query": query
}
# 3. 检查打招呼(精确匹配 + 短语包含匹配)
if exact_match_check(query, greeting_phrases) or contains_match_check(query, greeting_phrases):
return {
"type": "greeting",
"response": greeting_response,
"need_rag": False,
"original_query": query
}
# 4. 检查人工服务请求(精确匹配 + 短语包含匹配)
if exact_match_check(query, human_service_phrases) or contains_match_check(query, human_service_phrases):
return {
"type": "human_service",
"response": human_service_response,
"need_rag": False,
"original_query": query
}
# 5. 其他情况需要 RAG 检索
return {
"type": "rag_needed",
"response": "",
"need_rag": True,
"original_query": query
}
7.4 工作流配置
- 开始节点:接收用户输入
- 代码节点:运行意图识别代码
- 条件分支 :
type == "greeting"→ 直接回复type == "human_service"→ 返回人工链接type == "rag_needed"→ 知识库检索 → LLM 生成
- 结束节点:输出最终回复
7.5 优化建议
- 添加意图识别模型:使用分类模型替代规则匹配
- 多语言支持:扩展短语库支持更多语言
- 情感分析:识别用户情绪,调整回复策略
- 会话记忆:记录用户历史问题,提供个性化服务
8. 实战案例:Text2SQL 数据库查询
8.1 场景描述
构建一个自然语言查询学生成绩的系统,用户可以用中文提问,系统自动生成 SQL 并执行。
8.2 数据库设计
sql
CREATE TABLE student_grades (
id INT PRIMARY KEY AUTO_INCREMENT,
student_id VARCHAR(20) NOT NULL,
student_name VARCHAR(50) NOT NULL,
class_name VARCHAR(20),
subject VARCHAR(30),
score DECIMAL(5,2),
exam_date DATE,
semester VARCHAR(20),
grade INT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
8.3 LLM 提示词设计
markdown
## 角色
你是一个专业的 SQL 查询生成器,负责根据用户查询创建标准的 MySQL 数据库 SQL 语句。
## 任务
根据以下问题,生成一个格式清晰、结构明确的 JSON 数组,其中每个元素是一条合法且性能优化的 MySQL 查询语句。
### 表信息
表名:student_grades(学生成绩信息表)
### 字段说明
- id: 主键
- student_id: 学号
- student_name: 学生姓名
- class_name: 班级
- subject: 科目
- score: 分数
- exam_date: 考试日期
- semester: 学期
- grade: 年级
- created_at: 记录创建时间
- updated_at: 记录更新时间
### 输出要求
1. 根据用户的问题,生成最多 10 条直接关联问题的 SQL 查询语句。
2. 每条 SQL 应从不同分析角度(如按科目、班级、学期、年级等维度)切入,确保覆盖多维统计需求。
3. 所有 SQL 必须语法正确、可执行,并注重性能优化(如避免 SELECT *,合理使用索引字段等)。
4. 若问题涉及多维统计(例如"各班各科平均分"),请为每个统计维度单独生成子查询。
5. 对于全量数据查询,必须按 semester(学期)进行聚合或排序。
6. 最终输出必须是纯 JSON 数组格式,以 ```json 开头,以 ```结尾,不包含任何额外解释或文本,其中每个元素必须是对象,且仅包含一个字段:`"sql"`(字符串类型),格式示例:
```json
[
{ "sql": "SELECT ...;" },
{ "sql": "SELECT ...;" }
]
请严格按照上述格式和要求生成响应。
8.4 示例查询
用户输入:「查询三年级一班的数学平均分」
生成的 SQL:
json
[
{ "sql": "SELECT AVG(score) as avg_score FROM student_grades WHERE grade = 3 AND class_name = '一班' AND subject = '数学';" },
{ "sql": "SELECT class_name, subject, AVG(score) as avg_score FROM student_grades WHERE grade = 3 AND subject = '数学' GROUP BY class_name, subject;" },
{ "sql": "SELECT semester, AVG(score) as avg_score FROM student_grades WHERE grade = 3 AND class_name = '一班' AND subject = '数学' GROUP BY semester ORDER BY semester;" }
]
8.5 安全考虑
- 只读权限:数据库用户仅授予 SELECT 权限
- 查询限制:限制返回行数(如 LIMIT 1000)
- 超时控制:设置查询超时时间(如 30 秒)
- 审计日志:记录所有生成的 SQL 用于审计
8.6 工作流配置
- 开始节点:接收用户自然语言问题
- LLM 节点:使用提示词生成 SQL
- 代码节点:解析 JSON,提取 SQL 语句
- 数据库工具:执行 SQL 查询
- LLM 节点:将查询结果转换为自然语言回复
- 结束节点:输出最终回复
9. 网页集成方案
9.1 嵌入式聊天窗口
Dify 提供嵌入式脚本,可直接集成到网页中:
html
<!-- 在 </body> 前添加 -->
<script>
window.difyChatbotConfig = {
token: 'your-app-token',
baseUrl: 'https://your-dify-instance.com'
}
</script>
<script
src="https://your-dify-instance.com/embed.min.js"
id="your-app-token"
defer>
</script>
9.2 自定义样式
css
.dify-chatbot-container {
position: fixed;
bottom: 20px;
right: 20px;
z-index: 9999;
}
.dify-chatbot-bubble {
max-width: 400px;
border-radius: 12px;
box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}
9.3 自定义事件监听
javascript
document.addEventListener('dify-chatbot-ready', function() {
console.log('聊天机器人已就绪');
});
document.addEventListener('dify-chatbot-message', function(e) {
console.log('收到消息:', e.detail);
});
9.4 React/Vue 组件集成
jsx
// React 示例
import { useEffect } from 'react';
function DifyChatbot() {
useEffect(() => {
const script = document.createElement('script');
script.src = 'https://your-dify-instance.com/embed.min.js';
script.id = 'your-app-token';
script.defer = true;
document.body.appendChild(script);
return () => {
document.body.removeChild(script);
};
}, []);
return <div id="dify-chatbot" />;
}
10. 总结与建议
10.1 核心优势
| 优势 | 说明 |
|---|---|
| 快速部署 | Docker Compose 一键启动 |
| 可视化编排 | 无需编码即可构建工作流 |
| RAG 支持 | 私有知识库增强 AI 准确性 |
| 灵活集成 | 支持自定义工具和 API |
| 开源免费 | 社区版完全免费 |
10.2 适用场景推荐
强烈推荐:
- 企业知识库问答
- 智能客服系统
- 内部工具自动化
可以考虑:
- 个人 AI 助手
- 内容生成工具
- 数据分析助手
需要评估:
- 高并发场景(需企业版)
- 复杂业务逻辑(可能需要自定义开发)
- 严格合规要求(需私有化部署)
10.3 学习路线
- 入门:完成本地部署,熟悉界面
- 基础:创建第一个工作流和知识库
- 进阶:开发自定义工具,集成外部 API
- 高级:优化性能,生产环境部署
10.4 资源链接
- 官方网站:https://dify.ai
- GitHub 仓库:https://github.com/langgenius/dify
- 文档中心:https://docs.dify.ai
- 社区论坛:https://discord.gg/dify
10.5 结语
Dify 作为开源 LLM 应用开发平台,大大降低了 AI 应用的开发门槛。无论是个人开发者还是企业团队,都可以利用 Dify 快速构建自己的 AI 应用。希望本文能帮助你快速上手 Dify,开启 AI 应用开发之旅!
作者注:本文基于 Dify v0.6.x 版本编写,具体功能可能随版本更新有所变化。建议参考官方文档获取最新信息。