Dify 是一个开源的大模型应用开发与智能体搭建平台这篇文章会从安装部署讲起一直做到第一个能用的 AI 智能体。整个流程我尽量按新手能直接照着操作的方式写不绕弯子。先说结论只要机器配置不是太老、Docker 环境正常安装这一环并不难真正的分水岭在模型接入、工具配置和工作流调试。很多人卡住不是命令不会敲而是底层概念没理清。下面围绕 Dify 安装部署、模型接通、智能体搭建、知识库接入、问题排查和上线发布完整拆一遍。1. 先弄清楚 Dify 是什么再动手装1.1 它到底解决什么问题先理解 Dify 的定位。它不是一个大模型而是一个用来编排大模型能力的开源平台。你可以把大模型当作“员工”Dify 是给这个员工发任务、配工具、管流程、看效果的管理系统。Dify 解决的核心问题有三个。第一个是应用开发成本。以前想做一个基于大模型的服务要自己写前后端、设计接口、处理会话状态、管理日志和用户门槛不低。Dify 把这一层做成可视化界面你可以通过拖拽和配置快速搭出一个对话应用。第二个是智能体搭建门槛。智能体不是简单地把模型接出来聊几句它还需要角色设定、工具调用、知识库查询、多轮对话记忆、结果整理。这些东西如果从零开发需要掌握 Prompt 工程、函数调用、向量检索等一堆概念。Dify 把常用的智能体骨架内置好了你只需要填角色和目标然后绑定工具和知识库。第三个是运维和迭代问题。应用上线后怎么观察用户问了什么、模型答得怎么样、调用花了多少 Token、哪一步导致响应变慢都需要日志和监控。Dify 自带访问日志、标注和运行记录方便调试和优化。另外Dify 还支持工作流。工作流适合流程相对固定的业务比如“先判断用户意图再按不同分支调用不同模型步骤最后生成结构化结果”。智能体则适合灵活决策让模型自己决定调什么工具。两者可以分开用也可以组合。1.2 适合什么人不适合什么人从实际经验看Dify 适合这几类人想快速验证大模型应用想法的个人开发者。需要给企业做内部知识问答助手的产品或研发。暂时没有前端团队但想先做出一个可演示 Demo 的团队。做数据分析、客服、营销内容生成希望用智能体减少重复劳动的人。刚接触大模型想理解“模型、智能体、知识库、工作流”之间关系的新手。如果你本身就是做底层模型训练的那 Dify 不太适合你。它更偏应用层不负责训练模型也不负责微调权重。如果你需要的只是一个纯前端聊天窗口Dify 对你说不定有点重直接调模型 API 更快。还有一个需要提前说清楚的地方Dify 安装后它自己并不具备思考能力。你必须先给它接通一个大模型比如 OpenAI 兼容接口、DeepSeek、通义千问、Kimi、智谱或者本地部署的 Ollama。把模型接上之后Dify 的智能体、知识库、工作流才有意义。1.3 安装前必须理解的五个基础词模型供应商提供大模型接口的服务商。Dify 负责调用它离了它智能体就没有“大脑”。应用你最终给用户使用的一个入口可以是对话机器人也可以是工作流服务。智能体一种应用类型。它会根据用户目标自己决定调用哪些工具、查哪些知识库、怎样组织回答。知识库把文档切碎、向量化后存储起来方便智能体回答时按需检索减少模型瞎编。工作流提前设计好的节点流程像流程图一样固定执行适合确定性较强的业务。这五个词在装完之后马上会用到。先有个印象就行后面每一步都会碰到。2. DeployDocker 环境准备和 Dify 安装2.1 硬件和系统要求先说硬件。Dify 由一堆容器组成包括 API 服务、Worker、数据库 PostgreSQL、缓存 Redis、向量数据库、Nginx 入口等。容器数量多所以对内存有一定要求。我的建议是内存 8GB 起步能到 16GB 更好。CPU 4 核以上普通家用级 CPU 也能跑。磁盘至少预留 50GB因为镜像、数据库、日志和知识库向量数据都会增长。如果你用的是 Windows建议装 Docker Desktop并启用 WSL2 后端。如果你的机器只有 4GB 内存也不是完全不能跑。第一次安装有可能成功但启动会比较慢浏览器打开页面时可能卡顿。这时候不要同时开一堆容器也不要急着创建大量知识库分段。先用最小配置跑通再考虑扩展。系统方面Windows、macOS、Linux 都支持 Docker 安装。不过实际部署到服务器做生产用时我更推荐 Linux。因为资源占用低Docker 重启策略更好控制不容易出现桌面环境抢占内存的情况。2.2 安装 Docker 和 Docker Compose安装 Dify 之前首先要有一个能正常运行的 Docker 环境。Windows 用户安装 Docker Desktop安装时选择 WSL2 后端。Docker Desktop 自带 Docker Compose不需要单独装。Linux 用户建议安装 Docker Engine 和 Docker Compose 插件。不要漏了 ComposeDify 启动靠的是docker compose命令而不是单独docker run。装完 Docker 后先在终端验证一下docker --version docker compose version如果两个命令都正常输出版本信息说明 Docker 环境基本可用。这里注意一个常见问题Docker 启动后Windows 上可能提示 WSL 内核版本太旧Linux 上可能提示 dockerd 服务没起来。先把这个解决掉再继续下一步。否则 Dify 后面报什么错都容易被误判成安装问题。2.3 获取 Dify 源码并启动Dify 的安装方式主要是通过 Docker 启动官方提供的 compose 文件。通用流程是git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env docker compose up -d第一次执行docker compose up -d时需要拉取多个镜像。这个阶段耗时和网络关系很大可能几分钟也可能十几分钟。如果卡住不要反复按 CtrlC先确认 Docker 网络是否正常是否配置了镜像加速器。如果你在国内服务器或本地网络拉镜像很慢建议先配置 Docker 镜像加速器。常见做法是在 Docker Desktop 的配置里或在/etc/docker/daemon.json中填国内可用的镜像源地址。这个属于基础运维操作网上资料很多。配置完记得重启 Docker 再拉一次。镜像拉取完成后Dify 会自动启动这些服务组件nginx、api、worker、postgres、redis、weaviate 或 qdrant向量数据库。启动过程不是瞬间完成数据库初始化需要一点时间。2.4 验证安装是否成功启动完成后先看容器状态docker compose ps留意每个服务的状态是否都是running。如果看到restarting或exited说明某个服务有问题。这时候最该做的是看日志docker compose logs -f api不要只看容器是不是启动了还要看页面的初始化流程。浏览器输入http://localhost正常会进入 Dify 的初始化页面让你设置管理员邮箱和密码。这一步设置的是平台管理员不是智能体。真正创建智能体是在登录之后的控制台里。如果没有出现初始化页面优先排查两件事第一docker compose ps是否全部 running第二端口是否被占用。如果你本机 80 端口已经有别的服务需要在.env里修改EXPOSE_NGINX_PORT改成比如 8080再重新启动。2.5 安装阶段的几个坑第一不要直接修改 Dify 的.env.example应该复制一份成.env再修改。第二不要忽略 Docker 资源限制。Docker Desktop 默认分配的内存可能只有 2GB 到 4GB不够用的话去 Docker Desktop 设置里把内存调大建议调到 6GB 到 8GB。第三重新安装或升级前先备份数据卷。Dify 的数据主要存在 docker volume 里删掉容器不等于删掉数据但如果你执行了docker compose down -v数据卷就会一起被删除这点要非常小心。新手阶段还没数据问题不大做了知识库和真实用户之后再操作必须先想清楚备份方案。3. 接入大模型这是智能体能不能跑的前提3.1 Dify 为什么不自带模型很多新手第一次打开 Dify会疑惑为什么还要另外接模型。原因很简单模型推理成本高、模型更新快、每个开发者想用的模型不同。Dify 不做模型层它把接入做成标准接口让用户自由选择模型供应商。所以安装完 Dify 后第一件事不是急着创建智能体而是去设置里把模型接好。模型接不上后面做什么都会报模型相关错误。3.2 选择模型供应商的两种思路在 Dify 里配置模型通常有两种方式。第一种是调用在线大模型 API。比如 DeepSeek、通义千问、Kimi、智谱、OpenAI 兼容接口等。这种方式的好处是本地不用跑大模型对机器内存和显卡没有额外要求响应速度快效果也稳定。缺点是需要申请 API Key按量付费。第二种是接入本地模型比如通过 Ollama 跑一个开源模型再在 Dify 里配置 Ollama 作为模型供应商。这种方式适合数据不能出内网、或者想降低调用成本的场景。但本地模型对内存和显卡要求高7B 级别的模型至少建议 16GB 内存量化版会好一些但效果和在线大模型比还是有不小差距。我建议第一次学习时直接用在线 API。先把流程跑通再考虑本地化部署。如果连 API 都没调过直接上本地模型问题排查会多一层难度上升很多。3.3 以 API 模式为例填入模型配置登录 Dify 控制台后进入“设置”里的“模型供应商”页面找到你想用的服务商点击配置。以 DeepSeek 为例其他国内模型服务商也类似在模型服务商官网注册账号。创建一个 API Key并把 Key 复制下来。回到 Dify 的模型供应商页面选择 DeepSeek。把 API Key 填进去点“保存”。保存后Dify 会测试这个连接是否可用。如果测试通过你就能在 Dify 里选择 DeepSeek 作为智能体的模型了。如果你用的模型服务商支持 OpenAI 兼容协议Dify 也通常支持通过“OpenAI-API-compatible”方式添加。这个会更通用但需要你填 Base URL 和 API Key。这里的 Base URL 一定要写准确不同服务商提供的地址不一样填错会出现连接失败。我建议每配置完一个模型就先用 Dify 自带的“测试”按钮发一条消息不要直接跳去建智能体。确保模型本身能回答问题再接下一步。这个测试能帮你把“模型问题”和“智能体配置问题”区分开。3.4 模型配置的常见误区第一个误区以为模型配置完后所有应用都会自动用。Dify 里每个应用或者每个模型节点还要单独选择使用哪个模型。你只是在全局里把连接建好了具体应用要用哪个模型还需要在应用配置里再选一遍。第二个误区不管什么任务都选同一个模型。如果只是做闲聊一个普通模型够用了如果要做复杂的 Agent 工具调用或结构化输出建议选择更擅长指令遵循和函数调用的模型。对功能简单的小应用用大模型反而增加成本和响应时间。第三个误区API Key 填错了没注意空格。复制 Key 时可能多了一个空格或者结尾少了一位测试时就会报 401。遇到鉴权失败先检查 Key 是否完整、是否过期、账户是否有余额。4. 搭建第一个智能体从角色设定到工具联动4.1 创建应用并选择智能体类型模型接通后回到控制台首页点击“创建应用”。创建时你会看到几种应用类型比如聊天助手、智能体、工作流。第一次做请选择“智能体”。智能体和普通聊天助手的区别在于智能体可以调用工具。比如你让它查天气它可以调用天气接口你让它算个复杂表达式它可以调用计算工具你让它基于知识库回答它可以先检索知识库再回答。选好类型后给应用起个名字比如“客服助手”“运营小助手”。这只是一个便于管理的名字后面随时可以改。4.2 配置角色设定和指令创建完智能体后会进入编排页面。不要被一堆选项吓到关键配置就这几个模型、指令、工具、知识库、调试预览。“指令”是智能体的系统提示词它决定了智能体的人设和行为边界。我建议第一次先写一个简单清晰的指令比如你是一个客服助手负责回答用户关于产品使用的问题。回答时优先参考知识库内容。如果知识库中没有相关内容直接告诉用户需要核实后再答复不要编造信息。这里的关键是“清晰”。不要写得太空比如“你是一个很厉害的助手”这种没有约束力。要给智能体明确的行为边界。同时在指令里说明要不要使用工具、什么时候使用工具。比如当用户需要计算时使用计算工具当用户问到知识库中的信息时先检索知识库再回答。这一句会直接影响后面 Agent 工具调用的成功率。4.3 关联模型和工具在编排页面的“模型”位置选择你刚配置好的模型。模型选完后右侧调试区就能直接对话了。接下来是添加工具。Dify 自带了一些内置工具比如计算器、天气查询、搜索工具、翻译工具等。你把工具打开智能体在需要时就会主动调用。这些内置工具满足不了需求时还可以通过 OpenAPI Schema 或自定义工具的方式接入你自己的 HTTP 接口。这个属于进阶玩法新手可以放一放先试内置工具。注意很多智能体工具调用失败不是因为代码有问题而是指令中没有说清楚“什么时候用工具”。如果你发现模型一直在用文字回答而不是调工具可以在指令里加上一句“遇到计算类问题必须使用计算工具不能自己心算”。改完后重新测试通常会有改善。4.4 在调试区测试一轮完整对话配置完成后在右侧调试窗口输入一条测试消息。比如请帮我计算 23 乘以 77 等于多少如果模型和工具配置都正常你应该能看到智能体先调用计算工具再给出最终答案。这个“先工具后回答”的过程在 Dify 后台是有记录的。再看一个知识问答场景。你如果已经上传了知识库可以在调试区问一个和文档相关的问题。智能体会先去知识库检索相关内容再结合文档内容回答。调试区的作用不只是看答案更关键的是观察智能体的“思考过程”。Dify 在运行记录里会展示每一步调了哪个工具、检索了哪段知识、最终如何生成答案。遇到答非所问不要着急改提示词先看运行记录问题出在哪一步。4.5 智能体答非所问时先改指令新手最常见的困惑是“为什么智能体回答得不像我想象的那么聪明”。多数情况不是模型不行而是指令太含糊。比如你只写了一句“你是客服”模型不知道该用什么语气、按照什么格式、什么时候查知识库、什么时候用工具。试着把指令改得更具体你是谁平台、产品、岗位。能做什么回答范围、工具使用规则。不能做什么不编造信息不回答超出范围的问题。回答风格简洁、专业、友好。改完指令后重新测试一轮。如果效果变好说明问题解决了如果还是不行再检查是不是模型选得太弱或知识库没接上。5. 知识库和工作流从“只会聊天”到“会查资料、会干活”5.1 创建知识库并上传文档智能体只靠模型本身回答容易出现两个问题一是回答泛泛而谈没有你的业务细节二是幻觉模型会编造一些不存在的文件或数据。知识库就是用来缓解这两个问题的。在 Dify 控制台进入“知识库”创建一个新的知识库然后上传文档。支持的常见格式包括文本、PDF、Word、Excel 等。上传后Dify 会把文档内容拆成片段再做向量化索引。如果你只是测试随便放几段产品说明或内部规章制度都行。重点是走通“上传—分段—索引—召回”这条链路。5.2 分段和检索参数的判断标准分段是很多人容易忽略的一步。文档会被切成一个个片段智能体回答时从中检索相关片段。分段太小上下文信息不完整分段太大检索出来可能夹杂大量无关内容。Dify 里可以设置分段长度和重叠长度。一般场景下分段长度在 500 到 1000 字之间比较合适重叠长度可以设为 50 到 100。如果你的文档是问答形式每条问题答案都很短分段短一点没问题如果文档内容是长段落描述建议分段适当放大。另外向量检索时需要选择一个 Embedding 模型。这个模型的作用是把文本转成向量方便做相似度计算。你需要在模型配置里提前准备好一个支持 Embedding 的模型比如 Dify 支持的一些在线 Embedding 接口。如果没配知识库创建时就会卡住。5.3 创建知识库后一定要做召回测试上传文档并完成索引后很多人直接去智能体里问问题结果发现回答完全不基于文档。这是因为没有做召回测试。在 Dify 的知识库页面通常有一个“召回测试”功能。你可以输入一个测试问题看看系统能召回哪几个片段以及相似度分数是多少。如果召回到的片段和你预期不符先别急着改智能体指令先调整分段策略和检索方式。常见调整方向包括增大分段长度、减少重复内容、更换 Embedding 模型、调整 top-k 数量。召回测试通过后再去智能体里挂知识库效果会有明显变化。这一步很关键能帮你节省大量调试时间。5.4 在智能体里挂上知识库回到智能体编排页面在“知识库”区域添加你刚创建的知识库。添加后智能体才会在需要时自动去检索。挂上知识库后重新测试刚才的问题。这时你应该能从回答中看到文档里的具体内容说明知识库生效了。记住一个原则知识库负责提供“事实”模型负责组织“表达”。如果知识库本身召回内容不对模型再厉害也会给出错误答案。所以出问题时优先查召回结果。5.5 工作流适合固定流程不适合自由发挥智能体适合自由度高的场景但有些业务流程要求稳定和可控比如“用户提交问题后先判断分类再检索对应知识库最后生成固定格式的工单”。这种需求更适合做成工作流。Dify 的工作流允许你通过可视化方式编排节点常见的节点有开始、模型、知识库检索、条件分支、模板、应答。你可以在“创建应用”时选择“工作流”也可以在应用内切换到工作流编排。工作流的优点是可预测每一步都是固定的不会像智能体那样随机发挥。缺点是需要提前定义路径业务变化时要改架构。对新手来说我的建议是先玩明白智能体等到需求明确、逻辑稳定之后再把固定流程迁移到工作流里。反过来直接上手工作流容易被一堆节点绕晕。6. 调试、发布和 API 调用6.1 调试时看哪些信息Dify 的调试区只能看到当前一轮回答但很多问题需要看整条运行链路。这部分信息在“日志与标注”或“运行日志”里。运行日志里一般能看到用户输入了什么。模型用了哪个模型、消耗多少 Token。是否调用了工具调用结果是什么。是否检索了知识库召回哪些片段。最终回答内容。每一轮耗时。排查问题时先看这个日志再改参数效率会高很多。很多人反复改 Prompt但问题出在工具调用或知识库召回改 Prompt 当然没用。6.2 发布为 API 并获取应用凭据在 Dify 中当你觉得应用可以给别人用了可以发布这个应用。Dify 会提供访问 API 的接口供你自己的前端、钉钉、企业微信或其他系统接入。在“访问 API”页面你可以看到应用 ID、API 密钥、接口地址。API 密钥是应用密钥调用时需要用 Bearer Token 放在请求头里。这里要注意应用 API 密钥和模型供应商 API Key 不是一回事。前者是 Dify 生成的用来标识你的应用后者是你填在模型配置里的用来调用大模型。两者都要保密不能写死在公开代码里。6.3 用 curl 调用一个最简单的智能体接口Dify 的消息接口遵循统一格式。以 chat-messages 接口为例一个最小请求看起来像这样curl --location --request POST http://localhost/v1/chat-messages \ --header Authorization: Bearer app-你的应用API密钥 \ --header Content-Type: application/json \ --data-raw { inputs: {}, query: 你好, response_mode: blocking, user: test-user, conversation_id: }接口会返回消息 ID、会话 ID、回答内容等字段。这里的response_mode有两种blocking是等模型算完全部结果再返回streaming是流式返回适合做打字机效果。如果你只是测试先用 blocking 最直观。如果你的 Dify 修改了端口或域名记得把地址换成实际地址。这个 curl 请求如果成功返回说明应用发布链路是通的。接下来你可以用 Python、Node.js 或 Java 封装这个接口做成你自己的后端服务。6.4 批量调用前先想清楚限流、并发和重试如果你不只是想调试而是要批量处理一批问题先别急着开高并发。批量调用容易把两个地方打爆一是大模型 API 的限流二是 Dify 本身的容器资源。建议先把几百条测试数据跑一遍观察平均耗时和错误率。然后设置每秒钟最多请求多少次控制并发数。如果某条请求超时或返回 5xx要有重试机制但重试时要注意指数退避不要一直以同样频率重试。批量任务的日志也要保留。每条请求的唯一 ID、状态、耗时、错误信息都要记下来方便后续排查。否则跑完一批后只剩一个“失败”很难定位原因。7. 常见报错和排查清单7.1 Docker 和安装阶段问题现象可能原因排查方式浏览器打不开 Dify 页面容器未完全启动或端口被占用docker compose ps查看状态检查.env里的端口配置启动后某些服务反复重启内存不足或镜像版本不一致查看docker compose logs确认资源是否够用拉镜像持续失败或无响应Docker 网络问题镜像源不稳定配置镜像加速器重启 Docker 后再试初始化页面提示数据库异常PostgreSQL 或 Redis 还没就绪等待一段时间重新执行docker compose up -d7.2 模型相关报错现象可能原因排查方式模型测试返回鉴权失败API Key 错误、过期、有多余空格去模型供应商页面重新填写 Key确认账户余额提示模型不存在选错了模型名称或服务商在模型供应商页面确认已添加模型并在应用里重新选择模型响应很慢模型自身复杂、API 限流、网络慢查看运行日志耗时换个更快模型或调整超时应用提示“当前应用没有可用模型”应用还没选择具体模型回到应用编排页面把模型选上7.3 Agent 和知识库问题现象可能原因排查方式Agent 不调用工具工具未启用或指令没有说明打开工具并在指令中明确“什么时候用工具”工具调用后结果不对工具输入参数生成错误查看运行日志观察工具入参调整指令或工具描述知识库召回为空文档未索引或 Embedding 模型未配置在知识库里做召回测试检查分段和向量索引回答内容不含知识库知识库未挂到智能体或召回片段太靠后检查智能体编排里的知识库设置调大召回数量7.4 排查顺序建议遇到问题时我一般按这个顺序看不走冤枉路先看现象是报错、卡住还是返回结果不对。然后看 Docker 容器状态和日志确认服务本身没挂。再去 Dify 的设置里测试模型连通性排除模型问题。接着看应用的运行日志观察工具调用、知识库召回、Token 消耗。最后才改指令、改参数再重新测试。很多人习惯遇到问题就改代码或改系统但往往第一步就该确认“输入和配置是否正确”。一次只改一个变量改完马上测不要同时改模型、指令、分段好几个地方否则出了问题根本不知道是哪一步引起的。8. 最后留几句真实使用的建议8.1 先在最小范围里跑通再扩大如果你第一次用 Dify不要急着做几十个应用、几百个知识库。先创建一个最简单的聊天应用接一个模型跑通一句对话再创建第二个应用试试 Agent 工具接着再试知识库。每加一层能力都要用一条测试消息去验证。这样即使出问题你也能迅速定位到具体环节。8.2 资源占用要提前规划Dify 跑起来后内存会持续占用。如果你的机器还要跑其他服务建议给 Docker 限制一个合理的资源上限避免 Dify 把整台机器拉爆。另外日志和数据库会越跑越大。如果你只是学习定期清理一些不用的应用和知识库就够了。如果是生产环境必须考虑数据备份、磁盘监控和日志归档。开源项目持续运行一段时间后最常见的不是功能问题而是磁盘满了、内存不够了、数据库连接数炸了。8.3 不要把默认配置直接当生产配置使用Dify 默认生成的.env里有不少系统配置。如果你是本地测试默认配置够用如果要暴露到公网或者长期使用至少要检查几件事管理员密码改成强密码、应用密钥不要泄露、数据库端口不要直接暴露公网、定期升级到稳定版本。升级 Dify 前先备份数据卷和.env再看官方 Release Notes。不要一看到新版就原地docker compose pull有些变更可能需要额外的迁移步骤。8.4 智能体效果不好先看日志再改参数使用 Dify 最大的好处就是你能看到每一步发生了什么。效果不好时运行日志会告诉你模型消耗了多少 Token、工具调用了几次、知识库召回了哪些片段。比起反复随机改提示词我更建议记录每轮测试的输入、输出和问题现象。改一次测一次把有效配置固化下来。你会发现很多看起来“智能”的结果其实是靠清晰的指令、可靠的知识库和合理的工具配置堆出来的。Dify 装起来不难难的是把模型、知识库、工具和工作流真正捏合成一个能稳定干活的智能体。如果你第一次跑通了后面再扩展其他应用就会顺很多。先从这个小目标开始。
Dify 从安装部署到智能体搭建：开源大模型平台实战指南
Dify 是一个开源的大模型应用开发与智能体搭建平台这篇文章会从安装部署讲起一直做到第一个能用的 AI 智能体。整个流程我尽量按新手能直接照着操作的方式写不绕弯子。先说结论只要机器配置不是太老、Docker 环境正常安装这一环并不难真正的分水岭在模型接入、工具配置和工作流调试。很多人卡住不是命令不会敲而是底层概念没理清。下面围绕 Dify 安装部署、模型接通、智能体搭建、知识库接入、问题排查和上线发布完整拆一遍。1. 先弄清楚 Dify 是什么再动手装1.1 它到底解决什么问题先理解 Dify 的定位。它不是一个大模型而是一个用来编排大模型能力的开源平台。你可以把大模型当作“员工”Dify 是给这个员工发任务、配工具、管流程、看效果的管理系统。Dify 解决的核心问题有三个。第一个是应用开发成本。以前想做一个基于大模型的服务要自己写前后端、设计接口、处理会话状态、管理日志和用户门槛不低。Dify 把这一层做成可视化界面你可以通过拖拽和配置快速搭出一个对话应用。第二个是智能体搭建门槛。智能体不是简单地把模型接出来聊几句它还需要角色设定、工具调用、知识库查询、多轮对话记忆、结果整理。这些东西如果从零开发需要掌握 Prompt 工程、函数调用、向量检索等一堆概念。Dify 把常用的智能体骨架内置好了你只需要填角色和目标然后绑定工具和知识库。第三个是运维和迭代问题。应用上线后怎么观察用户问了什么、模型答得怎么样、调用花了多少 Token、哪一步导致响应变慢都需要日志和监控。Dify 自带访问日志、标注和运行记录方便调试和优化。另外Dify 还支持工作流。工作流适合流程相对固定的业务比如“先判断用户意图再按不同分支调用不同模型步骤最后生成结构化结果”。智能体则适合灵活决策让模型自己决定调什么工具。两者可以分开用也可以组合。1.2 适合什么人不适合什么人从实际经验看Dify 适合这几类人想快速验证大模型应用想法的个人开发者。需要给企业做内部知识问答助手的产品或研发。暂时没有前端团队但想先做出一个可演示 Demo 的团队。做数据分析、客服、营销内容生成希望用智能体减少重复劳动的人。刚接触大模型想理解“模型、智能体、知识库、工作流”之间关系的新手。如果你本身就是做底层模型训练的那 Dify 不太适合你。它更偏应用层不负责训练模型也不负责微调权重。如果你需要的只是一个纯前端聊天窗口Dify 对你说不定有点重直接调模型 API 更快。还有一个需要提前说清楚的地方Dify 安装后它自己并不具备思考能力。你必须先给它接通一个大模型比如 OpenAI 兼容接口、DeepSeek、通义千问、Kimi、智谱或者本地部署的 Ollama。把模型接上之后Dify 的智能体、知识库、工作流才有意义。1.3 安装前必须理解的五个基础词模型供应商提供大模型接口的服务商。Dify 负责调用它离了它智能体就没有“大脑”。应用你最终给用户使用的一个入口可以是对话机器人也可以是工作流服务。智能体一种应用类型。它会根据用户目标自己决定调用哪些工具、查哪些知识库、怎样组织回答。知识库把文档切碎、向量化后存储起来方便智能体回答时按需检索减少模型瞎编。工作流提前设计好的节点流程像流程图一样固定执行适合确定性较强的业务。这五个词在装完之后马上会用到。先有个印象就行后面每一步都会碰到。2. DeployDocker 环境准备和 Dify 安装2.1 硬件和系统要求先说硬件。Dify 由一堆容器组成包括 API 服务、Worker、数据库 PostgreSQL、缓存 Redis、向量数据库、Nginx 入口等。容器数量多所以对内存有一定要求。我的建议是内存 8GB 起步能到 16GB 更好。CPU 4 核以上普通家用级 CPU 也能跑。磁盘至少预留 50GB因为镜像、数据库、日志和知识库向量数据都会增长。如果你用的是 Windows建议装 Docker Desktop并启用 WSL2 后端。如果你的机器只有 4GB 内存也不是完全不能跑。第一次安装有可能成功但启动会比较慢浏览器打开页面时可能卡顿。这时候不要同时开一堆容器也不要急着创建大量知识库分段。先用最小配置跑通再考虑扩展。系统方面Windows、macOS、Linux 都支持 Docker 安装。不过实际部署到服务器做生产用时我更推荐 Linux。因为资源占用低Docker 重启策略更好控制不容易出现桌面环境抢占内存的情况。2.2 安装 Docker 和 Docker Compose安装 Dify 之前首先要有一个能正常运行的 Docker 环境。Windows 用户安装 Docker Desktop安装时选择 WSL2 后端。Docker Desktop 自带 Docker Compose不需要单独装。Linux 用户建议安装 Docker Engine 和 Docker Compose 插件。不要漏了 ComposeDify 启动靠的是docker compose命令而不是单独docker run。装完 Docker 后先在终端验证一下docker --version docker compose version如果两个命令都正常输出版本信息说明 Docker 环境基本可用。这里注意一个常见问题Docker 启动后Windows 上可能提示 WSL 内核版本太旧Linux 上可能提示 dockerd 服务没起来。先把这个解决掉再继续下一步。否则 Dify 后面报什么错都容易被误判成安装问题。2.3 获取 Dify 源码并启动Dify 的安装方式主要是通过 Docker 启动官方提供的 compose 文件。通用流程是git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env docker compose up -d第一次执行docker compose up -d时需要拉取多个镜像。这个阶段耗时和网络关系很大可能几分钟也可能十几分钟。如果卡住不要反复按 CtrlC先确认 Docker 网络是否正常是否配置了镜像加速器。如果你在国内服务器或本地网络拉镜像很慢建议先配置 Docker 镜像加速器。常见做法是在 Docker Desktop 的配置里或在/etc/docker/daemon.json中填国内可用的镜像源地址。这个属于基础运维操作网上资料很多。配置完记得重启 Docker 再拉一次。镜像拉取完成后Dify 会自动启动这些服务组件nginx、api、worker、postgres、redis、weaviate 或 qdrant向量数据库。启动过程不是瞬间完成数据库初始化需要一点时间。2.4 验证安装是否成功启动完成后先看容器状态docker compose ps留意每个服务的状态是否都是running。如果看到restarting或exited说明某个服务有问题。这时候最该做的是看日志docker compose logs -f api不要只看容器是不是启动了还要看页面的初始化流程。浏览器输入http://localhost正常会进入 Dify 的初始化页面让你设置管理员邮箱和密码。这一步设置的是平台管理员不是智能体。真正创建智能体是在登录之后的控制台里。如果没有出现初始化页面优先排查两件事第一docker compose ps是否全部 running第二端口是否被占用。如果你本机 80 端口已经有别的服务需要在.env里修改EXPOSE_NGINX_PORT改成比如 8080再重新启动。2.5 安装阶段的几个坑第一不要直接修改 Dify 的.env.example应该复制一份成.env再修改。第二不要忽略 Docker 资源限制。Docker Desktop 默认分配的内存可能只有 2GB 到 4GB不够用的话去 Docker Desktop 设置里把内存调大建议调到 6GB 到 8GB。第三重新安装或升级前先备份数据卷。Dify 的数据主要存在 docker volume 里删掉容器不等于删掉数据但如果你执行了docker compose down -v数据卷就会一起被删除这点要非常小心。新手阶段还没数据问题不大做了知识库和真实用户之后再操作必须先想清楚备份方案。3. 接入大模型这是智能体能不能跑的前提3.1 Dify 为什么不自带模型很多新手第一次打开 Dify会疑惑为什么还要另外接模型。原因很简单模型推理成本高、模型更新快、每个开发者想用的模型不同。Dify 不做模型层它把接入做成标准接口让用户自由选择模型供应商。所以安装完 Dify 后第一件事不是急着创建智能体而是去设置里把模型接好。模型接不上后面做什么都会报模型相关错误。3.2 选择模型供应商的两种思路在 Dify 里配置模型通常有两种方式。第一种是调用在线大模型 API。比如 DeepSeek、通义千问、Kimi、智谱、OpenAI 兼容接口等。这种方式的好处是本地不用跑大模型对机器内存和显卡没有额外要求响应速度快效果也稳定。缺点是需要申请 API Key按量付费。第二种是接入本地模型比如通过 Ollama 跑一个开源模型再在 Dify 里配置 Ollama 作为模型供应商。这种方式适合数据不能出内网、或者想降低调用成本的场景。但本地模型对内存和显卡要求高7B 级别的模型至少建议 16GB 内存量化版会好一些但效果和在线大模型比还是有不小差距。我建议第一次学习时直接用在线 API。先把流程跑通再考虑本地化部署。如果连 API 都没调过直接上本地模型问题排查会多一层难度上升很多。3.3 以 API 模式为例填入模型配置登录 Dify 控制台后进入“设置”里的“模型供应商”页面找到你想用的服务商点击配置。以 DeepSeek 为例其他国内模型服务商也类似在模型服务商官网注册账号。创建一个 API Key并把 Key 复制下来。回到 Dify 的模型供应商页面选择 DeepSeek。把 API Key 填进去点“保存”。保存后Dify 会测试这个连接是否可用。如果测试通过你就能在 Dify 里选择 DeepSeek 作为智能体的模型了。如果你用的模型服务商支持 OpenAI 兼容协议Dify 也通常支持通过“OpenAI-API-compatible”方式添加。这个会更通用但需要你填 Base URL 和 API Key。这里的 Base URL 一定要写准确不同服务商提供的地址不一样填错会出现连接失败。我建议每配置完一个模型就先用 Dify 自带的“测试”按钮发一条消息不要直接跳去建智能体。确保模型本身能回答问题再接下一步。这个测试能帮你把“模型问题”和“智能体配置问题”区分开。3.4 模型配置的常见误区第一个误区以为模型配置完后所有应用都会自动用。Dify 里每个应用或者每个模型节点还要单独选择使用哪个模型。你只是在全局里把连接建好了具体应用要用哪个模型还需要在应用配置里再选一遍。第二个误区不管什么任务都选同一个模型。如果只是做闲聊一个普通模型够用了如果要做复杂的 Agent 工具调用或结构化输出建议选择更擅长指令遵循和函数调用的模型。对功能简单的小应用用大模型反而增加成本和响应时间。第三个误区API Key 填错了没注意空格。复制 Key 时可能多了一个空格或者结尾少了一位测试时就会报 401。遇到鉴权失败先检查 Key 是否完整、是否过期、账户是否有余额。4. 搭建第一个智能体从角色设定到工具联动4.1 创建应用并选择智能体类型模型接通后回到控制台首页点击“创建应用”。创建时你会看到几种应用类型比如聊天助手、智能体、工作流。第一次做请选择“智能体”。智能体和普通聊天助手的区别在于智能体可以调用工具。比如你让它查天气它可以调用天气接口你让它算个复杂表达式它可以调用计算工具你让它基于知识库回答它可以先检索知识库再回答。选好类型后给应用起个名字比如“客服助手”“运营小助手”。这只是一个便于管理的名字后面随时可以改。4.2 配置角色设定和指令创建完智能体后会进入编排页面。不要被一堆选项吓到关键配置就这几个模型、指令、工具、知识库、调试预览。“指令”是智能体的系统提示词它决定了智能体的人设和行为边界。我建议第一次先写一个简单清晰的指令比如你是一个客服助手负责回答用户关于产品使用的问题。回答时优先参考知识库内容。如果知识库中没有相关内容直接告诉用户需要核实后再答复不要编造信息。这里的关键是“清晰”。不要写得太空比如“你是一个很厉害的助手”这种没有约束力。要给智能体明确的行为边界。同时在指令里说明要不要使用工具、什么时候使用工具。比如当用户需要计算时使用计算工具当用户问到知识库中的信息时先检索知识库再回答。这一句会直接影响后面 Agent 工具调用的成功率。4.3 关联模型和工具在编排页面的“模型”位置选择你刚配置好的模型。模型选完后右侧调试区就能直接对话了。接下来是添加工具。Dify 自带了一些内置工具比如计算器、天气查询、搜索工具、翻译工具等。你把工具打开智能体在需要时就会主动调用。这些内置工具满足不了需求时还可以通过 OpenAPI Schema 或自定义工具的方式接入你自己的 HTTP 接口。这个属于进阶玩法新手可以放一放先试内置工具。注意很多智能体工具调用失败不是因为代码有问题而是指令中没有说清楚“什么时候用工具”。如果你发现模型一直在用文字回答而不是调工具可以在指令里加上一句“遇到计算类问题必须使用计算工具不能自己心算”。改完后重新测试通常会有改善。4.4 在调试区测试一轮完整对话配置完成后在右侧调试窗口输入一条测试消息。比如请帮我计算 23 乘以 77 等于多少如果模型和工具配置都正常你应该能看到智能体先调用计算工具再给出最终答案。这个“先工具后回答”的过程在 Dify 后台是有记录的。再看一个知识问答场景。你如果已经上传了知识库可以在调试区问一个和文档相关的问题。智能体会先去知识库检索相关内容再结合文档内容回答。调试区的作用不只是看答案更关键的是观察智能体的“思考过程”。Dify 在运行记录里会展示每一步调了哪个工具、检索了哪段知识、最终如何生成答案。遇到答非所问不要着急改提示词先看运行记录问题出在哪一步。4.5 智能体答非所问时先改指令新手最常见的困惑是“为什么智能体回答得不像我想象的那么聪明”。多数情况不是模型不行而是指令太含糊。比如你只写了一句“你是客服”模型不知道该用什么语气、按照什么格式、什么时候查知识库、什么时候用工具。试着把指令改得更具体你是谁平台、产品、岗位。能做什么回答范围、工具使用规则。不能做什么不编造信息不回答超出范围的问题。回答风格简洁、专业、友好。改完指令后重新测试一轮。如果效果变好说明问题解决了如果还是不行再检查是不是模型选得太弱或知识库没接上。5. 知识库和工作流从“只会聊天”到“会查资料、会干活”5.1 创建知识库并上传文档智能体只靠模型本身回答容易出现两个问题一是回答泛泛而谈没有你的业务细节二是幻觉模型会编造一些不存在的文件或数据。知识库就是用来缓解这两个问题的。在 Dify 控制台进入“知识库”创建一个新的知识库然后上传文档。支持的常见格式包括文本、PDF、Word、Excel 等。上传后Dify 会把文档内容拆成片段再做向量化索引。如果你只是测试随便放几段产品说明或内部规章制度都行。重点是走通“上传—分段—索引—召回”这条链路。5.2 分段和检索参数的判断标准分段是很多人容易忽略的一步。文档会被切成一个个片段智能体回答时从中检索相关片段。分段太小上下文信息不完整分段太大检索出来可能夹杂大量无关内容。Dify 里可以设置分段长度和重叠长度。一般场景下分段长度在 500 到 1000 字之间比较合适重叠长度可以设为 50 到 100。如果你的文档是问答形式每条问题答案都很短分段短一点没问题如果文档内容是长段落描述建议分段适当放大。另外向量检索时需要选择一个 Embedding 模型。这个模型的作用是把文本转成向量方便做相似度计算。你需要在模型配置里提前准备好一个支持 Embedding 的模型比如 Dify 支持的一些在线 Embedding 接口。如果没配知识库创建时就会卡住。5.3 创建知识库后一定要做召回测试上传文档并完成索引后很多人直接去智能体里问问题结果发现回答完全不基于文档。这是因为没有做召回测试。在 Dify 的知识库页面通常有一个“召回测试”功能。你可以输入一个测试问题看看系统能召回哪几个片段以及相似度分数是多少。如果召回到的片段和你预期不符先别急着改智能体指令先调整分段策略和检索方式。常见调整方向包括增大分段长度、减少重复内容、更换 Embedding 模型、调整 top-k 数量。召回测试通过后再去智能体里挂知识库效果会有明显变化。这一步很关键能帮你节省大量调试时间。5.4 在智能体里挂上知识库回到智能体编排页面在“知识库”区域添加你刚创建的知识库。添加后智能体才会在需要时自动去检索。挂上知识库后重新测试刚才的问题。这时你应该能从回答中看到文档里的具体内容说明知识库生效了。记住一个原则知识库负责提供“事实”模型负责组织“表达”。如果知识库本身召回内容不对模型再厉害也会给出错误答案。所以出问题时优先查召回结果。5.5 工作流适合固定流程不适合自由发挥智能体适合自由度高的场景但有些业务流程要求稳定和可控比如“用户提交问题后先判断分类再检索对应知识库最后生成固定格式的工单”。这种需求更适合做成工作流。Dify 的工作流允许你通过可视化方式编排节点常见的节点有开始、模型、知识库检索、条件分支、模板、应答。你可以在“创建应用”时选择“工作流”也可以在应用内切换到工作流编排。工作流的优点是可预测每一步都是固定的不会像智能体那样随机发挥。缺点是需要提前定义路径业务变化时要改架构。对新手来说我的建议是先玩明白智能体等到需求明确、逻辑稳定之后再把固定流程迁移到工作流里。反过来直接上手工作流容易被一堆节点绕晕。6. 调试、发布和 API 调用6.1 调试时看哪些信息Dify 的调试区只能看到当前一轮回答但很多问题需要看整条运行链路。这部分信息在“日志与标注”或“运行日志”里。运行日志里一般能看到用户输入了什么。模型用了哪个模型、消耗多少 Token。是否调用了工具调用结果是什么。是否检索了知识库召回哪些片段。最终回答内容。每一轮耗时。排查问题时先看这个日志再改参数效率会高很多。很多人反复改 Prompt但问题出在工具调用或知识库召回改 Prompt 当然没用。6.2 发布为 API 并获取应用凭据在 Dify 中当你觉得应用可以给别人用了可以发布这个应用。Dify 会提供访问 API 的接口供你自己的前端、钉钉、企业微信或其他系统接入。在“访问 API”页面你可以看到应用 ID、API 密钥、接口地址。API 密钥是应用密钥调用时需要用 Bearer Token 放在请求头里。这里要注意应用 API 密钥和模型供应商 API Key 不是一回事。前者是 Dify 生成的用来标识你的应用后者是你填在模型配置里的用来调用大模型。两者都要保密不能写死在公开代码里。6.3 用 curl 调用一个最简单的智能体接口Dify 的消息接口遵循统一格式。以 chat-messages 接口为例一个最小请求看起来像这样curl --location --request POST http://localhost/v1/chat-messages \ --header Authorization: Bearer app-你的应用API密钥 \ --header Content-Type: application/json \ --data-raw { inputs: {}, query: 你好, response_mode: blocking, user: test-user, conversation_id: }接口会返回消息 ID、会话 ID、回答内容等字段。这里的response_mode有两种blocking是等模型算完全部结果再返回streaming是流式返回适合做打字机效果。如果你只是测试先用 blocking 最直观。如果你的 Dify 修改了端口或域名记得把地址换成实际地址。这个 curl 请求如果成功返回说明应用发布链路是通的。接下来你可以用 Python、Node.js 或 Java 封装这个接口做成你自己的后端服务。6.4 批量调用前先想清楚限流、并发和重试如果你不只是想调试而是要批量处理一批问题先别急着开高并发。批量调用容易把两个地方打爆一是大模型 API 的限流二是 Dify 本身的容器资源。建议先把几百条测试数据跑一遍观察平均耗时和错误率。然后设置每秒钟最多请求多少次控制并发数。如果某条请求超时或返回 5xx要有重试机制但重试时要注意指数退避不要一直以同样频率重试。批量任务的日志也要保留。每条请求的唯一 ID、状态、耗时、错误信息都要记下来方便后续排查。否则跑完一批后只剩一个“失败”很难定位原因。7. 常见报错和排查清单7.1 Docker 和安装阶段问题现象可能原因排查方式浏览器打不开 Dify 页面容器未完全启动或端口被占用docker compose ps查看状态检查.env里的端口配置启动后某些服务反复重启内存不足或镜像版本不一致查看docker compose logs确认资源是否够用拉镜像持续失败或无响应Docker 网络问题镜像源不稳定配置镜像加速器重启 Docker 后再试初始化页面提示数据库异常PostgreSQL 或 Redis 还没就绪等待一段时间重新执行docker compose up -d7.2 模型相关报错现象可能原因排查方式模型测试返回鉴权失败API Key 错误、过期、有多余空格去模型供应商页面重新填写 Key确认账户余额提示模型不存在选错了模型名称或服务商在模型供应商页面确认已添加模型并在应用里重新选择模型响应很慢模型自身复杂、API 限流、网络慢查看运行日志耗时换个更快模型或调整超时应用提示“当前应用没有可用模型”应用还没选择具体模型回到应用编排页面把模型选上7.3 Agent 和知识库问题现象可能原因排查方式Agent 不调用工具工具未启用或指令没有说明打开工具并在指令中明确“什么时候用工具”工具调用后结果不对工具输入参数生成错误查看运行日志观察工具入参调整指令或工具描述知识库召回为空文档未索引或 Embedding 模型未配置在知识库里做召回测试检查分段和向量索引回答内容不含知识库知识库未挂到智能体或召回片段太靠后检查智能体编排里的知识库设置调大召回数量7.4 排查顺序建议遇到问题时我一般按这个顺序看不走冤枉路先看现象是报错、卡住还是返回结果不对。然后看 Docker 容器状态和日志确认服务本身没挂。再去 Dify 的设置里测试模型连通性排除模型问题。接着看应用的运行日志观察工具调用、知识库召回、Token 消耗。最后才改指令、改参数再重新测试。很多人习惯遇到问题就改代码或改系统但往往第一步就该确认“输入和配置是否正确”。一次只改一个变量改完马上测不要同时改模型、指令、分段好几个地方否则出了问题根本不知道是哪一步引起的。8. 最后留几句真实使用的建议8.1 先在最小范围里跑通再扩大如果你第一次用 Dify不要急着做几十个应用、几百个知识库。先创建一个最简单的聊天应用接一个模型跑通一句对话再创建第二个应用试试 Agent 工具接着再试知识库。每加一层能力都要用一条测试消息去验证。这样即使出问题你也能迅速定位到具体环节。8.2 资源占用要提前规划Dify 跑起来后内存会持续占用。如果你的机器还要跑其他服务建议给 Docker 限制一个合理的资源上限避免 Dify 把整台机器拉爆。另外日志和数据库会越跑越大。如果你只是学习定期清理一些不用的应用和知识库就够了。如果是生产环境必须考虑数据备份、磁盘监控和日志归档。开源项目持续运行一段时间后最常见的不是功能问题而是磁盘满了、内存不够了、数据库连接数炸了。8.3 不要把默认配置直接当生产配置使用Dify 默认生成的.env里有不少系统配置。如果你是本地测试默认配置够用如果要暴露到公网或者长期使用至少要检查几件事管理员密码改成强密码、应用密钥不要泄露、数据库端口不要直接暴露公网、定期升级到稳定版本。升级 Dify 前先备份数据卷和.env再看官方 Release Notes。不要一看到新版就原地docker compose pull有些变更可能需要额外的迁移步骤。8.4 智能体效果不好先看日志再改参数使用 Dify 最大的好处就是你能看到每一步发生了什么。效果不好时运行日志会告诉你模型消耗了多少 Token、工具调用了几次、知识库召回了哪些片段。比起反复随机改提示词我更建议记录每轮测试的输入、输出和问题现象。改一次测一次把有效配置固化下来。你会发现很多看起来“智能”的结果其实是靠清晰的指令、可靠的知识库和合理的工具配置堆出来的。Dify 装起来不难难的是把模型、知识库、工具和工作流真正捏合成一个能稳定干活的智能体。如果你第一次跑通了后面再扩展其他应用就会顺很多。先从这个小目标开始。