基于Dify平台从零构建AI Agent工作流：本地部署与实战指南

在实际 AI 应用开发中从零开始构建一个功能完整、可维护的智能体Agent或工作流往往需要处理模型调用、上下文管理、工具集成、状态流转等一系列复杂问题。Dify 作为一个开源的 LLM 应用开发平台将 Prompt 工程、Agent 逻辑、知识库检索和工作流编排等能力进行了可视化封装极大地降低了开发门槛。对于希望快速上手 AI 应用开发的工程师来说理解 Dify 的核心概念并掌握其工作流搭建方法是构建从简单对话到复杂企业级项目的一条高效路径。本文旨在为初学者和希望快速实践的开发者提供一个清晰的入门指南。我们将从 Dify 的核心概念讲起逐步完成本地环境的部署然后通过构建一个具体的 Agent 工作流项目来演示如何将 Prompt 设计、工具调用和条件分支等环节串联起来。最终你将能够理解 Dify 工作流的运行机制并具备搭建满足特定业务需求的自定义 AI 应用的能力。1. 理解 Dify从 Prompt 到工作流的演进在深入动手之前我们需要厘清几个核心概念这有助于理解 Dify 要解决的问题以及它如何简化 AI 应用开发。1.1 Prompt、Agent 与工作流的关系很多开发者最初接触 AI 应用是通过直接向大语言模型LLM发送一段文本指令即 Prompt。这种方式简单直接但功能单一难以处理复杂逻辑。例如一个简单的天气查询 Prompt 可能是“告诉我北京今天的天气。” 这只是一个单次请求-响应。当任务变得复杂比如“查询北京天气如果下雨就推荐室内活动并生成一份活动清单”单次 Prompt 就力不从心了。这时就需要引入Agent智能体的概念。Agent 可以理解为一段能自主理解目标、规划步骤、调用工具如搜索、计算、API并执行行动的程序。它内部通常包含一个“大脑”LLM来决策以及“手脚”工具来执行。而工作流Workflow则是将 Agent 的执行逻辑进行可视化、模块化编排的一种方式。它把复杂的任务拆解成一个个可复用的节点如 LLM 调用、代码执行、条件判断、API 请求并通过有向连线定义节点间的数据流转和依赖关系。Dify 的核心价值就是提供了一个低代码界面让开发者可以通过拖拽这些节点来构建复杂的 AI 应用而无需编写大量的胶水代码。1.2 Dify 的核心组件与定位Dify 并非只是一个 Prompt 管理工具它是一个涵盖开发、部署、运营全流程的平台。对于开发者而言最需要关注的是其应用构建层面的几个核心组件文本生成应用/对话应用这是基础形态相当于一个配置了系统 Prompt、可选知识库的聊天界面。适合构建客服机器人、内容生成等场景。工作流这是 Dify 的进阶能力。你可以像搭积木一样将 LLM 模型、提示词模板、条件判断、变量处理、外部工具调用等节点连接起来形成一个自动化流程。它适合处理有固定步骤、需要决策或与外部系统交互的复杂任务。Agent在工作流中可以通过“工具”节点来赋予 LLM 调用外部能力这本质上就是在构建一个 Agent。Dify 的 Agent 能力是内嵌在工作流引擎中的。知识库可以为应用绑定知识库实现基于私有文档的问答RAG。在工作流中知识库检索可以作为一个节点被调用。简单来说Prompt 是原料Agent 是厨师工作流是菜谱Dify 就是整个厨房。它提供了灶具模型、厨具工具、食材库知识库和一套可视化的做菜流程设计器工作流编辑器。2. 环境准备与 Dify 本地部署为了获得最佳的学习和控制体验我们选择在本地部署 Dify。这能让你完全掌控数据和服务方便进行调试和定制化开发。2.1 系统与环境要求Dify 支持多种部署方式包括 Docker Compose、Kubernetes 和直接源码部署。对于大多数开发和学习场景Docker Compose是最简单、最推荐的方式。在开始前请确保你的开发环境满足以下要求组件要求检查命令说明操作系统Linux, macOS, Windows (WSL2)uname -a或systeminfoWindows 用户强烈建议使用 WSL2。Docker20.10.0 或更高版本docker --version负责容器化运行 Dify 及其依赖。Docker Compose2.0.0 或更高版本docker compose version负责编排多容器应用。CPU/RAM建议 4核 CPU / 8GB RAM 以上-运行 LLM 模型需要较多资源仅运行框架可适当降低。磁盘空间至少 10GB 可用空间df -h用于存放镜像、数据库和向量数据库数据。注意如果你在 Windows 上操作请先安装并配置好 WSL2例如 Ubuntu 发行版然后在 WSL2 终端中执行后续的 Docker 命令。直接在 Windows PowerShell 中操作可能会遇到路径和权限问题。2.2 使用 Docker Compose 一键部署这是最快捷的部署方式。Dify 官方维护了一个docker-compose.yaml文件它包含了 Web 前端、后端 API 服务器、数据库PostgreSQL、缓存Redis和向量数据库Weaviate等所有必需服务。获取部署文件打开终端在一个你喜欢的目录下例如~/projects执行以下命令克隆部署仓库。# 克隆部署代码仓库 git clone https://github.com/langgenius/dify.git # 进入 docker 部署目录 cd dify/docker启动 Dify 服务在docker目录下运行docker compose命令启动所有服务。# 在后台启动所有服务 docker compose up -d首次执行会从 Docker Hub 拉取所有镜像这取决于你的网络速度可能需要几分钟。完成后你会看到类似下面的输出表明五个容器都已成功启动。[] Running 6/6 ✔ Network docker_default Created ✔ Container docker-redis-1 Started ✔ Container docker-weaviate-1 Started ✔ Container docker-db-1 Started ✔ Container docker-api-1 Started ✔ Container docker-web-1 Started验证服务状态使用以下命令检查容器是否正常运行。docker compose ps你应该看到所有服务的状态State都是Up。访问 Dify 控制台在浏览器中打开http://localhost:3000。如果一切正常你将看到 Dify 的初始化页面按照指引完成管理员账号的注册。至此一个完整的 Dify 平台就在你的本地运行起来了。2.3 常见部署问题排查如果在部署或访问过程中遇到问题可以按照以下顺序排查问题现象可能原因检查与解决方式docker compose up -d失败提示端口冲突本地 3000、5432、6379、8080 等端口被占用。1. 使用netstat -tulnp | grep 端口号查找占用进程。2. 修改docker-compose.yaml文件中服务的ports映射如将3000:3000改为3001:3000。访问localhost:3000连接被拒绝容器未成功启动防火墙规则阻止WSL2 网络问题。1. 运行docker compose logs web查看前端容器日志。2. 运行docker compose logs api查看后端容器日志。3. 在 WSL2 中尝试curl localhost:3000。注册账号后无法登录或页面白屏浏览器缓存问题API 服务异常。1. 清除浏览器缓存或使用无痕模式。2. 检查docker compose logs api是否有数据库连接错误。3. 重启服务docker compose down docker compose up -d。工作流中连接模型超时未配置模型供应商如 OpenAI、通义千问等的 API Key。需要在 Dify 控制台 “设置” - “模型供应商” 中添加并配置可用的 LLM API。这是后续步骤的关键。3. 从零搭建你的第一个 Agent 工作流现在我们进入实战环节。假设我们要构建一个“智能旅行助手”Agent。它的功能是根据用户输入的目的地和天数自动规划行程并查询目的地的当前天气作为出行建议的一部分。这个工作流将包含接收用户输入 - 调用 LLM 生成行程草案 - 调用天气查询工具 - 整合信息生成最终建议。3.1 前期配置连接大模型Dify 本身不提供大模型它需要连接外部的模型 API。我们以使用广泛的 OpenAI GPT 系列为例你也可以配置国内如通义千问、智谱 AI 等。登录 Dify 控制台点击左下角 “设置” - “模型供应商”。点击 “添加模型供应商”选择 “OpenAI”。在配置页面填入你的 OpenAI API Key。如果你没有可以暂时使用 Dify 提供的测试 Key可能有速率限制或配置其他支持的模型。在 “模型” 列表里确保至少有一个模型状态是 “可用”例如gpt-3.5-turbo。记下你在配置中为这个模型设置的名称如gpt-35-turbo。3.2 创建工作流与应用在 Dify 首页点击 “创建工作流”。给工作流起一个名字如 “智能旅行规划助手”点击创建。系统会自动进入工作流画布。你会看到一个以 “开始” 节点和 “结束” 节点构成的空流程。在开始节点上我们需要定义用户输入。点击 “开始” 节点在右侧面板的 “变量” 选项卡点击 “添加输入变量”。变量名destination类型文本描述旅行目的地例如北京、上海必填勾选同样方式再添加一个输入变量变量名days类型数字描述旅行天数例如3必填勾选 这样工作流启动时就会要求用户提供这两个参数。3.3 编排核心工作流节点我们的目标是构建这样一个流程开始-LLM生成行程-查询天气-LLM整合建议-结束。第一步添加 LLM 节点生成行程草案从左侧节点库的 “基础” 分类中拖拽一个 “LLM” 节点到画布放在 “开始” 和 “结束” 节点之间。将 “开始” 节点的输出点右侧连接到 LLM 节点的输入点左侧。点击这个 LLM 节点进行配置模型选择你之前配置好的模型如gpt-35-turbo。上下文保持默认。提示词这是核心。我们需要编写一个 Prompt让它利用用户输入的destination和days变量。在提示词编辑框中输入你是一个专业的旅行规划师。请为一位计划前往 {{destination}} 旅行 {{days}} 天的游客生成一份详细的行程规划草案。 草案需要包含每天上午、下午、晚上的主要活动建议并注明活动类型如观光、美食、文化体验等。 请以清晰的列表形式输出。变量系统会自动识别{{destination}}和{{days}}作为变量。确保它们映射正确。将这个 LLM 节点的名称改为 “生成行程草案”。第二步添加 HTTP 请求节点查询天气模拟工具调用现实中我们需要调用一个真实的天气 API。这里我们用一个模拟的公开 API 来演示。从左侧 “工具” 分类中拖拽一个 “HTTP 请求” 节点到画布放在第一个 LLM 节点下方。将第一个 LLM 节点的输出连接到 HTTP 请求节点的输入。配置 HTTP 请求节点名称查询目的地天气URLhttps://restapi.amap.com/v3/weather/weatherInfo这里以高德地图天气API为例你需要自行申请Key或使用其他模拟API方法GET参数点击 “添加参数”。key你的高德API Key这是一个需要保密的变量应在环境变量中配置city{{destination}}这里简单映射实际需要城市编码处理响应由于我们只是演示可以简单地将整个响应体作为输出。在 “输出变量” 部分添加一个变量如weather_result选择 “响应体JSON”。注意在实际企业级项目中你会将 API Key 等敏感信息配置在 Dify 的“环境变量”中然后在节点里通过{{#env.YOUR_KEY#}}的形式引用避免硬编码。第三步添加第二个 LLM 节点整合最终建议再拖拽一个 “LLM” 节点到画布放在 HTTP 请求节点下方。将 HTTP 请求节点的输出连接到这个 LLM 节点的输入。配置这个 LLM 节点名称生成最终旅行建议模型同上。提示词你是一名贴心的旅行顾问。以下是一份旅行行程草案和目的地当前的天气信息。 请将两者结合为游客生成一份最终的、贴心的旅行建议。 【行程草案】 {{#生成行程草案.output#}} 【天气信息】 {{#查询目的地天气.output.weather_result#}} 请根据天气情况对行程草案提出调整建议例如下雨天推荐室内活动并补充穿衣、出行等方面的温馨提示。 最终输出应友好、详尽、具有可操作性。变量确保{{#生成行程草案.output#}}和{{#查询目的地天气.output.weather_result#}}正确映射了上游节点的输出。最后将这个 LLM 节点的输出连接到 “结束” 节点。第四步保存并测试点击画布右上角的 “保存” 按钮。点击右上角的 “发布” 按钮将此工作流版本发布。发布后点击 “测试” 选项卡。在测试面板中输入destination为 “杭州”days为 “3”然后点击 “运行”。观察画布上节点的运行状态它们会亮起并在右侧查看每个节点的输入输出详情特别是最后一个 LLM 节点的最终输出。通过这个流程你已亲手构建了一个串联 Prompt 设计、LLM 调用和外部工具HTTP API的简易 Agent。Dify 工作流引擎负责管理节点间的数据传递和异步执行。4. 工作流进阶条件判断、循环与错误处理基础的工作流是线性的。但真实场景中的 Agent 需要做决策条件判断和重复尝试循环并妥善处理失败。4.1 使用条件分支节点假设我们的旅行助手在查询天气时如果遇到 API 失败或返回“城市不存在”应该走另一条分支生成一个不包含天气信息的通用建议而不是让整个流程失败。在 “查询目的地天气” HTTP 请求节点后从左侧 “高级” 分类拖拽一个 “条件判断” 节点。将 HTTP 请求节点的输出连接到条件判断节点的输入。配置条件判断节点名称天气查询是否成功我们需要根据 HTTP 响应的状态码或内容来设置条件。点击 “添加条件”。变量选择选择上游节点输出例如查询目的地天气.output.status_code。比较方式等于。值200。这定义了一个分支如果状态码等于 200则视为成功走 “是” 分支否则走 “否” 分支。现在调整连线将条件判断节点的 “是” 输出连接到 “生成最终旅行建议” LLM 节点。这意味着天气查询成功时使用包含天气信息的 Prompt。我们需要为 “否” 分支创建另一个 LLM 节点。拖拽一个新的 LLM 节点命名为生成无天气建议。配置其提示词为“基于以下行程草案生成一份旅行建议。注意目前无法获取目的地实时天气请提醒用户自行查询天气并做好应变准备。行程草案{{#生成行程草案.output#}}”将条件判断节点的 “否” 输出连接到这个新 LLM 节点。最后将生成无天气建议节点和生成最终旅行建议节点的输出都连接到 “结束” 节点。Dify 支持多个节点汇聚到结束节点。4.2 错误处理与重试机制对于可能 transient failure临时失败的操作如网络请求可以配置重试。点击 “查询目的地天气” HTTP 请求节点。在右侧配置面板的底部找到 “重试” 配置。可以设置 “最大重试次数”如 2 次和 “重试间隔”如 1000 毫秒。这样当第一次请求失败非 2xx 状态码系统会自动按间隔重试直到成功或达到最大次数。重试后若仍失败节点状态会标记为失败流程会继续向下游条件判断节点传递失败状态从而触发我们的 “否” 分支。4.3 使用变量赋值与代码节点进行数据处理有时需要对上游节点的输出进行加工比如从复杂的 JSON 响应中提取某个字段。可以使用 “变量赋值” 或 “代码执行” 节点。变量赋值节点适合简单的提取和转换。例如在 HTTP 请求节点后添加一个变量赋值节点将{{#查询目的地天气.output.weather_result.lives[0].weather#}}赋值给一个新变量simple_weather供下游节点使用。代码执行节点Python适合复杂的逻辑处理。你可以编写 Python 脚本处理上游变量并输出新的变量。这极大地扩展了工作流的能力边界。5. 企业级项目实战考量与最佳实践将上述 demo 工作流应用于真实企业环境还需要考虑诸多工程化因素。5.1 配置管理与环境隔离敏感信息管理绝对不要在提示词或节点配置中硬编码 API Key、数据库密码等。务必使用 Dify 提供的“环境变量”功能。在“设置”-“环境变量”中定义在节点中使用{{#env.API_KEY#}}引用。多环境配置开发、测试、生产环境应使用不同的模型供应商配置、API 端点甚至变量。Dify 应用本身可以发布到不同环境但基础配置如模型供应商是全局的。企业部署时可能需要维护多套 Dify 实例或通过更精细的权限控制来隔离。5.2 性能、监控与日志超时设置为 LLM 节点和 HTTP 请求节点设置合理的超时时间避免单个节点阻塞整个工作流。监控看板Dify 提供了应用级别的访问统计、Token 消耗和平均响应时间。对于工作流需要关注每个节点的平均执行耗时定位瓶颈。日志排查当工作流运行出错时在“日志与异常”页面可以查看完整的执行轨迹。每个节点的输入、输出、错误信息都会被记录这是排查问题的第一现场。确保在开发阶段就养成查看日志的习惯。5.3 工作流设计最佳实践模块化设计将复杂的流程拆分成多个子工作流。Dify 支持“工作流作为节点”调用。例如将“行程生成”和“天气查询与整合”分别做成子工作流主工作流进行组装。这提高了复用性和可维护性。清晰的变量命名使用有意义的变量名如user_query,raw_itinerary,formatted_advice避免a,b,temp这样的命名。充分的错误处理如前所述对每一个可能失败的外部调用LLM、API、数据库都要设计失败分支提供降级方案或友好的错误提示。版本控制与回滚Dify 的工作流发布有版本概念。每次重大修改前先保存一个版本。如果新版本有问题可以快速回滚到上一个稳定版本。压力测试对于预计有高并发访问的工作流需要进行压力测试评估其在高负载下的稳定性和响应时间特别是关注 LLM API 的速率限制。5.4 从工作流到发布应用工作流调试完成后可以将其发布为一个独立的 Web 应用或 API。在工作流编辑页面点击“发布”。发布后进入“应用”界面你可以创建一个新的应用并选择“基于工作流构建”。为应用配置对话开场白、用户输入表单对应工作流的输入变量和界面样式。最后你可以通过 iframe 嵌入、API 接口或公开链接的方式将应用集成到你的业务系统中。通过以上步骤你不仅掌握了 Dify 工作流的基础搭建也了解了将其推向企业级应用所需关注的完整链路。从 Prompt 设计开始到可视化 Agent 工作流编排再到最后的部署与运维Dify 提供了一条渐进式的路径让开发者能更专注于业务逻辑本身而非底层基础设施的搭建。