周末在家折腾了一整天总算把 WeKnora 这套本地知识库问答系统完整跑通了。这套东西是腾讯微信团队开源出来的叫 WeKnora底层做得很扎实不是那种套壳 Demo。本地部署完之后我拿自己攒的一堆技术文档和日常笔记试了试效果比预想中能打。这篇就按我实际操作的顺序把整个部署过程和踩过的坑整理出来给你一份可以直接照着操作的参考。先想清楚你要解决什么问题再决定要不要入这套方案。我的场景很简单不想把内部资料传上云端又想要一个能基于自己文档做智能问答的入口。试过几个方向要么是纯向量库太原始要么是全托管的 SaaS 把数据拿走。WeKnora 属于“既要又要”的路线——本地跑大模型本地存知识库本地做检索整套链路自己掌握数据库、模型、接口全在局域网里。1. 为什么是 WeKnora从选型到硬件准备1.1 本地知识库问答的三种常见路线动手之前我先把自己的选项理了一遍。市面上做知识库问答的开源方案大致三条路纯向量库 调 API、本地部署大模型 RAG 框架、全家桶知识库平台。纯向量库看着简单Chroma、Qdrant 配个 Embedding 模型就能跑但问答链路要自己拼从切分文档、算向量、存数据库到检索、拼 Prompt、调模型每一步都要自己写代码。RAG 框架像 LangChain、LlamaIndex 能省不少事可对新手还是太碎经常一个版本升级就把链路搞崩。全家桶平台像 Dify、FastGPT 也有本地部署版功能确实全但我这种需求还要装一堆插件和中间件多少有点重。WeKnora 恰好是第三种里的例外它把「知识管理」和「问答」做成了两个清晰的产品模块跟 RAG 那套“临时拼装”的思路不太一样。对我这种文档管理需求大于花哨功能的人来说“先管理知识、再回答问题”的定位让我很受用。而且它整个项目里可以透明看到处理流程后续自己做二开或者接内部系统都方便。1.2 我的硬件配置与部署架构既然要本地部署大模型硬件先要过关。我手上这台机器用了挺久CPU 是 Intel i5-12600KF内存 64GB显卡是 RTX 4070 Ti SUPER 16GB。这个配置跑 7B 到 14B 量级的量化模型是够用的如果只跑 7B 模型显存 8GB 也能凑合。实测下来 16GB 显存刚好能把 Qwen2.5 7B 的量化版 Embedding 模型 上下文窗口都塞进去不爆显存。部署架构上我的规划是WeKnora 负责知识库和问答逻辑Ollama 负责跑模型推理Elasticsearch 负责向量检索和文档存储。三个服务都在本机跑通过 Docker Compose 串联起来。WeKnora 默认需要 Elasticsearch 存向量数据这一点跟很多“轻量”方案不太一样但 ES 带来的检索质量和扩展性是 SQLite 级别的方案给不了的。如果你文档量小到只有几百个杀鸡用牛刀但既然上全家桶了提前把量考虑进去。2. WeKnora 部署实战从零到能跑起来2.1 环境准备与 Ollama 部署先把基础环境准备好。我用的是 Ubuntu 22.04Docker 和 Compose 都得在。WeKnora 官方推荐用 Docker 部署因为 Python 依赖和系统库比较多直接裸机装太容易踩版本冲突的坑。Ollama 的部署很简单一条命令的事。装完之后第一件事就是拉模型。我试过几个模型最终留下来的是qwen2.5:7b中文能力在这个体量下算不错的。拉模型的命令ollama pull qwen2.5:7b这里有个细节容易被忽略Ollama 默认监听127.0.0.1:11434但 WeKnora 跑在 Docker 容器里它访问 Ollama 得通过宿主机 IP。如果你不想每次改 IP可以通过--network host启动容器或者配置环境变量让 Ollama 监听所有网卡。生产环境我建议设一个受控的局域网 IP 加端口别直接裸奔到公网毕竟大模型接口要是被人扫到了就是免费给别人跑算力。Embedding 模型也在 Ollama 里跑。我用的是bge-m3效果稳定对中文长文档的语义理解比早期的一些模型好不少。拉下来之后先手动测一下能不能正常出向量别等 WeKnora 配好了才发现模型没拉对。我踩过这个坑启动时总是报连接失败最后发现是模型名拼错了白花半小时。2.2 启动 WeKnora 的完整流程WeKnora 的安装是标准的 Docker Compose 流程。先把项目代码克隆到本地我习惯把数据目录统一放在/opt/weknora下方便以后备份和迁移。目录结构基本长这样weknora/ ├── docker-compose.yml ├── .env ├── elasticsearch/ │ └── data └── weknora/ └── logs.env文件里要改几个关键变量ES_URL指向 Elasticsearch 地址LLM_API_BASE指向 Ollama 的地址。因为我在 Docker 里跑 WeKnora宿主机 IP 就是默认网关地址我直接写成了http://宿主机IP:11434这是最容易出问题的地方之一。如果你在docker-compose.yml里单独定义了 Ollama 服务也可以用服务名访问看你怎么组织 Compose 编排。确认配置没问题后跑下面的命令拉镜像并启动docker compose up -d第一次启动会自动拉 Elasticsearch、WeKnora 等镜像时间取决于你的网络速度。这里要说一个很重要的耐心问题——ES 启动特别慢我第一次看日志以为卡死了实际上 ES 在初始化内存锁和分片日志要等一两分钟才会出现关键信息。别一看没反应就去docker restart容易把 ES 的分片状态弄脏。启动成功的标志不是容器状态是 Up而是 WeKnora 的日志里出现了类似Application startup complete的字样并且你访问http://localhost:8080能看到登录页。如果看到 502 或者连接拒绝先去看 ES 是否健康再看 WeKnora 的日志绝大多数初始化失败都和 ES 没起来有关。2.3 首次登录与连接大模型WeKnora 默认会初始化一个管理员账号。不同版本可能不一样我用的这个版本是首次登录后强制改密码避免默认口令打穿公网部署。进去之后第一件事就是去「模型配置」里把 Ollama 连接好。配置界面有点像一个简化的 OpenAI 兼容接口配置页。你要做的就是把 Base URL 改成 Ollama 的地址比如http://192.168.1.100:11434/v1然后在模型列表里选qwen2.5:7b和bge-m3。这里要注意Ollama 其实提供的是 OpenAI 兼容接口WeKnora 就是通过这个兼容接口调用它的所以不要纠结“为什么我填的不是 Ollama 原生地址”。接好模型之后建议先在对话页面手动发一句测试。我当时发了一句“介绍一下你自己”如果模型能正常回复说明基础链路已经通了。这时候再回去建知识库就会顺很多。如果对话报错优先查 Ollama 的日志和 WeKnora 的日志看错误信息里有没有模型名、鉴权或者超时相关的关键词。3. 知识库搭建与问答配置不是上传文件就完事3.1 文档上传与知识处理链路通了之后真正花时间的是知识库的建设。WeKnora 支持多种格式上传txt、Markdown、PDF、docx 等。我第一批传的是几十篇技术文档和个人笔记。上传后它会经历几个处理阶段文档解析、文本切分、向量化、索引写入。这里有个跟很多 RAG 框架不一样的地方——WeKnora 的定位不只是“给 LLM 提供参考片段”它还带了一套知识管理功能比如实体识别、知识抽取。这些听起来很“专业”但实际对问答的上下文理解帮助很大尤其在“多篇文档相互关联”的场景下它能让大模型理解的内容更完整。上传之后系统会异步处理文档。处理速度和 CPU、内存有关我传的一批 PDF几十个文档处理了大概几分钟。期间你可以在界面上看到每个文档的状态如果一直卡在“待处理”多半是 Embedding 模型的问题。当时我检查才发现是 Ollama 并发能力太低bge-m3 生成向量的速度很慢后来调整了 Ollama 并发参数才快起来。3.2 关键配置参数top k、相似度阈值与 chunk 设置这部分是整个问答效果的分水岭。很多教程只说“上传文档就能问”但实际上检索参数调不好大模型再强也是答非所问。先看top k。这个参数决定每次问答从知识库召回多少个候选片段。默认值给得很保守我实际测试下来在文档量 100 篇以内的场景top k 取 5~8 比较合适。太低会漏掉关键信息太高会把无关片段塞进上下文干扰模型判断。文档越碎top k 越要大一点因为单段的信息量小只能靠数量堆。再看相似度阈值。低于阈值的片段会被当作不相关丢弃。这个值我用的是 0.5 左右。如果文档专业性很强术语多阈值适当调低因为向量匹配本身会对专业词不那么敏感。反之如果都是大白话文档阈值可以调高一点减少噪声。这个参数没有绝对标准你要靠自己文档的实际情况去试我建议调参的时候围绕几个典型问题反复测别拿一个测试集跑完就下结论。chunk 大小我也是反复琢磨之后才定下来。chunk 不是越大越好——太大了语义信息混杂向量表达不聚焦太小了又切碎上下文模型读不出完整意思。我最终用的是 300 到 500 字左右配合一定比例的 overlap让相邻片段之间有过渡。这个值在 WeKnora 里可以设置但要注意改完 chunk 设置后原来已经处理过的文档不会自动重新切分你得删除重建索引否则改动不生效。3.3 系统提示词的设置技巧除了检索参数提示词对回答质量的影响也很大。WeKnora 里可以配置问答时的系统提示词。我反复改了几版最终沉淀下来的一套是明确角色设定要求模型优先基于知识库内容回答如果知识库没有覆盖就如实说明不要编造。加一句“在回答时引用或复述知识库中的关键内容”特别重要——这能让回答更贴文档原文而不是大模型自行发挥的“话疗”。提示词不用写得像长篇作文简洁的约束反而有效。我最早写了一大段解释效果反而不如后来精简版的好。关键是让模型知道边界在哪里哪些内容能说哪些内容不能说以及能不能把多个来源的信息综合起来。实测下来明确的边界描述可以明显减少幻觉答案尤其是涉及数据、版本号这些硬信息的问题。4. 性能调优与踩坑实录4.1 显存占用与推理性能实测整套系统跑起来之后我盯着监控面板看了一下午把 CPU、内存、显存的使用情况都记录了一遍。Ollama 里同时加载了 Qwen2.5 7B 和 bge-m3显存占用大概在 9GB 到 11GB 之间浮动。这个水平在 16GB 显卡上还有余量如果你想换更大的模型或者开更大的上下文也能撑得住。问答延迟方面单轮回答的冷启动时间相对长一点因为模型需要重新加载上下文。一旦首轮加载完之后后续回答基本在每秒 20~30 token 的生成速度体感两到五秒内能收到完整回答。如果觉得响应慢检查一下是不是把 Embedding 模型和 LLM 同时塞在一块显存里抢资源了这种情况下可以考虑给 Ollama 限制模型并发数或者把 Embedding 单独部署。实测有效。CPU 和内存方面Elasticsearch 是比较吃内存的我给 JVM 堆设了 4GB系统总占用保持在 12GB 到 16GB 之间。如果你机器内存只有 16GB跑这套会比较紧建议至少 32GB这样 ES 堆可以给到 4GB~6GBWeKnora 自身还能留足余量。4.2 遇到的几个坑和解决办法这个部分算是重头戏我把整个部署过程中遇到的坑按“症状 - 原因 - 解决办法”整理了一遍你在实操时大概率也会撞上一两个。症状原因解决办法WeKnora 界面打不开502 错误ES 还没启动完成查看 ES 日志等待started日志出现再刷新页面文档一直卡在处理中Embedding 模型没连通或并发过低检查模型配置调大 Ollama 的OLLAMA_NUM_PARALLEL问答回复明显答非所问相似度阈值过低噪声片段进入上下文调高阈值降低 top k删除旧索引重建Ollama 连接失败Base URL 写成localhost改成宿主机实际 IP确认端口可达模型回答长篇大论且不贴文档系统提示词约束不够加入“只基于知识库内容回答”的明确指令上传 PDF 后内容乱码扫描版 PDF 缺少 OCR 支持先转成文本或用带 OCR 的工具预处理有两个问题我想单独拎出来说一下。一个是并发参数。Ollama 默认的并发数很低多进程同时调用时会出现队列堆积。我在启动 Ollama 时配置了更大的并发数实测在多人问答场景下体验提升很明显。另一个是端口占用。我机器上有一个旧服务占了 8080启动 WeKnora 虽然没报错但始终访问不了。查了半天才发现是端口冲突容器实际跑在别的映射端口上。4.3 知识库问答效果的关键经验问答系统跑顺之后我花了不少时间测试它在不同问题类型上的表现。整体来看明确问一个事实比如“XX 文档里定义的接口协议是什么”回答得最稳基本能给出准确答案且附上来源。综述类问题比如“这套系统的整体架构是怎么设计的”也能回答但它依赖检索到的片段是否覆盖了足够的维度。如果某个维度在检索阶段就被漏掉了它会很干脆地漏答而不是主动联想补齐。还有一类是跨文档关联问题。这种问题单靠向量检索很难。WeKnora 的知识图谱能力在这种场景下能帮上忙但我个人觉得还有很大潜力。简单说它能把文档里的实体和关系抽出来形成一个结构化网络当问题问的是“哪些文档提到了某个共同概念”时效果比纯向量召回要精准。不过实际用起来我发现要充分发挥这个能力对文档本身的质量要求很高描述太含糊的文档抽出来的图谱也比较鸡肋。另外一个很多人都想知道的问题是能不能用 DeepSeek 或者其他模型替代默认模型可以。WeKnora 走的是 OpenAI 兼容接口只要你的模型服务暴露了兼容接口模型名填对就行。Ollama 里跑 DeepSeek 蒸馏版、Qwen、甚至开源 llama 系都没问题。我试过切换 DeepSeek 系的量化模型整体链路不用改只换了模型名。但要注意不同模型对提示词的敏感度不同切换模型之后回答风格的差异会很大需要重新微调提示词别指望零成本平替。最后再分享一个实战小技巧建议你在静态资源上传完了、问答链路调通之后自己整理一份“我在用的几个核心问题测试集”里面覆盖事实查询、列表归纳、对比分析、跨文档查询这几类。以后每次改参数或者换模型先用测试集跑一遍不要凭感觉判断效果。这样能让你每次改动都有明确的数据反馈而不是靠玄学调参。整套跑下来我的体感是 WeKnora 的核心思路是对的——知识管理是问答质量的地基地基没打好模型再强也白搭。它把这块做得比其他 RAG 玩具扎实不少而且文档处理流程透明、配置灵活适合我这种愿意花时间打磨细节的人。如果你想搭一套私有的知识库问答系统并且愿意接受它需要一定的学习和调参成本这套方案值得一试。