Dify（Agent + RAG）指南：从安装到实战的开源 LLM 应用开发平台

Dify 完全指南：从安装到实战的开源 LLM 应用开发平台

摘要：本文详细介绍开源 LLM 应用开发平台 Dify 的完整使用流程，包括本地部署、API 配置、工作流编排、知识库管理，以及跨境电商客服和 Text2SQL 两个实战案例。

目录

1. Dify 简介
2. 本地部署指南
3. API 配置与集成
4. 自定义工具开发
5. 工作流类型详解
6. 知识库管理
7. 实战案例：跨境电商客服
8. 实战案例：Text2SQL 数据库查询
9. 网页集成方案
10. 总结与建议

1. Dify 简介

1.1 什么是 Dify？

Dify 是一个开源的 LLM（大语言模型）应用开发平台，旨在降低 AI 应用开发的门槛。它提供了：

• 可视化工作流编排：拖拽式界面，无需编码即可构建复杂 AI 应用
• 知识库管理**：支持多种数据源，自动文本分段与向量化
• 丰富的工具集成：内置多种工具，支持自定义 API 接入
• 一键部署：Docker Compose 快速启动，生产就绪

1.2 核心概念

工作流 vs 智能体：

1.3 适用场景

• 智能客服系统
• 企业知识问答
• 数据分析助手
• 内容生成工具
• 自动化工作流

2. 本地部署指南

2.1 环境要求

• Docker 20.10+
• Docker Compose 2.0+
• 至少 4GB 可用内存
• 20GB 可用磁盘空间

2.2 安装步骤

步骤 1：克隆仓库

git clone https://github.com/langgenius/dify.git cd dify 

步骤 2：配置环境变量

cddockercp .env.example .env #dokcer目录下的.env.example文件夹名改成.env

提示：可根据需要修改 .env 文件中的配置，如数据库密码、服务端口等。

步骤 3：启动服务

docker compose up -d

步骤 4：验证部署

docker compose ps

所有服务应显示为 running 状态。

2.3 初始配置

1. 浏览器访问 http://localhost
2. 设置管理员邮箱、用户名和密码
3. 完成初始化设置

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: 启动失败怎么办？

# 查看日志docker compose logs -f# 重启服务docker compose down &&docker compose up -d

Q: 如何重置管理员密码？

docker compose exec api flask reset-password [email protected] 

3. API 配置与集成

3.1 获取 API Key

1. 登录 Dify 控制台
2. 进入「设置」→「API 访问」
3. 点击「创建密钥」
4. 复制并妥善保存 API Key

3.2 API 调用示例

Python SDK

from dify import DifyClient client = DifyClient(api_key="your-api-key")# 发送对话请求 response = client.chat_messages( inputs={"query":"你好"}, user="user-123")print(response.json())

cURL 示例

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 限流与配额

4. 自定义工具开发

4.1 为什么需要自定义工具？

Dify 内置工具可能无法满足所有需求。当需要：

• 访问企业内部 API
• 调用第三方服务
• 执行特定业务逻辑

这时就需要开发自定义工具。

4.2 本地 API 公网穿透

由于 Dify 云端服务无法直接访问本地 API，需要使用穿透工具。

安装 localtunnel

npminstall-g localtunnel 

启动穿透服务

lt --port8081

输出示例：

your url is: https://random-name-123.local.lt 

安全加固

# 添加基本认证 lt --port8081--basic_auth username:password 

4.3 工具配置步骤

1. 在 Dify 中添加工具
   • 进入「工具」→「自定义工具」
   • 填写 API URL（使用穿透后的地址）
   • 配置请求方法和参数
   • 设置鉴权方式（如需要）
2. 测试工具
   • 使用「测试」功能验证连接
   • 检查响应格式是否符合预期

创建 API 端点

from flask import Flask, request, jsonify app = Flask(__name__)@app.route('/api/custom-tool', methods=['POST'])defcustom_tool(): data = request.json # 处理逻辑return jsonify({"result":"success"})if __name__ =='__main__': app.run(port=8081)

4.4 鉴权配置

Dify 支持多种鉴权方式：

5. 工作流类型详解

5.1 Workflow（工作流）

特点：

• 面向任务处理
• 批量执行
• 无状态或弱状态
• 适合数据处理、内容生成等场景

典型流程：

输入 → 预处理 → LLM 处理 → 后处理 → 输出 

适用场景：

• 文章摘要生成
• 数据清洗与转换
• 批量内容创作
• 报告自动生成

5.2 Chatflow（对话流）

特点：

• 面向对话交互
• 保持上下文状态
• 支持多轮对话
• 适合客服、助手等场景

典型流程：

用户输入 → 意图识别 → 知识库检索 → LLM 生成 → 回复用户 ↓ 多轮记忆 

适用场景：

• 智能客服
• 个人助手
• 咨询问答
• 情感陪伴

5.3 Workflow vs Chatflow 对比

5.4 选择建议

• 选择 Workflow：当你需要处理一批数据、生成固定格式内容、或执行自动化任务时
• 选择 Chatflow：当你需要与用户进行自然对话、保持上下文、或提供个性化服务时

6. 知识库管理

6.1 知识库的作用

知识库是 Dify 的 RAG（检索增强生成）核心，通过向量化存储私有数据，让 AI 能够：

• 回答基于企业内部文档的问题
• 提供准确的产品信息
• 避免大模型的幻觉问题

6.2 创建知识库流程

步骤 1：选择数据源

支持的数据源类型：

步骤 2：文本分段与清洗

分段策略：

清洗选项：

• 去除 HTML 标签
• 去除特殊字符
• 标准化空白字符
• 去除页眉页脚

步骤 3：向量化处理

Dify 使用嵌入模型将文本转换为向量：

文本 → [嵌入模型] → 向量 → [向量数据库] → 可检索 

支持的嵌入模型：

• OpenAI text-embedding-ada-002
• 本地部署的 BGE/M3E
• 其他兼容模型

步骤 4：完成索引

等待向量化完成后，知识库即可用于检索。

6.3 检索配置

6.4 最佳实践

1. 文档质量优先：确保源文档清晰、准确、无歧义
2. 合理分段：避免过长或过短的分段
3. 定期更新：及时同步最新的企业知识
4. 权限控制：敏感信息需要访问控制

7. 实战案例：跨境电商客服

7.1 场景描述

构建一个跨境电商智能客服系统，能够：

• 自动识别用户意图
• 处理常见问候和礼貌用语
• 转接人工服务
• 基于知识库回答专业问题

7.2 系统架构

用户输入 ↓ [意图识别节点] ├─→ 打招呼 → 固定回复 ├─→ 感谢语 → 礼貌回复 ├─→ 告别语 → 告别回复 ├─→ 人工服务 → 转接链接 └─→ 其他问题 → RAG 检索 → LLM 生成 

7.3 意图识别代码实现

import random import re defmain(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 可进入人工答疑"defnormalize_text(text:str)->str:"""标准化文本：去除标点符号，转换为小写""" cleaned = re.sub(r'[^\w\u4e00-\u9fff]','', text.lower().strip())return cleaned defexact_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:returnTruereturnFalsedefcontains_match_check(query_text:str, phrase_set)->bool:"""包含匹配检查（用于短查询中包含关键短语的情况）""" normalized_query = normalize_text(query_text)# 只有当查询很短时才使用包含匹配（避免误匹配）iflen(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:returnTruereturnFalse# 处理输入 query = query.strip()ifnot 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 工作流配置

1. 开始节点：接收用户输入
2. 代码节点：运行意图识别代码
3. 条件分支：
   • type == "greeting" → 直接回复
   • type == "human_service" → 返回人工链接
   • type == "rag_needed" → 知识库检索 → LLM 生成
4. 结束节点：输出最终回复

7.5 优化建议

1. 添加意图识别模型：使用分类模型替代规则匹配
2. 多语言支持：扩展短语库支持更多语言
3. 情感分析：识别用户情绪，调整回复策略
4. 会话记忆：记录用户历史问题，提供个性化服务

8. 实战案例：Text2SQL 数据库查询

8.1 场景描述

构建一个自然语言查询学生成绩的系统，用户可以用中文提问，系统自动生成 SQL 并执行。

8.2 数据库设计

CREATETABLE student_grades ( id INTPRIMARYKEYAUTO_INCREMENT, student_id VARCHAR(20)NOTNULL, student_name VARCHAR(50)NOTNULL, class_name VARCHAR(20), subject VARCHAR(30), score DECIMAL(5,2), exam_date DATE, semester VARCHAR(20), grade INT, created_at TIMESTAMPDEFAULTCURRENT_TIMESTAMP, updated_at TIMESTAMPDEFAULTCURRENT_TIMESTAMPONUPDATECURRENT_TIMESTAMP);

8.3 LLM 提示词设计

## 角色 你是一个专业的 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：

[{"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 安全考虑

1. 只读权限：数据库用户仅授予 SELECT 权限
2. 查询限制：限制返回行数（如 LIMIT 1000）
3. 超时控制：设置查询超时时间（如 30 秒）
4. 审计日志：记录所有生成的 SQL 用于审计

8.6 工作流配置

1. 开始节点：接收用户自然语言问题
2. LLM 节点：使用提示词生成 SQL
3. 代码节点：解析 JSON，提取 SQL 语句
4. 数据库工具：执行 SQL 查询
5. LLM 节点：将查询结果转换为自然语言回复
6. 结束节点：输出最终回复

9. 网页集成方案

9.1 嵌入式聊天窗口

Dify 提供嵌入式脚本，可直接集成到网页中：

<!-- 在 </body> 前添加 --><script> window.difyChatbotConfig ={token:'your-app-token',baseUrl:'https://your-dify-instance.com'}</script><scriptsrc="https://your-dify-instance.com/embed.min.js"id="your-app-token"defer></script>

9.2 自定义样式

.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 自定义事件监听

document.addEventListener('dify-chatbot-ready',function(){ console.log('聊天机器人已就绪');}); document.addEventListener('dify-chatbot-message',function(e){ console.log('收到消息：', e.detail);});

9.4 React/Vue 组件集成

// 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 />; } 

10. 总结与建议

10.1 核心优势

10.2 适用场景推荐

强烈推荐：

• 企业知识库问答
• 智能客服系统
• 内部工具自动化

可以考虑：

• 个人 AI 助手
• 内容生成工具
• 数据分析助手

需要评估：

• 高并发场景（需企业版）
• 复杂业务逻辑（可能需要自定义开发）
• 严格合规要求（需私有化部署）

10.3 学习路线

1. 入门：完成本地部署，熟悉界面
2. 基础：创建第一个工作流和知识库
3. 进阶：开发自定义工具，集成外部 API
4. 高级：优化性能，生产环境部署

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 版本编写，具体功能可能随版本更新有所变化。建议参考官方文档获取最新信息。