Zerox 实战：视觉模型 OCR 金融组合报告，从 0013.pdf 到结构化 Markdown 的完整链路解析-平芜编程栈

OCR
AI 应用

【免费下载链接】zerox

OCR & Document Extraction using vision models

项目地址：https://gitcode.com/GitHub_Trending/ze/zerox

在 Zerox（README.md 中自述为 "A dead simple way of OCR-ing a document for AI ingestion"）的仓库里，shared/outputs/0013.md 是一份极具代表性的产物：它由 3 页 PDF 金融组合报告（shared/inputs/0013.pdf）经由视觉模型直接转换而来，完整保留了摘要、资产配置、行业分布、地域分布以及一张 32 行的税务过渡明细表。本文以这份输出文档为主体，结合仓库源码与测试框架，拆解 Zerox 的文档转 Markdown 流水线、表格结构的保真机制，并给出可复现的实战配置。

一、文档背景：一份来自 Zerox 的金融报告 OCR 产物

1.1 源文件与产物

仓库将输入与输出分开存放：输入文件位于 shared/inputs/0013.pdf，对应的 OCR 输出为 shared/outputs/0013.md。从输出内容可以确认，这是一份由理财顾问机构 Clark Capital 出具的客户组合分析报告，共 3 页，报告日期为 2023 年 1 月 31 日（文末注明 "As of 1/31/2023"）。

Zerox 把整份报告的内容完整继承到了 Markdown 中，覆盖：

组合概览：组合价值 $545k，股票/债券配置比例 82%/18%，投资风格为 Growth；
资产配置：现金 5.75%、美股 78.65%、非美股 3.45%、债券 12.12%、其他 0.03%；
组合构建方式：现金、ETF、共同基金、个股，股票持仓 634 只、债券持仓 9,748 只；
权益分析（第 2 页）：个股 96%、ETF 4%，风格矩阵、行业与地域分布及基准对比；
税务过渡/重叠分析（第 3 页）：市值 $138,494、未实现收益 $19,943，以及 32 行持仓明细表。

1.2 它在测试体系中的定位

shared/test.json 为每份输入定义了"预期关键词"（expectedKeywords）。针对0013.pdf，测试期望三页输出分别命中以下类型的关键词：

第 1 页：MSFT、AAPL、10.6%、Portfolio Value、$545k、82%/18% Stocks/Bonds、Cash、5.75、US Stocks、78.65、Total Stock Holdings、634、Total Bond Holdings、9,748等；
第 2 页：Your Equity Allocation、82%、Individual Stocks 96%、ETFs 4%、25% - 35%、600、Equity Style、Large/Mid/Small、Sectors、Consumer Def、Bmark%等；
第 3 页：Tax Transition/Overlap Analysis、$138,494、$19,943、PFIZER INC、($453)、RIO TINTO PLC SPONSORED ADR、ISHARES 5-10 YEAR IG CORP BOND ETF、PROCTER & GAMBLE CO、PG、1/31/2023等。

这意味着 shared/outputs/0013.md 不仅是演示产物，还是测试基准的一部分，可直接用于验证模型与流水线是否发生回归。

二、Zerox 的文档转 Markdown 流水线

2.1 核心逻辑

README.md 给出了 Zerox 的通用逻辑，正是这条链路生成了 0013.md：

传入文件（PDF、DOCX、图片等）；
将文件转换为一系列图片；
将每张图片交给视觉模型，请求其输出 Markdown；
聚合所有页面的响应，返回最终 Markdown。

对金融报告这类"视觉信息密度极高"的文档（表格、饼图、嵌套列表、页脚），视觉模型天然比传统 OCR 更适合，因为版面本身承载了大量语义。

2.2 源码级调用链（Node 实现）

在 node-zerox/src/index.ts 中，zerox()的完整执行流程（node-zerox/src/index.ts）为：

下载/定位源文件：downloadFile将本地路径或远程 URL 统一落地到临时目录（node-zerox/src/index.ts）；
分页选择：pagesToConvertAsImages支持-1（全部）或页码数组，越界页码会被过滤（node-zerox/src/index.ts）；
PDF → 图片：convertPdfToImages依据imageDensity（默认 300 DPI）、imageHeight等参数完成转换；
图片压缩：compressImage将超过maxImageSize（默认 15MB）的图片用 sharp 以递减质量（90 起步、步长 10、下限 20）转 JPEG 压缩（node-zerox/src/utils/image.ts）；
图片预处理：cleanupImage依次执行trimEdges（按左上角背景色裁剪边缘）、correctOrientation（用 Tesseract 对 4 个方向做 OCR 置信度比较并自动旋转，node-zerox/src/utils/image.ts），以及splitTallImage（对超高长图按空白行切分，避免超宽超高图超出模型输入限制，node-zerox/src/utils/image.ts）；
调用视觉模型：createModel依据modelProvider（OPENAI / AZURE / BEDROCK / GOOGLE）与model构建设备适配器，逐页调用getCompletion(OperationMode.OCR, ...)（node-zerox/src/index.ts）；
并发与串行：默认用pLimit(concurrency)并行处理各页；开启maintainFormat后改为串行，将上一页 Markdown 作为下一页的上下文（node-zerox/src/index.ts）；
聚合输出：按页序拼接 content，若指定outputDir则写入<fileName>.md，并返回ZeroxOutput（含completionTime、inputTokens、outputTokens、pages、summary）。

从 shared/outputs/0013.md 可以看出，流水线的预处理对金融 PDF 尤其关键：报告页通常包含页脚（"Page 3"）、免责声明行，而系统提示词（shared/systemPrompt.txt）明确要求 "You must include all information on the page. Do not exclude headers, footers, or subtext"，因此输出中页脚与免责声明都得到了保留。

2.3 源码级调用链（Python 实现）

Python 版的核心在 py_zerox/pyzerox/core/zerox.py：

使用pdf2image的convert_from_path完成 PDF → 图片（py_zerox/pyzerox/processor/pdf.py），默认参数来自 py_zerox/pyzerox/constants/conversion.py：DPI 300、格式 PNG、尺寸(None, 1056)、线程数 4、启用 pdftocairo；
select_pages支持单页或页码列表，先排序再通过create_selected_pages_pdf生成子集 PDF（py_zerox/pyzerox/core/zerox.py）；
并发控制通过asyncio.Semaphore(concurrency)实现，逐页调用 LiteLLM 封装的视觉模型（py_zerox/pyzerox/processor/pdf.py）；
custom_system_prompt可覆盖默认系统提示词（py_zerox/pyzerox/core/zerox.py），默认提示词定义在 py_zerox/pyzerox/constants/prompts.py，其中要求表格优先用 HTML/表格表达、Logo 与页码包裹在尖括号标签内、复选框用 ☐/☑。

2.4 系统提示词：决定输出结构的"隐形规则"

shared/systemPrompt.txt 与 py_zerox/pyzerox/constants/prompts.py 中 DEFAULT_SYSTEM_PROMPT 共同定义了逐页转换规则，其中与 0013.md 直接相关的有：

"Charts & infographics must be interpreted to a markdown format. Prefer table format when applicable."——这解释了资产配置饼图为何被转写为百分比列表、风格箱线图为何被转写为 3×3 表格；
"For tables with double headers, prefer adding a new column."——税务过渡表中"2024/2025/2026"三个年份列与主表头并存，正是这一规则的体现；
页面页脚与免责声明被完整保留，符合"不排除页眉页脚子文本"的要求。

三、0013.md 内容拆解：三层信息骨架

这份 3 页报告在 Zerox 输出中呈现为三个连续的 Markdown 段落，下面按页还原并解读其结构价值。

3.1 第 1 页：Executive Summary（执行摘要）

输出以## Executive Summary开头，先给 6 条"关键观察"（Key Observations），再给出资产配置与组合构建数据：

集中度风险：Microsoft (MSFT) 与 Apple (AAPL) 合计占权益配置 10.6%；
国际化不足：国际权益配置低于 Clark Capital 目标区间（第 2 页进一步给出目标区间为 25%–35%）；
市值偏向：中盘超配、小盘低配；
行业偏离：医疗健康超配、非必需消费相对基准低配；
固收久期：比 Clark Capital 当前定位更短，限制收益生成潜力；且到期结构集中于 0–3 年。

随后是数值快照：

项目	数值
组合价值	$545k
配置比例	82%/18% 股票/债券
投资风格	Growth

资产配置明细：现金 5.75%、美股 78.65%、非美股 3.45%、债券 12.12%、其他/未分类 0.03%。

组合构建方式：现金、ETF、共同基金、个股；股票总持仓 634 只，债券总持仓 9,748 只。页末保留了 "Page 3" 的页脚与 "For one-on-one use with a client's financial advisor only. Please see end disclosures for important information." 的免责声明——注意输出把本页标记为 "Page 3"，这正是 Zerox"逐页完整保留页眉页脚"规则的直接证据。

3.2 第 2 页：Your Equity Allocation – 82%

该页聚焦权益部分的关键观察：

个股 96%、ETF 4%；
规模：中盘超配、小盘低配；
行业：医疗健康超配、非必需消费相对基准低配；
国际化：权益中仅 4% 为国际资产，低于 Clark Capital 目标区间 25%–35%；
直接与间接股票持仓合计超过 600 只。

分散化分析部分指出：持有多个基金并不总能带来预期的分散收益，Microsoft、Apple、Meta Platforms 等证券被直接持有且又被某个基金重复持有；基金重叠加剧了组合集中度，MSFT 与 AAPL 合计占权益配置 10.6%，形成对单一个股波动的过度暴露。

风格矩阵（Equity Style）被转写为标准 Markdown 表格：

Value	Blend	Growth
Large	20	13	32
Mid	15	15	2
Small	2	1	0

行业分布（Sectors）按 Cyclical / Sensitive / Defensive 三大类组织，每行同时给出组合占比与基准（Bmark）占比：

分类	行业	组合	基准
Cyclical	Basic Matls	3.00%	2.43%
Cyclical	Consumer Cycl	5.10%	11.01%
Cyclical	Financial Svs	10.90%	12.77%
Cyclical	Real Estate	1.62%	2.52%
Sensitive	Commun Svs	11.36%	8.39%
Sensitive	Energy	3.37%	3.91%
Sensitive	Industrials	9.95%	8.72%
Sensitive	Technology	27.90%	28.95%
Defensive	Consumer Def	6.75%	6.24%
Defensive	Healthcare	16.56%	12.68%
Defensive	Utilities	3.49%	2.38%
—	Not Classified	0.00%	0.00%

地域分布（Geographic）同样与基准并列呈现：

区域	细项	组合	基准
Americas	整体	96.86%	95.30%
Americas	North America	96.55%	95.31%
Americas	Latin America	0.31%	0.00%
Greater Europe	整体	2.25%	3.24%
Greater Europe	United Kingdom	0.15%	0.65%
Greater Europe	Europe-Developed	1.96%	2.56%
Greater Europe	Europe-Emerging	0.00%	0.00%
Greater Europe	Africa/Middle East	0.14%	0.03%
Greater Asia	整体	0.89%	1.45%
Greater Asia	Japan	0.23%	0.94%
Greater Asia	Australasia	0.00%	0.32%
Greater Asia	Asia-Developed	0.51%	0.19%
Greater Asia	Asia-Emerging	0.15%	0.00%
—	Not Classified	0.00%	0.00%

页脚同时保留了 Morningstar 自动定制基准的说明文字，再次印证"不遗漏页脚子文本"的系统提示词规则。

3.3 第 3 页：Tax Transition/Overlap Analysis（税务过渡/重叠分析）

这一页是全文档信息密度最高、最能检验视觉模型表格还原能力的部分。目标（Objective）为"将已实现收益分摊到多个日历年度"，快照数据为：市场价值 $138,494、未实现收益 $19,943。32 行持仓明细表被完整还原：

Security Name	Ticker	Units	Cost	Value	Gain/Loss	2024
PFIZER INC	PFE	23.00	$1,114.91	$662	($453)	($453)
VERIZON COMMUNICATIONS INC	VZ	24.00	$1,371.14	$905	($466)	($466)
YUM CHINA HOLDINGS INC	YUMC	16.00	$956.83	$679	($278)	($278)
FOX CORP CL A	FOXA	28.00	$1,132.52	$830	($302)	($302)
ROBERT HALF INC	RHI	9.00	$654.92	$391	($264)	($264)
BIO RAD LABS INC CL A	BIO	2.00	$819.31	$645	($174)	($174)
MEDTRONIC PLC	MDT	16.00	$1,560.10	$1,238	($323)	($323)
MODERNA INC	MRNA	13.00	$1,570.51	$1,293	($278)	($278)
HF SINCLAIR CORP	DINO	14.00	$908.61	$778	($131)	($131)
RIO TINTO PLC SPONSORED ADR	RIO	9.00	$770.59	$670	($100)	($100)
ARCHER DANIELS MIDLAND COMPANY	ADM	16.00	$1,303.25	$1,156	($146)	($146)
ISHARES 5-10 YEAR IG CORP BOND ETF	IGIB	118.00	$6,905.54	$6,136	($770)	($770)
ISHARES 3-7YR TREASURY BOND ETF	IEI	79.00	$8,181.57	$7,953	($228)	($228)
NEXSTAR MEDIA GROUP INC	NXST	7.00	$1,198.95	$1,097	($102)	($102)
AFFILIATED MANAGERS GROUP INC	AMG	4.00	$843.50	$805	($38)	($38)
COGNIZANT TECHNOLOGY SOLUTIONS CORP CL A	CTSH	17.00	$1,341.30	$1,284	($57)	($57)
LABORATORY CORP OF AMER HOLDINGS NEW	LH	6.00	$1,415.64	$1,364	($52)	($52)
UNUM GROUP	UNM	32.00	$1,456.47	$1,209	($247)	($209)
PIMCO MORTGAGE OPPTY'S & BOND INSTL CL	PMZIX	311.55	$2,930.57	$2,957	$26	$26
NVIDIA CORP	NVDA	5.00	$2,477.52	$2,576	$98	$98
PIMCO ENHANCED SHORT MATURITY ACTIVE ETF	MINT	117.00	$11,631.26	$11,674	$44	$44
ARCH CAPITAL GROUP LTD	ACGL	7.00	$393.87	$418	$24	$24
CONSOLIDATED EDISON INC	ED	17.00	$52.45	$76	$24	$24
KINGSWAY FINL SUPERMATION HOLDINGS INC	KNDX	1.00	$92.15	$100	$8	$8
TAIWAN SEMICON MFG CO LTD SPON ADR	TSM	20.00	$2,213.93	$2,287	$74	$74
CISCO SYSTEMS INC	CSCO	38.00	$1,381.08	$1,970	$589	$589
ELECTRONIC ARTS INC	EA	7.00	$912.42	$945	$33	$33
DEVON ENERGY CORP NEW	DVN	14.00	$803.98	$835	$31	$31
MANULIFE FINANCIAL CORP	MFC	81.00	$1,561.98	$1,592	$30	$30
PROCTER & GAMBLE CO	PG	9.00	$1,284.62	$1,484	$200	$200
TEXAS INSTRUMENTS INC	TXN	22.00	$3,540.00	$3,840	$300	$300
GILEAD SCIENCES INC	GILD	36.00	$2,633.50	$2,916	$283	$283

紧随其后的Tax Transition段落解释了策略细节：首年可针对特定 ticker、未实现收益百分比或美元金额进行处置，后续年度默认沿用已识别的 ticker；持仓由 Clark Capital 与理财顾问持续共同监控，提前清算需客户指示；损益估计基于客户提供的成本基础数据，实际清算时的损益会存在差异，最终方案将以到账后更新的过渡计划为准（"The final plan will likely vary from the illustration shown here."）。页末保留了 "As of 1/31/2023" 与免责声明。

这一页最能说明视觉模型方案的价值：宽表（8 列 × 32 行）、多级表头（年度列）、括号负数格式、货币与千分位符号全部被结构化还原，直接可作为下游财务分析的输入。

四、测试框架如何校验这份输出

4.1 关键词比对机制

node-zerox/tests/index.ts 是仓库自带的回归测试入口：它读取 shared/test.json，遍历每份输入文件，以zerox()执行 OCR，然后用compareKeywords（node-zerox/tests/utils.ts）逐页将输出的小写化内容与预期关键词做包含比对，统计keywordsFound/keywordsMissing，最终输出每份文件的命中率与总体准确率。

对于0013.pdf，第 3 页的预期关键词覆盖了表格中的代表性实体（PFIZER INC、RIO TINTO PLC SPONSORED ADR、ISHARES 5-10 YEAR IG CORP BOND ETF、PROCTER & GAMBLE CO、PG）与关键数值（$138,494、$19,943、($453)、$283），这为"宽表内容被完整转写"提供了可量化的验收标准。

4.2 可重复性设计

测试脚本支持通过FILE_CONCURRENCY（默认 10）控制文件级并发，输出目录按时间戳隔离（test-run-${Date.now()}），并把tempDir指向结果目录下的temp文件夹以保留中间产物（node-zerox/tests/index.ts）。运行方式为在 node-zerox 目录下执行测试入口（仓库同时提供 jest.config.js 与 package.json 中的脚本配置），需要设置OPENAI_API_KEY环境变量（node-zerox/tests/index.ts）。

五、实战复现：用 Zerox 处理金融报告类 PDF

5.1 Node 方式

安装 zerox 与 PDF → 图片转换依赖（Linux 需 graphicsmagick）：

npm install zerox sudo apt-get update sudo apt-get install -y graphicsmagick

处理 shared/inputs/0013.pdf：

import { zerox } from "zerox"; import path from "path"; const result = await zerox({ filePath: path.resolve(__dirname, "shared/inputs/0013.pdf"), credentials: { apiKey: process.env.OPENAI_API_KEY, }, outputDir: path.resolve(__dirname, "shared/outputs"), concurrency: 10, });

关键可选参数（来源：README.md 参数清单与 node-zerox/src/types.ts）：

参数	默认值	说明
`cleanup`	`true`	运行后是否清理临时图片
`concurrency`	`10`	并发处理的页数
`correctOrientation`	`true`	用 Tesseract 自动识别并纠正页面方向
`errorMode`	`IGNORE`	`THROW`或`IGNORE`，控制失败页行为
`maintainFormat`	`false`	串行处理，把上一页 Markdown 作为下一页上下文，利于跨页表格
`maxRetries`	`1`	单页失败重试次数
`model`	`gpt-4o`	视觉模型，支持 OPENAI/AZURE/BEDROCK/GOOGLE 各系列
`pagesToConvertAsImages`	`-1`	页码数组或单个数字，`-1`表示全部
`tempDir`	系统临时目录	中间文件目录
`trimEdges`	`true`	按背景色裁剪边缘像素
`maxImageSize`	`15`	图片压缩上限（MB）
`outputDir`	无	聚合结果写入`<fileName>.md`的目录

值得强调的是maintainFormat：对 0013.pdf 这类"表格可能跨页"的文档，串行模式（Request #1 → page_1_image；Request #2 → page_1_markdown + page_2_image；以此类推）能显著改善跨页表格的一致性，代价是请求从并行退化为串行（README.md）。

5.2 Python 方式

先安装 poppler（保证pdftocairo在 PATH 中，py_zerox 的 PDF 转换默认启用use_pdftocairo，见 py_zerox/pyzerox/constants/conversion.py），再安装 SDK：

pip install py-zerox

import asyncio, os from pyzerox import zerox os.environ["OPENAI_API_KEY"] = "your-api-key" async def main(): result = await zerox( file_path="shared/inputs/0013.pdf", model="gpt-4o-mini", output_dir="shared/outputs", select_pages=None, # None 处理全部，或传 int / 页码列表 concurrency=10, maintain_format=False, # 跨页表格可开启 ) return result result = asyncio.run(main()) print(result)

Python 端参数（签名见 py_zerox/pyzerox/core/zerox.py）还包括image_density（默认 300）、image_height（默认(None, 1056)）、temp_dir、custom_system_prompt（覆盖默认提示词）、cleanup等；kwargs会透传给 LiteLLM 的completion方法。

5.3 面向金融文档的推荐组合

从 0013.pdf 的输出特征看，处理金融报告类文档时建议：

开启correctOrientation（默认开启），应对扫描版季度报告的方向混乱；
保留trimEdges，去除页眉页脚边缘噪声，避免误导表格识别；
若表格跨页（如长持仓明细），开启maintainFormat/maintain_format；
对超大报告先按页码抽样（pagesToConvertAsImages/select_pages），验证模型输出质量后再全量处理；
借助outputDir把聚合 Markdown 直接落盘，便于审计与归档。

六、适用前提与限制

本文数据均来自仓库中 shared/outputs/0013.md 的 OCR 产物；该产物是对 shared/inputs/0013.pdf 的视觉模型转写，原文中收益/损失数值与注释（如成本基础由客户提供、最终方案会变化）表明其属于演示性报告，不应视为真实投资建议。
视觉模型的转写质量依赖模型能力与系统提示词（shared/systemPrompt.txt）；数值、表格与图形的还原度以 shared/test.json 定义的关键词为验收基准，仓库并未对外宣称任何精确度指标。
Node 与 Python 两个实现的功能边界存在差异（例如结构化抽取schema、extractPerPage仅 Node 支持；custom_system_prompt仅 Python 支持），选型时可参考 README.md 的特性对照表。
运行示例需要有效的视觉模型凭证（如OPENAI_API_KEY）与 PDF 转换依赖（graphicsmagick / poppler），否则对应步骤会失败。

通过 shared/outputs/0013.md 这一实例，可以完整看到 Zerox 从"金融报告 PDF"到"结构化 Markdown"的价值：复杂宽表、风格矩阵、行业与地域分布、页脚免责声明都被忠实还原，且与测试基准、源码流水线一一对应。这份输出既是演示，也是可直接复用的验收样例。