Dify零基础开发本地Agent智能体
——从安装到部署，手把手构建你的第一个AI助手
前言：为什么选择Dify？
在智能体开发框架百花齐放的今天，Dify 凭借其独特的定位脱颖而出：

对比维度 LangChain/LangGraph AutoGen Dify
上手难度 高（需要Python熟练） 高（需要深入理解多智能体） 低（可视化操作+少量代码）
部署方式 仅代码 仅代码 本地/云端/Docker一键部署
LLM支持 需手写适配器 需手写适配器 内置50+模型提供商
知识库（RAG） 需集成LangChain 无原生支持 开箱即用的知识库管理
工作流编排 代码定义（LangGraph） 代码定义 可视化拖拽工作流
适用场景 深度定制开发 多智能体协作研究 快速原型验证、企业内部Agent
一句话定位： Dify = 开箱即用的智能体开发平台，让非AI专家也能在30分钟内搭建一个带知识库、工具调用、工作流的本地Agent。

第一章：Dify是什么？重新理解这个”AI操作系统”
1.1 核心架构
text
┌─────────────────────────────────────────────────────────┐
│ Dify 平台架构 │
├─────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 应用层 │ │ 工作流层 │ │ 知识库层 │ │
│ │ (Chatbot/ │ │ (可视化编排)│ │ (RAG检索) │ │
│ │ Agent) │ │ │ │ │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ └────────────────┼────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 模型中间层 (Model Gateway) │ │
│ │ OpenAI / Anthropic / 通义千问 / 智谱 / DeepSeek │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 工具层 (Tools) │ │
│ │ 内置工具 · 自定义API · MCP协议 · 代码执行 │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
1.2 核心概念速览
概念 通俗理解 你什么时候用它
应用（App） 一个完整的AI助手 每个业务场景创建1个App
工作流（Workflow） Agent的执行流程图 需要多步骤、有分支逻辑时
知识库（Knowledge） AI的”外挂大脑” 需要基于私有数据回答时
工具（Tools） AI的手和脚 需要调用API、查数据库、发邮件时
变量（Variables） 工作流中的”便签纸” 需要暂存中间结果时
节点（Nodes） 工作流中的每一步 可视化拖拽的那些方块
第二章：零基础起步——5分钟本地部署Dify
2.1 最低硬件要求
配置项 最低要求 推荐配置
CPU 2核 4核+
内存 4GB 8GB+
硬盘 20GB 50GB+
Docker 20.10+ 最新版
网络 能访问LLM API 稳定的外网连接
2.2 一键部署（Docker Compose方式）
这是最简单、最推荐的本地部署方式：

Step 1：克隆项目

bash
git clone github.com/langgenius/dify.git
cd dify/docker
Step 2：启动服务

bash

复制环境变量模板

cp .env.example .env

启动所有服务（PostgreSQL + Redis + Weaviate + Dify API + Dify Web）

docker-compose up -d
Step 3：验证部署

bash

查看容器状态

docker-compose ps

应该看到5个容器都在运行（状态为 Up）

Step 4：访问Dify

text
浏览器打开：localhost:3000
注册第一个账号（本地部署，无需邮箱验证）
🎉 恭喜！ 你已经拥有了一套完整的本地智能体开发环境。

2.3 配置你的第一个模型提供商
进入Dify后台 → 设置 → 模型提供商 → 添加你的API Key：

text
┌─────────────────────────────────────────────┐
│ 推荐配置（三选一即可） │
├─────────────────────────────────────────────┤
│ ☑ OpenAI: sk-xxx… (GPT-4o/GPT-4o-mini) │
│ ☑ 通义千问: sk-xxx… (qwen-max) │
│ ☑ DeepSeek: sk-xxx… (deepseek-chat) │
│ │
│ 💡 本地LLM爱好者可选：Ollama + Llama 3.1 │
└─────────────────────────────────────────────┘
第三章：你的第一个Agent——“本地知识库问答助手”
3.1 场景定义
需求： 公司内部有一个《员工手册》PDF，希望AI能基于这份手册回答员工关于休假、报销、考勤等问题。

3.2 Step 1：创建知识库
text
操作路径：知识库 → 创建知识库
配置参数：

配置项 推荐值 说明
名称 员工手册知识库 便于识别
分段规则 自动分段 默认即可
分段最大长度 500 tokens 太长影响检索精度
重叠长度 50 tokens 避免上下文断裂
嵌入模型 text-embedding-3-small 性价比最高
检索方式 混合检索（Hybrid） 关键词+向量，效果最好
上传文档：

bash

支持格式：PDF、Word、TXT、Excel、Markdown、HTML

拖拽上传你的《员工手册.pdf》

等待索引完成（约1-3分钟，取决于文档大小）

✅ 完成后，知识库状态变为”可用”，并显示文档片段数量。

3.3 Step 2：创建基础应用（聊天助手）
text
操作路径：工作室 → 创建空白应用 → 选择”聊天助手”
基础配置：

text
┌─────────────────────────────────────────────┐
│ 应用名称：员工助手 │
│ 应用模式：聊天助手 │
│ 模型：GPT-4o-mini / DeepSeek-chat │
│ 上下文窗口：8K │
│ 温度：0.3（事实性问答要偏低） │
└─────────────────────────────────────────────┘
3.4 Step 3：关联知识库 + 编写提示词
在”上下文”中，添加你的知识库：

text
点击”添加上下文” → 选择”员工手册知识库”
系统提示词（关键！）：

text
你是一位专业的公司HR助手，专门回答员工关于公司制度的问题。

知识库使用规则

1. 优先使用【知识库】中的内容回答，不要依赖自己的训练数据
2. 如果知识库中没有相关信息，请明确告知：”手册中暂未找到相关条款，建议咨询HR部门”
3. 引用知识库内容时，标注出处（如：根据《员工手册》第三章第2条）

回答规范

• 态度友好、专业
• 回答简洁明了，分点呈现
• 涉及数字/日期时，务必核实准确

禁止行为

• 不要编造政策条款
• 不要给出法律建议
• 不要推测知识库外的内容

3.5 Step 4：测试你的第一个Agent
在右侧对话窗输入：

text
👤 用户：请问公司年假怎么计算？

🤖 Agent：根据《员工手册》第五章”休假制度”第3条规定：

1. 入职满1年的员工，享有5天带薪年假
2. 入职满5年，年假增加至10天
3. 入职满10年，年假增加至15天
   年假需在当年度内使用完毕，不可累积至下一年。

如需申请年假，请在OA系统中提交《休假申请表》。
text
👤 用户：我入职半年，有年假吗？

🤖 Agent：根据知识库中的《员工手册》，年假资格需”入职满1年”。
您目前入职半年，暂不满足年假条件。
建议您查阅”调休假”相关政策（手册第六章），或咨询HR部门。
✅ 成功了！ 你的第一个本地知识库Agent已经可以回答私有问题了。

第四章：进阶实战——带工具调用的”代码执行助手”
4.1 场景定义
需求： 用户用自然语言描述”帮我分析这个Excel销售数据，找出异常值”，Agent能自动生成Python代码→执行→返回分析结果。

4.2 Step 1：开启代码执行工具
text
操作路径：应用设置 → 工具 → 添加工具 → 选择”代码执行器”
代码执行器配置：

配置项 设置 说明
执行环境 Python 3.11 内置安全沙箱
超时时间 30秒 防止死循环
允许的包 pandas, numpy, matplotlib, scikit-learn 数据分析常用库
存储空间 临时目录 每次执行独立
⚠️ 安全提示： 代码执行器在沙箱中运行，但仍有风险。不要在生产环境中开放给未受信任的用户。

4.3 Step 2：编写工作流
这次我们不用”聊天助手”模式，改用工作流（Workflow）模式，实现更复杂的逻辑：

text
操作路径：工作室 → 创建空白应用 → 选择”工作流”
工作流设计（可视化拖拽）：

text
┌────────────┐
│ 开始节点 │ ← 接收用户输入（”分析这个Excel”）
│ (Start) │
└─────┬──────┘
│
▼
┌────────────┐
│ 文件接收 │ ← 用户上传Excel文件
│ (File) │
└─────┬──────┘
│
▼
┌────────────┐
│ LLM节点 │ ← 分析用户意图，生成分析计划
│ “计划者” │ Prompt: “用户想要分析什么？需要哪些步骤？”
└─────┬──────┘
│
▼
┌────────────┐
│ 代码执行 │ ← 根据计划生成并执行Python代码
│ (Code) │ 输出：统计摘要、异常值列表、图表Base64
└─────┬──────┘
│
▼
┌────────────┐
│ LLM节点 │ ← 将代码执行结果转化为自然语言
│ “解释者” │ Prompt: “用通俗语言告诉用户分析结论”
└─────┬──────┘
│
▼
┌────────────┐
│ 结束节点 │ ← 返回最终回答
│ (End) │
└────────────┘
4.4 Step 3：关键节点配置详解
节点1：”计划者” LLM节点
yaml
节点名称: 计划者
模型: GPT-4o-mini
温度: 0.1

Prompt:

你是一个数据分析专家。用户上传了一个Excel文件，内容是销售数据。

请根据用户的描述，生成一个Python数据分析计划，输出为JSON格式：
{
“steps”: [
“读取Excel文件”,
“检查数据完整性（空值、重复值）”,
“计算基础统计量（均值、中位数、标准差）”,
“使用IQR方法检测异常值”,
“生成可视化图表”
],
“key_columns”: [“销售额”, “利润”, “数量”],
“chart_type”: “箱线图”
}

用户描述：{{user_input}}

输出变量: plan
节点2：”代码执行”节点
yaml
节点名称: 代码执行器
语言: python3

代码模板:

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import io
import base64
import json

读取用户上传的文件

df = pd.read_excel(‘{{uploaded_file_path}}’)

根据计划执行分析

plan = {{plan}}

results = {}

1. 基础统计

stats = df.describe().to_dict()
results[‘statistics’] = stats

2. 异常值检测（IQR方法）

Q1 = df[‘销售额’].quantile(0.25)
Q3 = df[‘销售额’].quantile(0.75)
IQR = Q3 - Q1
lower_bound = Q1 - 1.5 * IQR
upper_bound = Q3 + 1.5 * IQR
outliers = df[(df[‘销售额’] < lower_bound) | (df[‘销售额’] > upper_bound)]
results[‘outliers’] = outliers.to_dict(‘records’)
results[‘outlier_count’] = len(outliers)

3. 生成箱线图

plt.figure(figsize=(10, 6))
plt.boxplot(df[‘销售额’].dropna())
plt.title(‘销售额分布箱线图’)
buf = io.BytesIO()
plt.savefig(buf, format=’png’)
buf.seek(0)
chart_base64 = base64.b64encode(buf.read()).decode(‘utf-8’)
results[‘chart’] = chart_base64

输出结果

print(json.dumps(results, ensure_ascii=False))

输出变量: analysis_result
节点3：”解释者” LLM节点
yaml
节点名称: 解释者
模型: GPT-4o-mini
温度: 0.5

Prompt:

你是数据分析解说员。你收到了代码执行的结果，需要用通俗易懂的语言告诉用户。

数据统计结果：{{analysis_result.statistics}}
异常值数量：{{analysis_result.outlier_count}}
异常值详情：{{analysis_result.outliers}}

请按以下格式回答：

1. 📊 数据概览：用一句话概括数据规模和主要特征
2. 🔍 关键发现：列出3-5个最重要的洞察
3. ⚠️ 异常提醒：说明异常值的情况和可能原因
4. 💡 建议：给出下一步操作建议

注意：语气友好，避免过多专业术语。

输出变量: final_response
4.5 Step 4：测试运行
在对话窗上传Excel文件并输入：

text
👤 用户：帮我分析这个销售数据，看看有没有异常的订单

🤖 Agent（工作流执行中…）：
📊 数据概览
您的数据包含1,247条订单记录，覆盖2026年1-6月，总销售额为3,284,567元。

🔍 关键发现

1. 月均销售额约54.7万元，6月份销售额最高（89.2万）
2. 平均客单价为2,634元，中位数为2,180元
3. 华东地区贡献了42%的销售额，是主力区域

⚠️ 异常提醒
检测到 12笔异常订单（占总订单的0.96%）：

• 3笔订单金额 > 15,000元（远超均值）
• 9笔订单金额 < 200元（明显偏低）
• 建议重点关注这些订单是否存在录入错误或特殊折扣

💡 建议

1. 核查12笔异常订单的具体情况
2. 建议按月维度做同比分析，判断6月高增长是否可持续
3. 可针对华东地区制定针对性营销策略

[📈 箱线图已生成，可点击查看]
🎉 恭喜！ 你已经搭建了一个能自动写代码、执行分析、生成图表的智能体。

第五章：深度进阶——Dify的杀手级功能
5.1 多模型路由（Model Router）
当你有多个模型提供商时，Dify可以根据任务类型自动选择最优模型：

text
配置示例：

• 简单问答 → DeepSeek (成本低)
• 复杂推理 → GPT-4o (能力强)
• 代码生成 → Claude 3.5 Sonnet (代码质量高)
• 知识库检索 → 通义千问 (中文理解好)
  应用场景： 企业可以通过多模型路由在成本与质量之间取得最优平衡。

5.2 MCP协议支持（Model Context Protocol）
Dify 已集成 Anthropic提出的MCP协议，让Agent可以调用外部工具服务器：

text
┌──────────────┐ MCP协议 ┌──────────────┐
│ Dify Agent │ ◄──────────────► │ 工具服务器 │
│ │ │ - 数据库查询 │
│ │ │ - Git操作 │
│ │ │ - 邮件发送 │
│ │ │ - Slack通知 │
└──────────────┘ └──────────────┘
实战示例： 构建一个”智能运维Agent”，可以通过MCP连接到Prometheus查询监控指标，发现异常时自动创建Jira工单。

5.3 子工作流（Sub-Workflow）
当一个工作流过于复杂时，可以拆分为多个子工作流：

text
主工作流：处理用户订单退款
├── 子工作流1：验证用户身份
│ ├── 查用户表
│ └── 验证支付信息
├── 子工作流2：计算退款金额
│ ├── 计算折扣
│ └── 计算已用积分
└── 子工作流3：执行退款
├── 调用支付网关
├── 更新订单状态
└── 发送通知
好处： 子工作流可以复用，且每个子工作流可独立调试。

5.4 变量聚合与条件分支
text
┌─────────────┐
│ 查询用户等级 │ → 变量: user_level
└──────┬──────┘
│
▼
┌───┴───┐
│ 条件判断│
└───┬───┘
│
┌───┴───────────────────────────┐
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ VIP用户 │ │ 普通用户 │
│ 折扣95折 │ │ 原价 │
└─────────┘ └─────────┘
第六章：生产环境部署——让Agent真正跑起来
6.1 从”测试”到”生产”的6个关键步骤
步骤 操作 检查项
1 使用专用数据库 PostgreSQL 独立实例，开启备份
2 配置Redis持久化 防止对话记录丢失
3 设置模型API限流 防止成本失控
4 开启操作日志审计 记录所有Agent调用
5 设置知识库自动更新 文档变更时自动重新索引
6 配置监控告警 错误率、响应时间、Token消耗
6.2 使用环境变量覆盖配置
bash

.env 生产环境配置

数据库连接

DB_USERNAME=dify_prod
DB_PASSWORD=你的强密码
DB_HOST=postgres-prod.example.com

Redis配置

REDIS_HOST=redis-prod.example.com
REDIS_PASSWORD=你的redis密码

模型限流

MODEL_RATE_LIMIT=100/minute

日志级别

LOG_LEVEL=INFO

安全设置

SECRET_KEY=你的密钥
ADMIN_EMAIL=admin@company.com
6.3 性能优化建议
优化项 推荐方案
知识库检索速度 使用Qdrant替代默认Weaviate（更快的向量检索）
大文档处理 开启并行分段，充分利用多核CPU
对话历史 设置对话压缩，超过阈值时自动摘要
缓存 启用语义缓存，相似问题直接返回缓存结果
第七章：实战模板库——直接复制使用
模板1：智能客服Agent
yaml
应用模式: 聊天助手
知识库: 产品文档 + FAQ
工具: 无
温度: 0.3

Prompt核心:
你是XX公司官方客服。回答必须基于知识库。
如果知识库没有答案，引导用户留下联系方式，承诺24小时内人工回复。
情感基调：耐心、同理心，解决不了问题时要真诚道歉。
模板2：代码审查Agent
yaml
应用模式: 工作流
节点: 代码接收 → 代码分析 → 安全扫描 → 生成报告
工具: 代码执行器（静态分析）

Prompt核心:
审查代码时关注：安全性（SQL注入、XSS）、性能（N+1查询）、可维护性（圈复杂度）、规范（命名、注释）。
输出格式：通过/不通过 + 具体问题列表 + 修改建议。
模板3：周报生成Agent
yaml
应用模式: 工作流
输入: Jira任务列表 + Git提交记录 + 日历事件
工具: API调用（Jira、GitHub、Google Calendar）
温度: 0.7

Prompt核心:
根据输入数据，生成结构化的周报：

1. 本周完成（按项目分类）
2. 进行中（状态+进度）
3. 下周计划
4. 风险与问题
   风格：简洁、数据驱动、有洞察。
   模板4：私有知识库问答（含权限控制）
   yaml
   应用模式: 聊天助手
   知识库: 多个（按部门切分）
   工具: 无
   温度: 0.1

高级配置:

• 开启”知识库权限”：不同用户组访问不同知识库
• 开启”引用溯源”：每个回答附带文档来源链接
• 开启”负反馈收集”：用户可标记错误回答，用于迭代优化
  第八章：常见问题排雷
  Q1：知识库检索不到相关内容？
  排查清单：

文档是否已成功索引？（查看片段数）

分段大小是否合适？（太大会稀释语义，太小会丢失上下文）

是否开启了混合检索？（纯向量检索容易漏）

用户问题是否太模糊？（引导用户提供更多关键字）

Q2：Agent总是”胡说八道”（幻觉）怎么办？
策略 Dify实现方式
强制使用知识库 提示词中写”必须基于知识库回答，否则说不知道”
降低温度 设为0.1-0.3，减少随机性
开启引用溯源 让AI在回答中附上知识库片段原文
使用Rerank模型 提升检索Top-K的精准度
Q3：工作流执行太慢？
优化方法：

将多个LLM节点合并（减少往返次数）

使用更快的模型（如GPT-4o-mini替代GPT-4o）

启用节点缓存（相同输入跳过执行）

优化知识库检索（减少Top-K数量）

Q4：本地部署的Dify如何备份？
bash

备份数据库

docker exec -t dify-db pg_dump -U postgres dify > backup_$(date +%Y%m%d).sql

备份知识库向量数据（Weaviate）

docker exec -t dify-weaviate tar -czf - /var/lib/weaviate > weaviate_backup_$(date +%Y%m%d).tar.gz

备份上传文件

tar -czf uploads_backup_$(date +%Y%m%d).tar.gz ./docker/volumes/app/uploads
结语：从”会用”到”用好”的进化之路
阶段 能力 时间估计
入门 能搭建聊天助手 + 知识库问答 1天
进阶 能搭建带工具调用的工作流 3天
精通 能设计多模型路由 + 子工作流组合 2周
专家 能优化性能 + 处理复杂业务场景 1个月
最后送给你三个关键心法：

不要在提示词上偷懒。 一个精心设计的系统提示词，比换模型更有效。投入时间打磨Prompt，回报率极高。

先跑通再优化。 不要一开始就追求完美的工作流。先用最简单的”聊天助手”跑通核心逻辑，再逐步替换为工作流。

知识库是灵魂。 Dify最强的能力是RAG（检索增强生成）。花精力整理你的知识文档，这比调参重要10倍。

本作品采用《CC 协议》，转载必须注明作者和本文链接