知识库回答「重启后先检查状态灯」,下方只写着"维护手册.pdf"。打开手册才发现,第 2 页讲日常重启,第 7 页讲恢复出厂后的重启。这两种操作不能混在一起。排查时先找清楚:是 PDF 解析没给出页码,还是分块、检索或输出引用时把页码丢了?
先看解析结果有没有原页信息
有原 PDF 和解析结果时,先挑一句只出现在某页的文本,确认能读到它所在的页。不要先把整份 PDF 转成一条纯文本,再通过从头数换行推算页码。
以 ComPDF AI 文档解析 的解析 JSON 为例,接口文档中的 result.detail 逐条记录文字 text、段落 paragraph_id 及所在页 page_id。这里的页码从 1 开始,指文件里的物理页。PDF 内印的「第 1 页」可能在封面之后,两种页码不能混用。可以先用获准上传的教学文件导出 JSON,再挑两页各核对一句。

图:从解析 JSON、检索命中到引用跳转,逐步核对页码(示意)。
让索引和引用使用同一条来源记录
下面是可以直接运行的 Python 3 示例。parsed 是按官方字段组织的合成 JSON ,用来验证应用保留来源的逻辑;没有调用解析接口或检索服务。为了把问题讲清楚,每条段落单独入索引,hits 模拟检索返回的片段 ID。
python
parsed = {"result": {"detail": [
{"page_id": 2, "paragraph_id": 7, "text": "日常重启:先检查状态灯。"},
{"page_id": 7, "paragraph_id": 7, "text": "恢复出厂:备份配置后再重启。"},
{"paragraph_id": 9, "text": "没有页码的片段。"},
]}}
def index_paragraphs(parsed, document_version, total_pages):
records, unlocated = {}, []
for row in parsed["result"]["detail"]:
text = row.get("text", "").strip()
if not text:
continue
page = row.get("page_id")
if type(page) is not int or not 1 <= page <= total_pages:
unlocated.append(text)
continue
key = (document_version, page, row["paragraph_id"])
if key in records:
raise ValueError(f"重复的来源记录:{key}")
records[key] = text
return records, unlocated
records, unlocated = index_paragraphs(parsed, "maintenance-v3", 8)
hits = [("maintenance-v3", 2, 7), ("maintenance-v3", 7, 7)]
for key in hits:
version, page, _ = key
print(f"{version}|PDF 第 {page} 页|{records[key]}")
print("无页码,待核对:", len(unlocated))
输出中,同一份手册的两条命中分别显示为 PDF 第 2 页和第 7 页。没有页码的段落单列,不随手补成第 1 页。如果文档权限允许但页码确实无法恢复,产品可以明确显示「仅能定位到文件」,不生成看似精确的页码。
接入真实检索时,把 document_version、page_id 及片段标识一起写入索引。让模型引用检索结果已提供的片段 ID,再由应用读取页码;模型生成的页码不直接用于跳转。如果业务需要把同一节的跨页文本合为一个片段,给片段保留所涉及的每个页码与对应文字,不能总取起始页。跳转前还要由应用核对文件访问权限,并定位到被索引的版本。
换成自己的 PDF 后,过三个检查
| 测试 | 通过标准 |
|---|---|
| 同一份手册两页出现同一个词 | 两条引用分别回到各自的原句;检索时的页码与显示页码一致。 |
| 加一页封面,重新索引 | 下载或预览打开的是正确版本。跳转使用该版本的物理页号;如果要显示印刷页码,另存映射。 |
| 某条记录没有页码,或用户无权访问文件 | 缺页码时不编造跳转;无权访问时不展示原文摘录。 |
排查顺序是:先对解析 JSON 和原 PDF,再对检索记录,最后点一次用户实际看到的引用。页码在 JSON 里正确、到了检索结果却消失,就优先修分块或索引;只有解析阶段的页码或文字不对,才换样本回头检查解析设置。这样可以定位问题在哪一层,避免为了一个丢掉的字段重做整套知识库。