🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度
在实际 AI 应用开发中，从构思一个智能体（Agent）到将其部署为一个稳定、可用的服务，中间往往横亘着复杂的工程挑战。你需要处理提示词（Prompt）的编写与迭代、多个模型或工具的编排、知识库的检索增强、以及最终 API 或界面的交付。Dify 作为一个开源的 LLM 应用开发平台，其核心价值在于将这些环节标准化、可视化，让开发者能聚焦于业务逻辑而非底层设施。对于希望快速入门 AI Agent 开发的工程师来说，Dify 提供了一个从 Prompt 工程到企业级工作流搭建的低门槛路径。
本文将带你从零开始，在约两小时内完成 Dify 的本地部署，并基于其核心概念构建一个具备知识库检索和条件判断能力的智能工作流。你会理解 Dify 中应用、工作流、Agent、知识库等关键组件的定义与关系，掌握通过可视化画布编排复杂逻辑的方法，并最终获得一个可独立运行、具备扩展潜力的 AI 应用原型。无论你是想验证一个 AI 产品想法，还是希望为现有业务系统添加智能对话能力，这个过程都将为你提供一个清晰的实践框架。
1. 理解 Dify 的核心概念与架构
在动手部署和编码之前，必须先厘清 Dify 平台中的几个核心概念。这能帮助你理解后续每一步操作的目的，避免在配置时感到困惑。
1.1 应用、工作流与 Agent：三种构建模式
Dify 允许你以三种模式构建 AI 应用，它们对应不同的复杂度和灵活性。
- 应用模式：这是最直接的模式，类似于一个加强版的 ChatGPT 聊天界面。你主要配置系统提示词（Prompt）、选择模型、并可能连接一个知识库。它适用于简单的问答、聊天机器人等场景，开发速度最快，但定制化能力有限。
- 工作流模式：这是 Dify 的核心优势所在。它提供了一个可视化画布，让你可以通过拖拽节点的方式，将 LLM 调用、代码执行、条件判断、知识库检索、HTTP 请求等不同能力像搭积木一样组合起来。工作流模式支持复杂的、多步骤的业务逻辑，例如：先检索知识库，再根据检索结果调用不同的工具或模型进行加工，最后格式化输出。本文的实战部分将重点围绕工作流展开。
- Agent 模式：在 Dify 的语境下，Agent 特指一种具备“思考-行动”循环能力的智能体。它会根据用户目标，自动规划步骤、选择工具（如搜索、计算、API调用）并执行，直到达成目标或无法继续。这比普通的工作流更智能，但配置也相对复杂，需要对工具进行良好的定义。
对于初学者，从工作流模式入手是最佳选择。它既保留了足够的灵活性来构建复杂功能，又通过可视化降低了编排逻辑的认知负担。
1.2 关键组件：模型、提示词、工具与知识库
无论哪种模式，都离不开以下几个基础组件：
- 模型配置：Dify 本身不提供模型，而是作为中间层连接 OpenAI、Anthropic、国内各大模型厂商或本地部署的模型（如通过 Ollama、vLLM）。你需要在 Dify 中配置这些模型的 API 密钥和端点。
- 提示词工程：这是 LLM 应用的“灵魂”。Dify 提供了强大的提示词编辑器，支持变量插值（如
{{input}}）、上下文引用，并且在工作流中，上一个节点的输出可以作为下一个节点提示词的变量。良好的提示词设计直接决定应用的效果。 - 工具：工具是扩展 LLM 能力的函数，例如获取天气、执行计算、查询数据库等。Dify 支持预置工具（如联网搜索）和自定义工具（通过 Python 代码或 HTTP 接口定义）。
- 知识库：Dify 可以创建和管理知识库，通过上传文本、PDF、Word 等文档，并利用嵌入模型将其向量化存储。在应用或工作流中，可以接入知识库进行检索增强生成（RAG），让模型基于你提供的专有资料回答问题。
理解了这些概念，我们就能明白部署 Dify 后要做的第一件事：配置一个可用的模型，作为所有智能能力的“大脑”。
2. 环境准备与 Dify 本地部署
我们将采用 Docker Compose 的方式进行部署，这是官方推荐且最便捷的方式，能一次性启动 Dify 所需的所有服务（Web 前端、后端 API、数据库等）。
2.1 系统与环境要求
确保你的开发环境满足以下要求：
- 操作系统：Linux (Ubuntu 20.04+ / CentOS 7+), macOS, 或 Windows 10/11 (需安装 WSL 2)。
- Docker：版本 20.10.0 或更高。可通过
docker --version命令检查。 - Docker Compose：版本 v2.0.0 或更高。可通过
docker compose version检查（注意是compose不是docker-compose）。 - 硬件：建议至少 4GB 可用内存。如果计划运行本地嵌入模型或 LLM，需要更多资源。
- 网络：能够访问 Docker Hub 和所需的模型 API（如 OpenAI）。
注意：如果你在 Windows 上操作，请务必先安装并启用 WSL 2，然后在 WSL 2 的 Linux 发行版（如 Ubuntu）中执行后续命令，以获得最佳兼容性。
2.2. 通过 Docker Compose 一键部署
获取部署文件：在终端中，创建一个专门目录并下载官方提供的
docker-compose.yaml文件。mkdir dify && cd dify curl -O https://raw.githubusercontent.com/langgenius/dify/main/docker/docker-compose.yaml这个文件定义了 Dify 服务（
api和web）以及其依赖的 PostgreSQL 和 Redis。启动服务：执行以下命令，Docker 会自动拉取镜像并启动所有容器。
docker compose up -d首次运行会下载镜像，需要一些时间。
-d参数表示在后台运行。验证部署：服务启动后，可以通过以下命令查看容器状态。
docker compose ps如果所有服务状态均为
running，则部署成功。默认情况下，Dify 的 Web 界面运行在http://localhost:3000，后端 API 运行在http://localhost:5001。初始访问：打开浏览器，访问
http://localhost:3000。你会看到初始化页面，需要设置管理员账号和密码。完成设置后，即可登录进入 Dify 控制台。
2.3. 基础配置：连接你的 LLM
登录后，首要任务是为 Dify 配置一个“大脑”。我们以配置 OpenAI 的 GPT 模型为例（你也可以选择配置 Azure OpenAI、 Anthropic Claude 或国内其他模型）。
- 在控制台左侧导航栏，点击“设置”->“模型供应商”。
- 点击“添加模型供应商”，选择“OpenAI”。
- 在配置页面，你需要填写：
- 名称：自定义，如 “My-OpenAI”。
- API 密钥：你的 OpenAI API Key。
- API 基础 URL：通常使用默认的
https://api.openai.com/v1。如果你使用第三方代理，需要修改此处。
- 配置完成后，点击“保存”。然后点击“添加模型”，选择你拥有的模型，如
gpt-4o或gpt-3.5-turbo，并为其命名（如 “GPT-4o”）。 - 最后，进入“设置” -> “默认模型”，将你刚添加的模型设置为对话、文本生成等场景的默认模型。
至此，你的 Dify 平台已经就绪，并拥有了调用 LLM 的能力。接下来，我们将进入核心环节——构建第一个工作流。
3. 构建第一个 Dify 工作流：智能客服助手
我们将构建一个模拟的“智能客服助手”工作流。它的功能是：用户输入一个产品相关问题，系统先从一个模拟的“产品知识库”中检索相关信息，然后结合检索到的内容，让 LLM 生成一个友好且专业的回答。
3.1. 创建工作流与应用
- 在 Dify 控制台首页，点击“创建工作流”。
- 为工作流命名，例如 “Smart-Customer-Support”。
- 点击进入后，你会看到一个空白的画布。左侧是节点工具箱，右侧是画布和配置面板。
3.2. 设计工作流节点与连接
我们的工作流逻辑很简单：开始->知识库检索->LLM 处理->结束。
- 添加“开始”节点：画布上已有一个“开始”节点。选中它，在右侧配置面板的“变量”部分，点击“添加”。我们添加一个名为
user_question类型为“文本”的变量，这代表用户输入的问题。 - 添加“知识库检索”节点：
- 从左侧工具箱的“检索”分类中，拖拽“知识库检索”节点到画布。
- 将“开始”节点右侧的输出点拖拽连接到“知识库检索”节点的输入点。
- 选中“知识库检索”节点，在右侧配置：
- 知识库：由于我们是演示，可以先不连接真实知识库。这里我们使用一个“模拟”方式。你可以创建一个简单的知识库：在左侧导航进入“知识库”，创建并上传一个包含产品信息的 TXT 文件。然后在配置中选择它。
- 查询内容：这里要填入检索的关键词。我们输入
{{user_question}}，这样就会用用户的问题去检索。 - 检索模式：选择“向量化检索”。
- 返回条数：设置为 3。
- 添加“LLM”节点：
- 从工具箱“AI 模型”分类中，拖拽“LLM”节点到画布。
- 将“知识库检索”节点的输出点连接到“LLM”节点的输入点。
- 选中“LLM”节点，在右侧配置：
- 模型：选择你之前配置的模型，如 “GPT-4o”。
- 上下文：勾选“添加上下文”，这样 LLM 能记住对话历史（本例简单演示，可不勾）。
- 提示词：这是核心。我们需要编写一个系统提示词来指导模型如何利用检索结果。
你是一个专业的客服助手。请根据以下提供的产品知识来回答用户的问题。 如果知识库内容不足以回答问题，请如实告知用户你不知道，并建议其通过其他渠道咨询。 【相关产品知识】： {{#contexts}} {{content}} {{/contexts}} 【用户问题】： {{user_question}} 请用中文给出专业、清晰、友好的回答。- 提示词变量说明：
{{#contexts}} {{content}} {{/contexts}}：这是一个循环语法，会自动将“知识库检索”节点返回的多条内容拼接起来插入到这里。{{user_question}}：引用了开始节点定义的变量。
- 添加“结束”节点：
- 从工具箱“基础”分类中，拖拽“结束”节点到画布。
- 将“LLM”节点的输出点连接到“结束”节点的输入点。
- 选中“结束”节点，在右侧配置输出变量。我们将 LLM 的回答输出出来。添加一个变量，例如
assistant_answer，其值设置为{{#llm}} {{response}} {{/llm}}。这里的{{#llm}}引用了上一个 LLM 节点的输出。
至此，一个简单但完整的工作流就搭建完成了。画布上的连线清晰地展示了数据流向：用户问题 -> 知识库检索 -> 生成回答 -> 输出结果。
3.3. 调试与运行工作流
在发布前，务必使用调试功能验证工作流是否正确。
- 点击画布右上角的“调试”按钮。
- 在打开的调试面板中，为
user_question输入一个测试问题，例如：“你们的产品支持哪些支付方式？” - 点击“运行”。下方会显示执行过程。
- 你可以展开每个节点，查看其输入和输出。例如，在“知识库检索”节点，你能看到它实际检索到的文本片段；在“LLM”节点，你能看到发送给模型的完整提示词和模型返回的原始响应。
- 检查最终输出
assistant_answer是否符合预期。如果检索的知识库中有支付方式的信息，LLM 应该能据此生成回答。
调试通过后，点击右上角“发布”。发布后，这个工作流就成为一个可用的 AI 应用。
3.4. 访问与集成应用
发布后，你有多种方式使用这个工作流：
- Web 界面：在应用详情页，Dify 会提供一个类似 ChatGPT 的聊天窗口，你可以直接在那里与你的智能客服对话。
- API 集成：在“访问方式”页面，Dify 提供了该应用的 API 地址和密钥。你可以用任何 HTTP 客户端（如 curl、Postman）或在你自己的前端、后端代码中调用它。
# 示例 curl 命令 curl -X POST http://localhost:5001/v1/workflows/run \ -H "Authorization: Bearer your-app-api-key" \ -H "Content-Type: application/json" \ -d '{ "inputs": { "user_question": "产品的退货政策是什么？" } }' - 嵌入到网站：Dify 支持生成嵌入代码，你可以将其复制到你的网站 HTML 中，即可添加一个聊天机器人小部件。
4. 进阶：为工作流添加条件判断与外部工具
基础工作流只能线性执行。现实中的业务逻辑往往需要分支判断。接下来，我们升级工作流，让它能根据用户意图执行不同操作。
新需求：用户可能询问产品信息（走知识库检索），也可能想计算订单折扣（需要调用计算工具）。我们需要让工作流自动判断。
4.1. 使用“分类”节点进行意图识别
- 在之前的工作流中，删除“开始”到“知识库检索”的连线。
- 从工具箱“AI 模型”分类中，拖拽一个“分类”节点到画布，并连接在“开始”节点之后。
- 配置“分类”节点：
- 模型：选择一个模型。
- 分类选项：添加两个选项，并为其定义名称和描述。
- 选项1：
query_product， 描述：“用户想查询产品功能、价格、政策等信息。” - 选项2：
calculate_discount， 描述：“用户提供了订单金额，想计算折扣后的价格。”
- 选项1：
- 提示词：编写提示词让模型根据用户问题分类。
请判断用户问题的意图。 用户问题：{{user_question}} 请只输出分类选项的名称，不要输出任何其他文字。
4.2. 创建分支与工具调用
- 添加“条件判断”节点：
- 从工具箱“逻辑”分类中，拖拽“条件判断”节点到画布，连接在“分类”节点之后。
- 配置条件：我们需要根据分类结果来分支。
- 点击“添加条件”。
- 变量：选择
{{#classifier}} {{result}} {{/classifier}}（这引用了分类节点的输出）。 - 操作符：选择“等于”。
- 值：输入
query_product。 - 这个条件为真时，走“查询产品”分支。
- 构建“查询产品”分支：
- 将“条件判断”节点的“是”输出点，连接到之前已有的“知识库检索”节点。
- “知识库检索”节点之后继续连接“LLM”节点和“结束”节点。这部分逻辑与之前相同。
- 构建“计算折扣”分支：
- 从工具箱“工具”分类中，拖拽一个“代码”节点到画布。
- 将“条件判断”节点的“否”输出点连接到这个“代码”节点。
- 配置“代码”节点：
- 语言：选择 Python。
- 代码：编写一个简单的折扣计算函数。
def main(user_question: str) -> str: # 这是一个简单的示例，实际应从问题中解析金额和折扣率 # 假设问题格式为：“计算100元打8折后的价格” import re amount_match = re.search(r'(\d+(\.\d+)?)元', user_question) discount_match = re.search(r'打(\d+(\.\d+)?)折', user_question) if amount_match and discount_match: amount = float(amount_match.group(1)) discount = float(discount_match.group(1)) / 10.0 # 八折转为0.8 final_price = amount * discount return f"折扣后价格为：{final_price:.2f}元" else: return "无法从问题中解析出金额和折扣信息，请确认格式如‘计算100元打8折后的价格’。"- 输出：将函数返回值命名为
calculation_result。
- 然后，将这个“代码”节点的输出，连接到一个新的“LLM”节点，让 LLM 来组织最终的回答。提示词可以写为：“根据计算结果组织一段友好的回复给用户。计算结果：{{calculation_result}}”。最后连接到“结束”节点。
4.3. 合并输出与调试
现在你有两个分支最终都汇向了“结束”节点。你需要确保“结束”节点能接收来自不同分支的变量。在“结束”节点的输出配置中，你可以使用条件逻辑或简单的变量引用。一个简单的方法是，在两个分支最后的 LLM 节点，都将输出变量命名为同一个，例如final_answer。这样无论走哪条分支，“结束”节点都能输出final_answer。
再次使用调试功能，分别输入“产品保修期多久？”和“计算200元打9折多少钱”，观察工作流是否正确地走了不同的分支并给出了相应回答。
5. 常见问题排查与优化实践
在实际使用 Dify 构建和运行工作流时，你可能会遇到一些典型问题。以下是一些常见问题的排查思路和优化建议。
5.1. 部署与连接问题
| 问题现象 | 可能原因 | 检查方式 | 处理建议 |
|---|---|---|---|
访问localhost:3000失败 | Docker 服务未启动或端口被占用 | docker compose ps查看容器状态；netstat -tuln | grep 3000查看端口占用 | 确保容器运行；修改docker-compose.yaml中的端口映射（如3000:3000改为8080:3000）。 |
| 应用无法调用模型，报 API 错误 | 模型供应商配置错误、API 密钥无效或额度不足、网络不通 | 在 Dify 控制台“日志与异常”中查看详细错误；手动用 curl 测试模型 API。 | 检查 API 密钥和端点 URL 是否正确；确认账户余额或配额；检查服务器网络是否能访问目标 API 地址。 |
| 工作流调试时某个节点报错 | 节点配置错误、输入变量格式不对、依赖服务（如知识库）未就绪 | 点击调试面板中报错的节点，查看其输入数据和错误信息。 | 检查节点配置表单，特别是变量引用语法（如{{variable}}）是否正确；确保上游节点输出了下游节点需要的变量。 |
5.2. 工作流设计与调试问题
- 变量引用错误：这是最常见的问题。Dify 使用
{{}}语法引用变量。你必须确保：- 变量名拼写正确。
- 变量在其作用域内（例如，在“条件判断”节点的“否”分支中，无法引用只在“是”分支中创建的变量）。
- 引用复杂节点输出时，语法正确，如
{{#llm}} {{response}} {{/llm}}。
- 知识库检索效果不佳：如果 RAG 效果不好，可以：
- 检查文档处理：在知识库设置中，调整文本分割器（chunker）的大小和重叠度。过大的块可能包含无关信息，过小的块可能丢失上下文。
- 优化检索查询：不要直接将原始用户问题作为查询。可以在工作流中先加一个“LLM”节点，将问题重写为更利于检索的关键词。
- 尝试混合检索：在“知识库检索”节点中，可以开启“混合检索模式”（结合向量检索和全文关键词检索），可能提升召回率。
- 提示词效果不稳定：LLM 的输出不可控。
- 结构化输出：在提示词中明确要求输出格式，例如“请用 JSON 格式输出，包含
answer和confidence两个字段。” - 提供示例：在系统提示词中提供一两个输入输出的例子（Few-Shot Learning），能显著提升模型遵循指令的能力。
- 迭代优化：不要指望一次写好提示词。利用 Dify 的“对话”功能或工作流调试，反复测试不同问法，观察模型输出，不断调整提示词。
- 结构化输出：在提示词中明确要求输出格式，例如“请用 JSON 格式输出，包含
5.3. 生产环境考量
当你准备将 Dify 应用用于真实业务时，需要考虑以下几点：
- 配置外置与安全：不要将 API 密钥等敏感信息硬编码。Dify 支持通过环境变量注入配置。在
docker-compose.yaml中，使用environment部分或外部.env文件来管理密钥。 - 性能与监控：
- 超时设置：在工作流中，为“HTTP 请求”、“知识库检索”等可能耗时的节点设置合理的超时时间。
- 限流：在 Dify 的企业版中，或通过前置的 API 网关（如 Nginx），对应用 API 进行限流，防止滥用。
- 日志收集：确保 Dify 的日志（控制台日志和数据库中的日志）被收集到 ELK 或 Loki 等日志平台，便于排查问题。
- 高可用与备份：对于生产环境，考虑将 Docker Compose 部署迁移到 Kubernetes。定期备份 Dify 使用的 PostgreSQL 数据库。
- 版本管理：Dify 应用和工作流配置也需纳入版本控制。虽然 Dify 界面支持版本历史，但重要的变更建议通过其导出/导入功能，将应用配置保存为文件，用 Git 进行管理。
从 Prompt 工程到可视化工作流，Dify 极大地降低了 AI 应用开发的门槛。两小时的入门足以让你搭建出一个具备核心逻辑的原型。然而，构建一个真正鲁棒、高效的企业级应用，还需要在提示词优化、知识库构建、错误处理、性能监控等方面持续投入。建议你将本文构建的工作流作为起点，尝试接入真实的业务数据和 API，在实践中深入理解每个节点的细节和潜力，从而设计出更贴合业务需求的智能流程。
🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度
