2026/9/19 22:14:30
FEATURED · 精选文章 
如果你手里有一台 Windows 电脑又想搭一套属于自己的 AI 知识库和智能体系统我强烈建议你把 Dify 跑起来试试。Dify 是目前社区里非常活跃的开源 LLM 应用开发平台把 RAG 知识库、工作流编排、智能体Agent这些原本很重的工程能力做成了可视化配置。我在 Windows 上从零部署过很多次踩过不少坑这篇教程就是按照“保姆级”标准整理的尽量让你照着敲命令就能跑通。整个栈会基于 Docker Desktop 本地 Ollama 大模型不依赖商业 API数据全部留在自己机器里既能用来学习也能接真实业务。先说清楚这篇教程的目标在一台 Windows 10/11 机器上完整跑起 Dify 社区版接上本地大模型录入自己的文档资料建成一个可检索、可问答的 RAG 知识库再把它包装成一个能自动调用工具、按流程处理的智能体应用。适合同样在折腾本地部署的朋友尤其是想搞清楚“知识库到底怎么落地”“智能体开发该从哪里下手”的人。1. 项目综述Dify 是什么为什么选择本地部署1.1 Dify 到底解决了什么问题先聊一个现实问题如果你想自己做一个带知识库的 AI 产品传统路径有多麻烦你得准备一个向量数据库设计文本分块和 Embedding 逻辑写一套大模型的 Prompt 管理还要做用户会话记忆、权限控制、前端聊天框……这些加起来哪怕只是 MVP也得一个后端加一个前端忙活一两周。而 Dify 把这些环节全部整合成了平台能力你在网页上点点点就能完成。更关键的是Dify 把“普通聊天应用”和“智能化应用”的边界划得很清楚。聊天应用只负责模型对话但智能体应用能调用工具、检索知识库、执行工作流。它内置了 RAG 知识库的完整管线文档上传、自动分段、向量化索引、召回测试全部有可视化界面。这对非算法背景的人特别友好你不需要自己写向量检索代码只需要理解基本概念。我用它做过的场景包括内部文档问答、产品客服助手、竞品信息分析还有一个对内部同事开放的“销售素材助手”。这些需求如果每个都单独开发维护成本会高得离谱但统一收敛到 Dify 上之后一个平台就能承载多个应用。1.2 为什么我推荐 Windows Docker Desktop 这套组合很多教程默认大家用的是 Linux 服务器或 Mac对 Windows 用户很不友好。但实际上 Windows 跑 Dify 完全没问题前提是选对方案。第一种方案是直接在 Windows 上装 Docker Desktop开启 WSL2 后端整个 Dify 跑在轻量 Linux 虚拟机里。第二种方案是手动装一个 WSL2 发行版在发行版内部装 Docker Engine再把 Dify 放进 Linux 环境。第三种是在 Hyper-V 虚拟机里装 Linux 再装 Dify。我实际比较下来日常开发和学习最推荐的是第一种Docker Desktop WSL2。理由很简单。Docker Desktop 对 WSL2 的集成已经非常成熟你在 Windows 终端里敲 docker 命令底层容器运行在 WSL2两边文件互通、端口映射都自动处理。这样既不用维护独立虚拟机又能享受 Linux 容器生态。Dify 官方提供的 docker compose 编排文件也是为 Linux 容器设计的所以这套组合兼容性最好。很多人担心性能损耗其实 WSL2 是轻量级虚拟机内存和 CPU 调度效率很高。唯一的问题是吃内存我后面会专门讲硬件要求。如果你的机器是 8G 内存建议就别折腾了加到 16G 体验会好很多。1.3 整个部署会涉及哪些组件在动手之前先对整个系统的组件有一个整体印象这样后面出问题也知道去查哪里。完整架构大致是这样组件作用默认暴露端口Docker Desktop容器运行环境提供 Linux 容器能力无Dify API后端服务负责应用逻辑、知识库、Agent 执行5001内部Dify Web前端控制台可视化编排界面3000内部Nginx反向代理入口统一到 80 端口80PostgreSQL存储用户、应用、会话等元数据5432内部Redis缓存、异步任务队列6379内部Weaviate向量数据库存储知识库向量索引8080内部Ollama本地大模型推理服务运行在宿主机11434模型对话模型 Embedding 模型无另外还需要一个嵌入Embedding模型负责把文档切出来的片段转成向量。这个后面配置知识库时会用到我建议在 Ollama 里提前拉好。2. 环境准备先把本地地基打好2.1 Docker Desktop 安装与 WSL2 配置安装 Docker Desktop 本身不复杂但前期准备工作容易忽略。首先是确认 Windows 版本。Win10 2004 以上或 Win11 都支持 WSL2。打开 PowerShell执行wsl --status如果提示你还没有安装发行版或者提示 WSL 内核版本太旧先执行wsl --update这一步会把 WSL 内核升级到最新。然后确保 Windows 功能里“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两项已开启。如果你以前没开过在“启用或关闭 Windows 功能”里勾选后需要重启。接着去 Docker 官网下载 Docker Desktop for Windows 安装包。安装过程中会询问是否使用 WSL2 后端选是。装完后打开 Docker Desktop进入 Settings - Resources - WSL Integration把“Enable integration with my default WSL distro”打开。如果你有多个发行版做好对应勾选。注意很多人在这里会栽跟头装完 Docker Desktop终端里 docker 命令却报“无法连接到 Docker 守护进程”。这通常就是 Docker Desktop 还没启动或者 WSL2 后端没启动成功。打开桌面上的 Docker Desktop 图标等它显示 running 再试。验证环境docker version docker compose version只要 Client 和 Server 都有版本号就说明 Docker 环境正常。Server 部分出现才是真的有了容器运行能力。2.2 内存、CPU、磁盘到底要多大这块我先给一个实际建议表再解释为什么。配置项最低要求推荐配置CPU4 核8 核内存12 GB16 GB 以上磁盘30 GB 可用50 GB 以上 SSD操作系统Windows 10 2004Windows 11网络能正常访问 Docker Hub稳定外网环境内存是最大瓶颈。Dify 全部容器起来后PostgreSQL、Redis、Weaviate、API、Web、Nginx、Sandbox、Plugin Daemon空闲状态下大约会占 3 到 4 GB 内存。Ollama 加载一个 7B 参数模型量化为 Q4 大概需要 4 到 5 GB 内存Embedding 模型小一些几百 MB。如果你的模型跑在 CPU 上还会更多。所以 16G 内存是最舒服的基线8G 会非常紧张容器可能频繁被杀。磁盘方面Dify 镜像本身大概 3 到 5 GB模型文件另算。7B 模型 Q4 量化版大约 4 到 5 GBEmbedding 模型几百 MB。再加上日志、数据库、上传文档20 到 30 GB 是少不了的。建议给 Docker 分配至少 30 GB 空间。2.3 用 Ollama 准备本地大模型Ollama 是目前在本地跑大模型最省事的工具一条命令就能拉模型、起服务。下载 Ollama for Windows 后直接安装。验证安装ollama --version然后拉取对话模型。我推荐新手先用 qwen2.5:7b中文能力强、资源消耗适中配合 Dify 做知识库问答完全够用。如果你的显存有 8 GB 以上也可以用 qwen2.5:14b效果更好但更吃资源。ollama pull qwen2.5:7b同时拉一个 Embedding 模型。Dify 知识库要把文本变向量这步必须用 Embedding 模型。推荐 nomic-embed-text 或者 bge-m3。ollama pull nomic-embed-text拉完后验证ollama run qwen2.5:7b能正常对话就说明模型没问题输入 /bye 退出。然后确认服务端口ollama serveOllama 默认监听 11434 端口。这里有个小经验如果 Dify 容器总连不上宿主机 Ollama很多时候是因为 Ollama 默认只绑定了 127.0.0.1。虽然 Dify 容器通过 host.docker.internal 访问宿主机理论上没问题但保险起见可以把设置环境变量 OLLAMA_HOST0.0.0.0:11434 后重启 Ollama确保容器能访问。现在你的环境里已经有了Docker 容器能力、本地对话模型、本地 Embedding 模型。接下来正式部署 Dify。3. 正式部署把 Dify 容器编排跑起来3.1 获取 Dify 源码Dify 的部署不需要自己做 Dockerfile官方已经把整套编排文件放在了 GitHub 仓库里。选择你喜欢的目录打开 PowerShell 执行git clone https://github.com/langgenius/dify.git如果你没有安装 Git也可以直接访问 Dify 官方仓库的 Releases 页面下载最新 release 的 zip 包解压到本地。我建议用 git clone后面升级方便。Dify 更新很频繁当前社区版已经迭代到 1.17.x 版本比早期版本在知识库解析、工作流节点、插件生态上都完善了很多具体改动可以看官方 release notes。部署时建议切换到稳定 tag比如cd dify git checkout 1.17.1然后进入 docker 目录这个目录下有 docker-compose.yaml 和 .env.example 文件。cd docker3.2 配置 .env 并启动复制一份 .env 配置cp .env.example .env默认配置对于本地部署来说基本够用不需要改任何内容。Dify 会启动这些服务nginx、api、worker、web、postgres、redis、weaviate、sandbox、plugin_daemon。首次启动前建议手动拉一遍镜像避免 compose 启动时超时docker compose pull这一步取决于你的网络速度Dify 相关镜像体量不小耐心等。如果中途失败重新执行docker compose pullDocker 会从断点继续。镜像拉取完毕启动docker compose up -d等待几秒后检查状态docker compose ps我整理了一个状态速查表服务期望状态说明apirunning / healthy后端接口workerrunning异步任务队列webrunning前端控制台nginxrunning反向代理统一入口postgresrunning / healthy主数据库redisrunning / healthy缓存weaviaterunning / healthy向量库sandboxrunning代码执行沙箱plugin_daemonrunning插件守护进程如果出现 Exited (0) 或者 Restarting不要慌先看日志docker compose logs -f api第一次启动时API 可能需要等数据库准备好会有几秒到几十秒的等待看到数据库连接成功后就好了。只要容器没有反复重启过一会儿就会进入 healthy 状态。3.3 初始化管理员并接入 Ollama容器都起来后浏览器访问http://localhost/install这里会让你设置管理员邮箱和密码。填完点设置然后自动进入登录页用刚设置的管理员账号登录。进入 Dify 控制台后第一件事是配置模型供应商。点击右上角头像 - 设置 - 模型供应商找到 Ollama。这里有一个必须记住的关键点Docker 容器内部访问宿主机的服务不能写 localhost 或 127.0.0.1而要写 host.docker.internal。所以 Dify 的 Ollama Base URL 必须是 http://host.docker.internal:11434。配置方式模型类型选 LLM模型名称填 qwen2.5:7bBase URL 填 http://host.docker.internal:11434点测试显示连接成功即可保存。再添加一个 Embedding 类模型模型名称填 nomic-embed-textBase URL 同样填 http://host.docker.internal:11434。然后回到“设置 - 模型供应商”确认 Ollama 下两个模型状态都是已添加。没有这一步后面知识库无法向量化应用也无法对话。到这里Dify 核心部署其实已经完成。但为了后面知识库不踩坑建议先创建一个最简单的聊天应用选择 Ollama 的 qwen2.5:7b发一句话测试确保模型链路通畅。4. 搭建知识库从文档到可问答的 RAG 全流程4.1 RAG 是什么以及它的工作流程知识库问答不是把整本文档塞给大模型大模型也不能一次读那么多字。RAG检索增强生成的思路是先检索、后生成像是你查资料时先从书架里翻出最相关的那几页再基于这些内容回答问题。Dify 帮你把这条链路串好了文档上传 - 文本分段 - 向量化 - 存储 - 检索 - 拼装 Prompt - 模型回答。其中两个环节对最终效果影响最大。第一个是分段。你会把长文档切成一个个小片段切片太小会导致上下文不完整切片太大会让检索不够精准还浪费模型上下文。第二个是 Embedding 模型。它把文本变成了高维向量片段的语义越准相似度检索就越准。理解这个流程后你就知道为什么有些知识库“答非所问”——大多数问题不是模型不行而是分段和检索的细节没调好。4.2 创建知识库并选择索引方式在 Dify 顶部导航栏点“知识库”然后“创建知识库”填写名称和描述。这里有一个关键选项索引方式。Dify 提供两种高质量模式使用 Embedding 模型对每个分段做向量化检索时计算语义相似度效果最好我们本地部署肯定选这个。经济模式仅做关键词索引不耗模型资源但语义理解基本没有不推荐。选择高质量模式后会让你选 Embedding 模型。这里就选刚才配置的 Ollama 下的 nomic-embed-text。首次入库时会有向量化过程文档多的话需要一些时间。4.3 上传文档与分段参数调优创建好知识库后进入知识库详情页点击“添加文档”支持上传 txt、md、pdf、docx 等格式。选择文件后Dify 会自动解析内容然后进入分段设置界面。Dify 默认的分段规则通常已经不错但你需要理解两个参数分段长度Chunk Size每个片段包含多少 token。默认约 500 token。这个值偏小适合问答类文档偏大适合长上下文分析。重叠长度Overlap相邻片段之间重叠多少 token。默认约 80 token。重叠的目的是避免一个完整语义被拦腰切断比如一个段落正好被切到中间重叠部分能保留前后线索。我自己的实操建议是如果你的文档偏说明文、操作步骤分段长度可以设小一点比如 300 到 500如果是整篇合同、制度类长文本可以设到 800 左右。如果发现召回时经常漏掉关键内容先调大 overlap再考虑调分类长度。上传完成后等待索引进度结束。Dify 会在后台调用 Ollama 的 nomic-embed-text 逐段向量化。文档少的话一分钟内完成多的话需要等待。4.4 召回测试验证检索质量索引完成后知识库页面里有个“召回测试”功能这是我很推荐你先用起来的功能。输入一个问题它会展示从知识库里检索出来的相关分段以及相似度分数。用一条实际问题测一下比如“我们公司的报销流程是什么”。如果返回的片段里确实包含报销相关步骤说明检索链路正常如果返回一堆不相关的内容多半是分段设置或者 Embedding 模型的问题。实测下来效果不理想时按优先级排查检查文档原始排版。表格、扫描 PDF、乱码文档都会严重影响解析质量尽量用清晰的文本或 Word 文档。调整分段长度和重叠长度重新索引。换更强力的 Embedding 模型比如将 nomic-embed-text 换成 bge-m3。确认召回测试用的是高质量索引模式。这一套组合走下来你的知识库就具备真正可用的问答能力了。5. 搭建智能体把知识库变成能干活的助手5.1 智能体应用到底比普通对话强在哪里普通聊天应用只能基于模型自身的知识回答问题更准确说是“你问我答模型现编”。智能体应用不同它能自己判断“我需不需要工具”“需不需要从知识库查资料”“需不需要把问题拆分几步执行”。在 Dify 里“智能体”通常包含一个核心大模型、一套系统 Prompt、若干工具、知识库工具、会话记忆。你可以把它理解成一个有手有脚、会查资料再说话的员工。系统 Prompt 负责告诉它身份和规则模型负责推理工具负责执行动作知识库负责提供事实依据。我建议不要把智能体想得太玄学它的本质就是“大模型 工具调用 工作流”。Dify 把工具调用协议全部封装好你只需要在界面上把能力挂上去。5.2 创建一个能调用知识库的 Agent 应用在 Dify 控制台点“工作室” - “创建空白应用”选择“Agent”应用类型。进入编排页面后主要配置四项核心模型选 Ollama 的 qwen2.5:7b。系统提示词写清楚助手身份和回答原则。比如“你是一个企业知识助手必须优先依据知识库内容回答如果知识库没有相关内容要明确说明不知道不能编造”。工具点击“添加工具”选择“知识库”把刚才建好的知识库挂上去。这样 Agent 在回答问题时会自动去知识库检索。记忆打开“对话记忆”让多轮对话能保持上下文。保存后点右上角“发布”然后进入“概览”页面点击 WebApp 链接打开对话窗口。这时候你可以连续提问比如先问“报销流程里需要哪些材料”再追问“流程中审批人是哪个部门”Agent 能结合上下文和知识库给出答案。这里有个经验如果你发现 Agent 不使用知识库而是自己“硬答”多半是系统提示词约束不够或者本地模型对工具调用格式理解不好。你可以把提示词改成强制要求先检索再回答同时在 Agent 配置里设置允许模型在必要时调用工具。5.3 使用工作流做更可控的知识库问答纯 Agent 模式的好处是自由但自由度高的代价是不可控。比如有些问题它可能不检索或者多次调工具浪费时间。如果你希望流程完全可控那就用 Chatflow 工作流。新建应用时选择“Chatflow”类型会进入画布式编排界面。一个最经典的知识库问答工作流只需要四个节点开始节点接收用户输入。知识检索节点指定知识库设置 TopK即抽取最相关的片段数量以及 Score 阈值。LLM 节点把用户问题和检索结果拼成 Prompt交给 qwen2.5:7b 生成回答。结束节点返回最终答案。连线方式开始 - 知识检索 - LLM - 结束。在 LLM 节点里把用户输入变量插入到 Prompt 中比如“请根据以下资料回答用户问题这里是 {{#context#}}”。这样回答就一定会使用知识检索结果不会“自由发挥”。我实际体验下来Chatflow 是 Dify 最值得花时间学的部分原因在于它的每个节点结果都可以独立调试。比如某次回答质量差你可以单独看知识检索节点召回的内容对不对再决定是改分段还是改 Prompt。5.4 发布为 WebApp 或 API应用编排完成后点击“发布”Dify 会生成一个可通过浏览器访问的 WebApp 链接。这个链接默认就是跑在你的 Windows 机器上的同一个局域网内其他人也能访问适合快速分享给同事试用。如果想嵌入到自己的系统Dify 也提供 API 接口。在应用“访问 API”页面创建 API 密钥然后调用接口。核心请求格式如下curl -X POST http://localhost/v1/chat-messages \ -H Authorization: Bearer app-xxxxxxxx \ -H Content-Type: application/json \ -d { inputs: {}, query: 报销流程是什么, response_mode: blocking, conversation_id: , user: local-user }拿到结果后再把 conversation_id 传回去即可保持多轮对话。这个 API 结构很规范接小程序、H5、管理后台都不难。6. 常见问题与排查技巧实录6.1 Dify 镜像拉取失败怎么办这个可以说是 Windows 用户最常遇到的一关。docker compose pull时经常出现某个镜像拉取超时或者拉取到一半失败。我的排查顺序是查看 Docker Desktop 是否正常运行磁盘空间是否充足。镜像存放需要空间如果 C 盘快满了Docker 会莫名失败。确认网络。不同的网络环境下首次拉取的表现差别很大换一个时间段重试通常能解决。执行docker compose pull --ignore-pull-failures跳过失败的服务单独拉取然后再docker compose up -d。看具体报错。如果提示“no matching manifest for windows/amd64”说明你的 Docker Desktop 没有切到 Linux 容器模式右下角 Docker 图标右键选择“Switch to Linux containers”。不要手动去改 .env 里的镜像仓库地址除非你很确定镜像是安全的。保持默认仓库地址最可靠。6.2 端口 80 被占用如果你本机已经跑着 IIS、Nginx、Apache 或其他 Web 服务启动 Dify 时会看到Bind for 0.0.0.0:80 failed: port is already allocated最简单的解决办法是修改 Dify 对外端口。进入 docker 目录下的 .env找到EXPOSE_NGINX_PORT80改成其他端口比如EXPOSE_NGINX_PORT8080保存后重新创建容器docker compose up -d之后访问地址变成 http://localhost:8080。注意 .env 和 docker-compose.yaml 里的变量是绑定关系改 .env 比改 yaml 更规范启动时 Dify 会自动读取变量。6.3 Dify 连不上 Ollama模型测试失败配置好 Ollama 后在 Dify 里测试模型经常看到“connection error”或“timeout”。绝大多数情况是 Base URL 填错了。记住在 Dify 容器内访问宿主机必须用 host.docker.internal。所以正确地址是http://host.docker.internal:11434确认这一步没问题后再检查宿主机curl http://localhost:11434如果宿主机都访问不了说明 Ollama 服务没起。然后确认模型存在ollama list如果里面没有 qwen2.5:7b 或 nomic-embed-text说明你拉模型失败或模型名拼写错误。模型名必须完全一致否则 Dify 会报模型不存在。如果宿主机能通但容器还是不通试着把 Ollama 的环境变量 OLLAMA_HOST 设为 0.0.0.0:11434 并重启 Ollama。Windows 防火墙检查一下确保 11434 端口没有被拦截尤其当你用的是非默认网络环境时。6.4 知识库检索总是不准怎么调检索不准不要一上来就怪模型先看知识库本身。我的经验是文档质量决定了检索上限。扫描件 PDF、表格转 Word、带复杂排版的文档Dify 解析后很可能变成乱序文本这时候不管怎么调参数都没用。处理方式是优先用干净的文本格式比如 Markdown 或 Word 里纯文本导出。如果必须是扫描版 PDF需要先做 OCR 转成可编辑文本一步都不能省。分段参数方面如果召回结果“太碎”适当增大分段长度如果“答非所问”增大 overlap 并检查 Embedding 模型是否切换成了 bge-m3 这类更强的模型。最后在召回测试里对比不同参数下的相似度分数选择效果最好的组合。6.5 回答速度慢CPU 推理卡顿本地部署大模型速度焦虑一定会有。7B 模型在 CPU 上生成速度大概只有每秒几个 token体验谈不上流畅。如果你有 NVIDIA 显卡确认 Ollama 是否检测到 GPU。执行ollama run qwen2.5:7b然后看启动日志是否出现类似“inference compute: GPU”的输出。如果显示 CPU说明显卡未生效升级显卡驱动后再试。没有 GPU 的情况下一个折中方案是换小模型比如 qwen2.5:3b速度明显提升知识库问答场景下效果也能接受。另一个方法是控制输入长度知识检索 TopK 不要调太大避免每次请求携带过长的检索结果。最后的经验分享整套环境跑通之后我最大的体会是本地部署 Dify 最大的价值不是省 API 钱而是让你能在一个不依赖外部服务的安全环境里把 RAG 和智能体的每个环节拆开看明白。调试时我能直接看知识库召回内容能改工作流节点能换不同模型对比效果这种自由度是云端平台很难给的。几个小建议送给你先把“知识库问答”这个最小闭环跑通再加工具和复杂工作流升级 Dify 前把 docker 目录下的 volumes 数据目录备份一份避免数据丢失没事多去点 Dify 的“召回测试”和“工作流调试”问题定位都靠这两个功能。如果你在 Windows 上遇到其他奇怪的部署问题不妨先从 Docker Desktop 状态和日志入手大部分问题都能在docker compose logs里找到答案。
Windows本地部署Dify，打造RAG知识库与智能体实战
如果你手里有一台 Windows 电脑又想搭一套属于自己的 AI 知识库和智能体系统我强烈建议你把 Dify 跑起来试试。Dify 是目前社区里非常活跃的开源 LLM 应用开发平台把 RAG 知识库、工作流编排、智能体Agent这些原本很重的工程能力做成了可视化配置。我在 Windows 上从零部署过很多次踩过不少坑这篇教程就是按照“保姆级”标准整理的尽量让你照着敲命令就能跑通。整个栈会基于 Docker Desktop 本地 Ollama 大模型不依赖商业 API数据全部留在自己机器里既能用来学习也能接真实业务。先说清楚这篇教程的目标在一台 Windows 10/11 机器上完整跑起 Dify 社区版接上本地大模型录入自己的文档资料建成一个可检索、可问答的 RAG 知识库再把它包装成一个能自动调用工具、按流程处理的智能体应用。适合同样在折腾本地部署的朋友尤其是想搞清楚“知识库到底怎么落地”“智能体开发该从哪里下手”的人。1. 项目综述Dify 是什么为什么选择本地部署1.1 Dify 到底解决了什么问题先聊一个现实问题如果你想自己做一个带知识库的 AI 产品传统路径有多麻烦你得准备一个向量数据库设计文本分块和 Embedding 逻辑写一套大模型的 Prompt 管理还要做用户会话记忆、权限控制、前端聊天框……这些加起来哪怕只是 MVP也得一个后端加一个前端忙活一两周。而 Dify 把这些环节全部整合成了平台能力你在网页上点点点就能完成。更关键的是Dify 把“普通聊天应用”和“智能化应用”的边界划得很清楚。聊天应用只负责模型对话但智能体应用能调用工具、检索知识库、执行工作流。它内置了 RAG 知识库的完整管线文档上传、自动分段、向量化索引、召回测试全部有可视化界面。这对非算法背景的人特别友好你不需要自己写向量检索代码只需要理解基本概念。我用它做过的场景包括内部文档问答、产品客服助手、竞品信息分析还有一个对内部同事开放的“销售素材助手”。这些需求如果每个都单独开发维护成本会高得离谱但统一收敛到 Dify 上之后一个平台就能承载多个应用。1.2 为什么我推荐 Windows Docker Desktop 这套组合很多教程默认大家用的是 Linux 服务器或 Mac对 Windows 用户很不友好。但实际上 Windows 跑 Dify 完全没问题前提是选对方案。第一种方案是直接在 Windows 上装 Docker Desktop开启 WSL2 后端整个 Dify 跑在轻量 Linux 虚拟机里。第二种方案是手动装一个 WSL2 发行版在发行版内部装 Docker Engine再把 Dify 放进 Linux 环境。第三种是在 Hyper-V 虚拟机里装 Linux 再装 Dify。我实际比较下来日常开发和学习最推荐的是第一种Docker Desktop WSL2。理由很简单。Docker Desktop 对 WSL2 的集成已经非常成熟你在 Windows 终端里敲 docker 命令底层容器运行在 WSL2两边文件互通、端口映射都自动处理。这样既不用维护独立虚拟机又能享受 Linux 容器生态。Dify 官方提供的 docker compose 编排文件也是为 Linux 容器设计的所以这套组合兼容性最好。很多人担心性能损耗其实 WSL2 是轻量级虚拟机内存和 CPU 调度效率很高。唯一的问题是吃内存我后面会专门讲硬件要求。如果你的机器是 8G 内存建议就别折腾了加到 16G 体验会好很多。1.3 整个部署会涉及哪些组件在动手之前先对整个系统的组件有一个整体印象这样后面出问题也知道去查哪里。完整架构大致是这样组件作用默认暴露端口Docker Desktop容器运行环境提供 Linux 容器能力无Dify API后端服务负责应用逻辑、知识库、Agent 执行5001内部Dify Web前端控制台可视化编排界面3000内部Nginx反向代理入口统一到 80 端口80PostgreSQL存储用户、应用、会话等元数据5432内部Redis缓存、异步任务队列6379内部Weaviate向量数据库存储知识库向量索引8080内部Ollama本地大模型推理服务运行在宿主机11434模型对话模型 Embedding 模型无另外还需要一个嵌入Embedding模型负责把文档切出来的片段转成向量。这个后面配置知识库时会用到我建议在 Ollama 里提前拉好。2. 环境准备先把本地地基打好2.1 Docker Desktop 安装与 WSL2 配置安装 Docker Desktop 本身不复杂但前期准备工作容易忽略。首先是确认 Windows 版本。Win10 2004 以上或 Win11 都支持 WSL2。打开 PowerShell执行wsl --status如果提示你还没有安装发行版或者提示 WSL 内核版本太旧先执行wsl --update这一步会把 WSL 内核升级到最新。然后确保 Windows 功能里“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两项已开启。如果你以前没开过在“启用或关闭 Windows 功能”里勾选后需要重启。接着去 Docker 官网下载 Docker Desktop for Windows 安装包。安装过程中会询问是否使用 WSL2 后端选是。装完后打开 Docker Desktop进入 Settings - Resources - WSL Integration把“Enable integration with my default WSL distro”打开。如果你有多个发行版做好对应勾选。注意很多人在这里会栽跟头装完 Docker Desktop终端里 docker 命令却报“无法连接到 Docker 守护进程”。这通常就是 Docker Desktop 还没启动或者 WSL2 后端没启动成功。打开桌面上的 Docker Desktop 图标等它显示 running 再试。验证环境docker version docker compose version只要 Client 和 Server 都有版本号就说明 Docker 环境正常。Server 部分出现才是真的有了容器运行能力。2.2 内存、CPU、磁盘到底要多大这块我先给一个实际建议表再解释为什么。配置项最低要求推荐配置CPU4 核8 核内存12 GB16 GB 以上磁盘30 GB 可用50 GB 以上 SSD操作系统Windows 10 2004Windows 11网络能正常访问 Docker Hub稳定外网环境内存是最大瓶颈。Dify 全部容器起来后PostgreSQL、Redis、Weaviate、API、Web、Nginx、Sandbox、Plugin Daemon空闲状态下大约会占 3 到 4 GB 内存。Ollama 加载一个 7B 参数模型量化为 Q4 大概需要 4 到 5 GB 内存Embedding 模型小一些几百 MB。如果你的模型跑在 CPU 上还会更多。所以 16G 内存是最舒服的基线8G 会非常紧张容器可能频繁被杀。磁盘方面Dify 镜像本身大概 3 到 5 GB模型文件另算。7B 模型 Q4 量化版大约 4 到 5 GBEmbedding 模型几百 MB。再加上日志、数据库、上传文档20 到 30 GB 是少不了的。建议给 Docker 分配至少 30 GB 空间。2.3 用 Ollama 准备本地大模型Ollama 是目前在本地跑大模型最省事的工具一条命令就能拉模型、起服务。下载 Ollama for Windows 后直接安装。验证安装ollama --version然后拉取对话模型。我推荐新手先用 qwen2.5:7b中文能力强、资源消耗适中配合 Dify 做知识库问答完全够用。如果你的显存有 8 GB 以上也可以用 qwen2.5:14b效果更好但更吃资源。ollama pull qwen2.5:7b同时拉一个 Embedding 模型。Dify 知识库要把文本变向量这步必须用 Embedding 模型。推荐 nomic-embed-text 或者 bge-m3。ollama pull nomic-embed-text拉完后验证ollama run qwen2.5:7b能正常对话就说明模型没问题输入 /bye 退出。然后确认服务端口ollama serveOllama 默认监听 11434 端口。这里有个小经验如果 Dify 容器总连不上宿主机 Ollama很多时候是因为 Ollama 默认只绑定了 127.0.0.1。虽然 Dify 容器通过 host.docker.internal 访问宿主机理论上没问题但保险起见可以把设置环境变量 OLLAMA_HOST0.0.0.0:11434 后重启 Ollama确保容器能访问。现在你的环境里已经有了Docker 容器能力、本地对话模型、本地 Embedding 模型。接下来正式部署 Dify。3. 正式部署把 Dify 容器编排跑起来3.1 获取 Dify 源码Dify 的部署不需要自己做 Dockerfile官方已经把整套编排文件放在了 GitHub 仓库里。选择你喜欢的目录打开 PowerShell 执行git clone https://github.com/langgenius/dify.git如果你没有安装 Git也可以直接访问 Dify 官方仓库的 Releases 页面下载最新 release 的 zip 包解压到本地。我建议用 git clone后面升级方便。Dify 更新很频繁当前社区版已经迭代到 1.17.x 版本比早期版本在知识库解析、工作流节点、插件生态上都完善了很多具体改动可以看官方 release notes。部署时建议切换到稳定 tag比如cd dify git checkout 1.17.1然后进入 docker 目录这个目录下有 docker-compose.yaml 和 .env.example 文件。cd docker3.2 配置 .env 并启动复制一份 .env 配置cp .env.example .env默认配置对于本地部署来说基本够用不需要改任何内容。Dify 会启动这些服务nginx、api、worker、web、postgres、redis、weaviate、sandbox、plugin_daemon。首次启动前建议手动拉一遍镜像避免 compose 启动时超时docker compose pull这一步取决于你的网络速度Dify 相关镜像体量不小耐心等。如果中途失败重新执行docker compose pullDocker 会从断点继续。镜像拉取完毕启动docker compose up -d等待几秒后检查状态docker compose ps我整理了一个状态速查表服务期望状态说明apirunning / healthy后端接口workerrunning异步任务队列webrunning前端控制台nginxrunning反向代理统一入口postgresrunning / healthy主数据库redisrunning / healthy缓存weaviaterunning / healthy向量库sandboxrunning代码执行沙箱plugin_daemonrunning插件守护进程如果出现 Exited (0) 或者 Restarting不要慌先看日志docker compose logs -f api第一次启动时API 可能需要等数据库准备好会有几秒到几十秒的等待看到数据库连接成功后就好了。只要容器没有反复重启过一会儿就会进入 healthy 状态。3.3 初始化管理员并接入 Ollama容器都起来后浏览器访问http://localhost/install这里会让你设置管理员邮箱和密码。填完点设置然后自动进入登录页用刚设置的管理员账号登录。进入 Dify 控制台后第一件事是配置模型供应商。点击右上角头像 - 设置 - 模型供应商找到 Ollama。这里有一个必须记住的关键点Docker 容器内部访问宿主机的服务不能写 localhost 或 127.0.0.1而要写 host.docker.internal。所以 Dify 的 Ollama Base URL 必须是 http://host.docker.internal:11434。配置方式模型类型选 LLM模型名称填 qwen2.5:7bBase URL 填 http://host.docker.internal:11434点测试显示连接成功即可保存。再添加一个 Embedding 类模型模型名称填 nomic-embed-textBase URL 同样填 http://host.docker.internal:11434。然后回到“设置 - 模型供应商”确认 Ollama 下两个模型状态都是已添加。没有这一步后面知识库无法向量化应用也无法对话。到这里Dify 核心部署其实已经完成。但为了后面知识库不踩坑建议先创建一个最简单的聊天应用选择 Ollama 的 qwen2.5:7b发一句话测试确保模型链路通畅。4. 搭建知识库从文档到可问答的 RAG 全流程4.1 RAG 是什么以及它的工作流程知识库问答不是把整本文档塞给大模型大模型也不能一次读那么多字。RAG检索增强生成的思路是先检索、后生成像是你查资料时先从书架里翻出最相关的那几页再基于这些内容回答问题。Dify 帮你把这条链路串好了文档上传 - 文本分段 - 向量化 - 存储 - 检索 - 拼装 Prompt - 模型回答。其中两个环节对最终效果影响最大。第一个是分段。你会把长文档切成一个个小片段切片太小会导致上下文不完整切片太大会让检索不够精准还浪费模型上下文。第二个是 Embedding 模型。它把文本变成了高维向量片段的语义越准相似度检索就越准。理解这个流程后你就知道为什么有些知识库“答非所问”——大多数问题不是模型不行而是分段和检索的细节没调好。4.2 创建知识库并选择索引方式在 Dify 顶部导航栏点“知识库”然后“创建知识库”填写名称和描述。这里有一个关键选项索引方式。Dify 提供两种高质量模式使用 Embedding 模型对每个分段做向量化检索时计算语义相似度效果最好我们本地部署肯定选这个。经济模式仅做关键词索引不耗模型资源但语义理解基本没有不推荐。选择高质量模式后会让你选 Embedding 模型。这里就选刚才配置的 Ollama 下的 nomic-embed-text。首次入库时会有向量化过程文档多的话需要一些时间。4.3 上传文档与分段参数调优创建好知识库后进入知识库详情页点击“添加文档”支持上传 txt、md、pdf、docx 等格式。选择文件后Dify 会自动解析内容然后进入分段设置界面。Dify 默认的分段规则通常已经不错但你需要理解两个参数分段长度Chunk Size每个片段包含多少 token。默认约 500 token。这个值偏小适合问答类文档偏大适合长上下文分析。重叠长度Overlap相邻片段之间重叠多少 token。默认约 80 token。重叠的目的是避免一个完整语义被拦腰切断比如一个段落正好被切到中间重叠部分能保留前后线索。我自己的实操建议是如果你的文档偏说明文、操作步骤分段长度可以设小一点比如 300 到 500如果是整篇合同、制度类长文本可以设到 800 左右。如果发现召回时经常漏掉关键内容先调大 overlap再考虑调分类长度。上传完成后等待索引进度结束。Dify 会在后台调用 Ollama 的 nomic-embed-text 逐段向量化。文档少的话一分钟内完成多的话需要等待。4.4 召回测试验证检索质量索引完成后知识库页面里有个“召回测试”功能这是我很推荐你先用起来的功能。输入一个问题它会展示从知识库里检索出来的相关分段以及相似度分数。用一条实际问题测一下比如“我们公司的报销流程是什么”。如果返回的片段里确实包含报销相关步骤说明检索链路正常如果返回一堆不相关的内容多半是分段设置或者 Embedding 模型的问题。实测下来效果不理想时按优先级排查检查文档原始排版。表格、扫描 PDF、乱码文档都会严重影响解析质量尽量用清晰的文本或 Word 文档。调整分段长度和重叠长度重新索引。换更强力的 Embedding 模型比如将 nomic-embed-text 换成 bge-m3。确认召回测试用的是高质量索引模式。这一套组合走下来你的知识库就具备真正可用的问答能力了。5. 搭建智能体把知识库变成能干活的助手5.1 智能体应用到底比普通对话强在哪里普通聊天应用只能基于模型自身的知识回答问题更准确说是“你问我答模型现编”。智能体应用不同它能自己判断“我需不需要工具”“需不需要从知识库查资料”“需不需要把问题拆分几步执行”。在 Dify 里“智能体”通常包含一个核心大模型、一套系统 Prompt、若干工具、知识库工具、会话记忆。你可以把它理解成一个有手有脚、会查资料再说话的员工。系统 Prompt 负责告诉它身份和规则模型负责推理工具负责执行动作知识库负责提供事实依据。我建议不要把智能体想得太玄学它的本质就是“大模型 工具调用 工作流”。Dify 把工具调用协议全部封装好你只需要在界面上把能力挂上去。5.2 创建一个能调用知识库的 Agent 应用在 Dify 控制台点“工作室” - “创建空白应用”选择“Agent”应用类型。进入编排页面后主要配置四项核心模型选 Ollama 的 qwen2.5:7b。系统提示词写清楚助手身份和回答原则。比如“你是一个企业知识助手必须优先依据知识库内容回答如果知识库没有相关内容要明确说明不知道不能编造”。工具点击“添加工具”选择“知识库”把刚才建好的知识库挂上去。这样 Agent 在回答问题时会自动去知识库检索。记忆打开“对话记忆”让多轮对话能保持上下文。保存后点右上角“发布”然后进入“概览”页面点击 WebApp 链接打开对话窗口。这时候你可以连续提问比如先问“报销流程里需要哪些材料”再追问“流程中审批人是哪个部门”Agent 能结合上下文和知识库给出答案。这里有个经验如果你发现 Agent 不使用知识库而是自己“硬答”多半是系统提示词约束不够或者本地模型对工具调用格式理解不好。你可以把提示词改成强制要求先检索再回答同时在 Agent 配置里设置允许模型在必要时调用工具。5.3 使用工作流做更可控的知识库问答纯 Agent 模式的好处是自由但自由度高的代价是不可控。比如有些问题它可能不检索或者多次调工具浪费时间。如果你希望流程完全可控那就用 Chatflow 工作流。新建应用时选择“Chatflow”类型会进入画布式编排界面。一个最经典的知识库问答工作流只需要四个节点开始节点接收用户输入。知识检索节点指定知识库设置 TopK即抽取最相关的片段数量以及 Score 阈值。LLM 节点把用户问题和检索结果拼成 Prompt交给 qwen2.5:7b 生成回答。结束节点返回最终答案。连线方式开始 - 知识检索 - LLM - 结束。在 LLM 节点里把用户输入变量插入到 Prompt 中比如“请根据以下资料回答用户问题这里是 {{#context#}}”。这样回答就一定会使用知识检索结果不会“自由发挥”。我实际体验下来Chatflow 是 Dify 最值得花时间学的部分原因在于它的每个节点结果都可以独立调试。比如某次回答质量差你可以单独看知识检索节点召回的内容对不对再决定是改分段还是改 Prompt。5.4 发布为 WebApp 或 API应用编排完成后点击“发布”Dify 会生成一个可通过浏览器访问的 WebApp 链接。这个链接默认就是跑在你的 Windows 机器上的同一个局域网内其他人也能访问适合快速分享给同事试用。如果想嵌入到自己的系统Dify 也提供 API 接口。在应用“访问 API”页面创建 API 密钥然后调用接口。核心请求格式如下curl -X POST http://localhost/v1/chat-messages \ -H Authorization: Bearer app-xxxxxxxx \ -H Content-Type: application/json \ -d { inputs: {}, query: 报销流程是什么, response_mode: blocking, conversation_id: , user: local-user }拿到结果后再把 conversation_id 传回去即可保持多轮对话。这个 API 结构很规范接小程序、H5、管理后台都不难。6. 常见问题与排查技巧实录6.1 Dify 镜像拉取失败怎么办这个可以说是 Windows 用户最常遇到的一关。docker compose pull时经常出现某个镜像拉取超时或者拉取到一半失败。我的排查顺序是查看 Docker Desktop 是否正常运行磁盘空间是否充足。镜像存放需要空间如果 C 盘快满了Docker 会莫名失败。确认网络。不同的网络环境下首次拉取的表现差别很大换一个时间段重试通常能解决。执行docker compose pull --ignore-pull-failures跳过失败的服务单独拉取然后再docker compose up -d。看具体报错。如果提示“no matching manifest for windows/amd64”说明你的 Docker Desktop 没有切到 Linux 容器模式右下角 Docker 图标右键选择“Switch to Linux containers”。不要手动去改 .env 里的镜像仓库地址除非你很确定镜像是安全的。保持默认仓库地址最可靠。6.2 端口 80 被占用如果你本机已经跑着 IIS、Nginx、Apache 或其他 Web 服务启动 Dify 时会看到Bind for 0.0.0.0:80 failed: port is already allocated最简单的解决办法是修改 Dify 对外端口。进入 docker 目录下的 .env找到EXPOSE_NGINX_PORT80改成其他端口比如EXPOSE_NGINX_PORT8080保存后重新创建容器docker compose up -d之后访问地址变成 http://localhost:8080。注意 .env 和 docker-compose.yaml 里的变量是绑定关系改 .env 比改 yaml 更规范启动时 Dify 会自动读取变量。6.3 Dify 连不上 Ollama模型测试失败配置好 Ollama 后在 Dify 里测试模型经常看到“connection error”或“timeout”。绝大多数情况是 Base URL 填错了。记住在 Dify 容器内访问宿主机必须用 host.docker.internal。所以正确地址是http://host.docker.internal:11434确认这一步没问题后再检查宿主机curl http://localhost:11434如果宿主机都访问不了说明 Ollama 服务没起。然后确认模型存在ollama list如果里面没有 qwen2.5:7b 或 nomic-embed-text说明你拉模型失败或模型名拼写错误。模型名必须完全一致否则 Dify 会报模型不存在。如果宿主机能通但容器还是不通试着把 Ollama 的环境变量 OLLAMA_HOST 设为 0.0.0.0:11434 并重启 Ollama。Windows 防火墙检查一下确保 11434 端口没有被拦截尤其当你用的是非默认网络环境时。6.4 知识库检索总是不准怎么调检索不准不要一上来就怪模型先看知识库本身。我的经验是文档质量决定了检索上限。扫描件 PDF、表格转 Word、带复杂排版的文档Dify 解析后很可能变成乱序文本这时候不管怎么调参数都没用。处理方式是优先用干净的文本格式比如 Markdown 或 Word 里纯文本导出。如果必须是扫描版 PDF需要先做 OCR 转成可编辑文本一步都不能省。分段参数方面如果召回结果“太碎”适当增大分段长度如果“答非所问”增大 overlap 并检查 Embedding 模型是否切换成了 bge-m3 这类更强的模型。最后在召回测试里对比不同参数下的相似度分数选择效果最好的组合。6.5 回答速度慢CPU 推理卡顿本地部署大模型速度焦虑一定会有。7B 模型在 CPU 上生成速度大概只有每秒几个 token体验谈不上流畅。如果你有 NVIDIA 显卡确认 Ollama 是否检测到 GPU。执行ollama run qwen2.5:7b然后看启动日志是否出现类似“inference compute: GPU”的输出。如果显示 CPU说明显卡未生效升级显卡驱动后再试。没有 GPU 的情况下一个折中方案是换小模型比如 qwen2.5:3b速度明显提升知识库问答场景下效果也能接受。另一个方法是控制输入长度知识检索 TopK 不要调太大避免每次请求携带过长的检索结果。最后的经验分享整套环境跑通之后我最大的体会是本地部署 Dify 最大的价值不是省 API 钱而是让你能在一个不依赖外部服务的安全环境里把 RAG 和智能体的每个环节拆开看明白。调试时我能直接看知识库召回内容能改工作流节点能换不同模型对比效果这种自由度是云端平台很难给的。几个小建议送给你先把“知识库问答”这个最小闭环跑通再加工具和复杂工作流升级 Dify 前把 docker 目录下的 volumes 数据目录备份一份避免数据丢失没事多去点 Dify 的“召回测试”和“工作流调试”问题定位都靠这两个功能。如果你在 Windows 上遇到其他奇怪的部署问题不妨先从 Docker Desktop 状态和日志入手大部分问题都能在docker compose logs里找到答案。 
