WeKnora 快速上手指南：5 分钟把散落文档变成能问答的知识库

WeKnora 快速上手指南：5 分钟把散落文档变成能问答的知识库

【免费下载链接】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

WeKnora 是一个开源的 LLM 知识平台：把原始文档变成可检索的 RAG 问答、自主推理的智能体和自维护的 Wiki。它解决的核心问题是——你的资料躺在各处，搜不准，问不倒，还得靠人手工整理。

从图中可以看到整体分层：输入渠道层（Web UI、API、IM 机器人）→ 核心引擎层（文档处理 + RAG 问答 + ReAct Agent）→ 存储层（PostgreSQL、向量库、Neo4j），每个组件都可替换，LLM、向量库、存储后端都能换成你自己的。

它解决什么问题：资料散落、搜不到、问不倒

先说三个很常见的场景。

一是资料散落各处：产品文档在网盘，操作手册在飞书，FAQ 在 Wiki，新人入职只能一个个翻。二是搜不到：传统搜索靠关键词，你问"怎么改密码"，文档里写的是"修改登录凭据"，搜不出来。三是问不倒：好不容易搜到了，还得自己读、自己拼答案，跨多个文档的问题基本无解。

WeKnora 把这三步合并成一条流水线：输入是文档（支持 PDF、Word、Excel、PPT、Markdown、图片等 10+ 种格式），处理是解析 → 分块 → 向量化入库，输出是能直接提问的对话入口，回答还带可点击的引用，点一下就跳回原文。

这意味着你可以把整个部门的文档一次性喂给它，之后无论是新人提问还是跨文档的复杂问题，都有带出处的答案——而且部署在本地或私有云，数据不出门。

上图是智能问答界面：回答正文里有引用角标，点开引用抽屉能看到每条答案对应哪份文档，检索的是知识库还是联网来源也做了区分。

5 分钟跑起来：最简部署路径

前置条件只有 Docker 和 Git。完整命令在 README 的 Getting Started 章节，跑通所需的最简步骤：

git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env docker compose pull docker compose up -d

浏览器打开http://localhost即可：注册一个账号（会自动得到一个属于你的工作空间），建知识库、选对话模型和向量模型（本地 Ollama 或任意 OpenAI 兼容 API 都行），上传文档，等解析完成就能提问。

想要知识图谱、对象存储、链路追踪这些可选组件，加--profile参数即可，比如docker compose --profile neo4j up -d启用知识图谱。

这意味着你不需要改一行代码，十几分钟就能有一个能回答自己文档内容的最小闭环。

核心机制拆解：分块和检索两条流水线

机制一：自适应三阶段分块。

输入一份文档，先跑一个"文档分析器"统计结构特征（Markdown 标题数量、分页符、多语言章节标记等），再从三档策略里选最合适的一档：

• heading：Markdown 风格文档，在#/##/###边界切，每块还带上"面包屑"标题路径
• heuristic：PDF 风格文档，按分页符、编号章节切
• legacy（递归切分）：兜底，默认 512 字符、50 字符重叠

用切菜的类比：不是所有菜都切丁，鱼片肉丝要区别对待，auto模式就是先看看这是哪种食材再下刀。官方基准测试（Vecta 2026-02，50 篇论文）里，512 token + 15% 重叠的递归切分拿到了 69% 端到端准确率，是单项最优基线，WeKnora 在此基础上叠加结构感知。详见 docs/CHUNKING.md。

这意味着同一套配置能同时管好 FAQ、Markdown 文档和 PDF 报告，不用为每类文档单独调参。

机制二：多路混合检索管线。

一次问答请求进来后走的事件驱动管线是：查询改写 → 并行检索（BM25 关键词 + 密集向量）→ 重排序 → 融合合并 → 截断 → 流式生成回答。类比一下：不是让一个图书管理员去找书，而是派多个渠道同时找（关键词查、语义查），再请一个"裁判"（重排模型）把最相关的排前面，最后才交给 LLM 作答。

上图展示了数据准备、查询检索、生成响应三个阶段的整体流程。这条管线还支持断线续传：生成结果走独立的 StreamManager，页面刷新或网络抖动后可以从断点继续读。

这意味着即使你的问题措辞和原文不一致，靠向量这一路也能捞回来；而重排把噪声压下去，答案的出处更靠谱。

一个真实场景走一遍：上传产品手册，问操作问题

按 快速上手文档 的完整流程走一遍，每一步都能在仓库文档里找到对应截图。

给什么：一份产品手册 PDF，加一个可用的对话模型 + 向量模型。

项目做什么：上传后文档异步解析，状态依次是pending → processing → finalizing → completed，列表页实时刷新进度；解析即分块，按该知识库配置的策略切片并生成向量索引。解析完成后进对话页选上这个库，直接提问。

得到什么：一条带引用角标的回答。点角标跳到原文对应位置，可以逐条核对答案出处。如果要更复杂的问题（"对比 A 和 B 两种配置的区别"），切到"智能推理" Agent，它基于 ReAct 架构，自己决定检索几轮、要不要联网、要不要调工具。

到这里，从"一份 PDF"到"能问答、带出处"的最小闭环就完整了。

值得调的几个参数：config.yaml 里的三个旋钮

默认配置在 config/config.yaml，以下三个最值得先看：

knowledge_base: chunk_size: 512 # 分块大小 chunk_overlap: 50 # 块间重叠 conversation: embedding_top_k: 30 # 向量检索取回条数 rerank_threshold: 0.3 # 重排准入阈值

调优方向（依据 docs/CHUNKING.md 的设置参考表）：

• chunk_size：FAQ / 原子问答建议 200–400，叙事长文 1000–2000，一般文档保持 512
• chunk_overlap：FAQ 和结构化记录可以设 0，论证跨块的长文给 150–200
• rerank_threshold：答案精度优先就调高，召回优先就调低并配合更大的embedding_top_k

注意一点：向量模型建库后不建议更换，换了要重建索引，初始化向导里也做了限制。

适合谁，以及下一步

一句话选型建议：如果你需要把私有文档变成可问答的知识库，且要求数据留在自己手里，WeKnora 是目前少数能同时覆盖 RAG 问答、Agent 推理和 Wiki 三种形态的开源方案。

接下来按你的诉求挑扩展方向即可：接飞书 / Notion / 语雀 / RSS 自动同步文档，把问答接到企业微信、飞书等 IM 里，或者用官方 MCP Server 把 29 个工具挂给你的编程助手。更远的规划——Lite 轻量化版本、语义分块、时序知识库——见 docs/ROADMAP.md，完整文档在 website-docs/。

克隆下来跑一遍，从你自己的第一份文档开始问起来。

【免费下载链接】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