Tencent/WeKnora

| English | 简体中文 | 日本語 |

[概述](#-overview) • [架构](#-architecture) • [核心功能](#-key-features) • [快速开始](#-getting-started) • [API 参考](#-api-reference) • [开发者指南](#-developer-guide)

# 💡 WeKnora - LLM 驱动的文档理解与检索框架 ## 📌 概述 [**WeKnora**](https://weknora.weixin.qq.com) 是一个基于 LLM 的框架，专为深度文档理解和语义检索而设计，尤其擅长处理复杂的异构文档。 它采用模块化架构，融合了多模态预处理、语义向量索引、智能检索和大语言模型推理。在核心层面，WeKnora 遵循 **RAG (Retrieval-Augmented Generation)** 范式，通过结合相关文档块与模型推理，生成高质量、具备上下文感知能力的答案。 **官方网站:** https://weknora.weixin.qq.com ## ✨ 最新动态 **v0.3.0 亮点:** - 🏢 **共享空间**: 支持成员邀请的共享空间，成员间共享知识库和 Agent，检索时租户隔离 - 🧩 **Agent 技能**: Agent 技能系统，预置智能推理 Agent 技能，提供沙箱执行环境以进行安全隔离 - 🤖 **自定义 Agent**: 支持创建、配置和选择自定义 Agent，支持知识库选择模式（全部/指定/禁用） - 📊 **数据分析 Agent**: 内置 Data Analyst agent，配备 DataSchema 工具用于 CSV/Excel 分析 - 🧠 **思维模式**: 支持 LLM 和 Agent 的思维模式，智能过滤思维内容 - 🔍 **网页搜索提供商**: 除 DuckDuckGo 外，新增 Bing 和 Google 搜索提供商 - 📋 **FAQ 增强**: 批量导入 dry run，相似问题，搜索结果中显示匹配的问题，大量导入转存至对象存储 - 🔑 **API Key 认证**: API Key 认证机制，Swagger 文档安全保护 - 📎 **输入框内选择**: 在输入框内直接选择知识库和文件，支持 @mention 显示 - ☸️ **Helm Chart**: 完整的 Kubernetes 部署 Helm chart，支持 Neo4j GraphRAG - 🌍 **国际化**: 新增韩语 (한국어) 语言支持 - 🔒 **安全加固**: SSRF 安全的 HTTP 客户端，增强 SQL 校验，MCP stdio 传输安全，基于沙箱的执行 - ⚡ **基础设施**: 支持 Qdrant 向量数据库，支持 Redis ACL，可配置日志级别，Ollama embedding 优化，`DISABLE_REGISTRATION` 控制开关 **v0.2.0 亮点:** - 🤖 **Agent 模式**: 全新 ReACT Agent 模式，可调用内置工具、MCP 工具和网页搜索，通过多轮迭代和反思提供综合性总结报告 - 📚 **多类型知识库**: 支持 FAQ 和文档知识库类型，具备文件夹导入、URL 导入、标签管理和在线录入等新功能 - ⚙️ **对话策略**: 支持配置 Agent 模型、普通模式模型、检索阈值和 Prompts，精确控制多轮对话行为 - 🌐 **网页搜索**: 支持可扩展的网页搜索引擎，内置 DuckDuckGo 搜索引擎 - 🔌 **MCP 工具集成**: 支持通过 MCP 扩展 Agent 能力，内置 uvx 和 npx 启动器，支持多种传输方式 - 🎨 **全新 UI**: 优化的对话界面，支持 Agent 模式/普通模式切换，工具调用过程展示，以及全面升级的知识库管理界面 - ⚡ **基础设施升级**: 引入 MQ 异步任务管理，支持数据库自动迁移，提供快速开发模式 ## 🔒 安全提示 **重要提示:** 从 v0.1.3 版本开始，WeKnora 包含登录认证功能以增强系统安全性。对于生产环境部署，我们强烈建议： - 将 WeKnora 服务部署在内部/私有网络环境中，而非公共互联网 - 避免将服务直接暴露在公网，以防潜在的信息泄露 - 为您的部署环境配置适当的防火墙规则和访问控制 - 定期更新到最新版本以获取安全补丁和改进 ## 🏗️ 架构  WeKnora 采用现代模块化设计，构建了完整的文档理解和检索流水线。系统主要包括文档解析、向量处理、检索引擎和大模型推理等核心模块，每个组件均可灵活配置和扩展。 ## 🎯 核心功能 - **🤖 Agent 模式**: 支持 ReACT Agent 模式，可使用内置工具检索知识库，利用 MCP 工具和网页搜索工具访问外部服务，通过多轮迭代和反思提供综合性总结报告 - **🔍 精准理解**: 将 PDF、Word 文档、图片等多种格式的结构化内容提取为统一的语义视图 - **🧠 智能推理**: 利用 LLM 理解文档上下文和用户意图，实现精准的问答和多轮对话 - **📚 多类型知识库**: 支持 FAQ 和文档知识库类型，具备文件夹导入、URL 导入、标签管理和在线录入能力 - **🔧 灵活扩展**: 从解析、嵌入到检索和生成的所有组件均解耦，易于定制 - **⚡ 高效检索**: 混合检索策略，结合关键词、向量和知识图谱，支持跨知识库检索 - **🌐 网页搜索**: 支持可扩展的网页搜索引擎，内置 DuckDuckGo 搜索引擎 - **🔌 MCP 工具集成**: 支持通过 MCP 扩展 Agent 能力，内置 uvx 和 npx 启动器，支持多种传输方式 - **⚙️ 对话策略**: 支持配置 Agent 模型、普通模式模型、检索阈值和 Prompts，精确控制多轮对话行为 - **🎯 用户友好**: 直观的 Web 界面和标准化 API，零技术门槛 - **🔒 安全可控**: 支持本地部署和私有云，确保完全的数据主权 ## 📊 应用场景 | 场景 | 应用 | 核心价值 | |---------|----------|----------| | **企业知识管理** | 内部文档检索、政策问答、操作手册查询 | 提升知识发现效率，降低培训成本 | | **学术研究分析** | 论文检索、研究报告分析、学术资料整理 | 加速文献综述，辅助研究决策 | | **产品技术支持** | 产品手册问答、技术文档检索、故障排查 | 提升客服质量，减轻支持压力 | | **法律合规审查** | 合同条款检索、法规政策查询、案例分析 | 提高合规效率，降低法律风险 | | **医疗知识辅助** | 医学文献检索、治疗指南查询、病例分析 | 支持临床决策，提升诊断质量 | ## 🧩 功能矩阵 | 模块 | 支持 | 描述 | |---------|--------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Agent 模式 | ✅ ReACT Agent Mode | 支持使用内置工具检索知识库、MCP 工具和网页搜索，具备跨知识库检索和多轮迭代能力 | | 知识库类型 | ✅ FAQ / Document | 支持 FAQ 和文档知识库类型，具备文件夹导入、URL 导入、标签管理和在线录入功能 | | 文档格式 | ✅ PDF / Word / Txt / Markdown / Images (with OCR / Caption) | 支持结构化和非结构化文档，支持图片文字提取 | | 模型管理 | ✅ 集中配置，内置模型共享 | 集中式模型配置，在知识库设置中选择模型，支持多租户共享内置模型 | | Embedding 模型 | ✅ 本地模型, BGE / GTE APIs, 等. | 可定制 embedding 模型，兼容本地部署和云端向量生成 APIs | | 向量数据库集成 | ✅ PostgreSQL (pgvector), Elasticsearch | 支持主流向量索引后端，可根据不同检索场景灵活切换 | | 检索策略 | ✅ BM25 / Dense Retrieval / GraphRAG | 支持稀疏/密集召回和知识图谱增强检索，支持可定制的 retrieve-rerank-generate 流水线 | | LLM 集成 | ✅ 支持 Qwen, DeepSeek 等, 支持 thinking/non-thinking mode 切换 | 兼容本地模型（如通过 Ollama）或外部 API 服务，具备灵活的推理配置 | | 对话策略 | ✅ Agent 模型，普通模式模型，检索阈值，Prompt 配置 | 支持配置 Agent 模型、普通模式模型、检索阈值、在线 Prompt 配置，精确控制多轮对话行为 | | 网页搜索 | ✅ 可扩展搜索引擎，DuckDuckGo / Google | 支持可扩展的网页搜索引擎，内置 DuckDuckGo 搜索引擎 | | MCP 工具 | ✅ uvx, npx 启动器, Stdio/HTTP Streamable/SSE | 支持通过 MCP 扩展 Agent 能力，内置 uvx 和 npx 启动器，支持三种传输方式 | | 问答能力 | ✅ 上下文感知，多轮对话，提示词模板 | 支持复杂语义建模、指令控制和思维链问答，支持可配置 Prompts 和上下文窗口 | | E2E 测试 | ✅ 检索+生成过程可视化与指标评估 | 端到端测试工具，用于评估召回命中率、答案覆盖率、BLEU/ROUGE 等指标 | | 部署模式 | ✅ 支持本地部署 / Docker 镜像 | 满足私有化、离线部署和灵活运维需求，支持快速开发模式 | | 用户界面 | ✅ Web UI + RESTful API | 交互界面和标准 API 端点，支持 Agent 模式/普通模式切换和工具调用过程展示 | | 任务管理 | ✅ MQ 异步任务，数据库自动迁移 | 基于 MQ 的异步任务状态维护，支持版本升级期间的数据库 Schema 和数据自动迁移 | ## 🚀 快速开始 ### 🛠 前置条件 请确保您的系统已安装以下工具： * [Docker](https://www.docker.com/) * [Docker Compose](https://docs.docker.com/compose/) * [Git](https://git-scm.com/) ### 📦 安装 #### ① 克隆仓库 ``` # Clone 主仓库 git clone https://github.com/Tencent/WeKnora.git cd WeKnora ``` #### ② 配置环境变量 ``` # 复制示例 env 文件 cp .env.example .env # 编辑 .env 并设置必需的值 # 所有变量均在 .env.example 注释中记录 ``` #### ③ 启动服务（包含 Ollama） 请检查 .env 文件中需要启动的镜像。 ``` ./scripts/start_all.sh ``` 或 ``` make start-all ``` #### ③.0 启动 ollama 服务（可选） ``` ollama serve > /dev/null 2>&1 & ``` #### ③.1 启用不同功能组合 - 最小核心服务 ``` docker compose up -d ``` - 启用所有功能 ``` docker-compose --profile full up -d ``` - 需要 Tracing 日志 ``` docker-compose --profile jaeger up -d ``` - 需要 Neo4j 知识图谱 ``` docker-compose --profile neo4j up -d ``` - 需要 Minio 文件存储服务 ``` docker-compose --profile minio up -d ``` - 多选项组合 ``` docker-compose --profile neo4j --profile minio up -d ``` #### ④ 停止服务 ``` ./scripts/start_all.sh --stop # 或者 make stop-all ``` ### 🌐 访问服务 启动后，服务可通过以下地址访问： * Web UI: `http://localhost` * 后端 API: `http://localhost:8080` * Jaeger Tracing: `http://localhost:16686` ### 🔌 使用微信对话开放平台 WeKnora 是 [微信对话开放平台](https://chatbot.weixin.qq.com) 的核心技术框架，提供了更便捷的使用方式： - **零代码部署**: 只需上传知识即可在微信生态内快速部署智能问答服务，实现“即问即答”的体验 - **高效问题管理**: 支持高频问题的分类管理，丰富的数据工具确保答案准确、可靠且易于维护 - **微信生态集成**: 通过微信对话开放平台，WeKnora 的智能问答能力可无缝集成到公众号、小程序等微信场景中，提升用户交互体验 ### 🔗 通过 MCP Server 访问 WeKnora #### 1️⃣ 克隆仓库 ``` git clone https://github.com/Tencent/WeKnora ``` #### 2️⃣ 配置 MCP Server 配置 MCP 客户端以连接到服务器： ``` { "mcpServers": { "weknora": { "args": [ "path/to/WeKnora/mcp-server/run_server.py" ], "command": "python", "env":{ "WEKNORA_API_KEY":"Enter your WeKnora instance, open developer tools, check the request header x-api-key starting with sk", "WEKNORA_BASE_URL":"http(s)://your-weknora-address/api/v1" } } } } ``` 直接使用 stdio 命令运行： ``` pip install weknora-mcp-server python -m weknora-mcp-server ``` ## 🔧 初始化配置指南 为了帮助用户快速配置各类模型并降低试错成本，我们在原有配置文件初始化方式的基础上增加了 Web UI 界面进行模型配置。在使用前，请确保代码已更新至最新版本。具体步骤如下： 如果您是首次使用本项目，可以跳过步骤 ①②，直接执行步骤 ③④。 ### ① 停止服务 ``` ./scripts/start_all.sh --stop ``` ### ② 清理现有数据表（建议在无重要时操作） ``` make clean-db ``` ### ③ 编译并启动服务 ``` ./scripts/start_all.sh ``` ### ④ 访问 Web UI http://localhost 首次访问时，您将被自动重定向到注册/登录页面。完成注册后，请新建一个知识库，并在其配置页面完成相关设置。 ## 📱 界面展示 ### Web UI 界面

Knowledge Base Management	Conversation Settings
Agent Mode Tool Call Process

**知识库管理:** 支持创建 FAQ 和文档知识库类型，提供拖拽、文件夹导入、URL 导入等多种导入方式。自动识别文档结构并提取核心知识建立索引。支持标签管理和在线录入。系统清晰展示处理进度和文档状态，实现高效的知识库管理。 **Agent 模式:** 支持 ReACT Agent 模式，可使用内置工具检索知识库，调用用户配置的 MCP 工具和网页搜索工具访问外部服务，通过多轮迭代和反思提供综合性总结报告。支持跨知识库检索，可选择多个知识库同时检索。 **对话策略:** 支持配置 Agent 模型、普通模式模型、检索阈值和在线 Prompt 配置，精确控制多轮对话行为和检索执行方式。对话输入框支持 Agent 模式/普通模式切换、开启/关闭网页搜索以及选择对话模型。 ### 文档知识图谱 WeKnora 支持将文档转化为知识图谱，展示文档不同章节之间的关系。启用知识图谱功能后，系统会分析并构建内部的语义关联网络，这不仅有助于用户理解文档内容，也为索引和检索提供结构化支持，从而增强搜索结果的相关性和广度。 详细配置请参阅 [知识图谱配置指南](./docs/KnowledgeGraph.md)。 ### MCP Server 请参考 [MCP 配置指南](./mcp-server/MCP_CONFIG.md) 进行必要的设置。 ## 📘 API 参考 故障排除 FAQ: [故障排除 FAQ](./docs/QA.md) 详细 API 文档请访问: [API 文档](./docs/api/README.md) 产品计划和即将推出的功能: [路线图](./docs/ROADMAP.md) ## 🧭 开发者指南 ### ⚡ 快速开发模式（推荐） 如果您需要频繁修改代码，**无需每次都重新构建 Docker 镜像**！请使用快速开发模式： ``` # 方法 1：使用 Make 命令（推荐） make dev-start # Start infrastructure make dev-app # Start backend (new terminal) make dev-frontend # Start frontend (new terminal) # 方法 2：一键启动 ./scripts/quick-dev.sh # 方法 3：使用 scripts ./scripts/dev.sh start # Start infrastructure ./scripts/dev.sh app # Start backend (new terminal) ./scripts/dev.sh frontend # Start frontend (new terminal) ``` **开发优势:** - ✅ 前端修改自动热重载（无需重启） - ✅ 后端修改快速重启（5-10 秒，支持 Air 热重载） - ✅ 无需重新构建 Docker 镜像 - ✅ 支持 IDE 断点调试 **详细文档:** [开发环境快速入门](./docs/开发指南.md) ### 📁 目录结构 ``` WeKnora/ ├── client/ # go client ├── cmd/ # Main entry point ├── config/ # Configuration files ├── docker/ # docker images files ├── docreader/ # Document parsing app ├── docs/ # Project documentation ├── frontend/ # Frontend app ├── internal/ # Core business logic ├── mcp-server/ # MCP server ├── migrations/ # DB migration scripts └── scripts/ # Shell scripts ``` ## 🤝 参与贡献 我们欢迎社区贡献！如有建议、Bug 或功能请求，请提交 [Issue](https://github.com/Tencent/WeKnora/issues) 或直接创建 Pull Request。 ### 🎯 如何贡献 - 🐛 **Bug 修复**: 发现并修复系统缺陷 - ✨ **新功能**: 提出并实现新功能 - 📚 **文档**: 改进项目文档 - 🧪 **测试用例**: 编写单元测试和集成测试 - 🎨 **UI/UX 改进**: 改进用户界面和体验 ### 📋 贡献流程 1. **Fork 项目** 到您的 GitHub 账号 2. **创建功能分支** `git checkout -b feature/amazing-feature` 3. **提交更改** `git commit -m 'Add amazing feature'` 4. **推送分支** `git push origin feature/amazing-feature` 5. **创建 Pull Request** 并详细描述更改内容 ### 🎨 代码规范 - 遵循 [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) - 使用 `gofmt` 格式化代码 - 添加必要的单元测试 - 更新相关文档 ### 📝 提交规范 使用 [Conventional Commits](https://www.conventionalcommits.org/) 标准： ``` feat: Add document batch upload functionality fix: Resolve vector retrieval precision issue docs: Update API documentation test: Add retrieval engine test cases refactor: Restructure document parsing module ``` ## 👥 贡献者 感谢这些优秀的贡献者： [](https://github.com/Tencent/WeKnora/graphs/contributors) ## 📄 许可证 本项目基于 [MIT 许可证](./LICENSE) 授权。 在保留适当署名的前提下，您可以自由使用、修改和分发本代码。 ## 📈 项目统计

标签：AI风险缓解, DLL 劫持, EVTX分析, EVTX分析, EVTX分析, RAG, Ruby, WeKnora, 上下文感知, 人工智能, 企业搜索, 向量化索引, 向量数据库, 多模态, 大语言模型, 子域名突变, 异构文档处理, 文本分析, 文档理解, 文档解析, 日志审计, 智能检索, 智能问答, 检索增强生成, 测试用例, 深度学习, 用户模式Hook绕过, 知识库, 腾讯, 语义检索, 请求拦截, 逆向工具