企业官网建设流程全解析

把文档变成会答题的知识库：WeKnora RAG 智能问答平台完整指南

【免费下载链接】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 这类原始文档变成可查询的 RAG 知识库、会自主推理的 Agent 和自动维护的 Wiki，支持 RAG 智能问答与私有化部署。这篇指南面向第一次接触它的你，讲清楚它解决什么问题、怎么几分钟跑起来、怎么用得准，以及哪些地方能替换、哪里是坑。

它替你把三件事做掉了

先说痛点。公司文档散在网盘、IM 群和几个人的电脑里，关键词搜索搜不到"意思相同但字面不同"的内容；直接问通用大模型，它不读你的文档，答错了也没法追责。

WeKnora 用三块能力应对：

• RAG 问答：文档上传后自动解析、分块、向量化；提问时混合检索相关片段，答案里逐条标注引用，点引用能跳回原文。
• ReAct 智能体：对"跨多个文档、需要分步判断"的问题，智能体自己决定检索几轮、要不要联网搜索、要不要调用 MCP 工具，甚至把代码写进 Docker / E2B / Cube 沙箱里执行，最后汇总作答。
• Wiki 模式：Agent 从原始文档里自动蒸馏出结构化的 Markdown 页面，页面互相链接，还生成可视化的知识图谱。这些页面你可以在浏览器里直接编辑，有版本历史、行级 diff 和一键回滚。

它定位是平台而非代码库：解析、检索、推理整条链路模块化解耦，组件都能换。向量库支持 8 种（ParadeDB、Milvus、Weaviate、Qdrant、Elasticsearch、OpenSearch、Apache Doris、腾讯云 VectorDB），对象存储可选本地 / S3 / OSS / COS，模型侧兼容 OpenAI、DeepSeek、通义、智谱、Gemini、Ollama 等 20 多家。

5 分钟启动 WeKnora：Docker Compose 部署步骤

前置条件两样：Docker 和 Docker Compose；机器建议 4 核 / 8GB 内存起步（解析服务内置 LibreOffice 和 Playwright，比较吃内存）。另外你需要一套可用的模型——本地 Ollama，或任意 OpenAI 兼容 API 的 base_url 加 api_key。

git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env # 按注释填 DB 账号密码、JWT_SECRET 等必填项 docker compose pull docker compose up -d

等docker compose ps里所有服务变 healthy。前端在http://localhost，后端健康检查是http://localhost:8080/health。

跑通第一个 RAG 问答：从注册到带引用的回答

启动后浏览器打开http://localhost，走一遍最小闭环，顺利的话十几分钟，大头是等文档解析：

1. 注册账号。系统没有内置默认账号，注册完自动得到一个工作空间，你是 Owner。
2. 建库并选模型。新建知识库时，初始化向导让你为这个库选模型：对话模型（LLM）和向量模型（Embedding）是必填的两项，Rerank、图片理解 VLM、语音转写 ASR、知识图谱抽取都先不开也行，之后随时补。向导里有个「测试」按钮，先确认模型连得通再保存。一个硬约束：向量模型建库后尽量别换，换了要重建整个索引。
3. 上传文档。拖文件进上传区，或粘贴一个网页 URL。支持 PDF、Word、Excel、PPT、Markdown、HTML、EPUB、图片、音频等。解析是异步的，状态依次是pending → processing → finalizing → completed，扫描件和大文件会慢一些。
4. 提问。进对话页选这个知识库，直接问。回答里带引用角标，点开能看到原文片段。到这一步，最小闭环就跑通了。

最容易踩的一个坑：后端跑在容器里，用本地 Ollama 时地址要填http://host.docker.internal:11434，填localhost连不上。

两种内置 Agent：快速问答和智能推理怎么选

对话页顶部可以一键切换两种内置智能体：

• 快速问答：一轮检索、一次生成，延迟低、token 成本小。查定义、找数据这类单点问题用它就够。
• 智能推理（ReACT）：Agent 自己决定检索几轮、要不要联网、要不要调 MCP 工具，适合"对比两个方案并列出依据"这类多步问题。

想更定制，可以在「智能体」页建自定义 Agent，按需挂 MCP 工具和联网搜索。

还有一条不那么显眼的路径：Wiki 模式。开启后 Agent 从原始文档自治生成结构化、互相链接的 Markdown 知识页面，并生成可视化知识图谱——不是每次检索时现算，而是把知识提前"编译"好。你也能在浏览器里改页面，有版本历史可以回滚。

怎么让答案更准：重排、分块与知识图谱

答案不准，基本是三个环节之一出了问题：没检回相关分片、检回的分片排序不对、或者分片本身被切坏了。每个环节 WeKnora 都留了调节口：

• 模型侧：向量模型决定召回上限，它的维度要和向量库匹配（比如 pgvector 的 1024 维 HNSW 索引）。Rerank 重排解决"检回了但排序不对"；图片理解 VLM 和 ASR 语音转写让图表、录音里的内容也可问答；这些都在知识库初始化向导里按需开启。
• 分块侧：chunk 大小是精度和连贯性的权衡，默认值之外可以按文档类型调。调完效果不好定位时，可以直接在界面里编辑单个分片——保存后自动重建索引，编辑保留版本快照，支持 diff 和回滚。
• 检索侧：支持 BM25 稀疏召回、向量稠密召回和 GraphRAG 图谱增强。开启知识图谱后，系统会分析段落间的语义关联，对跨段落的关联问题提升相关性和召回广度。配置参考 docs/KnowledgeGraph.md。

平台自带端到端测试：输入一批问题，可视化整条检索链路，输出召回命中率和 BLEU / ROUGE 指标。调参别凭感觉，用这个面板看趋势。

文档进去之后发生了什么

上传的文档交给独立的 docreader 解析服务：PDF、Office、图片、EPUB、MHTML、XMind 等格式各自有解析器，Office 文档由进程内的 anydoc 直接解析，产出结构化文本和图片。

接着按配置分块——自适应三层分块加父子分块，每个分块做 embedding，连同元数据一起入库；目录结构以树形保留，像文件管理器一样能浏览、重命名、重新归档。

检索时，用户的问题先经过重写，再走 BM25 与向量两路召回（可选图谱增强），命中的分片交给 Rerank 模型排序，最后把 top-k 分片连同系统提示词交给 LLM，生成带引用编号的回答。解析和索引都是异步任务，走 Redis + Asynq 队列，不同阶段用独立的 worker 池治理，管理后台能看到队列深度、按模型并发，失败任务可以排查和手动重试。

想追踪每次 Agent 推理的每一步，可以挂 Langfuse（Docker Compose 里--profile langfuse就能起）：ReAct 循环、token 消耗、工具调用全程可查；文档解析本身也有一条 Langfuse 风格的时间线，解析卡住时能直接定位在哪个环节。

知识怎么进来，答案怎么出去

文档进来有两条路：手动上传（文件、网页 URL、文件夹），或接数据源自动同步——飞书知识库 / 飞书云盘、GitLab、腾讯 IMA、Notion、语雀、RSS 都在列，支持增量和全量。

答案出去的渠道比多数人预期得多：

• Web 界面之外，IM 渠道覆盖企业微信、飞书、Lark、QQBot、Slack、Telegram、钉钉、Mattermost、微信、云之家共 10 家，同事不用打开你的网站就能问；
• Chrome 插件可以在浏览器里选中文本或整页，一键存进知识库；
• 网站嵌入 Widget 把智能体嵌到外部站点，带域名白名单、限流和安全模式；
• 程序集成走 RESTful API（官方文档覆盖约 360 个端点），API Key 支持能力级授权加按知识库限制；另有官方 Python MCP Server，29 个工具、stdio / SSE / HTTP 三种传输，源码在 mcp-server/；命令行客户端weknora在 cli/。

部署与权限：上生产前要改的几处

• 官方安全声明的原文建议：服务部署在内网/私有网络，不要直接暴露公网。生产环境放内网，前面挂反向代理加认证，或接 OIDC（支持 JWKS 验签）。
• Docker Compose 按 profile 加可选组件：--profile neo4j（知识图谱）、--profile minio（对象存储）、--profile langfuse（链路追踪），可叠加。Kubernetes 上用仓库自带的 Helm chart（helm/，要求 K8s ≥ 1.25）。
• 多人协作走空间 RBAC：Owner / Admin / Contributor / Viewer 四级角色，按知识库归属资源，每个空间有审计日志。注册完第一个账号后，建议把注册模式改成邀请制（设置页里改auth.registration_mode，立即生效不用重启）。
• 版本升级：.env里把WEKNORA_VERSION改成目标版本，docker compose pull之后再up -d——只执行up -d会复用本地缓存镜像，Web UI 显示的版本可能对不上。

常见问题

部署后页面打不开？先docker compose ps看服务是否都 healthy（前端依赖 app 变 healthy），再确认.env存在且必填项都填了——app 服务直接读这个文件，缺失会导致 compose 解析失败。

模型连不上？用初始化向导里的「测试」按钮定位；本地 Ollama 记得用host.docker.internal地址。

文档一直卡在解析中？大扫描件确实慢，先在解析时间线里看卡在哪一步；管理后台的任务队列面板能看到失败任务和原因，可以手动重试。

答案开始跑偏？先点引用看检回了什么片段。片段不对，按 Rerank → 分块 → 图谱的顺序逐个调，每调一项用端到端测试面板对比指标。

与同类方案的取舍

WeKnora 给的是完整平台：从上传、解析、问答到权限和 IM 集成。如果你只想在代码里拼一条 RAG 链路，LangChain、LlamaIndex 这类开发框架更轻——但界面、账号、权限、IM 集成都得自己搭。和 RAGFlow、Dify 这类同形态的开源平台比，WeKnora 的侧重是 ReAct 智能体加沙箱技能运行时、Agent 自动生成的 Wiki，以及数据源同步和 IM 渠道的覆盖面。如果你的需求就是私有化、多格式文档、团队共享、可观测性，它基本不用再拼组件；如果只是偶尔问几个文档，更轻的方案可能就够了。

下一步建议：先把最小闭环跑通，然后上传一批真实工作文档——测试效果要用自己的语料才有意义。建库时测试按钮确认模型连通，embedding 模型当场定好。答案不好时先点引用看检回了什么，再按 Rerank、分块、图谱的顺序调。团队场景把注册改成邀请制，并按前面提到的方式指定第一个系统管理员。

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