Dify零基础开发本地Agent智能体：从入门到实战

Dify零基础开发本地Agent智能体：从入门到实战

一、什么是Dify？为什么选择它？

Dify是一个开源的LLM应用开发平台，它最大的特点是将复杂的AI应用开发流程可视化、模块化，让你即使不懂代码，也能通过拖拽和配置的方式构建出功能强大的AI Agent。

对于零基础开发者来说，Dify有三大核心优势：

• 低代码甚至零代码：大部分功能通过界面配置即可完成，无需深究底层技术细节。
• 原生支持Agent能力：内置了ReAct、Function Calling等Agent框架，开箱即用。
• 完全本地化部署：数据不出本地，适合处理敏感信息或需要私有化部署的场景。

简单来说，Dify就像一个"AI应用组装工厂"，你只需要准备好模型和想法，剩下的交给平台来完成。

二、本地部署Dify（手把手教程）

2.1 硬件与软件要求

2.2 一键部署步骤

Dify官方提供了Docker Compose方式，这是最简单的部署路径：

第一步：克隆项目仓库

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

第二步：启动服务

# 复制环境变量模板
cp .env.example .env

# 启动所有容器
docker compose up -d

首次启动会自动下载所需的镜像文件（约2-3GB），请耐心等待。看到以下输出即表示启动成功：

✔ Container docker-web-1     Started
✔ Container docker-api-1     Started
✔ Container docker-worker-1  Started
✔ Container docker-nginx-1   Started

第三步：访问Dify控制台

打开浏览器，访问 http://localhost:8080，注册第一个管理员账号即可进入主界面。

小贴士：如果你是Windows用户，建议使用WSL2环境来运行Docker，兼容性更好。

三、核心概念速览

在动手开发之前，先理解Dify的四个核心概念：

3.1 应用（App）

应用是你最终交付给用户使用的AI产品形态。Dify支持三种应用类型：

• 聊天助手：纯粹的对话式交互
• 文本生成器：用于生成文章、报告等
• Agent：具备自主决策和工具调用能力的智能体

3.2 知识库（Knowledge）

知识库是Agent的"外脑"，用来存储你的私有数据（文档、FAQ、数据库记录等）。当用户提问时，Agent会先从知识库中检索相关信息，再结合大模型生成答案——这就是RAG（检索增强生成）的核心机制。

3.3 工具（Tools）

工具是Agent可以调用的外部能力，就像给Agent装上了"手和脚"。内置工具包括：

• 搜索引擎（Google、Bing）
• 计算器
• 网页爬虫
• 自定义API接口

3.4 工作流（Workflow）

工作流是Dify最强大的功能之一，它允许你用节点图的方式编排复杂的业务逻辑，例如：输入 → 知识库检索 → LLM推理 → 条件分支 → 输出。

四、实战：开发一个本地知识库问答Agent

现在，我们正式开始开发第一个Agent——一个能回答你本地文档问题的智能助手。

4.1 第一步：创建Agent应用

1. 登录Dify控制台，点击左侧菜单的"工作室"
2. 点击"创建应用"按钮
3. 选择"Agent"类型
4. 填写应用名称："我的本地知识助手"，点击确认

4.2 第二步：配置大模型

在Agent的设置页面，找到"模型配置"：

1. 模型提供商：选择"OpenAI"或"Azure OpenAI"，如果你有本地部署的模型（如Ollama），也可以选择"自定义模型"
2. 模型名称：选择gpt-4o-mini或gpt-3.5-turbo（兼顾效果与成本）
3. API密钥：填入你的API Key

本地模型替代方案：如果你不想依赖云端API，可以使用Ollama部署Qwen或Llama 3等开源模型，然后在Dify中添加"Ollama"作为模型提供商，填写本地地址（如 http://localhost:11434）即可。

4.3 第三步：创建知识库

这是让Agent回答本地问题的关键步骤：

1. 在左侧菜单点击"知识库"，然后点击"创建知识库"
2. 知识库名称：填写"公司内部文档"
3. 数据源：点击"添加文档"，选择"本地文件"
4. 上传文件：支持txt、pdf、docx、markdown等格式，一次可上传多个
5. 分段设置：Dify会自动将长文档切分成小段落，建议每段500-800个字符，重叠50-100个字符
6. Embedding模型：选择"text-embedding-3-small"或"BAAI/bge-m3"
7. 点击"保存并处理"，等待向量化完成（文档越多，时间越长）

完成后，你的知识库就建好了。

4.4 第四步：配置Agent工具

回到Agent设置页面，找到"工具"选项卡：

1. 点击"添加工具"
2. 勾选"知识库检索"工具
3. 选择刚才创建的"公司内部文档"知识库
4. 点击确认

现在，你的Agent已经具备了检索本地文档的能力。

4.5 第五步：编写系统指令（Prompt）

在Agent设置中找到"系统指令"输入框，填入以下提示词：

你是一个专业的公司知识助手，你的职责是帮助员工快速找到公司内部文档中的信息。

规则：
1. 当用户提问时，优先使用知识库检索工具查找相关信息
2. 如果知识库中没有相关信息，明确告知用户"抱歉，我未能从现有文档中找到答案"
3. 回答要简洁、准确，引用具体的文档来源
4. 不要编造信息，不要使用知识库以外的知识

这段指令让Agent明确了自己的角色和行为边界，有效避免"幻觉"问题。

4.6 第六步：测试与对话

点击右上角的"预览"或"运行"按钮，进入对话界面。尝试输入：

"我们公司的年假政策是什么？"

Agent会自动调用知识库检索工具，查找相关文档片段，然后基于检索结果生成回答。你可以在右侧看到Agent的"思考过程"——它调用了什么工具、检索到了哪些内容。

4.7 第七步：发布应用

测试满意后，点击"发布"按钮。Dify会生成一个可分享的链接或嵌入代码，你可以：

• 将链接发给团队成员使用
• 通过API接入到自己的网站或应用中
• 嵌入到飞书、钉钉等企业IM工具

五、进阶：让Agent调用自定义工具

当内置工具不够用时，你可以让Agent调用自己的API服务。

5.1 创建工具

1. 在"工具"页面，点击"创建自定义工具"
2. 选择"OpenAPI Schema"方式（兼容Swagger格式）
3. 填入API的URL、请求方法、参数说明
4. Dify会自动解析并生成工具描述

5.2 示例：查询天气

假设你有一个天气API：

• 地址：https://api.weather.com/current
• 参数：city（城市名）
• 返回：温度、天气状况

在Dify中配置好这个工具后，Agent就可以回答"北京今天天气怎么样？"这样的问题，自动调用你的天气API获取实时数据。

六、常见问题与解决方案

Q1：知识库检索不到相关内容？

• 检查文档格式：确保上传的文档是可解析的文本格式（PDF需为文字版而非扫描版）
• 调整分段大小：过小的分段会丢失上下文，过大的分段会降低检索精度
• 调整检索阈值：在知识库设置中降低"相似度阈值"，召回更多结果

Q2：Agent回答速度慢？

• 更换更快的模型：如gpt-4o-mini比gpt-4o响应更快
• 减少知识库检索数量：将"Top K"值从5降到3
• 检查网络延迟：如果是本地部署，确保容器资源充足

Q3：Dify如何连接本地Ollama？

1. 确保Ollama已启动并加载了模型（如ollama run qwen:7b）
2. 在Dify的"模型提供商"中选择"Ollama"
3. 填写Base URL：http://host.docker.internal:11434（Docker内访问宿主机）
4. 填写模型名称：qwen:7b
5. 保存即可

七、总结与下一步

通过本教程，你已经完成了：

• ✅ Dify的本地部署
• ✅ 第一个Agent应用的创建
• ✅ 知识库的构建与接入
• ✅ Agent的系统指令配置
• ✅ 自定义工具的扩展方法

接下来可以尝试的方向：

• 接入企业微信/飞书，让Agent成为团队共享助手
• 创建多Agent协作的工作流，实现复杂任务编排
• 结合爬虫工具，让Agent能主动抓取网页信息
• 通过API将Agent能力集成到自己的应用中

Dify的低代码特性让AI应用开发的门槛大幅降低，即使你只有产品思维而没有编程基础，也能快速将想法变成可用的Agent。关键在于多动手尝试，从一个具体的场景开始，逐步扩展功能边界。