Dify 是我最近半年用得最多的一个开源项目几乎把之前零零散散写脚本、调 API、拼提示词的工作全统一到了一个平台里。如果你也在做 AI 应用或者正在纠结怎么把大模型真正落地到业务里这篇内容值得你看完。我会从最基础的概念讲起用一套完整的本地部署和首个应用搭建流程带你快速跑通 Dify还会把那些文档里没写清楚的坑一并交代清楚。1. Dify 到底是什么先搞懂它解决什么问题1.1 我对 Dify 的第一印象第一次接触 Dify是在一个技术社群里看到有人讨论可视化编排 LLM 应用。当时我手头正好有个需求给公司内部的客服系统做一个知识库问答机器人。之前我的做法是直接调 OpenAI API自己写检索逻辑再拼 prompt前前后后折腾了两周。后来有人推荐我试试 Dify说它把模型接入、提示词编排、知识库、工作流、Agent、监控全都打包好了我当时半信半疑结果用下来发现确实省掉了很多重复劳动。Dify 的中文名通常叫大模型应用开发平台它的核心定位是让你不需要从零写后端代码就能搭建一个功能完整的 AI 应用。你可以在它的界面上完成几个关键动作选择合适的模型、设计提示词、上传文档做知识库、拖拽节点构建工作流、发布应用给用户使用。过去这些能力分散在各个工具里Dify 把链路串起来了。1.2 它能帮你省下哪些事可以这么说如果没有 Dify一个典型的 AI 应用从想法到上线需要解决模型 API 管理、上下文处理、用户会话隔离、内容审核、日志追踪、成本控制等一堆问题。而在 Dify 里这些问题大部分都内置了。举几个具体场景客服知识库把公司产品文档、FAQ 导入知识库模型根据命中内容回答不再凭空编造。内容生成工具设定好提示词和输入表单团队成员填几个字段就能生成文案草稿。数据分析助手通过工作流把自然语言转换成 SQL 查询对接业务数据库。个人助理接入本地大模型做成完全离线的私人助手。我在前面提到的那个客服机器人最终就用 Dify 完成了。从我搭建到上线一共花了不到两天后续改 prompt、加新文档也全在网页端完成不需要再碰代码。这也是为什么我特别想把 Dify 的基础使用经验分享出来——它真的能改变一个人的开发方式。2. 快速上手本地部署 Dify 并跑通第一个应用2.1 部署前需要准备什么先把最基础的条件理清楚。Dify 服务端本质是一组容器最常见的部署方式是 Docker Compose所以你本地需要具备以下环境。硬件要求官方建议的最低配置是 2 核 4G 内存磁盘空间建议预留 30G 以上。如果只是学习试用4G 内存的旧笔记本也够跑但启动多个服务时会比较吃力。我自己的开发机是 8G 内存的 MacBook Air跑 Dify 加本地模型基本流畅。需要特别说明的是如果后续要跑本地大模型比如通过 Ollama 接入建议内存至少 16G因为模型推理本身对内存占用很大。软件要求Docker 和 Docker Compose。Windows 用户建议直接装 Docker DesktopMac 用户也一样。注意 Docker Desktop 需要开启 WSL2 后端Windows 下否则容器运行效率会差不少。浏览器推荐用 Chrome 或 Edge 最新版本Dify 的前端界面做得比较现代太老的浏览器有兼容问题。模型 API Key。你可以准备 OpenAI 的 Key也可以用国内其他兼容 OpenAI 接口的服务或者干脆用本地模型。我建议新手先用云端模型 API因为配置最简单后面再考虑本地化。这一套准备工作本质上就是要有一个容器运行环境因为 Dify 把前前后后几十个服务都用容器隔离起来了安装和卸载都很干净不会污染你的系统环境。2.2 下载解压与初始化配置Dify 的部署流程在 GitHub 仓库里有详细说明我这里把实操步骤重新走一遍把容易踩坑的地方标注出来。第一步去 Dify 的 GitHub Releases 页面下载对应版本的源码包。注意你下载的是一个 zip 压缩包解压后里面会有一个docker文件夹所有部署相关文件都在这。不要下错成文档里那个自动构建的 master 分支源码——虽然也能用但版本管理比较乱新手直接拿 release 包定位问题更容易。解压之后在文件管理器中进入docker文件夹地址栏右键打开终端。Windows 下可以按住 Shift 点击右键选择在此处打开 PowerShell 窗口或打开命令窗口Mac 用户在访达中进入该目录后可以开启终端输入cd拖入文件夹路径。接下来需要复制环境变量配置文件命令如下cp .env.example .env如果是在 Windows PowerShell 里cp命令同样可用它会被解析为Copy-Item。有些用户在 cmd 里执行这条命令时报系统找不到指定的路径多半是因为没有进入docker文件夹就执行了请务必先确认当前目录正确。然后使用文本编辑器打开.env文件。这里你可以看到一堆配置项新手不需要全部理解只需要关注几个关键点SECRET_KEY系统加密密钥初次配置时可以留空让系统自动生成但生产环境建议自定义一个随机字符串。POSTGRES_PASSWORD和REDIS_PASSWORD数据库和缓存的密码默认是 difyai123456如果暴露在公网环境务必改掉。端口映射默认EXPOSE_NGINX_PORT80意思是 Dify 的 Web 界面跑在 80 端口访问http://localhost即可。如果 80 端口被占用改成 8080 之类的端口即可。保存之后启动服务。在docker目录下执行docker compose up -d首次执行会自动拉取镜像这个过程取决于网络情况可能需要几分钟到十几分钟。中间如果拉取失败参考后面常见问题一节里的换源方案。2.3 初始化管理员账号与第一个应用等所有容器状态变成Up之后浏览器访问http://localhost或你改过的端口第一次打开会进入管理员初始化页面。设置管理员邮箱和密码这一步完成后就进入 Dify 主界面了。接下来的核心流程是创建第一个应用。在首页点击创建空白应用选择应用类型。Dify 支持多种应用类型比如聊天助手、文本生成、Agent、工作流等。作为入门我建议选择聊天助手它会给你一个最直观的对话界面。创建完应用你会进入提示词编排页面。页面的布局分三大块左侧是模型选择与参数配置中间是提示词System Prompt编辑区右侧是预览对话窗口。先把模型选好点击模型名称会弹窗让你选择供应商并填入 API Key。以 OpenAI 为例填入sk-开头的密钥模型选gpt-4o-mini或gpt-4o保存在左侧面板里。然后在提示词编辑区录入指令。比如这是一个翻译助手我写的提示词是你是一位专业的翻译助手。用户会给你一段文字请翻译成简体中文。如果原文本来就是中文请翻译成英文。注意保持语气和风格的一致性。右侧预览区可以直接测试对话。输入一句英文比如 The quick brown fox jumps over the lazy dog模型应该会给出中文翻译。如果一切正常恭喜你第一个 Dify 应用已经跑通了。最后点击页面右上角的发布应用会生成一个独立的访问链接你也可以在访问 API页面看到 API 密钥和调用示例。到这里你已经走完了 Dify 从安装到上线的全流程。3. 核心功能拆解提示词、知识库、工作流与 Agent3.1 提示词编排控制 AI 行为的关键提示词编排Prompt Engineering是 Dify 里最高频的功能也是最容易看出水平差异的地方。初学者往往只写一句话就让模型干活结果输出质量不稳定。其实一个合格的系统提示词应该包含角色设定、任务目标、约束条件、输入输出格式四部分。我拿实际项目举例。假设要做一个小红书文案生成器如果你的提示词只写帮我写一篇小红书笔记模型生成的风格可能千奇百怪。我在 Dify 里是这样设计的你是资深的新媒体运营专家精通小红书平台的文案风格。你的任务是帮助用户生成适合发布的小红书笔记。 要求 1. 标题需要包含 2-3 个 emoji此处仅举例说明实际输出策略要根据目标平台规范来定。 2. 正文控制在 300 字以内段落间用空行分隔语言活泼亲切。 3. 结尾加上 5-8 个话题标签。 4. 如果用户提供了产品信息需要提炼卖点如果没有先引导用户补充产品名称、适用人群和价格区间。 输入格式 用户会以任意形式描述产品你要先提取关键信息再生成笔记。大家可以看到同样的模型在不同提示词下的输出质量差别巨大。Dify 的好处在于你不需要改代码直接在界面上迭代提示词右侧预览区立刻能看到效果。我习惯的做法是先写一个粗略版本然后用不同的测试输入跑十几轮逐步加约束直到输出稳定。还有一个建议是把用户可能输入的示例放在提示词里称为 few-shot。比如上面那个例子如果你给模型展示一篇标准答案格式的小红书笔记它模仿出来的效果会比纯文字描述好很多。Dify 的提示词编辑区支持多轮上下文你可以把示例对话放进对话前示例模块这在聊天助手里尤其好用。3.2 知识库让 AI 学会用你的文档回答知识库是我认为 Dify 最核心的能力之一也是很多企业选择它的原因。简单理解知识库就是一种检索增强生成RAG的实现先把文档拆分成小块通过 Embedding 模型转成向量用户提问时系统先检索相关的文本块再连同问题一起发给大模型让模型基于检索结果作答。在 Dify 里建知识库的步骤大致是这样在知识库页面点击创建知识库输入名称。上传文档支持 PDF、Word、Markdown、TXT 等格式也可以直接连接 Notion 或网页数据源。选择分段模式和索引方式。Dify 会自动把文档拆成多段默认按长度切分段长约 500 个字符重叠 50 个字符。如果文档结构清晰也可以选择自定义分段或按 Markdown 标题切分。选择 Embedding 模型。这一步通常需要调用模型的 Embedding 接口比如text-embedding-3-small。如果使用本地部署可以用 Ollama 提供 embed 模型下文会详述。完成创建后对文档进行检索测试查看命中效果。这里有个新手常忽略的点知识库的效果不是由大模型决定的而是由检索质量决定的。如果你的文档切分不合理或者没有配置 Rerank 模型检索结果经常不准确大模型给出的答案自然也不对。Dify 支持多种检索模式和 Rerank 重排功能我强烈建议在检索设置里开启 Rerank哪怕是一个小模型也能显著提升命中率。实际业务中我遇到过用户抱怨知识库回答像没加载文档一样老是瞎编。排查下来发现两个原因一是在聊天助手里没有在提示词中引用知识库的上下文变量二是知识库挂载后没有把 Rerank 打开导致识别的文本块不对。解决方式是在提示词中加入【上下文】{context}这样的占位符并把知识库关联到应用上。3.3 工作流把多步操作串成自动化流水线如果说提示词和知识库让 AI 更像一个人那工作流就是让 AI 变成一套生产线。Dify 的工作流功能采用可视化节点编排你可以把 LLM 调用、代码执行、HTTP 请求、条件分支、变量赋值等节点连接起来构建复杂的自动化流程。举个最常见的案例自动生成周报。传统方法是人力收集数据再写文字而 Dify 工作流可以把流程设计为开始节点接收用户输入的本周工作要点用LLM 节点1 做内容分析提炼关键成果用代码节点处理格式补充统计信息用条件分支判断是否存在未完成事项最后用一个 LLM 节点生成完整周报并通过 HTTP 请求发送到钉钉或企业微信这个流程怎么落地Dify 的工作流画布中你可以从一个开始节点拖出LLM节点选择模型和提示词再拖出条件分支节点设定规则。每个节点之间通过变量传递数据。我刚开始用的时候觉得不如写代码直接但熟练后反而更喜欢这种可视化方式——调整流程不用改代码非技术人员也能参与设计。工作流的另一大用途是知识库预处理。你可以把一篇长文档丢进工作流通过多个节点实现内容清洗、信息提取、结构化输出再把结果写入数据库或另一个知识库实现类似文档流水线的效果。这也是最近不少人在讨论Dify 知识库流水线的原因。3.4 Agent 与多智能体从问答走向自主行动Agent智能体是 Dify 进阶功能它让 AI 不只是回答还能动手。在 Dify 里创建 Agent 应用后你可以给模型配置工具比如调用网络搜索、执行 SQL 查询、访问内部 API 等。模型会在对话中根据用户意图自主决定调用哪个工具、如何组织最终回答。我在一个实际项目里用 Dify 做了一个数据查询助手对接了公司的 MySQL 数据库。用户在应用里提问上个月华东区的销售额是多少Agent 会自动生成 SQL、查询数据库、再把结果整理成自然语言回复。这个场景放到以前要么找工程师写查询接口要么教业务人员看报表而现在直接对话就能解决。Dify 的 Agent 节点还支持创建多个工具形成多智能体的协作方式尽管复杂应用对工程能力要求更高但 Dify 已经把门槛降低了很多。如果你对多智能体感兴趣可以把 Agent 应用和个人知识库、HTTP 请求工具组合起来构建一个能查资料、算数据、写总结的全能助手。这里特别想提一句Dify 的定位是应用开发平台它不等于模型本身所以它支持对接各种模型——包括通过 Ollama 或 LM Studio 部署的本地模型这为隐私敏感场景提供了很好的方案。4. 实际部署与使用中常见的问题清单4.1 镜像拉取失败怎么办Dify 部署时最常见的报错就是拉取镜像超时或拉取失败。原因很简单默认镜像源在国外网络状况不好时很容易失败。解决方案是把镜像源切换到国内镜像。在 Docker Desktop 的设置里找到 Docker Engine 配置项把registry-mirrors加上{ registry-mirrors: [https://docker.m.daocloud.io] }保存后 Docker 会自动重启。接着再执行docker compose up -d拉取就会快很多。如果个别镜像还是失败可以单独docker pull后重试。4.2 启动后页面打不开如果你执行完docker compose up -d后访问http://localhost出现无法访问可以用docker compose ps检查容器状态。常见原因是端口冲突特别是 80 端口被其他服务占用。此时需要修改.env中的EXPOSE_NGINX_PORT把 Web 服务映射到其他端口比如8080然后重新执行docker compose up -d。还有一种情况是容器状态显示 Restarting。碰到这个先用docker compose logs查看日志最常见的原因是.env文件里某些配置有问题比如密码包含特殊字符导致解析失败。建议把数据库密码改成纯字母数字组合避免这类问题。4.3 知识库检索效果差这是使用知识库时反馈最多的问题。检索效果差通常不是模型的问题而是没有做好预处理和检索配置。我的排查顺序是先看文档切分是否合理。如果一段内容过长信息就被稀释如果切得过碎语义可能断裂。Dify 默认的切分长度一般够用但遇到表格或代码块的文档建议手动调整分段方式。确认是否启用了 Rerank。没有重排模型时TopK 检索可能命中完全无关的内容。安装 Rerank 模型如 BAAI/bge-reranker-v2-m3并在知识库关联的测试页面里配置稳定提升准确率。检查 Embedding 模型是不是选的同一个。知识库创建时用的 Embedding 模型和查询时如果不同会导致向量空间不一致检索效果自然差。4.4 其他几个高频问题问题一Windows 下提示cp命令没有执行权限或找不到路径。解决办法先确保在docker目录下打开终端。可以在文件管理器中复制该目录路径然后在终端里输入cd C:\你的路径\docker再执行命令。问题二cp .env.example .env报系统找不到指定的路径。检查当前目录里是否存在.env.example文件。Windows 资源管理器默认不显示以.开头的文件但在终端里ls -a能看到。确保文件存在且目录正确。问题三本地模型接入后响应很慢。比如通过 Ollama 接入本地大模型在 8G 内存的机器上跑 7B 模型基本是能用但慢。可以降低模型量化等级比如从 Q8 换到 Q4也可以关闭其他容器释放资源。如果追求速度优先考虑 API 调用或者换更小参数的模型。问题四如何把网页左下角的 Powered by Dify 去掉。这在社区版里是允许的在应用设置或前端配置文件里找到相应的水印开关关闭即可。不同版本位置略有差异大致在应用设置—外观—显示系统标识这个路径下。如果找不到可以搜索项目前端代码里Powered by关键字。问题五Dify 如何读取本地文件。网页版 Dify 通常无法直接访问你电脑上的本地文件它是运行在浏览器里的应用。如果想让它读取本地内容要么通过知识库上传要么用 HTTP 请求工具让后端读取要么把本地文件挂载到 Dify 服务端所在机器的某个路径并通过自定义工具去访问。这块跟部署方式有关本地 Docker 部署时可以通过卷挂载的方式让容器访问宿主机文件。5. 进阶思路从入门到精通的下一步规划5.1 接入本地大模型实现完全离线很多人在意数据隐私Dify 支持通过 Ollama 或 LM Studio 接入本地模型。以 Ollama 为例你先在宿主机安装 Ollama拉取一个模型比如qwen2.5:7b或llama3.1:8b然后在 Dify 的模型供应商页面选择 Ollama 类型填写 Ollama 的 API 地址通常是http://host.docker.internal:11434就可以在应用中使用本地模型了。需要注意两点一是 Docker 容器访问宿主机服务时Windows/Mac 环境要用host.docker.internal而不是localhost二是本地模型的推理效果通常不如大厂 API所以建议在效果要求不高的内部场景使用比如个人助理、内网问答。5.2 用 Dify 构建个人智能助手回到热搜里讨论的一个问题Dify 和 Codex 结合可以做一套个人的智能助手吗我的答案是完全可以。你可以把 Dify 当作调度与装配层把各类 API 工具接到 Agent 里形成一个能对话、能查资料、能写代码、能调外部服务的个人助理。只要有想法Dify 的拼接能力非常强不同的组件可以随意组合这也是我持续深入使用它的原因。实际操作中我用 Dify 做过一个小而全的个人知识管家知识库里放了我的笔记和收藏的文章工作流里接入了 RSS 抓取Agent 里挂了搜索 API。我每天打开这个应用输入今天有什么值得关注的内容它会自动抓取、检索并汇总。这种个人化的小工具用传统开发方式得写不少服务而 Dify 半天就能做出一个能用的版本。5.3 关注版本更新从 1.10 到 1.17Dify 的版本迭代相当快。印象比较深的是 1.10 左右的社区版引入了多租户支持1.15 和 1.17 版本里工作流和多模型管理能力又有了不少改进。每隔一两个月就有一个新版本这说明项目本身非常活跃但同时也提醒你要注意升级节奏。升级 Dify 的官方方式不算复杂但千万不要直接在旧目录上覆盖。建议先备份数据库Dify 使用 Postgres记录当前版本再拉新版本代码执行迁移。社区版升级时有个细节docker compose down后docker compose pull再docker compose up -d一定要把.env文件保留好。如果自定义过环境配置新版可能会有新增的环境变量至少看一下env.example的变动避免升级后功能异常。我对升级的建议是非生产环境可以大胆追新体验新功能生产环境务必先在测试环境跑一遍关键流程确认无问题后再上。另外如果对英文界面不熟悉部分版本中文翻译可能滞后这一点在新功能上线初期多少会遇到耐心等几个版本就好。5.4 探索多智能体与自动化集成如果你已经熟悉了基础功能下一步可以尝试更复杂的多智能体协作。Dify 本身提供了一些 Agent 节点的能力你可以把多个 Agent 分别设定不同的角色比如一个负责数据查询、一个负责文档撰写、一个负责质量检查然后通过工作流把它们串联起来。这种设计在中型业务场景里非常实用。我见过一个比较巧妙的用法一个 Agent 负责用 Dify 的知识库检索相关论文另一个 Agent 负责总结并生成 PPT 大纲第三个 Agent 负责检查内容的逻辑漏洞。三个 Agent 通过工作流协作最终输出一份质量不错的研究报告。虽然不能完全替代人的判断但能大幅度减少前期信息收集的时间。另外Dify 的 API 接口也可以和外部系统深度集成。比如通过 API 把应用嵌入到你自己的网站、企业微信、飞书、钉钉里。有不少人在问如何对接飞书其实 Dify 的官方文档提供了飞书接入指南按其步骤创建一个飞书机器人再配置 Dify 的 API 地址和密钥就能在飞书群里直接对话你的 AI 应用。方式不难难的在于你对自己的业务语义是否拆解得足够清晰。在我个人的实操过程中最大的感受是Dify 真正解决了AI 应用从原型到落地之间那段漫长的工程化路程。你不需要把每个环节都造一遍轮子只需要专注在业务逻辑和提示词的设计上。入门篇的内容到这里已经覆盖了安装、第一个应用、核心功能、常见问题与进阶方向。接下来的文章里我会专门拆解工作流的高级用法、知识库的调优策略以及如何把本地模型接入 Dify 做到真正离线可用有兴趣的可以持续关注。最后分享一个小技巧在 Dify 里做任何配置变更尤其是提示词和工作流的修改都建议先保存一个版本再改动。Dify 支持版本管理很多新手不知道这个功能结果辛辛苦苦调好的提示词被一次实验改动覆盖再想恢复就麻烦了。先归档、再实验这个习惯能帮你省下很多不必要的返工时间。