WeKnora 文档
WeKnora(维娜拉)是腾讯开源的企业级知识库与 RAG(Retrieval-Augmented Generation)系统:Go 单体后端 + Vue 3 前端 + Python 文档解析微服务(docreader),支持多租户、多知识库、混合检索、Agent 智能体、知识图谱、Wiki 生成、MCP 集成、多平台 IM 接入与网页嵌入等能力。
本目录是 WeKnora 的完整官方文档,全部内容基于源码整理,按「入门 → 架构 → 功能 → API → 客户端 → 开发」六个部分组织。
文档站点
本目录同时是一个 VitePress 站点,Markdown 即页面,新增文件会自动进入侧边栏(标题取正文一级标题,目录顺序按文件名数字前缀)。
npm install
npm run dev # 本地预览
npm run build # 产物输出到 .vitepress/dist
npm run preview # 预览构建产物
主题位于 .vitepress/theme/:style.css 是排版与配色的单一来源,Landing.vue 是首页。
阅读路径建议
- 初次使用:01 快速开始 四篇按顺序读完即可完成部署与首次问答。
- 评估选型 / 了解原理:02 架构 五篇给出系统全貌与两条核心流水线(文档入库、检索问答)。
- 使用某项具体功能:直接查 03 功能模块 对应章节。
- 对接 API / 写集成:04 API 参考 + 05 客户端(CLI / Go SDK)。
- 二次开发 / 贡献代码:06 开发指南,尤其是扩展点指南。
目录
01 快速开始
| 文档 |
内容 |
| 产品介绍 |
WeKnora 是什么、核心概念(租户/知识库/知识/分块/会话/Agent 等)、功能总览与系统组件图 |
| 安装部署 |
docker-compose(含 12 个可选 profile)、开发模式、Helm、Lite 单二进制、macOS 桌面端、Homebrew |
| 快速上手 |
注册 → 初始化向导 → 配置模型 → 建库 → 上传 → 问答的完整路径,含可直接执行的 curl 链路 |
| 配置详解 |
config.yaml 全字段、约 150 个环境变量、prompt 模板、内置模型与内置 Agent 配置 |
02 架构
| 文档 |
内容 |
| 总体架构 |
组件构成、技术栈、进程间通信、顶层目录导览 |
| Go 后端设计 |
四层架构、uber/dig 依赖注入、启动与优雅退出、路由与中间件、领域模型 ER 图 |
| 文档入库流程 |
上传/URL/手动创建 → 存储 → 解析 → 分块 → 向量化 → 索引 → 后处理的全链路与状态机 |
| 检索问答流程 |
chat_pipeline 插件流水线、跨库检索与融合、重排、流式输出(SSE)与引用生成 |
| 异步任务系统 |
asynq 队列拓扑、6 个 worker pool、Lite 同步模式、死信与任务巡检、事件总线 |
03 功能模块
| 文档 |
内容 |
| 租户、用户与认证授权 |
多租户模型、JWT / API Key / OIDC、RBAC 角色矩阵、组织与共享空间 |
| 知识库与知识管理 |
知识库类型与全部可配置项、标签、预览安全、复制与移动、活动流、配额 |
| 文档解析服务 docreader |
gRPC 接口、三引擎注册表、13 个解析器矩阵、并发模型、部署与扩容 |
| 分块机制 |
自适应分块架构(heading/heuristic/recursive)、父子分块、ContextHeader、调试端点 |
| 检索引擎与向量存储 |
各检索引擎(向量/BM25/全文/混合)能力对比、驱动选择、维度管理、打分归一化 |
| 模型管理 |
5 类模型、27 个厂商 Provider、内置模型机制、Ollama 本地模型、限流与用量 |
| Agent 引擎 |
ReAct 循环、24 个内置工具、上下文与记忆管理、技能系统与沙箱、自定义 Agent |
| MCP 集成 |
MCP 客户端管理、OAuth 2.0 + PKCE 全流程、工具审批、WeKnora MCP Server |
| 知识图谱 |
两级开关、LLM 实体关系抽取、Neo4j 存储、图谱增强检索 |
| 数据源导入 |
连接器体系(飞书/Lark/Notion/语雀/RSS)、凭据加密、同步调度与增量更新 |
| 网络搜索与网页抓取 |
9 个搜索引擎、SSRF 防护、web_fetch 双实现、SearXNG 自托管 |
| IM 集成 |
10 个 IM 平台适配、消息处理流水线、内置命令、流式渲染、多实例协同 |
| 网页嵌入 Embed Channel |
嵌入渠道配置、匿名会话与 token 交换、安全模式、webhook、接入示例 |
| Wiki 能力 |
基于知识库的 LLM Wiki 站点生成、四阶段管道、slug 机制、issue 闭环 |
| 评估能力 |
评估任务、Parquet 数据集格式、12 项检索/生成指标 |
| 可观测性与审计 |
日志体系、Langfuse 追踪、审计日志与保留策略、限流、健康检查 |
| FAQ 能力 |
FAQ 条目模型、批量导入与去重、检索命中策略、克隆同步 |
04 API 参考
以 internal/router/router.go 为事实来源整理,共覆盖约 360 个端点,每个端点含权限要求、参数表与 curl 示例。
05 客户端
| 文档 |
内容 |
| Web 前端 |
Vue 3 + TDesign 技术栈、页面路由、状态管理、i18n、部署 |
| 命令行工具 CLI |
17 个命令组、多 profile 配置、输出格式与退出码、脚本化用法 |
| Go SDK |
约 170 个方法的资源覆盖、流式对话、错误处理、完整示例 |
| 微信小程序 |
页面结构、后端地址与 API Key 配置、构建发布 |
| 桌面端 |
Wails macOS 应用、内嵌 Lite 后端、偏好设置与自动更新 |
06 开发指南
| 文档 |
内容 |
| 开发指南 |
环境要求、Makefile 全目标、开发模式、四条测试线、CI 与代码规范、调试技巧 |
| 数据库与迁移 |
40+ 张表结构与 ER 图、golang-migrate 双路径、新增迁移步骤、故障排查 |
| 扩展点指南 |
9 大扩展点:解析器/分块策略/检索引擎/模型 Provider/搜索引擎/数据源连接器/IM 适配器/Agent 工具/存储后端 |
系统组件速览
flowchart LR
subgraph Clients["客户端"]
FE["Web 前端 Vue 3"]
CLI["CLI weknora"]
SDK["Go SDK"]
MINI["微信小程序"]
EMBED["网页嵌入挂件"]
IM["IM 平台 x10"]
end
subgraph Core["核心服务"]
APP["app 主服务 Go/Gin :8080"]
DR["docreader 解析服务 Python gRPC :50051"]
end
subgraph Infra["基础设施"]
PG[("PostgreSQL / ParadeDB")]
RD[("Redis + asynq")]
VS[("向量/检索引擎 可选多种")]
OBJ[("对象存储 local/minio/cos/oss/s3 等")]
NEO[("Neo4j 知识图谱 可选")]
end
LLM["LLM / Embedding / Rerank / VLM 多厂商"]
FE --> APP
CLI --> APP
SDK --> APP
MINI --> APP
EMBED --> APP
IM --> APP
APP --> DR
APP --> PG
APP --> RD
APP --> VS
APP --> OBJ
APP --> NEO
APP --> LLM
文档约定
- 文中源码路径均相对仓库根目录,如
internal/agent/engine.go。
- API 路径默认带
/api/v1 前缀;认证方式见 API 总览。
- 配置示例中的密钥均为占位符,生产环境务必替换(尤其
JWT_SECRET、SYSTEM_AES_KEY、数据库口令)。
- 文档基于仓库 v0.7.1 版本源码整理。