用 Docling 将 SEC XBRL 财报转换为生成式 AI 就绪文档：以一份 10-Q 的处理全解析

用 Docling 将 SEC XBRL 财报转换为生成式 AI 就绪文档：以一份 10-Q 的处理全解析

【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling

Docling 通过专用的 XBRL 后端把以 XBRL 格式发布的企业财务报告（如美国 SEC EDGAR 的 10-Q/10-K）解析为结构化的 DoclingDocument，为生成式 AI 应用提供可直接检索的文本、表格与键值数据。本文以仓库中真实的测试样本（Groove Botanicals, Inc. 2025-12-31 财报）为主线，从后端实现、配置项、源码调用链到最终 Markdown 输出形态，完整还原 Docling 处理 XBRL 实例文档的原理，读者读完后可以复现同样的转换流程，并理解叙事文本块、数值事实键值图与分类体系层级是如何被一步步搬进标准文档模型的。

XBRL 处理在 Docling 中的定位

XBRL（eXtensible Business Reporting Language）是基于 XML 的财务报告交换标准，被上市公司与监管机构广泛用于发布结构化财务信息。Docling 将 XBRL 视为一种声明式（declarative）输入格式，由 XBRLDocumentBackend 负责解析，其支持的输入格式被声明为InputFormat.XML_XBRL（见 xbrl_backend.py）。由于 XBRL 本质上是带标签的 XML，该后端并不走版面分析/OCR 管线，而是在解析后把结果拼装进标准的 DoclingDocument 对象。

后端实现上有几个值得注意的技术选择：

• 依赖 Arelle 解析 XBRL：模块顶部通过try/except惰性导入arelle.Cntlr、ModelXbrl、ModelConcept、ModelDtsObject等符号，_XBRL_AVAILABLE标志决定是否可用。如果未安装，构造后端时会直接抛出带安装提示的ImportError：pip install 'docling-slim[format-xml-xbrl]'。
• 必须提供 taxonomy（分类体系）：XBRL 的标签语义依赖与实例文件配套的 Schema 与 Linkbase。后端把用户传入的 taxonomy 目录整体拷贝到临时目录，扫描其中的.ziptaxonomy package 交给 Arelle 加载。
• 默认完全离线：除非显式打开enable_remote_fetch，否则会设置cntlr.webCache.workOffline = True并关闭披露体系校验，防止加载不可信 XBRL 时意外访问外网。
• 图数据结构仍在演进：文件头 docstring 明确提示，键值对目前使用 docling-core 的GraphData/GraphCell/GraphLink表示，该设计可能随 docling-core 新版本而变化。

配置项与代码级调用链

XBRL 特有配置集中在 XBRLBackendOptions：

后端构造时会校验enable_local_fetch与enable_remote_fetch至少开启一个，否则抛OperationNotAllowed——这是加载 taxonomy 的硬性前提。

完整的调用链可以从端到端测试 test_backend_xbrl.py 复现：DocumentConverter限定allowed_formats=[InputFormat.XML_XBRL]，通过format_options里的 XBRLFormatOption 传入backend_options。无论是本地文件路径还是BytesIO流（DocumentStream），最终都会走DocumentConverter.convert()→XBRLDocumentBackend.convert()。

一个最小可运行示例（与测试同构）：

from docling.document_converter import DocumentConverter, XBRLFormatOption from docling.datamodel.backend_options import XBRLBackendOptions from docling.datamodel.base_models import InputFormat backend_options = XBRLBackendOptions( enable_local_fetch=True, # 允许解析本地 taxonomy（必开其一） # enable_remote_fetch=True, # 若 taxonomy 中的引用需联网补齐，则再加这一项 taxonomy="grve-taxonomy", # 指向包含 .xsd/.xml 与可选 .zip 的目录 ) converter = DocumentConverter( allowed_formats=[InputFormat.XML_XBRL], format_options={ InputFormat.XML_XBRL: XBRLFormatOption(backend_options=backend_options), }, ) result = converter.convert("grve_10q_htm.xml") # 或传入 DocumentStream doc = result.document print(doc.export_to_markdown(compact_tables=True))

转换流程：后端把一份 XBRL 实例拆成了哪几类内容

进入 XBRLDocumentBackend.convert() 后，实例文档的内容被分门别类处理，这在仓库样本 grve_10q_htm.xml（一份 2671 行的 SEC 10-Q 实例）上可以得到完整印证：

1. 元数据标题来自 dei 概念

后端遍历所有事实（fact），从dei命名空间读取三个关键值拼出文档标题：DocumentType（本样本为10-Q）、EntityRegistrantName（GROOVE BOTANICALS, INC.）、DocumentPeriodEndDate（2025-12-31），对应源码中 xbrl_backend.py 的元数据提取，并调用doc.add_title()。因此 groundtruth Markdown 的第一行就是# 10-Q GROOVE BOTANICALS, INC. 2025-12-31，这正是生成式 AI 检索时最需要的“这是什么文件”的锚点。

2. 叙事型披露走 textBlockItemType → HTML 二次解析

SEC 报告的正文（管理层讨论、脚注、会计政策等）以超长 HTML 字符串存放在textBlockItemType类型的事实里。后端识别该类概念后，先把值中的空白折叠（re.sub(r"\s+", " ", ...)），再交给HTMLDocumentBackend做一次真正的 HTML 解析，最后用DoclingDocument.concatenate并入主文档。嵌套用到的 HTMLBackendOptions 刻意关闭了本地/远程抓取、图片下载与版面推断（add_title=False），说明这一层只关心文本结构，不触碰外部资源。

这解释了为什么 Markdown 输出里能够看到层级化段落、加粗的 NOTE 标题（**NOTE 1 - ORGANIZATION AND OPERATIONS**）以及内嵌表格——它们都是从 HTML 富文本中还原出来的。值得注意的一个导出细节是：docling 的 Markdown 导出会把文本中的&安全转义为&，所以正文里“formerly known as Avalon Oil & Gas, Inc.”展示的是 HTML 安全的转义形式。

3. 数值事实进键值图，不渲染进 Markdown

对于带isNumeric的数值型事实，后端逐个生成GraphCell，围绕事实名挂接五类子单元：value、period（瞬时点或起止区间）、currency（单位命名空间的本地名）、decimals以及dimension（如RelatedPartyTransactionsByRelatedPartyAxis: KentRodriguezMember），并通过GraphLinkLabel.TO_VALUE建立主键到取值的关系。事实名以orig保存完整 QName。打开 groundtruth JSON 能看到真实的key_value_items，例如"text": "value: 10"、"text": "period: 2025-04-01"这样的单元。

关键事实：键值图在 Markdown 中没有渲染形式。因此 groundtruth 的.md文件末尾出现了<!-- missing-key-value-item -->注释占位，而.itxt中对应条目则是item-72 at level 1: key_value_region: ignored——这是导出去重后对无法表达内容的位置标记，属于预期行为。要拿到完整的数值事实，应以 JSON 输出（或编程访问doc.key_value_items）为准。

4. 分类体系层级用 Linkbase 关系重建

后端进一步读取presentation linkbase的 parent-child 弧与calculation linkbase的 summation-item 弧，把数值事实挂回概念层级树，并为每个求和关系生成weight单元。见 xbrl_backend.py。这意味着 DoclingDocument 里的键值图不仅存储“报表值”，还保留了概念之间的父子与计算结构，可供需要理解科目勾稽关系的上层应用使用。

仓库样本与其三重 groundtruth

本仓库 tests/data/xbrl 目录下配有完整测试素材：

• 实例文件：grve_10q_htm.xml（10-Q）与mlac-20251231.xml（另一家公司的年报式实例），XML 中可见大量context（时间段/瞬时点）、xbrldi:explicitMember维度以及dei:DocumentType等事实定义。
• 配套 taxonomy：grve-taxonomy/内含grve-20251231.xsd、_cal.xml、_def.xml、_lab.xml、_pre.xml等 Linkbase，外加可直接作为 Arelle taxonomy package 加载的taxonomy_package.zip；mlac-taxonomy/结构一致。两者与各自实例一一对应。
• 三种 groundtruth：每个实例导出为.md（Markdown）、.itxt（缩进文本，测试中max_text_len=70, explicit_tables=False）、.json（完整 DoclingDocument 序列化，schema_name: DoclingDocument），供回归比对。

端到端测试 test_backend_xbrl.py 会遍历全部 (实例, taxonomy) 对，分别以文件路径与DocumentStream两种方式转换，并用doc.export_to_markdown(compact_tables=True)、doc._export_to_indented_text(...)与verify_document对照三份 groundtruth，确保新代码不会破坏既有输出。

逐节读懂转换产物：10-Q 里的九段脚注

以 grve_10q_htm.xml.md 为索引，可以完整对照 Docling 还原出的财务内容。每个 NOTE 来自文本块事实，其正文说明了 Docling 对段落、强调、表格的保真能力：

NOTE 1 – ORGANIZATION AND OPERATIONS

公司沿革与现状：Groove Botanicals, Inc.（原名 Avalon Oil & Gas, Inc.）1991 年在科罗拉多注册为 Snow Runner (USA), Inc.，历经多次更名与迁册（1993 年迁往明尼苏达、1999 年并入 Xdogs.com Inc. 改籍内华达、2005 年更名 Avalon Oil and Gas、2018 年更名 Groove Botanicals）。2021 年 8 月提交 15-12B 暂停报告义务，2023 年 9 月 14 日提交 Form 10 并于 60 天后生效。管理层计划组建挪威/瑞典/芬兰高校早期 EV 电池技术组合并申请明尼苏达州资助，但公司目前不持有相关专利，无法保证收购成功。

NOTE 2 – SUMMARY OF SIGNIFICANT ACCOUNTING POLICIES

会计政策摘要，涵盖列报基础（遵循 SEC 10-Q 与 Reg S-X 指引，与 2025-03-31 年报合并口径）、合并范围（合并两家 100% 控股的怀俄明州非经营子公司 Biotrex, Inc. 与 Maxidyne, Inc.）、估计的使用、金融工具与公允价值层级（ASC 820 的 Level 1/2/3）、每股亏损计算（ASC 260 的基本与稀释 EPS）、所得税（C 公司负债法、递延税估值备抵、不确定税务头寸）。政策后还罗列了已采用的 ASU 2023-07（分部披露）与 ASU 2023-09（所得税披露），以及尚未采用的 ASU 2024-03（费用分解披露）。文件中也出现同一批政策文案被两个文本块事实重复包含的情况——在后端对每个事实分别解析的设计下，输出自然随之重复，这并非解析错误，而是源实例本身的特性。

NOTE 3 – GOING CONCERN

持续经营重大疑虑：九个月净亏损 $104,420（2025-12-31 止）对比 $99,404（2024 年同期），累计亏损 $35,464,854（2025-12-31）与 $35,196,581（2025-03-31），审计师对此表达重大疑虑；公司计划转向新业务模式并寻求股权/债务融资。

NOTE 4 – CASH

现金界定为原始到期日三个月内的高流动性投资；截至 2025-12-31 现金均为非受限现金。

NOTE 5 – RELATED PARTY TRANSACTIONS

关联方应付款 2025-12-31 为 $719,961（2025-03-31 为 $608,833），系管理层垫付运营资金与薪酬。CEO Kent Rodriguez 的四年期雇佣协议自 2020-04-01 起每年计提 $48,000（月付 $4,000），并于 2024-07-30 续期两年至 2026-03-31。报告期内为 A 系列优先股计提 $30,000 股息，为其控制的 18.6% B 系列优先股计提 $24,896 股息。

NOTE 6 – PREFERRED STOCK

优先股结构是键值数据最密集的一节：公司获准发行 1,000,000 股优先股，其中 A 系列 100 股、B 系列 2,000 股，面值均为 $0.10。A 系列按每股 8% 现金股息率累计，转换后对应当时全面稀释流通股的 51%（2018-01-12 修正，从 0.4% 上调至 0.51%），清算优先权总额 $500,000（即每股 $5,000）；2023-04-01 起恢复计息。B 系列股息率 9%，位列 A 系列之后，两周年内赎回价为 Stated Value 的 105%，之后为 100%。2025-12-31 未付股息：A 系列 $110,000、B 系列 $490,792（含 Rodriguez 名下部分）。

该 NOTE 内的应付股息汇总表是文本块内嵌 HTML<table>的典型样本，地面真相 Markdown 中它以紧凑表格出现。原表为双期并列布局，清理后信息如下：

而itxt中对应两处table with [4x9]，其富单元格组rich_cell_group_1_1_1/rich_cell_group_1_5_1分别承载“December 31, 2025”“March 31, 2025”等跨列内容，能直观看到表格在转换模型里的行列分配。

NOTE 7 – COMMON STOCK

普通股授权 200,000,000 股、面值 $0.001；2025-12-31 与 2025-03-31 均发行在外 59,643,062 股，期间无新股发行。

NOTE 8 – COMMITMENTS AND CONTINGENCIES

截至 2025-12-31 有一份按月口头租赁协议，月租 $1,200。

NOTE 9 – SUBSEQUENT EVENTS

管理层按 ASC 855 评估后认定，除文中列明事项外无重大期后事项。

三种输出形态如何配合使用

同一份转换结果在仓库里有三种导出格式，用途互补，测试代码也据此做三路校验：

• Markdown（.md）：适合直接喂给 LLM/RAG 做语义检索，正文叙事完整、表格紧凑（compact_tables=True）；代价是键值图数据不可见，仅以 HTML 注释<!-- missing-key-value-item -->占位。
• 缩进文本（.itxt）：带层级缩进的调试视图，能看到 title/text/table/key_value_region 的嵌套顺序与每个 item 的级别，适合理解文档树结构与定位解析边界（如item-72 at level 1: key_value_region: ignored）。
• JSON（.json）：DoclingDocument 的完整序列化，保留 body 元素、texts/tables/key_value_items等全部容器与单元、链接及标签，是做结构化下游处理（财务报表科目级抽取、口径比对）的首选出口。

对于财务场景，推荐组合策略：叙事部分用 Markdown，数值事实与概念层级用 JSON 的键值图。Docling 的这一设计把“给 AI 读的叙述”和“给程序算的科目”分离开，恰好匹配 SEC 报告既有人话又有数据的特点。

适用前提与限制

• XBRL 解析要求arelle-release运行时依赖，未安装时后端会拒绝启动并提示安装docling-slim[format-xml-xbrl]。
• taxonomy目录必须完整携带实例引用的 Schema/Linkbase，缺失时 Arelle 会报错；若引用指向绝对 URL，需要enable_remote_fetch=True联网补齐或通过 catalog 映射到本地 taxonomy package。
• enable_local_fetch/enable_remote_fetch默认双关，至少开启其一才能加载分类体系，这是出于安全考虑的显式设计。
• 键值图（GraphData）在 docling-core 中可能演进，后端实现也已声明将随新版本同步调整，升级依赖时需留意输出结构变化。
• 文本块内容经 HTML 后端二次解析，因此对 HTML 标签的处理规则（如标题层级推断、表格单元格合并）会影响最终 Markdown 版式；跨行空白会被折叠为单空格。实例源文件若自身重复包含同一披露（如 NOTE 2 的两处重复段落），输出会忠实呈现两次，属于源数据特性。

【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling