WeKnora：腾讯开源的LLM文档理解与语义检索框架

一、WeKnora是什么

WeKnora是腾讯面向开源社区推出的大语言模型（LLM）驱动文档理解与语义检索框架，专为处理结构复杂、内容异构的文档场景量身打造，核心遵循检索增强生成（RAG）核心范式，从根本上解决传统全文检索、关键词匹配存在的检索不准、理解不深、回答有幻觉三大痛点。

作为一款企业级定位的开源框架，WeKnora不只是简单的文档检索工具，更是打通文档解析-知识建模-检索匹配-智能推理-交互问答的全流程闭环系统，既能让非技术用户通过可视化界面快速搭建专属知识库，也能让开发者通过组件扩展满足定制化需求。

该项目核心开发语言为Go，辅助语言为Python，首个公开版本为2025年9月发布的v0.1.0，截至目前最新稳定版本为v0.2.5，历经多次版本迭代，新增多格式文档支持、多语言适配、知识库克隆导出、Agent工具扩展等核心功能，同时强化安全防护与部署便捷性。

WeKnora的核心目标十分明确：

1. 提升复杂文档的理解与检索效率，让用户快速获取精准知识；

2. 保障数据安全，支持本地/私有云部署，掌握数据主权；

3. 降低使用门槛，可视化Web UI+一键部署方案，适配不同技术基础用户；

4. 兼顾扩展性，全流程组件解耦，支持自定义模型、工具与检索策略。

与LangChain、Haystack等通用LLM应用框架不同，WeKnora聚焦文档理解与语义检索垂直领域，针对性优化复杂文档处理逻辑，内置知识图谱构建、多模态解析等专属能力，且原生适配企业级场景的安全与管理需求，是一款“开箱即用、灵活扩展、安全可控”的开源智能知识库解决方案。

二、功能特色

WeKnora的功能围绕“复杂文档处理”与“智能问答”两大核心展开，兼具实用性、灵活性与扩展性，核心功能覆盖从文档入库到问答输出的全流程，且每个功能均针对性解决实际场景痛点，核心功能及价值如下表所示，后续展开详细解读。

WeKnora核心功能及核心价值表

1. ReACT Agent智能体模式，赋能复杂任务自主解决

WeKnora核心支持ReACT智能体架构，实现推理-行动-观察-反思的闭环决策机制，让AI具备类人类的思考与解决问题能力，而非局限于单一问答。

• 自主工具调用：智能体可自主判断用户问题是否需调用工具，支持内置知识库检索、MCP扩展工具，还可集成DuckDuckGo网页搜索补充实时信息；

• 复杂任务拆解：面对多步骤复杂问题，会通过多轮迭代拆分任务，最终生成完整报告，例如“整理某产品近3年技术参数变更并对比”，无需人工干预；

• 流程可追溯：支持展示思考轨迹与工具调用流程，回答来源清晰可查，避免“黑箱”输出；

• 工具灵活扩展：支持MCP协议接入自有工具，开发者无需修改核心代码即可拓展能力边界。

2. 多格式多来源文档深度解析，告别“格式适配难、信息提取乱”

WeKnora支持11种主流文档格式解析，涵盖PDF、DOCX、DOC、TXT、MD、JPG、PNG、CSV、XLSX、XLS等，适配结构化、半结构化、非结构化各类异构文档，且针对不同格式优化专属解析逻辑：

• 图片/扫描版PDF：内置PaddleOCR高精度识别，支持多语言，可区分标题、正文、注释等语义角色，同步提取图表核心描述；

• 表格类文档（Excel/CSV）：自动识别表格边框与单元格关联，转换为二维列表或JSON结构化数据，避免“表格变纯文本”导致的信息丢失；

• 长文档处理：采用自适应滑动窗口分块算法，默认512token窗口，可动态调整，确保拆分后文本片段语义完整，为后续检索筑牢基础；

• 多来源入库：支持文件夹批量导入、URL链接导入、在线编辑录入三种方式，适配不同场景的文档归集需求。

3. 混合检索策略，兼顾精准与全面

传统检索存在“关键词精准但覆盖面窄、语义全面但精准度不足”的弊端，WeKnora创新采用关键词+向量+知识图谱混合检索策略，实现二者平衡：

• 关键词检索：基于Elasticsearch的BM25算法，适配“某条款出自哪份合同”“某参数具体数值”等事实性问题，确保检索精准；

• 向量检索：基于语义嵌入模型，计算用户问题与文档片段的语义相似度，适配“如何解决设备报错E103”等语义性问题，覆盖关联内容；

• 知识图谱检索：挖掘文档中的实体与关系（如“产品型号-技术参数”“甲方-乙方-签约金额”），解决隐藏关联信息检索难题；

• 智能权重调整：根据查询类型动态分配权重，事实性问题关键词权重60%，语义性问题向量权重70%，检索结果经重排模型优化，Top10准确率达89%。

4. 双类型知识库灵活管理，适配多元存储需求

WeKnora支持FAQ型和文档型两种核心知识库类型，满足不同场景知识管理需求，管理功能高效灵活：

• FAQ型知识库：存储“问题-答案”一对一标准化知识（如常见问题、政策解读），支持批量导入导出，v0.2.4版本新增CSV格式导出，方便知识迁移备份；

• 文档型知识库：存储各类长文档，支持多格式导入、标签分类管理，可按业务场景、文档类型归类，检索更高效；

• 便捷管理功能：支持知识库异步克隆（同步标签与元数据）、增量同步、在线编辑，无需重新导入即可修改内容，提升管理效率。

5. 可配置对话策略，精准控制问答效果

WeKnora支持灵活的对话策略配置，非技术用户可通过可视化界面调整参数，适配不同场景问答需求：

• 双模型独立配置：Agent模式与普通模式可分别指定LLM模型，支持本地Ollama部署（deepseek、Llama3）与外部API模型（混元、DeepSeek）；

• 检索参数可调：自定义检索阈值，控制结果数量与相似度，避免无关信息干扰；

• Prompt自定义：引导模型输出指定格式（简洁回答、详细解析、带引用来源），贴合使用场景；

• 多轮对话记忆：支持上下文连贯问答，解决“重复提问”“上下文断裂”问题。

6. 全流程组件解耦，轻松实现定制化扩展

WeKnora采用模块化设计，文档解析、向量嵌入、检索引擎、LLM生成四大核心环节完全解耦，每个环节均可独立配置与替换，适配定制化需求：

• 文档解析：可替换为自有解析工具；

• 向量嵌入：支持切换nomic-embed-text、BGE等模型；

• 检索引擎：兼容PostgreSQL(pgvector)、Elasticsearch、Qdrant等主流向量数据库；

• LLM生成：兼容所有支持标准API的大模型；

• 工具扩展：内置uvx/npx启动器，通过MCP协议快速接入外部工具，扩展性极强。

7. 多语言与多模态适配，适配全球化场景

• 多语言支持：全流程适配中英俄日韩多语言，从文档解析、检索到问答输出无阻碍，满足全球化业务需求；

• 多模态处理：打破“文本之外无知识”局限，可从产品宣传图提取核心卖点、从医学影像报告图片提取诊断信息，适配复杂多元场景。

8. 安全可控部署，保障数据主权与合规

数据安全是企业级场景核心需求，WeKnora从底层设计保障安全可控：

• 身份认证：v0.1.3版本起新增登录认证，支持账号密码登录与权限管理；

• 部署灵活：支持本地部署、私有云部署，所有数据存储在本地/私有云，不经过第三方服务器，掌控数据主权；

• 安全加固：修复前端XSS等漏洞，强化输入验证与内容安全策略，符合政府、金融、医疗等行业合规要求。

三、技术细节

WeKnora的技术设计围绕“高效、稳定、灵活、易用”四大原则展开，从技术栈选型到核心架构，再到关键技术实现，均针对性适配文档理解与语义检索核心需求，既保证开箱即用的便捷性，又兼顾企业级部署的稳定性与扩展性，核心模块及职责如下表，后续分维度详细解读。

WeKnora核心模块及核心职责表

1. 技术栈选型：兼顾高效性与兼容性

WeKnora的技术栈选型充分平衡高效性、稳定性与兼容性，适配开源生态与企业级需求，核心技术栈如下：

• 开发语言：核心用Go（高并发、高性能、跨平台，适配后端服务）；辅助用Python（适配AI生态，用于解析工具、重排服务）；

• 存储体系（三层架构）：

1. 元数据存储：PostgreSQL，支持数据库自动迁移，适配结构化数据管理；

2. 向量存储：支持pgvector、Elasticsearch、Qdrant，适配不同数据量与检索需求；

3. 文件存储：MinIO对象存储，适配多模态文档存储；

4. 知识图谱存储：Neo4j，支持实体关系存储与关联检索；

• 模型生态：兼容本地模型（Ollama）与外部API模型，不绑定特定厂商，灵活适配不同算力环境；

• 辅助工具：文档解析依赖MinerU、Markitdown，OCR依赖PaddleOCR，链路追踪依赖Jaeger，异步任务依赖MQ，保障各环节高效运转；

• 部署方式：Docker容器化部署，支持Docker Compose一键启动，适配Linux、Windows、macOS多系统。

2. 核心架构设计：模块化闭环架构，全流程可控

WeKnora采用模块化闭环架构，围绕“文档理解-知识建模-检索匹配-推理生成-基础设施支撑”五大环节构建，各模块独立运行且协同联动，形成完整智能知识库闭环：

1. 文档接入层：知识入库入口，接收用户上传文档、URL链接或在线录入知识；

2. 文档理解层（文档解析模块）：核心是“读懂”文档，完成多格式解析、结构化提取与语义分块；

3. 知识建模层（向量处理+知识图谱）：将文本片段向量化存储，同时自动提取实体关系构建知识图谱，实现知识结构化建模；

4. 检索匹配层（检索引擎模块）：接收用户查询，通过混合检索召回相关知识，经重排优化输出精准候选集；

5. 推理生成层（LLM推理+Agent工具层）：普通模式直接生成回答，Agent模式通过思考调用工具，输出高质量结果；

6. 支撑层（权限安全+基础设施）：负责账号安全、服务调度、数据备份，保障框架稳定运行。

3. 核心模块详解：各司其职，协同增效

结合核心模块表，对关键模块的运行逻辑展开详细解读，明晰框架底层运转原理：

• 文档解析模块：采用责任链模式处理复杂文档，PDF优先用MinerU，失败切换Markitdown；文本类文档先识别不可切分内容（表格、图片占位符）再语义分块；图片类文档先OCR识别再语义处理，确保解析内容完整结构化；

• 向量处理模块：文本片段经嵌入模型生成固定维度向量（默认nomic-embed-text生成768维向量），向量存入指定数据库，支持批量导入、增量更新、批量删除，嵌入模型选定后不可修改，保障语义一致性；

• 检索引擎模块：接收查询后先优化表述，再同步触发关键词、向量、知识图谱检索，按预设权重整合结果，经重排模型筛选TopN，支持跨知识库检索，兼顾精准与全面；

• LLM推理模块：接收检索结果后，结合查询与上下文生成回答，支持引用来源标注降低幻觉；多轮对话时压缩长上下文，保留关键信息，确保对话连贯；

• Agent工具层：基于ReACT架构实现工具调用，内置知识库检索、网页搜索，支持MCP协议扩展外部工具，工具调用格式标准化，记录调用链支持回溯，同时限制最大迭代次数避免无限循环；

• 权限安全层：负责账号注册、登录认证、权限分配，强化输入验证与XSS防护，拦截恶意攻击，确保数据与服务安全。

4. 关键技术实现：核心优势的底层支撑

WeKnora的核心竞争力源于四大关键技术优化，也是其区别于其他开源框架的核心亮点：

• RAG范式落地优化：传统RAG易出现“检索无关、回答脱节”问题，WeKnora通过“问题优化-多策略检索-结果重排-引用生成”四步优化，先让LLM优化查询提升检索精准度，再通过混合检索+重排筛选优质知识，最后生成带来源标注的回答，有效降低幻觉率；

• ReACT Agent机制落地：通过少样本Prompt引导模型生成思考轨迹与标准化工具调用指令，工具返回结果后模型判断是否满足需求，未满足则迭代，既解决复杂问题，又保证运行效率；

• 多格式文档自适应解析：为不同格式设计专属解析类，封装在/docreader/parser目录，格式自动识别触发对应逻辑，自适应分块算法根据内容长度与语义动态调整分块大小，兼顾向量化适配性与语义完整性；

• 知识图谱自动构建：无需手动标注，通过LLM自动提取文档中11类实体及关系，生成“实体1-关系-实体2”三元组，存入Neo4j，检索时可挖掘隐藏关联知识，比如从“产品A用技术B，技术B解问题C”中，关联检索“产品A能解什么问题”。

四、应用场景

1. 企业内部知识管理场景

• 核心痛点：企业内部规章制度、操作手册、项目文档、技术资料分散存储、格式各异，传统检索难以快速查找，新员工培训耗时长，核心知识易流失；

• 解决方案：搭建企业私有知识库，批量导入内部文档至文档型知识库，规章制度、常见问题导入FAQ型知识库，按部门、业务线标签分类；员工自然语言提问即可快速检索，Agent模式可生成知识总结（如“部门季度工作总结核心要点”）；

• 应用价值：实现知识集中化、结构化管理，降低查找成本，提升工作效率，减少核心知识流失，助力企业知识沉淀复用。

2. 学术研究辅助场景

• 核心痛点：科研人员需查阅大量论文、文献，多为PDF格式（含公式、图表），传统关键词检索难以定位核心内容，文献综述撰写耗时长，跨文献关联分析难；

• 解决方案：搭建学术知识库，导入论文文献，WeKnora精准解析公式、图表描述，结构化提取研究观点、实验方法、数据结论；支持自然语言检索（如“某领域近5年研究热点”），Agent模式辅助撰写文献综述；

• 应用价值：加速文献检索分析效率，降低综述撰写难度，帮助科研人员快速把握研究核心，提升科研效率。

3. 产品技术支持场景

• 核心痛点：产品售后、技术支持中，用户咨询量大，技术手册、故障指南复杂，客服难以快速精准解答，用户自行查阅难度高；

• 解决方案：搭建产品技术支持知识库，导入产品手册、故障排查指南、常见问题，按产品型号、问题类型分类；客服快速检索答案回复用户，同时搭建用户自助查询平台，减轻客服压力；

• 应用价值：提升客服响应速度与准确性，提高用户满意度，降低人力成本，优化产品使用体验。

4. 法律合规审查场景

• 核心痛点：法律、金融行业需处理大量合同、法规、政策，条款复杂、更新频繁，传统检索难以快速定位，合规审查耗时长，易遗漏关键信息引发风险；

• 解决方案：搭建法律合规知识库，导入法规、政策、合同模板，WeKnora精准解析条款、条文，提取关键权责信息；支持自然语言检索（如“某合同违约责任条款”），知识图谱关联检索（如“某法规对应的违规后果”）；

• 应用价值：提升法规合同检索效率，降低合规审查难度，减少遗漏风险，助力企业合规经营。

5. 医疗知识辅助场景

• 核心痛点：医疗行业医学文献、诊疗指南、药品说明书更新快、内容专业、格式复杂，医护人员难以快速获取精准知识，患者难以理解专业内容；

• 解决方案：搭建医疗知识辅助知识库，导入医学文献、诊疗指南、药品说明书，解析专业术语与数据，提取诊疗方案、用药禁忌等核心信息；医护人员检索辅助临床决策，患者咨询平台用通俗语言解答疑问；

• 应用价值：提升医护诊疗效率与准确性，优化患者就医体验，助力医疗服务提质增效。

五、使用方法

WeKnora支持Docker Compose一键部署（推荐新手）与源码部署（适合开发者），部署流程简洁，无需复杂配置，部署后通过可视化Web UI即可完成知识库搭建与问答，详细步骤如下：

第一步：部署前环境准备

无论哪种部署方式，需先完成基础环境准备，确保部署顺利：

1. 操作系统：支持Linux、Windows 10+、macOS 12+，推荐Linux（稳定性更强）；

2. 核心依赖：安装Docker（≥20.10）与Docker Compose（≥2.0），用于容器化部署；

3. 辅助工具：安装Git，用于克隆代码仓库；

4. 可选依赖：安装Ollama，用于本地部署大模型，无需依赖外部API，保障数据安全；

5. 硬件要求：最低1C2G，推荐2C4G及以上；本地部署大模型需升级配置（7B模型推荐8G+内存）。

第二步：部署方式选择（二选一）

方式一：Docker Compose一键部署（推荐新手，开箱即用）

无需关注底层配置，一键启动所有服务，步骤最简：

1. 克隆代码仓库：终端执行git clone https://github.com/Tencent/WeKnora.git，进入目录cd WeKnora；

2. 配置环境变量：复制.env.example为.env，执行cp .env.example .env，新手默认配置即可，需自定义（换模型、改端口）可编辑.env文件；

3. 启动服务：按需选择服务组合，推荐全功能启动

• 核心服务（基础功能）：docker compose up -d

• 全功能服务（含知识图谱、对象存储）：docker-compose --profile full up -d

• 知识图谱服务（核心+Neo4j）：docker-compose --profile neo4j up -d

4. 验证部署：等待3-5分钟（首次启动拉取镜像），浏览器访问http://localhost，出现登录界面即部署成功；后端API：http://localhost:8080，链路追踪：http://localhost:16686（可选）。

方式二：源码部署（适合开发者，支持定制化）

适合需修改源码、定制功能的开发者，步骤稍复杂，需额外安装依赖：

1. 克隆代码仓库：git clone https://github.com/Tencent/WeKnora.git && cd WeKnora；

2. 安装基础依赖：Go（≥1.21）、Python（≥3.9），配置环境变量；

3. 安装项目依赖：go mod download（Go依赖）、pip install -r requirements.txt（Python依赖）；

4. 配置环境变量：复制.env.example为.env并按需配置；

5. 启动依赖服务：docker compose -f docker-compose.deps.yml up -d（启动PostgreSQL、Elasticsearch等）；

6. 启动核心服务：先启动后端go run main.go，再进入frontend目录启动前端npm install && npm run dev；

7. 验证部署：浏览器访问http://localhost:8081，登录界面正常显示即成功。

第三步：部署后基础操作（可视化Web UI）

部署成功后，无需编写代码，通过Web UI即可完成所有操作：

1. 注册登录：首次访问注册本地账号，登录后支持修改账号密码；

2. 创建知识库：点击「知识库管理-新建知识库」，选择类型（FAQ型/文档型），填写名称、描述，完成创建；

3. 配置知识库参数（部分参数配置后不可修改）：

• 模型配置：选择LLM模型（本地Ollama/外部API）、嵌入模型，填写API Key等信息；

• 检索配置：选择检索策略（混合/单一），调整检索阈值；

• 高级配置：是否启用多模态、知识图谱，设置文档分块大小；

4. 导入知识：文档型支持文件/文件夹/URL导入，FAQ型支持手动录入/批量导入，导入后系统自动解析、分块、向量化，等待处理完成；

5. 发起问答：进入知识库对话界面，切换普通/Agent模式，输入自然语言提问，即可获取回答；Agent模式可查看思考与工具调用流程，回答支持查看引用来源；

6. 知识库管理：支持编辑、克隆、导出、删除，添加标签分类，方便检索管理。

第四步：停止与卸载服务

1. 停止服务：Docker部署执行docker compose down，源码部署直接关闭终端进程；

2. 清空数据：需重新部署时，执行docker compose down -v清空数据卷，再重启即可。

六、常见问题解答

1. 部署类：Docker启动后访问http://localhost无响应

• 原因1：服务未完全启动，首次拉取镜像耗时久；解决方案：等待5-10分钟，docker compose ps查看服务状态，确保全部“up”；

• 原因2：80端口被占用；解决方案：编辑.env修改SERVER_PORT为未占用端口（如8080），重启后访问http://localhost:8080；

• 原因3：Elasticsearch等依赖启动失败；解决方案：docker logs elasticsearch查看日志，多为内存不足，修改jvm.options将-Xms、-Xmx改为512m，重启依赖服务。

2. 文档导入类：上传后提示“导入失败”“解析失败”

• 原因1：格式不支持（非11种支持格式）；解决方案：转换为PDF、DOCX等支持格式再上传；

• 原因2：文档过大/损坏；解决方案：单个文档不超100M，修复损坏文档，或分块上传；

• 原因3：OCR识别失败（图片/扫描PDF）；解决方案：确保文档清晰无乱码，重新上传解析；

• 原因4：权限不足；解决方案：确保上传文件无只读权限，本地部署给WeKnora目录读写权限。

3. 检索问答类：提问后检索结果不准或回答有幻觉

• 原因1：知识库无相关知识；解决方案：补充对应文档，重新导入后提问；

• 原因2：检索阈值不合理；解决方案：知识库配置中，调低阈值提召回率、调高阈值提精准度，按需调整；

• 原因3：嵌入模型与LLM不匹配；解决方案：更换适配模型（如BGE搭配多数LLM），保障语义一致；

• 原因4：提问表述不清晰；解决方案：优化提问，补充上下文，让问题更明确。

4. Agent模式类：Agent无响应或工具调用失败

• 原因1：最大迭代次数不足；解决方案：对话策略配置中，调高最大迭代次数（默认3次，可设5-10次）；

• 原因2：工具配置错误（如网页搜索）；解决方案：核对工具参数，确保网络通畅，网页搜索需外网；

• 原因3：无Agent使用权限；解决方案：确认账号权限，管理员后台配置权限；

• 原因4：问题无需调用工具；解决方案：简单事实性问题切换普通模式，Agent适配复杂问题。

5. 账号安全类：忘记密码或登录失败

• 原因1：密码输入错误；解决方案：核对密码（区分大小写），重新输入；

• 原因2：忘记密码；解决方案：本地部署通过数据库重置，执行docker exec -it postgres psql -U weknora，进入数据库后执行更新语句；

• 原因3：账号被禁用；解决方案：联系管理员解除禁用（本地部署可重建账号）。

6. 功能使用类：知识库无法克隆或FAQ无法导出

• 原因1：知识库正在处理文档（导入/解析中）；解决方案：等待处理完成后，再执行克隆/导出；

• 原因2：FAQ导出格式错误；解决方案：FAQ仅支持CSV导出，选择正确格式；

• 原因3：磁盘空间不足；解决方案：清理本地磁盘，预留足够空间存储文件。

七、相关官方链接

1. 官方GitHub仓库：https://github.com/Tencent/WeKnora

2. 官方官网：https://weknora.weixin.qq.com

八、总结

WeKnora是腾讯开源的一款专注于复杂异构文档处理与语义检索的LLM驱动框架，核心基于RAG范式构建全流程闭环，采用模块化架构设计，兼具多格式文档深度解析、关键词-向量-知识图谱混合检索、ReACT Agent智能体、双类型知识库管理等核心功能，支持本地与私有云部署，既保证了开箱即用的便捷性，又具备高度的扩展性与安全性，同时通过可视化Web UI大幅降低使用门槛，非技术用户也能快速搭建专属智能知识库。该框架针对性解决传统文档检索“理解不深、检索不准、回答有幻觉”的痛点，适配企业知识管理、学术研究、技术支持、法律合规、医疗辅助等多类核心场景，既能显著提升知识利用效率，又能严格保障数据安全与主权，是一款兼顾实用性与企业级需求的优秀开源智能知识库解决方案，为用户提供了高效、精准、可控的复杂文档处理与智能问答新选择。