1. ChatPDF 这类工具到底在替你做什么

第一次看到“把 PDF 丢进去就能对话”这个形态，我的反应是：这不就是把文档塞进模型上下文吗，有什么难的。真动手做过两版之后才发现，难点从来不在“调模型”，而在于你怎么把一份几十页、排版混乱、中英混排、带表格带脚注的 PDF，切成模型能准确用上的碎片，并且在回答时能指出这句话来自第几页。ChatPDF 这个品类之所以在办公场景里落地得比很多花哨的 AI 功能都快，是因为它精准踩在了一个高频痛点上：法务翻合同、财务对报销制度、HR 查员工手册、技术看规格书，这些动作的本质都是“在一堆长文本里定位一小段”，而人肉做这件事的效率和耐心都很有限。

我先把这类工具的能力边界讲清楚，免得你期待错方向。它能做的是：基于你上传的文档内容做受限域问答，回答必须落在文档里，能返回引用位置，能处理多份文档的交叉比对。它不能做的是：替你判断合同有没有法律风险、替你做出业务决策、替你把文档里没写的常识补全。一旦模型开始“发挥”，输出看起来更漂亮，实际风险反而更大。所以我做这类工具的第一原则是：宁可它说“文档中未找到”，也不要它编一段听起来很合理的话。

适合看这篇内容的人有三类。第一类是纯使用者，想知道为什么有时问得好有时问得离谱，该怎么问、该传什么格式的文件；第二类是想自己搭一套内部工具的开发者，手里有私有文档不方便外传，需要一个能跑的方案；第三类是做办公类产品的同行，想看看这条链路上哪些环节最容易翻车。下面的内容会从原理解构一路写到可运行的代码和踩坑清单，中间穿插我实际测出来的参数和数字，能直接抄的部分我会标出来。

2. 拆开看：一条文档问答链路的五个环节

2.1 从“关键词搜索”到“回答问题”，差的不只是一个模型

很多人以为这类工具是“搜索的升级版”，其实两者的工作方式完全不同。传统全文检索的输入是关键词，输出是一堆命中的位置，判断相关性的依据是词频和位置权重；而文档问答的输入是一句自然语言，输出是一段整合过的答案，中间多了一步“理解意图 + 组织语言”。这个差别带来的直接后果是：搜索错了你一眼能看出来（返回的段落明显不相关），问答错了你不一定能看出来（它把两段不相干的内容缝成了一句通顺的话）。这也是为什么在这类工具里，可溯源引用不是锦上添花的功能，而是安全底线。

我一般把整条链路拆成五个环节：文档解析、文本分块、向量化与索引、检索召回、生成与引用。这五步里，绝大多数人把 80% 的精力花在第五步（换模型、调提示词），但实际上决定效果上限的是第一步和第二步。一个扫描件没做 OCR、页眉页脚全混进正文、表格被拆成乱七八糟的碎片，后面接再强的模型也救不回来。我自己做第二版的时候，光是把 PDF 解析从“整篇抽文本”改成“按页抽 + 块级页码映射”，回答准确率肉眼可见地往上走了一截，模型一行没改。

2.2 五个环节各自的失败模式

把每个环节的典型故障列出来，排查的时候你会省很多时间。

这张表我建议你贴在显示器边上。实际排查时按从上到下的顺序走，因为下游的问题经常是上游传染的。有人问“为什么它答得头头是道但页码是错的”，你去查生成环节没用，问题在解析环节——你把整篇文档当成一个块，模型当然只能瞎猜页码。

2.3 为什么“直接丢进长上下文”不是答案

现在不少模型的上下文窗口动辄几十万 token，于是有人问：还要分块检索干什么，整篇塞进去不就行了。我实测过，一份 80 页的技术规格书大约 6 万汉字，塞进上下文确实放得下，但三个问题立刻出现。第一是成本，每次提问都把这 6 万字重新计费一遍，问十次就是十遍的钱，而分块检索每次只带几千字。第二是注意力稀释，上下文里塞的东西越多，模型对关键句的定位精度越差，尤其是答案藏在第 60 页的时候，中间部分的信息容易被忽略。第三是延迟，长上下文的首次响应时间会明显拉长，办公场景下用户等三秒就开始烦躁了。

所以我的判断是：上下文窗口变大，不会有淘汰检索，反而会让检索的价值更高——因为检索帮你把信噪比提上去了。真正被淘汰的是“粗暴地按固定字数切块、不做任何语义优化”的初级做法。长上下文更适合作为一种兜底策略：当检索召回不足、且文档总量在可控范围内时，退化成小范围整体投喂，而不是无条件全量投喂。

3. 方案选型：四条路径，各有各的坑

3.1 四种实现路径的横向对比

自己动手之前，先把路径选清楚，否则会在错误的路上耗掉大量时间。

我个人在内部测试时用的是第三种和第四种的组合：解析、分块、索引全部在本地完成，只有“把召回片段 + 问题拼成提示词”这一步才涉及模型调用，而且可以在配置里一键切成完全本地。这个架构的好处是，敏感内容从来不会以原始文档的形态离开机器，出去的只是已经被你筛选过的几个片段。当然这也不是绝对安全，片段本身也可能包含敏感信息，所以还需要一层字段级的脱敏规则。

3.2 分块策略：这是最容易被糊弄、也最影响效果的一步

分块这件事，绝大多数教程一句话带过：“按 500 字切，重叠 50 字”。这句话不算错，但它没告诉你为什么是 500，什么时候该大什么时候该小。我的经验判断标准是这样的：块的粒度应该匹配“一个完整语义单元”的大小。合同里的一个条款、手册里的一条规则、规格书里的一个参数表，这些才是自然的切分单位。按固定字数硬切，很容易把一个条款切成两半，前半段在块 A，后半段在块 B，检索时只召回 A，模型就只能答半句。

实际做法上，我采用“结构优先、字数兜底”的策略：先按段落、标题、条款编号这类结构标记切，切出来的段如果太长（超过阈值）再按句号、分号二次切，如果太短（小于阈值）就和相邻段合并。中文场景下我常用的阈值是：目标块长 400 到 600 字，重叠 60 到 100 字。重叠的作用是防止边界切断，但重叠太大也有副作用——同一段内容被多个块重复包含，检索时会挤占 top-k 名额，反而降低多样性。我试过把重叠从 80 调到 300，召回的相关块数量没变，但有效信息密度明显下降，回答开始出现重复啰嗦的毛病。

至于具体数字怎么算，举个我实际调过的例子。一份 60 页的制度手册，抽出正文大约 3.2 万字。目标块长 500 字、重叠 80 字，那么有效步长是 420 字，块数约为 32000 ÷ 420 ≈ 76 块。每块 500 汉字，按中文大约 1 字对应 1.4 到 1.6 个 token 估算，单块约 700 到 800 token。检索时取 top 5，投喂给模型的片段总量约 4000 token，加上系统提示和问题，单次请求输入在 4500 token 上下。这个量级对成本非常友好，一次问答的输入成本基本可以忽略，真正花钱的是生成和可能的二次重排。

3.3 检索方式：纯向量不够，纯关键词也不够

向量检索的强项是“语义相近”，你问“报销要多久到账”，它能召回写着“费用核销周期为五个工作日”的段落，即使两者没有一个共同的字。但它的弱项同样明显：对数字、编号、专有名词、缩写不敏感。你问“第 3.2 条怎么规定的”，向量检索很可能召回一堆讲条款的段落，就是找不到第 3.2 条那一段。

所以我现在的默认配置是混合检索：向量召回和关键词召回各取一批，然后合并去重，按融合分数排序。关键词那一路，中文没有天然的空格分词，我不用重型分词器，直接用字符二元组（bigram）做倒排，效果好、实现简单、不依赖词典。融合的时候给两路各一个权重，我从 0.6/0.4 开始调，实测在制度类文档上比纯向量提升明显，尤其是在“问具体条款编号”“问具体金额”“问具体日期”这类问题上。

如果文档量不大（几百块以内），还可以加一步重排：把召回的 15 到 20 个块，用一个小模型或者规则打分重新排序，取前 5。这一步对准确率的提升在跨文档场景下非常可观，代价是多一次调用，延迟会增加几百毫秒。我的做法是把它做成开关，默认关，用户反馈“答不准”的时候再开。

4. 动手实现：一个能跑的最小可用版本

4.1 目录结构与依赖

我习惯把这类工具拆成四个模块，互不干扰，方便单独替换：解析（parser）、索引（indexer）、检索（retriever）、生成（answerer）。目录大概长这样：

docchat/ parser.py # PDF -> 带页码的文本块 chunker.py # 文本块 -> 检索单元 indexer.py # 向量化 + 倒排索引落盘 retriever.py # 混合召回 + 融合排序 answerer.py # 拼提示词 + 调用模型 + 引用回填 store/ # 索引文件、原文缓存

依赖上，解析我用 PyMuPDF（导入名fitz），它对中文 PDF 的文本抽取和坐标信息支持比较稳；向量部分用 numpy 就够了，几百到几万块的规模完全不需要上重型向量库，一个矩阵加一次点积就行。真要上十万块以上再考虑专门的索引结构，那时候瓶颈才出现。

pip install pymupdf numpy

这里先说一个我踩过的坑：别在解析阶段就把文本清洗得太狠。我第一版为了“干净”，把换行全删了、把连续空格合并了、把看起来像页眉的短行过滤了，结果表格的行列关系全毁了，模型看到的是“项目 金额 备注 差旅 2000 住宿 800”这种粘连在一起的东西。后来改成保留原始换行，只在分块阶段做归一化，表格的可读性好了很多。

4.2 文档解析：按页抽文本，页码一定要带着

解析阶段最重要的一件事不是抽得多干净，而是把页码和文本绑定在一起。因为用户最终要的是“这句话在第几页”，你如果在这一步丢了页码，后面再怎么补都是猜。

import fitz # PyMuPDF def parse_pdf(path: str): doc = fitz.open(path) pages = [] for i, page in enumerate(doc): text = page.get_text("text") if not text.strip(): # 无文本层，大概率是扫描件，走 OCR 分支 pages.append({"page": i + 1, "text": "", "need_ocr": True}) continue pages.append({"page": i + 1, "text": text, "need_ocr": False}) doc.close() return pages

这段代码里need_ocr这个标记很关键。很多 PDF 是扫描后拼起来的，没有任何文本层，get_text返回空字符串。如果不做标记，用户在界面上看到“文档已解析成功”，然后问什么都说找不到，体验极差。我的处理是：解析后统计空页比例，超过 30% 就提示用户“这份文件可能是扫描件，需要开启文字识别，识别会慢一些且可能有误差”，把预期管理做在前面。

页眉页脚的清洗我放在分块阶段做，规则很土但有效：统计每页开头和结尾两行，如果同一行内容在多页重复出现，就判定为页眉页脚并剔除。纯靠规则不用模型，几十毫秒跑完，比上模型稳。

4.3 分块：结构优先，字数为辅，重叠别贪大

import re def split_paragraphs(text: str): # 按空行和常见条款编号切 parts = re.split(r"\n\s*\n|(?=^\s*第[一二三四五六七八九十百]+条)", text, flags=re.M) return [p.strip() for p in parts if p.strip()] def build_chunks(pages, target=500, overlap=80): chunks = [] for p in pages: if p["need_ocr"]: continue buf, buf_len = [], 0 for para in split_paragraphs(p["text"]): if buf_len + len(para) > target and buf: chunk_text = "\n".join(buf) chunks.append({ "text": chunk_text, "page_start": p["page"], "page_end": p["page"], }) # 保留尾部做重叠 tail, tail_len = [], 0 for seg in reversed(buf): if tail_len + len(seg) > overlap: break tail.insert(0, seg) tail_len += len(seg) buf, buf_len = tail + [para], tail_len + len(para) else: buf.append(para) buf_len += len(para) if buf: chunks.append({ "text": "\n".join(buf), "page_start": p["page"], "page_end": p["page"], }) return chunks

这段代码有个简化处理：跨页的段落会被切断，块的page_start和page_end都记成单页。真实场景里合同条款经常跨页，我的处理是允许跨页合并，page_end取最后一段所在的页，引用时显示成“第 12 至 13 页”。这一点很重要，用户看到“第 12-13 页”会觉得可信，看到“第 12 页”但翻过去发现内容在第 13 页，信任感立刻打折。

分块做完，我习惯跑一个自检：打印块长度分布，看看有没有异常值。正常应该是大部分落在 350 到 650 之间，如果有几块只有 20 个字（通常是目录项或者孤立标题），把它们直接丢掉或者合并进相邻块，这类碎片对检索只有干扰。

4.4 向量化与索引：规模不大时，简单就是可靠

import numpy as np def build_index(chunks, embed_fn): vectors = [] for c in chunks: v = embed_fn(c["text"]) v = v / (np.linalg.norm(v) + 1e-9) # 归一化，方便用点积算余弦 vectors.append(v) return np.array(vectors, dtype=np.float32) def search_vector(query, embed_fn, matrix, chunks, top_k=8): q = embed_fn(query) q = q / (np.linalg.norm(q) + 1e-9) scores = matrix @ q # 归一化后点积 = 余弦相似度 idx = np.argsort(-scores)[:top_k] return [(chunks[i], float(scores[i])) for i in idx]

关于维度，768 或 1024 是常见选择。算一下内存：一块对应一个向量，1024 维 float32 就是 4KB。一万块是 40MB，十万块是 400MB，普通机器扛得住。真正需要注意的是嵌入模型要统一：建索引时用哪个模型，查询时就必须用同一个，换模型必须重建索引，否则向量空间不匹配，检索结果会变成随机噪声。我在项目里把模型名和维度写进了索引文件的元数据里，加载时校验，不匹配直接报错，避免有人偷偷换了模型还不自知。

关键词那一路，用字符二元组建倒排：

from collections import defaultdict def bigrams(text): t = re.sub(r"\s+", "", text) return [t[i:i+2] for i in range(len(t) - 1)] or [t] def build_inverted(chunks): inv = defaultdict(list) for i, c in enumerate(chunks): for bg in set(bigrams(c["text"])): inv[bg].append(i) return inv

查询时把问题也切成二元组，统计每个块的命中数，做一个简单的归一化打分。别小看这个粗糙的实现，在“第 3.2 条”“增值税专用发票”“2024 年 6 月”这类查询上，它比向量检索准得多。

4.5 拼提示词：把引用规则写死，别指望模型自觉

生成这一步，提示词的结构比措辞重要。我用的模板大致是这样：

你是文档问答助手。只能依据下面提供的资料回答，不得使用资料之外的知识。 资料以编号开头，每个编号对应一段原文和它的页码。 回答规则： 1. 如果资料能完整回答问题，用简洁的中文作答，并在相关句子后标注 [编号]。 2. 如果资料只能部分回答，说明哪部分有依据、哪部分资料中没有。 3. 如果资料完全无法回答，直接说"文档中未找到相关内容"，不要推测。 4. 不要自行编造页码，页码只从资料里逐字抄录。 资料： [1] (第12页) ...... [2] (第13页) ......

这套规则里最有用的是第 4 条。早期版本我让模型自己写“见第 X 页”，结果它经常把页码写错，因为它在生成时并不会严格对照输入的页码。后来改成模型只输出编号，页码由后端从块的元数据里回填，错误率直接归零。这个改动很小，但它是“看起来能用”和“敢给别人用”的分界线。

回答之后的引用回填大概是这样：

def render_answer(raw, chunk_map): def repl(m): i = int(m.group(1)) c = chunk_map.get(i) return f"[{i}](第{c['page_start']}-{c['page_end']}页)" if c else "" return re.sub(r"\[(\d+)\]", repl, raw)

顺便说一下多轮对话。用户第一句问“差旅标准是多少”，第二句问“那住宿呢”，如果第二句原样拿去检索，向量里只有“住宿”两个字，召回质量会很差。我的做法是把上一轮的问题和这一轮拼起来送进检索（“差旅标准是多少 那住宿呢”），但只把当前问题和检索结果送进生成，避免上下文越来越长。这个细节在单轮测试里完全看不出来，上线后立刻暴露。

5. 常见问题排查实录

5.1 答不出、答不准：按顺序排查，别乱猜

这张表是我实际排查时用的顺序，从上往下走，命中率很高。

这里重点讲“换个说法就问不出”这个最典型的症状。用户问“出差补贴一天多少钱”，文档里写的是“差旅补助标准为每人每日 200 元”。纯向量检索大概率能召回，因为语义接近。但如果用户问“住宿费上限”，文档写的是“住宿标准按职级分档执行”，这就属于语义有距离、字面也没重叠，召回就会掉。我的处理是给这类高频问法做一层“查询改写”：在检索前用一个轻量步骤把口语化问题转成更接近文档表述的样子，比如“住宿费上限”改写成“住宿标准 职级 分档”，命中率能提不少。这一步不必用大模型，用一份业务词表做映射就行，维护成本低、可控性强。

5.2 扫描件和表格这两块硬骨头

扫描件的处理没有捷径，就是 OCR。但我要提醒的是OCR 的错误分布很不均匀：正文印刷体识别率通常不错，表格里的数字、金额、日期错误率显著偏高，因为排版密、字号小。我的做法是：识别完成后，对纯数字段落做一次校验，比如金额字段必须匹配“数字 + 元/万元”，日期必须能解析成合法日期，校验不过的标记出来，在界面上提示“此页为识别结果，数字请以原件为准”。这句话看起来是甩锅，实际上是对用户负责。

表格的问题更隐蔽。PDF 里的表格在文本层里往往是一串按位置排列的文字，抽出来就是“项目 金额 差旅 2000 住宿 800”这种前后粘连的线性文本。模型看到这种文本，很难判断哪个数字对应哪个项目。我的处理是把表格区域单独识别出来，按行列还原成结构化的文本表达，比如转成“差旅：2000 元；住宿：800 元”这种明确配对的形式，再作为一个独立的块入索引。这一步实现成本不低，但凡是财务、采购、规格参数类的文档，收益非常明显。

提示：如果你的文档里有大量表格，先做一件事——随机抽 10 份，人工看解析后的块文本里表格有没有散架。散架率超过三成，就老老实实做表格结构化，别指望调提示词能救。

5.3 幻觉治理：从“让它别编”到“让它编不出来”

只靠提示词说“不要编造”，效果有限。真正管用的是一套组合拳。第一招是收紧上下文，只把高分的 3 到 5 个块送进去，不要一股脑塞 20 个，块越多，模型跨块拼接出错误结论的概率越大。第二招是加一句兜底话术，明确告诉它允许回答“未找到”，很多幻觉是模型觉得“必须给出答案”才产生的。第三招是后置校验，回答生成后，把答案里的关键实体（金额、日期、编号）抽出来，回到召回的块里做一次字符串比对，比对不上的字段加一个提示标记。这一招我实测能拦住相当一部分数字类幻觉，尤其是金额和期限这类用户最在意的字段。

还有一类幻觉特别容易被忽略：跨文档串味。用户同时上传了 A 公司和 B 公司的两份制度，问“年假多少天”，模型可能把两份的内容混在一起答，或者只答了一份但不说是哪份。解决方式是在块的元数据里带上文档标识，检索时限定范围，回答时要求它说明依据的是哪份文件。多人协作场景下，这个细节决定了输出能不能直接用。

5.4 性能与成本：几个实测数字

我这边的测试环境是一台普通办公配置的机器，本地嵌入、本地索引，生成走外部接口。实测数据大致是：一份 60 页、3.2 万字的 PDF，解析加清洗约 1.5 秒，分块约 0.1 秒，76 个块做嵌入约 3 到 6 秒（取决于模型大小和是否批处理），落盘索引文件不到 1MB。单次查询的检索耗时在 20 毫秒以内，主要时间花在生成上，首字延迟 1 到 3 秒。

成本这块，按每次问答输入 4500 token、输出 300 token 估算，即使一天问 200 次，一天的消耗也非常有限。真正需要控制成本的是索引重建：每次用户上传新文件、或者编辑了文档，都可能触发重新嵌入。我的策略是做增量索引，按文件哈希判断是否需要重建，只有新文件或者内容变了的文件才重新嵌入，其余复用。这个改动把批量导入 500 份文档的耗时从几十分钟压到了几分钟。

6. 上线前我会做的几件事

6.1 一份 50 题的自测集，比任何主观感受都靠谱

模型调完之后，光靠自己随便问几句，判断不了好坏。我固定做一件事：从文档里挑 50 个问题，覆盖六种类型——直接查事实（某个数字是多少）、查条件（什么情况下适用）、查流程（第一步做什么）、跨段组合（A 和 B 有什么关系）、边界问题（文档里没有的内容）、以及指代模糊的问题（“这个”“上述”指什么）。然后人工标注标准答案来源页，跑一遍，统计两个指标：召回命中率（标准答案所在的块有没有被召回进 top 5）和答案正确率（回答的意思对不对）。这两个指标要分开看，因为召回对了但答错，是生成的问题；召回没进去，是分块或检索的问题。定位清楚了再改，效率高得多。

我自己的经验是，第一版做出来召回命中率通常只有 60% 到 70%，答案正确率更低。把分块改成结构优先、加上混合检索这两步之后，召回能到 85% 以上。剩下的那部分，往往是文档本身的表述太绕或者表格太难，属于投入产出比开始下降的区间，这时候我倾向于不继续死磕算法，而是在界面上加一句“未找到时建议换个说法，或直接查看原文第 X 页”。

6.2 那些决定“好不好用”的非技术细节

做了几版之后我越来越确信，这类工具的成败有一半在非技术细节上。第一是首次使用的引导，用户不知道该怎么问，界面上直接给三个示例问题（“这份文件的有效期是多久”“付款方式有哪些”“有没有提到违约金”），点击即填，新手的第一印象分就是这么来的。第二是回答里的原文高亮，点引用跳到 PDF 对应页并把那一块高亮出来，这个动作让用户从“信不信”变成“自己看”，信任成本大幅下降。第三是失败时的措辞，“未找到”太冷，改成“这份文件里没有直接写明，你可以试试问 XXX 或者查看第 X 页附近的条款”，用户会愿意再试一次。

还有一点我得单独说：别把检索结果直接暴露给用户看。有些早期实现会把召回的原文片段列在回答下面，本意是增加透明度，实际上用户看到五段半相关的内容，反而怀疑回答的可靠性。我的做法是默认折叠，只显示引用编号和页码，需要的时候再展开。

注意：如果文档涉及个人信息或者商业敏感内容，上传前的告知和删除机制必须做扎实。我见过有人图省事把整批文档丢进公共空间做测试，后面清理起来非常麻烦。本地处理、随时可删、明确告知存储位置，这三条是底线，不是加分项。

最后分享一个我在实际使用中的小体会：这类工具的价值不在于“替你读完文档”，而在于“把你从翻找中解放出来，把时间留给判断”。它给的每一条答案，你仍然应该点开引用看一眼原文，尤其是在合同、制度、参数这类不能出错的场景。工具越顺手，这一步越容易省，但恰恰是这一步不能省。我自己用的时候有个习惯，凡是涉及数字和期限的答案，一定要点引用核对，这个动作花不了三秒，能挡掉绝大多数麻烦。