智能体工程 · 11j
一张表拆成几块,行列对应还在吗?
读完能做的判断:按输入合同、布局歧义与最终预算保护表头、单元格和证据关系。
表格分块与证据保真
⏱ 阅读约 31 分钟 · 动手实践另计
本章保留教学代码、路径说明与历史验证结论;完整实验工程和运行记录未随本站及公开仓库分发。命令用于说明调用方式,复现需自行准备对应实现、数据与环境。
一句话带走:长表按完整行分组时,型号、单位、条件和脚注必须一起走;能追溯到人工确认的输入,不等于自动识别了复杂 PDF 表格。
表格分块的检查项
在 t01 中核对整表被拒的原因、分组数量,以及各行是否有独立出处。接着检查特殊字符、空白、权限和修订,并添加一个待人工复核标记,观察它怎样阻断处理。
本章接在 PDF 与表格解析实验 后面,继续保留整表超过 8000 字符的限制。输入为原创人工结构化 JSON,调用同一个 SQLite 核心;不是 扫描件 OCR 与人工复核 的输出,两个模块没有接口依赖。
重排与上下文预算实验 讨论证据如何进入上下文;这里先保证表格行的身份与条件。不运行生成模型。
按原示例目录结构,测试与演示命令如下:
python -m unittest discover -s examples/knowledge-assistant -p test_table_lab.py -v
python examples/knowledge-assistant/table_lab.py
在示例 knowledge-assistant 目录内,对应命令为:
python -m unittest test_table_lab -v
python table_lab.py
原示例环境使用 examples/knowledge-assistant/.venv/Scripts/python.exe。模块只用标准库与现有 core,默认创建 .runtime/table-日期时间/,包含 demo、Markdown、manifest 与 provenance;同名目录拒绝覆盖。
从整张表看见三个不同问题
参数表有 250 行,查询 PX-100 要找到对应型号及条件。整表保留关系但太长;行组重复必要上下文,让每一组能独立引用。
| 处理方式 | 留下什么 | 本实验的边界 |
|---|---|---|
| 平铺文字 | 一串字符,原来的列与行身份可能不清楚 | 不运行自动平铺;它不能作为完整表格关系的证明 |
| 整表保留 | 表头、整张表的行关系和说明 | 现有 core 保持超过 8000 字符明确拒绝 |
| 连续行组 | 完整行、重复表头/单位/条件/脚注、逐行页码与行 ID | 依赖人工已确认结构;单行带上下文仍超预算就拒绝 |
输入契约先把“确认过”说清楚
输入包含表身份、来源修订、列、条件、脚注和行。key 对应单元格,label/unit 是表头;人工提供的 page/row_id 保留原页与稳定行身份。
一条完整行的写法如下,完整契约见 schema(examples/knowledge-assistant/fixtures/structured-tables/schema.md)。
{"row_id": "r001", "page": 2,
"cells": {"model": "PX-100", "pressure": "0.0500"}}
validate_table(value) 拒绝缺列、重复列 key、重复 row_id、空型号、非法页码和非法修订。每一行 cells 的键必须与 columns 完全一致。布尔值不能冒充页码 1,字符串页码也不能被悄悄转换。额外的 rowspan、colspan 或行级表头字段都拒绝;整理器没有解释这些布局的能力。
所有单元格值只接收原始字符串或 JSON null。"0.0500" 与 "5e-2" 保持原文,不化成浮点数,也不从 MPa 换算成 kPa。空字符串表示输入明确留空,null 表示未知,两者的 provenance 值不同;程序不会把未知补成零。零是一个数据值,会改变后续判断,不能充当“我们没读清”的替代物。
空白型号拒绝,不自动向下填或拼接相邻型号。人工确认后可以显式重复完整型号;同型号不同工况仍是不同记录。
t05 的完整行来自第 2–5 页,共同表头已人工确认。接受 JSON 不能证明原 PDF 没换单位;若单位变化,先人工拆表。
遇到布局歧义,整表停止
manual_review_required 是可选的原因列表。一旦非空,chunk_table 在输出任何行组前拒绝。t06 标记第二页从 MPa 换成 kPa;t07 标记合并跨度尚未解决、跨页续行归属不确定。它们都返回 manual_review_required,没有输出“恢复完成”的文字。
标记是人工声明,不能检测遗漏的歧义。合法 JSON 也可能配错原表的行,仍需人工核对。t08 缺列、t09 空型号直接违反契约;不能填默认值绕过拒绝。
预算数的是最终证据块
chunk_table(value, max_chars=1200) 按输入顺序逐行尝试加入当前组。一次加入会渲染完整表块,再用 Python len(body) 判断是否超限。预算包括表名、source_id、修订、所有列名与单位、条件、脚注、Markdown 分隔符,以及每行的 page 与 row_id;不是只加单元格长度。
每块先写列头与上下文,再写数据行。条件与脚注适用整个输入表,每组完整复制;脚注范围不同应先人工拆表。
当前组放不下新行时,先结束当前组,再用完整上下文开启下一组。任何一行独立渲染后仍超过预算,都返回 single_row_exceeds_budget。程序先为整表完成这个检查,再写新目录或调用入库;所以 t10 即使只有最后一行过长,也不会先发布前面的正常行。
不得、仅、批准后、日期、单位和原字符串精度不截断。字面保留不等于理解工况;字符数不等于模型 token 数,还需为引用和提示词预留空间。
特殊字符有两份可核对的表示
如果单元格原文包含 a|b,直接插进 Markdown 会增加一列;换行可能产生新行或新段落;<script> 之类文字也不应成为可执行 HTML。encode_cell 把管道、换行、HTML 与 Markdown 控制字符编码成数字实体。整理结果是一张合法表,原文没有被解释成表结构或执行指令。
t11 保留管道、换行、HTML 标签与 Markdown 链接文字。provenance 的 rows 保存原始字符串,rendered_rows 保存对应呈现值;decode_cell 可以反向核对。实体长度计入预算。PX_100 内部下划线原样保留,让原文查询与core词项一致;强调分隔的下划线仍转义。
null 显示为 [unknown:null],空字符串显示为 [blank:string]。原文若恰好写着这些标记,方括号先转义,仍能反查为字符串;审查以 provenance 原始值为准。
每组 JSON 记录 source_id/table_id/source_revision,每行记录 row_id/page。ordinal 随预算改变,稳定 row_id 不随之改变;页映射不能从生成的 Markdown 反推。
一个表一次原子发布,再检索当前授权块
publish_table 接收独立的可信管理员参数:tenant、doc_id、revision、title、readers。表格内容没有这些权限字段,额外顶层字段会被拒绝;单元格里写 readers=[*] 仍只是文字。t13 正是这个例子,正文没有把跨租户身份变成可读用户。
发布修订必须与 source_revision 一致。所有行组写进一份 table.md,每组前面使用独立标题清空现有解析器的前文状态,再调用未修改的 core.ingest(..., chunk_chars=8000)。不是把一张表分成十二个独立数据库提交:十二组属于一个文档的一次发布,core 事务失败时一起回滚。
预检失败不创建目录;数据库故障可留下暂存文件,但 documents/chunks 一起回滚。多个表独立发布,没有跨表事务。
retrieve_table 真实调用 BM25,预算按当前授权块完整body加title/section及core出处开销计算,避免合法大行组遭固定6000预算遗漏;包装超20000上限则明确拒绝,不截断。再复验 ACL/修订,只返回当前可见上下文及 chunk_id/revision/quote,无候选诊断。validate_citations 检查出处,不检查回答蕴含。
复验是当前快照。测试在检索后、导出前撤权,输出为空;生产并发响应原子性仍需另外设计。
真实运行留下哪些证据
2026-10-11 在 Windows、Python 3.12.14、SQLite 3.53.1 上实际运行 13 场景:8 发布、5 拒绝,符合预先写明的预期。原创虚构夹具证明接口行为,不能当真实设备验收。
t01 原整表 10813 字符,core 返回 table_requires_row_chunking。相同 250 行经 1200 字符预算整理为 12 组,每组 1053–1185 字符,顺序完整,每行恰好出现一次。入库后对 PX-100 的真实查询返回可见证据与有效引用。整表限制没有放宽。
同一次 demo 撤掉 t01 的 reader 权限,检索输出为空,先前引用返回 citation_not_current_or_permitted;随后恢复权限并发布 source_revision=2,旧 revision=1 引用仍失效,新修订可以检索。报告没有给撤权请求输出原文或候选 ID。
审查后的 demo(examples/knowledge-assistant/validation/table-reviewed-20261011/demo.json) 保存输入、配置、环境/代码哈希、预算、原值/呈现映射、行来源、检索和整表失败对照,旧development记录保留。行为 RED(examples/knowledge-assistant/validation/table-red-contract-20261011.txt)、生命周期 RED(examples/knowledge-assistant/validation/table-red-demo-lifecycle-concise-20261011.txt) 与 审查回归 RED(examples/knowledge-assistant/validation/table-review-red-20261011.txt) 都保留。最新 GREEN(examples/knowledge-assistant/validation/table-review-green-20261011.txt) 为13项通过;审查回归实际确认PX_100和6523字符完整块均能检索。未改既有gold,没有生成正确率。
走神救援
只打开 demo.json 的 whole_table_control 和 cases[0]。先看原表长度,再数 chunks,选一组核对表名、MPa、不得、日期、row_id 和 page,最后比较 provenance 的原值与呈现值。若还没准备好看代码,在这里停下也能得到本章的主要结论。
再回来时选 t06 与 t10:前者关系未确认,回来源复核;后者单行超预算,调整资料组织或预算,不能截掉否定条件。
核对真实资料的来源、页码、单位和脚注,未确认的行保留复核标记。送入问答系统前,按 上下文预算 检查引用包装后的长度。
折叠自检
检查点 1. 这份表是不是从 PDF 自动恢复的?
不是。输入为原创人工结构化 JSON;行组算法不解析扫描件、OCR、合并单元格或续行。
检查点 2. 空型号能用上一行填上吗?
不能自动填。只有人工查明并显式重复完整型号才允许;缺列、空型号和重复行 ID 直接拒绝。
检查点 3. null、空字符串和零一样吗?
不同。null 未知,空字符串明确留空,零是数据值。provenance 保留原始类型,代码不换算数值。
检查点 4. 单元格文字够短就符合预算吗?
不一定。最终 body 还包含表名、来源修订、单位、条件脚注、每行出处、转义实体与表格符号。
检查点 5. 跨页完整行与跨页续行为何不同?
完整行与共同表头已由人确认,可以分组;续行归属或表头变化未解决,必须停止,算法不自行推断。
检查点 6. 转义是否丢了管道和换行?
没有。原始值存在 rows,呈现值存在 rendered_rows,decode_cell 可反向核对;HTML 文字不会变成执行标签。
检查点 7. 最后一行过长,前面的行会先发布吗?
不会。整表先完成预算预检,再以一个文档调用 core 原子入库;数据库故障回滚所有行组。
检查点 8. 出处有效就等于回答正确吗?
不等于。引用还要保持当前授权与修订;字面出处通过也没有证明语义、真实页映射或生成答案正确。
来源与采用范围
语雀 112.RAG 表格识别 提供主题线索。页面显示 PDF 附件,PDF 正文未读;不能把本章的 schema、行组算法或运行结果归为原作者的方案。pypdf 官方文本提取说明 用于核对边界:PDF 中的表格通常由定位文字组成,行列与合并关系难以恢复,pypdf 本身不进行图像 OCR。官方说明不验证本章整理器的质量;代码、原创夹具和真实 SQLite 结果承担各自的证据范围。