
Muse 实操教程:从零开始建一个本地问答知识库
14 分钟阅读
参考来源:500-AI-Agents-Projects 「pdf-qa-agent」、awesome-ai-apps 「Production PDF RAG」
一、这篇做什么、适合谁
你手里有一份很长、又必须答得准的文档:一本产品官方手册、一份行业白皮书、一部技术标准。直接把问题丢给聊天机器人,它答得飞快,但你不知道哪句是原文、哪句是它顺手编的——手册类问答最怕的就是这个:答案看起来通顺,页码查无此文。
这篇教程带你从零建一个本地文档问答知识库,走的是最朴素、也最可核查的一条路线:把文档切成小块,给每个块建索引;提问时先检索最相关的块,再从块里把原句摘出来当答案,并附上页码和章节;如果检索证据不足,系统明确拒答,输出一份「文档没覆盖的问题」清单,而不是硬凑一个答案。全程在本机运行,不用任何付费接口、不用密钥、不用向量数据库,唯一的外部依赖是一个免费的 PDF 文本抽取工具。
实测用的文档是 IETF 官方发布的 RFC 9110《HTTP Semantics》:互联网最基础的协议标准之一,194 页,任何人都能从官方站点免费下载。我们对它提了 20 个真实问题(各种方法的定义、状态码的含义、缓存与校验器等),逐条作答并附原文出处;另外混了 8 个文档根本没写的问题,故意验证它会不会编造。最终结果:该答的 20 题全部作答,人工逐条回原文核对,18 条精准命中定义句、2 条部分对、0 条错答;不该答的 8 题全部拒答。这套流程适合:手里有长文档、需要反复查证、且对「编造」零容忍的个人和小团队,比如查产品手册的客服与售后、啃标准文档的工程师、整理白皮书做选题的内容工作者。不适合的场景先说清:想要流畅改写、跨文档推理、中文语义问答的生产系统,这套土办法不够,文末边界一节会逐条交代。
建好之后它有两种用法。一种是批量回归:把你关心的问题攒进问题集,每次文档换版就整套重跑,对比答案与出处的变动,等于给文档建了一套问答体检表,特别适合手册改版、标准更新这类场景。另一种是日常速查:临时想到一个问题,临时加进问题集跑一遍,十秒内拿到带页码的原文答案,再翻到那一页确认上下文,比在两百页里肉眼搜索快得多。两种用法都不需要联网、不需要账号,整个文件夹拷到任何一台装了 Python 的电脑上都能跑。
二、准备工作
第一,准备文档。本次用 RFC 9110,下载地址是 IETF 官方文档站的公开链接:https://www.rfc-editor.org/rfc/rfc9110.pdf 。在终端里用 curl 下载即可,文件约 2.8 MB。选它有三个理由:足够长(194 页,能真实考验切分与检索)、完全公开免费(不存在版权与账号问题)、内容是定义密集型的规范文本(每个问题在原文里都有明确出处,方便验收)。你跟着做时可以换成任何公开 PDF,流程不变;但第一次建议先用同一份文档跑通,对照本文的数字验收,再换自己的。
第二,准备运行环境。需要 Python 3(本次实测为 3.12),以及一个 PDF 抽取工具。这里有个实测踩出来的坑,必须先讲:我们起初用 pypdf 抽文本,结果第 75 页 HEAD 方法的定义句里,规范关键词 MUST NOT 被抽丢了——原句「服务器不得发送内容」变成了「服务器发送内容」,意思整个反了。换成系统工具 pdftotext(属于 poppler-utils 软件包,多数 Linux 自带,macOS 可用 Homebrew 装 poppler)后,同一句完整无缺。所以本教程的脚本优先调用 pdftotext,找不到时才退回 pypdf(需 pip install pypdf)。装好后先用 pdfinfo 看一眼页数,用 pdftotext 抽一页出来肉眼检查关键词是否完整,这一步是整个知识库的第一个质量关口。
第三,想好提问语言。文档是英文,问题就用英文问。这不是崇洋,是检索的物理规律:本教程用的是关键词检索,问题里的词必须和原文里的词对得上,中文问题翻成关键词去匹配英文原文,命中率会大幅下降。20 道覆盖题和 8 道未覆盖题都写在一个 questions.json 文件里,你可以照着格式替换成自己的问题。
第四,建工作目录。把 PDF、脚本、问题集和产出都放同一个文件夹,本次实跑的目录结构是:source-rfc9110.pdf(原文档)、rag.py(主脚本)、questions.json(问题集),运行后生成 answers.md / answers.json(带出处的答案)、uncovered.md(未覆盖清单)、selfcheck.md(自检结果)、chunks.json(切分统计)。
三、手把手步骤
第一步,下载文档并做抽取抽查。命令只有三行:curl 下载 PDF;pdfinfo 确认页数(应为 194 页);pdftotext 把全文抽成文本后,用 grep 搜一个关键词密集的句子,比如 HEAD 的定义句,确认 MUST NOT 这类词没有丢。抽查通过再往下走;抽查不过,先换抽取工具,不要带着残缺文本建库——后面的检索再准,也是在残缺语料上检索。
第二步,写主脚本 rag.py。完整代码附在本节末尾,可以直接保存运行。它做五件事,这里把每件事的要点和实测教训讲清,你改自己的文档时主要就改这几处。其一是按页抽文本:优先 pdftotext 并按换页符切页,这样每个文本块都能标回原始页码;退回 pypdf 时逐页读取,页码同样保留。其二是切分:先剔除每页重复出现的页眉页脚,再以章节标题行作为切分边界,把正文按句子累积成约 380 字的块,相邻块重叠一句。这里有三个实测教训:一是抽出的正文几乎没有空行分段,千万不能按空行切段,我们第一版就这么切过,194 页只切出 10 个块,整个库当场报废;二是目录页整页都是标题行,必须整页跳过,否则目录块会靠词频在检索里胜出,却给不出任何定义;三是块不能太大,750 字时定义句被后续讨论稀释,380 字左右时定义块的词密度才够。其三是建索引:对每个块做分词和轻量词干归一(让 described 与 describes、caches 与 cache 能互相命中),再用纯标准库手写的 BM25 打分——BM25 是经典的关键词相关性算法,不需要任何第三方库。用大白话解释它的打分逻辑:一个词在某个块里出现得越多,这个块越相关;但一个词如果在所有块里都出现(比如在一本 HTTP 手册里问 http),它就没什么区分度,权重自动变低;同时块越长,词频会被适当打折免得长块占便宜。这三条直觉写成公式只有十几行代码,却是几代搜索引擎验证过的基线,新手不必一上来就追求向量检索,先把这个基线跑通、跑准,再谈升级。其四是检索重排:先取 BM25 前 50 名,再用四个通用信号重排——问题词命中章节标题加权、问题短语在块中原样出现加权、定义型问题偏好章节的第一块、问题里带引号的术语在原文中也以引号形式出现加权;这么做的原因在实跑一节有硬数字:纯 BM25 时,GET 的定义块原始分排在第 35 名,origin server 的定义块排在第 149 名,全被「反复提及该词的讨论段」压在下面。其五是作答与拒答:作答采用抽取式,在最佳块里按词权重挑两句原句拼成答案,附页码、章节与整段原文——不改写、不润色,所以答案不存在「编造措辞」的空间;拒答设两道关,问题内容词在最佳块中的覆盖率低于 0.34 拒答,问题里的锚点词(带数字的编码、大写专名)在前三个检索块中缺失也拒答,任一关不过就不生成答案、只登记进未覆盖清单。
第三步,写问题集 questions.json。格式很简单:covered 数组放文档能答的问题,uncovered 数组放文档答不了的问题,每条给个编号和问题文本。出覆盖题的方法是按目录出题:翻文档的章节目录,每个核心章节出 1 到 2 题,问法尽量贴近原文词汇,比如问定义就用「What does the term … refer to」这种规范文档自己的句式。出未覆盖题有个关键技巧:不要只放「怎么做蛋糕」这种一望即知的域外题,必须混入近域陷阱——本题面沾边、但文档其实没写的问題,比如问一个文档里不存在的状态码、问另一个协议的默认端口。这类题最容易骗过检索,因为一半关键词都能在原文里找到。本次 8 道未覆盖题里有 5 道远域题、3 道近域陷阱(Nginx 配置、MQTT 端口、状态码 777)。
第四步,运行。在目录里执行 python3 rag.py,脚本会依次打印页数、块数和自检汇总,全量跑完约 5 秒。第一次运行先别急着看答案,先看三个数:页数是否 194、块数是否在千级(本次 1487 块)、自检里覆盖题作答数与未覆盖题拒答数是否满额。数字不对,优先回第二步查切分,不要急着调阈值。
第五步,读产物并人工抽验。answers.md 里每题有五项:问题、分数与覆盖率、答案、 出处页码与章节、出处段落原文。随机抽 3 条,打开 PDF 翻到标注页码,确认答案句在原文里逐字存在、且确实回答了问题——这一步不能省,程序自检只能验证「判定对不对」,验证不了「答得对不对」,本次就是靠人工逐条核对才发现两条「部分对」。uncovered.md 里每道拒答题会写明被哪道关拦下、缺失的锚点词是什么,并附最接近的原文块供你人工确认它确实答不了。
第六步,换上你自己的文档。改动只有三处:把脚本里的 PDF 文件名换成你的文档;在切分函数里把页眉页脚的特征短语换成你文档的页眉页脚(每份文档都要单独处理,这是体力活,省不掉);问题集全部换成你的问题,覆盖题按你的目录出、未覆盖题照样混近域陷阱。换完先跑自检,再人工抽验至少 5 条,覆盖率阈值 0.34 是在 RFC 9110 上标定的,换文档后如果出现该答的被拒,先检查问题措辞与原文词汇是否对齐,再小幅调整阈值,并把调整理由记进自检文件。
主脚本 rag.py 全文如下,保存即可运行(问题集 questions.json 全文附在代码之后):https://github.com/pcyone/muse-local-rag-knowledge-base
问题集 questions.json 全文如下:
json
{"covered":[{"id":"Q01","q":"What kind of protocol is HTTP described as in the abstract?"},{"id":"Q02","q":"What does the GET method request and what is it used for?"},{"id":"Q03","q":"What does the POST method do with the enclosed representation?"},{"id":"Q04","q":"What does the PUT method request the state of the target resource to do?"},{"id":"Q05","q":"What does the DELETE method request the origin server to do?"},{"id":"Q06","q":"What is the purpose of the HEAD method and how does it differ from GET?"},{"id":"Q07","q":"What does the OPTIONS method allow a client to determine?"},{"id":"Q08","q":"Which request methods are considered safe methods?"},{"id":"Q09","q":"What does it mean for a method to be idempotent?"},{"id":"Q10","q":"What are the five classes of HTTP status codes and what does the first digit indicate?"},{"id":"Q11","q":"What does the 404 Not Found status code indicate?"},{"id":"Q12","q":"When is the 301 Moved Permanently status code used?"},{"id":"Q13","q":"What does the 500 Internal Server Error status code indicate?"},{"id":"Q14","q":"What is a user agent in HTTP terminology?"},{"id":"Q15","q":"What does the term 'origin server' refer to in HTTP?"},{"id":"Q16","q":"What is content negotiation in HTTP and how does it select a representation for a request?"},{"id":"Q17","q":"What does the term 'cache' refer to in HTTP and what does a cache store?"},{"id":"Q18","q":"What is a validator in HTTP and how is it used to make a conditional request?"},{"id":"Q19","q":"What does a range request allow a client to do and what is the 206 Partial Content status code?"},{"id":"Q20","q":"What does the 401 Unauthorized status code indicate and what header must the response contain?"}],"uncovered":[{"id":"U01","q":"How do I configure an Nginx reverse proxy step by step on Ubuntu?"},{"id":"U02","q":"What is a good recipe for baking a chocolate cake at home?"},{"id":"U03","q":"What will the weather be like in Beijing tomorrow morning?"},{"id":"U04","q":"How much revenue did Google earn in the year 2025?"},{"id":"U05","q":"What is the default port number used by the MQTT protocol?"},{"id":"U06","q":"How do I sort a list of numbers in Python with the sorted function?"},{"id":"U07","q":"What does the HTTP status code 777 mean and which section defines it?"},{"id":"U08","q":"Which country won the football World Cup final in 2026?"}]}
四、验收清单
照着下面逐项打勾,全部过关才算这个知识库建好了。验收的顺序也有讲究:先验抽取与切分这些地基,再验判定,最后验语义,地基歪了,后面验得再细也是白验。页数与文档一致:pdfinfo 显示的页数与脚本打印的 pages 相同(本次同为 194),不一致说明抽取丢了页,先修抽取。切分规模合理:块数为千级(本次 1487 块),只有几十块说明切分逻辑坏了,几万块说明块太小、定义被切碎。抽取完整性抽查过:随机抽 2 页,把抽出的文本与 PDF 原页对照,规范关键词、人名、数字无丢失(重点抽查带 MUST、SHALL 这类关键词的句子)。覆盖题判定满额:selfcheck.md 里覆盖题作答数等于题数(本次 20/20)。未覆盖题判定满额:未覆盖题拒答数等于题数(本次 8/8),且每条拒答都写明了被哪道关拦下。近域陷阱被拦下:在未覆盖清单里确认,MQTT 端口题与状态码 777 题都是被锚点关拦下的(它们的覆盖率分别是 0.5 与 0.571,单靠覆盖率关会漏过),这是整套拒答机制最关键的一条验收。答案可逐字溯源:随机抽 3 条答案,把答案句复制到出处段落里搜索,必须逐字命中;再打开 PDF 对应页码复核一次。人工语义抽验做过:至少 5 条答案由人读过并判定「精准 / 部分对 / 错答」,结论记成文件(本次 20 条全审:精准 18、部分对 2、错答 0,核查表与产物放在一起)。产物四件套齐全:问题集、带出处答案、未覆盖清单、自检结果四份文件都在同一目录,且换一台机器、断网状态下重跑能得到同样结果。
五、边界与如实标注
先说能力边界。这套系统是抽取式问答:答案是原文句子的拼接,不会改写、不会总结、不会跨段推理。好处是零编造空间,坏处是读感生硬,遇到原文用两段话分散讲清的概念,它只能给出其中一块。其次,它没有语义理解:BM25 只认词形,轻量词干归一只能弥合时态与单复数,真正的同义改写(比如把「删除」问成「移除关联」之外的全新表述)可能漏检;问题措辞越贴近原文词汇,命中越稳,这既是使用技巧,也是它的天花板。第三,本教程的分词与词干规则只针对英文,中文文档需要换中文分词与停用词表,本次没有实测中文文档,效果未验证。第四,阈值与加权参数是在 RFC 9110 这一份文档上标定的,换文档必须重跑自检与人工抽验,不能把 0.34 当成普适常数。第五,它只是单机脚本:没有增量更新、没有权限管理、没有并发服务,文档更新了要整库重跑(好在全量只需约 5 秒);扫描版 PDF、复杂表格与公式密集的文档本次未测,抽取质量存疑。
再如实交代本次实跑的瑕疵与修正。两条答案只算部分对:第 10 题问状态码五大类,系统答出了取值范围与「首位定类」,但五类枚举在紧邻的下一块里、没被选进答案句,枚举原文在出处页可直接读到;第 16 题问内容协商,系统答的是其中「主动协商」模式的定义句,原因是原文第 12 章本就没有一句总定义、只有三种模式分述,属文档形态限制。一处抽取事故已在正文提过:pypdf 在个别页面会抽丢规范关键词(MUST NOT),全文计数与 pdftotext 相近、但具体页面有缺字,最终脚本改为 pdftotext 优先并保留 pypdf 兜底,使用兜底路径时请务必做关键词抽查。未覆盖题有一处换题记录:陷阱题最初用状态码 999,实跑发现原文第 15.1 节写过「600..999」这一区间(指非 HTTP 的内部用途),999 不算纯未覆盖,系统给出该段反倒是答对了,于是把陷阱码换成全文零出现的 777 后重跑,换题理由记录在未覆盖清单文件头部。最后说明数字口径:判定准确率(20/20 作答、8/8 拒答)来自程序自检;语义质量(精准 18、部分对 2、错答 0)来自人工逐条对原文核对,两者口径不同,不要混为一个「准确率」对外宣称。
什么时候该升级、怎么升级,也一并交代,免得你在土办法上无限打磨。如果你的问题大多是换词改写、同义表达,人工抽验里开始出现「原文有答案但没检索到」的漏检,就该引入向量检索做混合召回;如果你需要把分散在多处的原文综合成一段通顺回答,就该在检索之后接一个生成模型,但必须保留出处标注与拒答阈值,否则等于把防编造的根基拆了。升级的验收标准不变:同一套问题集、同一种人工核查口径,新方案要在精准数上真正超过这套基线,才值得换。
六、附:实跑实例
运行输出(节选,原文照录):
text
`pages=194 chunks=1487 chunk_chars=664086
自检结果
- 文档页数:194
- 切分块数:1487
- 覆盖题:20/20 被正确作答
- 未覆盖题:8/8 被正确拒答`
覆盖题实例一,第 79 页,DELETE 的定义,覆盖率 1.0、重排分数 73.69:
text
`问题:What does the DELETE method request the origin server to do?
答案(原文句子拼接):The DELETE method requests that the origin server remove the association
between the target resource and its current functionality. In effect, this method is similar
to the "rm" command in UNIX…
出处:第 79 页,章节「9.3.5. DELETE」`
覆盖题实例二,第 138 页,404 的定义,覆盖率 1.0、重排分数 166.67:
text
`问题:What does the 404 Not Found status code indicate?
答案(原文句子拼接):The 404 (Not Found) status code indicates that the origin server did not
find a current representation for the target resource or is not willing to disclose that one exists.
出处:第 138 页,章节「15.5.5. 404 Not Found」`
覆盖题实例三,第 22 页,cache 的定义,展示引号术语信号命中的样子:
text
`问题:What does the term 'cache' refer to in HTTP and what does a cache store?
答案(原文句子拼接):A "cache" is a local store of previous response messages and the subsystem
that controls its message storage, retrieval, and deletion. A cache stores cacheable responses
in order to reduce the response time and network bandwidth consumption on future, equivalent requests.
出处:第 22 页,章节「3.8. Caches」`
未覆盖题实例一,近域陷阱,覆盖率 0.5 过了第一关、被锚点关拦下:
text
`问题:What is the default port number used by the MQTT protocol?
- 最高分数:50.94,关键词覆盖率:0.5,缺失锚点词:['mqtt']
- 系统判定:未覆盖,已拒答
- 最接近的原文块(仅供人工核查):第 167 页「18.9. Port Registration」——讲的是 80/443 端口登记,与 MQTT 无关`
未覆盖题实例二,近域陷阱,覆盖率 0.571、锚点 777 全文零出现:
text
`问题:What does the HTTP status code 777 mean and which section defines it?
- 最高分数:65.82,关键词覆盖率:0.571,缺失锚点词:['777']
- 系统判定:未覆盖,已拒答`
迭代过程的两个硬数字,供你判断重排的必要性:只用纯 BM25 时,GET 定义块的原始分在全部块中排第 35 名、origin server 定义块排第 149 名,都进不了答案位;加上标题、短语、章节首块、定义句式与引号术语五个信号重排后,20 道覆盖题全部由定义块作答。人工语义核查结论照录:精准 18/20、部分对 2/20(状态码分类枚举未进答案句、内容协商只答出主动协商模式)、错答 0/20;未覆盖题 8/8 拒答,其中 2 道近域陷阱靠锚点关拦下。以上数字与片段全部来自本次实跑产物,问题集、带出处答案、未覆盖清单、自检结果与人工核查表都在同一产物目录,可逐条复核。
还没有注册好Muse ,不想折腾注册的朋友,可以直接安排!Muse 成品号、还有Muse 邀请码助力,详情请查看我的置顶帖;

ETH & BTC Holder | 早期项目研究 | 持续分享 AI 内容、自动化工作流、实用教程
Muse 成品号、ChatGPT Plus 成品号(质保28天):wzyp.cn/shop/yunnaoai
ChatGPT 原号直充:oneai.click
加入 6,320 关注者
—— 本文首发于 光阴慢递(www.pai.gg),转载请注明出处。原文:《X 上的 Ryan:“Muse 实操教程:从零开始建一个本地问答知识库” / X》









评论(0)
还没有评论,快来写下第一条吧。