WeKnora 是腾讯开源的一个 LLM 驱动框架，专为深度文档理解和语义检索设计，特别适用于处理复杂异构文档，如 PDF、Word 和图像。它遵循 RAG（Retrieval-Augmented Generation）范式，通过模块化架构整合多模态预处理、向量索引、智能检索和大模型推理，实现上下文感知的高质量问答。

核心架构剖析

WeKnora 的架构分为文档解析、向量处理、检索引擎和 LLM 推理四大模块，每模块独立可配置，便于扩展。文档解析模块支持 PDF、Word、Txt、Markdown 和图像（集成 OCR 和 Caption），将结构化与非结构化内容统一转换为语义视图。例如，对于多页 PDF，它能提取表格、图表和文本层级关系，避免传统 OCR 的碎片化问题。

在嵌入阶段，支持本地模型如 BGE/GTE 或云 API 生成向量，支持 PostgreSQL (pgvector) 和 Elasticsearch 等向量数据库。检索策略融合 BM25（稀疏检索）、Dense Retrieval（稠密向量）和 GraphRAG（知识图谱增强），可跨知识库检索。“WeKnora 采用混合检索策略，提升召回精度与广度 [1]。” 生成环节兼容 Qwen、DeepSeek 等模型，支持思考 / 非思考模式切换，以及多轮对话 Prompt 配置。

新增 Agent 模式基于 ReACT 框架，能调用内置工具、MCP 工具和 Web 搜索（如 DuckDuckGo），通过多轮迭代和反思生成综合报告。这对企业知识管理特别实用，如内部政策 Q&A 或技术手册检索。

部署与配置清单

快速部署依赖 Docker Compose，前置条件：Docker、Docker Compose 和 Git。

  1. 克隆与环境配置：

    git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env

    编辑 .env，关键参数：

    • EMBEDDING_MODEL: "bge-large-zh"（中文文档推荐，维度 1024）。
    • LLM_MODEL: "qwen2.5:7b"（Ollama 本地部署，平衡速度与精度）。
    • VECTOR_DB: "pgvector"（轻量级首选，生产用 Elasticsearch 扩展规模）。
    • RETRIEVAL_THRESHOLD: 0.7（相似度阈值，低于此丢弃 chunk，避免噪声）。

  2. 启动服务：

    docker-compose --profile full up -d

    包含全功能：核心服务 + MQ 异步任务 + 自动数据库迁移。访问 Web UI：http://localhost，后台 API：http://localhost:8080。

  3. 知识库创建：

    • 类型：FAQ 或 Document。
    • 导入：拖拽文件夹、URL 或在线录入，支持标签管理。
    • 启用知识图谱（Neo4j profile）：docker-compose --profile neo4j up -d，解析文档间关系，提升 GraphRAG 效果。

生产部署注意安全：v0.1.3+ 内置登录认证，推荐内网部署，避免公网暴露；配置防火墙，仅开放 80/8080 端口。

RAG 优化参数与阈值

为高效召回，配置 retrieve-rerank-generate 管道：

  • Chunking 策略：语义分割，chunk_size=512，overlap=128。复杂文档用层级 chunk（段落 + 句子），保留结构元数据。
  • 检索 Top-K：初始 20，rerank 后 5。使用跨编码器如 bge-reranker-large 过滤。
  • 融合权重：BM25:0.3 + Dense:0.5 + Graph:0.2（知识图谱权重随文档复杂度上调至 0.4）。
  • 上下文窗口：4096 tokens，超长用总结压缩（LLM 递归总结 chunk）。
  • 检索阈值：0.75（召回）+ 0.85（rerank），监控命中率 >90%。

Agent 模式配置：

  • Agent 模型：qwen2.5:14b（推理强）。
  • 工具链：内置 KB 检索 + Web 搜索 + MCP（uvx/npx 启动外部工具）。
  • 迭代上限：5 轮，反思 Prompt："评估上轮输出，识别遗漏并规划下一步工具调用。"
  • 阈值：检索分数 <0.6 触发 Web 搜索。

监控与回滚策略

集成 Jaeger 追踪（--profile jaeger）：监控端到端延迟，检索命中率、生成 BLEU/ROUGE 分数。E2E 测试工具可视化 recall@K 和答案覆盖率。

关键指标：

指标 阈值 告警
检索延迟 <500ms 扩容向量 DB
召回率 >0.9 调高 Top-K 或嵌入模型
生成幻觉率 <5% 加强 RAG Prompt
Agent 迭代数 ≤4 优化工具描述

回滚：版本变更用 MQ 任务维护状态，自动迁移数据库。问题排查参考 docs/QA.md。

落地价值与扩展

在企业场景，WeKnora 降低知识发现成本，支持法律合规审查（合同条款检索）和医疗辅助（指南分析）。扩展 MCP Server 集成自定义工具，如数据库查询。结合 WeChat 对话平台，实现零代码部署。

总体，WeKnora 以参数化配置驱动 RAG 工程化，参数如阈值 0.7-0.85 和 chunk 512 经测试稳定，适用于 10w+ 文档规模。

资料来源： [1] Tencent/WeKnora GitHub README，https://github.com/Tencent/WeKnora。 官网：https://weknora.weixin.qq.com/。