从文档到可查询知识库：WeKnora 搭建企业 RAG 问答系统的 5 个关键步骤

从文档到可查询知识库：WeKnora 搭建企业 RAG 问答系统的 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 知识平台，能把 PDF、Word、网页以及飞书、Notion、语雀里的资料收进知识库，再通过 RAG 检索增强与智能体推理回答你的问题，答案自带出处。本文用 5 个关键步骤，带你从零搭建一套企业级 RAG 问答系统，并避开部署与调优路上最常见的几个坑。

一、先看结论：三种部署形态怎么选

动手之前先做选择题。WeKnora 的部署形态从轻到重分三档，选错了后面会走不少弯路：

给你的建议：只想快速验证"这个工具适不适合我们"，直接跑 Lite；准备长期当团队知识底座，一步到位用 Docker Compose，别用 Lite 顶生产——标准版才有共享空间、多解析引擎和完整审计能力，两者差异见 docs/LITE.md。

二、最小可用：10 分钟跑通第一个知识库

先建立最小闭环，再谈优化。标准版部署方式如下（仓库地址：https://gitcode.com/GitHub_Trending/we/WeKnora）：

git clone https://gitcode.com/GitHub_Trending/we/WeKnora && cd WeKnora cp .env.example .env # 编辑 DB_USER / JWT_SECRET / SYSTEM_AES_KEY 等必填项 docker compose up -d

等所有服务变 healthy 后打开http://localhost，按下面 5 步走完一遍：

1. 注册账号：系统没有内置默认账号，首个注册用户会自动获得一个工作空间并成为 Owner；
2. 创建知识库：选document（文档库）或faq（问答对库），随后进入初始化向导；
3. 配置模型：至少选一个对话模型（LLM）和一个向量模型（Embedding），用向导里的"测试"按钮确认连通；
4. 上传文档：拖入 PDF、Word 或粘贴网页 URL，等待异步解析完成（状态依次为 pending → processing → completed）；
5. 提问：在对话页选择该知识库直接提问，回答会带可点击的出处引用。

到第 5 步，你的第一个知识库问答闭环就跑通了。

三、进阶调优：让回答更准的 3 个旋钮

很多人跑到上一步就停了，结果发现回答质量不稳定。想让准确率上一个台阶，重点调这三个地方：

旋钮一：分块策略。默认分块大小 512、重叠 50，对多数文档够用；但表格、扫描件、长章节文档往往需要按结构切分。WeKnora 支持父子分块与自适应策略，还能在界面上直接编辑检索分块、对比版本并一键回滚，改完自动重建索引——这是排查"某段内容永远检索不到"的最快手段。

旋钮二：混合检索与重排。单一向量检索召回不稳定，建议开启"向量 + 关键词（BM25）"混合检索并用 RRF 融合，再叠加 Rerank 重排。实测把enable_rerank打开后，长尾问题的命中率提升非常明显，代价只是每次问答多一次重排调用。

旋钮三：模型选型。LLM 可以随时换、随意试，但Embedding 向量模型建库后不要换——换了需要全库重建索引。选型时优先用和你的文档语言、领域匹配的向量模型，维度建议直接对齐 1024 维 HNSW 索引支持。

相关配置项集中在 config/config.yaml，对话管线参数（检索条数、阈值、兜底策略）都在conversation段。

四、生产落地：从单机到团队协作的 4 件事

内测通过后，真正决定成败的是下面 4 件事：

1. 数据自动进来。别让同事手动传文件。WeKnora 支持飞书知识库、飞书云盘、Notion、语雀、RSS 等数据源定时同步，支持增量与全量两种模式，配置一次后知识库会自己保持新鲜。

2. 权限与协作。团队用起来后立刻上多空间 RBAC：四级角色（Owner / Admin / Contributor / Viewer）加按知识库的资源归属，配合每空间审计日志，谁看了什么、改了什么都有迹可循。

3. 可观测性。接入 Langfuse 全链路追踪，观察每次问答的检索片段、Token 消耗和工具调用。回答质量波动时，这是定位"是检索问题还是模型问题"的唯一可靠手段。

4. 私有化与安全。数据敏感就别放公网。WeKnora 支持全栈私有部署，API Key 与数据源凭据以 AES-256-GCM 加密落盘，docreader 走 gRPC TLS，前端默认仅本机访问。生产环境记得：关闭公开注册、启用邀请制、为部署配置防火墙。

五、三个最常见的坑（都是真实踩过的）

• 容器连不上本地 Ollama：后端跑在容器里时，填http://localhost:11434是连不上宿主机的，要用http://host.docker.internal:11434；
• 改了环境变量没生效：部分开关（注册模式、SSRF 白名单、并发上限）一旦在"设置 → 系统"界面改过，就会写入数据库并盖过环境变量，排查时先看运行时的系统设置，别只顾着改.env；
• 升级后版本没变化：只执行docker compose up -d会复用本地缓存镜像，升级前先docker compose pull，或在.env里锁定WEKNORA_VERSION。

下一步行动

先别急着追求完美配置。今天就用 Lite 或 Docker 版跑通"上传一份真实文档 → 问一个真实问题 → 核对出处"这个闭环，再按第三节的三个旋钮逐个调优。确认可行后，再上数据源同步、RBAC 与 Langfuse。想知道更深层的原理，推荐顺着两条线读下去：检索与分块机制见 website-docs/03-features/，API 对接与 CLI 用法见 cli/README.md 和 docs/api/README.md。文档变成可查询的知识资产，从这 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