Dify 本地部署、Ollama 与 Xinference 集成：踩坑与最佳实践指南

Dify 本地部署、Ollama 与 Xinference 集成踩坑与最佳实践指南0. 背景与整体架构目标在本地以 Windows 为主搭建一套完全本地化、可离线运行的 AI 应用平台包含Dify低代码 AI 应用开发平台知识库 智能体/Agent通过 Docker 部署。Ollama本地运行大语言模型LLM与向量嵌入模型Embedding。Xinference本地运行重排序模型Rerank弥补 Ollama 在 Dify 中无法直接提供 Rerank 能力的短板。典型调用链用户 → DifyDocker ├── LLM / Embedding → Ollama宿主机11434 └── Rerank → Xinference宿主机9999/9997最核心的三条踩坑结论请先记住能不装 C 盘就不装 C 盘Docker Desktop、Ollama 模型、Xinference 数据都默认往 C 盘塞务必提前改路径。Ollama 在 Dify 里配 Rerank 会出问题即使 Ollama 能下载 rerank 模型Dify 实际应用仍可能异常稳妥方案是用Xinference单独部署 Rerank。Docker 内的 Dify 访问宿主机服务有网络坑Ollama 用host.docker.internalXinference 用宿主机真实 IP 防火墙放行端口否则就是各种连接拒绝 / 超时。1. 环境准备虚拟化 WSL2 Docker Desktop1.1 开启虚拟化打开任务管理器CtrlShiftEsc→ 性能 → CPU确认虚拟化已启用。若显示禁用需重启进 BIOS 开启不同主板设置不同可自行检索。1.2 安装 WSL2右键 Windows 图标 → 终端(管理员) → PowerShell 中执行wsl --install等待 Linux 子系统与 WSL2 内核安装完成。1.3 安装 Docker Desktop重点别装 C 盘先确认架构echo %PROCESSOR_ARCHITECTURE%返回AMD64→ 下载 AMD64 版返回ARM64→ 下载 ARM64 版。若 C 盘空间紧张用命令行指定安装目录推荐提前手动创建目录D:\Program Files\Docker与D:\Program Files\Docker\data不预建可能报错。以管理员身份打开命令提示符切到安装包所在目录执行弹窗选 OK等待完成。若 C 盘够大直接右键以管理员身份运行安装包按引导勾选后点 OK 即可。1.4 验证与配置验证docker --version有版本号即成功进一步docker run hello-world见到欢迎语说明能正常拉取运行镜像。配置国内镜像源强烈建议Docker Desktop 右上角 Settings → Docker Engine加入registry-mirrors阿里云、清华、腾讯云等国内镜像地址避免拉镜像超时。启动桌面 Docker 图标右键以管理员身份运行左下角出现Engine running即就绪。2. 部署 DifyDocker Compose下载源码从 Dify 的 GitHub Release 下载最新版.zip解压得到dify-main内含docker/目录。生成配置进入dify-main/docker/将.env.example复制/重命名为.env。端口冲突处理常见坑若本机 80/443 被占用需改 Dify 对外映射端口。编辑.envNGINX_PORT/NGINX_SSL_PORT容器内端口默认 80/443可不动EXPOSE_NGINX_PORT/EXPOSE_NGINX_SSL_PORT对外映射端口必须改例如改为8100/6443。启动在docker/目录打开终端执行docker compose up -d网络不稳定导致某镜像下载中断时可先单独docker pull 镜像再重新up -d。访问浏览器打开首次设置管理员账号密码。提示Dify 调用本地模型不需要 API Key不花钱但性能受本机硬件限制。3. 部署 Ollama本地 LLM Embedding3.1 安装重点改模型路径别让模型占满 C 盘下载OllamaSetup.exe。改路径安装在 D 盘建目录D:\ollama把安装包放进去D:\ollama\OllamaSetup.exe。设置系统环境变量OLLAMA_MODELS D:\ollama\models。管理员 PowerShell 进入该目录执行.\OllamaSetup.exe /dirD:\ollama安装界面点 Install等待完成。说明Ollama程序本体默认装 C 盘且安装时一般无法改目录模型存储路径可通过环境变量或修改 Ollama 设置里的 Model location 改到非 C 盘。两者都要留意。3.2 验证与拉取模型选型建议LLM 推荐deepseek、qwenEmbedding 推荐bge-m3专为嵌入训练比拿 deepseek 当 embedding 效果好。4. Dify 接入 Ollama配置本地模型Dify 主界面 → 头像 → 设置 → 模型供应商 → 找到Ollama插件并安装首次下载较慢耐心等。点击添加模型把本地 LLM 与 Embedding 都加进去模型名称ollama list查到的名字模型类型推理模型选LLM嵌入模型选Text Embedding基础 URL-Docker 内访问宿主机 Ollama 必须用这个别用 localhost/127.0.0.1。右上角系统模型设置 → 选好系统推理模型与Embedding 模型。改完重启容器使配置生效。5. Rerank 模型为什么必须用 Xinference关键踩坑问题Dify 的 Ollama 集成不支持直接调用 Rerank API。即便在 Ollama 下载了 rerank 模型Dify 实际应用知识库检索重排时仍会出问题尝试用 Dify 插件方式接入 rerank 在本项目实践中也未能成功。结论放弃Ollama 提供 Rerank的思路改用 Xinference 本地部署 Rerank 模型。推荐模型开源免费的bge-reranker-v2-m3作用在 Dify 知识库检索设置中启用 Rerank可显著提升召回的相关性与最终回答质量。6. 部署 Xinference本地 Rerank6.1 安装.2 改数据存储路径别装 C 盘6.3 启动CPU 机器 / 通用推荐用本机真实 IP有 NVIDIA GPU需 CUDA可用官方镜像6.4 验证与启动 Rerank 模型验证服务打开 WebUI7. Xinference 接入 Dify 的踩坑连接拒绝 / 超时这是本项目最典型的部署成功却连不上问题两个独立来源都踩过坑 1DifyDocker连 Xinference 报拒绝连接 / HTTPConnectionPool现象xinference-local启动在 Dify 填0.0.0.0或127.0.0.1配置连接结果拒绝连接。原因Dify 跑在 Docker 里Docker 容器网络与宿主机隔离。0.0.0.0/127.0.0.1在容器内指向的是容器自己不是宿主机上的 Xinference。解决Xinference 启动时--host填宿主机的真实局域网 IPDify 里也填http://宿主机IP:9999。坑 2防火墙未放行端口现象IP 填对了仍报HTTPConnectionPool连接超时/失败。原因宿主机的防火墙没放行 Xinference 端口。解决Dify 侧添加 Rerank 模型Dify → 设置 → 模型供应商 →Xinference→ 添加模型模型类型选Rerank基础 URL模型 UID/名称填 Xinference 中启动的bge-reranker-v2-m3。8. 知识库上传一直排队中问题Celery Worker 不足现象用脚本/API 批量上传文件几天后发现成百上千个文件全部卡在排队中删除后手动重传仍无效。根因关键Dify 的文档向量化由Celery Worker异步处理。默认.env中CELERY_WORKER_AMOUNT为空实际只起 1 个 workermax-concurrency1CELERY_AUTO_SCALEfalse不自动扩缩。任务产生速度 处理速度 → Redis 中dataset队列严重积压于是所有文件长期排队中。排查流程照做解决方案紧急不重启地加 worker紧急清空积压队列谨慎会丢失未处理任务预防定期监控队列长度llen dataset与 worker 状态inspect stats服务器性能差不要一次性批量上传大量文件错峰、分批真解决不了先备份 DSL应用编排与数据库再考虑重装。9. 最佳实践清单一页速查主题推荐做法磁盘路径Docker、Ollama 模型、Xinference 数据全部改到非 C 盘命令行装 Docker、OLLAMA_MODELS、XINFERENCE_HOME镜像加速Docker Desktop 配置国内registry-mirrors否则拉镜像频繁超时端口冲突80/443 被占时改EXPOSE_NGINX_PORT/EXPOSE_NGINX_SSL_PORTOllama 接入Dify 里基础 URL 用Rerank放弃 Ollama 提供 Rerank用 Xinference 部署bge-reranker-v2-m3Xinference 接入启动--host填宿主机真实 IPDify 内填http://IP:9999防火墙放行端口知识库批量上传性能差别批量传备份改动前备份 DSL 与数据库常用命令速查