我最早接触 Dify是去年帮一家客户做政务类的 RAG 知识库项目。当时团队里几个人对“AI 应用定制化”的理解还停留在调 API、套 Prompt 的阶段结果一上手才发现真正的拦路虎根本不在模型而是怎么把知识库、工作流、外部工具揉进一个能落地、能上线、能迭代的系统里。折腾了几版自研方案之后我们换到了 Dify整个项目的交付节奏一下子就不一样了。今天这篇实战笔记我不打算写官方文档式的教程而是把我从“下载 Dify 到跑通生产级 AI 应用”这条路上踩过的坑、验证过的做法、用真金白银换来的判断标准尽量完整地分享出来。不管你是准备做 AI 应用定制化开发的工程师还是想在公司内部搭一套智能体平台的产品负责人这篇文章应该都能帮你省下不少试错时间。Dify 本质上是一个开源的 LLMOps 平台它把大模型应用开发里最麻烦的几件事——Prompt 编排、知识库管理、工作流设计、模型接入、日志观测、应用发布全都做成了可视化操作。我的体会是Dify 最大的价值不是“零代码”而是“少代码但高可控”。它给你搭好了骨架但血液和肌肉还是你自己来填充。所以它既适合快速验证想法的原型阶段也扛得住生产环境里复杂的业务逻辑。1. 内容整体设计与思路拆解1.1 为什么 AI 应用定制化绕不开 Dify 这一类平台先说一个很多新手容易误解的点AI 应用定制化不等于“训练模型”。绝大多数业务场景下你不需要也不应该去微调一个大模型。你需要的是把已有的模型能力按照你所在的行业规则、业务流程、数据权限重新组装成一个能被业务人员直接使用的工具。这里有个很直白的类比。大模型就像一台发动机功率很大但你不可能把裸发动机直接塞进车里开上路。你需要变速箱、底盘、方向盘、仪表盘甚至还有安全带和气囊。Dify 做的就是后面这一整层“整车制造”的活。知识库就是油箱工作流就是传动系统Agent 就是自动驾驶逻辑日志和监控就是仪表盘。你把发动机比如 GPT、Qwen、DeepSeek 或本地部署的 bge-m3 这类模型装进 Dify 这个“车架”才能交付一台真正能跑业务的车。我见过不少团队一开始雄心勃勃要自研一套 RAG 框架结果三个月后连文件解析的准确率都没调明白。不是说自研不行而是如果你的核心业务不是做 AI 基础设施那么站在 Dify 这类开源平台肩膀上把精力花在业务流程和知识沉淀上ROI 会高得多。1.2 我眼中的 Dify 核心功能拼图Dify 的功能模块我用一句话来概括就是“从模型到应用中间所有环节都给你管起来”。具体拆开来看有这么几个核心点模型接入层它支持 OpenAI 格式的 API也支持各种本地模型比如通过 Ollama 部署的 bge-m3 嵌入模型、Qwen 系列。关键是你可以同时配置多家模型供应商在单个应用里自由切换。知识库RAG 流水线这是 Dify 社区版里使用频率最高的模块之一。从文件上传、自动分段清洗、向量化、召回测试到引用设置完整覆盖了一条 RAG 流水线。很多政务类、企业类的知识问答机器人本质上就是靠这一块撑起来的。工作流编排你可以把 LLM、知识检索、条件分支、代码执行、HTTP 请求、模板转换这些节点拖到画布上连成一条可执行的业务流程。Dify 的工作流不是摆设我后续会具体讲怎么用它处理复杂的业务判断。Agent 与工具调用在智能体应用里你可以给 Agent 挂上各种工具比如自定义 API、数据库 MCP 工具、浏览器自动化工具等。Agent 自己决定什么时候调用什么工具这比死板的工作流更灵活但也更需要调教。可观测性与运维日志、标注、数据标注、API 访问密钥管理、发布渠道管理这些“不起眼”的功能恰恰是生产环境能不能长期跑下去的命根子。我个人的经验是如果你能把这五块拼图都理解到位并且知道在什么场景下用哪一块那你基本就已经从“会用 Dify”进阶到“能用 Dify 做架构设计”了。2. 核心细节解析与实操要点本地部署与版本管理2.1 Windows 10 本地部署 Dify 的完整流程Dify 官方对 Linux 和 Mac 的支持比较顺滑但现实中确实有大量开发者的主力机器是 Windows。我一开始就是在 Windows 10 上折腾的这里把我的实操路径完整还原一遍。先说准备工作。Dify 的部署强烈依赖 Docker所以第一步是装好 Docker Desktop for Windows并确保它使用的是 WSL2 后端而不是老的 Hyper-V。这一步非常关键因为 WSL2 在文件 I/O 性能和兼容性上要好得多。你可以在 PowerShell 里输入wsl --status确认 WSL 版本如果不是 2就执行wsl --set-default-version 2升级。接下来到 Dify 的 GitHub Releases 页面下载对应版本的源码包。你拿到手的是一个压缩包解压后里面有一个dify-main目录进入这个目录后找到docker文件夹然后在这个文件夹路径下右键打开终端Windows 11 自带这个右键菜单Windows 10 可以按住 Shift 再右键选择“在此处打开 PowerShell 窗口”。这里有一个高频坑很多人第一次启动 Dify 会报错说缺少环境变量文件。Dify 官方提供了一个.env.example模板但 Docker Compose 默认读取的是.env不是.env.example。所以你必须手动拷贝一份。在刚才打开的终端里执行cp .env.example .env这条命令的意思是把模板文件复制一份并命名为.env。复制完成之后根据你的实际需求修改关键配置项比如SECRET_KEY建议改成一段随机字符串、POSTGRES_PASSWORD数据库密码等。如果你不确定怎么改即便保持默认值也能先把服务跑起来但生产环境必须改。然后执行docker compose up -d第一次运行会拉取镜像耗时取决于你的网络环境可能需要 5 到 20 分钟。看到各个容器状态为 healthy 之后浏览器访问http://localhost就能打开 Dify 的登录页。初始账户是admindify.ai密码是password首次登录会强制要求修改密码。顺便提一句压缩包文件名里那个dify-main的问题。很多新手一看到main就以为是主线代码、不稳定版。其实main只是 GitHub 默认分支的名字Dify 每次发版都会把对应版本的代码打成这种格式的包所以你下载到的dify-main就是当前最新稳定版源码不是开发中的分支可以放心用。2.2 从单机版到社区版多租户版本演进带来的变化如果你关注 Dify 的更新日志会发现“多租户”这个词出现的频率越来越高。Dify 社区版从 1.10 版本左右开始逐步加强了对多租户场景的支持。这对做项目交付的人来说是个大福利。怎么理解多租户打个比方以前你给三家客户各自部署一套 Dify每套都要单独维护、单独升级就像给每户人家单独装一个水表。而多租户模式下你可以在一套 Dify 系统里创建多个工作空间每个工作空间的模型配置、知识库、应用、成员权限完全隔离共享一套底层基础设施。这相当于一栋楼只装一个总水表但每户有独立的分表。我实际测试下来在社区版里开启多租户的路径是在“平台设置”或者管理员后台里找到工作空间管理手动创建新的工作空间然后邀请不同团队的成员进入各自的工作空间。在 1.10 之前个人开发者想要隔离环境只能靠部署多套实例资源消耗非常大。现在一台 8C16G 的服务器就可以撑起好几个相互隔离的项目环境对小团队的交付场景非常友好。2.3 在线升级 Dify 的正确姿势升级这事我踩过的坑比部署还多。Dify 的迭代速度很快经常一两个月就出一个大版本里面包含新的节点类型、UI 优化和 bug 修复。很多人直接删掉旧容器再拉新镜像结果数据库结构不兼容启动直接失败。我的升级流程是这样的实测过多个版本基本没出过问题进入docker文件夹备份当前环境文件和数据卷cp .env .env.bak停止并移除当前容器docker compose down用docker compose pull拉取新版镜像在源码目录里把新版docker文件夹下的.env.example和旧版.env对比把新增的配置项合并进.env执行docker compose up -d启动服务启动后立即查看日志docker compose logs -f api和docker compose logs -f worker最重要的原则是升级前一定备份数据卷尤其是 Postgres 和 Redis 的数据目录。Dify 在启动时会自动执行数据库迁移脚本Migration正常情况下老数据会自动平滑升级但一旦迁移到一半失败没有备份的话就只能从头重建知识库那滋味真不好受。另外Dify 官方也提供了在线升级工具但我在 Windows 环境里用下来偶尔会遇到路径识别问题。所以我更推荐的方式是直接下载新版源码包保留旧版的.env和持久化数据再走一遍docker compose down up的流程。这个“半手动”方式看着笨反而最稳。3. 实操过程与核心环节实现知识库的构建、调优与 RAG 实战3.1 知识库是如何“喂”给大模型的很多人用 Dify 创建知识库时觉得“上传文档、点击分段、完成”就结束了。但实际上RAG 系统的效果好坏关键就在这一步。你需要搞清楚 Dify 在背后做了什么。当你在 Dify 的知识库里点击“添加文件”上传一份 PDF 或 Word 文档之后系统会走这样一个流水线预处理把文件内容的文本提取出来。这个环节对 PDF 尤其容易出问题如果是扫描版 PDF自带的提取器只能拿到一堆乱码必须配合 OCR 工具。分段ChunkingDify 会根据你设定的分段长度和分段重叠长度把长文本切成若干个文本块。默认的分段长度是 500 token重叠长度是 50 token。这两个参数直接决定了后续向量检索的粒度。清洗Dify 提供了一些清洗规则例如删除多余的换行、空格、URL 等。针对代码类文本还可以启用“代码块”识别。向量化Embedding调用你配置的嵌入模型将每个文本块转换为一个高维向量。这里可以选 OpenAI 的text-embedding-3-small也可以选本地部署的bge-m3。索引存储向量和原始文本一起存储到 Dify 内置的向量数据库里。社区版默认用的是 Weaviate也可以切换成 Qdrant、Milvus 等。当用户提问时Dify 会将问题向量化然后在向量库里做相似度检索把最相关的几个文本块召回连同用户问题一起塞给 LLM 生成答案。这个“检索增强生成”的过程就是 RAG 的完整链路。3.2 分段参数怎么调才能提高准确率“Dify 知识库准确率不高怎么调”这几乎是每个群里的置顶问题。我的经验是先别急着怪模型先检查分段策略。打个比方分段就像切菜。你要做一盘回锅肉肉片切得太厚调料进不去切得太薄一下锅就碎了。文本分段也是一样分段太长文本块里塞进大量无关信息向量化之后特征会被稀释召回精度下降分段太短上下文丢失召回的内容可能只是问题的一个零碎片段模型无法理解完整意思。具体到操作上我建议这样调如果你的文档是条款式、FAQ 式一问一答把分段长度调小到 200-300 token重叠长度调大到 100 token保证同一组问答不被切断。如果你的文档是长篇技术手册、论文分段长度可以放到 800-1000 token重叠长度设置 100-200让相邻段之间有足够的语义衔接。如果你的文档是代码建议在清洗规则里启用代码识别并且降低分段长度否则一段代码被拦腰切断之后语法结构就毁了。还有一个很实用但容易被忽略的操作知识库每个文档的“召回模式”。Dify 支持“向量检索”“全文检索”“混合检索”。默认的向量检索对语义理解好但有时关键词精确匹配更重要。政务、法律类的 RAG 项目里很多实体名称比如政策文号、专有名词用向量检索反而召回不准。我当时做政务项目时把召回模式改成了“混合检索”并开启Rerank重排模型准确率肉眼可见地提升了一截。3.3 本地部署 bge-m3 嵌入模型的心得嵌入模型是 RAG 的另一条腿。OpenAI 的 embedding API 确实好用但对很多企业来说把内部文档的向量化数据发到外部 API合规上就过不了。所以本地部署嵌入模型成了刚需。我在 Dify 里接 bge-m3 的方式有两种一是通过 Ollama 部署二是在 XInference 里部署。Ollama 更轻量XInference 的兼容性更广。我以 Ollama 为例在服务器上安装 Ollama 后拉取模型ollama pull bge-m3 ollama run bge-m3然后在 Dify 的“设置 - 模型供应商 - Ollama”里填入 Ollama 的 API 地址默认http://localhost:11434模型类型选“Text Embedding”模型 ID 填bge-m3。保存之后在知识库创建时的嵌入模型选项里就能看到它了。实测下来bge-m3 对中文文档的支持比很多英文原生的 embedding 模型强不少而且它是多语言模型支持中英混合文档。它的向量维度是 1024比 OpenAI 的 1536 稍小检索速度会快一些。如果你的场景主要是中文bge-m3 基本是社区里的默认答案。3.4 政务 RAG 知识库实战中的几个细节当时我们做的政务 RAG 项目有几个细节我印象特别深分享出来供你参考。第一政务文档的文件格式极其不友好。大量红头文件是扫描 PDF文本层完全不存在。Dify 自带的文档提取器对这类文件无能为力我们最后是在上游单独接了一个 OCR 服务把扫描件转成可编辑文本之后再投喂给 Dify 知识库。第二政务问答对引用的要求极高。答案不能是模型自己编的必须带着“出处”。Dify 知识库的引用属性设置里可以选择“有引用”模式这样模型生成的答案会附带引用的文档和分段内容界面还会高亮显示出处。这个能力在政务场景里简直是刚需。第三需要控制“幻觉”。政务场景宁可答不上来也不能胡说。我在 Dify 的 Prompt 编排里加了很严格的约束如果检索到的内容不足以回答问题必须明确回复“根据现有文件无法准确回答”不得自行推断。同时把知识库检索的“TopK”值稍微调高一点比如从 3 调到 5让模型有更多上下文可参考减少乱编的概率。4. 工作流与智能体实战从固定流程到动态决策4.1 工作流节点详解与搭建实例Dify 的工作流是整个平台里潜力和坑都最大的地方。你要把“AI 应用定制化”落到实处工作流是绕不开的。先看节点类型。我常用到的有这么几类开始节点定义入口参数。可以是对话输入也可以是 API 调用时的结构化参数。LLM 节点调用大模型。可以自定义 Prompt、模型、温度等参数。知识检索节点在指定知识库里做召回。可以和 LLM 节点串联实现 RAG。条件分支节点根据前面节点的输出走不同的分支。比如判断问题类型是“政策咨询”还是“办事流程”走不同的处理链路。代码执行节点支持 Python 和 Node.js 代码。这是工作流里灵活性最高的节点相当于给自己开了一个后门可以写任意逻辑。HTTP 请求节点调用外部系统的 API把第三方数据拉进来。比如查天气、查物流、查数据库。变量聚合器把多个分支的输出合并成一个节点方便后续统一处理。模板转换节点用 Jinja2 模板把变量拼接成一段文本或结构化 JSON。结束节点定义最终输出内容。我自己搭建过的一个典型工作流是“工单自动分类与知识推荐”。用户提交一个模糊的工单描述工作流先把描述传给一个 LLM 节点进行分类判断属于网络故障、账号权限还是硬件问题然后根据分类结果走不同的知识检索分支各自绑定不同的知识库最后把分类结果、推荐解决方案、相关文档链接拼装成一条结构化输出通过 HTTP 请求节点回传给工单系统。这个流程如果不用 Dify纯代码实现大概要写几百行还涉及 Prompt 管理、重试逻辑、结果格式化工作量不小。而在 Dify 里就是拖一拖、连一连的事。4.2 Agent 工作流中如何选择工具有了工作流的基础再来看 Agent。Dify 的 Agent 应用本质上是一个“会自己决定调用哪个工具”的智能体。和工作流“按图索骥”不同Agent 根据用户的请求动态决定调用哪些工具、按什么顺序调用。在 Dify 里给 Agent 配工具最常见的方式是“自定义工具”。你可以导入一个 OpenAPI schema也就是一个 JSON 格式的 API 描述文件Dify 就能自动识别里面的接口然后作为一个工具暴露给 Agent。举个例子我之前给一个内部系统配了一个“查请假余额”的工具。这个工具的后端是一个已经存在的查询接口参数就两个用户名、年度。Dify 的 Agent 在用户问“我还剩几天年假”时会通过 LLM 的 Function Calling 能力识别出这个意图自动抽取用户名和年度参数调用这个查询工具再把返回的数据加工成一段自然语言答案。整个过程用户完全感知不到工具的存在。还有社区里很火的“浏览器自动化工具”。Dify 社区有一些基于 Playwright 封装的工具可以让 Agent 打开网页、点击按钮、提取页面数据。这种工具在抓取动态网页数据时非常实用但我要提醒你一句浏览器自动化是重资源操作并发能力有限而且页面结构一变脚本就可能挂掉需要定期维护。4.3 Skill 机制把能力封装成可复用的技能包我注意到搜索热词里有 “dify skill” 和 “dify 的 skill”说明大家对技能机制越来越关注。Dify 的 Skill 可以理解为“工作流/工具的复用包”。比如你写好了一个“PDF 内容总结”的工作流可以把它封装成 Skill之后在别的应用里直接调用不用再重新拖一次节点。这个机制的思路其实很像软件开发里的函数库。以前你封装一个函数现在你封装一个能力。我在团队内部推动了一个做法所有常用工具和知识库处理流程都先沉淀成 Skill再基于 Skill 搭建应用。项目的可维护性和复用率提升非常明显。5. 多端发布与外部系统集成5.1 Dify 发布后的几种访问方式把应用做好之后发布成了下一个问题。Dify 发布应用的访问方式我总结下来至少有这么几种WebApp 直链Dify 会为每个应用生成一个可分享的网页链接直接在浏览器里打开就能对话。嵌入网页Iframe在 Dify 的“嵌入站点”里可以拿到一段嵌入代码贴到自己的官网或后台系统里应用就像原生组件一样嵌入进去。API 接入这是最灵活的方式。在 Dify 的“访问 API”里每个应用有专属的 API 密钥Bearer Token你可以通过调用 OpenAI 兼容的接口格式把 Dify 应用集成到任何自己的代码里。发布为工具Dify 应用可以被发布成工具供其他 Agent 或工作流调用。这是一种“应用套应用”的玩法。即时通讯平台比如飞书、钉钉、企业微信Dify 官方或社区提供相应的接入能力应用可以变成群里的机器人。移动端 SDKDify 提供了 Flutter、iOS、Android 的 SDK可以快速打包成移动端应用。官方把后几种统称为“被集成的七种方式”。我的看法是能走 API 就走 API除非项目要求必须快速演示。5.2 与飞书等 IM 平台的对接经验“Dify 如何对接飞书”是群里问得很频繁的问题。以飞书为例常规做法是走飞书的“自定义机器人”或者“应用机器人”。流程大概是在飞书开放平台创建企业自建应用拿到 App ID 和 App Secret配置事件订阅和机器人能力。然后在 Dify 这边如果官方没有直接的一键接入就用“API 接入 飞书事件回调”的方式自己做一个中间层飞书用户发消息事件回调把消息内容发给你的后端服务后端服务调用 Dify 的 API 拿到回答再通过飞书机器人 API 把回答发回群里或私聊。我踩过的坑是飞书的事件订阅有 URL 验证环节需要你的服务在被配置时能正确响应飞书发来的 challenge 验证请求。很多人在这一步卡住其实就是一个简单的 GET/POST 接口收到challenge参数后原样返回即可。5.3 数据库 MCP 工具如何配置使用关于 “Dify 中的数据库 MCP 工具如何配置使用”我多说一句。MCPModel Context Protocol是最近社区里特别火的一个协议本质上是把外部数据源或工具通过标准协议暴露给 AI 应用。在 Dify 里你可以配置一个 MCP 工具指向你的 MySQL 或 PostgreSQL 数据库这样 Agent 就可以直接查询数据表并基于查询结果回答问题。我自己的配置经验是不要给 Agent 太大的数据库权限。MCP 工具默认可能让模型执行任意 SQL这非常危险。建议在数据库侧创建一个只读账号并且在 Dify 的工具描述里明确写清楚“仅允许 SELECT 查询”避免模型生成 INSERT 或 DELETE 语句。生产环境上我甚至建议在 MCP 服务层做一层 SQL 白名单检查只允许执行符合规则模板的查询。6. 常见问题与排查技巧实录6.1 怎么让 LLM 不输出“思考过程”“Dify llm 怎么让模型不输出思考过程”——搜索量这么高说明踩的人真不少。这个问题的根源在于一些推理类模型如 DeepSeek-R1、Qwen 的推理模式在回答时会先输出一个“思维链”过程再输出最终答案。Dify 把这两部分都展示给了用户体验很糟糕。解决办法有几种在 Prompt 里主动声明“不要展示推理过程只输出最终答案”。如果是深度思考模型检查模型供应商的设置里是否有“思考模式”开关把它关掉或改为“隐藏”。在 LLM 节点的输出处理里用代码节点或模板节点只提取最终答案字段也就是去掉thinking相关的字段。如果是在聊天应用里可以在前端界面通过 CSS 隐藏思考区块。我最推荐的是前两种因为它们是从源头解决而不是事后裁剪。6.2 知识库文件排队中、不同步问题“Dify 知识库 文件 排队中”这个问题也很多人问。文件上传后一直显示“排队中”多半不是 Dify 自己卡了而是底层的文档处理任务没有执行成功。我遇到过的原因主要有这么几种worker容器没有正常运行。Dify 的文档解析和向量化任务是由 worker 容器异步处理的如果 worker 挂了任务就会一直排队。检查方法docker compose ps确认 worker 状态是 Up。向量数据库连接异常。如果 Weaviate 或其他向量库没有准备好索引写入会失败。嵌入模型 API Key 失效。如果配置的 embedding 模型调用失败任务也会卡住。排查思路是从下往上先看 worker 日志再看向量库状态最后检查模型供应商的连通性。6.3 工作流 debug 日志怎么用好Dify 工作流的调试功能是很多新手没充分挖掘的利器。在构建工作流时右上角有个“运行”按钮点击后会让你模拟输入参数。运行结束后每个节点下面都会显示详细的输入、输出和耗时。我的习惯是新建或修改工作流后先用一组典型的“正例”输入跑一遍确认主干逻辑通顺再用一组“边界情况”输入跑一遍比如空字符串、超长文本、不存在的用户 ID确认分支逻辑不出错最后用一组“异常输入”测试比如明显越权的内容确认系统不会崩溃。如果某个节点输出不符合预期就点开那个节点单独看它的 raw 输出。特别是在代码执行节点里变量名写错、类型不匹配等问题日志里会直接报出来看一次就知道怎么改。6.4 去掉 Dify Logo 与品牌自定义“Dify 去掉 logo”是另一个高频需求。这个操作本身不算复杂但要看版本。社区版里前端界面右上角有一个 Dify 的 Logo 和名称底部也有版权声明。如果你不想改了前端源码再重新构建镜像最快的办法是在系统管理后台的“外观设置”里看看有没有自定义选项。Dify 后台有些版本支持自定义应用名称但 Logo 不一定能直接替换。如果需要彻底去掉那就得动前端代码。在web目录下找到对应的 Logo 组件替换成你自己的品牌图然后重新打包 Docker 镜像。这个方式维护成本高因为每次 Dify 升级你可能都要重新打一次补丁。我一般建议如果是给客户交付的白标要求就去改如果是内部使用保留 Dify 品牌反而对后续升级友好。6.5 Windows 上部署和升级的其他琐碎问题Windows 上部署还有一个常见问题是路径中的反斜杠和空格导致 Docker 挂载卷失败。我的建议是解压 Dify 源码的路径不要带中文名、不要带空格比如直接放在D:\dify下。另外“dify 安装”阶段有用户反馈docker compose up -d之后页面打不开。排查顺序是docker compose ps确认所有容器是否都处于 Up 状态查看docker compose logs nginx确认前端服务是否正常检查本机防火墙是否放行了 80 端口如果 nginx 容器没起来大概率是端口被占用修改.env里的NGINX_PORT换一个端口比如8080重启即可。写到这里我回头看了一下这篇文章涉及的场景从 Windows 本地部署、多租户升级到知识库分段调优、bge-m3 接入再到工作流、Agent、Skill、飞书集成、MCP 工具和一堆疑难杂症基本覆盖了从一个 Dify 新手到能独立交付项目的完整路径。AI 应用定制化这个事远不是“调一个 Prompt”那么简单它需要你同时具备工程思维、数据意识和产品嗅觉。Dify 的价值在于帮你把工程复杂度降了下来但它并不会替你思考业务逻辑。我个人的体会是每个项目团队都应该尽快把 Dify 这类平台纳入自己的工具箱不用追求一次到位先拿一个小场景跑通全流程再逐步扩大应用范围。你很快会发现以前需要几个后端工程师忙活好几周的事现在可能一个下午就搞定了。