本地知识库问答（ollama + MaxKB） 已实测

场景

你攒了一堆笔记、PDF、公司文档，想「问自己的资料」而不是全网搜：把文档喂进去，用自然语言提问，答案基于你自己的内容。刷到的教程各说各话：有让用云平台的（数据出去了）、有让装一堆组件的（向量库+分块+embedding 全自己搭）、有讲了一半烂尾的。

本组合包给一条30 分钟内能跑通的路：ollama 负责本地模型（数据不出机器），MaxKB 负责「上传文档 → 自动分块向量化 → 基于文档回答」，自带网页界面。装完之后你得到：一个 http://localhost:8080 的知识库问答台，拖进文档就能问。

组合成员 （2）

curl -fsSL https://gh-proxy.com/https://github.com/ollama/ollama/releases/latest/download/install.sh | sh
# 或手动：下载 tar.zst 解压（需 tar --zstd 或 zstd 工具）
curl -sL -o /tmp/ollama.tar.zst https://gh-proxy.com/https://github.com/ollama/ollama/releases/latest/download/ollama-linux-amd64.tar.zst
mkdir -p /tmp/ollama-bin && tar --zstd -xf /tmp/ollama.tar.zst -C /tmp/ollama-bin
/tmp/ollama-bin/bin/ollama --version

# 国内网络：走 daocloud 加速前缀（2026-09-01 实测可拉）
docker run -d --name=maxkb --restart=always -p 8080:8080 \
  -v ~/.maxkb:/opt/maxkb \
  docker.m.daocloud.io/1panel/maxkb:latest
# 官方原版（网络允许直连 Docker Hub 时）
# docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb

方案总览

两个工具各管一段：

备选方案：AnythingLLM（桌面端 App，适合不熟 Docker 的用户；但安装包 400-860MB）／Dify（功能重，面向应用搭建）／coze（云端，数据出境）。纯命令行用户可只用 ollama（ollama run 问答，但没有知识库）。

安装顺序按依赖排：先 ollama（模型底座，MaxKB 配置模型源时要用它的 API）→ 再 MaxKB（Docker 起容器，管理后台里把模型源指到 ollama）。

快速开始

一键脚本由本文档自动生成（渲染后位于 pages/combos/combo-local-rag.sh），按官方下载源 + 国内镜像适配，逐条执行：

bash pages/combos/combo-local-rag.sh
````

- 装完你会得到：ollama 服务（端口 11434）+ 知识库问答台（http://localhost:8080）。
- 预计耗时：10-20 分钟。**最大卡点 = MaxKB 首次拉 Docker 镜像（4.62GB，daocloud 加速，2026-09-01 实测）**；模型下载另计（4-70GB 视模型大小，先拉小模型验证链路）。
- 前置条件：内存 ≥ 8GB（建议 16GB）；磁盘 ≥ 10GB 空闲；Docker（本仓库已实测 WSL dockerd 路径）。

> 想弄明白每一步在干什么、装错了怎么恢复 → 看「逐步教学」。一键脚本出问题 → 按逐步教学手动执行定位。

逐步教学

第 1 步：装 ollama（模型底座，一切依赖它）

ollama 是整套环境的地基：模型文件由它管理（默认 ~/.ollama/models），MaxKB 通过它的 API（11434 端口）做生成与 embedding。安装过程会下载官方脚本/二进制并注册后台服务；国内网络 GitHub 直连慢，走 gh-proxy 前缀。

curl -fsSL https://gh-proxy.com/https://github.com/ollama/ollama/releases/latest/download/install.sh | sh
# 或手动：下载 tar.zst 解压（需 tar --zstd 或 zstd 工具）
curl -sL -o /tmp/ollama.tar.zst https://gh-proxy.com/https://github.com/ollama/ollama/releases/latest/download/ollama-linux-amd64.tar.zst
mkdir -p /tmp/ollama-bin && tar --zstd -xf /tmp/ollama.tar.zst -C /tmp/ollama-bin
/tmp/ollama-bin/bin/ollama --version
````

预期输出: `ollama version 0.33.2`（或更高）

装好确认：
- `ollama --version` 输出版本号；
- `curl http://localhost:11434/api/version` 返回 `{"version":"0.33.2"}`。

卡住怎么办：
- **下载超时/失败** → 换手动 tar.zst 路径，下载走 gh-proxy 前缀（2026-08-29 实测通过）。
- **`tar --zstd` 报错** → `sudo apt install -y zstd` 后重试。
- **服务没起来** → `ollama serve` 前台启动看日志；端口被占 → `OLLAMA_HOST=127.0.0.1:11435 ollama serve` 换端口（MaxKB 对接地址同步改）。

> note: 模型下载默认走 ollama 官方 registry（国内可能超时）；备选 = ModelScope 下载 GGUF 后用 `ollama create` 导入（实测：qwen2.5-0.5b 491MB 58.5s + create success + CPU 冒烟，实测复现日志（2026-08-29））。

### 第 2 步：装 MaxKB（知识库问答台）

MaxKB 是一个 Docker 容器搞定全部：内置 Postgres（数据持久化）、文档解析、向量化、检索与生成。官方命令把数据目录挂到 `~/.maxkb`，删容器不丢数据。国内拉 Docker Hub 镜像失败时，把镜像名加 `docker.m.daocloud.io/` 前缀（2026-09-01 实测该路径可拉）。

````bash
# 国内网络：走 daocloud 加速前缀（2026-09-01 实测可拉）
docker run -d --name=maxkb --restart=always -p 8080:8080 \
  -v ~/.maxkb:/opt/maxkb \
  docker.m.daocloud.io/1panel/maxkb:latest
# 官方原版（网络允许直连 Docker Hub 时）
# docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb
````

预期输出: 容器 `maxkb` 启动，浏览器打开 http://localhost:8080 出现登录页

装好确认：
- `docker ps` 里 maxkb 状态 Up（首次启动 1-3 分钟初始化，日志 `docker logs maxkb` 可看进度）；
- 浏览器 http://localhost:8080 出现登录页 → 默认账号 `admin / MaxKB@123..`（首次登录建议改密）。

卡住怎么办：
- **镜像拉取失败** → 换加速前缀（daocloud）；再不行看官方离线安装文档 https://maxkb.cn/docs/v2/installation/offline_installtion/。
- **8080 被占** → `-p 8081:8080` 换宿主机端口，访问地址同步换。
- **登录页打不开** → `docker logs maxkb --tail 50` 看初始化报错；容器重启后等 1-3 分钟再刷。

### 第 3 步：把 MaxKB 接上 ollama（核心联动）

MaxKB 默认不带模型，要把它指到本地 ollama（模型不出机器）。这一步在网页里操作，不需要命令。

1. 登录 MaxKB（admin / MaxKB@123..）→ 左侧「模型设置」→「模型供应商」→ 选 **Ollama**；
2. API 域名填 `http://host.docker.internal:11434`（Docker 容器里访问宿主机的固定地址；Linux 直接跑则填 `http://127.0.0.1:11434`）；
3. 选一个已拉好的模型（如 `qwen2.5:0.5b`）保存；
4. 左侧「知识库」→ 新建 → 上传文档（PDF/Word/Markdown 等）→ 等解析完成；
5. 左侧「应用」→ 新建应用 → 选该模型 + 关联知识库 → 开始问答。

预期输出: 提问「这个文档里 XX 是什么」能基于文档内容回答

卡住怎么办：
- **连不上 ollama** → 先确认宿主机 `curl http://127.0.0.1:11434/api/version` 有返回；容器内用 host.docker.internal 必须 Docker 支持该地址（WSL dockerd 实测可用；老版本加 `--add-host=host.docker.internal:host-gateway`）。
- **模型列表为空** → 先在宿主机 `ollama pull qwen2.5:0.5b`（小模型验证链路，或 ModelScope GGUF 导入）。
- **回答不基于文档** → 按顺序查三处（2026-09-01 实测踩坑）：① 应用知识库检索相似度阈值太高——本地 text2vec 中文匹配建议 similarity <= 0.2（0.6 会检索为空）；② 应用「模型设置 → 提示词」必须含 `{data}` 占位符，否则检索到的段落不会拼进 prompt，模型会编造答案；③ 改过应用配置后必须重新「发布」，聊天走的是发布时的版本快照（旧配置不生效）。

日常使用

启动与入口

• ollama：服务常驻（ollama serve 或系统服务），入口 API http://localhost:11434；
• MaxKB：docker start maxkb，入口 http://localhost:8080。

常用操作

• 传新文档：MaxKB → 知识库 → 上传（支持 PDF/Word/Markdown/Excel/网页等）；
• 换模型：MaxKB → 模型设置 → 供应商 → Ollama → 换模型名（先在宿主机拉好）；
• 看状态：docker logs maxkb --tail 20；ollama ps 看当前加载模型。

数据与目录

• MaxKB 数据：~/.maxkb/（容器 /opt/maxkb，含 Postgres 数据——备份就是备份这个目录）；
• ollama 模型：~/.ollama/models/（OLLAMA_MODELS 可指到大分区）。

卸载与清理

按安装顺序反向卸载：

docker rm -f maxkb
# 数据目录（含知识库文档与配置，删了不可恢复）
rm -rf ~/.maxkb
# ollama 如不再需要：删模型 + 停服务
ollama rm qwen2.5:0.5b 2>/dev/null
````

预期输出: 容器消失、目录清理完成

> note: `~/.maxkb` 是知识库数据本体，确认不再需要再删。

安装顺序

1. 先 ollama（底座）——装完 ollama --version 冒烟，拉一个模型（国内网络此步最容易卡，见第 1 步卡住怎么办）。
2. 再 MaxKB（知识库台）——Docker 起容器（默认 8080 端口），管理后台 → 模型设置 → 模型供应商选 ollama → 填 http://host.docker.internal:11434 → 选模型 → 建知识库 → 传文档 → 问答。

每步的"为什么 + 命令 + 装好确认 + 卡住怎么办"见「逐步教学」。

依赖警告

• 版本：ollama >= 0.33.2（实测）；MaxKB v2.10.5-lts（latest 标签）；Docker >= 20.10（compose 可选）。
• 环境：内存 >= 8GB（模型加载 + 向量化同时跑建议 16GB）；磁盘 MaxKB 镜像 4.62GB（实测）+ 模型 4-70GB；端口 11434（ollama）/8080（MaxKB）。
• 环境（实测坑）：snap/apt 版 ollama 默认只监听 127.0.0.1:11434，bridge 容器访问会被拒（connection refused，2026-09-01 实测）；解法 sudo snap set ollama host=0.0.0.0:11434（或 apt 版改启动参数）后重启，容器内经 172.17.0.1:11434 可达。注意 0.0.0.0 会暴露到局域网，按需配防火墙。
• 冲突：MaxKB×open-webui 若同机跑——两者都是「知识库问答」定位，功能重叠建议只留一个（possible-conflict，静态判定：端口不同但定位重叠）；ollama×MaxKB 为 compatible（MaxKB 只读 ollama API，无共享写面）；与本站其他工具无共享写面。
• 国内网络：ollama 二进制走 gh-proxy（实测）；模型走 ModelScope GGUF 导入（实测）或官方 registry（可能超时）；MaxKB 镜像走 daocloud 加速（实测）。

FAQ

1. 为什么用 MaxKB 而不是 open-webui 的知识库？ → open-webui 的 RAG 是附属功能，MaxKB 是专门的知识库问答台（文档解析更全、可嵌入业务系统、中文界面）；两者二选一即可。
2. 数据会出网吗？ → 模型在本地 ollama、知识库在本地容器，不上传云端；只有 MaxKB 拉镜像/升级时走网络。
3. 答得不好怎么办？ → 换大一点的模型（7B 起步，14B 更好）；文档拆分更细（一个文档一个主题）；应用设置里调检索参数。
4. 容器里连不上 ollama（connection refused）？ → snap/apt 版 ollama 默认只监听 127.0.0.1，容器访问不到；改 sudo snap set ollama host=0.0.0.0:11434 并重启 ollama 服务（实测解法），MaxKB 里 API 地址填 http://172.17.0.1:11434（WSL/Linux bridge）或 http://host.docker.internal:11434（Docker Desktop）。
5. 能嵌入自己的网站/系统吗？ → 可以，MaxKB 应用有「嵌入」功能（HTML 片段），官方文档有说明（未实测）。
6. Mac/Windows 能装吗？ → 都可以：Docker Desktop 起 MaxKB；ollama 有官方安装器；WSL2 内路径与本指南一致。
7. 问答不引用知识库/答得不对？ → 三处排查（2026-09-01 实测）：① 相似度阈值太高（本地 text2vec 中文建议 <=0.2）；② 应用提示词缺 {data} 占位符（段落拼不进 prompt）；③ 改配置后没重新发布（聊天读发布快照）。逐条对照证据 §6.4。
8. API 方式操作 MaxKB 有什么注意？ → 发布是 PUT；创建应用必带 prologue；PUT 更新必须带 knowledge_id_list；no_references_setting.status 合法值只有 ai_questioning/designated_answer。实测细节见证据 §6.4。

验证证据

每份组合包在隔离环境实测（冒烟 + 写面检查），未实测项在文中如实标注；实测日期见下方验证证据。

验证于 2026-09-01 · TTL 到期 2027-02-28（180 天）

• MaxKB 镜像拉取 + 容器启动 + 登录 + 容器→ollama 连通（2026-09-01，WSL Ubuntu，dockerd 29.1.3）：实测复现日志（2026-09-01）
• daocloud 拉 1panel/maxkb:latest 4.62GB 成功；容器 Up + 8080 映射 + PostgreSQL 17.10 就绪 + "MaxKB started."
• 默认账号 admin / MaxKB@123.. 登录 API 返回 token（成功）
• snap ollama 默认只监听 127.0.0.1 → 改 host=0.0.0.0:11434 后容器内经 172.17.0.1:11434 访问 ollama API 成功（{"version":"0.32.14"}）
• MaxKB「建知识库→传文档→向量化→应用→问答」API 全链路（2026-09-01 晚，同环境）：同上证据文件 §6
• 创建 SIMPLE 应用 + PUT 发布（is_publish=true）；聊天 POST /admin/api/chat_message/<chat_id> 开卷问答
• 提问「MAXKB_PROBE_TOKEN 的含义是什么？」→ 回答「MAXKB_PROBE_TOKEN 的含义是 trove-rag-test-passed-20260901。」与知识库事实逐字一致（检索→向量→prompt→本地模型生成全链路成功）
• 完整踩坑 8 条（相似度阈值/{data} 占位符/编辑后必须重发布等）见证据 §6.4
• 未实测（如实标注）：Docker Hub 官方直连未测（daocloud 已覆盖国内路径）
• ollama 侧复用既有实测：实测复现日志（2026-08-29）（0.33.2 + qwen2.5-0.5b 导入 + CPU 冒烟）

关联问题

• ollama-pull-timeout
• ollama-install-slow
• ollama-connect-failed