从零到一搭建企业文档知识库：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/WeKnora如果你手头攒了一批 PDF、Word、Markdown同事每天在群里重复问同样的问题而你试过把文档直接丢给大模型、得到的却是半真半假的回答——那么这篇 WeKnora RAG 实战手记正是为你准备的。WeKnora 是一个开源的 LLM 知识平台核心能力就是把原始文档加工成可查询的 RAG 知识库、可自主推理的 Agent以及会自动维护的 Wiki。本文记录我一次真实落地过程从一台空机器开始到知识库上线、准确率调到可用全程约一个下午踩过的坑都写在里面了。一、故事从一次答不上来开始先说背景。我帮一个三十多人的团队搭内部知识库他们的资料并不少产品手册、排障记录、会议纪要、几十个版本的报价表散落在共享盘和聊天记录里。新同事入职第一周基本就是在问人和翻文件之间反复横跳。最开始的方案很朴素——把文档全塞给大模型让它直接答。结果可想而知模型一本正经地编造不存在的功能参数老员工看了直摇头。问题不在模型而在模型根本没读过你们的资料。它缺的不是知识是检索这一步先把相关片段从你的文档里捞出来再让模型基于这些片段作答。这正是 RAG检索增强生成要做的事也是 WeKnora 这类平台存在的意义。二、先把 RAG 这层窗户纸捅破RAG 听起来唬人拆开就四个环节WeKnora 把它们做成了全自动流水线解析把 PDF、Word、Excel 等二进制文档变成结构化文本扫描件还要走 OCR。这一层由独立的 docreader 服务负责相关代码在docreader/parser/。分块把长文本切成有边界感的小段。切太碎答不全切太大向量表达不准。默认 512 字符、重叠 80实现在internal/infrastructure/chunker/。向量化用 embedding 模型把每段文字转成向量连同关键词一起建索引方便后面做混合检索。检索 生成收到问题时先在库里做向量相似度 关键词混合召回再交给大模型组织成带出处的回答。之所以不能把整批文档直接喂给模型是因为上下文窗口有限、成本高、而且细节越多越容易胡说。RAG 的聪明之处在于每次只给模型看与问题最相关的几段既省 token又有出处可查。三、动手前的准备清单在开始之前先确认这几样东西齐不齐依赖要求说明Docker20.10含 Compose v2标准部署全靠容器编排最省心硬件建议 4 核 CPU / 8GB 内存起docreader 要跑 LibreOffice 和 Playwright比较吃内存对话模型LLMOllama 本地模型或任意 OpenAI 兼容 API负责组织回答如 qwen3、DeepSeek、通义等向量模型EmbeddingOllama 或远程 API负责理解语义如 bge-m3建库后不要更换模型可以用本地 Ollama 零成本跑起来也可以用云厂商的 API。至少需要一个对话模型和一个 embedding 模型两者可以来自不同服务商。四、分步实操从空机器到能问答的完整链路下面按步骤走顺利的话十几分钟就能跑通最小闭环。全程两种玩法网页界面点一点或者纯 API 脚本我都演示一遍。步骤一一键拉起整套服务克隆仓库并启动仓库地址为 https://gitcode.com/GitHub_Trending/we/WeKnoragit clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env # 按需修改数据库密码、JWT_SECRET 等 make start-all # 等价于 scripts/start_all.sh docker compose ps # 等所有服务变成 healthy/running启动后用一条命令确认后端活着curl http://localhost:8080/health # 期望返回 {status:ok}前端默认在http://localhost首次访问会落到注册页。 提示.env文件不存在会导致 Compose 解析失败make start-all会自动从示例文件兜底但部署前务必把里面的默认密码换掉。步骤二注册账号创建第一个知识库系统没有内置默认账号。在登录页的注册页签里创建账号注册完成后会自动生成一个属于你的工作空间你就是这个空间的 Owner。登录后点新建知识库填名称类型选document普通文档库faq是问答对库。接着在弹出的初始化向导里做两件关键的事选对话模型回答问题时用选向量模型文档转向量用保存后不要再换换了必须重建索引否则检索结果会牛头不对马嘴Rerank、VLM 等其余能力先不开之后随时能加。向导里带测试按钮保存前先确认模型连得通。⚠️ 注意后端跑在容器里时填http://localhost:11434是连不上宿主机 Ollama 的必须用http://host.docker.internal:11434。这是新手第一坑几乎人人都会踩。步骤三上传文档看它被消化进入知识库把文件拖进上传区即可支持 PDF、Word、Excel、PPT、Markdown、HTML、EPUB、图片、音频等十多种格式也可以直接粘贴网页 URL。上传后文档进入异步解析状态依次是pending → processing → finalizing → completed。扫描版 PDF 会慢一些列表页实时刷新进度分块数一目了然。你可以点开任意一块查看切分效果——这是判断分块质量最直观的方式。步骤四提问看带出处的回答进入对话页选中刚建的知识库直接提问。默认走内置的快速问答Agent检索相关片段 → 交给大模型 → 返回带引用的回答。点回答里的角标可以跳回原文段落答案有没有依据一眼就能核验。到这里最小闭环就跑通了。步骤五用 API 走通同一条链路网页操作背后的每个动作都有对应接口统一前缀/api/v1。这段脚本可以直接复制运行适合以后做自动化集成BASEhttp://localhost:8080/api/v1 # 1) 登录取 JWT TOKEN$(curl -s -X POST $BASE/auth/login -H Content-Type: application/json \ -d {email:adminexample.com,password:pass123456} | jq -r .token) AUTHAuthorization: Bearer $TOKEN # 2) 创建知识库 KB_ID$(curl -s -X POST $BASE/knowledge-bases -H $AUTH -H Content-Type: application/json \ -d {name:我的知识库,type:document} | jq -r .data.id) # 3) 初始化以本地 Ollama 为例 curl -s -X POST $BASE/initialization/initialize/$KB_ID -H $AUTH -H Content-Type: application/json -d { llm: {source:local,modelName:qwen3:8b}, embedding: {source:local,modelName:bge-m3,dimension:1024}, documentSplitting:{chunkSize:512,chunkOverlap:80}} # 4) 上传文档 curl -s -X POST $BASE/knowledge-bases/$KB_ID/knowledge/file -H $AUTH \ -F file./demo.pdf # 5) 创建会话并发起知识问答SSE 流式输出 SESSION_ID$(curl -s -X POST $BASE/sessions -H $AUTH -H Content-Type: application/json \ -d {title:第一次对话} | jq -r .data.id) curl -N -X POST $BASE/knowledge-chat/$SESSION_ID -H $AUTH -H Content-Type: application/json \ -d {query:这份文档讲了什么,knowledge_base_ids:[$KB_ID]} 提示服务端集成建议用 API Key 而不是 JWT——在空间设置里创建支持细粒度权限retrieve/chat/ingest/manage_kbs等还能限定可访问的知识库比长期有效的登录令牌安全得多。五、进阶玩法把准确率从能用调到好用最小闭环通了之后真正的功夫在调优。以下是我实践下来性价比最高的几个杠杆按收益排序。1. 分块参数调优收益最大、成本为零答案好不好一半取决于文档被切成什么样。绝大多数场景默认值512 / 80就够了遇到下面这些情况再动手你遇到的问题建议做法回答缺上下文、经常答半句调大chunk_size或开启父子分块子块检索、父块回答命中的块跟问题关系不大调小chunk_size让每块主题更集中资料是条目式的FAQ、参数表重叠设为 0避免相邻条目互相污染资料是长篇叙述报告、论文重叠调到 150–200保住跨块语义连贯拿不准会切成什么样用分块预览接口POST /api/v1/chunker/preview试切不落库、免费试错改完分块配置后需要对已有文档重新解析才会生效这点别忘了。2. 打开 Rerank让排序更聪明单纯靠向量相似度召回偶尔会出现语义相近但答非所问的块排在前面。开启 Rerank 重排后系统会用专门的排序模型对召回的候选重新打分把最贴合问题的段落顶到前面。响应时间会多几十毫秒但对准确率的提升非常明显。相关参数在config/config.yaml的conversation段落rerank_threshold、rerank_top_k。3. 从快速问答升级到智能推理Agent快速问答是检索 → 回答的直线流程适合日常查资料。遇到对比这两个方案的优劣总结一下并列出依据这类需要多步推理的问题切换到内置的智能推理Agent它会自己决定检索几轮、要不要联网、要不要调工具甚至可以在对话里Skill / MCP限定这一轮的能力范围。下面这张图展示的就是 Agent 在检索与工具调用之间来回决策的过程4. 让知识库自己生长Wiki 模式这是我个人觉得 WeKnora 最有想象力的功能。开启 Wiki 模式后Agent 会把知识库里的原始文档蒸馏成结构清晰、互相链接的 Markdown 词条并在界面里生成可视化知识图谱——相当于给你配了一个 24 小时在线的资料整理员。之后新文档进来Wiki 会增量更新你可以在浏览器里手动编辑、查看修订历史、一键回滚。5. 实践中最容易踩的坑把上面那些坑汇总成一张速查表都是过来人用时间换来的现象原因与对策初始化时 Ollama 检测失败容器内要填http://host.docker.internal:11434Linux 需确认extra_hosts: host.docker.internal:host-gateway生效上传后一直processing看docker logs WeKnora-docreader单文件默认上限 50MB超时默认 2 小时问答没有引用、召回为空确认文档解析已完成调低vector_threshold检查 embedding 模型是否与建库时一致换了 embedding 模型后检索变差换模型必须重建索引旧向量与新模型不兼容API Key 请求返回 403Key 的 capabilities 不含所需能力或知识库白名单没包含目标库六、FAQ 与排查清单Q一定要自己部署吗有没有更省事的入口桌面版和 Lite 单二进制版本免注册、开箱即用适合个人和低资源环境团队级使用建议走 Docker Compose 标准部署。Q只有一台 2 核 4G 的云服务器能跑吗能但建议用 Lite 版SQLite 内存队列无 Redis/Postgres 依赖模型走远程 API 而不是本地 Ollama把内存留给 docreader。Q文档解析支持哪些格式扫描件能识别吗PDF、Word、Excel、PPT、Markdown、HTML、EPUB、图片、音频都支持扫描版 PDF 走 OCR。解析引擎的完整清单见docreader/parser/目录。Q多个人用怎么管权限支持工作空间 RBAC四层角色Owner / Admin / Contributor / Viewer知识库可指定归属人每个空间有独立的审计日志。部署后记得在设置里把公开注册关掉改用邀请链接加人。排查清单照着勾一遍curl http://localhost:8080/health返回 ok文档解析状态已是completed问答对话框选中的知识库正确Ollama 地址用的是host.docker.internalembedding 模型与建库时一致vector_threshold没有高到把结果全滤掉七、小结与下一步回顾一下这趟落地我们用 Docker 一键拉起服务通过网页和 API 各走通了一遍建库 → 上传 → 问答的完整链路再用分块调优、Rerank、Agent 和 Wiki 模式把能用提升到了好用。整个过程中最值钱的认知是RAG 的瓶颈往往不在模型而在你喂给模型的那几段文字质量——检索、分块、重排这些工程细节才是准确率的真正分水岭。下一步建议你这样做把你手上最头疼的那批文档不用多先来十几份按本文流程跑一遍重点感受两个地方——打开分块预览看看切得合不合理以及把同一问题分别抛给快速问答和智能推理Agent 对比答案质量。跑通之后想深入了解项目里有不少值得一读的资料docs/目录下的功能说明分块机制、检索引擎、RBAC 都在里面config/config.yaml是所有调参的入口源码层面internal/infrastructure/chunker/是理解分块策略的最佳起点。祝你的知识库早日上线让同事少问几遍这个在哪个文档里。【免费下载链接】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），仅供参考