Skip to content

跨境客服助手(三):700 字切片与一条过期政策:知识入库流水线 ​

上线前最容易被低估的一段,是知识入库。

问答出问题,大家第一反应是改提示词、换模型、调阈值;但很多错误的根在更早的地方:政策文件的 YAML 头被切进了第一条证据,模型把它当正文引用给客户;PDF 的出处标错了一页,点开引用看到的是目录;旧版政策没有禁用,检索时和新版一起召回。

这条流水线在 app/ingest.py 和 modules/doc_ingest/,做的是“把原件变成可检索、可核验出处的证据单元”。

后台知识源管理:每份文档显示格式、分类、适用国家与状态,右侧能看到证据单元数量;归档版本的切片会标为不可检索

一、全链路:从上传到可检索 ​

text
上传 / 批量导入
  → documents 建档(sha256 去重)
  → jobs 入队(或 --parse-now 同步解析)
  → 解析:PDF / DOCX / MD / TXT / Excel / CSV
  → 切片:700 字上限、120 字下限
  → 向量化:bge-m3,1024 维,批大小 16
  → chunks 落库(正文 + 元数据 + 向量 + BM25 预分词)

管理后台上传和批量导入共用同一张后缀映射表,新增格式只改一处。建档时算 file_sha256,同一份文件重复上传直接返回已有文档,不会建出两份。

解析既可以同步做,也可以入队交给 worker。批量导入常用 --parse-now --no-enqueue:当前进程直接解析,避免同一批文档既同步跑又排队跑一遍。

二、front matter 不是正文 ​

演示语料是 Markdown,每份文件顶部有 YAML:

yaml
---
doc_id: return-policy
title: Return Policy
version: "2.0"
effective_date: 2026-01-01
expires_on: 2027-01-01
applies_to: [US]
status: current
---

这些字段决定检索时的国家过滤和有效期过滤。但它们不是给客户看的内容。如果直接整份文件送去切片,第一块证据里就会包含 doc_id: return-policy,模型完全可能把它当原文引用出来。

所以入库前先剥:

python
raw_text = path.read_text(encoding="utf-8", errors="replace")
_front, body = parse_front_matter(raw_text)
if body != raw_text:
    # 只把正文写进临时文件再解析,元数据走 documents.meta_json
    parsed = parse_plaintext(body_path)

元数据随后被整理成 camelCase,下放到每条切片:

python
inherited_meta = {
    key: doc_meta[key]
    for key in ("docId", "category", "version", "appliesTo",
                "expiresOn", "effectiveDate", "status", "language")
    if doc_meta.get(key) not in (None, "", [])
}

下放的好处是检索后置过滤只查 chunks 一张表,不用回表 join documents;也不会因为文档元数据后来被改,出现“切片看不出来源”的情况。

三、切片的三个约束 ​

切片器的参数是 max_chars=700、min_chars=120。三个约束来自一个目标:每块都能单独作为证据被引用。

约束一:出处随格式走 ​

PDF 的出处是页码,所以不能用“估算页码”。解析时保留逐页文本,切片按页归属:

python
for page_no, page_text in section.page_texts:
    for paragraph in _paragraphs(page_text):
        items.append((page_no, paragraph))

一块跨了两页,就记 page_from 和 page_to。点开引用能落到正确的页,这是“可核验”的最低要求。

约束二:不做无依据的合并 ​

段落优先切;单段超过预算时按句号硬切;短于 120 字的块并回前一块,但只限同一章节。

跨章节合并会让引用指错地方:客户点开“退货期限”的引用,看到的却是上一节“配送说明”。宁可多一块短证据,也不做这种合并。

约束三:标题随块走 ​

每块正文以章节标题开头,检索命中时模型能看到“这是哪一节”。如果正文第一行已经是标题,就先去掉再统一补,避免每块重复两遍。

表格类资料例外:FAQ Excel 和数据表按“一行一条记录”切,正文拼成“列名:值”,首列作为章节分组。单文件超过 5000 行直接拒绝,要求拆文件——一行一片的情况下,超大表会把检索噪声放大。

四、过期政策:入库,但禁用 ​

那条 60 天的旧退货政策没有被删掉,而是以 status: archived 入库。

这是刻意的:留档才能解释“为什么以前这么答”,也方便审计。但它不能参与检索,所以入库时给每条切片打上 disabled=true:

python
blocked_reason = inactive_reason(doc_meta)   # status=archived / expiresOn 已过
...
chunk_meta["disabledReason"] = blocked_reason

chunks.disabled 是检索的硬过滤条件;即使有人绕过它,第二篇讲的后置过滤还会按 status 和 expiresOn 再挡一次。两层防线看起来重复,但一层是存储约束,一层是业务语义,改一处不影响另一处。

评测集里有 3 条“新旧冲突”用例带 noArchived: true,专门断言回答不能引用归档切片。没有这条断言,禁用逻辑坏了也不会被发现。

五、幂等:重复解析不翻倍 ​

同一份文档改了元数据、换了 embedding 服务,都需要重新解析。如果每次追加切片,知识库会迅速变成一团重复。

所以落库事务是“先删后写”:

python
cur.execute("delete from chunks where document_id = %s", (doc_id,))
for draft, vector in zip(drafts, vectors, strict=True):
    cur.execute("insert into chunks (...) values (...)")

同一文档重复解析多少次,切片数都只跟当前版本有关。文档级的 file_sha256 则挡住“同一份文件建两次档”。

六、证据 ID:一眼能看出出处 ​

切片落库时生成 evidence_id,格式是“分类前缀 + 两位文档号 + 三位序号”,例如 RP01003。

前缀按资料分类走:退货政策 RP、配送 SP、尺码 SZ、支付 PM、隐私 PR、促销 PV、订单 OP、FAQ FQ。后两段保证全局唯一且可排序。

这个 ID 会出现在引用卡片、后台切片预览和导出文件里。它不承载业务含义,但能让人快速判断“这条是政策还是 FAQ”,排查串库问题时很有用。

七、这条流水线的边界 ​

  • 不做 OCR。整份 PDF 抽出的有效文本少于 max(20, 页数 × 5) 个字符时判为疑似扫描件,直接提示需要 OCR,而不是硬塞空切片;
  • 切片质量受原件结构影响。多栏排版、表格嵌图的 PDF,解析出来仍然可能是乱的;
  • 碎片会被过滤。切片后短于 20 个字符的残片直接丢弃(MIN_DRAFT_CHARS=20),页眉、目录这类碎片不会成为证据;
  • 语言以英文语料为主。BM25 用 jieba 预分词,英文能切,但中文语料的检索效果没有专门评测。

入库决定了检索的上限。下一篇换一条完全不同的路:订单和物流不查知识库,查工具;而工具会超时,超时之后说什么,才是真正需要设计的地方。

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