WeKnora 离线 RAG 知识库部署：本地单机跑通文档问答的完整教程

WeKnora 离线 RAG 知识库部署本地单机跑通文档问答的完整教程【免费下载链接】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/WeKnoraWeKnora 是一套开源的 LLM 知识平台核心功能是把 PDF、Word 这类原始文档转成可检索的 RAG 知识库再挂上一个能自主推理的问答 Agent还能自动维护 Wiki。这篇教程演示如何在不依赖任何云端 API的机器上用 Docker Ollama 把整套系统离线跑起来。动手前先对表这套方案适不适合你先用这张表做判断避免白忙一场你的情况结论机器完全无法访问外网文档问答必须本地闭环✅ 按本教程走模型推理、向量检索、文档解析全部本机完成数据涉密不允许流向第三方 API✅ 私有化部署后文件只落在自己的磁盘个人学习 RAG 链路或给小团队做试点✅ 单机 Compose 足够不需要 K8s只是个人尝鲜、不想维护一堆容器❌ 去看单应用零依赖的 Lite 版本更轻文档量极大、多团队高并发生产⚠️ 先看 Helm 编排模板单机方案先别上一句话决策只要数据不能出机器或机器连不上外网中有一条成立就继续往下。开工前的准备清单全部满足再动手省得中途返工软件三件套Docker≥20.10、Docker Composev2、Git。Ollama 不用提前装启动脚本会自动处理但如果目标是离线机器镜像和模型必须先在联网机器上备好用docker save打包再拷过去。硬件底线8 核 CPU 32GB 内存起步推理主要吃内存跑 7B 对话模型时建议留出 16GB 以上可用空间。磁盘预留 200GB镜像、模型权重、解析产物都会往盘上写。⚠️网络窗口首次拉镜像和模型必须联网。真正无网环境的正确姿势是联网机器备齐一切 → 拷贝 → 目标机部署而不是在目标机上现拉。任务一获取代码并生成配置入口git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env为什么从模板复制而不是手写整套部署只有.env这一个配置入口数据库密码、存储类型、Ollama 地址都收敛在这一个文件里模板里每项都带注释照着填即可。任务二只动三个关键位置打开.env其余保持默认重点确认这几处STORAGE_TYPE保持local——文件直接落在容器挂载的本地目录不引入任何对象存储依赖OLLAMA_BASE_URL保持默认http://host.docker.internal:11434这样容器才能找到宿主机上的 Ollama。⚠️ 容器视角下localhost指的是容器自己写localhost是最常见的坑DB_PASSWORD、REDIS_PASSWORD、SYSTEM_AES_KEY换成自己生成的值别沿用模板里的示例值。另外 config/config.yaml 会被直接挂载进 app 容器后续想微调解析与检索行为时改它就行不用重建镜像。模型侧还要把 docs/QA.md 里提到的INIT_LLM_MODEL_NAME、INIT_EMBEDDING_MODEL_NAME、INIT_EMBEDDING_MODEL_DIMENSION这几个变量指向你实际要用的模型否则文档上传会卡在嵌入环节。任务三在 Ollama 上备齐嵌入和对话两个模型嵌入和对话各需要一个ollama pull bge-m3 # 嵌入模型 ollama pull qwen2.5:7b # 对话模型换成你已有的模型名即可⚠️ 无网机器上这两条命令要在联网机器执行、导出模型文件拷过来再导入。模型没就位时 app 只告警不崩但问答功能暂时不可用先知道这一点别把它当成部署失败。任务四一条命令拉起整套服务./scripts/start_all.sh --no-pull脚本替你把三件事串起来确认 Ollama 存活、校验.env是否齐全、再用 Compose 拉起前端、app、postgres、docreader、redis 这批容器。--no-pull表示不联网拉镜像、直接用本地已有的这正是离线部署的关键开关如果首次就在有网机器上部署去掉这个参数即可。动手前也可以先执行./scripts/start_all.sh -c做一次环境自检。 脚本末尾打印出前端界面: http://localhost和API接口: http://localhost:8080时说明整套集群已经起来了。跑通后的验收五件事全过才算成功按顺序做任何一步卡住就跳到下面的排障速查#动作通过标准1docker compose ps所有容器 Up重点看 WeKnora-app、WeKnora-postgres、WeKnora-docreader2curl -f http://localhost:8080/health返回 200后端健康检查通过3浏览器打开http://localhost默认开放注册注册并登录第一个账号4新建知识库上传一份 PDF解析状态变为完成5问答页问这份文档主要讲什么拿到带引用出处的回答整条链路全通排障速查表高频故障都按现象 → 处理两句话给结论现象处理app 容器反复重启日志全是 Ollama 连不上先在宿主机curl http://localhost:11434/api/tags确认 Ollama 活着再核对.env的OLLAMA_BASE_URL是否写成host.docker.internal上传文档直接被拒默认单文件上限 50MBMAX_FILE_SIZE_MB超限先换小文件没超限就docker compose logs docreader看解析器报的具体格式问题文档传上去了但问答没反应检查任务二里的INIT_LLM_MODEL_NAME/INIT_EMBEDDING_MODEL_NAME是否真的指向 Ollama 里已有的模型名问答太慢无 GPU 时推理全压在 CPU 上换更小的对话模型或把BATCH_EMBED_SIZE调小换内存通常比换硬件见效快要继续压性能优先动三处对话模型规格、嵌入批次大小、知识库 top_k 召回数量——全部集中在.env和 config/config.yaml 里。回滚与清理不想留痕迹时按顺序执行./scripts/start_all.sh --stop # 停掉所有容器 docker volume prune # 清掉数据卷会删数据先确认无备份需求⚠️docker volume prune不可逆生产试点机先docker volume ls确认卷名或改用make clean-db只清数据库。延伸阅读部署到此结束下一步值得做两件运维事给数据卷挂独立磁盘并定期备份把 Ollama 指向内网显存最大的那台机器做负载分担。继续深入可以从这些仓库内材料入手部署脚本scripts/start_all.sh启动、停止、环境检查都在这里配置模板.env.example 与 config/config.yaml常见问题与运维docs/QA.md分块与解析细节docs/CHUNKING.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），仅供参考