ollama + dify 快速搭建本地免费知识库配置实战避坑指南：手把手步骤拆解

很多站长在搭建本地知识库时，第一反应就是去找各种在线 API，结果要么被限流，要么用着用着就开始计费。其实完全可以用 ollama 跑本地大模型，再配合 dify 做编排层，整套链路完全离线、完全免费，数据不出本机。但网上大多数教程只告诉你“能跑”，却没告诉你显存怎么分配、端口怎么互通、模型怎么选、向量库怎么挂。站长踩过一圈坑之后，把完整流程和避坑要点整理成这篇实操指南，照着做基本能一次跑通。

一、前置依赖：别急着装 dify，先把底座理清楚

整套架构分三层：底层是 ollama 提供本地推理服务，中间是 dify 负责知识库管理、RAG 编排和对话界面，上层是浏览器访问。很多站长一上来就装 dify，结果发现 ollama 连不上，或者模型加载失败，回头重装浪费大量时间。

先把硬件底线说清楚：纯 CPU 也能跑，但 7B 级别模型推理速度大概每秒 2 到 5 个 token，知识库问答体验会比较卡。建议至少有一张 8GB 显存的显卡，跑 7B 量化模型比较顺畅；16GB 显存可以上 14B 量化模型，效果明显更好。内存建议 16GB 起步，因为 dify 本身加上向量库会吃掉不少内存。

操作系统方面，Linux 最省心，Windows 建议用 WSL2，macOS 用 Apple Silicon 芯片也能跑，但要注意 ollama 对 Metal 的支持情况。下面以 Linux 环境为主线，Windows 和 macOS 的差异会单独标注。

# 先确认显卡驱动和容器运行时是否就绪
nvidia-smi
docker --version
docker compose version

# 如果 nvidia-smi 报错，先装驱动，不要跳过这一步
# Ubuntu 下可参考：
# sudo apt install nvidia-driver-xxx
# 具体版本根据显卡型号选择

这里第一个坑：docker 默认运行时不是 nvidia，需要安装 nvidia-container-toolkit，否则 ollama 容器里看不到显卡。很多站长装完 ollama 发现速度极慢，就是因为容器没吃到 GPU。

# 安装 nvidia-container-toolkit（Ubuntu/Debian 示例）
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

二、ollama 安装与模型拉取：选对模型比装对软件更重要

ollama 的安装本身很简单，一行脚本搞定。但真正的坑在模型选择上。知识库场景对模型的指令遵循能力和中文理解要求比较高，不是随便拉一个模型就能用。

# 安装 ollama
curl -fsSL https://ollama.com/install.sh | sh

# 启动服务
sudo systemctl enable ollama
sudo systemctl start ollama

# 验证服务
curl http://localhost:11434/api/tags

模型推荐分两档：如果显存 8GB 左右，优先用 qwen2.5:7b 或 llama3.1:8b 的量化版本；如果显存 16GB 以上，可以上 qwen2.5:14b。中文知识库场景下，qwen 系列对中文文档的理解明显更稳。嵌入模型建议用 nomic-embed-text，体积小、速度快，和 dify 配合没问题。

# 拉取对话模型（根据显存二选一）
ollama pull qwen2.5:7b
# ollama pull qwen2.5:14b

# 拉取嵌入模型
ollama pull nomic-embed-text

# 测试模型是否能正常推理
ollama run qwen2.5:7b "用一句话说明什么是RAG"

第二个坑：ollama 默认只监听 127.0.0.1，如果 dify 跑在 docker 里，容器内部访问 localhost 是访问不到宿主机的 ollama 的。必须让 ollama 监听 0.0.0.0，并且 dify 配置里用宿主机 IP 或 host.docker.internal。

# 修改 ollama 监听地址
sudo systemctl edit ollama

# 在编辑器中加入以下内容
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

# 保存后重载并重启
sudo systemctl daemon-reload
sudo systemctl restart ollama

# 验证监听状态
ss -tlnp | grep 11434

第三个坑：防火墙。如果服务器开了 ufw 或 firewalld，11434 端口没放行，dify 容器同样连不上。本地测试可以临时关闭防火墙，生产环境建议只放行内网网段。

三、dify 部署：docker compose 方式最稳，但配置项要改对

💡 关联延伸阅读：如果你在配置过程中遇到相关报错，请参阅站长之前的解决教程：dify+ollama部署怎么用？小白极速入门保姆级教程

dify 官方推荐 docker compose 部署，但默认配置里模型供应商走的是在线 API，需要手动改成 ollama。另外向量库默认用的是内置的，数据量大了之后检索速度会下降，建议换成外部向量库或者至少把持久化目录挂载好。

# 克隆 dify 仓库
git clone https://github.com/langgenius/dify.git
cd dify/docker

# 复制环境变量文件
cp .env.example .env

# 启动前先改配置，不要直接 up
# 编辑 .env 文件，重点改以下几项

在 .env 里需要关注的核心配置：向量库类型、存储路径、以及是否开启多租户。个人使用可以关掉多租户简化流程。另外 dify 的 API 和 Web 端口默认是 5001 和 3000，如果和本机其他服务冲突，提前改掉。

# .env 关键配置示例（按需修改）
# 向量库选择，个人用默认的即可，数据量大再换
VECTOR_STORE=weaviate

# 数据库密码，务必改掉默认值
DB_PASSWORD=your_strong_password

# 端口映射，避免冲突
EXPOSE_NGINX_PORT=3000
EXPOSE_NGINX_SSL_PORT=3443

# 关闭不必要的遥测
SENTRY_DSN=

配置改完之后再启动，不要一边启动一边改，否则容器状态会混乱。

# 启动 dify
docker compose up -d

# 查看容器状态，确保全部 healthy
docker compose ps

# 查看日志，排查启动错误
docker compose logs -f api
docker compose logs -f worker

第四个坑：dify 的 worker 容器负责异步处理文档索引任务，如果 worker 没起来，上传文档后会一直卡在“等待处理”。所以 docker compose ps 里必须确认 worker 和 worker_beat 都是 running 状态。

四、打通 ollama 与 dify：模型供应商配置的细节

dify 启动后，浏览器访问 http://你的IP:3000，首次进入需要设置管理员账号。登录后在右上角头像进入“设置”，找到“模型供应商”，选择 Ollama。

这里是最容易翻车的地方。Base URL 不能填 localhost，因为 dify 的 api 容器和 ollama 不在同一个网络命名空间。如果 ollama 跑在宿主机上，dify 跑在 docker 里，正确填法有两种：

# 方式一：使用宿主机内网 IP
http://192.168.1.100:11434

# 方式二：使用 docker 特殊域名（Linux 下需要额外配置）
http://host.docker.internal:11434

# 如果方式二不通，在 docker-compose.yml 的 api 和 worker 服务下加入：
extra_hosts:
  - "host.docker.internal:host-gateway"

模型名称必须和 ollama list 里显示的完全一致，包括标签。比如 qwen2.5:7b 不能写成 qwen2.5。嵌入模型同理，nomic-embed-text 要单独添加为 text embedding 类型。

第五个坑：上下文长度和最大 token 数。ollama 默认的上下文窗口可能不够，dify 里如果设置过大，ollama 会报错或者截断。建议对话模型上下文设为 8192，最大 token 设为 4096，嵌入模型维度保持默认 768。这些参数在模型配置的高级设置里调整。

五、知识库创建与文档索引：分块策略决定检索质量

模型供应商配好之后，进入“知识库”创建。选择刚刚配置的 ollama 嵌入模型作为索引模型。上传文档时，分块设置非常关键。默认的自动分块对中文文档不太友好，容易把一句话切断。

# 推荐的分块参数（在知识库设置中调整）
分段标识符：\n\n
最大分段长度：500
分段重叠长度：50

# 如果文档是技术手册或合同类，可以改用：
分段标识符：\n
最大分段长度：300
分段重叠长度：30

第六个坑：PDF 解析。dify 默认的 PDF 解析对扫描版 PDF 无效，必须先用 OCR 工具转成文本再上传。另外表格内容在分块后容易丢失结构，建议把表格单独整理成 Markdown 再入库。

文档上传后，索引任务会进入队列。如果发现一直处于“索引中”，去检查 worker 日志。常见原因是嵌入模型调用超时，或者 ollama 的并发处理能力不足。可以在 ollama 启动参数里调整 OLLAMA_NUM_PARALLEL 来增加并发。

# 增加 ollama 并发处理能力
sudo systemctl edit ollama

[Service]
Environment="OLLAMA_NUM_PARALLEL=4"
Environment="OLLAMA_MAX_LOADED_MODELS=2"

sudo systemctl daemon-reload
sudo systemctl restart ollama

六、对话测试与效果调优：别指望一次就完美

知识库索引完成后，创建一个对话应用，关联该知识库。在编排界面里，把召回策略设为“向量检索”，Top K 设为 3 到 5，Score 阈值设为 0.5 左右。如果回答总是答非所问，先降低 Score 阈值，再检查分块是否合理。

第七个坑：模型幻觉。本地 7B 模型在知识库检索不到相关内容时，容易自己编答案。在提示词里明确加入“如果知识库中没有相关信息，请直接回答不知道”，能明显减少幻觉。另外把温度调到 0.1 到 0.3 之间，输出会更稳定。

# 提示词参考（在对话应用编排中设置）
你是一个严谨的知识库助手。请仅根据以下知识库内容回答问题。
如果知识库内容不足以回答，请直接说“根据现有资料无法回答”，不要编造。
知识库内容：
{{context}}
用户问题：
{{query}}

如果响应速度慢，优先检查是不是模型太大导致显存不够，发生了内存交换。用 nvidia-smi 观察显存占用，如果接近满载，换更小的量化模型或者减少并发。另外 dify 的 api 容器如果内存不足也会拖慢整体响应，建议给 docker 分配至少 8GB 内存。

七、总结：能跑通和好用之间差的是细节

ollama + dify 这套组合的优势在于完全本地、免费、数据可控，但代价是每个环节都需要自己调。站长把整个流程走下来，最耗时的不是安装，而是排查端口不通、模型加载失败、索引卡住这三类问题。只要把 ollama 监听地址、docker 网络互通、worker 状态、分块参数这四个点盯住，基本就能稳定运行。

另外提醒一点：本地知识库的效果上限取决于模型能力和文档质量，不要指望 7B 模型达到在线大模型的效果。如果对回答质量要求高，要么升级硬件跑更大模型，要么在文档预处理上多下功夫。整套环境搭好之后，日常维护主要是定期清理无用文档、更新模型版本、监控磁盘和显存占用。把这些做到位，本地免费知识库完全可以作为日常工作的可靠工具。