从零手搓AI工程：数据管道、模型训练与部署监控全链路实战
2026/10/2 8:06:48
WeKnora 离线部署实操：如何在无网环境下跑起本地 RAG 知识库与问答 Agent
【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora
内网机器没有外网，文档又不能交给云端 API，但你仍想要一个能传文档、能提问、能给出引用出处的 RAG 知识库。本文用 Docker + Ollama 完成 WeKnora 私有化部署：跑通后，解析、检索、推理全部落在本机，问答自带引用来源。
先看你的处境：这条路是否适合走
| 你的情况 | 这条路线是否适合 | 更省事的替代选择 |
|---|---|---|
| 机器连不上外网（单位内网、机房），网页都打不开 | 适合。镜像、模型、解析全部本地化，拔线也能跑 | 若偶尔有网络窗口，在联网机上把物料备齐再拷入内网部署 |
| 文档涉密，合规要求数据不出机器 | 适合。文件与权重只落在自己的磁盘上 | 涉密与非涉密混用时，只让涉密文档进这套库，其余走云端服务 |
| 想在自己的硬件上吃透 RAG 链路，或给小团队做试点 | 适合。单机 compose 编排就够，不必上重型调度 | 纯个人尝鲜、无多人协作需求，可先试零依赖的单应用 Lite 版 |
机器预检：硬件下限与联网窗口清单
| 项目 | 下限 | 一句原因 |
|---|---|---|
| 软件 | Docker ≥ 20.10、Compose v2、Git | compose 文件按 v2 语法编写，老版本直接解析失败 |
| 硬件 | 8 核 CPU / 32GB 内存 | 7B 对话模型推理以内存为主，可用内存低于 16GB 时响应明显拖慢 |
| 磁盘 | 预留 200GB | 镜像、模型权重、解析中间产物都往盘上写 |
| 联网窗口 | 首次拉镜像、下模型必须能上网 | ⚠️ 离线部署的正确顺序：在联网机上拉完镜像（docker save打包）、下好模型，再整体拷进内网，而非在目标机上现拉 |
搭建走查：取壳、接脑、跑通
取壳：代码与唯一配置入口
git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora && cp .env.example .env克隆代码并复制出配置模板——整个部署只有一个配置入口就是.env，数据库密码、存储类型、Ollama 地址全在这一个文件里，模板内每项都带注释。
重点确认以下几处，其余保持默认：
| 变量 | 模板默认值 | 作用（一句话） |
|---|---|---|
STORAGE_TYPE | local | 文件直接落到容器挂载的本地目录，不引入对象存储 |
OLLAMA_BASE_URL | http://host.docker.internal:11434 | 容器内访问宿主机 Ollama 的固定写法，写成localhost会指向容器自己 |
DB_PASSWORD/REDIS_PASSWORD/SYSTEM_AES_KEY | 模板示例值 | 换成自生成值，内网环境也别直接沿用示例密码 |
另外 config/config.yaml 会被直接挂载进 app 容器（映射到/app/config/config.yaml），调解析与检索行为时改它、重启容器即可，不需要重建镜像。
接脑：两个 Ollama 模型就位
ollama pull bge-m3 # 嵌入模型 ollama pull qwen2.5:7b # 对话模型，可换成你已有的型号嵌入和对话各备一个；离线机器上这两条命令要在联网机执行，导出模型文件拷入目标机再导入。模型缺席时 app 只告警、不崩溃，但问答功能暂时不可用。
跑通：一条命令拉起整套集群
./scripts/start_all.sh -c ./scripts/start_all.sh --no-pull第一条是环境自检，先跑一遍排除低级问题；第二条正式拉起前端、app、postgres、docreader、redis 这批容器。--no-pull表示跳过联网拉镜像、只用本地已有的——这正是离线启动的开关，有网的首次部署去掉它即可。脚本还会顺带确认 Ollama 存活、.env齐全。
🚀 脚本末尾打印出前端（80 端口）与 API（8080 端口）两个地址时，集群即就绪。更多启动、停止、重建操作都收在 scripts/start_all.sh 里。
验收：从进程级到效果级逐层确认
进程级——容器状态。
docker compose ps确认全部为 Up，重点盯WeKnora-app、WeKnora-postgres、WeKnora-docreader三个核心容器。
服务级——健康检查与首次登录。
curl -f http://localhost:8080/health返回 200 说明后端自检通过；随后浏览器打开http://localhost，系统默认开放注册，把第一个账号注册并登录。
效果级——传 PDF 提问，回答带引用。
新建一个知识库，上传一份 PDF，等解析状态转为完成；再到问答页问一句"这份文档主要讲什么"。回答中出现引用来源标注，整条链路才算全通。
✅ 三层全部通过，这次部署才算真正落地。
排障与调优：高频卡点与三个旋钮
| 症状 | 可能原因 | 处理 |
|---|---|---|
| app 容器反复重启，日志刷 Ollama 连接失败 | Ollama 进程没起，或.env里地址写成localhost | 先在宿主机跑curl http://localhost:11434/api/tags确认进程活着，再把地址改成host.docker.internal |
| 上传文档被直接拒绝 | 单文件超过 50MB 默认上限 | 拆分文件，或在.env调大MAX_FILE_SIZE_MB |
| 解析卡住无进展 | 该格式不被解析器支持 | 看docker compose logs docreader，解析错误会指明具体原因 |
调优集中在三个旋钮，无 GPU 时优先动第一个：
| 旋钮 | 所在文件 | 说明 |
|---|---|---|
| 对话模型规格 | 前端模型设置 /ollama pull的目标型号 | CPU 推理全压对话模型，换更小规格见效最快 |
| 嵌入批次大小 | .env的BATCH_EMBED_SIZE | 调小用内存换稳定性 |
| 召回数量 | config/config.yaml 的embedding_top_k/rerank_top_k | 调小减少检索上下文，回答更快 |
收尾：跑通之后
至此，一台不碰外网的机器上已跑起完整的 WeKnora 私有化链路：文档解析、向量检索、模型推理全部本地完成，数据不出机器。
接下来值得做的两件事：给data-files数据卷挂独立磁盘并定期备份；把 Ollama 指向内网里显存最大的那台机器，做模型负载分担。
延伸阅读：
- 部署脚本与全部子命令：scripts/start_all.sh
- 配置模板（含逐项注释）：
.env.example - 常见问题与运维手册：docs/QA.md
【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考