在实际 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 管理工具，它是一个涵盖开发、部署、运营全流程的平台。对于开发者而言，最需要关注的是其应用构建层面的几个核心组件：

  1. 文本生成应用/对话应用 ：这是基础形态，相当于一个配置了系统 Prompt、可选知识库的聊天界面。适合构建客服机器人、内容生成等场景。
  2. 工作流 ：这是 Dify 的进阶能力。你可以像搭积木一样，将 LLM 模型、提示词模板、条件判断、变量处理、外部工具调用等节点连接起来，形成一个自动化流程。它适合处理有固定步骤、需要决策或与外部系统交互的复杂任务。
  3. Agent ：在工作流中，可以通过“工具”节点来赋予 LLM 调用外部能力，这本质上就是在构建一个 Agent。Dify 的 Agent 能力是内嵌在工作流引擎中的。
  4. 知识库 ：可以为应用绑定知识库，实现基于私有文档的问答（RAG）。在工作流中，知识库检索可以作为一个节点被调用。

简单来说， Prompt 是原料，Agent 是厨师，工作流是菜谱，Dify 就是整个厨房 。它提供了灶具（模型）、厨具（工具）、食材库（知识库）和一套可视化的做菜流程设计器（工作流编辑器）。

2. 环境准备与 Dify 本地部署

为了获得最佳的学习和控制体验，我们选择在本地部署 Dify。这能让你完全掌控数据和服务，方便进行调试和定制化开发。

2.1 系统与环境要求

Dify 支持多种部署方式，包括 Docker Compose、Kubernetes 和直接源码部署。对于大多数开发和学习场景， Docker Compose 是最简单、最推荐的方式。

在开始前，请确保你的开发环境满足以下要求：

组件 要求 检查命令 说明
操作系统 Linux, macOS, Windows (WSL2) uname -a 或 systeminfo Windows 用户强烈建议使用 WSL2。
Docker 20.10.0 或更高版本 docker --version 负责容器化运行 Dify 及其依赖。
Docker Compose 2.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）等所有必需服务。

  1. 获取部署文件 ：打开终端，在一个你喜欢的目录下（例如 ~/projects ），执行以下命令克隆部署仓库。

    # 克隆部署代码仓库
git clone https://github.com/langgenius/dify.git
# 进入 docker 部署目录
cd dify/docker

  2. 启动 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

  3. 验证服务状态 ：使用以下命令检查容器是否正常运行。

    docker compose ps

    你应该看到所有服务的状态（State）都是 Up 。

  4. 访问 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 等）。

  1. 登录 Dify 控制台，点击左下角 “设置” -> “模型供应商”。
  2. 点击 “添加模型供应商”，选择 “OpenAI”。
  3. 在配置页面，填入你的 OpenAI API Key。如果你没有，可以暂时使用 Dify 提供的测试 Key（可能有速率限制），或配置其他支持的模型。
  4. 在 “模型” 列表里，确保至少有一个模型状态是 “可用”，例如 gpt-3.5-turbo 。记下你在配置中为这个模型设置的名称，如 gpt-35-turbo 。

3.2 创建工作流与应用

  1. 在 Dify 首页，点击 “创建工作流”。
  2. 给工作流起一个名字，如 “智能旅行规划助手”，点击创建。
  3. 系统会自动进入工作流画布。你会看到一个以 “开始” 节点和 “结束” 节点构成的空流程。
  4. 在开始节点上，我们需要定义用户输入。点击 “开始” 节点，在右侧面板的 “变量” 选项卡，点击 “添加输入变量”。
    • 变量名 ： destination
    • 类型 ： 文本
    • 描述 ： 旅行目的地，例如：北京、上海
    • 必填 ：勾选
  5. 同样方式，再添加一个输入变量：
    • 变量名 ： days
    • 类型 ： 数字
    • 描述 ： 旅行天数，例如：3
    • 必填 ：勾选 这样，工作流启动时就会要求用户提供这两个参数。

3.3 编排核心工作流节点

我们的目标是构建这样一个流程： 开始 -> LLM生成行程 -> 查询天气 -> LLM整合建议 -> 结束 。

第一步：添加 LLM 节点生成行程草案

  1. 从左侧节点库的 “基础” 分类中，拖拽一个 “LLM” 节点到画布，放在 “开始” 和 “结束” 节点之间。
  2. 将 “开始” 节点的输出点（右侧）连接到 LLM 节点的输入点（左侧）。
  3. 点击这个 LLM 节点进行配置：
    • 模型 ：选择你之前配置好的模型，如 gpt-35-turbo 。
    • 上下文 ：保持默认。
    • 提示词 ：这是核心。我们需要编写一个 Prompt，让它利用用户输入的 destination 和 days 变量。在提示词编辑框中输入： 
      你是一个专业的旅行规划师。请为一位计划前往 {{destination}} 旅行 {{days}} 天的游客，生成一份详细的行程规划草案。
草案需要包含每天上午、下午、晚上的主要活动建议，并注明活动类型（如观光、美食、文化体验等）。
请以清晰的列表形式输出。
    • 变量 ：系统会自动识别 {{destination}} 和 {{days}} 作为变量。确保它们映射正确。
  4. 将这个 LLM 节点的名称改为 “生成行程草案”。

第二步：添加 HTTP 请求节点查询天气（模拟工具调用） 现实中，我们需要调用一个真实的天气 API。这里我们用一个模拟的公开 API 来演示。

  1. 从左侧 “工具” 分类中，拖拽一个 “HTTP 请求” 节点到画布，放在第一个 LLM 节点下方。
  2. 将第一个 LLM 节点的输出连接到 HTTP 请求节点的输入。
  3. 配置 HTTP 请求节点：
    • 名称 ： 查询目的地天气
    • URL ： https://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 节点整合最终建议

  1. 再拖拽一个 “LLM” 节点到画布，放在 HTTP 请求节点下方。
  2. 将 HTTP 请求节点的输出连接到这个 LLM 节点的输入。
  3. 配置这个 LLM 节点：
    • 名称 ： 生成最终旅行建议
    • 模型 ：同上。
    • 提示词 ： 
      你是一名贴心的旅行顾问。以下是一份旅行行程草案和目的地当前的天气信息。
请将两者结合，为游客生成一份最终的、贴心的旅行建议。

【行程草案】：
{{#生成行程草案.output#}}

【天气信息】：
{{#查询目的地天气.output.weather_result#}}

请根据天气情况，对行程草案提出调整建议（例如，下雨天推荐室内活动），并补充穿衣、出行等方面的温馨提示。
最终输出应友好、详尽、具有可操作性。
    • 变量 ：确保 {{#生成行程草案.output#}} 和 {{#查询目的地天气.output.weather_result#}} 正确映射了上游节点的输出。
  4. 最后，将这个 LLM 节点的输出连接到 “结束” 节点。

第四步：保存并测试

  1. 点击画布右上角的 “保存” 按钮。
  2. 点击右上角的 “发布” 按钮，将此工作流版本发布。
  3. 发布后，点击 “测试” 选项卡。在测试面板中，输入 destination 为 “杭州”， days 为 “3”，然后点击 “运行”。
  4. 观察画布上节点的运行状态（它们会亮起），并在右侧查看每个节点的输入输出详情，特别是最后一个 LLM 节点的最终输出。

通过这个流程，你已亲手构建了一个串联 Prompt 设计、LLM 调用和外部工具（HTTP API）的简易 Agent。Dify 工作流引擎负责管理节点间的数据传递和异步执行。

4. 工作流进阶：条件判断、循环与错误处理

基础的工作流是线性的。但真实场景中的 Agent 需要做决策（条件判断）和重复尝试（循环），并妥善处理失败。

4.1 使用条件分支节点

假设我们的旅行助手在查询天气时，如果遇到 API 失败或返回“城市不存在”，应该走另一条分支，生成一个不包含天气信息的通用建议，而不是让整个流程失败。

  1. 在 “查询目的地天气” HTTP 请求节点后，从左侧 “高级” 分类拖拽一个 “条件判断” 节点。
  2. 将 HTTP 请求节点的输出连接到条件判断节点的输入。
  3. 配置条件判断节点：
    • 名称 ： 天气查询是否成功？
    • 我们需要根据 HTTP 响应的状态码或内容来设置条件。点击 “添加条件”。
    • 变量选择 ：选择上游节点输出，例如 查询目的地天气.output.status_code 。
    • 比较方式 ： 等于 。
    • 值 ： 200 。
    • 这定义了一个分支：如果状态码等于 200，则视为成功，走 “是” 分支；否则走 “否” 分支。
  4. 现在调整连线：
    • 将条件判断节点的 “是” 输出，连接到 “生成最终旅行建议” LLM 节点。这意味着天气查询成功时，使用包含天气信息的 Prompt。
    • 我们需要为 “否” 分支创建另一个 LLM 节点。拖拽一个新的 LLM 节点，命名为 生成无天气建议 。
    • 配置其提示词为：“基于以下行程草案，生成一份旅行建议。注意，目前无法获取目的地实时天气，请提醒用户自行查询天气并做好应变准备。行程草案：{{#生成行程草案.output#}}”
    • 将条件判断节点的 “否” 输出连接到这个新 LLM 节点。
    • 最后，将 生成无天气建议 节点和 生成最终旅行建议 节点的输出，都连接到 “结束” 节点。Dify 支持多个节点汇聚到结束节点。

4.2 错误处理与重试机制

对于可能 transient failure（临时失败）的操作，如网络请求，可以配置重试。

  1. 点击 “查询目的地天气” HTTP 请求节点。
  2. 在右侧配置面板的底部，找到 “重试” 配置。
  3. 可以设置 “最大重试次数”（如 2 次）和 “重试间隔”（如 1000 毫秒）。
  4. 这样，当第一次请求失败（非 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 工作流设计最佳实践

  1. 模块化设计 ：将复杂的流程拆分成多个子工作流。Dify 支持“工作流作为节点”调用。例如，将“行程生成”和“天气查询与整合”分别做成子工作流，主工作流进行组装。这提高了复用性和可维护性。
  2. 清晰的变量命名 ：使用有意义的变量名，如 user_query , raw_itinerary , formatted_advice ，避免 a , b , temp 这样的命名。
  3. 充分的错误处理 ：如前所述，对每一个可能失败的外部调用（LLM、API、数据库）都要设计失败分支，提供降级方案或友好的错误提示。
  4. 版本控制与回滚 ：Dify 的工作流发布有版本概念。每次重大修改前，先保存一个版本。如果新版本有问题，可以快速回滚到上一个稳定版本。
  5. 压力测试 ：对于预计有高并发访问的工作流，需要进行压力测试，评估其在高负载下的稳定性和响应时间，特别是关注 LLM API 的速率限制。

5.4 从工作流到发布应用

工作流调试完成后，可以将其发布为一个独立的 Web 应用或 API。

  1. 在工作流编辑页面，点击“发布”。
  2. 发布后，进入“应用”界面，你可以创建一个新的应用，并选择“基于工作流构建”。
  3. 为应用配置对话开场白、用户输入表单（对应工作流的输入变量）和界面样式。
  4. 最后，你可以通过 iframe 嵌入、API 接口或公开链接的方式，将应用集成到你的业务系统中。

通过以上步骤，你不仅掌握了 Dify 工作流的基础搭建，也了解了将其推向企业级应用所需关注的完整链路。从 Prompt 设计开始，到可视化 Agent 工作流编排，再到最后的部署与运维，Dify 提供了一条渐进式的路径，让开发者能更专注于业务逻辑本身，而非底层基础设施的搭建。

# 工作流
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

告别扫描文档处理烦恼：ScanTailor Advanced的智能文档优化解决方案

ScanTailor Advanced是一款专业的扫描文档后期处理工具，专为解决老旧文档数字化中的各种问题而设计。通过智能内容识别、批量处理和多线程优化，它能将倾斜、模糊、杂乱的扫描文档转化为整洁的电子文件，显著提升文档数字化效率。## 文档数字化的常见痛点与解决方案### 页面歪斜校正：智能算法自动修正传统扫描文档经常出现页面歪斜问题，手动调整每页耗时耗力。ScanTailor Adv

avatar AI Agent技术社区

SeedVR2终极指南：如何用单步扩散模型实现专业级视频修复

还在为老旧视频的模糊画质而烦恼吗？面对抖动严重的监控录像或褪色的家庭影像，你是否曾希望有一种简单高效的修复方案？SeedVR2正是为解决这些痛点而生的一站式视频修复工具。作为字节跳动推出的先进视频修复模型，它能够在单步推理中实现专业级的视频质量提升，彻底改变了传统视频修复的工作流程。## 核心价值：为什么选择SeedVR2进行视频修复？**传统视频修复的三大瓶颈**：1. **计算成本高

avatar AI Agent技术社区

终极指南：如何用Python自动化工具告别大麦抢票焦虑，轻松获取心仪演出门票

还记得那些让你心跳加速的抢票时刻吗？热门演唱会开票瞬间，你手忙脚乱地刷新页面，却眼睁睁看着"立即购买"按钮变灰，票在几秒内售罄。这种"拼手速"的抢票时代已经过去，现在有了基于Python开发的大麦自动抢票工具，让你告别手速焦虑，轻松获取周杰伦、五月天、周深等热门演出的门票。## 🔥 你的抢票痛点，我们都有解决方案### 场景一：热门演唱会一票难求"周杰伦演唱会开票3秒售罄，我连页面都没

avatar AI Agent技术社区