五步跑通企业级 RAG：WeKnora 私有化部署实操手册

五步跑通企业级 RAG：WeKnora 私有化部署实操手册

【免费下载链接】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 问答、自主推理 Agent 和自动维护的 Wiki 三种形态，面向需要私有化部署、搭建多租户企业知识库的开发者。

它到底解决了什么

自建 RAG 的第一道坎不在模型，而在链路：文档解析、分块、向量化、混合检索、重排，任何一环粗糙都会让"答非所问"成为常态，而你很难定位是哪一环出了问题。第二道坎是文档本身散落——PDF 在网盘、Markdown 在代码仓库、流程文档在飞书和语雀里，每次问答前都要靠人肉搬运。第三道坎是可信度：答案没有引用出处，业务方无法判断它"编"了多少。

WeKnora 的定位：一套可 Docker Compose 一键落地的知识库 RAG 平台，内置 ReAct Agent 与自维护 Wiki，全组件可替换、可私有化。它不是一个向量检索库，也不是纯 Prompt 编排工具。

核心能力拆解：技术链路怎么走的

架构上把文档解析、向量化、检索、大模型推理拆成独立阶段，每一层组件可单独替换。

分块策略怎么选：三级自适应分块

输入原始文档，docreader 先做文档画像——统计 Markdown 标题、分页符、多语言章节标记等结构信号——再决定分块方式：heading模式沿#/##/###边界切分，切出的每个块在 embedding 前自动补上"顶层 > 章节"面包屑上下文；heuristic模式处理 PDF 分页符与编号章节；都不命中时回退递归分隔符分块。校验器会拒绝明显破碎的输出（例如产出 200 个单行块）并自动降级到下一级。

knowledge_base: chunk_size: 512 chunk_overlap: 50 split_markers: ["\n\n", "\n", "。"]

默认值直接来自 Vecta 基准测试结论：约 512 字符、15% 重叠的递归切分在 50 篇学术论文上拿到 69% 端到端准确率，是单一分块策略里的最强基线。

混合检索：四路召回加 LLM 重排

一次查询并行走四路：BM25 稀疏召回、稠密向量召回、知识图谱关联（需开 Neo4j）、重排序模型对融合结果智能排序。

流程分数据准备与索引、查询与检索、生成与响应三段；排查"为什么没答对"时，先看检索段命中了什么，再看生成段引用了哪些片段。

conversation: embedding_top_k: 30 vector_threshold: 0.2 rerank_top_k: 30 rerank_threshold: 0.3

RETRIEVE_DRIVER支持逗号分隔多向量库并行检索（PostgreSQL pgvector / Elasticsearch / Milvus / Qdrant 等），并行超时由MULTI_STORE_RETRIEVE_TIMEOUT_SEC控制。

ReAct Agent 与 Wiki：检索之外的两条路

引擎循环：LLM 决定下一步调用什么工具→执行→把结果塞回上下文继续推理。工具覆盖内置检索、MCP 工具（含 OAuth2 远程服务与人工审批闸口）、网络搜索；技能执行走 Docker 沙箱隔离。另一条是 Wiki 模式：Agent 从原始文档自治生成相互链接的 Markdown 知识库和可视化知识图谱，支持浏览器内人工编辑、行级 diff、版本历史与一键回滚——把"一次性问答"变成"可持续维护的知识资产"。

从零到跑通：最小部署五步

git clone https://gitcode.com/GitHub_Trending/we/WeKnora.git cd WeKnora cp .env.example .env # 改 DB/Redis 口令与 SYSTEM_AES_KEY docker compose pull docker compose up -d

1. 浏览器打开http://localhost，应出现注册页；http://localhost:8080/health返回 200 说明后端就绪
2. 注册账号，在设置页配置 LLM 与 Embedding 的 API Key
3. 新建文档型知识库，上传一份 PDF
4. 对着文档提一个问题，确认回答带引用浮层且可点击回到原文出处
5. 需要知识图谱或对象存储时再按需开：docker compose --profile neo4j --profile minio up -d

调优与进阶：遇到问题再动手

• 如果检索漏召回或引用不相关→调低vector_threshold（0.2→0.15）、调大embedding_top_k（30→50），改 config/config.yaml 后重启 app 容器
• 如果分块质量存疑→别急着全量重传：用知识库编辑器的分块侧边栏"样例文本测试"，先对同一段文本预览不同配置被拒的层级与块尺寸统计，再批量重解析
• 如果是 FAQ 类短知识库→分块改成chunk_size200~400、overlap 0、关闭父子分块，省一半存储
• 如果大批量导入排队太久→调大WEKNORA_ASYNQ_CORE_CONCURRENCY与BATCH_EMBED_SIZE（默认 8，见 .env.example B 区注释）

选型参考

先翻 website-docs/ 的快速开始，再对照 docs/api/ 做 API 集成。

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