简介：面向具备一定编程基础、希望快速搭建基于大语言模型应用的开发者，这份DOCX文档系统解析了开源AI应用开发平台Dify，内容覆盖平台核心特性与智能客服、内容生成、数据分析等典型场景，并给出从Docker Compose到Kubernetes的完整部署流程及高可用配置建议。全文从基础安装、可视化工作流与提示词工程讲起，逐步深入到条件分支、循环与并行处理等复杂工作流设计，以及高级提示词技巧、API集成，同时延伸至插件系统架构、模型微调工作流和企业级最佳实践，能够帮助读者按入门到进阶的路径完整掌握Dify的使用方法。资源为单个DOCX文件，体积约30KB，正文以图文和可复制的配置代码为主，并包含环境变量、Deployment等关键配置示例，目录结构清晰，便于查阅和对照实践。目前已有498人学习下载，适合作为AI应用开发入门与进阶的技术手册。

1. Dify是什么：LLM应用从代码到配置的转折点

做过几个大模型应用落地项目之后，我越来越确认一件事：Dify这类平台真正的价值，不是省掉写几行代码，而是把「模型、知识库、工具、对话流程」这些本该粘在一起的东西，变成了看得见、调得动、改得快的可视化资产。Dify是一个开源的大语言模型应用开发平台，它把LLM应用从「纯代码工程」变成了「配置工程」：你在网页上拖几个节点、填几个参数，就能跑出一个带知识库和工具调用的AI应用。

这篇文章面向的是想快速把Dify用起来的人——不管你是后端工程师想减少重复开发，还是产品经理想自己验证AI交互方案，甚至是学生想搭一个完整Demo去参赛，按下面的路径走，都能在一天内跑通自己的第一个应用。我会先把平台的核心机制讲清楚，再带你在本地部署、建应用、配知识库，最后把那些调试时最容易翻车的坑挨个拆开。整篇的核心就一句话：Dify不复杂，但它的配置项都有代价，理解每个参数在改什么，比会点按钮重要得多。

2. Dify核心机制拆解：模型接入、应用编排与RAG管道的设计逻辑

2.1 模型接入层：为什么所有应用都先挂在模型供应商上

Dify所有应用的推理能力都来自外部模型，平台本身不训练模型、不托管权重。你在Dify里做的每一件事——对话、生成、分类、提取——最终都是把Prompt和上下文组装好，发给某个已接入的模型服务，再拿回结果。所以第一步永远是配置模型供应商：OpenAI-compatible接口、各类国产大模型API、本地部署的推理服务，都在「设置-模型供应商」里统一管理。

这个设计有一个容易被忽略的好处：上层应用逻辑完全不关心模型从哪来。一个工作流里可以同时用两个不同厂商的模型，一个负责意图识别（便宜、快），一个负责最终生成（更强、贵），互相不干扰。我一般会把开发和生产环境各配一套供应商：开发用本地模型省成本，生产切到正式的API key。这样做还有个附加收益——排查问题时，可以直接在同一个页面把模型切换成不同厂商，验证结果是模型能力问题还是Prompt问题。

配置模型供应商时有几个关键参数值得留意。API Base URL必须精确到能接受/chat/completions的路径；模型名称要填服务端真正注册的名字，不是随便起的别名；Temperature、Max Tokens这类参数在每个模型供应商配置里可以单独设置，但更推荐在应用编排的模型节点里再细调，因为不同场景对温度的要求完全不一样——分类任务要低温趋向确定，创意写作需要高温度发散。

2.2 应用编排层：聊天助手、Agent与工作流的边界

Dify把应用分成几类，新手最常犯的错是把它们混着用。聊天助手适合纯对话场景，本质是一个带系统Prompt的模型封装，适合客服、问答、角色扮演；Agent在聊天助手基础上加了工具调用能力，让模型可以主动决定要不要调用外部API、查知识库、做计算；工作流则是最灵活也最复杂的形式，你手动编排每一步逻辑，模型只负责其中特定的节点。

这三类应用不是递进关系，而是不同诉求的选择。如果你只需要一个稳定的问答机器人，聊天助手加知识库就够了——但很多人在这个场景硬上Agent，结果模型频繁误判该不该调工具，回复反而更不稳定。反过来，如果你的需求里有明确的「先判断、再检索、后生成」这种固定流程，只有工作流能保证步骤不跳、顺序不乱。

我自己的选型经验可以概括成三句话。流程固定且需要保证执行顺序，选工作流；希望模型自己决定下一步做什么，选Agent；最简单、只有一个Prompt加一个知识库的，选聊天助手，省得维护那些用不上的编排能力。这里还要提一个容易被忽略的边界：聊天助手其实也能挂知识库和少量工具，Agent和工作流的差别不在于容量，而在于控制权——控制权放在模型手里还是放在流程图里，这是选型的真正分界点。

2.3 配套服务：知识库管道与观测能力

Dify不是一个单纯的编排工具，它自带了完整的RAG管道：文档上传、文本提取、分段（chunking）、Embedding入库、检索召回，这些都在平台内闭环完成。这意味着你不需要自己写文档解析脚本，也不用单独维护向量数据库，知识库建好之后，在任意应用里通过「知识检索」节点或上下文注入就能引用。

管道里有一个关键设计：分段和Embedding一旦执行，就变成了知识库里的静态数据。之后你修改分段规则或更换Embedding模型，只对新写入的文档生效，老文档如果不重新分段和索引，检索效果不会变化。很多资料没提这一点，导致不少人改了分段大小后感觉「没效果」，其实是索引没重建。

观测方面，Dify提供了完整的调试追踪：每次对话的完整链路、每个节点的输入输出、Prompt最终拼装结果、模型返回的原始响应，都可以在调试面板里展开看。这个能力对排错极其重要，尤其是工作流应用——下游节点拿到的输入不对，往往是上游节点的输出结构理解错了。

3. 本地跑通首个应用：Dify部署与最小对话应用搭建

3.1 用Docker Compose启动Dify：最小部署命令与参数说明

本地部署Dify最常见的方式是Docker Comppose。以正式发布的版本为例，部署包自带完整的编排文件和Env示例，你只需要准备好Docker环境，然后启动服务。

# 1. 获取部署配置 git clone <dify官方部署仓库地址> dify cd dify/docker # 2. 复制环境变量模板并做最小修改 cp .env.example .env # 3. 启动所有服务，首次启动会拉取镜像，需要几分钟 docker compose up -d

这里要重点说明几个环境变量，改错任何一个都会让后面举步维艰。SECRET_KEY用于加密会话和应用内部数据，首次部署建议改成一段足够长的随机字符串，否则重启后会话可能失效；EXPOSE_NGINX_PORT决定你访问Dify控制台的端口，默认是80，如果你本机80端口被占，改成8080再访问http://localhost:8080；还有INIT_EMBEDDING_MODEL和INIT_LLM_PROVIDER——这两个变量控制安装完成后默认预置哪个Embedding模型和哪家模型供应商，如果不确定就用默认值，之后在页面上手动配也来得及。

启动完成后，确认服务全部进入healthy状态再开始配置。一个经常碰到的状况是，docker compose up -d命令看起来执行成功了，但实际上Web服务还处在启动中，页面打不开是正常的，等一两分钟再刷新就好。

注意：生产环境部署建议把默认账号密码改掉，并关闭注册入口。Dify管理后台的「安全设置」里有相关开关，这一步不要省。

3.2 创建第一个聊天助手：模型配置、Prompt调试与预览验证

服务起来之后，第一步是接入模型供应商。这里以本地部署的推理服务为例，这类Ollama兼容的本地推理服务可以通过OpenAI兼容接口接入。

# 假设你的本地模型服务已运行在 11434 端口 # 在Dify的"设置-模型供应商"里选择对应类型，填入以下参数： # API Base URL: http://host.docker.internal:11434/v1 # API Key: 任意占位字符串（本地服务通常不校验） # Model Name: 你的模型在推理服务中注册的名称

这里有个容易踩坑的点：Dify容器内部不能直接用localhost访问宿主机上的服务，必须用host.docker.internal这样的Docker内置域名。填错了地址，测试连接时永远报连接失败，查不出原因的情况多半在这里。

模型配好之后，开始建应用。进入「创建应用-聊天助手」，填应用名称后，核心配置集中在两个位置：左侧的「提示词编排」和右侧的「模型参数」。一个最小的客服助手Prompt，我通常这么写：

你是{{name}}的智能客服助手。你的职责是： 1. 基于已提供的知识库内容回答用户问题； 2. 如果知识库中没有相关信息，明确告知用户"暂时没有查到相关资料"； 3. 回答时保持简洁、直接，每次回复不超过200字。 当前对话历史： {{chat_history}} 用户问题： {{sys.query}}

这段Prompt里有两个内置变量需要认识：{{chat_history}}是Dify自动注入的对话历史，{{sys.query}}是用户当前的问题原文。在Prompt里显式声明对话历史很重要，因为如果你不写它，模型只凭当前问题回答，多轮对话完全没有记忆。右侧模型参数里，Temperature在客服场景我会调到0.2到0.4之间，保证回答稳定、不飘。

右上角的「预览」按钮已经够用了：右侧直接对话，下方可以展开每次对话的详细轨迹，能看到模型实际收到Prompt是什么、引用知识库的哪段内容、最终生成了什么回答。每次修改Prompt或参数都必须用真实问题重新验证一次，不要只点「运行」看它没报错就觉得万事大吉。

3.3 发布与调用：应用API的访问方式与凭证配置

调试完成之后，应用需要发布才能被外部访问。Dify里「发布」这个动作会把当前编排内容生成一个正式版本，之后对Prompt的修改在重新发布之前不会影响到线上API。这是好事也是坑——改了配置忘发布，外部系统调用的还是老版本，排查半天才发现问题出在「没点发布」。

发布后可以在「API访问」页签里找到两个东西：API密钥和API地址。密钥需要自己创建，创建时最好限制来源IP或指定可访问的地址。调用方式就是一个标准的HTTP POST请求：

curl -X POST 'https://your-dify-host/v1/chat-messages' \ -H 'Authorization: Bearer app-xxxxxxxxxxxx' \ -H 'Content-Type: application/json' \ -d '{ "inputs": {}, "query": "你好，请问你们支持哪些功能？", "response_mode": "blocking", "conversation_id": "" }'

response_mode有两个取值：blocking是同步等完整回答返回，适合后端服务之间的调用；streaming是流式返回，适合前端页面实时展示打字机效果。conversation_id是Dify用来维护多轮会话的标识，第一次调用传空字符串，响应里会返回本次会话的ID，后续对话带上它才能保持上下文连续。

4. 知识库与RAG落地：从文档上传到检索参数调优

4.1 文档接入与分段策略：Chunk大小怎么定

知识库是把Dify从「玩具」变成「生产工具」的关键一步，但它的效果好坏，七成由分段和检索配置决定，Prompt反而作用有限。Dify控制台的「知识库」模块支持上传多种格式文档，上传时会要求选择分段模式和分段规则。

Dify的分段模式分为自动分段和自定义分段。自动分段适合结构简单、篇幅短的文档，系统会按段落切分；自定义分段则允许你明确指定分段标识符、最大分段长度和分段重叠长度三个核心参数。实际使用中我很少用自动分段，因为不同文档的格式差异太大，自动切很容易把表格和列表切得稀碎。

分段长度的取舍，本质上是在两个风险之间找平衡：长了，语义完整但检索粒度粗，容易把不相关内容一起带出来，还更耗模型Token；短了，检索精准但语义可能被切断，关键信息分布在不同分段里，单段检索召回的上下文不完整。我的起步建议是：

• 操作指南、FAQ类文档：最大分段长度 500 到 800 字符，重叠 50 到 80 字符
• 技术规范、产品说明类文档：最大分段长度 300 到 500 字符，重叠 30 到 50 字符
• 长篇幅连续叙述类文档：最大分段长度 800 到 1200 字符，重叠 100 字符以上

分段重叠的作用是避免切分点正好落在关键句中间，给前后文一些「缓冲带」。重叠量不是越大越好，过大的重叠会让相邻两段内容高度相似，检索时召回一堆几乎重复的片段，既浪费Token又干扰答案质量。

4.2 Embedding模型与检索模式选型：三条路线的取舍

分段完成之后，文档需要经过Embedding模型转换成向量才能被语义检索。Dify允许为每个知识库单独指定Embedding模型，不同知识库之间互不影响。这里有一个值得注意的约束：知识库一旦建好并写入了向量数据，Embedding模型就固定了，不能随意更换——换Embedding模型等于把向量空间整体换掉，旧向量全部作废，必须重建整个知识库，这个操作在文档量大的时候非常耗时。

检索模式方面，Dify知识库提供三类选项，它们解决的问题不同。向量检索适合找语义相近但字面不同的问题，比如用户问「怎么退款」，文档里写的是「取消订单并返回费用」——字面差异大但语义一致。全文检索则按照关键词匹配，适合专业术语、型号、编号这类需要精确匹配的场景。混合检索把两者结合：先用全文检索锁定候选集，再用向量相似度重排。大部分场景我会直接选混合检索，这是默认值和最稳的组合。

Embedding模型选择上，如果文档以中文为主，优先考虑对中文支持更好的模型；文档中英文混杂，则选多语言能力覆盖好的模型。判断Embedding效果好不好的笨办法也很实用：建完知识库后不做任何调参，直接在「召回测试」里输入几类典型问题，看召回分段是否命中了你心里预期的那段内容——命中就是好，不命中的该调参数调参数，该换模型就换模型。

4.3 检索参数调优：TopK与Score阈值的配合方法

知识库检索有两个核心参数在每次应用中可调：TopK决定一次取回多少分段，Score阈值决定只保留相似度高于多少的分段，对我个人而言这其实是「数量」与「质量」之间的平衡旋钮。

参数调整上值得注意的细节是：TopK加大之后检索结果变多，一方面可能带上不相关的内容干扰模型，另一方面上下文过长会挤占模型的输出长度。Score阈值调高会让召回变得更「保守」，只敢放相似度极高的片段，但如果知识库里本来就没有跟问题特别接近的文本，阈值调太高反而会变成「从未检索到任何内容」。

参数之间不是孤立的。我的习惯是先把Score阈值设定得比较低比如0.2到0.3，保证有东西进来；然后用真实问题看召回了什么，逐步把阈值往上推，同时观察TopK能不能往下收。当一份文档里刚好有两个分段都在描述同一个问题时，检索结果会一起带回，这时应当降低TopK，或者检查分段是否重叠过多，而不是靠阈值去硬挡。追求检索精准度的一个实用技巧是：把Prompt里加一段「如果检索内容与问题无关，直接说明没有找到相关信息」，让模型做一道质检，比你在参数上反复拉扯更有效。

4.4 知识检索节点并入工作流：从知识库到应用的正确接法

知识库建好只是第一步，真正需要理解的是「怎么把检索结果接到应用里」。在聊天助手应用中，可以在Prompt中引用知识库上下文变量；在工作流应用中，则通过「知识检索」节点完成这一步。

工作流里的知识检索节点有几个关键配置要做：选择一个或多个知识库、设定检索模式、指定TopK与Score阈值。节点运行后输出一个数组结构，包含每个命中的分段内容、相似度分数、来源文档和分段ID。这里新手经常翻车——不知道知识检索节点的输出是个数组，在下一个节点里直接当字符串拼接，结果整个流程跑不通。正确做法是：先运行一次节点，在调试面板里看输出的数据结构，再配置下游节点怎么取这个数组里的字段。

知识检索节点还有一个常被忽略的高级特性：可以在节点内设置「重排序」开关。开启后，Dify会调用额外的重排序模型对召回结果重新打分排序，把最贴合问题的内容排到最前面。代价是多一次模型调用，延迟和成本都会略增。对答案质量要求高的场景建议开启，对响应速度敏感的场景可以先关掉。

5. 高频翻车排查：Dify应用开发中的常见问题与解决方法

5.1 知识库检索不到内容，或者答非所问

现象：应用能正常对话，但你问知识库里的内容，模型要么说不知道，要么答得文不对题。在调试面板里看知识检索的调用记录，发现命中的分段根本和问题不沾边，或者命中的分段数量为零。

原因：最常见的是分段策略不合理。每段太长，一段里塞了太多不同主题的内容，向量化之后无法准确表达其中任何一个小主题，检索时自然匹配不上。其次容易忽视的是Score阈值设太高了，和问题本身就不够相似的相关内容已经低于阈值被过滤了，看起来像知识库失效，其实是过滤器把结果掐掉了。另外还有一个原因做错了Embedding模型选型，随便选了与你文档语言不匹配的模型，向量空间表达完全不对。

解决：先用「召回测试」做定位，把问题输入进去，拉低Score阈值，打开TopK，查看召回结果。如果这种情况下还是召回不到相关内容，问题出在分段或Embedding模型上，重新按上文建议调整分段长度，必要时重建知识库换Embedding模型。如果调低阈值后能召回了，那问题就出在你阈值上下限的搭配上，把阈值往下调一档再试几个问题，找到「下限太松、上限太紧」之间的那个量感。

注意：查询时的问法和分段写法也影响匹配。冗长的带语气修饰的提问，不如直接拆成关键实体词搜索，这一点对关键词型知识库检索特别有效。

5.2 工作流节点设置了但没生效，流程默默跳过某一步

现象：工作流的流程图里明明拖了「知识检索」和「LLM」两个节点，连线也对，但最终的Debug输出里只看到LLM节点的调用，知识检索节点压根没有执行记录。

原因：Dify工作流的执行逻辑和手动操作直觉不一样——「连线」只表示数据从上往下游传递，不代表上游一定会先执行，除非下游节点确实需要上游的输出作为输入。如果你把知识检索和LLM节点画成了两条平行分支，而LLM节点没引用知识检索的任何输出字段，执行引擎就会跳过知识检索，因为它是「死分支」。

解决：检查知识检索节点的输出变量是否真的被LLM节点的Prompt模板使用了。在LLM节点的输入配置里，把知识检索输出添加为一个变量，并在Prompt中显式写上这个变量，例如{{#context#}}。只看流程图不点每个节点展开看具体变量绑定，几乎不可能发现这个问题。我自己的习惯是：每次改完工作流，点开每一个节点，确认它的输入变量名称来自上游哪个节点，再运行测试，别只看整体链路。

5.3 长文档召回结果太多，上下文溢出把对话撑爆

现象：知识库文档一多，召回的分段数量多、单段又长，模型在生成答案时出现「超出最大上下文长度」的报错，或者回答到一半直接断掉，输出内容与原来的长度上限对不上。

原因：应用模型的了上下文窗口是有限的，它属于公有硬性约束。当检索TopK设得偏高、分段长度又大时，拼装到Prompt里的内容很容易超过可用窗口。有些场景下并发调用也很容易加重这个问题，容错空间几乎没有。

解决：按下表做一次整体压降。

调整之后注意一个连带反应：TopK降了、分段短了，回答的信息完整度可能下降，这就要求Prompt里明确写「如果检索内容不足以回答问题，直接说明需要补充信息」。在长文档场景里，额外建议再检查各个分段之间是不是存在大量重叠内容，重叠过密会导致多个分段讲同一件事，等于浪费了好几段上下文空间。

5.4 同一套配置，预览正常但API调用报错

现象：在Dify页面预览里测试对话完全正常，把应用发布后通过API调用，返回报错或者回复内容和预览时完全不一致。

原因：90%的情况是没有重新发布。你在预览时的调试配置，和发布到API的线上版本是两套状态。工作流内容在预览里是一份「草稿」，发布时选择的是一个版本快照。改完Prompt或知识库参数之后没有点「发布」，API就会一直用旧版本。另外还有一种少见情况——发布后立刻调用，API网关的缓存还没过期，导致短暂路由到了旧版本。

解决：每次改完配置，发布前先在「发布版本」页签里看一眼当前生成的版本是不是包含最新改动。发布后等10到20秒再发起调用，一来是给网关缓存刷新留时间，二来是避免跨服务读取到不一致的配置快照。如果还是对不上，查看API调用日志中的响应头或错误码，确认命中的服务实例没有异常。

5.5 Prompt里的变量语法没问题，但模型就是拿不到值

现象：Prompt里写了变量，比如{{user_name}}，调试时发现模型回复里把变量名原样输出了，或者变量显示为空。

原因：变量名拼写错误之外，最隐蔽的情况是作用域问题——工作流里每个节点有自己的变量作用域，上一个节点的输出变量，如果不通过「变量赋值」节点或上下文引用映射到当前节点，当前节点的Prompt里就引用不到。聊天助手里也有类似的坑：自定义变量需要先在「变量」面板里声明，才能被Prompt引用，只写在Prompt模板里不声明，不会自动生效。

解决：在调试面板里打开「变量」标签页，逐项查看每个变量在执行时的实际值，是空字符串还是有内容。如果实际值有内容但模型输出变量名，说明Prompt拼装时语法标识写错了——Dify的变量引用用的是双大括号语法，大小写敏感的字段漏了一个符号都会导致原样输出。我在这个坑上消耗过不少时间，现在的习惯是先点调试面板看变量实际值，再怀疑自己的Prompt语法，而不是反复重写Prompt猜原因。

6. 工作流与Agent高级玩法：变量传递、并行执行与效果验证

工作流类应用的调试效率比其他类型高一个量级。它最大的优势是有「分支」和「并行」能力——你可以在一次运行里对同一个输入同时跑多个LLM节点，分别做总结、分类、情感分析，再由后面的节点合并结果。我常用一种做法是：用第一个LLM节点做意图分类，分类结果作为条件分支的判断依据，不同分支走各自的Prompt和处理逻辑，这样做出来的应用边界清晰、每个分支的Prompt短而专注，好调试得多。

并行执行时有一个参数我几乎每次都调：每个分支节点的最大回复Token数。并行节点是各自独立计费的，但共享同一个上下文窗口，同时跑三个大输出节点很容易把上下文顶爆。我会把需要长输出的分支单独拉出来串行执行，短输出的分支并行走。

变量传递是工作流真正的骨架。跨节点传数据靠「变量赋值」节点，它的行为是「把上游节点的输出结构化成指定名称的变量」，供下游引用。这里有一个习惯值得养成：给每个变量起名时携带来源信息，比如ctx_kb_result、llm_classify_label，排查时一眼看出当前值来自哪个环节，比叫output1、output2高效得多。

效果验证方面我推荐一档固化的验收清单：准备好5到10个覆盖典型场景的真实问题，每次改动配置之后完整跑一遍。重点看三类东西：召回分段是否命中预期内容、模型回答是否引用了召回内容而非自己编、回答延迟是否在可接受范围。以前我做知识库应用，凭感觉调参数调了好几天也没有明显起色，后来固定了这组验收问题集，每次只动一个参数，对照回答质量变化再决定下一步，收敛速度快了很多。

最后分享一个算过账的教训：Dify的编排能力再强，也只是执行层，真正决定应用上限的是顶层设计——知识库的分段策略、Prompt的结构、模型和参数的搭配。刚开始用Dify的时候，我总把时间花在摸索按钮上，觉得把界面功能都点一遍就能通晓全局，后来被一个极其简单的变量传递问题卡了两天才意识到，把「每个参数在改什么」弄明白才是正确方向。从那以后我养成了每天读完一个配置项的文档再动手的习惯。这个思路现在也分享给你，希望帮到你。

本文还有配套的精品资源，点击获取