用 Docling 将 SEC XBRL 财报转换为生成式 AI 就绪文档以一份 10-Q 的处理全解析【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/doclingDocling 通过专用的 XBRL 后端把以 XBRL 格式发布的企业财务报告如美国 SEC EDGAR 的 10-Q/10-K解析为结构化的 DoclingDocument为生成式 AI 应用提供可直接检索的文本、表格与键值数据。本文以仓库中真实的测试样本Groove Botanicals, Inc. 2025-12-31 财报为主线从后端实现、配置项、源码调用链到最终 Markdown 输出形态完整还原 Docling 处理 XBRL 实例文档的原理读者读完后可以复现同样的转换流程并理解叙事文本块、数值事实键值图与分类体系层级是如何被一步步搬进标准文档模型的。XBRL 处理在 Docling 中的定位XBRLeXtensible 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标志决定是否可用。如果未安装构造后端时会直接抛出带安装提示的ImportErrorpip 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配置字段默认值说明taxonomyNonetaxonomy 目录路径需按实例文件引用保持相对位置放置.xsdSchema 与.xmlLinkbase可选包含被实例文件以绝对 URL 引用、并通过 catalog 映射到本地的 taxonomy package.zipenable_local_fetchFalse是否允许从本地解析外部引用资源来自基类 BaseBackendOptionsenable_remote_fetchFalse是否允许联网下载外部 taxonomy 文件来自同一基类默认关闭以保障安全后端构造时会校验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_fetchTrue, # 允许解析本地 taxonomy必开其一 # enable_remote_fetchTrue, # 若 taxonomy 中的引用需联网补齐则再加这一项 taxonomygrve-taxonomy, # 指向包含 .xsd/.xml 与可选 .zip 的目录 ) converter DocumentConverter( allowed_formats[InputFormat.XML_XBRL], format_options{ InputFormat.XML_XBRL: XBRLFormatOption(backend_optionsbackend_options), }, ) result converter.convert(grve_10q_htm.xml) # 或传入 DocumentStream doc result.document print(doc.export_to_markdown(compact_tablesTrue))转换流程后端把一份 XBRL 实例拆成了哪几类内容进入 XBRLDocumentBackend.convert() 后实例文档的内容被分门别类处理这在仓库样本 grve_10q_htm.xml一份 2671 行的 SEC 10-Q 实例上可以得到完整印证1. 元数据标题来自 dei 概念后端遍历所有事实fact从dei命名空间读取三个关键值拼出文档标题DocumentType本样本为10-Q、EntityRegistrantNameGROOVE BOTANICALS, INC.、DocumentPeriodEndDate2025-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_titleFalse说明这一层只关心文本结构不触碰外部资源。这解释了为什么 Markdown 输出里能够看到层级化段落、加粗的 NOTE 标题**NOTE 1 - ORGANIZATION AND OPERATIONS**以及内嵌表格——它们都是从 HTML 富文本中还原出来的。值得注意的一个导出细节是docling 的 Markdown 导出会把文本中的安全转义为amp;所以正文里“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.xml10-Q与mlac-20251231.xml另一家公司的年报式实例XML 中可见大量context时间段/瞬时点、xbrldi:explicitMember维度以及dei:DocumentType等事实定义。配套 taxonomygrve-taxonomy/内含grve-20251231.xsd、_cal.xml、_def.xml、_lab.xml、_pre.xml等 Linkbase外加可直接作为 Arelle taxonomy package 加载的taxonomy_package.zipmlac-taxonomy/结构一致。两者与各自实例一一对应。三种 groundtruth每个实例导出为.mdMarkdown、.itxt缩进文本测试中max_text_len70, explicit_tablesFalse、.json完整 DoclingDocument 序列化schema_name: DoclingDocument供回归比对。端到端测试 test_backend_xbrl.py 会遍历全部 (实例, taxonomy) 对分别以文件路径与DocumentStream两种方式转换并用doc.export_to_markdown(compact_tablesTrue)、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,4202025-12-31 止对比 $99,4042024 年同期累计亏损 $35,464,8542025-12-31与 $35,196,5812025-03-31审计师对此表达重大疑虑公司计划转向新业务模式并寻求股权/债务融资。NOTE 4 – CASH现金界定为原始到期日三个月内的高流动性投资截至 2025-12-31 现金均为非受限现金。NOTE 5 – RELATED PARTY TRANSACTIONS关联方应付款 2025-12-31 为 $719,9612025-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,0002023-04-01 起恢复计息。B 系列股息率 9%位列 A 系列之后两周年内赎回价为 Stated Value 的 105%之后为 100%。2025-12-31 未付股息A 系列 $110,000、B 系列 $490,792含 Rodriguez 名下部分。该 NOTE 内的应付股息汇总表是文本块内嵌 HTMLtable的典型样本地面真相 Markdown 中它以紧凑表格出现。原表为双期并列布局清理后信息如下项目2025-12-31$2025-03-31$应付股息399,506290,550应付股息关联方201,286146,390而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.0012025-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_tablesTrue代价是键值图数据不可见仅以 HTML 注释!-- missing-key-value-item --占位。缩进文本.itxt带层级缩进的调试视图能看到 title/text/table/key_value_region 的嵌套顺序与每个 item 的级别适合理解文档树结构与定位解析边界如item-72 at level 1: key_value_region: ignored。JSON.jsonDoclingDocument 的完整序列化保留 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_fetchTrue联网补齐或通过 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考