真实文件入库:从PDF、Word和HTML保留出处
生成三份真实文件,调用解析器提取文字与表格,并把页码、坐标、正文位置传给语义检索。
前面用Markdown字符串把检索跑通。实际资料通常是PDF、Word或网页文件。这次先生成三份可重复的小文件,再读取其中的段落和表格,让来源位置跟着内容进入检索。
解析产物为什么不只是一个长字符串
退款政策的“普通商品七天可退”与“定制商品不支持”同样重要。把后一句漏掉,检索和重排越稳定,越可能稳定地返回不完整条件。我们保留每段内容以及来源坐标:PDF记录页码和bbox;DOCX记录正文元素序号,表格再带行列;HTML记录所选元素序号与标签。
DOCX的页码会随字体和分页设置变化,所以这里使用稳定到当前文件结构的正文元素位置。HTML元素序号也只对应当前文件快照,发布新版时应更新版本。
保存完整解析程序
继续使用第07节的独立环境与目录。安装文件已经包含pymupdf、python-docx和beautifulsoup4,无需额外账号。保存下面完整文件为 ingest.py。
create_samples写入真实二进制PDF和DOCX,以及HTML文件。parse读取它们,PDF的blocks给出矩形坐标;Word用iter_inner_content保留段落和表格的主体顺序;HTML先去除脚本/样式,再提取正文元素。表格示例只含单层表头、无合并单元格;复杂跨页表格需要额外处理表头继承和阅读顺序。
"""生成并真实解析 PDF、DOCX、HTML;输出可直接交给 kb.Knowledge.publish。"""
import json
from pathlib import Path
import os
import pymupdf
from docx import Document
from bs4 import BeautifulSoup
def create_samples(folder):
folder.mkdir(parents=True, exist_ok=True)
# 内置 CJK 字体避免依赖作者机器的中文字体文件;这是文本 PDF,不是扫描件。
pdf = pymupdf.open()
page = pdf.new_page()
page.insert_text((60, 80), '退款政策:普通商品收到后七天内可以退款。', fontname='china-s', fontsize=12)
page.insert_text((60, 110), '例外:定制商品不支持无理由退货。', fontname='china-s', fontsize=12)
pdf.save(folder / 'refund.pdf')
pdf.close()
doc = Document()
doc.add_heading('生产数据库访问', 0)
doc.add_paragraph('只读权限需系统负责人批准,有效期七天。')
table = doc.add_table(rows=1, cols=2)
table.rows[0].cells[0].text = '权限'
table.rows[0].cells[1].text = '有效期'
cells = table.add_row().cells
cells[0].text, cells[1].text = '只读', '七天'
doc.save(folder / 'access.docx')
(folder / 'travel.html').write_text('''<!doctype html><html><body>
<h1>差旅报销</h1><p>出差结束后十个工作日内提交发票。</p>
<table><tr><th>项目</th><th>材料</th></tr>
<tr><td>国际差旅</td><td>汇率凭证</td></tr></table>
<script>不得进入正文的脚本内容</script></body></html>''', encoding='utf-8')
def parse(path):
"""返回元素文本和来源坐标;不运行宏、脚本、外部连接或 OCR。"""
elements = []
if path.suffix == '.pdf':
with pymupdf.open(path) as pdf:
for page_number, page in enumerate(pdf, 1):
for block in page.get_text('blocks', sort=True):
if block[6] == 0 and block[4].strip():
box = ','.join(f'{v:.1f}' for v in block[:4])
elements.append((block[4].strip(), f'page={page_number};bbox={box}'))
if not elements:
raise ValueError('未提取到文本:可能是扫描件,需要独立 OCR 流程')
elif path.suffix == '.docx':
doc = Document(path)
# 按 XML 主体顺序迭代段落和表格,避免把所有表格移动到文末。
for index, item in enumerate(doc.iter_inner_content(), 1):
if hasattr(item, 'text'):
if item.text.strip():
elements.append((item.text.strip(), f'body={index};paragraph'))
else:
headers = [cell.text for cell in item.rows[0].cells]
for row_index, row in enumerate(item.rows[1:], 2):
text = ';'.join(f'{key}:{cell.text}' for key, cell in zip(headers, row.cells))
elements.append((text, f'body={index};table-row={row_index};columns=1-{len(headers)}'))
elif path.suffix == '.html':
soup = BeautifulSoup(path.read_text(encoding='utf-8'), 'html.parser')
for node in soup(['script', 'style']):
node.decompose()
for index, element in enumerate(soup.select('h1,h2,p,tr'), 1):
cells = element.find_all(['th', 'td'])
text = ' | '.join(c.get_text(' ', strip=True) for c in cells) if cells else element.get_text(' ', strip=True)
if text:
elements.append((text, f'element={index};tag={element.name}'))
else:
raise ValueError('不支持的格式')
return elements
def ingest(folder, tenant):
rows = []
for path in sorted(folder.iterdir()):
if path.suffix not in {'.pdf', '.docx', '.html'}:
continue
for index, (text, coordinate) in enumerate(parse(path)):
# 来源坐标保留在每个块上;长元素需另做保留偏移的分块。
rows.append(dict(tenant=tenant, document=path.stem, revision=1,
id=f'{path.name}@1:{index}', title=path.stem, text=text,
source=f'{path.name}#{coordinate}'))
return rows
if __name__ == '__main__':
root = Path(os.getenv('RETRIEVAL_STATE', Path(__file__).parent / '.runtime'))
folder = root / 'documents'
create_samples(folder)
rows = ingest(folder, 'alpha')
root.mkdir(parents=True, exist_ok=True)
(root / 'parsed.json').write_text(json.dumps(rows, ensure_ascii=False, indent=2), encoding='utf-8')
for row in rows:
print(row['source'], '=>', row['text'].replace('\n', ' / '))
print('元素数量', len(rows))Windows运行:
.venv/Scripts/python -X utf8 ingest.pymacOS/Linux运行:
.venv/bin/python -X utf8 ingest.py文件生成在.runtime/documents,解析记录写入.runtime/parsed.json。若设置了RETRIEVAL_STATE,则使用该目录。程序每次重建自己的同名教学文件;不要把客户原件放进这个样本生成目录。
对照原件和实际输出
access.docx#body=1;paragraph => 生产数据库访问
access.docx#body=2;paragraph => 只读权限需系统负责人批准,有效期七天。
access.docx#body=3;table-row=2;columns=1-2 => 权限:只读;有效期:七天
refund.pdf#page=1;bbox=60.0,68.0,300.0,82.4 => 退款政策:普通商品收到后七天内可以退款。
refund.pdf#page=1;bbox=60.0,98.0,252.0,112.4 => 例外:定制商品不支持无理由退货。
travel.html#element=1;tag=h1 => 差旅报销
travel.html#element=2;tag=p => 出差结束后十个工作日内提交发票。
travel.html#element=3;tag=tr => 项目 | 材料
travel.html#element=4;tag=tr => 国际差旅 | 汇率凭证
元素数量 9九个元素里,PDF保留了退款例外,Word表格保留了“权限→只读”“有效期→七天”的列关系,HTML保留了国际差旅与汇率凭证。HTML表头与数据行目前分别保留,尚未把表头上下文合并进每条记录;若单独检索表格行,需要补充该上下文。
这里没有OCR。扫描PDF可能没有任何文本块,代码会显式报错,要求进入独立OCR流程;不能将空字符串静默发布。双栏PDF的sort=True也不是通用版面理解保证;复杂资料需要对照原件核查顺序。DOCX页眉、页脚、批注、文本框、修订标记和嵌套/合并表格都不在当前解析范围内。
把真实解析块送进检索
保存 query_files.py,与第07节的kb.py、本节的ingest.py放在同一个目录:
"""真实文件解析 → 实际编码 → 真实CrossEncoder;来源随候选返回。"""
from kb import Knowledge, STATE
from ingest import create_samples, ingest
folder = STATE / 'documents'
create_samples(folder)
rows = ingest(folder, 'alpha')
kb = Knowledge()
kb.publish(rows)
rankings, timings = kb.search('定制商品能无理由退货吗', 'alpha')
for hit in rankings['reranked'][:3]:
print(hit['source'], '=>', hit['text'])
print('这是检索候选,不是生成答案;必须同时检查普通规则与例外。')用同一解释器运行python query_files.py,Windows完整写法为.venv/Scripts/python -X utf8 query_files.py,macOS/Linux为.venv/bin/python -X utf8 query_files.py。这会将活动索引替换为本节的文件块,重新运行第07节evaluate.py可恢复其独立样本。
实际查询返回:
refund.pdf#page=1;bbox=60.0,98.0,252.0,112.4 => 例外:定制商品不支持无理由退货。
refund.pdf#page=1;bbox=60.0,68.0,300.0,82.4 => 退款政策:普通商品收到后七天内可以退款。
travel.html#element=1;tag=h1 => 差旅报销
这是检索候选,不是生成答案;必须同时检查普通规则与例外。第一条来源定位到退款例外,第二条给出普通规则;第三条虽然进入候选,但与该问题无关。回答时需要检查支持关系,不能把全部top-k拼成结论。
用回归测试抓住解析退化
保存 test_contracts.py。测试读取真实生成文件,检查否定词、表格头值关系、HTML脚本排除和来源唯一性,临时文件只放在项目目录。
"""不用权重的真实解析回归;模型与更新/租户检查由 evaluate.py 实跑覆盖。"""
import tempfile
import unittest
from pathlib import Path
from ingest import create_samples, ingest, parse
class ParsingTests(unittest.TestCase):
def setUp(self):
root = Path(__file__).parent / '.runtime'
root.mkdir(exist_ok=True)
self.temp = tempfile.TemporaryDirectory(dir=root)
self.folder = Path(self.temp.name)
create_samples(self.folder)
def tearDown(self):
self.temp.cleanup()
def test_pdf_negation_and_coordinate(self):
rows = parse(self.folder / 'refund.pdf')
self.assertTrue(any('不支持' in text for text, _ in rows))
self.assertTrue(all('page=1;bbox=' in source for _, source in rows))
def test_docx_table_keeps_header_and_value(self):
rows = parse(self.folder / 'access.docx')
self.assertIn(('权限:只读;有效期:七天', 'body=3;table-row=2;columns=1-2'), rows)
def test_html_no_script(self):
rows = parse(self.folder / 'travel.html')
self.assertFalse(any('脚本内容' in text for text, _ in rows))
self.assertTrue(any('国际差旅 | 汇率凭证' == text for text, _ in rows))
def test_ingested_provenance(self):
rows = ingest(self.folder, 'beta')
self.assertEqual(len(rows), 9)
self.assertTrue(all(r['tenant'] == 'beta' and r['source'] for r in rows))
self.assertEqual(len({r['id'] for r in rows}), len(rows))
if __name__ == '__main__':
unittest.main()Windows执行.venv/Scripts/python -m unittest test_contracts.py -v;macOS/Linux执行.venv/bin/python -m unittest test_contracts.py -v。正常情况下,四项测试均显示ok。这组测试保护否定词、表头和来源信息。换成业务资料后,按相同方法补充实际格式与失败样本。
课后练习展开习题收起习题
练习:让来源帮助排错
- 把PDF中“七天”改成“十四天”,重新生成和解析,核对文本、页码和bbox;文字变化后来源位置可能怎样变化?
- 给Word表格增加“管理员/一天”一行,检查输出是否仍保留列名以及正确行号。
- 只保留扫描图片、不含文本层的PDF会怎样?为什么返回“未提取到文本”比创建一个空块更容易排错?
参考检查思路
核对实际输出而非只查文件存在。行列和坐标属于当前文档版本,改排版后可能变化;扫描件需要OCR才能进入后续编码。解析失败应留在入库失败队列,不能靠增大top-k补回不存在的证据。
解析接口依据:PyMuPDF文本块与阅读顺序、python-docx文档对象。选用PyMuPDF进入其他项目时还要核对其许可证及项目使用条件。