如果你最近在关注AI应用开发Dify这个名字大概率已经在各类技术社区刷屏。定位上Dify是一个开源的LLM应用开发平台简单说就是帮你把大模型、知识库、工作流、Agent这些能力封装成可视化可编排的产品让开发者不需要从零写一堆胶水代码就能把一个有业务逻辑的AI应用跑起来。这篇是“Dify从入门到精通”系列的第一篇目标非常明确把Dify是什么讲透同时带你把环境跑起来做出第一个能对话的智能应用。适合刚接触Dify、想本地部署试一试、或者已经在用但想系统梳理一遍的朋友。我最早接触Dify是在1.0版本刚开源的时候当时团队要做企业内部的知识库问答系统选型对比过LangChain全家桶、Flowise、FastGPT最后留在了Dify上。原因很简单Dify把模型管理、RAG流程、Agent编排、应用发布这些高频需求全部做成了开箱即用的模块既保留灵活性又不像LangChain那样要自己组装太多零件。接下来我会按自己的实操经历从部署、接入模型到发布应用一步步讲争取这篇看完你就能把Dify跑起来。1. Dify是个什么东西它到底解决了我什么痛点1.1 为什么现在做AI应用这么难做AI应用和做传统后端应用有一个本质区别传统应用里逻辑是你写的数据流是你控制的出问题你知道去哪里查。但到了大模型时代核心逻辑变成了“模型的输入输出”你要考虑上下文管理、提示词策略、知识库切片与召回、Token成本、模型切换、流式响应还有用户会话多轮管理。这些东西单独拆开都还好组合在一起就是一团乱麻。我见过很多团队做AI功能初期找人写一个调用OpenAI接口的脚本测试时很爽等到要接知识库、做多轮对话、按权限控制访问、上生产环境脚本直接变成面条代码改一行崩三处。Dify做的最重要的事就是把“模型调用”和“应用逻辑”解耦。你只需要在界面上把节点拖进来、连上线、填参数一份可维护、可观测的AI应用就完成了。它不替代你的后端但把你后端的AI部分几乎全部接管了。1.2 Dify做了哪些事以及它能替代什么Dify在LLM应用开发生态里的位置大致相当于“WordPress之于建站”。你不需要手写HTML、CSS、JS去实现一个博客系统而是在一个后台里选模板、填内容、发布上线。Dify也是一样它把开发AI应用最常见的几块能力全部做成了模块模型接入层OpenAI、Anthropic、Azure OpenAI、Google Gemini以及所有兼容OpenAI协议的模型服务当然也包括本地部署的Ollama、Xinference等。一套界面统一管理切换模型不用改代码。RAG能力文档上传、自动切片、向量化、检索召回还支持Rerank二次排序这块是知识库问答的核心。工作流编排支持类Coze的拖拽式工作流把LLM、代码执行、条件判断、HTTP请求等节点串起来做自动化任务。Agent能力给模型配置工具比如网页搜索、内部API、数据库查询让它自动决定调用哪个工具完成复杂任务。应用发布与管理内部使用可以发布成WebApp外部接入可以走API还自带用户管理和访问凭证控制。这套组合拳下来Dify能替代你原本用LangChain FastAPI 向量数据库 前端页面这堆技术栈组合起来的全套后端逻辑。你省下来的时间可以全部投入到业务本身比如优化知识库内容、打磨提示词、调工作流逻辑这比每天跟Embedding维度、向量库连接池参数死磕有价值得多。2. 上手前的准备工作从选型到本地部署2.1 二选一用云端版本还是自己部署Dify官方提供了两个使用途径一个是注册并使用Dify Cloud云端服务另一个是社区版自托管部署。我没有贬低云端版的意思但作为开发者和技术团队我强烈建议至少从本地部署开始接触。原因有三点第一社区版功能完全够用核心能力与云端版基本一致而且没有API调用配额限制。第二本地部署意味着数据完全掌控在自己手里企业内部文档接入知识库没有隐私顾虑。第三部署过程本身就是一次环境预检你能直观理解Dify的架构依赖哪些基础设施后面出问题排错会快很多。如果只是纯粹想快速看一眼Dify长什么样那直接去官网注册云端版体验也可以。但如果你要认真用起来、做二次开发或者接入企业内部系统请跟我走一遍本地Docker部署。2.2 在Windows上本地部署Dify的完整步骤先说环境前提Dify本质是一组Docker容器编排所以你需要本机装有Docker Desktop并且把资源配额调高。Dify全家桶包含API服务、Worker、Web前端、PostgreSQL、Redis、Weaviate或Qdrant等多个容器内存建议至少8GB磁盘预留20GB以上比较稳妥。我以Windows系统为例实际步骤记录如下去Dify官方GitHub仓库的Releases页面下载最新版压缩包dify-main.zip这种格式。注意是docker目录所在的那个完整包不要只下载源码片段。将压缩包解压到本地比如D:\dify然后进入dify-main\docker目录。在docker目录下打开命令提示符可以先执行dir确认文件都在。首次启动前需要创建环境变量文件直接复制模板cp .env.example .env启动全部容器docker compose up -d这里补充一下新版本Dify已经使用docker compose插件旧版如果是docker-compose请更新。启动过程会拉取镜像时间取决于网络状况。等待所有容器状态变成healthy用下面命令查看docker compose ps浏览器访问http://localhost或http://localhost/apps首次打开会进入管理员账号初始化页面设置邮箱和密码后即可登录。整个过程看起来不难但实际部署时最大的坑基本都集中在镜像拉取失败和容器启动顺序上。下面专门讲一下镜像拉取的问题这几乎是每个本地部署Dify的人都会遇到的第一道坎。2.3 镜像拉取失败的处理思路我见过太多人在这一步卡死日志里反复出现failed to pull image、dial tcp: lookup ... no such host、EOF这类错误。这不一定是你操作有问题而是国内网络环境访问Docker Hub的常规障碍。解决方法有几个层面按顺序尝试给Docker Desktop配置镜像加速器。打开Docker Desktop进入Settings - Docker Engine在配置JSON中添加registry-mirrors填一个你所在地区延迟较低的加速地址。改完点击Apply Restart。这个方法对多数人有效。如果加速器效果不理想可以考虑使用代理环境。但如果你不方便用代理还有一个更实用的办法找一台能正常拉取镜像的机器用docker pull手动拉取后通过docker save导出镜像包再拷贝到目标机器docker load。这套离线镜像迁移流程在部分企业内网环境是标准操作。还有一种情况是你改了.env里的镜像版本但本地没有对应tag的缓存这时候可以先把旧的Dify容器彻底清理掉再重新执行docker compose up -d避免Tag混乱导致拉取长时间无响应。注意部署完成后如果修改了.env文件里的配置比如更换向量数据库、调整端口一定要执行docker compose down然后重新docker compose up -d而不是只重启部分容器否则配置不会全量生效。3. 接入大模型让Dify跑起来的临门一脚3.1 模型供应商的整体概念Dify部署完成之后登录进去第一眼会看到欢迎页但真正要开始用你得先接一个大模型。Dify把模型接入抽象成了“模型供应商”的概念。供应商可以是OpenAI这种云端服务商也可以是你本地跑的Ollama、LM Studio、Xinference等开源推理服务。在Dify的“设置 - 模型供应商”页面会看到一张已经支持的供应商列表。点击任意一个提供商填入对应的API Key和Base URL就能激活该服务。多人协作场景下管理员配置好模型后团队成员直接用就行不用每个人都去申请API Key。这里有个很容易被忽略的点Dify的模型分为几类第一大类型是“系统推理模型”也就是聊天对话、文本生成使用的底层大模型比如GPT-4o、Claude 3.5 Sonnet或者本地Llama系列。第二大类是“Embedding模型”用于知识库文档向量化。第三类是“Rerank模型”用于知识库检索后的精排。新手经常只配了推理模型然后发现知识库上传文档后问答效果很差一查日志才发现Embedding没配或者没配对。3.2 接入本地Ollama模型零成本跑通对话如果你暂时不想花钱申请云端API我推荐先用Ollama把本地模型跑起来再接进Dify。Ollama是一个极简的本地大模型管理工具一条命令就能下载并启动模型。我在没有GPU的笔记本上用Ollama跑过qwen2.5:7b速度虽然一般但验证流程完全够用。Ollama安装后默认监听在http://localhost:11434但要被Dify容器访问这里的地址有讲究。你在Dify的模型供应商里选Ollama填的Base URL不能是http://localhost:11434因为Dify容器内部访问不到你宿主机的localhost。在Windows和Mac上Docker Desktop提供了一条宿主机特殊域名host.docker.internal所以应该填http://host.docker.internal:11434在Linux宿主机上则要直接用宿主机局域网IP如果没有额外配置host网络模式的话。这个细节我见过不少人在社区里问“为什么本地模型连不上”十有八九都是Base URL填错了。填好模型名称后点击保存系统会做一次连通性检测。如果提示连接失败按下面顺序排查确认Ollama服务正在运行浏览器访问http://localhost:11434能出现Ollama is running。确认在Dify里填的Base URL是host.docker.internal而不是localhost。确认Ollama里已经拉取了你填写的那个模型名比如ollama pull qwen2.5:7b。在Dify容器内部临时执行wget http://host.docker.internal:11434测试连通性能通就说明网络层没问题。3.3 Embedding与Rerank模型知识库效果的隐形决定者很多人第一次用Dify做知识库问答传了文档进去却发现回答质量惨不忍睹不是答非所问就是漏掉关键信息。这里我先给一个经验总结如果只配了推理模型知识库问答的效果大概率不会好。原因在于知识库涉及两条链路入库时要把文档切片编码成向量这叫Embedding检索时要对召回的候选段落做相关性精排这叫Rerank。两者分别需要专门的模型。Embedding方面Dify内置支持多种模型。国内使用比较稳定的是BAAI/bge-m3系列它可以在Ollama里直接跑。你也可以用OpenAI的text-embedding-3-small效果不错但会产生费用。我的实践经验是中文场景如果不追求极致效果bge-m3已经够用如果做专业领域比如法律、医疗术语多建议测试多个Embedding模型的效果差异再定。Rerank方面Dify推荐配置一个Rerank模型比如Cohere的Rerank接口或者开源的BGE Reranker。配置Rerank后知识库检索流程会变成先用Embedding召回Top-20候选再用Rerank模型精排取Top-3。这一步对准确率提升非常明显尤其是在文档数量多、内容相似度高的场景。我现在做新项目Rerank几乎是必选项没有Rerank的RAG系统总觉得少了灵魂。提示在“设置 - 模型供应商”里不同的模型类型要分别配置。推理模型、Embedding模型、Rerank模型是三个独立配置项别混在一个入口里找。4. 快速上手从创建应用到发布第一个智能助手4.1 应用类型的选择聊天助手还是文本生成模型配好之后就可以创建第一个应用了。Dify创建应用时有几个类型选项最常见的是“聊天助手”和“文本生成”另外还有“Agent”和“工作流”。聊天助手适合多轮对话场景自带会话记忆能力用户问一句答一句上下文自动关联。用于客服、知识库问答等。文本生成适合一次输入、一次输出的场景比如写摘要、生成文案、翻译。它不做多轮会话管理逻辑更简单。Agent聊天助手的增强版可以配置工具模型在对话中会自己判断是否调用工具以及调用哪个工具。适合查数据、查天气、调API等动作型应用。工作流多节点编排模式适合有明确流程的任务比如先检索知识库、再让LLM总结、再做敏感词过滤、再输出。对第一个应用来说我建议从“聊天助手”起步。它最简单、最容易看到即时效果而且聊天助手里也能挂知识库足以体验Dify最核心的能力。命名可以随意比如“第一个智能助手”模型选择你刚接入的那个。4.2 提示词编排界面不需要会编程的“系统提示词”创建完应用会进入Dify最有名的“提示词编排”界面。左边是提示词输入区右上角是模型参数配置右下角可以直接跟应用对话调试整个布局非常适合新手。提示词编排的本质是给模型设定角色和规则。你可以把系统提示词理解为“给一个刚入职的新人写工作说明书”它决定了模型以什么身份、什么语气、什么边界来回答。一个最简单的系统提示词可以是这样你是一个专业的IT技术支持助手。请用简洁、准确的中文回答用户的问题。如果用户的问题与IT无关请礼貌说明你无法回答并建议用户咨询相关专业人员。界面里还可以做变量引用比如加一个{{input}}占位符运行时Dify会把用户输入自动替换进去。右上角的“模型参数”可以调整温度temperature、Top P、最大Token等。新手阶段建议温度保持在0.5以下尤其是做知识库问答时温度太高模型容易“编造”内容。调试框就在右下角直接输入“你好”测试如果模型有响应恭喜你的第一个Dify应用已经活了。这里我会额外建议先不要急着调复杂功能把系统提示词反复打磨几次试试不同表达对回答风格的影响这比一开始就冲进去做工作流更有手感。4.3 发布与调用WebApp和API两种方式调试满意之后点击界面上方的“发布”按钮应用才正式对外生效。发布后Dify提供两种使用方式第一发布为WebApp。在“概览”页会生成一个访问链接别人打开就能用不需要登录后台。这个适合快速做Demo给业务方看效果。第二通过API调用。在“API访问”菜单里Dify会生成应用的API密钥类似app-xxx的字符串。同时Dify提供了完整的RESTful API接口后端服务可以用HTTP方式调用这个应用。这样Dify应用就变成了你业务系统里一个AI能力微服务前端页面、企业微信机器人、钉钉机器人都可以通过API对接。我第一次生产接入时就是先把Dify应用调好然后从自己的后端发HTTP请求到Dify的API传用户问题、收AI回答整体非常顺。这里提醒一下API密钥不要暴露在前端代码里一定要由后端代理调用否则别人拿到密钥就能白嫖你的Token额度。密钥权限管理在“访问控制”里还可以配置允许的IP列表建议开起来。5. Dify核心功能地图先看清你面前有哪些武器5.1 工作流把AI从一个“对话框”变成一条“流水线”很多人第一次接触Dify把它当成一个高级ChatGPT套壳这就太低估它了。Dify真正的威力在于工作流英文叫Workflow。它让你像画流程图一样把LLM节点、知识库检索节点、代码执行节点、条件判断节点、HTTP请求节点串联起来实现一个复杂的自动化任务。举个例子接一个“根据语意生成SQL”的内部工具。传统做法是你写一套NL2SQL的代码定义意图识别、表结构映射、SQL校验、结果解释这些模块。在Dify工作流里可以这样搭开始节点拿到用户问题知识库节点召回相关表结构和历史SQL样例LLM节点基于这些上下文生成SQL代码节点做语法校验最后HTTP请求节点执行查询再把结果通过LLM节点转成自然语言回复。整个过程可视化每一步的输入输出都看得到排错比看日志直观得多。第一篇我先不展开工作流的细节但你要建立这个意识Dify不止是做聊天它是一个应用编排平台。后面的系列文章会专门用整篇篇幅讲工作流节点的选择、参数传递、循环和分支逻辑怎么写。5.2 知识库Dify里最实用的企业级能力知识库是Dify日常使用频率最高的功能没有之一。你可以把PDF、Word、Markdown、TXT、甚至网页内容上传进去Dify会做文档解析、分段、向量化之后在聊天助手里开启“知识库”功能问答时自动检索相关内容作为上下文给模型参考。假设你有一套内部产品手册几百页PDF员工问“XX功能的限额是多少”传统方式是翻文档用了Dify知识库后几秒钟就能得到准确答案。但前提是你得知道文档切片粒度直接影响检索效果。切太大检索召回准确率降低切太小上下文碎片化模型缺少完整逻辑。Dify默认提供自动分段模式但针对多级标题结构明显的文档我建议在分段设置里开启“自定义分段标识符”用Markdown标题作为分隔。这个方法能让段落结构更符合原文档逻辑检索效果明显好于无脑按字数切。5.3 Agent与多智能体更复杂的AI应用形态我注意到最近社区里关于Dify多智能体的讨论越来越多比如和AgentScope、Java后端结合做多智能体协作。Dify的Agent能力目前主要是“单Agent 多工具”模式模型根据任务目标自主决定调用哪些工具、按什么顺序调用。Dify本身就支持在Agent里接入多个自定义工具和插件可以实现“帮我查天气再根据天气推荐穿搭”这种需要两步动作的任务。如果你要做多个AI角色协同决策的“多智能体系统”Dify的Agent可以直接作为一个节点嵌入到工作流中外部再通过API统一编排。坦白说多智能体本身还比较前沿生产环境落地要关注的不只是技术还有业务规则怎么拆、错误怎么兜底。新手阶段先把单Agent的工具调用玩明白后续我会专门写一篇如何基于Dify构建多智能体协作应用。6. 高频问题与避坑记录我在实际部署和日常使用中踩过的坑6.1 端口占用与容器启动失败Dify默认使用80端口提供Web服务如果本机80端口被占用容器启动会报端口冲突。解决办法是在.env文件里改EXPOSE_NGINX_PORT8080然后访问http://localhost:8080。改完保存后执行docker compose down再docker compose up -d。另外Dify依赖的PostgreSQL和Redis如果端口被本机已有的服务占用也会启动失败。一般改宿主机的映射端口即可方法同上在.env里找到对应配置项修改。启动后观察日志docker compose logs -f api看到类似Starting server at port 5001的日志基本可以确认后端已经起来了。6.2 不同版本的差异1.17.1和1.15.0到底差在哪很多人在社区问Dify 1.17.1和1.15.0的区别。我在升级到1.17.1后感受明显的几个变化一是工作流节点类型和调试体验有优化变量赋值器的操作更顺手二是构建Agent时的工具调优界面更清晰三是修复了一些知识库检索的边界问题。不过1.15.0作为稳定版本在旧项目里跑得也很好。我的建议是新项目直接用最新稳定版老项目如果工作正常没必要频繁升级。升级Dify的方法是先在GitHub Releases里下载新版压缩包备份.env和docker目录里的数据卷然后替换代码目录再执行docker compose down和docker compose up -d。数据卷特别是PostgreSQL和向量数据库的持久化目录一定不要删除否则所有知识库和应用配置都会消失。有条件的话升级前先对整个 docker 数据目录做一次快照或者压缩备份。6.3 几个我实际遇到过的操作细节先说一个最不起眼但影响很大的上传文档的大小限制。Dify默认上传文件大小限制有上限如果你要传几百MB的PDF可能会直接失败。这个限制可以在.env里调整UPLOAD_FILE_SIZE_LIMIT单位是根据文档说明来的通常用MB。我在做制造业设备手册入库时就遇到过这个问题改成较大值后重启服务就正常了。再说变量赋值器。Dify工作流里有一个节点叫“变量赋值器”作用是把前面节点的输出重新组织成后面节点需要的变量格式。我印象最深的场景是LLM节点输出的是一段带Markdown格式的文本但下游HTTP请求节点要求JSON格式这时候就靠变量赋值器做转换和取值。新手经常忘记看节点输出的数据类型直接连线导致下游解析报错。记住一个原则连线之前先点开上游节点的输出预览确认字段结构再决定要不要加一个变量赋值器或代码节点做转换。最后是第三方登录授权问题。Dify社区版支持通过飞书等平台创建应用并用于内部用户登录但首次使用飞书云文档的授权凭证时很多人找不到app_id和app_secret在哪。这里强调一点飞书的凭证不是填在Dify的“设置”里而是在创建飞书自建应用后从飞书开放平台的“凭证与基础信息”页面复制然后再到Dify对应渠道配置里填入。如果授权失败优先检查回调地址是否已经配置到飞书应用的“重定向URL”里。我自己在写这篇系列文章时把之前折腾Dify的过程重新复盘了一遍。从最开始拉镜像失败、模型连不上到后来用工作流做自动化报告、给业务方搭知识库问答机器人Dify确实把我从大量重复的模型对接代码里解放了出来。第一篇的内容先到这后面的文章我会逐步深入工作流编排、知识库进阶调优、Agent工具开发这些方向。如果你按这篇文章部署成功了可以动手试着自己搭一个简单问答应用遇到问题随时回来对照第6节的排查思路。 Dify从入门到精通：本地部署与首个AI应用实战
如果你最近在关注AI应用开发Dify这个名字大概率已经在各类技术社区刷屏。定位上Dify是一个开源的LLM应用开发平台简单说就是帮你把大模型、知识库、工作流、Agent这些能力封装成可视化可编排的产品让开发者不需要从零写一堆胶水代码就能把一个有业务逻辑的AI应用跑起来。这篇是“Dify从入门到精通”系列的第一篇目标非常明确把Dify是什么讲透同时带你把环境跑起来做出第一个能对话的智能应用。适合刚接触Dify、想本地部署试一试、或者已经在用但想系统梳理一遍的朋友。我最早接触Dify是在1.0版本刚开源的时候当时团队要做企业内部的知识库问答系统选型对比过LangChain全家桶、Flowise、FastGPT最后留在了Dify上。原因很简单Dify把模型管理、RAG流程、Agent编排、应用发布这些高频需求全部做成了开箱即用的模块既保留灵活性又不像LangChain那样要自己组装太多零件。接下来我会按自己的实操经历从部署、接入模型到发布应用一步步讲争取这篇看完你就能把Dify跑起来。1. Dify是个什么东西它到底解决了我什么痛点1.1 为什么现在做AI应用这么难做AI应用和做传统后端应用有一个本质区别传统应用里逻辑是你写的数据流是你控制的出问题你知道去哪里查。但到了大模型时代核心逻辑变成了“模型的输入输出”你要考虑上下文管理、提示词策略、知识库切片与召回、Token成本、模型切换、流式响应还有用户会话多轮管理。这些东西单独拆开都还好组合在一起就是一团乱麻。我见过很多团队做AI功能初期找人写一个调用OpenAI接口的脚本测试时很爽等到要接知识库、做多轮对话、按权限控制访问、上生产环境脚本直接变成面条代码改一行崩三处。Dify做的最重要的事就是把“模型调用”和“应用逻辑”解耦。你只需要在界面上把节点拖进来、连上线、填参数一份可维护、可观测的AI应用就完成了。它不替代你的后端但把你后端的AI部分几乎全部接管了。1.2 Dify做了哪些事以及它能替代什么Dify在LLM应用开发生态里的位置大致相当于“WordPress之于建站”。你不需要手写HTML、CSS、JS去实现一个博客系统而是在一个后台里选模板、填内容、发布上线。Dify也是一样它把开发AI应用最常见的几块能力全部做成了模块模型接入层OpenAI、Anthropic、Azure OpenAI、Google Gemini以及所有兼容OpenAI协议的模型服务当然也包括本地部署的Ollama、Xinference等。一套界面统一管理切换模型不用改代码。RAG能力文档上传、自动切片、向量化、检索召回还支持Rerank二次排序这块是知识库问答的核心。工作流编排支持类Coze的拖拽式工作流把LLM、代码执行、条件判断、HTTP请求等节点串起来做自动化任务。Agent能力给模型配置工具比如网页搜索、内部API、数据库查询让它自动决定调用哪个工具完成复杂任务。应用发布与管理内部使用可以发布成WebApp外部接入可以走API还自带用户管理和访问凭证控制。这套组合拳下来Dify能替代你原本用LangChain FastAPI 向量数据库 前端页面这堆技术栈组合起来的全套后端逻辑。你省下来的时间可以全部投入到业务本身比如优化知识库内容、打磨提示词、调工作流逻辑这比每天跟Embedding维度、向量库连接池参数死磕有价值得多。2. 上手前的准备工作从选型到本地部署2.1 二选一用云端版本还是自己部署Dify官方提供了两个使用途径一个是注册并使用Dify Cloud云端服务另一个是社区版自托管部署。我没有贬低云端版的意思但作为开发者和技术团队我强烈建议至少从本地部署开始接触。原因有三点第一社区版功能完全够用核心能力与云端版基本一致而且没有API调用配额限制。第二本地部署意味着数据完全掌控在自己手里企业内部文档接入知识库没有隐私顾虑。第三部署过程本身就是一次环境预检你能直观理解Dify的架构依赖哪些基础设施后面出问题排错会快很多。如果只是纯粹想快速看一眼Dify长什么样那直接去官网注册云端版体验也可以。但如果你要认真用起来、做二次开发或者接入企业内部系统请跟我走一遍本地Docker部署。2.2 在Windows上本地部署Dify的完整步骤先说环境前提Dify本质是一组Docker容器编排所以你需要本机装有Docker Desktop并且把资源配额调高。Dify全家桶包含API服务、Worker、Web前端、PostgreSQL、Redis、Weaviate或Qdrant等多个容器内存建议至少8GB磁盘预留20GB以上比较稳妥。我以Windows系统为例实际步骤记录如下去Dify官方GitHub仓库的Releases页面下载最新版压缩包dify-main.zip这种格式。注意是docker目录所在的那个完整包不要只下载源码片段。将压缩包解压到本地比如D:\dify然后进入dify-main\docker目录。在docker目录下打开命令提示符可以先执行dir确认文件都在。首次启动前需要创建环境变量文件直接复制模板cp .env.example .env启动全部容器docker compose up -d这里补充一下新版本Dify已经使用docker compose插件旧版如果是docker-compose请更新。启动过程会拉取镜像时间取决于网络状况。等待所有容器状态变成healthy用下面命令查看docker compose ps浏览器访问http://localhost或http://localhost/apps首次打开会进入管理员账号初始化页面设置邮箱和密码后即可登录。整个过程看起来不难但实际部署时最大的坑基本都集中在镜像拉取失败和容器启动顺序上。下面专门讲一下镜像拉取的问题这几乎是每个本地部署Dify的人都会遇到的第一道坎。2.3 镜像拉取失败的处理思路我见过太多人在这一步卡死日志里反复出现failed to pull image、dial tcp: lookup ... no such host、EOF这类错误。这不一定是你操作有问题而是国内网络环境访问Docker Hub的常规障碍。解决方法有几个层面按顺序尝试给Docker Desktop配置镜像加速器。打开Docker Desktop进入Settings - Docker Engine在配置JSON中添加registry-mirrors填一个你所在地区延迟较低的加速地址。改完点击Apply Restart。这个方法对多数人有效。如果加速器效果不理想可以考虑使用代理环境。但如果你不方便用代理还有一个更实用的办法找一台能正常拉取镜像的机器用docker pull手动拉取后通过docker save导出镜像包再拷贝到目标机器docker load。这套离线镜像迁移流程在部分企业内网环境是标准操作。还有一种情况是你改了.env里的镜像版本但本地没有对应tag的缓存这时候可以先把旧的Dify容器彻底清理掉再重新执行docker compose up -d避免Tag混乱导致拉取长时间无响应。注意部署完成后如果修改了.env文件里的配置比如更换向量数据库、调整端口一定要执行docker compose down然后重新docker compose up -d而不是只重启部分容器否则配置不会全量生效。3. 接入大模型让Dify跑起来的临门一脚3.1 模型供应商的整体概念Dify部署完成之后登录进去第一眼会看到欢迎页但真正要开始用你得先接一个大模型。Dify把模型接入抽象成了“模型供应商”的概念。供应商可以是OpenAI这种云端服务商也可以是你本地跑的Ollama、LM Studio、Xinference等开源推理服务。在Dify的“设置 - 模型供应商”页面会看到一张已经支持的供应商列表。点击任意一个提供商填入对应的API Key和Base URL就能激活该服务。多人协作场景下管理员配置好模型后团队成员直接用就行不用每个人都去申请API Key。这里有个很容易被忽略的点Dify的模型分为几类第一大类型是“系统推理模型”也就是聊天对话、文本生成使用的底层大模型比如GPT-4o、Claude 3.5 Sonnet或者本地Llama系列。第二大类是“Embedding模型”用于知识库文档向量化。第三类是“Rerank模型”用于知识库检索后的精排。新手经常只配了推理模型然后发现知识库上传文档后问答效果很差一查日志才发现Embedding没配或者没配对。3.2 接入本地Ollama模型零成本跑通对话如果你暂时不想花钱申请云端API我推荐先用Ollama把本地模型跑起来再接进Dify。Ollama是一个极简的本地大模型管理工具一条命令就能下载并启动模型。我在没有GPU的笔记本上用Ollama跑过qwen2.5:7b速度虽然一般但验证流程完全够用。Ollama安装后默认监听在http://localhost:11434但要被Dify容器访问这里的地址有讲究。你在Dify的模型供应商里选Ollama填的Base URL不能是http://localhost:11434因为Dify容器内部访问不到你宿主机的localhost。在Windows和Mac上Docker Desktop提供了一条宿主机特殊域名host.docker.internal所以应该填http://host.docker.internal:11434在Linux宿主机上则要直接用宿主机局域网IP如果没有额外配置host网络模式的话。这个细节我见过不少人在社区里问“为什么本地模型连不上”十有八九都是Base URL填错了。填好模型名称后点击保存系统会做一次连通性检测。如果提示连接失败按下面顺序排查确认Ollama服务正在运行浏览器访问http://localhost:11434能出现Ollama is running。确认在Dify里填的Base URL是host.docker.internal而不是localhost。确认Ollama里已经拉取了你填写的那个模型名比如ollama pull qwen2.5:7b。在Dify容器内部临时执行wget http://host.docker.internal:11434测试连通性能通就说明网络层没问题。3.3 Embedding与Rerank模型知识库效果的隐形决定者很多人第一次用Dify做知识库问答传了文档进去却发现回答质量惨不忍睹不是答非所问就是漏掉关键信息。这里我先给一个经验总结如果只配了推理模型知识库问答的效果大概率不会好。原因在于知识库涉及两条链路入库时要把文档切片编码成向量这叫Embedding检索时要对召回的候选段落做相关性精排这叫Rerank。两者分别需要专门的模型。Embedding方面Dify内置支持多种模型。国内使用比较稳定的是BAAI/bge-m3系列它可以在Ollama里直接跑。你也可以用OpenAI的text-embedding-3-small效果不错但会产生费用。我的实践经验是中文场景如果不追求极致效果bge-m3已经够用如果做专业领域比如法律、医疗术语多建议测试多个Embedding模型的效果差异再定。Rerank方面Dify推荐配置一个Rerank模型比如Cohere的Rerank接口或者开源的BGE Reranker。配置Rerank后知识库检索流程会变成先用Embedding召回Top-20候选再用Rerank模型精排取Top-3。这一步对准确率提升非常明显尤其是在文档数量多、内容相似度高的场景。我现在做新项目Rerank几乎是必选项没有Rerank的RAG系统总觉得少了灵魂。提示在“设置 - 模型供应商”里不同的模型类型要分别配置。推理模型、Embedding模型、Rerank模型是三个独立配置项别混在一个入口里找。4. 快速上手从创建应用到发布第一个智能助手4.1 应用类型的选择聊天助手还是文本生成模型配好之后就可以创建第一个应用了。Dify创建应用时有几个类型选项最常见的是“聊天助手”和“文本生成”另外还有“Agent”和“工作流”。聊天助手适合多轮对话场景自带会话记忆能力用户问一句答一句上下文自动关联。用于客服、知识库问答等。文本生成适合一次输入、一次输出的场景比如写摘要、生成文案、翻译。它不做多轮会话管理逻辑更简单。Agent聊天助手的增强版可以配置工具模型在对话中会自己判断是否调用工具以及调用哪个工具。适合查数据、查天气、调API等动作型应用。工作流多节点编排模式适合有明确流程的任务比如先检索知识库、再让LLM总结、再做敏感词过滤、再输出。对第一个应用来说我建议从“聊天助手”起步。它最简单、最容易看到即时效果而且聊天助手里也能挂知识库足以体验Dify最核心的能力。命名可以随意比如“第一个智能助手”模型选择你刚接入的那个。4.2 提示词编排界面不需要会编程的“系统提示词”创建完应用会进入Dify最有名的“提示词编排”界面。左边是提示词输入区右上角是模型参数配置右下角可以直接跟应用对话调试整个布局非常适合新手。提示词编排的本质是给模型设定角色和规则。你可以把系统提示词理解为“给一个刚入职的新人写工作说明书”它决定了模型以什么身份、什么语气、什么边界来回答。一个最简单的系统提示词可以是这样你是一个专业的IT技术支持助手。请用简洁、准确的中文回答用户的问题。如果用户的问题与IT无关请礼貌说明你无法回答并建议用户咨询相关专业人员。界面里还可以做变量引用比如加一个{{input}}占位符运行时Dify会把用户输入自动替换进去。右上角的“模型参数”可以调整温度temperature、Top P、最大Token等。新手阶段建议温度保持在0.5以下尤其是做知识库问答时温度太高模型容易“编造”内容。调试框就在右下角直接输入“你好”测试如果模型有响应恭喜你的第一个Dify应用已经活了。这里我会额外建议先不要急着调复杂功能把系统提示词反复打磨几次试试不同表达对回答风格的影响这比一开始就冲进去做工作流更有手感。4.3 发布与调用WebApp和API两种方式调试满意之后点击界面上方的“发布”按钮应用才正式对外生效。发布后Dify提供两种使用方式第一发布为WebApp。在“概览”页会生成一个访问链接别人打开就能用不需要登录后台。这个适合快速做Demo给业务方看效果。第二通过API调用。在“API访问”菜单里Dify会生成应用的API密钥类似app-xxx的字符串。同时Dify提供了完整的RESTful API接口后端服务可以用HTTP方式调用这个应用。这样Dify应用就变成了你业务系统里一个AI能力微服务前端页面、企业微信机器人、钉钉机器人都可以通过API对接。我第一次生产接入时就是先把Dify应用调好然后从自己的后端发HTTP请求到Dify的API传用户问题、收AI回答整体非常顺。这里提醒一下API密钥不要暴露在前端代码里一定要由后端代理调用否则别人拿到密钥就能白嫖你的Token额度。密钥权限管理在“访问控制”里还可以配置允许的IP列表建议开起来。5. Dify核心功能地图先看清你面前有哪些武器5.1 工作流把AI从一个“对话框”变成一条“流水线”很多人第一次接触Dify把它当成一个高级ChatGPT套壳这就太低估它了。Dify真正的威力在于工作流英文叫Workflow。它让你像画流程图一样把LLM节点、知识库检索节点、代码执行节点、条件判断节点、HTTP请求节点串联起来实现一个复杂的自动化任务。举个例子接一个“根据语意生成SQL”的内部工具。传统做法是你写一套NL2SQL的代码定义意图识别、表结构映射、SQL校验、结果解释这些模块。在Dify工作流里可以这样搭开始节点拿到用户问题知识库节点召回相关表结构和历史SQL样例LLM节点基于这些上下文生成SQL代码节点做语法校验最后HTTP请求节点执行查询再把结果通过LLM节点转成自然语言回复。整个过程可视化每一步的输入输出都看得到排错比看日志直观得多。第一篇我先不展开工作流的细节但你要建立这个意识Dify不止是做聊天它是一个应用编排平台。后面的系列文章会专门用整篇篇幅讲工作流节点的选择、参数传递、循环和分支逻辑怎么写。5.2 知识库Dify里最实用的企业级能力知识库是Dify日常使用频率最高的功能没有之一。你可以把PDF、Word、Markdown、TXT、甚至网页内容上传进去Dify会做文档解析、分段、向量化之后在聊天助手里开启“知识库”功能问答时自动检索相关内容作为上下文给模型参考。假设你有一套内部产品手册几百页PDF员工问“XX功能的限额是多少”传统方式是翻文档用了Dify知识库后几秒钟就能得到准确答案。但前提是你得知道文档切片粒度直接影响检索效果。切太大检索召回准确率降低切太小上下文碎片化模型缺少完整逻辑。Dify默认提供自动分段模式但针对多级标题结构明显的文档我建议在分段设置里开启“自定义分段标识符”用Markdown标题作为分隔。这个方法能让段落结构更符合原文档逻辑检索效果明显好于无脑按字数切。5.3 Agent与多智能体更复杂的AI应用形态我注意到最近社区里关于Dify多智能体的讨论越来越多比如和AgentScope、Java后端结合做多智能体协作。Dify的Agent能力目前主要是“单Agent 多工具”模式模型根据任务目标自主决定调用哪些工具、按什么顺序调用。Dify本身就支持在Agent里接入多个自定义工具和插件可以实现“帮我查天气再根据天气推荐穿搭”这种需要两步动作的任务。如果你要做多个AI角色协同决策的“多智能体系统”Dify的Agent可以直接作为一个节点嵌入到工作流中外部再通过API统一编排。坦白说多智能体本身还比较前沿生产环境落地要关注的不只是技术还有业务规则怎么拆、错误怎么兜底。新手阶段先把单Agent的工具调用玩明白后续我会专门写一篇如何基于Dify构建多智能体协作应用。6. 高频问题与避坑记录我在实际部署和日常使用中踩过的坑6.1 端口占用与容器启动失败Dify默认使用80端口提供Web服务如果本机80端口被占用容器启动会报端口冲突。解决办法是在.env文件里改EXPOSE_NGINX_PORT8080然后访问http://localhost:8080。改完保存后执行docker compose down再docker compose up -d。另外Dify依赖的PostgreSQL和Redis如果端口被本机已有的服务占用也会启动失败。一般改宿主机的映射端口即可方法同上在.env里找到对应配置项修改。启动后观察日志docker compose logs -f api看到类似Starting server at port 5001的日志基本可以确认后端已经起来了。6.2 不同版本的差异1.17.1和1.15.0到底差在哪很多人在社区问Dify 1.17.1和1.15.0的区别。我在升级到1.17.1后感受明显的几个变化一是工作流节点类型和调试体验有优化变量赋值器的操作更顺手二是构建Agent时的工具调优界面更清晰三是修复了一些知识库检索的边界问题。不过1.15.0作为稳定版本在旧项目里跑得也很好。我的建议是新项目直接用最新稳定版老项目如果工作正常没必要频繁升级。升级Dify的方法是先在GitHub Releases里下载新版压缩包备份.env和docker目录里的数据卷然后替换代码目录再执行docker compose down和docker compose up -d。数据卷特别是PostgreSQL和向量数据库的持久化目录一定不要删除否则所有知识库和应用配置都会消失。有条件的话升级前先对整个 docker 数据目录做一次快照或者压缩备份。6.3 几个我实际遇到过的操作细节先说一个最不起眼但影响很大的上传文档的大小限制。Dify默认上传文件大小限制有上限如果你要传几百MB的PDF可能会直接失败。这个限制可以在.env里调整UPLOAD_FILE_SIZE_LIMIT单位是根据文档说明来的通常用MB。我在做制造业设备手册入库时就遇到过这个问题改成较大值后重启服务就正常了。再说变量赋值器。Dify工作流里有一个节点叫“变量赋值器”作用是把前面节点的输出重新组织成后面节点需要的变量格式。我印象最深的场景是LLM节点输出的是一段带Markdown格式的文本但下游HTTP请求节点要求JSON格式这时候就靠变量赋值器做转换和取值。新手经常忘记看节点输出的数据类型直接连线导致下游解析报错。记住一个原则连线之前先点开上游节点的输出预览确认字段结构再决定要不要加一个变量赋值器或代码节点做转换。最后是第三方登录授权问题。Dify社区版支持通过飞书等平台创建应用并用于内部用户登录但首次使用飞书云文档的授权凭证时很多人找不到app_id和app_secret在哪。这里强调一点飞书的凭证不是填在Dify的“设置”里而是在创建飞书自建应用后从飞书开放平台的“凭证与基础信息”页面复制然后再到Dify对应渠道配置里填入。如果授权失败优先检查回调地址是否已经配置到飞书应用的“重定向URL”里。我自己在写这篇系列文章时把之前折腾Dify的过程重新复盘了一遍。从最开始拉镜像失败、模型连不上到后来用工作流做自动化报告、给业务方搭知识库问答机器人Dify确实把我从大量重复的模型对接代码里解放了出来。第一篇的内容先到这后面的文章我会逐步深入工作流编排、知识库进阶调优、Agent工具开发这些方向。如果你按这篇文章部署成功了可以动手试着自己搭一个简单问答应用遇到问题随时回来对照第6节的排查思路。