企业官网建设流程全解析

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. 最佳实践清单（一页速查）

常用命令速查