在实际 AI 应用开发中如何快速将大模型能力转化为稳定、可复用的业务流程是许多开发者和团队面临的共同挑战。直接调用 API 虽然简单但难以处理复杂的多步骤逻辑、条件分支、外部工具集成以及知识库检索。Dify 作为一个开源的 LLM 应用开发平台其核心价值在于通过可视化的工作流编排将复杂的 AI 应用逻辑模块化、流程化让开发者能像搭积木一样构建应用。本文将以一个从零开始的视角详细介绍如何在 2026 年主流环境下完成 Dify 的本地化部署并基于其工作流功能手把手构建一个具备知识库问答能力的 AI 应用。整个过程将覆盖 Docker 与 MySQL 环境准备、Dify 部署、核心概念理解、工作流搭建、应用发布以及生产环境下的关键考量。1. 理解 Dify 的核心工作流与知识库在开始动手部署和编码之前需要先厘清 Dify 平台中的几个核心概念这决定了后续所有操作的逻辑。1.1 工作流从线性调用到可视化编排传统的大模型应用开发往往是线性的准备 Prompt - 调用 API - 解析结果。当业务逻辑变得复杂例如需要先检索知识库再根据检索结果判断是否需要调用特定工具如计算器、搜索引擎最后再生成回答时线性代码会变得难以维护和调试。Dify 的工作流Workflow功能将这个过程可视化。它将一个 AI 应用的完整处理流程拆解为多个节点Node每个节点代表一个独立的功能单元例如开始节点接收用户输入。知识库检索节点根据输入查询向量数据库。LLM 节点调用大模型可以组合检索结果和用户问题生成 Prompt。代码执行节点运行一段 Python 脚本处理数据。条件判断节点根据变量值决定流程走向。结束节点输出最终结果。节点之间通过连线Edge连接数据以变量的形式在节点间流动。这种设计使得复杂的多步推理、工具调用和条件分支变得一目了然也便于团队协作和流程优化。1.2 知识库赋予模型“长期记忆”大模型本身并不包含你的私有数据。知识库Knowledge Base功能就是为了解决这个问题。你可以将公司文档、产品手册、帮助文章等文本资料上传至 Dify平台会自动化完成文本分割、向量化Embedding并存储到向量数据库中。当用户提问时工作流中的“知识库检索节点”会先进行语义搜索找到最相关的文档片段并将其作为上下文提供给 LLM 节点从而实现基于私有知识的精准问答。1.3 应用、工作流与 API在 Dify 中一个“AI 应用”App是最终交付给用户或通过 API 调用的产物。一个应用可以有两种构建模式对话型应用基于简单的 Prompt 模板适用于单轮或简单多轮对话。工作流型应用基于上述可视化工作流构建适用于复杂、多步骤的业务场景。本文重点在于后者。部署好 Dify 后你创建的工作流型应用会自动提供一个可调用的 API 端点方便集成到你的网站、小程序或后端服务中。2. 环境准备Docker 与 MySQL 的安装与配置Dify 官方推荐使用 Docker Compose 进行部署这能最大程度保证环境一致性避免因系统差异导致的依赖问题。我们将分步完成基础环境的搭建。2.1 安装 Docker 与 Docker ComposeDocker 是容器化运行的基石。以下以 Ubuntu 22.04 为例其他 Linux 发行版或 macOS 可参考 Docker 官方文档调整。# 1. 卸载旧版本如有 sudo apt-get remove docker docker-engine docker.io containerd runc # 2. 更新 apt 包索引并安装依赖 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg lsb-release # 3. 添加 Docker 官方 GPG 密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 4. 设置稳定版仓库 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 5. 安装 Docker Engine sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 6. 验证安装 sudo docker --version sudo docker compose version对于 Windows 用户需要安装 Docker Desktop。安装后若启动失败并提示“Virtualization support wasn‘t detected”通常是因为未在 BIOS/UEFI 中开启 CPU 虚拟化支持Intel VT-x / AMD-V或者 Windows 功能中的“Hyper-V”和“Windows 虚拟机监控程序平台”未启用。2.2 安装与配置 MySQLDify 依赖关系型数据库存储应用配置、用户信息、对话记录等元数据。虽然 Docker Compose 文件里可以包含一个 MySQL 服务但为了生产环境管理的便利性更推荐使用一个独立部署的、已有维护经验的 MySQL 实例版本 5.7 或 8.0。在 Ubuntu 上安装 MySQL 8.0# 1. 下载并安装 MySQL APT 仓库配置包 wget https://dev.mysql.com/get/mysql-apt-config_0.8.24-1_all.deb sudo dpkg -i mysql-apt-config_0.8.24-1_all.deb # 在弹出的配置界面中选择 OK 即可 # 2. 更新包列表并安装 MySQL sudo apt-get update sudo apt-get install -y mysql-server # 3. 运行安全初始化脚本设置 root 密码、移除匿名用户等 sudo mysql_secure_installation为 Dify 创建专用数据库和用户登录 MySQL 后执行以下 SQL 语句-- 创建名为 dify 的数据库使用 utf8mb4 字符集以支持完整 Unicode如表情符号 CREATE DATABASE dify CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- 创建一个新用户例如 ‘dify_user‘并设置一个强密码 CREATE USER ‘dify_user‘‘%‘ IDENTIFIED BY ‘YourStrongPassword123!‘; -- 授予该用户对 dify 数据库的所有权限 GRANT ALL PRIVILEGES ON dify.* TO ‘dify_user‘‘%‘; -- 刷新权限使更改生效 FLUSH PRIVILEGES;注意在生产环境中‘%‘表示允许从任何主机连接这存在安全风险。应替换为‘具体Dify服务器IP‘以限制访问源。同时务必使用复杂的密码。2.3 系统资源检查运行 Dify 需要一定的内存和 CPU 资源尤其是在处理知识库文档嵌入或运行复杂工作流时。建议部署服务器至少满足CPU: 2 核以上。内存: 4 GB 以上如需处理大量知识库文档建议 8 GB。磁盘: 20 GB 以上可用空间SSD 为佳。可以使用free -h和df -h命令检查内存和磁盘空间。3. 部署 Dify使用 Docker Compose 一键启动有了 Docker 和 MySQL部署 Dify 本身变得非常简单。我们采用其社区版进行部署。3.1 获取部署配置文件首先创建一个工作目录并下载官方提供的 Docker Compose 配置文件。# 创建并进入目录 mkdir dify cd dify # 下载 docker-compose.yml 配置文件 curl -O https://raw.githubusercontent.com/langgenius/dify/main/docker/docker-compose.yaml # 下载环境变量配置文件模板 curl -O https://raw.githubusercontent.com/langgenius/dify/main/docker/.env.example cp .env.example .env3.2 关键配置修改接下来需要编辑.env文件将 Dify 连接到我们之前准备好的 MySQL并配置一些关键参数。使用vim或nano打开.env文件。nano .env找到并修改以下关键配置项# 数据库配置指向我们自建的 MySQL DB_HOST你的MySQL服务器IP DB_PORT3306 DB_PASSWORDYourStrongPassword123! # 之前为 dify_user 设置的密码 DB_USERNAMEdify_user DB_DATABASEdify DB_CHARSETutf8mb4 # 外部访问地址这是你访问 Dify Web 界面的地址 CONSOLE_API_URLhttp://你的服务器IP:3000 CONSOLE_WEB_URLhttp://你的服务器IP:3000 # 默认管理员账号首次登录用 DEFAULT_APP_LANGUAGEzh-Hans DEFAULT_ACCOUNT_EMAILadminexample.com DEFAULT_ACCOUNT_PASSWORDadmin123 # 请务必在首次登录后修改 # 向量数据库Dify 内置了 Weaviate对于入门和中小规模使用足够。生产环境可考虑外接 Milvus、PGVector 等。 VECTOR_STOREweaviate WEAVIATE_URLhttp://weaviate:8080注意如果 MySQL 和 Dify 部署在同一台服务器DB_HOST不能直接写127.0.0.1或localhost因为这是从 Docker 容器内部访问的视角。需要写宿主机的真实 IP或者使用 Docker 网络别名如果 MySQL 也在 Docker 中。最简单的方式是写服务器对外的 IP。3.3 启动 Dify 服务配置完成后使用 Docker Compose 启动所有服务。# 在 dify 目录下后台启动服务 sudo docker compose up -d这个命令会拉取 Dify API 服务器、前端界面、Weaviate向量数据库、Redis 等镜像并启动容器。首次运行需要下载镜像时间取决于网络速度。使用以下命令查看服务状态和日志# 查看所有容器状态 sudo docker compose ps # 查看 Dify API 服务的日志用于排查启动问题 sudo docker compose logs -f api当看到日志中出现 “Application startup complete.” 或类似信息时表示服务已成功启动。3.4 访问与初始化打开浏览器访问http://你的服务器IP:3000。你将看到 Dify 的登录界面。使用.env文件中设置的DEFAULT_ACCOUNT_EMAIL和DEFAULT_ACCOUNT_PASSWORD登录。首次登录后系统会引导你进行初始化设置包括命名你的工作室相当于团队或项目空间。配置模型供应商这是最关键的一步。你需要接入一个大模型 API例如 OpenAI 的 GPT 系列、 Anthropic 的 Claude或国内的通义千问、智谱 AI 等。在“模型供应商”设置中添加相应的 API Key 和 Base URL如果使用 Azure OpenAI 或代理。至此Dify 平台本身已部署并配置完成。4. 构建第一个工作流应用智能知识库助手我们将创建一个经典的应用场景一个能回答特定领域问题的智能助手。它首先从我们上传的知识库中查找相关信息然后结合找到的信息生成回答。4.1 创建应用与知识库创建应用在 Dify 控制台点击“创建应用”选择“工作流”类型输入应用名称如“产品支持助手”。创建并填充知识库进入“知识库”菜单点击“创建知识库”命名为“产品手册”。进入该知识库点击“上传文件”支持 txt、md、pdf、docx、ppt 等多种格式。你可以上传一份产品说明书或一些技术文档。上传后Dify 会自动进行文本分割和向量化嵌入。你可以在“文件列表”中查看处理状态状态变为“可用”即表示已就绪。在知识库设置中可以调整“分段处理”规则如分段长度、重叠区间等以优化检索效果。4.2 设计工作流进入刚创建的“产品支持助手”应用点击“工作流”标签页你会看到一个空白的画布只有一个“开始”节点。我们将搭建一个基础的知识库问答流程开始节点接收用户问题。知识库检索节点根据用户问题从“产品手册”知识库中查找相关片段。LLM 节点将用户问题和检索到的知识片段组合成 Prompt发送给大模型生成友好回答。结束节点输出最终回答。具体操作步骤从右侧节点列表拖拽一个“知识库检索”节点到画布。将“开始”节点的“query”变量输出连线到“知识库检索”节点的“query”输入。点击“知识库检索”节点在右侧配置面板中选择我们创建的“产品手册”知识库。可以调整“检索模式”相似度/全文和“返回条数”。拖拽一个“LLM”节点到画布。将“知识库检索”节点的“content”输出连线到“LLM”节点的“context”输入。将“开始”节点的“query”也连线到“LLM”节点的“query”输入。点击“LLM”节点进行配置选择你已配置好的模型供应商和模型如 gpt-4o-mini。在“上下文”区域你会看到{{#context#}}和{{#query#}}变量它们分别对应传入的知识片段和用户问题。编写系统 Prompt例如“你是一个专业的产品支持助手请严格根据提供的上下文信息来回答问题。如果上下文信息不足以回答问题请如实告知用户你不知道不要编造信息。”编写用户 Prompt 模板例如“上下文{{#context#}}\n\n问题{{#query#}}\n\n请根据上下文回答上述问题”拖拽一个“结束”节点到画布。将“LLM”节点的“answer”输出连线到“结束”节点的“answer”输入。现在你的工作流看起来应该是开始 - 知识库检索 - LLM - 结束。4.3 调试与运行保存工作流点击右上角“保存”。调试运行点击右上角“调试”。在右侧调试面板的“用户问题”输入框输入一个测试问题例如“这款产品支持哪些操作系统”查看运行过程点击“运行”你可以看到数据流经每个节点的动画并可以展开每个节点查看其输入和输出。这非常有助于理解工作流是如何执行的以及排查问题。检查结果在“结束”节点或调试面板底部查看模型生成的最终答案。确认答案是否基于你上传的知识库内容。4.4 发布与 API 集成调试无误后即可发布应用。点击工作流编辑器右上角的“发布”。发布后应用状态变为“已发布”。你可以切换到“概览”页这里会显示应用的访问方式Web 访问地址一个可分享的对话链接。API 端点用于程序化调用的 HTTP API 地址和密钥。复制 API 密钥和端点即可像调用普通 API 一样从你的代码中调用这个智能助手。一个简单的 Python 调用示例import requests import json api_key “你的应用API密钥” endpoint “你的应用API端点” headers { “Authorization”: f”Bearer {api_key}“, “Content-Type”: “application/json” } data { “inputs”: {}, “query”: “这款产品如何充电”, “response_mode”: “blocking”, # 同步模式 “conversation_id”: “”, “user”: “test_user_001” } response requests.post(endpoint, headersheaders, datajson.dumps(data)) result response.json() print(result[“answer”])5. 进阶工作流节点与复杂逻辑编排基础流程跑通后可以探索更多节点构建更强大的应用。5.1 条件判断与流程分支“IF/ELSE”节点允许你根据变量值决定流程走向。例如你可以先让 LLM 判断用户意图如果是“查询产品信息”走知识库检索分支。如果是“计算价格”走“代码执行”节点分支调用一个计算函数。如果是“转人工”走“HTTP 请求”节点分支通知你的客服系统。配置“IF/ELSE”节点时你需要定义一个条件表达式例如{{intent}} ‘query‘其中intent是上游某个节点如一个专门用于分类的 LLM 节点输出的变量。5.2 变量操作与转换“变量分配器”节点非常有用它可以在流程中创建、修改或组合变量。例如在知识库检索后你可能想对检索到的内容进行清洗或摘要可以将{{#context#}}分配给一个新变量processed_context然后传递给后续节点。“工具调用”节点允许你集成外部功能。Dify 内置了一些工具你也可以通过“自定义工具”功能将任何 HTTP API 封装成工具节点在工作流中调用如查询天气、调用内部业务系统等。5.3 循环与迭代对于需要处理列表或重复操作的任务可以使用“循环”节点。例如你有一个用户输入的需求列表需要对每一条需求分别进行知识库检索和回答最后汇总。“循环”节点可以遍历一个数组变量在每次迭代中执行子流程。6. 生产环境部署的注意事项与故障排查将 Dify 用于实际业务时需要考虑更多运维层面的问题。6.1 配置持久化与备份Docker 容器默认是无状态的。必须确保以下数据的持久化存储MySQL 数据我们使用了外部 MySQL其数据本身是持久的。但仍需建立定期的 MySQL 数据库备份策略。向量数据库数据如果使用内置的 Weaviate需要在docker-compose.yml中为weaviate服务配置卷挂载否则容器重启后向量数据会丢失。上传的文件知识库上传的原始文件存储在 Dify 的storage目录也需要通过卷挂载到宿主机。修改docker-compose.yml为相关服务添加volumes配置services: weaviate: # ... 其他配置 volumes: - weaviate_data:/var/lib/weaviate api: # ... 其他配置 volumes: - ./storage:/app/api/storage volumes: weaviate_data:6.2 性能、监控与安全资源监控使用docker stats或cAdvisor、Prometheus等工具监控容器 CPU、内存使用情况。知识库批量处理时资源消耗较大。日志收集Docker 日志默认在容器内。配置docker-compose.yml使用json-file或journald日志驱动并考虑使用ELK或Loki进行集中日志管理方便排查 API 调用错误或工作流执行问题。网络与安全通过 Nginx 配置反向代理为 Dify 的 3000 端口添加 HTTPS。在.env中修改SECRET_KEY使用强随机字符串。定期轮换 API 密钥。在防火墙中限制对 3000 端口的访问仅允许可信 IP。6.3 常见问题排查表问题现象可能原因检查与解决步骤访问http://IP:3000连接被拒绝1. 服务未启动。2. 防火墙阻止端口。1. 运行docker compose ps检查容器状态。2. 运行docker compose logs api查看 API 服务日志。3. 检查服务器防火墙规则sudo ufw status。登录后提示“数据库连接错误”1..env中数据库配置错误。2. MySQL 服务未运行或无权访问。3. MySQL 用户权限不足。1. 核对.env中的DB_HOST,DB_PORT,DB_USERNAME,DB_PASSWORD。2. 从 Dify 服务器尝试连接 MySQLmysql -h [host] -u dify_user -p。3. 在 MySQL 中确认用户权限SHOW GRANTS FOR ‘dify_user‘‘%‘;。知识库文件处理一直“排队中”或失败1. 向量数据库Weaviate连接问题。2. Embedding 模型服务不可用。3. 文件格式不支持或损坏。1. 检查 Weaviate 容器日志docker compose logs weaviate。2. 在“设置 - 模型供应商”确认 Embedding 模型配置正确且 API 可用。3. 尝试上传一个简单的.txt文件测试。工作流运行时报错“请安装缺失的包以使用此节点”使用了“代码执行”等节点但容器内缺少所需 Python 包。1. 此提示通常针对自定义 Python 节点代码。2. 需要自定义 Docker 镜像在构建时安装所需依赖或确保代码使用标准库。API 调用返回 401 或 403API 密钥错误或过期应用未发布。1. 在应用“概览”页复制正确的 API 密钥。2. 确认应用状态为“已发布”。3. 检查请求头Authorization: Bearer {api_key}格式。工作流调试时 LLM 节点无响应或超时1. 模型供应商 API 网络不通或额度用尽。2. Prompt 过长导致超时。3. 工作流存在循环依赖。1. 直接在 Dify “模型供应商”设置页测试模型调用。2. 简化 Prompt检查知识库检索返回内容是否过多。3. 检查工作流连线确保无循环。7. 最佳实践与扩展方向7.1 工作流设计最佳实践模块化设计将复杂流程拆分成子工作流。Dify 支持“迭代器”和“子工作流”节点可以将通用功能如“信息标准化处理”封装成子工作流提高复用性。善用变量为节点输出变量起有意义的名字如user_intent,search_results而不是一直使用output_1这能极大提升工作流的可读性和维护性。添加错误处理关键节点后可以接“IF/ELSE”节点判断执行是否成功失败时跳转到错误处理分支或给出用户友好提示。版本控制Dify 支持工作流版本历史。在做出重大修改前先保存并发布当前版本。这样一旦新版本有问题可以快速回滚。7.2 知识库优化建议文档预处理在上传前尽量保证文档格式清晰。对于 PDF 或扫描件使用 OCR 工具提取高质量文本。清除无关的页眉页脚、水印。分段策略根据文档类型调整分段大小和重叠区。技术文档可能适合较小的分段200-300字而文章可能适合较大的分段。适当的重叠可以避免答案被截断在分段边界。混合检索除了默认的向量相似度检索可以尝试“全文检索”或“混合检索”模式有时关键词匹配能补充语义搜索的不足。测试与评估构建一个测试问题集评估知识库问答的准确率。根据 bad case 调整分段策略或优化原始文档。7.3 扩展方向接入更多模型除了 OpenAI积极尝试 Claude、通义千问、智谱 GLM、本地部署的 Llama 等模型在成本、速度和效果间取得平衡。自定义工具深度集成将企业内部系统CRM、ERP、工单系统的 API 封装成工具让工作流不仅能“回答”还能“执行操作”如创建工单、查询订单状态。实现复杂业务逻辑结合条件判断、循环和变量操作可以实现审批流、数据提取与格式化、多轮对话状态管理等复杂业务场景。探索 Agent 能力Dify 的工作流本质是一种规划能力固定的 Agent。可以设计让 LLM 动态决定调用哪个工具或检索哪个知识库的工作流向更自主的智能体迈进。从部署到构建第一个应用再到设计复杂工作流Dify 通过可视化降低了 AI 应用开发的门槛但并未限制其能力上限。真正的挑战在于如何将业务需求精准地拆解为可编排的节点与数据流这需要开发者同时具备对业务的理解和对大模型能力边界的认知。建议从解决一个具体的、小规模的问题开始逐步迭代工作流同时密切关注日志和性能指标确保应用在提供价值的同时也稳定可靠。