简介面向希望快速搭建AI应用开发环境的开发者、运维人员及对大模型落地感兴趣的进阶学习者Dify教程PDF以Dify为主线系统讲解本地部署全流程。内容覆盖Docker命令行安装与DockerDesktop两种方式包含镜像加速配置、docker-compose启动、Windows环境下的访问初始化等具体操作并说明安装完成后的管理员设置与登录步骤同时介绍借助Ollama在本地部署deepseek-r1:1.5b等大模型方法详细演示如何通过修改.env文件、添加模型供应商与系统模型设置让Dify成功关联Ollama最终创建智能聊天机器人并搭建本地知识库从环境准备到知识库落地的完整链路均有涉及。资源为单个PDF文档约5.28MB内容结构完整含界面操作说明与配置参数提示便于对照练习。已有791人学习下载适合具备一定命令行基础、希望在自己电脑上完整跑通Dify加本地大模型链路的读者使用。1. 从 Dify 教程 PDF 到真正跑起来先给这套平台一个坐标翻了半天 Dify 教程 PDF不如先回答一个问题Dify 到底替你省掉了什么。做 LLM 应用时Prompt 拼接、模型 Key 管理、知识库分段与召回、Agent 工具调用每一样都能写成一套独立代码Dify 社区版把这套链路做成可视化平台用工作流把节点串起来用知识库流水线承接文档数据。这篇 Dify 教程不按界面截图走而是从选型逻辑、容器拓扑讲到镜像拉取失败与检索调参。适合正在做内部知识库问答、想把工作流交给非开发人员维护的团队也适合评估要不要在自己环境里搭一套 Dify 平台。2. Dify 的架构定位工作流、知识库与模型网关怎么粘在一起2.1 先回答「Dify 到底是什么」一个带界面的 LLM 应用编排系统企业里做 AI 应用最大的浪费是每个项目都把模型调用、Prompt 拼接、向量库、日志和权限重做一遍。Dify 社区版把这条链路固化成平台能力模型网关统一管理多个供应商的 Key工作流可视化编排推理逻辑知识库流水线负责文档接入、分段、向量化和检索Agent 节点能按需调用工具搭一个多步决策的智能体应用也只需要拖拽几条边。第一次登录控制台时你面对的是「创建应用」而不是「初始化项目」这是它和 LangChain 这类开发框架最明显的差别。先理清应用类型。Dify 里的应用分成聊天助手、Agent、文本生成、工作流四大类。聊天助手按编排好的节点顺序执行适合客服问答、知识库问答这类结果稳定的场景Agent 则多了「推理-行动」循环每一轮可以决定调哪个工具、搜什么资料适合需要多步决策的任务文本生成是面向单次生成的简化形态工作流是前面三者的底层底座新建任意应用后都能切到编排页签看到一张节点图。这里要纠正一个容易走偏的点不是所有场景都要用 Agent。内部知识库问答、工单分类、报表生成这类流程固定的任务用聊天助手或工作流就够了。Agent 的推理开销和不确定性都更高上线前还要处理工具调用失败的重试团队初期尽量少引入。等流程跑通、确实需要模型自主决策时再逐步把 Agent 节点加进工作流。2.2 容器拓扑api、worker、web 与中间件各管一段Dify 不是单体服务docker compose 拉起的是一个分布式拓扑。api 容器负责接收 HTTP 请求、业务逻辑和鉴权worker 通过 Celery 消费异步任务知识库文档处理、Embedding 生成这些耗时操作都在 worker 里跑web 是前端静态资源nginx 做反向代理。数据层有三个角色PostgreSQL 存业务数据Redis 存缓存和任务队列向量数据库默认 Weaviate存文档向量。理解这个拓扑排错才能有的放矢。上传 PDF 后知识库里迟迟没有内容看 api 日志通常查不到问题要去看 worker 日志因为分段和向量化在队列里消费。反之页面能打开但接口报 401问题多半在模型 Key 或登录态和容器没关系。先判断故障层再动手翻日志。# 查看编排里所有服务的运行状态重点看 STATUS 是否 healthy docker compose ps这条命令在部署和排错时都会反复用到。STATUS 列出现 restarting 时用 docker compose logs 服务名 跟进出现 unhealthy 则优先检查依赖它的中间件是否就绪比如 api 起不来常常是数据库还没初始化完。2.3 选择 Dify 而不是自己拼的边界在哪里用 Dify 之前先确认边界。它替你做掉的是通用链路但要清楚两件事一是复杂业务系统集成要靠 API 或自定义工具节点别把所有业务逻辑塞进工作流图里二是高频、低延迟、强一致性的交易场景更适合把编排结果沉淀为独立服务Dify 做原型验证和运营后台更合适。给团队选型时可以按这几个维度过一遍对比项Dify 社区版自研 LLM 编排LangFlow上手成本低控制台可视化高需自行选型组合中等流程图式拖拽知识库能力内置分段清洗与检索需自行接向量库依赖组件拼装多租户工作区级隔离自行设计权限表需二次开发生产运维社区版自行维护全链路自己维护相对简化这个表格给决策用。自研路线最亏的不是编码时间而是为知识库分段、召回调优、Key 管理这些通用问题反复造轮子。LangFlow 更贴近「流程图式原型」生产级能力不如 Dify 完整。所以实际部署中Dify 通常被当作企业内部的 LLM 应用底座上面接多个业务线下面统一管模型和知识库。3. Dify 本地部署实战用 Docker Compose 跑通最小安装3.1 最小可用的部署步骤与启动前检查拿到社区版发布包或者代码仓库后进 docker 编排目录其余工作交给 Compose。生产环境建议固定到具体版本 tag而不是用 latest避免中间件升级带来行为变化。到这一步的代码很少关键在配置理解。# 进入 compose 编排目录发布包或仓库已存在于本机 cd dify/docker # 从示例文件生成环境变量后续端口和存储都靠它 cp .env.example .env # 拉起全部服务首次会把 api、worker、web、db、redis、weaviate 都拉下来 docker compose up -d # 查看服务状态等所有容器处于 running/healthy 后再初始化 docker compose ps逻辑说明cp .env.example .env 是部署里最关键的一步端口映射、存储路径、中间件连接串都集中在这个文件。docker compose up -d 会按依赖关系启动全部容器ps 用于确认状态看到 unhealthy 就继续看日志。初始化完成后浏览器访问 http://服务器IP:端口/install 设置管理员邮箱和密码。登录不进去时先查宿主机防火墙和 nginx 容器端口映射而不是怀疑 Dify 本身。参数说明.env 里最常改的是 EXPOSE_NGINX_PORT默认 80本机已有 Nginx 或 IIS 时改成 18080 这类空闲端口。POSTGRES 和 REDIS 连接串保持默认即可容器间通过 Docker 网络互访手动改成 127.0.0.1 反而会让 api 连不上库。SANDBOX 相关变量控制代码执行沙箱不需要代码解释器时保持默认。3.2 Docker Desktop 环境的两个注意点在 Windows 或 macOS 上通过 Docker Desktop 跑 Dify 很常见但最容易栽在资源上。这套拓扑有八九个容器默认 2 核 4G 内存跑不动api 和 worker 会频繁 OOM。建议先在 Docker Desktop 的 Resources 里把内存调到 8GB 以上CPU 至少 4 核WSL2 后端还要给磁盘留出 10GB 以上余量镜像、日志、向量数据加起来并不小。第二个注意点是端口冲突。Windows 上 80 端口常被 IIS 或其它进程占用改法是修改 .env 中的 EXPOSE_NGINX_PORT然后重新执行 docker compose up -dnginx 会按新映射启动。不要在 Docker Desktop 界面里手动改容器端口容器重建后改动会丢失。遇到端口改了还是被占用用 netstat -ano | findstr :端口 看进程号再处理。3.3 镜像拉取失败的常见原因与处理顺序首次 docker compose up -d 卡在拉取阶段很常见原因通常分四类tag 不存在、网络波动或仓库限流、磁盘空间不足、compose 文件语法问题。处理顺序固定一下不要上来就改配置。# 先针对具体服务拉镜像减少干扰因素 docker compose pull api # 确认拉取目标后单独验证这条链路是否能走通 docker compose config /dev/null echo compose ok第一条命令把 api 服务的镜像单独拉到本地如果还是失败看错误类型。manifest unknown 表示镜像 tag 对不上去 release 页面核对 compose 文件里的镜像 tag 与版本timeout 或 429 表示网络层问题先重试几次再考虑给 Docker 配置 registry mirror 或换仓库源no space left on device 则是磁盘写满清理旧镜像和构建缓存。compose config 用来校验编排文件语法语法错误时 docker compose up 会在启动前就报错和镜像无关先排除这条路径。社区版发布节奏较快1.10 到 1.17 这一代版本之间compose 文件结构有过调整。升级时如果 git pull 后直接 up -d 报 manifest unknown多半是本地 .env 里的变量和新的 compose 文件不兼容。这时先备份 .env再基于新的 .env.example 重新生成再逐项迁移自定义项。3.4 .env 里值得先确认的 5 个参数变量默认值参数说明EXPOSE_NGINX_PORT80对外访问端口宿主机被占用时优先改这里EXPOSE_NGINX_SSL_PORT443HTTPS 映射不需要外网 HTTPS 时可保持默认DB_USERNAME / DB_PASSWORDdify / dify生产环境必须改本地体验可不改VECTOR_STOREweaviate向量库类型切换前端到 Qdrant 或 pgvector 后再改MODEapiapi 和 worker 共用镜像MODE 区分进程角色不建议动提示改动 .env 后docker compose up -d 不会自动重建所有容器。稳妥做法是 docker compose down 后再 up -d确保 api 和 worker 都用新配置启动。4. Dify 知识库流水线与工作流案例把 PDF 里的内容变成能问答的资产4.1 从文档到可检索知识的四段式接入一上来导入一堆 PDF然后被「知识库检索效果差」反复折磨是新手最常见的路径。Dify 的知识库是一条完整流水线上传文档、分段、清洗、向量化入库。界面里的「创建知识库」只是入口真正决定检索质量的是分段和 Embedding 配置。分段设置上Dify 支持自动分段和自定义分段。自动分段按语义边界切分适合排版规整的 PDFMarkdown、HTML 这类本身有章节结构的文档自定义分隔符更可控。最关键的参数是最大分段长度它决定每个 chunk 的 token 上限。工程经验是 200-500 token太小召回碎片多答案容易被切断太大容易把无关信息带进上下文稀释注意力。向量化之前清洗规则里可以去掉页眉页脚、处理无效换行这些操作在界面的清洗环节完成不需要写脚本。4.2 知识库检索效果差的诊断清单检索效果差先别急着换 Embedding 模型。Dify 的检索参数集中在知识库的「检索设置」里逐项排查才是高效路径。参数作用调优方向检索模式向量检索 / 全文检索 / 混合检索专有名词多时开混合Top K返回给 LLM 的候选块数量常见 3-5取值过大会稀释 PromptScore 阈值低于阈值的块不返回0.5 打底效果好再收紧Rerank对召回结果二次排序召回结果杂时打开需要额外模型分段大小每个 chunk 的 token 上限答案分散时长文档调大片段问答调小逐项调优的验证方式很简单在知识库的「召回测试」里输入问题看返回的 hit 是不是你期望的段落。这一步能定位故障层——hit 不相关问题在分段和检索模式不在阈值hit 相关但 LLM 答错问题在提示词回去改 Prompt 模板。混合检索对含人名、型号、缩写等专有术语的知识库尤其重要向量检索按语义找全文检索按字面找两者结合能覆盖语义接近但字面完全不同的坑。4.3 最小可运行的工作流案例知识库问答在 Dify 工作流里搭一个知识库问答最少需要四个节点开始、知识检索、LLM、直接回复。常见做法是新建「工作流」应用把开始节点的用户问题作为知识检索的查询输入知识检索节点选中目标知识库LLM 节点在提示词里引用检索结果直接回复节点把答案返回。关键在变量引用。知识检索节点输出的上下文变量一般叫 contextLLM 节点提示词这样写请基于以下资料回答问题不要使用资料外的知识 {{#context#}} 问题{{#sys.query#}}逻辑说明{{#context#}} 是知识检索节点传给 LLM 的结构化上下文一般按得分降序拼接 Top K 个命中的分段sys.query 是开始节点接收到的用户原问题。这样设计的好处是把「检索」和「生成」解耦上下文由知识库节点决定模型只负责在前置资料里组织答案。业务上要加「无答案兜底」时在知识检索后加条件分支判断 context 是否为空再走不同回复路径这是 Dify 工作流案例里最常见的扩展形态。4.4 外部结构化数据如何导入知识库知识库不只能上传 PDF 和 Word还支持通过 API 导入外部结构化数据。常见做法是调用知识库的文档创建接口用 form-data 上传 CSV 或 JSON指定分段策略接口返回文档 ID 后先查文档状态等 worker 异步完成向量化再用于检索。# 用知识库ID和API Key创建文档file 指向本地 CSV 文件 curl -X POST \ -H Authorization: Bearer ${DIFY_API_KEY} \ -F data${DATASET_ID} \ -F file/tmp/issues.csv \ http://你的Dify域名/v1/datasets/{dataset_id}/document/create逻辑说明Authorization 请求头里的 Bearer Token 在控制台的「API 访问」菜单生成权限按应用隔离data 参数是知识库 ID文件和知识库的对应关系在提交时确定。接口返回的是文档状态而不是向量结果因为分段和向量化发生在 worker 队列里。轮询文档状态接口状态变为 completed 后再做召回测试能确认数据真正进了向量库。参数说明file 支持 CSV、Markdown、PDF 等格式上传后默认沿用知识库的分段设置生产环境建议用脚本把业务表导出为 CSV 再批量调用导入频率高时注意控制并发避免压垮 worker。具体接口路径以你部署版本的 API 文档为准不同小版本对数据集接口有兼容性调整。5. Dify 上线前的最后一课多租户隔离、升级备份与一条验证命令5.1 社区版多租户先理解工作区边界社区版从 1.10 开始强调多租户能力但多租户不必理解成复杂的 SaaS 隔离体系。Dify 里天然的隔离单元是工作区管理员后台创建多个工作区每个工作区拥有独立的成员、知识库、应用和 API Key。业务线之间默认互不可见这比自己在应用层拼权限来得省事。多租户的配置入口在系统管理后台的成员与工作区管理里。常见做法是给每个业务线建一个独立工作区把对应成员拉进去知识库和应用各自维护模型配置仍在统一设置里管理Key 不随工作区下发。这样团队统一管账各业务线不互相污染数据。5.2 升级流程备份、拉新、重建和回滚Windows 上做 Dify 在线升级思路和 Linux 一致先停服务再备份 volumes最后拉新镜像重建。备份是唯一的后悔药建议升级前手动做一次。# 停服前先整体备份数据目录确认 volumes 目录存在再打包 docker compose down tar czf /backup/dify-volumes-$(date %Y%m%d).tar.gz ./volumes # 拉取新镜像并重建容器 docker compose pull docker compose up -d逻辑说明down 会停止并移除容器但 volumes 目录里的数据不会丢tar 把整个目录打包回滚时解压还原再重启即可。pull 只更新镜像不碰数据数据库结构变更会在容器启动时自动迁移。备份后第一件事是拉新镜像镜像 index 拿到后再重建能避免一边启动一边拉镜像导致的中断。5.3 一条验证命令走完部署检查部署完成后直接用对话功能验证不够快建议先做三层链路检查模型可访问、知识库可召回、api 无报错。# 校验后端健康检查接口返回 200 说明 api 与中间件链路正常 curl -s -o /dev/null -w %{http_code} http://localhost/health再配合容器日志确认运行时状态docker compose logs --tail50 api日志里出现模型鉴权错误401、403时去控制台检查模型 Key 和模型名是否匹配知识库检索结果为空时回知识库做召回测试确认 worker 完成了向量化容器反复重启时先看退出码内存不足和 .env 变量不一致是最常见原因。升级后先新建一个聊天助手输入任意问题验证模型通道再打开知识库问答做端到端验证全通了再对外开放。本文还有配套的精品资源点击获取