Skip to content

售后知识助手(二):把手册切成能被引用的证据单元 ​

老陈带新人,最烦听到一句话:「手册上写了。」

哪本手册?哪一版?第几页?说不上来的「手册上写了」,在老陈那里等于没说。售后这一行,参数记错一位小数就可能出事,引用必须精确到能翻开就找到的地步。

助手也一样。它说「依据《维修手册》§2.6」,工程师点开,看到的必须正好是那一节;它说「P12」,翻到第 12 页就得有那段话。引用指错地方,比不引用还糟:不引用,工程师至少知道要自己去核对;引用错了,他会以为已经核对过了。

这一篇讲资料怎么变成「能被精确引用」的东西。

你在这里

上传原件 → 解析与切片 → 任务队列 → PostgreSQL(入库链路),问答链路的检索就从这里取数据

一、原子是切片,不是文件 ​

普通的文档管理系统,最小单位是文件。这个知识库的最小单位是证据单元:一段能单独被引用、单独被核对的文本。一页手册可能切成两三块,一张 Excel 的每一行都是一块。

后台的知识源管理页把这件事写在了标题旁边,「知识库的原子是证据单元,不是文件」:

后台知识源管理页:顶部统计 30 个知识源、195 个证据单元;列表里每份文档显示格式、适用型号、批次和证据单元数,可以查看切片、重新解析、禁用或归档

30 份演示资料,切出来 195 个证据单元。每个证据单元有一个全局唯一的编号:

python
def evidence_id_for(source_type: str, document_id: int, seq: int) -> str:
    """证据 ID:`M01001` = 手册 + 文档 01 + 第 001 片。"""
    prefix = EVIDENCE_ID_PREFIX.get(source_type, DEFAULT_EVIDENCE_PREFIX)
    return f"{prefix}{document_id:02d}{seq:03d}"

前缀按资料分类走:手册 M、工单 T、FAQ F、图纸 D、表格 X。这张前缀表放在 app/domain.py,因为「工单」「图纸」是售后行业的词汇,解析模块本身不认识它们。

为什么不用 UUID?因为这个编号是要给人看的。它会出现在大模型的回答里([M23002])、浮层的引用列表里、后台的问答日志里。工程师和主管看到 T08005,能一眼认出这是「工单类资料、第 8 份文档、第 5 条」。第 5 篇会讲,引用校验也正是靠这个格式从回答里把编号抽出来的。

二、出处随格式走 ​

不同格式能提供的「出处」不一样,这个项目的原则是:有什么写什么,没有的不编。

格式出处页码
PDF章节号 + 页码,如 §2.6 · P12逐段精确到页
Word / Markdown / TXT章节标题一律为空
Excel FAQ工作表 + 行号,如 FAQ 第 2 行为空
通用表格(台账、记录表、CSV)工作表 + 行号为空

Word 的页码为什么是空的?Word 文件里根本没有「页」这个概念,分页是打开它的软件现场排出来的,换个字体、换个纸张大小,页码就变了。按字数估一个页码当然可以,但那就是一个看起来很精确的假页码。解析器的注释写得很直白:

Word 的分页由渲染器决定,落库时不能凭字数估算,否则引用会指到不存在的页码。

宁可只给章节,也不给一个会把人带错地方的页码。

三、PDF:先信目录,再清噪声 ​

PDF 是售后资料里最常见的格式,也是最麻烦的。

章节:优先用书签目录 ​

很多手册 PDF 自带书签目录(TOC),它就是「章节 → 页码」的权威映射,比从字体大小猜标题可靠得多。解析器优先用它。

没有目录的 PDF 才走兜底:用正则识别几种明显的标题形态,「第一章」「第二节」「2.6 抱闸故障」「附录 A」。注释里有一句我很认同的话:宁可漏认也不误认。漏认一个标题,最多是一整页变成一个块,引用粒度粗一点;误认一个标题,正文就被切进了错误的章节,引用会指错。编号标题还多了一条限制,数字后面必须紧跟中文,否则「24 小时服务热线」也会被当成第 24 章。

三类噪声 ​

PDF 抽出来的文本里混着三类东西,不清掉会直接污染出处:

  1. 页眉页脚:书名、文件编号、版本号,每页都有。不清掉的话,每个切片里都混着一行「××维修保养手册 · 文件编号 · 版本号」之类的文字,向量检索会被它严重干扰。
  2. 目录行:「2.6 抱闸故障 ………… 12」。看着像标题,其实不是正文,绝不能当成章节。
  3. 页码、热线、网址:不承载知识,还会干扰标题识别。

页眉页脚的识别靠「跨页频率」:

python
def _boilerplate_lines(page_lines: list[list[str]]) -> set[str]:
    """跨页重复出现的短行 = 页眉/页脚,返回其"签名"集合。"""
    if len(page_lines) < 2:
        return set()
    threshold = max(2, math.ceil(len(page_lines) * 0.5))
    ...
    return {
        key
        for key, count in counts.items()
        # 标题样式的行不参与"页眉"判定:它可能既是真标题、又是续页页眉
        if count >= threshold and 4 <= len(key) <= 80 and key not in heading_sigs
    }

modules/doc_ingest/pdf.py#L78-L100

一行短文本在一半以上的页面都出现过,就判定为页眉页脚。比较之前先把行尾的页码去掉,「文件编号… 版本:3 1」和「… 2」才会被认成同一行。

踩坑:标题也会「跨页重复」

有些手册在每一页顶部重复当前章节的标题(续页页眉)。按频率规则,它会被当成页眉删掉,真正的章节标题也就跟着没了。所以长得像标题的行不参与页眉判定,续页上的重复标题交给章节切分那一步,按「和上一节同名就跳过」来处理。

页码要逐段归属 ​

一个章节可能横跨好几页。最省事的做法是整节共用一个页码范围「P12–P14」,但一个切片如果只包含第 13 页的内容,引用写「P12–P14」就让人白翻了两页。

所以解析结果里每个章节都保留了「每一页各自的文本」,切片时逐段标注所在页码,一个切片的页码范围就是它实际包含的那几页。

扫描件直接拒收 ​

有些 PDF 是扫描件,整份都是图片,一个字也抽不出来。判断很粗暴:可提取的汉字数少于 max(20, 页数 × 5),就判定为疑似扫描件,入库失败,提示「需要 OCR 后再入库」。不做 OCR 是有意的:OCR 的识别错误会变成「带引用的错误参数」,这比没有这份资料更危险。

四、切片:不跨章节,不糊页码 ​

解析之后是切片。切片器开头的注释列了三条约束:

  1. 原子是切片,不是文件:每块都要能单独作为证据被引用
  2. 出处随格式走:PDF 的每块必须带准确页码
  3. 不做无依据的合并:小块宁可单独成块,也不和别的章节拼在一起

具体规则:每块上限 700 字、下限 120 字;段落优先,一段太长就按句号切,句子还太长就硬切(中文没有空格,没法按词切);每块正文以章节标题开头,这样检索命中时,模型能看到「这段话出自哪一节」。

最关键的是第三条,体现在合并小块的逻辑里:

python
def _merge_small(drafts: list[ChunkDraft], *, min_chars: int) -> list[ChunkDraft]:
    """把过短的块并回**同一章节**的前一块;跨章节不合并(合并会让引用指错节)。"""
    merged: list[ChunkDraft] = []
    for draft in drafts:
        if (
            merged
            and len(draft.text) < min_chars
            and merged[-1].section_no == draft.section_no
            and merged[-1].heading == draft.heading
            and len(merged[-1].text) + len(draft.text) <= min_chars * 3
        ):
            previous = merged[-1]
            previous.text = previous.text + "\n" + draft.text
            previous.page_from = min(previous.page_from, draft.page_from)
            previous.page_to = max(previous.page_to, draft.page_to)
            continue
        merged.append(draft)
    ...

modules/doc_ingest/chunker.py#L147-L167

很多 RAG 教程会把短块往前后拼,凑够长度再说。对一般问答这没问题,但在这里,§2.6 末尾的一小段和 §2.7 开头拼在一起,这个切片该标哪一节?标哪一节都有一半是错的。所以短块只能并回同一章节的前一块,跨章节宁可留一个短块。

切片粒度没有标准答案

700 / 120 这组数是在这批演示语料上调出来的,后台和 .env 都能改。判断粒度合不合适,我用的是一个很土的办法:随机抽十个切片,问自己「如果只给我看这一块,我能不能判断它在说什么、出自哪里」。能,粒度就差不多;不能,要么太碎,要么混了太多东西。

五、表格:每一行都是一条证据 ​

售后资料里有大量表格:FAQ、工单台账、维保记录表、部件更换记录。表格不按字数切,一行一条证据。

FAQ 最简单,一行就是一个「问题 + 答案」,本身就是完整的证据。通用表格麻烦一点:一行数据单独拿出来是「HY-G1000 | B23 | 0.20 | 0.40」,模型完全看不懂这几个数是什么。所以每一行都渲染成「列名:值」的形式,大致是这样(示意):

text
型号:HY-G1000/1.6-JXW
批次:B23 及以后
间隙下限(mm):0.20
间隙上限(mm):0.40

表头是语义的一部分,丢了表头,数字就没有意义。

找表头本身也有讲究。很多 Excel 第一行是合并单元格的大标题(「宏远电梯部件更换记录表」),只有第一格有值,不能当表头。规则是:前 10 行里,第一行有两个以上非空单元格的才是表头;表头之前的标题和说明文字,单独存成一条「前言」证据,也不丢。

还有两个细节:

  • 行级批次。FAQ 表里可以有一列「适用批次」,填了值的行,批次以行为准;没填的行继承整份文档的批次;两者都空就是「不限批次」。这一列叫什么名字(「适用批次」「批次」「batch」)由 app 注入,解析器不认识行业词。
  • 行数上限。一张表超过 5000 行直接拒收,提示拆分。表格入库会产生大量切片,不能无限吃。

六、流水线:幂等、可重跑、失败要说清楚 ​

一份文件从上传到可检索,经过这几步:

后台解析任务页:每个任务显示上传、解析、切片、向量化、入库五个阶段的进度,以及运行中、排队中、失败、完成的计数

建档时按 sha256 去重。同一份文件上传两次,只会建一份档案。批量导入用的是一个命令行脚本,而不是启动时自动扫目录:

自动扫描会在启动时意外把新文件入库,「入库」是治理动作,应由人触发。

原件统一复制进 data/original-docs/,后台的「原件在线预览」只允许读这个目录。

解析失败要说人话。疑似扫描件、解析成功但一个有效切片都没有、向量条数和切片数对不上,每种失败都会把具体原因写回文档状态,后台能直接看到「为什么失败」,而不是一个笼统的「解析出错」。

向量化走 OpenAI 兼容接口,默认是本机 Ollama 跑 bge-m3。仓库里记了一组实测数据:单条冷启动约 9.2 秒(加载模型),批量 8 条约 754 毫秒。所以向量化一定要分批,默认每批 16 条。返回的维度如果和库表的 vector(1024) 对不上,抛的是配置错误,不重试,因为重试一万次也还是错的维度。

落库是先删后建,在一个事务里:

python
# 入库事务:先删旧切片再整体写入,保证重复解析不翻倍
with conn.cursor() as cur:
    cur.execute("delete from chunks where document_id = %s", (doc_id,))
    for draft, vector in zip(drafts, vectors, strict=True):
        # 行级批次优先;行内没填则继承文档批次(两者都空 = 不限批次)
        chunk_batch = draft.batch or batch
        ...
        cur.execute("insert into chunks (...) values (...)", (
            doc_id,
            evidence_id_for(category, doc_id, draft.seq),
            draft.text,
            ...
            _vector_literal(vector),
            _tokenize(draft.text),     # jieba 预分词,BM25 直接用
        ))

app/ingest.py#L262-L299

同一份文档解析多少遍,结果都一样,不会翻倍。改了切片参数想重新切,点一下「重新解析」就行。BM25 要用的分词结果也在这一步顺手算好存起来,第 3 篇的内存 BM25 索引就是直接读这一列。

zip(..., strict=True) 是一个小保险:向量和切片条数不一致时,宁可在这里报错,也不能让第 5 条切片配上第 6 条的向量。前面已经单独检查过一次条数,这里是第二道。

七、小结 ​

原则落在哪
知识库的原子是证据单元每块有人能读懂的全局编号 M01001
出处随格式走,不编页码Word / 表格页码为空;PDF 逐段归属页码
宁可漏认,不误认标题识别只认明显形态;扫描件直接拒收
不跨章节合并短块只并回同一章节的前一块
表头是语义的一部分表格每行渲染成「列名:值」
入库是治理动作人工触发导入;sha256 去重;先删后建保证幂等

资料变成了一块块带编号、带出处的证据,存进了 PostgreSQL。接下来它们怎么被找出来,是第 3 篇的内容;找出来之后够不够格回答,是第 4 篇。

本文阅读--次|全站访问--次|访客--人