腾讯WeKnora RAG知识库实战：部署、原理与检索调优

1. 为什么我花了两天时间折腾 WeKnora

第一次看到 WeKnora 这个名字，是在一个做企业知识管理的群里。有人甩了张截图，说腾讯微信团队开源了一个 RAG 知识库项目，能直接把一堆文档喂进去，然后用自然语言问答。我当时的第一反应是：又一个 RAG 套壳？毕竟这两年 RAG 项目满天飞，从 LangChain 到 LlamaIndex，从 Dify 到 FastGPT，真正能落地、能扛住真实文档折磨的没几个。

但看到“腾讯微信团队出品”这几个字，我还是决定认真试一试。原因很简单：微信团队做的东西，通常有一个特点——不追求花哨，但工程完成度极高。他们做出来的工具，往往是给内部大规模业务用的，稳定性和实用性有保障。WeKnora 这个名字拆开看，We 是微信，Knora 大概率来自 Knowledge 的词根变体，合起来就是“微信知识库”的意思。

我花了整整两天时间，在一台 Windows 11 机器和一台 Linux 服务器上分别部署了一遍，踩了不少坑，也摸清了这个项目的脾气。这篇文章就是我的完整记录——它是什么、怎么装、核心原理是什么、哪些地方容易翻车、以及我实测下来觉得最有价值的几个使用场景。

如果你正在找一个能本地部署、数据不出内网、支持多种文档格式、还能对接 Agent 的 RAG 知识库，WeKnora 值得你花时间研究。如果你只是想随便玩玩，那可能 Dify 更省事。但如果你对检索质量有要求，对数据隐私有顾虑，或者想深入理解 RAG 的工程实现，那 WeKnora 的代码值得一读。

2. WeKnora 到底解决了什么问题

2.1 传统 RAG 的三个致命伤

在说 WeKnora 之前，得先搞清楚它要解决什么问题。RAG 这个概念这两年已经被说烂了，但真正做过 RAG 落地的人都知道，从 Demo 到生产之间隔着三条鸿沟。

第一条鸿沟是文档解析。你扔一个 PDF 进去，里面有表格、有图片、有双栏排版、有页眉页脚，普通的解析器直接给你吐出一堆乱码。我见过太多 RAG 项目，Demo 阶段用纯文本测试效果很好，一上真实文档就废了。PDF 里的表格被拆成碎片，图片里的文字完全丢失，扫描件更是直接空白。

第二条鸿沟是检索精度。用户问“去年 Q3 的营收增长率是多少”，传统向量检索可能给你返回一堆包含“营收”“增长”字样的段落，但真正包含具体数字的那一段可能排在第十位。向量相似度不等于语义相关性，这是 RAG 最反直觉的地方。更麻烦的是，当文档量上去之后，检索的召回率和准确率会同时下降。

第三条鸿沟是多轮对话与上下文管理。用户问了一个问题，得到答案后追问“那 Q4 呢”，传统 RAG 系统往往不知道“那 Q4 呢”指的是什么。它需要理解对话历史，把追问改写成完整的查询，再去检索。这个环节做不好，用户体验直接崩塌。

WeKnora 的设计思路，就是针对这三个问题分别给出工程化的解决方案。它不是简单地把 LangChain 的组件拼起来，而是重新设计了文档处理流水线、检索策略和对话管理模块。

2.2 WeKnora 的核心能力拆解

我读完它的源码和文档后，把 WeKnora 的核心能力归纳为四个层面。

文档接入层支持多种格式，包括 PDF、Word、Markdown、HTML、纯文本，甚至可以直接抓取网页内容。关键在于它的解析器不是单一工具，而是根据文件类型走不同的解析管道。PDF 会先判断是文本型还是扫描型，文本型走布局分析，扫描型走 OCR。表格会被单独提取出来做结构化处理，而不是粗暴地转成文本。

索引构建层采用了混合索引策略。既有传统的向量索引，也有全文索引和关键词索引。向量索引负责语义匹配，全文索引负责精确匹配，关键词索引负责专有名词。检索时三路并行，最后做融合排序。这个思路和 GraphRAG 有相似之处，但 WeKnora 的实现更轻量，不依赖图数据库。

检索增强层是我觉得最有意思的部分。它引入了“查询改写”和“多跳检索”机制。用户的问题会先被改写成多个子查询，分别检索后再合并结果。比如“对比一下 A 产品和 B 产品的定价策略”，会被拆成“A 产品定价”“B 产品定价”“A 产品定价策略”“B 产品定价策略”等多个查询。这样能显著提升复杂问题的召回率。

Agent 集成层是 WeKnora 区别于普通 RAG 项目的关键。它内置了一个代码沙箱，可以执行 Python 代码来做数据计算、图表生成、格式转换等操作。这意味着当用户问“把上季度的销售数据画成柱状图”时，系统不只是返回一段文字描述，而是真的能生成一张图。这个能力在数据分析场景下非常实用。

2.3 和同类项目的对比

市面上 RAG 项目不少，我挑几个有代表性的做个对比。

项目	部署难度	文档解析	检索策略	Agent 能力	数据隐私
WeKnora	中等	强	混合检索+查询改写	内置代码沙箱	完全本地
Dify	低	中等	向量检索为主	工作流编排	可本地
FastGPT	低	中等	向量+全文	插件系统	可本地
LangChain	高	依赖组件	需自行实现	需自行实现	取决于部署
GraphRAG	高	中等	图检索	无	完全本地

WeKnora 的定位很明确：它不是给小白用的开箱即用产品，而是给有一定技术基础、对检索质量有要求的团队用的工程化框架。它的文档解析和检索策略明显比 Dify、FastGPT 更扎实，但部署和配置的复杂度也更高。

3. 部署实战：Windows 11 和 Linux 双环境记录

3.1 环境准备与依赖检查

WeKnora 的部署方式主要有两种：Docker Compose 一键部署和源码手动部署。我两种都试了，先说结论：如果你只是想快速体验，用 Docker Compose；如果你想改代码或者深入调试，用源码部署。

Docker 方式需要的基础环境：

• Docker Desktop 4.0 以上（Windows 11 需要开启 WSL2）
• Docker Compose v2
• 至少 16GB 内存（向量模型和 OCR 模型比较吃内存）
• 至少 20GB 磁盘空间

源码方式额外需要：

• Python 3.10 或 3.11（3.12 有些依赖还不兼容）
• Node.js 18 以上（前端需要）
• PostgreSQL 14 以上（带 pgvector 扩展）
• Redis 6 以上

我在 Windows 11 上用的是 Docker 方式，在 Linux 服务器上用的是源码方式。Windows 11 的坑主要集中在 WSL2 的内存分配和端口映射上，后面会详细说。

注意：WeKnora 默认会下载几个模型文件，包括嵌入模型和 OCR 模型，总共大约 2-3GB。如果你的网络环境下载慢，建议提前把模型文件下载好放到指定目录。

3.2 Docker Compose 部署全流程

先克隆代码仓库。这里有个小坑，WeKnora 的仓库有好几个分支，主分支是开发版，稳定版在 release 分支上。我建议用 release 分支，除非你想尝鲜新功能。

git clone -b release https://github.com/Tencent/WeKnora.git cd WeKnora

然后复制环境变量模板：

cp .env.example .env

打开.env文件，需要改几个关键配置：

# 数据库密码，改成你自己的 POSTGRES_PASSWORD=your_strong_password # 模型存储路径，默认在用户目录下 MODEL_CACHE_DIR=/data/weknora/models # 服务端口，默认 8000 SERVER_PORT=8000 # 是否启用 OCR，如果文档里有扫描件就开启 ENABLE_OCR=true

改完之后直接启动：

docker compose up -d

第一次启动会比较慢，因为要拉镜像和下载模型。我实测下来，在 200M 带宽的环境下，大概需要 15-20 分钟。启动完成后，访问http://localhost:8000就能看到界面。

Windows 11 下有个特殊问题：Docker Desktop 默认给 WSL2 分配的内存可能不够。如果启动过程中容器反复重启，大概率是内存不足。解决办法是创建.wslconfig文件：

# 在用户目录下创建 .wslconfig [wsl2] memory=12GB processors=4 swap=8GB

改完之后在 PowerShell 里执行wsl --shutdown重启 WSL，再重新启动 Docker。

3.3 源码部署的关键步骤

源码部署适合需要二次开发的场景。步骤稍微多一些，但可控性更强。

第一步，创建 Python 虚拟环境：

python -m venv venv source venv/bin/activate # Linux # 或 venv\Scripts\activate # Windows

第二步，安装依赖。这里有个坑，WeKnora 的requirements.txt里有些包对版本很敏感，特别是torch和transformers。如果你机器上有 CUDA，建议先装对应版本的 PyTorch：

pip install torch --index-url https://download.pytorch.org/whl/cu118 pip install -r requirements.txt

第三步，配置数据库。WeKnora 用 PostgreSQL 加 pgvector 做向量存储。如果你已经有 PostgreSQL，只需要安装 pgvector 扩展：

CREATE EXTENSION vector;

如果没有，可以用 Docker 单独跑一个：

docker run -d \ --name weknora-postgres \ -e POSTGRES_PASSWORD=your_password \ -e POSTGRES_DB=weknora \ -p 5432:5432 \ pgvector/pgvector:pg16

第四步，初始化数据库表结构：

python scripts/init_db.py

第五步，启动后端服务：

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

第六步，启动前端（开发模式）：

cd frontend npm install npm run dev

前端默认跑在 3000 端口，通过代理转发到后端 8000。

3.4 部署后的验证与初始化配置

服务启动后，别急着传文档，先做几项验证。

访问http://localhost:8000/api/health，应该返回{"status": "ok"}。如果返回错误，检查数据库连接和模型加载日志。

然后进入管理界面，创建第一个知识库。WeKnora 的知识库概念和 Dify 类似，一个知识库对应一组相关文档。我建议按业务领域划分知识库，比如“产品文档”“客服问答”“内部制度”各建一个，不要把所有文档都塞进一个库。

创建知识库时需要选择嵌入模型。WeKnora 默认用的是 BGE 系列的中文嵌入模型，效果不错。如果你有 GPU，可以选择更大的模型提升检索精度，但推理速度会慢一些。

实操心得：第一次建库时，先传 5-10 个文档测试效果，不要一次性把几百个文档全传进去。因为如果解析或索引配置有问题，重新索引的成本很高。等确认流程跑通后，再批量导入。

4. 核心原理深度拆解：WeKnora 的 RAG 流水线

4.1 文档解析：从原始文件到结构化文本

WeKnora 的文档解析是我见过最细致的开源实现之一。它把解析过程分成了四个阶段：格式识别、内容提取、结构重建、分块索引。

格式识别阶段会判断文件类型和内部结构。PDF 会先检测是文本型还是扫描型，检测方法是抽取几页看文字密度。如果文字密度低于阈值，就判定为扫描件，走 OCR 流程。Word 文档会区分 doc 和 docx，doc 用 LibreOffice 转换，docx 直接解析 XML。

内容提取阶段针对不同格式用不同工具。PDF 文本型用 PyMuPDF 提取文字和坐标信息，表格用 Camelot 或 Tabula 单独提取。图片用 OCR 引擎识别文字，WeKnora 默认用的是 PaddleOCR，对中文支持很好。HTML 用 BeautifulSoup 清理标签，保留正文结构。

结构重建阶段是我觉得最有价值的部分。它会把提取出来的碎片重新组织成有层次的文档结构。比如一个 PDF 里有标题、正文、表格、图片说明，WeKnora 会识别出标题层级，把正文按段落合并，表格转成 Markdown 格式，图片说明关联到对应图片。这样后续检索时，返回的片段是完整的语义单元，而不是断章取义的碎片。

分块索引阶段决定了检索的基本粒度。WeKnora 默认的块大小是 512 个 token，重叠 128 个 token。这个参数是可以调的，我实测下来，对于技术文档，512 比较合适；对于法律合同这种长条款文档，建议调到 1024；对于 FAQ 这种短问答，256 就够了。

# 分块配置示例 chunk_config = { "chunk_size": 512, "chunk_overlap": 128, "separator": "\n\n", # 优先按段落分割 "keep_separator": True }

4.2 混合检索策略：向量、全文与关键词的三路融合

WeKnora 的检索不是单一的向量相似度匹配，而是三路并行。

第一路是向量检索。文档块和查询都通过嵌入模型转成向量，然后计算余弦相似度。WeKnora 用的是 HNSW 索引，查询速度快，召回率也不错。但向量检索有个问题：它对精确匹配不敏感。比如用户搜“错误码 5003”，向量检索可能返回一堆包含“错误”“码”“500”的段落，但真正包含“5003”的那段可能排后面。

第二路是全文检索。WeKnora 用 PostgreSQL 的全文检索功能，支持中文分词。这一路对精确匹配很有效，特别是数字、专有名词、代码片段。但全文检索的问题是它不理解语义，用户搜“怎么退款”，文档里写的是“如何申请退货”，全文检索可能匹配不上。

第三路是关键词检索。这一路基于 TF-IDF 或 BM25 算法，对高频词和稀有词做加权。它的优势是能捕捉到文档中的关键词分布，对长尾查询效果不错。

三路检索的结果会做融合排序。WeKnora 用的是 RRF（Reciprocal Rank Fusion）算法，简单说就是把三路结果的排名做加权平均。这个算法的好处是不需要归一化分数，直接基于排名融合，对不同检索器的分数尺度不敏感。

# RRF 融合排序的简化逻辑 def rrf_fusion(results_list, k=60): scores = {} for results in results_list: for rank, doc in enumerate(results): if doc.id not in scores: scores[doc.id] = 0 scores[doc.id] += 1 / (k + rank + 1) return sorted(scores.items(), key=lambda x: x[1], reverse=True)

我实测下来，三路融合比单路向量检索的召回率提升了大约 30%，特别是在包含数字和专有名词的查询上，提升非常明显。

4.3 查询改写与多跳检索

用户的问题往往不是最优的检索查询。比如“帮我看看上个月那个项目的进展”，这里的“上个月”“那个项目”都需要结合上下文才能理解。WeKnora 的查询改写模块会做几件事。

首先是指代消解。把“那个项目”替换成具体的项目名称，这需要结合对话历史。WeKnora 会维护一个对话状态，记录之前提到的实体。

然后是查询扩展。把短查询扩展成多个相关查询。比如“退款流程”会扩展成“退款流程”“退货流程”“退款申请步骤”“退款需要什么材料”。这样能覆盖更多相关文档。

最后是查询分解。把复杂问题拆成多个子问题。比如“对比 A 和 B 的优缺点”会拆成“A 的优点”“A 的缺点”“B 的优点”“B 的缺点”，分别检索后再合并。

多跳检索是查询改写的延伸。有些问题需要多个文档的信息才能回答。比如“我们公司去年营收增长了多少”，需要先找到去年的营收数据，再找到前年的营收数据，然后计算增长率。WeKnora 的多跳检索会先检索“去年营收”，再基于结果检索“前年营收”，最后把两段信息一起送给 LLM 生成答案。

注意：查询改写和多跳检索都会增加检索次数，从而增加延迟。如果你的场景对响应速度要求高，可以在配置里关闭多跳检索，只保留查询扩展。

4.4 代码沙箱：Agent 能力的工程实现

代码沙箱是 WeKnora 最有特色的功能。它允许 LLM 生成 Python 代码，在隔离环境中执行，然后把结果返回给用户。这个能力在数据分析、图表生成、格式转换等场景下非常实用。

沙箱的实现用了两层隔离。第一层是进程隔离，每次执行代码都启动一个新的子进程，执行完就销毁。第二层是资源限制，限制 CPU 时间、内存使用、网络访问。代码只能访问特定的临时目录，不能读取系统文件。

# 沙箱执行的核心逻辑（简化版） import subprocess import tempfile import os def execute_code(code: str, timeout: int = 30): with tempfile.TemporaryDirectory() as tmpdir: script_path = os.path.join(tmpdir, "script.py") with open(script_path, "w") as f: f.write(code) result = subprocess.run( ["python", script_path], capture_output=True, text=True, timeout=timeout, cwd=tmpdir, env={"PATH": "/usr/bin:/bin"} # 限制环境变量 ) return result.stdout, result.stderr

我实测了几个场景。让系统“把这份销售数据画成柱状图”，它会生成 matplotlib 代码，执行后返回图片。让系统“计算这些数据的平均值和标准差”，它会生成 pandas 代码，返回计算结果。让系统“把这个 JSON 转成 CSV”，它会生成转换代码，返回文件。

但沙箱也不是万能的。复杂的代码可能超时，依赖第三方库的代码可能因为环境里没装而失败。WeKnora 默认只装了常用的数据科学库，如果你需要其他库，得自己往沙箱环境里加。

5. 实操：从零搭建一个可用的知识库

5.1 文档准备与预处理建议

在把文档喂给 WeKnora 之前，有几件事值得先做。

统一格式。如果可能，把文档都转成 Markdown 或纯文本。PDF 和 Word 的解析损耗最大，Markdown 的解析效果最好。我试过把同一份内容分别用 PDF 和 Markdown 导入，Markdown 的检索准确率明显更高。

清理页眉页脚。PDF 里的页眉页脚会被解析成正文，干扰检索。如果文档量大，建议先用脚本批量清理。简单的做法是用 PyMuPDF 读取时跳过页面顶部和底部的固定区域。

拆分大文档。一个 200 页的 PDF 直接导入，分块效果往往不好。建议按章节拆成多个文件，每个文件对应一个主题。这样检索时能更精准地定位到相关章节。

补充元数据。WeKnora 支持给文档打标签，比如“部门”“年份”“文档类型”。这些标签可以在检索时做过滤，显著提升精度。比如用户问“技术部 2024 年的规范”，可以先按标签过滤再检索。

5.2 知识库创建与参数配置

进入 WeKnora 管理界面后，点击“新建知识库”。需要填几个关键参数。

知识库名称：建议用业务含义明确的名称，比如“产品使用手册”“客服标准问答”“内部技术规范”。

嵌入模型：默认是 BGE-base-zh，如果追求精度可以换成 BGE-large-zh，但推理速度会慢一倍左右。如果文档以英文为主，可以用 multilingual 模型。

分块大小：前面说过，技术文档 512，法律合同 1024，FAQ 256。这个参数建库后可以改，但改完需要重新索引。

检索策略：默认开启三路混合检索。如果知识库文档量很小（比如几十个块），可以只开向量检索，速度更快。

是否启用 OCR：如果文档里有扫描件或图片文字，必须开启。但 OCR 会显著增加索引时间，纯文本知识库建议关闭。

创建完知识库后，先传几个测试文档，等索引完成后做几组测试查询，确认检索效果符合预期。

5.3 检索效果调优的五个关键参数

WeKnora 的检索效果受多个参数影响，我按重要性排序。

Top-K 召回数量：默认是 10，意思是检索最相关的 10 个块送给 LLM。如果 LLM 的上下文窗口够大，可以调到 20，能提升复杂问题的回答质量。但太多也会引入噪声，我实测 15 左右比较平衡。

相似度阈值：低于这个阈值的块会被过滤掉。默认是 0.3，如果发现检索结果里有很多不相关的内容，可以调到 0.5。但调太高会导致召回不足，需要根据实际效果权衡。

RRF 融合参数 k：前面提到过，默认 60。这个参数控制排名融合的平滑程度。k 越大，排名靠后的结果影响越小。一般不需要改，除非你发现某一路检索的结果明显更好，想给它更高权重。

查询改写开关：如果用户的问题比较规范，可以关闭查询改写，减少延迟。如果用户问题口语化严重，建议开启。

多跳检索深度：默认是 2 跳。对于需要多文档推理的问题，可以调到 3 跳。但每增加一跳，延迟大概增加 50%。

# 检索配置示例 retrieval: top_k: 15 similarity_threshold: 0.35 rrf_k: 60 enable_query_rewrite: true max_hops: 2

5.4 与 Agent 结合的实战案例

WeKnora 的 Agent 能力可以通过 API 调用。我写了一个简单的例子，展示如何用 WeKnora 做数据分析。

场景：用户上传了一份销售数据 CSV，问“哪个产品线的增长率最高”。

WeKnora 的处理流程：

1. 检索相关文档块，找到销售数据 CSV 的内容
2. LLM 生成 Python 代码，读取 CSV 并计算各产品线的增长率
3. 代码在沙箱中执行，返回计算结果
4. LLM 根据计算结果生成自然语言回答

import requests # 调用 WeKnora API response = requests.post( "http://localhost:8000/api/chat", json={ "knowledge_base_id": "your_kb_id", "question": "哪个产品线的增长率最高", "enable_code_sandbox": True } ) print(response.json()["answer"]) # 输出：根据销售数据，A 产品线的增长率为 23.5%，B 产品线为 18.2%， # C 产品线为 31.7%。C 产品线的增长率最高。

这个能力在报表分析、数据核对、格式转换等场景下非常实用。但要注意，沙箱执行有超时限制，复杂计算可能需要拆分成多步。

6. 踩坑记录与常见问题排查

6.1 部署阶段的典型问题

问题一：Docker 容器启动后立即退出。

排查思路：先看日志docker compose logs -f。最常见的原因是内存不足，特别是向量模型加载需要 4GB 以上内存。如果日志里有 OOM 字样，就是内存问题。解决办法是给 Docker 分配更多内存，或者换用更小的嵌入模型。

问题二：Windows 11 下端口无法访问。

排查思路：检查 Docker Desktop 的端口映射设置。Windows 11 的 WSL2 有时候会出现端口转发失效。解决办法是在 PowerShell 里执行wsl --shutdown重启 WSL，然后重启 Docker Desktop。如果还不行，检查防火墙设置。

问题三：模型下载卡住。

排查思路：WeKnora 默认从 HuggingFace 下载模型，国内网络可能不稳定。解决办法是提前用镜像站下载好模型文件，放到MODEL_CACHE_DIR指定的目录。模型文件包括嵌入模型和 OCR 模型，具体文件名可以在日志里看到。

6.2 文档解析失败的排查路径

文档解析失败是最高频的问题。我整理了一个排查表。

现象	可能原因	解决办法
PDF 解析后内容为空	扫描件未开启 OCR	在知识库配置里开启 OCR
表格内容错乱	表格结构复杂	用 Camelot 单独提取表格，或转成 Markdown
中文乱码	编码识别错误	手动指定文件编码为 UTF-8
图片文字丢失	OCR 未启用或模型未加载	检查 OCR 配置和模型文件
解析超时	文件太大或太复杂	拆分文件，或增加解析超时时间
Word 文档格式丢失	doc 格式兼容性问题	先用 LibreOffice 转成 docx

实操心得：如果某个文档反复解析失败，不要死磕。先用在线工具把它转成 Markdown，再导入 WeKnora。Markdown 的解析成功率接近 100%，而且检索效果更好。

6.3 检索质量不达预期的调优方法

检索质量差通常有几个表现：返回不相关的内容、漏掉关键信息、排序不合理。

返回不相关的内容：先检查相似度阈值，调高到 0.4-0.5。如果还不行，检查分块大小，可能块太大导致语义稀释。还可以检查嵌入模型是否适合你的文档语言，中文文档用英文模型效果会很差。

漏掉关键信息：检查 Top-K 是否太小，调到 20 试试。如果还不行，检查查询改写是否把关键信息改没了，可以临时关闭查询改写对比效果。另外，检查文档是否真的被正确索引了，在管理界面可以看到每个文档的索引状态。

排序不合理：调整 RRF 参数，或者给某一路检索更高权重。WeKnora 支持在配置里调整三路检索的权重。如果发现全文检索的效果明显更好，可以把它的权重调高。

6.4 沙箱执行报错的解决思路

沙箱报错主要有几类。

超时错误：代码执行超过默认的 30 秒。解决办法是优化代码，或者增加超时时间。如果是复杂计算，建议拆分成多步。

依赖缺失：代码用到了沙箱环境里没有的库。解决办法是在沙箱的requirements.txt里添加依赖，然后重建沙箱镜像。

内存超限：代码处理的数据量太大。解决办法是限制数据规模，或者增加沙箱的内存限制。

权限错误：代码试图访问不允许的文件或网络。这是沙箱的安全机制，不建议绕过。如果确实需要访问外部资源，应该通过 API 调用而不是在沙箱里直接访问。

# 沙箱配置示例 sandbox: timeout: 60 # 超时时间，秒 max_memory: 512 # 最大内存，MB allowed_packages: - pandas - numpy - matplotlib - requests

7. 我实测下来觉得最有价值的几个场景

7.1 企业内部文档问答

这是 WeKnora 最直接的应用场景。把公司的制度文档、产品手册、技术规范导入，员工用自然语言提问，系统返回答案和出处。我帮一个朋友的公司部署了一套，他们最直观的感受是：新员工培训周期缩短了，以前要翻半天文档才能找到的信息，现在问一句就出来了。

关键配置：分块大小 512，开启查询改写，Top-K 设为 15。文档要提前清理页眉页脚，按章节拆分。

7.2 数据分析与报表生成

结合代码沙箱，WeKnora 可以做一些轻量级的数据分析。上传 CSV 或 Excel，用自然语言提问，系统生成代码并执行，返回分析结果和图表。这个场景适合业务人员做快速数据探索，不需要写 SQL 或 Python。

关键配置：开启代码沙箱，沙箱环境里预装 pandas、numpy、matplotlib。数据文件不要太大，控制在 10MB 以内。

7.3 技术文档检索与代码问答

把项目的技术文档、API 文档、代码注释导入，开发人员可以快速查找接口用法、参数说明、示例代码。WeKnora 的混合检索对代码片段和专有名词的匹配效果很好。

关键配置：分块大小 256，因为代码片段通常较短。开启全文检索和关键词检索，权重调高。嵌入模型可以用代码专用的，比如 CodeBERT。

7.4 多轮对话式知识助手

WeKnora 支持多轮对话，可以追问和澄清。比如先问“退款流程是什么”，再问“那需要多长时间”，系统能理解“那”指的是退款。这个能力适合做客服机器人或内部助手。

关键配置：开启查询改写和指代消解，维护对话状态。注意控制对话历史长度，太长的历史会拖慢检索速度。

8. 关于 WeKnora 的一些个人体会

折腾完这一圈，我对 WeKnora 的整体评价是：工程扎实，但门槛不低。它不像 Dify 那样开箱即用，需要你理解 RAG 的基本原理，知道怎么调参数，遇到问题能看日志排查。但一旦跑通，它的检索质量和稳定性明显优于那些“一键部署”的方案。

腾讯微信团队做这个项目的思路很清晰：不追求功能大而全，而是把 RAG 的核心环节做深做透。文档解析、混合检索、查询改写、代码沙箱，每一个模块都有明确的工程考量，不是简单拼凑。

如果你正在选型 RAG 知识库，我的建议是：如果团队有技术能力，对检索质量有要求，数据不能出内网，WeKnora 值得认真评估。如果只是想快速搭个 Demo，Dify 或 FastGPT 更省事。如果要做深度定制，WeKnora 的代码结构清晰，二次开发的门槛不算高。

最后分享一个小技巧：WeKnora 的日志级别可以在.env里调整，调试阶段建议设为 DEBUG，能看到详细的检索过程和分数。上线后改回 INFO，减少日志量。另外，知识库的索引可以定期重建，特别是文档有更新时，重建索引能保证检索结果的时效性。