从本地部署到知识库：Dify构建AI原生应用的实战指南

在RSG 敏捷嘉年华大会 2026 上海站的分享中，Dify 创始人张路宇老师带来了关于 AI 原生应用开发与敏捷方法论深度融合的实践思考。对于很多正在使用 Dify 搭建企业级智能应用的开发者来说，这不仅仅是一场技术演讲，更是一次对“AI 时代软件研发流程”的重新审视。

本文基于这次大会的行业背景，结合 Dify 社区版的实际使用场景，系统梳理从平台概念、本地部署、工作流搭建到知识库管理的完整实战路径。无论你是刚接触 Dify 的新手，还是已经在企业内落地智能体的开发者，都能从中找到可以直接上手的配置方案与排错思路。

1. 背景与核心概念

1.1 Dify 是什么

Dify 是一个开源的大语言模型（LLM）应用开发平台，它的定位非常明确：让开发者用更少的代码，完成 AI 应用的搭建、调试和运营。

在过去，开发一个带知识库、带工具调用、带多轮对话记忆的 AI 应用，往往需要自己处理模型 API 对接、向量数据库选型、Prompt 调优、上下文管理、日志追踪等一系列工程问题。Dify 把这些问题统一抽象成了可视化的工作台，开发者只需要在界面上拖拽组件、编排工作流、配置模型参数，就能快速产出可用的 LLM 应用。

从技术架构上看，Dify 的核心能力可以拆成几个部分：

• 应用编排：支持聊天助手、Agent、文本生成、工作流四种应用形态。
• 知识库：内置文档解析、分段清洗、向量化存储流程，支持多种检索策略。
• 模型管理：统一接入 OpenAI、Azure OpenAI、Anthropic、通义千问、DeepSeek 以及本地部署的 Ollama 等模型服务。
• 工具调用：支持内置工具、自定义 API 工具，以及 MCP（Model Context Protocol）服务的接入。
• 可观测性：提供完整的日志、标注、监控能力，帮助开发者在生产环境持续优化。

Dify 社区版是开源项目，代码托管在 GitHub，遵循 Apache 2.0 协议，可以免费用于商业场景。如果团队需要多租户隔离、SSO 登录、更多审计能力，可以关注商业版和企业版。

1.2 敏捷开发与 AI 应用开发的关系

RSG 是 Regional Scrum Gathering 的缩写，是全球 Scrum 社区的区域性盛会。敏捷开发（Agile Development）强调迭代、快速反馈、持续交付和跨职能协作。传统软件工程中的“预测型”（计划驱动）流程，往往在需求明确、变更较少的大型项目中更适用；而敏捷型流程则在需求不确定、市场变化快的场景下更具优势。

AI 应用开发恰恰是典型的敏捷场景。原因是多方面的：

1. 模型能力在快速迭代，半年前能实现的效果和今天可能完全不同，方案必须持续调整。
2. 用户需求不确定，知识库的覆盖范围、问答效果、Agent 工具链的合理性都需要通过真实用户反馈来修正。
3. 评估困难，传统的单元测试很难覆盖大模型输出的语义正确性，必须依赖灰度发布、A/B 测试和人工反馈。

张路宇老师在大会上的分享，正是围绕“如何用敏捷的方式做 AI 应用”展开，强调 Dify 在其中的作用是降低试错成本：一个工作流从修改到上线可能只需要几分钟，团队可以把精力聚焦在 Prompt 优化、知识库质量和用户反馈闭环上，而不是陷入繁琐的工程编码。

1.3 为什么选择本地部署 Dify

在实际项目中，不少团队会优先选择 Dify 云服务，开箱即用。但也有一些场景必须考虑本地部署：

• 数据敏感：企业内部文档、客户数据不能上传到第三方云平台。
• 合规要求：公司有明确的数据出境或数据隔离要求。
• 模型私有化：团队已经通过 Ollama、vLLM 等方式部署了本地模型，希望内网打通。
• 二次开发：需要修改 Dify 源码，定制自己的功能模块。

本地部署 Dify 社区版并不复杂，核心依赖是 Docker 和 Docker Compose。接下来我们完整走一遍从环境准备到服务启动的流程。

2. 环境准备与版本说明

2.1 部署环境要求

Dify 社区版官方推荐使用 Docker Compose 方式部署。这里用一个常见的 Linux 服务器环境作为示例，Windows 和 macOS 下的操作思路是类似的。

如果你使用 Dify 较新版本，还需要关注 Docker Compose 的版本兼容问题。文章示例中的地址、端口和目录结构为通用配置，实际操作时请以官方文档和你的实际环境为准。

2.2 安装 Docker

在 Linux 上安装 Docker 可以按下面的命令操作。以 Ubuntu 为例：

# 更新 apt 软件包索引 sudo apt update # 安装依赖包，允许 apt 通过 HTTPS 使用仓库 sudo apt install -y ca-certificates curl gnupg lsb-release # 添加 Docker 官方 GPG 密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 添加稳定版仓库 echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 再次更新并安装 Docker Engine sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

安装完成后，启动 Docker 服务并设置为开机自启：

sudo systemctl start docker sudo systemctl enable docker

验证是否安装成功：

docker --version docker compose version

看到版本号输出就说明 Docker 环境已经就绪。

2.3 获取 Dify 代码

Dify 的官方仓库地址在 GitHub。部署时通常不建议直接下载代码压缩包，而是通过git clone拉取指定版本，方便后续升级和查看版本说明。

# 克隆 Dify 源码仓库 git clone https://github.com/langgenius/dify.git # 切换到稳定版本分支，这里以 1.x 为例 cd dify git checkout 1.10.0

如果你不需要查看完整 Git 历史，也可以使用--depth 1参数做浅克隆，减少下载时间。

2.4 Docker Compose 启动

Dify 源码根目录下包含docker文件夹，里面有完整的docker-compose.yaml和环境变量示例文件。进入该目录后，复制环境变量文件：

cd dify/docker cp .env.example .env

然后启动服务：

docker compose up -d

第一次启动会拉取多个镜像，包括 API 服务、Worker、Web 前端、PostgreSQL、Redis、Weaviate 或 Qdrant 向量数据库等，耗时取决于网络环境，通常在几分钟到十几分钟之间。

启动完成后，查看容器状态：

docker compose ps

当所有容器的状态都是Up时，浏览器访问http://<服务器IP>/即可进入 Dify 初始化界面。

需要说明的是，不同版本默认使用的向量数据库可能不同，Dify 社区版在早期常用 Weaviate，新版本也支持 Qdrant、pgvector 等多种存储。.env文件里可以通过环境变量切换向量库类型，具体配置项以当前版本源码中的注释为准。

2.5 初始化管理员账号

首次访问 Dify 页面时，系统会要求设置管理员邮箱和密码。这个账号拥有平台最高权限，负责后续的用户管理、模型配置和应用发布。

初始化完成后，第一件事是进入“设置”页面，在“模型供应商”中配置你需要的模型服务商。如果使用 Ollama 本地模型，需要填写 Ollama 服务的 API 地址，比如http://host.docker.internal:11434（在 Docker 容器中访问宿主机地址时要注意网络模式）。

3. 核心功能拆解：应用、工作流与知识库

在进入实战之前，先把 Dify 的几个核心概念搞清楚。很多新手一开始就急着建应用，结果在“应用类型”“知识库分段”“工作流节点”之间来回切换，反而容易绕晕。

3.1 四种应用形态

Dify 支持创建四种类型的应用：

• 聊天助手（Chatbot）：面向对话场景，支持多轮上下文、变量、文件上传，是构建客服、助手类应用最常见的选择。
• 文本生成（Text Generator）：面向单轮生成任务，比如写摘要、翻译、扩写，适合不需要记忆上下文的调用场景。
• Agent：具备“自主决策”能力的聊天应用，可以理解用户意图，调用工具来完成多步任务，比如查天气、查数据库、调用业务 API。
• 工作流（Workflow）：通过编排多个节点来定义一个确定性的处理流程，适合对输出稳定性要求较高的场景，比如审批流程、表单解析、定时生成报表。

从敏捷的角度看，工作流适合流程确定的业务，Agent 适合边界无法 100% 确定的长尾任务。在真实项目中，这两者并不矛盾，很多企业先用 Agent 做探索，等某个流程足够稳定后再固化成 Workflow。

3.2 知识库的工作方式

知识库是 Dify 中最常用于企业落地的模块。它解决的问题是：让模型能回答私有化、非公开的知识，而不需要重新训练模型。

知识库的处理链条是：

1. 文档导入：支持 PDF、Word、Markdown、TXT 等格式。
2. 分段（Chunking）：按一定规则把长文档切成小块，便于检索。
3. 清洗：去掉页眉页脚、异常字符、重复内容。
4. 向量化（Embedding）：把文本块转为高维向量。
5. 存储：写入向量数据库。
6. 检索：用户提问时，根据问题向量相似度召回相关文本片段。
7. 增强生成（RAG）：把召回的文本片段作为上下文拼进 Prompt，让模型结合知识库内容回答。

理解这条链路非常重要，因为很多“回答不准确”的问题，根因并不在模型，而在于分段策略不合理或检索召回不到有效内容。

3.3 工作流的核心节点

Dify 工作流采用节点式编排，常用节点包括：

关于节点选择的思路：能确定的逻辑用代码节点和条件分支，能靠模型理解的内容用 LLM 节点，需要外部数据的用 HTTP 节点。不要把整个业务的判断逻辑全部交给模型，也不要写出大量“硬核”代码来绕过模型，最好的方案是两者结合。

4. 实战案例：搭建企业制度问答机器人

为了让整个过程更具体，这里模拟一个真实场景：某企业需要把内部规章制度整理成一个问答机器人，员工可以随时提问“年假怎么休”“报销流程是什么”，机器人基于知识库进行回答。

4.1 准备知识文档

先将企业制度文档整理为 Markdown 或 PDF 格式。示例文档内容如下：

# 员工年假管理制度 ## 第一条 适用范围 本制度适用于公司全体正式员工。 ## 第二条 年假天数 员工累计工作满1年不满10年的，年休假5天； 满10年不满20年的，年休假10天； 满20年的，年休假15天。 ## 第三条 申请流程 员工需提前3个工作日通过 OA 系统提交年假申请， 经直属上级审批后生效。

这里建议用 Markdown 格式，因为 Dify 的分段器对结构化文本的解析效果通常更好。

4.2 创建知识库

在 Dify 控制台左侧导航中，点击“知识库”进入列表页，然后点击“创建知识库”。

填写知识库名称，比如“员工制度库”，选择索引方式。索引方式建议使用高质量模式，它会调用 Embedding 模型对文本进行向量化，检索效果更好。

接下来上传刚才准备的文件，Dify 会进入分段流程。分段长度和重叠长度是影响检索效果的关键参数：

• 分段长度（Segment Length）：每个块的字符数，默认值通常适合通用问答。
• 分段重叠（Segment Overlap）：相邻块之间的重叠字符数，适当增大可以避免知识点被切断。

比如制度文档里的“满1年不满10年”和“满10年不满20年”这些不同档位，如果在分段时恰好被不同文本块截开，检索时可能漏掉其中一部分，导致回答不完整。此时可以把分段重叠设置为 20~50 个字符，减少上下文断裂的问题。

保存并完成分段后，可以点击文档名，在分段列表里检查每一段的内容是否完整。如果发现某些段落被不合理切断，可以手动调整分段规则后重新处理。

4.3 创建聊天助手应用

回到“应用”页面，点击“创建应用”，选择“聊天助手”。

在“编排”页面里，需要做以下几步：

第一步，选择模型。在右上角选择已经配置好的模型，比如 GPT-4o、DeepSeek、Qwen 或本地 Ollama 模型。这里用本地模型时要注意推理速度，如果显存不够，建议选择较小的量化模型。

第二步，编写系统提示词（System Prompt）。一个好的系统提示词是问答质量的基础。示例：

你叫“小制”，是企业内部制度问答助手。 你负责根据知识库内容回答员工关于人事、行政、财务等制度的问题。 回答要求： 1. 优先使用知识库内容回答，不要编造不存在的制度条款。 2. 如果知识库中没有相关信息，明确告知员工“暂时无法从制度文档中找到答案”，并建议其咨询 HR。 3. 回答时使用简洁、清晰的中文。

第三步，添加上下文。在对话框中把“知识库”上下文关联到上一步创建的“员工制度库”，并设置召回数量的上限。通常情况下，召回 3~5 个文本块即可满足回答要求，召回数量过多反而会引入噪音。

第四步，开启引用和标注功能。开启“引用”后，用户能直接看到回答依据了哪些文档片段，这在企业内部场景里非常重要，既能增加可信度，也便于后续审计。

4.4 调试与发布

在右侧预览窗口中输入“年假怎么申请”，观察模型回答是否准确。如果回答不理想，可以按以下顺序排查：

1. 知识库分段是否合理。
2. 系统提示词是否把规则说清楚。
3. 召回数量是否足够。
4. Embedding 模型是否合适。

调试完成后，点击“发布”。在“访问 API”菜单中，可以拿到应用的 API 密钥和调用地址。后端程序可以通过 Dify 的 Service API 把问答能力集成到企业微信、钉钉、飞书或自研系统中。

一个简单的 Python 调用示例：

import requests # Dify 应用 API 地址和密钥 api_url = "https://your-dify-domain/v1/chat-messages" api_key = "app-xxxxxxxxxxxxxxxx" headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", } payload = { "inputs": {}, "query": "年假有几天？", "response_mode": "blocking", "user": "employee-001", } response = requests.post(api_url, json=payload, headers=headers, timeout=30) print(response.json())

这里的chat-messages接口采用流式或阻塞两种响应模式。开发测试时使用blocking更直观；生产环境为了用户体验，建议使用streaming模式做打字机效果。

4.5 知识库的持续维护

问答机器人上线只是开始，日常维护才是重点。建议运营人员定期查看“日志与标注”，把新增的员工高频问题加入知识库，把回答错误的记录打上标签，持续优化提示词和文档内容。这其实就是张路宇老师在大会中提到的“敏捷反馈闭环”：每一次真实问答，都是下一次迭代的输入。

5. 进阶实战：工作流与 MCP 服务集成

当企业不满足于单纯的“知识库问答”，而是需要让 AI 真正连接业务系统时，工作流和工具调用会发挥更大价值。

5.1 场景：售后服务工单自动分类

假设企业有一个售后工单系统，客户提交的工单内容杂乱，需要先判断工单类型（退换货、维修、发票、咨询），再提取关键信息（订单号、产品型号、问题描述），最后把结构化数据写入工单系统。

这个场景非常适合用 Dify 工作流实现。

流程设计如下：

1. 开始节点：接收原始工单文本。
2. 参数提取节点：调用模型从文本中提取订单号、产品型号。
3. 问题分类节点：调用模型判断工单类型。
4. 条件分支节点：根据分类结果走向不同处理分支。
5. HTTP 请求节点：将结构化数据写入工单系统 API。
6. 结束节点：返回处理结果。

在工作流的关键节点中，参数提取是一个容易被忽略但极好用的能力。它本质上用模型做了一次“结构化解析”，把非结构化文本转换为 JSON。下面是一个参数提取节点的配置示意，核心是告诉模型要抽取哪些字段、字段类型是什么。

{ "订单号": { "type": "string", "description": "工单中的订单号，通常以字母 OR 开头" }, "产品型号": { "type": "string", "description": "产品型号，例如 iPhone 15 Pro" }, "问题描述": { "type": "string", "description": "用户反馈的问题内容" } }

这样，后续的 HTTP 请求节点就能直接使用{{节点名.订单号}}这类变量引用，避免写复杂的正则表达式去匹配。

5.2 MCP 服务集成

MCP（Model Context Protocol）是当前 AI 工具调用领域的重要协议，它相当于给 AI 应用提供了一套标准化的“外设接口”。通过 MCP，Dify Agent 可以方便地连接外部数据源和工具服务，而不需要针对每个工具单独写一套自定义接入逻辑。

在 Dify 中配置 MCP 服务时，需要进入 Agent 应用的“工具”配置页，找到 MCP 相关选项，填写 MCP 服务的地址和鉴权信息。配置完成后，Agent 会在对话中按需调用这些工具。

一个常见场景是：通过 MCP 接入企业内部的数据查询服务，让 AI 助手查询订单状态、库存数量、物流轨迹等实时数据。相比传统 API 集成，MCP 的优势在于工具描述标准化，模型可以更准确地理解“什么时候调用哪个工具”。

具体配置方法会随 Dify 版本变化而有所不同，配置前建议先确认当前版本的 MCP 功能入口，并将 MCP 服务部署在可控的内网环境中。

5.3 Agent 策略与插件

在 Dify 中，Agent 支持不同的推理策略，常见的有 Function Calling 和 ReAct 等。不同的策略适合不同场景：

• Function Calling：模型先判断调用哪个函数，再生成函数参数，适合结构化工具调用。
• ReAct：把推理和行动交错进行，适合需要复杂思考的任务，但消耗的 Token 更多。

实际项目中建议优先使用 Function Calling。如果模型本身不支持 Function Calling，再考虑 ReAct 等替代方案。

插件的安装和更新是另一个常见需求。Dify 社区有插件 Marketplace，可以安装第三方工具和工作流扩展。遇到插件安装失败时，通常与网络环境或版本兼容有关，可以先查看插件日志定位具体原因。Dify 也支持本地安装插件，便于企业内网离线环境使用。

6. 常见问题与排查思路

Dify 本地部署和使用过程中，社区中常见的几类问题如下。

针对最常见的Dify 中的 Ollama 模型处理超时问题，这里展开说一下。Ollama 部署在本地后，Dify 容器访问宿主机时不能直接用localhost，而需要使用 Docker 网桥地址。Linux 下可以执行ip addr show docker0查看宿主机在 Docker 网络中的 IP，通常是172.17.0.1。在 Dify 模型供应商配置中填入http://172.17.0.1:11434即可解决。

如果使用的是较新 Docker Desktop 版本的 Windows/macOS，则可以使用host.docker.internal作为宿主机地址。另外，模型推理速度本身也可能成为瓶颈。如果是 7B 或 13B 参数模型，建议在普通 CPU 环境或有足够显存的 GPU 上单独部署，尽量避免在 Dify 容器所在机器上同时承担高并发推理。

再来看Dify 出现内部服务器错误的情况。这个问题需要先区分是 Web 前端报错还是 API 接口报错。可以打开浏览器 F12 开发者工具，查看 Network 面板中请求的响应状态码和错误信息；然后到部署目录执行：

docker compose logs api --tail 200

查看 API 容器的最近日志。常见的内部错误包括：数据库迁移未完成、模型配置缺失、环境变量变更后没有重启容器。遇到这类问题时，先检查.env文件是否有语法错误，再执行docker compose down && docker compose up -d重建容器。

7. 最佳实践与工程建议

7.1 用敏捷迭代方式管理 AI 应用

AI 应用和传统软件的显著区别是：它的“代码”不只是业务逻辑，还包括模型选择、Prompt、知识库和评估方式。因此，我建议团队在 AI 应用开发中采用“小步快跑”的敏捷模式：

• 两周一个迭代，每次迭代只针对一到两个用户反馈最集中的场景做优化。
• 每次 Prompt 修改都要记录版本，可以用 Dify 的版本管理功能，或者把 Prompt 保存到 Git 仓库做 diff。
• 建立评估集，定期用固定问题集回归测试应用效果，避免一个优化导致另一个场景退化。

7.2 生产环境部署注意事项

如果只是本地学习，使用默认配置即可。但进入生产环境，必须注意以下几点：

1. 数据库备份：PostgreSQL 和向量数据库中存有应用配置和知识库数据，建议每天定期备份。备份前最好先停掉写入操作，或使用数据库事务一致性快照。
2. 密钥管理：Dify 的.env文件包含大量密钥，例如向量库密码、模型 API Key。不要把.env文件提交到 Git 仓库，仓库中应有.env.example模板，实际密钥通过部署系统的环境变量注入。
3. 资源限制：为 Docker 容器设置内存限制，避免某个进程把整个服务器资源耗尽。
4. HTTPS：生产环境务必使用 Nginx 反向代理，并为域名配置 HTTPS 证书，保证 API 调用过程中的数据安全。
5. 升级前先做快照：Dify 版本更新可能涉及数据库结构变化，升级前必须备份数据库并阅读官方升级说明。

7.3 知识库的长期维护机制

知识库不是“一次导入就结束”。很多企业应用上线后效果越来越差，就是因为文档更新了，但知识库没有同步；知识库更新了，但没有重新向量化。推荐做法是：

• 建立文档更新流程：当源文档变更时，通知运营人员重新上传。
• 设置文档责任人：每个知识库至少指定一名维护负责人。
• 记录知识库变更日志：记录每次新增、删除、更新操作，便于回滚。
• 定期清理噪音数据：删除过期、重复或内容质量差的文档片段。

7.4 敏感信息与权限边界

在企业级应用中，必须谨慎设计 AI 助手的权限边界。Dify 生态中，可以通过应用级密钥来控制不同系统的调用权限；在多团队场景下，要合理规划空间或项目隔离，避免 A 部门的数据被 B 部门调用。

同时要注意：知识库中如果有员工薪资、身份证号、银行账号等高敏信息，最好不要直接加入知识库。如果业务确实需要，应通过脱敏、掩码或单独的应用权限管理来控制访问范围。任何情况下，向用户展示回答时都应提供出处引用，方便追溯和审计。

8. 总结与学习路线

通过 RSG 敏捷嘉年华大会 2026 上海站这个背景，我们回顾了 Dify 创始人张路宇老师在 AI 应用开发与敏捷实践结合上的分享方向，并系统完成了从概念到实战的梳理。

本文重点内容包括：

• Dify 平台的核心能力与本地部署流程。
• 知识库问答应用的完整搭建过程。
• 工作流编排、参数提取与 MCP 服务集成的进阶思路。
• 常见报错现象的排查方法。
• 生产环境落地的工程最佳实践。

如果你想继续深入，建议按下面的顺序学习：

1. 先熟练使用 Dify 可视化界面创建“聊天助手”，理解 Prompt、上下文、知识库三者的配合。
2. 再到“工作流”中复现一个小型业务场景，比如工单分类、内容摘要、数据清洗。
3. 然后学习 Agent 和工具调用，尝试接入现有业务 API。
4. 最后学习 Docker Compose 部署细节、数据库备份和监控告警，把应用正式发布到测试环境。

一套可用的 Dify 项目并不复杂，难的是在真实场景中持续优化。它能帮你把“模型能力”快速变成“业务能力”，而你和团队的快速迭代能力，才是把 AI 落地的核心竞争力。

如果这篇文章对你有帮助，欢迎收藏备用。也欢迎在评论区聊聊你在部署 Dify、构建知识库或调试工作流时遇到的问题，一起交流解决思路。