先说问题:会聊天,不等于能干活
聊天框式的 AI 用法有个天花板:每次都要手动粘贴内容、重复交代要求、再把结果复制出来。真正能省时间的用法,是把「输入 → 处理步骤 → 输出格式」固定下来,做成一个可以反复调用的小应用:文章丢进去,摘要出来;工单丢进去,分类和回复草稿出来。这类「把提示词变成流水线」的活,正是 Dify 的主场。
Dify 是一个开源的 LLM 应用开发平台,可以自托管。它把几件通常要分别搭的东西打包在了一起:可视化工作流编排、知识库(RAG)、Agent、模型供应商管理、应用发布(网页端+API)。你在画布上拖节点连线,背后就是一次真实的程序执行;搭好的应用既能生成一个可分享的网页,也能拿到 API Key 被自己的脚本和系统调用。
本篇主线:Docker Compose 自托管部署 Dify → 初始化管理员 → 接入云端 API 与本地 Ollama 两种模型 → 搞清四种应用形态 → 完整搭一个「长文章 → 摘要+要点+标题」工作流 → 发布成网页和 API → 资源占用与备份要点。本地模型与知识库的原理细节,本系列另有 Ollama 部署本地大模型 与 RAG 个人知识库 两篇,本篇只讲在 Dify 里怎么用,不重复展开。
部署:Docker Compose 一把梭
Dify 官方只推荐 Docker Compose 部署。先看一眼它到底会拉起多少东西,心里有数再动手:
| 组件 | 作用 | 备注 |
|---|---|---|
| api | 后端 API 服务 | 业务逻辑核心 |
| worker / worker_beat | 异步任务与定时任务 | 文档解析、索引构建都在这里跑 |
| web | 前端控制台 | 浏览器里操作的那个界面 |
| db | PostgreSQL | 存应用、对话、配置 |
| redis | 缓存与队列 | 任务队列依赖 |
| weaviate | 默认向量数据库 | 知识库索引,可换 Qdrant、Milvus 等 |
| sandbox | 代码节点沙箱 | 跑工作流里的代码节点 |
| plugin_daemon | 插件守护进程 | 模型与工具以插件形式接入 |
| ssrf_proxy | 出站请求防护 | HTTP 请求节点经它出网 |
| nginx | 统一入口反代 | 对外只暴露它 |
部署命令(服务器上执行,目录位置按自己习惯):
git clone https://github.com/langgenius/dify.gitcd dify/dockercp .env.example .envdocker compose up -d.env 里第一次部署真正需要留意的就几项,其余保持默认:
# 对外端口(被占用就改这两个)EXPOSE_NGINX_PORT=80EXPOSE_NGINX_SSL_PORT=443
# 数据库密码,默认是弱口令,务必改掉DB_PASSWORD=换成你自己的强密码
# 向量库类型,默认 weaviate,想换在这里改VECTOR_STORE=weaviate
# 文件存储,默认本地磁盘STORAGE_TYPE=opendalOPENDAL_SCHEME=fs启动后等一两分钟,容器陆续 healthy,再访问 http://你的服务器地址/install 进入初始化页面,设置管理员邮箱和密码。登录后看到的控制台首页,就是后面所有工作的起点。
WARNING初始化页面在建好管理员之前是无鉴权的,谁先打开谁就是管理员。部署完成后第一件事就是立刻完成初始化,不要把 /install 页面在公网上晾着。另外 Dify 这一套容器不少,官方口径的最低配置是 2 核 4GB 内存,小于这个规格跑文档解析时很容易被 OOM 打断。
接入模型:云端与本地两条线
Dify 本身不带模型智能,所有生成能力都来自你接入的模型供应商。在右上角头像菜单进入「设置 → 模型供应商」,按插件方式安装并配置。两条路线:
云端 API:装 OpenAI、Anthropic、DeepSeek、通义千问等对应插件,填 API Key 即可。适合效果优先、按量付费的场景。
本地 Ollama:装 Ollama 插件,添加模型时把 API 基础地址指向你的 Ollama 服务。这里有个经典坑:Dify 在容器里,Ollama 在宿主机上时,地址不能写 localhost,要写宿主机在 Docker 网络里的地址:
模型类型:LLM模型名称:qwen3:8b ← 与 ollama list 里显示的名字一字不差API 基础地址:http://host.docker.internal:11434如果 Ollama 是另一台机器,就填那台机器的内网地址和端口。填完在供应商页面能看到模型状态变绿,再去「系统模型设置」里把默认推理模型、嵌入模型各指定一个,后面建应用时就不用每次重选。嵌入模型如果要做知识库,必须配一个(如 bge-m3 或云端 embedding 接口),只配聊天模型是不够的。
两种供应商可以同时存在、按应用切换:工作流里每个 LLM 节点都能独立选模型,完全可以让摘要节点用云端大模型、分类节点用本地小模型,把钱花在刀刃上。
建应用之前:四种形态先选对
Dify 创建应用时要先选形态,选错了后面全是别扭。四种主要形态对比:
| 形态 | 交互方式 | 适合场景 | 说明 |
|---|---|---|---|
| 聊天助手 | 多轮对话 | 客服问答、带知识库的问答机器人 | 内置对话记忆,可挂知识库 |
| 文本生成 | 一次输入一次输出 | 摘要、改写、批量文案 | 表单式输入,跑完出结果 |
| 工作流 | 一次运行、节点流水线 | 结构化处理、多步骤加工、对外供 API | 无对话,输入变量 → 输出变量,最适合自动化 |
| Agent | 自主调用工具的多轮对话 | 需要查资料、调接口的复杂问答 | 模型自己决定调用哪些工具 |
还有一种「对话流(Chatflow)」是工作流的对话版,每轮对话触发一次流程编排,属于进阶玩法,先知道有它即可。本篇实战选工作流:输入输出都结构化,跑完还能直接当 API 用,是四种里最「程序员友好」的形态。
实战:长文章 → 摘要+要点+标题
需求很具体:给一段长文章(比如一篇博客草稿或一篇新闻稿),自动产出三样东西——一句话摘要、3–5 条要点、一个标题,并拼成固定格式输出。下面逐节点搭。
在工作室点「创建应用 → 工作流」,命名为「文章摘要助手」。画布上默认已有一个开始节点。
节点 1:开始——定义输入
点开开始节点,添加一个输入字段:
变量名:article类型:段落(长文本)标签:文章正文必填:是再加一个可选字段 style(短文本,选填),用来控制标题风格,比如填「严肃」或「活泼」,不填就走默认。开始节点的作用就是声明这条流水线的入参,后面所有节点都只能引用这里定义过的变量——这也是工作流比聊天框可靠的原因:输入契约是写死的。
节点 2:LLM——干活的核心
从节点面板拖一个 LLM 节点连到开始节点后面,配置三处:
- 模型:选一个中文能力好的模型。摘要这类任务对推理要求不高,云端的中杯模型或本地 8B 级别模型都够用。
- 系统提示词:把输出结构钉死,这是全篇最重要的一段文字:
你是一个中文编辑助手。阅读用户给出的文章,严格按以下结构输出,不要输出任何多余的解释:
用一句话概括全文,不超过 60 字。
提炼 3 到 5 条核心要点,每条一行,以「- 」开头。
给出一个标题,不超过 24 字。标题风格:{{#开始节点.style#}}- 用户提示词:只放文章变量本身,形如
{{#开始节点.article#}}(在编辑器里通过变量选择器插入,不要手打,节点 ID 对不上会直接报错)。
WARNING结构化输出最容易翻车的地方,是模型在正文前后加「好的,以下是摘要:」这类客套话。提示词里必须明确写「不要输出任何多余的解释」,并且先在调试里跑两三篇不同长度的文章验证格式稳定性,再往下接节点。格式不稳,后面的模板拼装全会跟着乱。
节点 3:模板转换——拼装成品
LLM 的输出是一整段带标记的文本,很多时候直接用就够了。但如果要给下游系统消费,或者想换个排版,就加一个「模板转换」节点,用 Jinja2 模板把上游变量拼成最终成品:
# 文章速览
{{ arg1}}
---由文章摘要助手自动生成模板节点里把 arg1 绑定为 LLM 节点的输出文本即可。模板转换不消耗任何模型调用,纯字符串处理,适合做加页眉页脚、拼 Markdown、组装 JSON 前的文本整形这类活。
节点 4:直接回复——交付结果
最后拖一个「直接回复」节点(部分版本里叫「结束/Answer」),内容引用模板转换节点的输出变量。工作流跑到这里,就把这段文本作为最终结果返回。
跑通与调试
点右上角「运行」,在测试面板粘贴一篇文章全文,点执行。画布上每个节点会依次亮起,点任意节点能看到它的实际输入与输出——这是 Dify 调试体验最好的地方:哪一步格式跑偏,一眼定位。常见调整就两类:摘要太长,回 LLM 节点把字数上限写得更硬;要点数量不稳,在提示词里把「3 到 5 条」改成固定「4 条」。
如果这个摘要结果还要喂给别的系统(比如自动发到笔记软件),把「直接回复」换成或追加一个「HTTP 请求」节点即可:方法选 POST,URL 填目标接口,Body 选 JSON 并引用上游输出变量。工作流的终点是回复还是请求,取决于结果给谁看。
知识库:点到为止
如果你的应用需要「照着我的文档回答」,就用知识库:控制台「知识库 → 创建」,上传文档后 Dify 会自动完成分段、向量化、建索引,应用里加一个「知识检索」节点(或在聊天助手里直接挂载知识库)就能引用。
本篇只提醒两个关键点:第一,索引质量取决于分段,文档先清洗再上传,扫描版 PDF 先转成文本,别指望它替你 OCR 出奇迹;第二,嵌入模型一旦选定,中途换模型等于全量重建索引,动手前想清楚。原理、切分策略与召回调参,本系列的 RAG 个人知识库 一篇专门讲透,这里不展开。
另外提一句定位问题:如果只是想要一个带知识库的聊天网页,不需要工作流编排,Open WebUI 那类工具更轻;Dify 的价值在于「流程+发布」,别为喝牛奶养一头牛。
发布:网页与 API 两种入口
调试通过后点「发布」,应用立刻有两个入口:
WebApp:发布页给出一个独立网址,任何人打开就能用(可设置访问密码或仅限成员)。适合把摘要助手这类小工具直接分享给同事。
API:在应用的「访问 API」页生成 API Key,用标准 HTTP 调用工作流:
curl -X POST 'http://你的服务器地址/v1/workflows/run' \ -H 'Authorization: Bearer app-替换成你的APIKey' \ -H 'Content-Type: application/json' \ -d '{ "inputs": { "article": "把文章全文放在这里……", "style": "严肃" }, "response_mode": "blocking", "user": "my-script" }'response_mode 用 blocking 是等跑完一次性返回结果,脚本里最好处理;streaming 则是流式返回中间事件。返回 JSON 里 data.outputs 就是直接回复节点的内容。至此,这个摘要流水线就从「网页上的小玩具」变成了任何脚本、定时任务、其他服务都能调用的能力。
WARNINGAPI Key 等同于这个应用的调用凭证,不要把带 Key 的调用代码提交到公开仓库,也不要给公网应用关闭访问控制裸奔。自托管实例如果只在内网用,建议连同控制台一起放在反向代理加认证之后,或干脆不映射公网端口。
资源占用与备份
资源方面有个心理预期:全套容器空载时内存占用大约 2–3GB,其中 PostgreSQL、向量库和 api/worker 是大头;跑文档解析和批量索引时 CPU 会阶段性拉满。2 核 4GB 是能跑的下限,长期用建议 4 核 8GB 起步。磁盘增长主要来自三处:上传的知识库文件、向量索引、对话日志,定期看一眼 docker system df 和数据卷大小。
备份要抓三样,缺一不可:
# 1. 数据库(应用、提示词、对话全在这里)docker compose exec db pg_dump -U postgres dify > dify-db-$(date +%F).sql
# 2. 文件存储卷(上传文件、知识库源文件、生成结果)docker compose stop api workertar -czf dify-storage-$(date +%F).tar.gz -C /var/lib/docker/volumes/docker_app-storage/_data .docker compose start api worker
# 3. 配置本身cp .env docker-compose.yaml ~/dify-config-backup/记住一句话:Dify 里最值钱的不是容器,而是数据库加存储卷这两份数据,备份策略围着它们转就对了。升级 Dify 时先备份再 git pull 拉新镜像重建,官方升级路径一直是这个套路;跨大版本升级前先看一眼 release notes 里的迁移说明。
常见问题与排障
容器都起来了,但打开页面白屏或 502。 先看 nginx 和 api 的日志:docker compose logs -f nginx api。多半是 api 还没完成数据库迁移就对外服务,等一两分钟再刷新;若 api 日志里报数据库连接失败,回头检查 .env 里 DB_PASSWORD 是否与 db 容器初始化时用的密码一致——改密码要在首次启动前改,库已经初始化后再改 .env 是对不上的。
模型供应商里加 Ollama 一直报连接失败。 按顺序查:Ollama 那边是否监听在 0.0.0.0:11434(默认只听本机回环,服务化部署要设 OLLAMA_HOST);Dify 容器里能否解析并连通你填的地址,本机部署优先用 host.docker.internal(Linux 上需在 compose 里给 api/worker 补 extra_hosts: ["host.docker.internal:host-gateway"],官方 compose 已内置,改过网络配置的要自查);最后才是模型名拼写,名字必须与 ollama list 输出一字不差。
工作流运行时在 LLM 节点报错或超时。 先单独在供应商页面测试这个模型通不通,再看输入长度:长文章很容易顶爆模型的上下文窗口,表现就是报错或输出截断。解法是换长上下文模型、或在 LLM 节点前加一个代码/模板节点先做截断。另外云端 API 的速率限制也会以超时形式出现,批量跑时把并发降下来。
模板转换节点输出为空或变量没替换。 九成是变量绑定问题:模板里的 arg1、arg2 必须在节点配置区逐个绑定到上游节点的输出,绑定后模板里用 {{ arg1 }} 引用;如果直接在模板里写工作流变量语法,版本不同语法不同,容易 silently 输出空字符串。改完先用「运行」里的单步调试确认本节点输出,再往下查。
知识库上传文档一直卡在索引中。 索引任务由 worker 执行,先看 docker compose logs -f worker 有没有报错:嵌入模型没配或连不上是最常见原因;大文件解析吃内存被 OOM kill 也常见,加内存或拆小文件。向量库容器异常时整个索引链会一起卡住,docker compose ps 先把不健康的容器找出来。
发布成 WebApp 后别人打不开。 检查 .env 里的几个 URL 配置(CONSOLE_API_URL、SERVICE_API_URL、APP_WEB_URL):同机部署通常留空走相对路径没问题,但一旦你改过域名或加了 HTTPS 反代,这几处不改对,页面能开、接口全挂。改完 .env 要 docker compose up -d 重建容器才生效,只 restart 不读新环境变量。
小结
Dify 的定位是「把提示词变成可交付的应用」:工作流负责把处理步骤钉死,知识库负责给模型喂私有资料,发布环节负责把能力交出去。本篇走完了一条完整链路——自托管部署、云端与本地双模型接入、四种形态的取舍、一个能真跑起来的摘要工作流、API 发布与备份。照着这个骨架,把 LLM 节点换成翻译、分类、信息抽取,开始节点换成你的业务输入,就是一个个新应用。这也是本系列后面几篇会反复用到的基本功:先把流程拆对,模型只是其中一个节点。