WeKnora RAG 知识库上手指南：从文档到智能问答的完整路径
项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora WeKnora 是一款开源的 RAG 知识库与智能问答系统，把散落的文档变成可检索、可推理的知识资产。如果你手上有成堆的 PDF、Word、Wiki 页面，又不想从零搭向量数据库和提示词工程，WeKnora 部署后开箱即用：上传文档即可问答，还能跑自主推理代理和自动 Wiki 生成，支持本地与私有化部署，数据留在自己手里。
它到底是什么
一句话定位：把文档变成"活"的知识——能问（RAG 快速问答）、能想（ReAct 智能体）、能自己写 Wiki。
适合谁：
- 新手/业务人员：零代码，网页端上传文档、提问、看引用
- 开发者：提供约 360 个 API 端点、
weknoraCLI 和 MCP Server，方便接入现有系统 - 技术决策者：多租户 RBAC（Owner/Admin/Contributor/Viewer 四级角色 + 空间级审计日志）、完全自托管，满足数据主权要求
架构总览（输入渠道 → 核心引擎 → 存储后端，每一层都可替换）：
核心能力地图
| 能力块 | 具体提供什么 | 入口/位置 |
|---|---|---|
| 文档解析 | PDF、Word、Excel、PPT、图片等 10+ 格式，含 OCR 与多模态 | docreader/ |
| RAG 快速问答 | 多知识库问答、引用溯源、问题推荐 | Web UI / API |
| ReAct 智能体 | 自主编排检索、MCP 工具、网络搜索，多步推理 | internal/agent/ |
| Wiki 模式 | 代理自动把文档蒸馏成互联的 Markdown Wiki，可编辑、有版本回滚 | Web UI |
| 数据源同步 | 飞书/飞书云盘、Notion、语雀、RSS 自动同步 | internal/datasource/connector/ |
| IM 渠道 | 企业微信、飞书、Slack、Telegram、钉钉、Mattermost、QQ 机器人等 9 类 | internal/im/ |
| 模型与检索后端 | 20+ LLM 提供商；PostgreSQL、Qdrant、Milvus、Weaviate、OpenSearch、Doris、Tencent VectorDB 等 | docs/使用其他向量数据库.md |
| 可观测性 | 集成 Langfuse 追踪推理链与 token 用量 | docs/Langfuse集成.md |
| 编程接入 | 带作用域 API Key、MCP Server、Go/Python 客户端、CLI | mcp-server/、client/、cli/ |
运行机制拆解
一条主链路：文档进 → 索引 → 检索 → 生成。
索引：解析、分块、向量化
文档先由解析服务拆成文本（扫描件走 OCR/多模态），再按分块策略切分、算嵌入向量入库。默认参数在 config/config.yaml 里：chunk_size: 512、chunk_overlap: 50。
亮点是自适应分块，四种策略见 docs/CHUNKING.md：
- auto（推荐）：先给文档"画像"（标题数量、分页符、章节标记），再自动挑最优策略
- heading：按
#/##/###边界切 Markdown 文档，并在嵌入时给每块加"面包屑"路径，让向量带上章节上下文 - heuristic：针对 PDF，识别分页符、编号章节、多语言章节标记
- legacy：传统递归切分，兜底用
检索：四路混合
问题进来后不是只查向量库，而是多路召回再融合：
- 关键词/BM25 稀疏检索
- 密集向量语义检索
- 知识图谱实体关联检索（可选，依赖 Neo4j）
- 重排序（Rerank）打分 + 阈值过滤
配置里还默认开启了查询改写和查询扩展，先把口语化问题改写成更适合检索的形式。
生成：流式输出 + 智能体编排
RAG 模式把命中片段拼进上下文模板（config/prompt_templates/ 下全是可热改的提示词 YAML），走 SSE 流式吐答案，并附引用来源。智能体模式则基于 ReAct 循环：思考 → 调工具（检索/MCP/搜索）→ 观察 → 再思考，多步完成任务；技能执行放在沙箱里隔离。
三步跑起来
第一步：克隆仓库并准备环境
git clone https://gitcode.com/GitHub_Trending/we/WeKnora
cd WeKnora
cp .env.example .env
第二步：一条命令拉起服务栈
docker compose up -d
docker-compose.yml 里默认包含前端（80 端口）、应用（8080 端口）、PostgreSQL、Redis、文档解析服务等。前端起来后浏览器打开 http://localhost 即可。
需要可选组件时按 profile 追加，比如知识图谱、对象存储、可观测性：
docker compose --profile neo4j --profile minio --profile langfuse up -d
个人/小团队想更省事，可以看 docs/LITE.md 里的 Lite 版：单应用、零外部依赖、本机开箱即用。
第三步：配置模型并导入第一个文档
在 Web 端"设置"里填入 LLM 提供商的 API Key（支持 OpenAI、DeepSeek、通义千问、智谱、腾讯混元、Gemini、Ollama 等 20+ 家）。如果想声明式地预置一批内置模型，把 config/builtin_models.yaml.example 复制为 builtin_models.yaml 再按 docs/BUILTIN_MODELS.md 说明填写。
之后：新建知识库 → 上传文档（选解析引擎与分块策略）→ 等索引完成 → 开始提问。
典型落地场景
场景一：企业知识库问答
文档型知识库支持批量导入，文件夹树保留上传目录结构；命中片段可直接编辑并留版本。
问答界面右侧给出引用来源，答案可追溯：
场景二：IM 里直接问
把渠道挂到工作空间后，团队在企业微信、飞书、Slack 里 @机器人 就能查知识，不用切换系统。
智能体模式下工具调用过程对用户可见，多步推理不再"黑盒"：
场景三：让代理替你写 Wiki
Wiki 模式把原始文档蒸馏成结构化、互链的 Markdown 页面，配可视化知识图谱；页面可手动编辑，有行级 diff 和一键回滚，适合沉淀部门级知识。
调优与避坑
检索参数怎么调
关键项都在 config/config.yaml 的 conversation 段：
conversation:
embedding_top_k: 30 # 向量召回条数
rerank_top_k: 30 # 参与重排序的条数
vector_threshold: 0.2 # 向量相似度阈值
rerank_threshold: 0.3 # 重排序阈值
经验法则：答案被截断 → 调大 top_k；答非所问 → 阈值适当调低，再不行开启/关闭 rerank 做 A/B。每个知识库还可以单独指定模型，便于按库切换。
分块策略选择 + 一个必知的坑
docs/CHUNKING.md 给了按文档类型的建议值：FAQ 库 200–400 字符、Markdown 文档 512、带分页符的 PDF 报告 800–1200、长篇叙事 1000–2000。
坑：切换分块策略不会自动重建索引，改完需要让存量文档重新解析/索引才能生效，别以为改完立刻生效。命中片段不满意时，可在界面上直接编辑 chunk，系统自动重索引，改动有版本可回滚：
其他常见坑
- 模型不匹配：嵌入维度要和向量库一致（如
weknora_embeddings_768这类按维度建的集合），换嵌入模型前确认维度 - IM 里图片显示不出来：存储后端需公网可达，或按 docker-compose.yml 注释配置
APP_EXTERNAL_URL - 看不清代理为什么这么答：开 Langfuse（
--profile langfuse），推理链、token 消耗、管道耗时全链路可查 - 升级/迁移出问题：先看 docs/migration-troubleshooting.md
生态 · 路线图 · 选型建议
下一步往哪走
按 docs/ROADMAP.md，方向主要有四块：
- 轻量化：Lite 版与原子化接口（Embedding/Rerank/解析单独调用），降低试用门槛
- 知识理解：语义/章节级分块、文档结构可视化、音视频等多模态格式
- 检索体验：输入框 @标签指定检索范围、上传图片附件检索
- 生态：Chrome 剪藏扩展、JS SDK、小程序插件、编辑器插件（VSCode/Cursor 等）
周边生态现状：官方 MCP Server 提供 29 个工具（mcp-server/）、weknora CLI 覆盖日常运维、Kubernetes 用 helm/ 部署、client/ 提供 Go 客户端。
给不同角色的取舍
开发者：优先关注 API Key 作用域模型与 MCP 接入，把 WeKnora 当"知识中台"，而不是只当网页应用用；提示词模板外置在 config/prompt_templates/，改策略不用动代码。
技术决策者：数据主权（全自托管 + 多实例存储后端）、四级 RBAC 与空间级审计、Langfuse 可观测性，是评估私有化部署时的三个加分项；团队规模小就先上 Lite 验证，需要协作再切标准版。
新手：别一上来调参数。先跑通"上传 → 问答"，确认解析质量没问题，再按上面分表调 chunk，最后才动检索阈值——顺序反了会互相干扰，不好定位。
结语
WeKnora 把"文档 → 知识库 → 问答/推理/Wiki"整条链路打包好了，部署三步、配置模型、导入文档，当天就能看到效果。建议你先从最常用的一批文档建一个知识库，用真实问题检验回答质量，再按需开启智能体、IM 渠道和知识图谱。把文档跑起来，比把参数调完美更重要——现在就可以动手了。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
