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

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

0. 背景与整体架构

目标：在本地（以 Windows 为主）搭建一套完全本地化、可离线运行的 AI 应用平台，包含：

• Dify：低代码 AI 应用开发平台（知识库 + 智能体/Agent），通过 Docker 部署。
• Ollama：本地运行大语言模型（LLM）与向量嵌入模型（Embedding）。
• Xinference：本地运行重排序模型（Rerank），弥补 Ollama 在 Dify 中无法直接提供 Rerank 能力的短板。

典型调用链：

用户 → Dify（Docker） ├── LLM / Embedding → Ollama（宿主机，11434） └── Rerank → Xinference（宿主机，9999/9997） 

最核心的三条踩坑结论（请先记住）：

1. 能不装 C 盘就不装 C 盘：Docker Desktop、Ollama 模型、Xinference 数据都默认往 C 盘塞，务必提前改路径。
2. Ollama 在 Dify 里配 Rerank 会出问题 ：即使 Ollama 能下载 rerank 模型，Dify 实际应用仍可能异常；稳妥方案是用 Xinference 单独部署 Rerank。
3. Docker 内的 Dify 访问宿主机服务有网络坑 ：Ollama 用 host.docker.internal，Xinference 用宿主机真实 IP + 防火墙放行端口，否则就是各种"连接拒绝 / 超时"。

1. 环境准备：虚拟化 + WSL2 + Docker Desktop

1.1 开启虚拟化

• 打开任务管理器（Ctrl+Shift+Esc）→ 性能 → CPU，确认"虚拟化"已启用。
• 若显示禁用，需重启进 BIOS 开启（不同主板设置不同，可自行检索）。

1.2 安装 WSL2

• 右键 Windows 图标 → 终端(管理员) → PowerShell 中执行：

  wsl --install

• 等待 Linux 子系统与 WSL2 内核安装完成。

1.3 安装 Docker Desktop（重点：别装 C 盘）

• 先确认架构：

  echo %PROCESSOR_ARCHITECTURE%

  • 返回 AMD64 → 下载 AMD64 版；返回 ARM64 → 下载 ARM64 版。

• 若 C 盘空间紧张 ，用命令行指定安装目录（推荐）：

  1. 提前手动创建目录：D:\Program Files\Docker 与 D:\Program Files\Docker\data（不预建可能报错）。
  2. 以管理员身份打开命令提示符，切到安装包所在目录，执行：
  3. 弹窗选 OK，等待完成。

• 若 C 盘够大，直接右键"以管理员身份运行"安装包，按引导勾选后点 OK 即可。

1.4 验证与配置

• 验证：docker --version 有版本号即成功；进一步 docker run hello-world 见到欢迎语说明能正常拉取运行镜像。
• 配置国内镜像源（强烈建议） ：Docker Desktop 右上角 Settings → Docker Engine，加入 registry-mirrors（阿里云、清华、腾讯云等国内镜像地址），避免拉镜像超时。
• 启动：桌面 Docker 图标右键"以管理员身份运行"，左下角出现 Engine running 即就绪。

2. 部署 Dify（Docker Compose）

1. 下载源码 ：从 Dify 的 GitHub Release 下载最新版 .zip，解压得到 dify-main（内含 docker/ 目录）。

2. 生成配置 ：进入 dify-main/docker/，将 .env.example 复制/重命名为 .env。

3. 端口冲突处理（常见坑） ：若本机 80/443 被占用，需改 Dify 对外映射端口。编辑 .env：

   • NGINX_PORT / NGINX_SSL_PORT（容器内端口）默认 80/443，可不动；
   • EXPOSE_NGINX_PORT / EXPOSE_NGINX_SSL_PORT（对外映射端口）必须改 ，例如改为 8100 / 6443。

4. 启动 ：在 docker/ 目录打开终端执行：

   docker compose up -d

   • 网络不稳定导致某镜像下载中断时，可先单独 docker pull <镜像> 再重新 up -d。

5. 访问：浏览器打开，首次设置管理员账号密码。

提示：Dify 调用本地模型不需要 API Key，不花钱，但性能受本机硬件限制。

3. 部署 Ollama（本地 LLM + Embedding）

3.1 安装（重点：改模型路径，别让模型占满 C 盘）

• 下载 OllamaSetup.exe。
• 改路径安装 ：

  1. 在 D 盘建目录 D:\ollama，把安装包放进去：D:\ollama\OllamaSetup.exe。

  2. 设置系统环境变量：OLLAMA_MODELS = D:\ollama\models。

  3. 管理员 PowerShell 进入该目录执行：

     .\OllamaSetup.exe /dir=D:\ollama

  4. 安装界面点 Install，等待完成。

• 说明：Ollama 程序本体 默认装 C 盘且安装时一般无法改目录；模型存储路径可通过环境变量或修改 Ollama 设置里的 "Model location" 改到非 C 盘。两者都要留意。

3.2 验证与拉取模型

• 选型建议 ：LLM 推荐 deepseek、qwen；Embedding 推荐 bge-m3（专为嵌入训练，比拿 deepseek 当 embedding 效果好）。

4. Dify 接入 Ollama（配置本地模型）

1. Dify 主界面 → 头像 → 设置 → 模型供应商 → 找到 Ollama 插件并安装（首次下载较慢，耐心等）。
2. 点击"添加模型"，把本地 LLM 与 Embedding 都加进去：
   • 模型名称：ollama list 查到的名字；
   • 模型类型：推理模型选 LLM ，嵌入模型选 Text Embedding；
   • 基础 URL：-（Docker 内访问宿主机 Ollama 必须用这个，别用 localhost/127.0.0.1）。
3. 右上角"系统模型设置" → 选好系统推理模型 与 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（本地 Rerank）

6.1 安装

.2 改数据存储路径（别装 C 盘）

6.3 启动

• CPU 机器 / 通用（推荐用本机真实 IP） ：

• 有 NVIDIA GPU（需 CUDA）可用官方镜像 ：

6.4 验证与启动 Rerank 模型

• 验证服务：
• 打开 WebUI：

7. Xinference 接入 Dify 的踩坑（连接拒绝 / 超时）

这是本项目最典型的"部署成功却连不上"问题，两个独立来源都踩过：

坑 1：Dify（Docker）连 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 填宿主机的真实局域网 IP ，Dify 里也填 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 个 worker，max-concurrency=1）；
  • CELERY_AUTO_SCALE=false（不自动扩缩）。
• 任务产生速度 > 处理速度 → 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_PORT
Ollama 接入	Dify 里基础 URL 用
Rerank	放弃 Ollama 提供 Rerank ，用 Xinference 部署 bge-reranker-v2-m3
Xinference 接入	启动 --host 填宿主机真实 IP ；Dify 内填 http://<IP>:9999；防火墙放行端口
知识库批量上传	性能差别批量传
备份	改动前备份 DSL 与数据库

常用命令速查