docling

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 21, 2026 License: MIT Imports: 57 Imported by: 0

README

docling — 纯 Go 文档解析,为 Gen-AI 而生

English | 简体中文

把任何文档喂给你的大模型 —— 纯 Go 单二进制,快 1~2 个数量级,复杂页可挂大模型增强。

docling 将 PDF、Word、PPT、Excel/CSV、HTML、Markdown、AsciiDoc、EML 邮件、图片与纯文本解析为统一的 DoclingDocument 结构化模型(对齐 Docling Core 1.10.0 官方协议),为 RAG 切片、向量化和 Agent 工具链提供开箱即用的文档摄入层。

命名说明:本仓库是 Docling 协议的纯 Go 实现,Go 包名为 docling,与 Python 官方实现共享同一文档模型。

为什么开发这个库

一句话:让任何文档都能被大模型可靠地读懂——不拖一台 Python 模型服务下水。

把文档喂给 LLM/RAG 前,先要回答四个问题:

痛点 docling(Go)的答案
文档格式异构:PDF、Office、网页、邮件、图片各有一套解析栈,拼起来维护成本极高 统一 DoclingDocument 模型:12 种格式一个入口、一套 API,输出对齐官方协议
现有高质方案(Python 模型管线)部署重:Python 服务 + 数 GB 布局/表格模型,批量入库、CI、边缘节点很难落地 纯 Go 单二进制,go get 即用,毫秒~秒级解析,零外部服务
全靠模型太贵太慢,全靠规则质量有上限 混合架构:规则引擎保底,扫描件/图片表格/公式密集页按质量信号自动路由给大模型——模型只用在刀刃上
模型转写会"幻觉"改数据,入库结果不可信 不伪造结果:图表数据从文档自带缓存精确还原,规则不确定的内容保留原始信号并明示,而非猜一个

若你的场景是"高保真审阅、扫描件密集",Python 官方 Docling 仍是首选,见下方差距说明。

为什么是 docling(Go)

现代文档解析的主流方案是 Python 模型管线(如 Docling):质量高,但需要 Python 服务、加载布局模型,转换一个文档动辄几十秒。docling(Go)给出另一种工程取舍:

  • ⚡ 快 1~2 个数量级:纯 Go 规则引擎处理文本型文档毫秒到秒级完成(实测见下),批量摄入十万级文档不再需要 GPU 集群
  • 📦 单二进制部署:纯 Go 实现,零 Python/零外部服务,go get 即用;CI、边缘节点、嵌入式场景同样可跑
  • 🧠 现代混合架构:规则引擎覆盖结构化内容,扫描件、图片表格、公式密集页自动按页路由给大模型(OCRHook/PDFVisualHook)——把模型用在刀刃上,而不是每个页面
  • 🔒 不伪造结果:解析器不确定的内容保留原始信号进入视觉回退,而不是猜一个结构
  • 🤝 生态兼容:输出与 Docling 官方协议完全对齐,已有的 Docling 下游工具链无缝衔接

架构创新:一个模型接口,替代五组件识别管线

传统文档解析管线的复杂度来自"专用组件堆叠"——识别、布局、表格、公式、阅读顺序各配一个专用模型/引擎:

能力 传统管线 docling(Go)
文字识别(OCR) tesseract 等 OCR 引擎 规则层:字体/CMap 恢复;识别类 → 大模型钩子
版面布局 布局模型(如 LayoutLMv3) 规则层:递归 XY-cut 多栏;歧义页 → 大模型钩子
表格结构 表格模型(如 TableFormer) 规则层:坐标网格恢复(含无边框/跨页);图片表格 → 大模型钩子
公式识别 公式模型 规则层:OMML→LaTeX;图片公式 → 大模型钩子
阅读顺序 顺序模型 规则层:栏切分 + 锚点排序

确定性结构交给规则引擎(不需要模型,精确且快),识别类任务全部收敛到一个多模态大模型接口(OCRHook/PDFVisualHook):依赖从"OCR 引擎 + 4 个模型文件"变成"0 个内置模型 + 1 个可选模型接口",部署与升级随之大幅简化——换更强的大模型,整条识别链路一起升级。

架构

docling 架构图

架构图右侧的大模型旁路,就是上表全部"识别类"能力的统一接入点。解析器对每页计算质量信号(乱码率、表格候选、公式密度、栏位歧义),只有命中的疑难页才路由给大模型;模型返回结果经强校验与规则文本几何去重合并,失败保留纯 Go 结果——模型只用在刀刃上,增强永远不破坏既有输出。

性能实测

同一台机器、同一批真实 PDF(Apache-2.0 测试样本),docling(Go,无模型)对 Docling 2.x(CPU 模型管线,同进程预热后计时):

文档 docling(Go) Python Docling(CPU) 加速比
学术论文(141 KB,10 页) 0.31s 10.5s 34×
技术书稿(1.2 MB,图文混排) 0.73s 111.7s 153× 
xychart-beta
    title "PDF 转换耗时(秒,越低越好)"
    x-axis ["论文 141KB", "书稿 1.2MB"]
    y-axis "耗时(秒)" 0 --> 120
    bar [10.5, 111.7]
    bar [0.31, 0.73]

柱状序列依次为 Python Docling(CPU 模型管线)与 docling(Go 纯规则)。Python 版耗时包含布局/表格模型推理;Go 版不加载任何模型。

质量取舍请诚实对待:Docling 的模型管线在复杂版面、图片理解上仍是上限;docling(Go)的策略是规则引擎保底 + 关键页大模型增强,两者互补而非互斥。

解析能力对比

能力 docling(纯 Go) Python Docling docling + 大模型钩子
文本型 PDF 文字与坐标 ✅ 纯 Go ✅ ✅
缺 ToUnicode 字体乱码恢复(CJK CMap/嵌入字体) ✅ 纯 Go ✅ ✅
表格还原(线框/稀疏无边框/跨页合并) ✅ 纯 Go ✅ 模型 ✅(复杂图片表格走视觉)
多栏阅读顺序(递归 XY-cut) ✅ 纯 Go ✅ 模型 ✅
扫描件 OCR ➖ 需配置 ✅ 内置 ✅ OCRHook 接任意模型
图片表格 / 公式密集 / 版面歧义页 ➖ 视觉回退 ✅ 模型 ✅ PDFVisualHook 按页增强
内嵌图片解码(含 JPEG2000/JBIG2/软蒙版) ✅ 纯 Go ✅ ✅
DOCX/PPTX/XLSX 批注·公式·修订·图表·SmartArt ✅ 纯 Go ⚠️ 部分 ✅
输出协议 ✅ Docling 1.10 官方 JSON ✅ 官方 ✅
部署形态 单二进制 Python 服务 + 模型文件 单二进制 + 模型 API

输入格式对比

输入格式 docling(Go) Python Docling
PDF ✅ ✅
Word (DOCX) ✅ ✅
PPT (PPTX) ✅ ✅
Excel (XLSX) / CSV ✅ ✅
HTML ✅ ✅
Markdown ✅ ✅
AsciiDoc ✅ ❌
EML 邮件 ✅ ✅(另支持 MSG)
图片 PNG/JPEG/BMP/WEBP ✅ ✅(另支持 TIFF)
纯文本 ✅ ✅
Docling JSON(回读) ✅ ✅
音频转写(WAV/MP3 ASR) ❌ 规划中 ✅
EPUB / Apple Pages ❌ 规划中 ✅
XML(XBRL/JATS/USPTO)/ usda ❌ 规划中 ✅
LaTeX ❌ 规划中 ✅
ZIP 压缩包 ❌ ✅

输出格式对比

输出格式 docling(Go) Python Docling
Markdown ✅ ✅
HTML ✅ ✅
DoclingDocument JSON(无损) ✅ ✅
content_list(检索扁平内容列表) ✅ ⚠️ 类似能力
层级分块(Hierarchical / Hybrid) ✅ ✅
知识库分块(长度/表格/多模态策略) ✅ ❌
DocTags ❌ 规划中 ✅
纯文本 ✅ ✅
WebVTT(音频字幕) ❌ ✅

支持的格式

格式 入口函数 说明
按扩展名自动分发 ParseByExt / ParseByExtWithOptions 不知道格式时的首选入口;自动补齐文档名、MIME、SHA-256 哈希与 origin
PDF ParsePDF / ParsePDFWithOptions 坐标归一化、词/行 bbox、字体恢复、内嵌位图、表格、跨页续表、递归 XY-cut;可选 Poppler、OCR 与视觉 Hook
Word ParseDocx Transitional/Strict OOXML、批注回复链、脚注/尾注、修订与域、OMML 公式、图表与 SmartArt/OLE
PPT ParsePPTX notes、批注回复链、母版回退、组合元素、图表与复杂 Office 对象
Excel / CSV ParseXLSX / ParseCSV 隐藏表、threaded comments、原始公式、透视表、图表工作表
HTML ParseHTML furniture、平铺标题、图片占位、富表格
Markdown ParseMarkdown 平铺标题、图片占位、GFM 表格
AsciiDoc ParseAsciiDoc 标题树、列表、字面/源码块
EML 邮件 ParseEML RFC 5322 头、正文择优、常见字符集、附件名称
图片 ParseImage PNG/JPEG/BMP/WEBP;配置 OCR 后追加识别结构
纯文本 ParseText BOM 与控制字符清理
Docling JSON ParseDoclingDocument 解析 Docling 服务输出的 JSON

快速上手

go get github.com/unitedrhino/docling

// 一行完成"解析 → Markdown"
md, err := docling.ParseByExtToMarkdown("报告.pdf", data)

// 或分步:拿到结构化模型再消费
doc, err := docling.ParseByExt("报告.docx", data)
items := docling.ToContentList(doc, docling.SourceGolight) // RAG 切片用扁平内容
chunks := docling.HierarchicalChunks(doc)                   // 官方语义层级分块
md := doc.ToMarkdown()
html := doc.ToHTML()
挂载大模型:现代混合解析
doc, err := docling.ParsePDFWithOptions(data, docling.PDFOptions{
    GarbageThreshold: 0.4, // 乱码率超过该值的页触发 OCR
    OCRHook: func(req docling.OCRRequest) (string, error) {
        return myLLMOCR(req) // 接任意 OCR / 多模态模型
    },
    VisualHook: func(req docling.PDFVisualRequest) (docling.PDFVisualResult, error) {
        // req.Prompt 是内置的严格 JSON 提示词;把多模态模型返回解码即可。
        return myStructuredVision(req)
    },
    MaxVisualPages: 20,
})

组件对钩子返回值做强校验(标签、置信度、bbox、表格拓扑、防拒答/防复读),无效结果自动重试一次;有效结果与规则文本按几何去重合并,失败则保留纯 Go 结果——模型增强永远不破坏既有输出。

PDF 安全边界

ParsePDF 和 ParseByExt 默认拒绝超过 50 MiB 或 2000 页的 PDF，并在文本解析前使用 pdfcpu 对对象、XRef、压缩流、图片和递归深度做有界校验。结构超限返回可通过 errors.Is(err, docling.ErrPDFResourceLimit) 判断的错误；单张损坏或超限图片只会被跳过，不影响正文。

doc, err := docling.ParsePDFWithOptions(data, docling.PDFOptions{
    Limits: docling.PDFLimits{MaxFileBytes: 100 << 20, MaxPages: 5000},
})

未设置或设置为非正值时使用 DefaultPDFLimits()，不会关闭限制。OCR 与视觉钩子可优先读取请求中的 PageData（安全抽取的单页 PDF），并保留 Data 作为原文件兼容字段。

命令行工具(CLI)

不想写代码?开箱即用的 docling 命令(同为纯 Go 单二进制):

go install github.com/unitedrhino/docling/cmd/docling@latest

# 渐进式:先看结构地图(章节树/表格/图片,几百字节)
docling parse report.pdf --format outline
# 通读全文,或按章节精取
docling parse report.pdf --format md
docling parse report.pdf --format md --section 第四章
# 无损 JSON 落盘,查询交给 jq
docling parse report.xlsx --format json --out doc.json
# excel 公式溯源:列出所有公式单元格(值,公式)
jq -r '.texts[] | select(.meta.docling__xlsx_formula) | [.text, .meta.docling__xlsx_formula] | @tsv' doc.json
# 反查哪个表格单元格引用了公式节点 #/texts/3
jq '.tables[].data.table_cells[] | select(.ref."$ref" == "#/texts/3")' doc.json
大模型 OCR(可选)
OPENAI_API_KEY=sk-xxx docling parse scan.pdf --format md --ocr
# 更多:OPENAI_BASE_URL(自定义网关)、DOCLING_OCR_MODEL(模型名,默认 gpt-4o)、--ocr-max-pages(页数预算)

--ocr 同时挂载逐字 OCR 与结构化视觉两个钩子:扫描页/乱码页/图片表格/公式密集页自动送模型,识别失败自动回退纯 Go 结果,页数预算防失控。任意 OpenAI 兼容多模态模型(vLLM、GLM、Qwen-VL 等)均可使用。

examples:成果示例(原文 ↔ 识别后的 Markdown)

examples/ 为每种受支持格式提供"样例源文件 ↔ Markdown 期望输出"的成对对照。以下全部展示真实世界文档的实际识别结果:

Word · 微软官方测试文档(6 个原生图表)

真实 Office 生成的多系列柱状图/折线图文档(微软 Open XML SDK 官方测试资产,MIT 授权):

Word 原生图表文档

识别后的 Markdown(节选):图表数据按系列精确还原为可检索表格,缺失单元格如实留空,并附 SVG 语义预览:

| 类别 | Series 1 | Series 2 | Series 3 |
| --- | --- | --- | --- |
| Category 1 | 4.3 | 2.4 | 2 |
| Category 2 | 2.5 | 4.4 |  |
| Category 3 | 3.5 | 1.8 | 3 |
| Category 4 | 4.5 | 2.8 | 5 |
PPT · 微软官方演示(3D 饼图)

PPT 3D 饼图

识别后的 Markdown(节选):3D 饼图的季度数据完整还原:

| 类别 | Sales |
| --- | --- |
| 1st Qtr | 8.2 |
| 2nd Qtr | 3.2 |
| 3rd Qtr | 1.4 |
| 4th Qtr | 1.2 |
Excel · 微软官方工作簿(OLE 嵌入对象)

Excel OLE 嵌入对象

工作簿中的 OLE 嵌入对象按语义分类记录(目标路径、程序标识入 meta,载荷不执行)。

PDF · 真实学术论文(196 页 + 双栏会议论文)

196 页硕士论文 10 页双栏会议论文

识别后的 Markdown(节选;两份论文 200+ 页纯 Go 解析约 30 秒):

## Evaluating the GO

## Programming Language with

## Design Patterns

by

### Frank Schmager

A thesis
submitted to the Victoria University of Wellington
in partial fulfilment of the requirements for the degree of
Master of Science in Computer Science.

### Abstract

GO is a new object-oriented programming language developed at Google
by Rob Pike, Ken Thompson, and others. ...

右侧的 10 页双栏会议论文(gohotdraw-paper.pdf)展示双栏阅读顺序还原。

TXT / CSV / EML · 真实文本类文档

《汤姆·索亚历险记》全书(380KB)、x86 指令集表(3700+ 行)、CPython 标准库的真实 MIME 退信邮件:

# Banned file: auto__mail.python.bat in mail from you

From: MAILER DAEMON <>

To: <webmaster@python.org>

Date: Fri, 26 Nov 2004 19:41:44 -0800 (PST)

BANNED FILENAME ALERT

Your message to: xxxxxxx@dot.ca.gov, ...
was blocked by our Spam Firewall. The email you sent with the following
subject has NOT BEEN DELIVERED:

邮件头、multipart 正文择优、收件人列表逐项还原;CSV 表与长文本按原样结构化。

构造样例(rich-*)

对 SmartArt、OMML 公式、艺术字、组合图等复杂对象提供确定性对照(代码构造、可再生产):公式转 LaTeX({E}^{2}=mc)、SmartArt 流程转语义 SVG 且节点文字进入可检索 caption、组合图按系列类型分列渲染——见 examples/ 与 examples/README.md。

各格式真实样例总览
格式 真实样本 来源
PDF 196 页硕士论文 + 10 页双栏会议论文 Victoria University of Wellington(公开论文)
Word 含 6 个原生图表的官方测试文档 微软 Open XML SDK 测试资产(MIT)
PPT 含 3D 饼图的官方测试演示 微软 Open XML SDK 测试资产(MIT)
Excel 含 OLE 嵌入对象的工作簿 微软 Open XML SDK 测试资产(MIT)
EML 真实 MIME 多段退信邮件 CPython 标准库测试数据(PSF 授权)
纯文本 《汤姆·索亚历险记》全书(380KB) 公版书(pdfcpu testdata)
CSV x86 指令集描述表(3700+ 行) golang.org/x/arch
Markdown goldmark 项目 README yuin/goldmark(MIT)
AsciiDoc lzip-go 项目 CHANGELOG sorairolake/lzip-go(CC-BY-4.0)
HTML Go net/http 包文档页(godoc) Go 官方文档快照
亲自跑一遍(无需任何外部服务)
git clone https://github.com/unitedrhino/docling
cd docling
go test ./... -run TestExamplesGolden -v   # 全部样例逐字回归,含上方复杂对象样例

或在你的代码里直接解析复杂样例:

// go get github.com/unitedrhino/docling
data, _ := os.ReadFile("examples/docx/rich.docx")
md, err := docling.ParseByExtToMarkdown("rich.docx", data)
fmt.Println(md) // 公式 LaTeX、SmartArt 流程 SVG、艺术字与 OLE 分类一目了然

与 anydoc 的对比(Firecrawl 的 Rust 转换库)

anydoc(Rust,MIT,1.7 万 Star)与 docling 同属"文档 → LLM 就绪数据"这一层,但取舍不同——anydoc 把转换层做到极简极快(14 种格式 → GFM Markdown,中位 4.4ms,无模型无外部服务,扫描 PDF 直接报错 Unsupported);docling 走结构化深度 + RAG 完整度路线:

维度 anydoc(Rust) docling(Go)
定位 纯转换层:不做 OCR/chunking/图表语义 转换 + 结构化 + RAG 分块,一站到检索
格式 14 种(强在旧二进制 .doc/.ppt/.xls、ODF、RTF、EPUB) 12 种(强在 HTML、Markdown、AsciiDoc、EML 邮件、图片、Docling JSON 回读)
输出 仅 GFM Markdown Markdown / HTML / Docling JSON(无损)/ content_list + 三种分块器
PDF 深度 文本型直接提取;扫描件返回 Unsupported(OCR 走 Firecrawl 托管 API) 文本型深度解析(跨页表格/多栏/字体乱码恢复/JPEG2000-JBIG2-软蒙版);扫描页可挂自部署大模型钩子
图表 不解析图表语义 OOXML 图表数据回填为可检索表格 + SVG 预览
速度 中位 4.4ms(Office 文档,浅转换) 论文 0.31s / 书稿 0.73s(深度解析口径,比 Python Docling 快 34~153 倍)
失败哲学 正确转换或大声失败(明确报错) 不伪造结果(缺失单元格留空、不确定保留原始信号)

速度口径提示:4.4ms 与 0.31s 不可直接对轰——前者是 Office 文档浅转换,后者是 PDF 深度解析(表格结构/阅读顺序/字体恢复)。两者哲学相近(明确失败优于静默污染),选型看你要"最快拿到干净 Markdown"还是"结构化深度 + RAG 就绪"。旧版二进制 Office(.doc/.ppt/.xls)、ODF、RTF、EPUB 在 docling 路线图中。

与 Python Docling 的差距(如实说明)

本仓库是 Docling 协议的 Go 实现,与 Python 官方版是互补关系而非等价替代。协议层与 Docling Core 1.10.0 完全对齐、可无损往返官方 JSON,分块语义对齐官方 HierarchicalChunker/HybridChunker;但解析质量层面存在明确差距:

我们领先的(纯 Go 规则引擎的优势)
  • 速度与部署:文本型文档快 34~153 倍,单二进制零依赖;官方版需要 Python 服务与模型文件(布局/表格/公式模型动辄数 GB)
  • Office 结构化深度:批注回复链、修订记录、OMML 公式、原始公式与透视表语义、SmartArt/艺术字/OLE 分类——官方版对 Office 的覆盖相对有限(如修订与部分图表语义不还原)
  • 文档内图表数据:OOXML 图表的缓存数据与公式区域回填为可检索表格;官方版图表理解走视觉模型,数据精度依赖模型
  • 额外输出:content_list 检索列表与知识库分块策略为 RAG 场景定制,官方版无对应物
官方版领先的(模型管线的能力上限)
  • 扫描件与图片型文档:官方版内置 OCR 模型管线开箱即用;我们未配置 OCRHook 时对纯扫描页无法产出文字(实测 mountain/VectorApple 等图片型 PDF 只能输出图片资产)
  • 复杂版面理解:像素级布局分割、非矩形版面、旋转扫描页(实测 ITU-T.81 标准封面为旋转扫描,需配置 PDFVisualHook 才能按正确方向读取)——官方模型管线原生处理
  • 图片内表格/公式:官方 TableFormer 模型可直接识别图片表格;我们依赖 VisualHook 按页路由,未配置时保留几何信号不猜结果
  • 输入覆盖:音频 ASR、EPUB、Apple Pages、XML 系列(XBRL/JATS/USPTO)、LaTeX 等官方版已支持,我们规划中
  • 极端字体文档:嵌入 CID-keyed CFF 且无映射、加密字体等无法证明字符含义的情况,官方视觉模型仍可"认出"文字,我们保留替换符
何时选谁
场景 建议
批量文本型文档入库、RAG 切片、CI/边缘部署 docling(Go):毫秒级、零依赖
高保真审阅、扫描件密集、图片表格/公式密集 Python Docling,或 docling(Go)+ 大模型钩子
两者都要 双引擎并用:Go 做基线与路由,Python/模型做疑难页增强

一句话:规则能确定的结构我们用纯 Go 做到极致;规则不确定的,我们诚实回退并留好模型接入点,而不是猜一个结果。

目录结构

docling/
├── docling.go          # 门面:Item、ParseByExt、ParseByExtToMarkdown
├── doclingserve.go      # Docling 服务解析(可选第二引擎)
├── export*.go           # Markdown / HTML 导出
├── contentlist.go       # ToContentList(RAG 内容列表)
├── chunker.go hybrid_chunker.go content_chunk.go # 三种分块策略
├── pdf*.go              # PDF:文本/布局/表格/视觉路由/图片编排
├── docx*.go pptx.go sheet.go # Word / PPT / Excel 解析
├── html.go markdown.go asciidoc.go eml.go image.go text.go table.go
├── internal/pdfenc/     # PDF 字节编码层:ToUnicode/CMap/SFNT 恢复、JPX/JBIG2 解码、软蒙版 alpha
├── internal/ooxml/      # Strict OOXML → Transitional 归一化
├── examples/            # 各格式样例源文件 ↔ Markdown 期望输出对照集
└── *_test.go            # 单元/端到端/官方 schema 验收测试

依赖与致谢

社区与共建

欢迎通过任意方式参与共建:

  • 提 Issue / PR:本仓库
  • 扫码关注公众号,获取版本更新与文档解析实践分享,一起共建:

微信公众号二维码

License

MIT

Documentation

Overview

asciidoc.go 用逐行状态机把 AsciiDoc 文本解析为 DoclingDocument， 是 docling 通用组件的 AsciiDoc 后端。 标题/列表/表格/字面块/图片/注释/段落语义复刻 docling 的 asciidoc_backend.py （docling 同样不依赖第三方 asciidoc 解析库，为纯逐行状态机）； 按任务约定补充/偏离的点（均已在对应位置注释说明）：

  • `[source,lang]` + `----` 围栏块产出 code 元素（docling 未处理，任务要求补齐）；
  • 表格 cell 装饰中的 `h` 标记映射 column_header=true，且装饰剥离扩展到 每个 "|" 之前（docling 仅剥行首/空白后装饰、剥后即弃，任务要求保留表头语义）；
  • 标题作为后续内容的父节点（层级父栈模式），使 content_list 携带章节路径； prov 全空不生成。

chunker.go 实现 DoclingDocument 的官方层级语义分块：标题只作为上下文， 普通文档元素各自成块，连续列表按 ListGroup 整体序列化，表格保持 GFM Markdown 结构。该分块器不做长度裁剪，检索尺寸策略由 ContentChunk 适配器负责。

content_chunk.go 实现面向知识库检索的 content_list 分块适配器。 它保持 Item 持久化协议不变，在消费侧统一完成章节聚合、长度控制、 大表拆分、版式噪声过滤和 Docling 多模态元素分流。

contentlist.go 实现 DoclingDocument（详细 JSON）到 content_list（简化 JSON） 的统一简化器，并附带 ParseDoclingDocument 兼容读取入口。

简化语义（上游转换层与简化层两路收敛）：

  • body 树先序遍历产出扁平 Item；标题节点更新章节路径栈， 元素的 _section_path = 祖先标题链（Docling 产物因此获得章节路径增强）；
  • label → 模态映射：title/section_header→text+TextLevel、formula→equation、 code/checkbox/paragraph/list_item/text→text、table→table、picture→image；
  • 细粒度 label 透传：page_header/page_footer/document_index/list_item/code/ checkbox/caption 填充 Item.Label（formula 由 type=equation 表达不填）， 供下游过滤/分流；
  • prov 取首段：page_no-1 对齐 golight 的 0-based PageIdx 基准（行为变更点， 旧 Docling 路径曾直通 1-based page_no）；bbox 归一化为 top<=bottom， 保持历史 content_list 不携带 coord_origin 的协议可稳定求并集；
  • 表格按 cell offset 铺格子渲染为 GFM Markdown，并做表格后处理清洗。

Package docling 提供知识库/文档场景的通用结构化解析能力： 把 Markdown、docx、PDF、xlsx、csv、纯文本统一解析为 content_list （[]Item 元素列表），元素携带标题层级（TextLevel）与章节路径 （SectionPath），表格独立成 table 元素并渲染为 GFM Markdown。 供切片、索引、检索等上层消费，各服务无需重复实现格式解析。

各格式解析要点：

  • Markdown：goldmark（GFM 扩展）AST 解析，代码块/表格结构化提取；
  • docx：WordprocessingML 流式状态机，pStyle 标题层级 + 表格行列；
  • PDF：ledongthuc/pdf 字符级字号/坐标，字号启发式识别标题层级， 按 Y 坐标聚合行、按页归组正文；
  • xlsx：excelize 遍历全部 sheet，每 sheet 独立 table 元素，大表分段；
  • csv：首行表头 + 行数分段；
  • eml：RFC 5322 头 + MIME 递归（text/html、text/plain、嵌套邮件）；
  • 图片（png/jpg/bmp/webp）：尺寸/DPI PictureItem + 可选 OCRHook 识别文本。

docling.go 定义 DoclingDocument 的 Go 结构体与文档树构建 API， 序列化形态与 docling-core 2.93.0（schema version 1.10.0）保持同构， 作为 docling 通用组件的"详细 JSON"输出协议： 各解析器（markdown/docx/pdf/xlsx/pptx/html 等）产出本结构， 再由 contentlist.go 的 ToContentList 统一简化为知识库 content_list。

协议要点（源自 docling-core 源码核对）：

  • 引用一律为 {"$ref": "#/texts/0"} 形式（RefItem）；
  • texts 为八类文本元素的 Union，Go 侧用单结构体 + label 分派专属字段表达；
  • prov（ProvenanceItem）为列表，bbox 默认 TOPLEFT 坐标原点；
  • 表格 cell 行列偏移 start 闭 end 开，grid 为序列化时现算的 computed 字段；
  • pages 键为字符串化的页号（Python int 键序列化产物）。

docx.go 实现 docx（WordprocessingML）的纯规则解析后端，产出 DoclingDocument。 行为复刻 Docling 的 msword_backend.py（.reference/docling 源码核对），复刻要点：

  • body 逐元素遍历（_walk_linear）：w:p 段落、w:tbl 表格、w:sdt 递归； 含图片（a:blip / v:imagedata）的段落产出 picture 元素（rId 经 document.xml.rels 定位 word/media 部件内嵌 data URI，段落文本作 caption；超出 Docling msword 后端"仅保留文本"行为的 P0 增强）； c:chart 关系委托共享 OOXML 图表解析器生成带 tabular_chart 的 picture； w:txbxContent 文本框按锚点顺序递归产出正文元素；
  • 页眉页脚关系部件输出 page_header/page_footer 并固定为 furniture 层； comments.xml 输出 notes 层 comment_section，并回填正文 Comments 引用； footnotes.xml 输出 footnote 元素，并与正文或表格单元格建立双向引用；
  • run 级粗体/斜体/下划线/删除线/上下标汇总到 formatting，关系超链接 写入 hyperlink；表格单元格通过 ref 关联同等富文本元数据；
  • label 判定（_get_label_and_level）：样式 id/name/base_style 任一含 "heading"（不区分大小写）→ section_header，层级优先取样式定义的 w:outlineLvl+1（仅 1-9 有效），否则从 "Heading N" 形态解析； Title 样式 → title（挂 body 顶层，后续一级标题挂其下）；
  • Code 样式（id/name 精确匹配集合，沿 base_style 链回溯）→ code 元素， 连续 Code 段落合并为同一元素（\n 连接，空段缓冲一个换行）；
  • w14:checkbox 段落 → checkbox_selected / checkbox_unselected（勾选状态 由 w14:checked val 判定，前缀 ☐☑☒ 由 AddCheckbox 清除）；
  • m:oMath：独立公式段落 → formula，常见 OMML 结构纯 Go 转 LaTeX， 行内公式按位置并入段落文本；未知节点递归保留可见内容；
  • 列表（_manage_list_structure 简化版）：w:numPr（numId+ilvl，ilvl 缺省 0， numId=0 视为无列表）→ list_group + list_item；numFmt 属于可见编号集合 （decimal/lowerRoman/upperRoman/lowerLetter/upperLetter/decimalZero）时 为有序（marker "1."/"2." 组内自增），否则无序（marker ""）； 不同 numId 切换新建分组；ilvl 增加时子分组挂上一级列表项（嵌套）；
  • 标题层级树（_add_heading）：维护 parents 槽位数组（键 0 为 Title 槽）， 跳级时补隐式 section 分组（name="header-i"），标题挂 parents[level-1]；
  • 表格（_handle_tables）：1x1 表视为版式容器（单元格内容当正文递归处理， 不产出 table）；gridSpan → ColSpan；vMerge continue 扩展锚单元格的 EndRowOffsetIdx 与 RowSpan；gridBefore 处理行首列偏移；首行 column_header=true；单元格多段落 "\n" 连接；
  • 不生成 prov（docx 无页面概念，对齐 Docling）。

无样式标题 fallback 为超出 Docling msword 后端的增强（对齐版面模型的识别 效果，Docling 纯规则后端只认样式）：第一遍解析后全文档零 heading/title 元素时，对收集的段落中间表示（run 加粗/字号）重跑标题判定，命中的手工 加粗/大字号短段改标 section_header 并线性重挂层级；见 applyUnstyledHeadingFallback。

文本抽取保留流式状态机口径：w:t 文本、w:tab→\t、w:br→\n。 内容为空时返回元素为空的文档（不视为错误）；畸形 zip/xml 返回 error。

docx_omml.go 实现 Office Math Markup Language 到 LaTeX 的纯 Go 转换。 转换器优先覆盖技术文档常见结构；未知标签递归保留可见子内容，确保公式 不因扩展属性或新版 Office 节点而丢失。

eml.go 实现 EML（RFC 5322 邮件，含 MIME 多部分）解析为 DoclingDocument：

  • 头解析：Subject 经 RFC 2047 解码后产出标题项并填 Meta.Title/Subject， From 显示名填 Meta.Author、Date 填 Meta.CreatedAt（RFC3339 UTC）， From/To/Date 引用头以"键: 值"文本项产出；
  • 正文按 MIME 递归拆解（深度上限 emlMaxDepth）：multipart 逐 part 递归， text/html 复用 ParseHTML、text/plain 复用 ParseText、message/rfc822 附件递归 ParseEML，其余二进制附件跳过；
  • Content-Transfer-Encoding 显式解码 base64 / quoted-printable， 字符集尽力转换（utf-8/us-ascii/iso-8859-1）；
  • 各 part 解析失败仅跳过该 part（不阻断整体），顶层头解析失败返回 error。

export.go 实现 DoclingDocument → Markdown 的内容级完整还原导出： 按文档树遍历产出结构完整的可读 Markdown（标题层级/段落/列表嵌套与 序号/GFM 表格/代码块/公式/图片），用于"还原原始文档"的预览与重建场景。

层级口径：标题以 TextLevel 优先（语义层级）；TextLevel 缺失时按树深度。 列表：list_item 带 Marker（"1."）用之，否则无序 "-"；嵌套按树深度缩进。

export_html.go 实现 DoclingDocument → HTML 的结构化导出，与 ExportMarkdown 保持同构的元素覆盖面：title/section 标题（h1-h6 按层级）、段落文本、列表 （组与列表项嵌套，有序/无序自动判定）、表格（首行表头 th + 跨行跨列）、 图片（<img src=URI> + caption）、代码块（<pre><code data-lang>）与公式 （LaTeX 原文以 <span class="formula"> 包裹，不要求前端渲染）， 输出完整 <!DOCTYPE html> 文档，用于 Web 预览与富文本下游消费。

html.go 把 HTML 文档解析为 DoclingDocument，是 docling 通用组件的 HTML 后端。 块级标签分发、平铺标题、列表/表格/代码块/图片语义、<br> 哨兵换行与 隐藏元素过滤均复刻 docling 的 html_backend.py； 图片占位和首标题前 furniture 分层对齐 Docling HTML 后端；prov 全空不生成。

hybrid_chunker.go 在层级语义分块之上实现 token 感知的二次切分与合并。 调用方可注入与向量模型一致的纯 Go tokenizer 计数函数；未注入时使用 rune 数作为保守上限，不引入 Python、模型文件或外部服务依赖。

image.go 实现图片格式输入（PNG/JPEG/BMP/WEBP）解析为 DoclingDocument： 魔数识别格式后构造单页文档（一页一图，ImageRef 内嵌 data URI）； 无 OCR 时仍产出包含像素尺寸/DPI 的 PictureItem；配置 OCRHook 或兼容的 PageOCRHook 时，识别结果经清洗校验后由 ParseMarkdown 结构化并入文档。

markdown.go 实现 Markdown 到官方 DoclingDocument 的结构化转换。

media.go 实现 OOXML 容器（docx/pptx/xlsx）共用的媒体资产与文档元数据提取：

  • mediaToDataURI 把 zip 内图片字节封装为 data URI（内嵌 ImageRef.URI）， 单图超过 maxMediaDataURIBytes 时返回空串（URI 留空，避免内存放大）；
  • parseOOXMLRelationships 由 pptx.go 提供的通用关系解析，本文件的 ooxmlCorePropsMeta 借助它定位图片目标部件；
  • parseOOXMLCoreProps 解析 docProps/core.xml 为文档级元数据 DocMeta。

三个 OOXML 后端（docx/pptx/xlsx）共用，避免各后端重复实现。

ocr.go 定义 PDF 解析的外部 OCR 钩子能力：扫描件页与高乱码页可回调 调用方注入的识别实现（如大模型视觉识别服务），识别结果以 Markdown 结构化子文档并入主文档——docling 本身不引入任何 OCR 引擎或渲染依赖，识别完全由调用方决定。

office_comment.go 定义 Office 协作批注在 Docling 节点 meta 中的稳定扩展键， 并集中完成作者、回复、时间和解决状态的 JSON 编码。

office_object.go 统一保存 OOXML 复杂对象的语义、关系来源和可选预览。 SmartArt、艺术字与嵌入对象均按 Docling 1.10 的 PictureItem 表示； 非官方信息只写入带 docling__ 前缀的 PictureMeta 扩展字段。

office_object_render.go 为无法直接复用 Office 预览资源的复杂对象生成 稳定语义 SVG。该预览不追求像素级还原，但在纯 Go 环境中保证对象可见。

ooxml_chart.go 实现 DOCX、PPTX、XLSX 共用的 OOXML 图表解析：从 chart*.xml 的内嵌缓存读取图表类型、标题、分类轴与系列数值，转换为官方 label=picture 的 PictureMeta.classification 和 tabular_chart.chart_data。

本实现只读取 OOXML 包内已有 XML/缓存，不调用 LibreOffice 或其他外部程序； 公式引用没有缓存值时，由调用方提供的工作簿解析器回填数据。

ooxml_chart_data.go 实现 OOXML 图表公式的数据回填。XLSX 图表直接读取 当前工作簿，DOCX/PPTX 图表读取 chart*.xml.rels 指向的嵌入 XLSX；全部 使用 archive/zip 与 excelize 的纯 Go 路径，不依赖 Office 或 LibreOffice。

ooxml_chart_render.go 把结构化 OOXML 图表数据渲染为内嵌 SVG ImageRef。 渲染器覆盖柱状、折线、面积、饼图、圆环、散点和雷达等常见系列；未知 类型输出带标题与数据摘要的稳定占位图。实现仅使用 Go 标准库。

pdf.go 实现 PDF 纯文本解析：基于 ledongthuc/pdf 的字符级 Content() 提取 （对应 docling pypdfium2_backend 的 rect 级文本路径，Go 侧为 char 级聚合）， 按 Y 坐标垂直分行、行内按 X 水平合并，并以字号启发式识别标题， 产出 DoclingDocument 文档树。

有意设计（非复刻误差）：官方无模型 PDF 路径不产 label 与 prov， 本项目的 Go 实现由既有字号启发式提供 label/层级，并由行聚合坐标填充 prov（页号 + BOTTOMLEFT bbox + charspan），以满足知识库切片的定位语义。

主要模块划分：

  • 行聚合：assemblePDFPageLines / assemblePDFLines（垂直分行 + 水平合并， 同时累计行 bbox 供 prov 填充）；
  • 版式增强：classifyPDFFurnitureLines（归一化跨页指纹识别页眉/页脚）、 annotatePDFTOCRegions（点线+页码行识别目录区域，收进"目次"分组）、 封面主标题识别（首页最大字号短行判 title，封面其余大字行降为正文）；
  • 标题启发式：medianLineFontSize / isPDFHeadingCandidate / buildPDFElements （全文档行字号中位数估正文字号，字号显著更大的短行判为标题， 字号降序映射 1-3 级；页眉/页脚/目录行不参与统计与标题判定）；
  • 块组装：buildPDFBlocks（标题独立成块、正文按页归组并按长度分段）；
  • 树构建：buildPDFDoclingDocument（标题按层级父挂接表达章节路径）；
  • 兼容出口：buildPDFContentItems / classifyPDFLines（旧 content_list 视图， 供既有测试与统计使用）。

pdf_image.go 纯 Go 解析 PDF 页面 Image XObject 的绘制位置与覆盖率， 并通过 pdfcpu 将可安全解码的图片保存为带 data URI 的 PictureItem 中间行。 几何识别与像素解码相互独立：解码失败仍保留图片质量信号用于视觉路由。

pdf_image_codecs.go 是 PDF 内嵌图片补充解码的编排层：JPEG 2000 与 JBIG2 的字节级解码由 internal/pdfenc 提供，这里负责从 pdfcpu 提取结果 中识别对应资产并接入提取流程。

pdfcpu 不解码这两类编码：JPEG 2000 原始 codestream 被透传为 image/jp2 资产，JBIG2 段流被透传为 image/jbig2 资产，此前均无法进入检索与多模态 链路。任何解码失败都由后续统一图片校验跳过该资源，正文解析不受影响。

pdf_layout.go 基于行级边界框实现保守的 PDF XY-cut 阅读顺序恢复。 算法只在页面存在稳定主空白带时切分左右栏；跨越空白带的宽行作为标题、 说明等横向锚点，先按锚点划分上下区域，再在各区域内按左到右递归读取。

pdf_poppler.go 实现 PDF 文本提取的 poppler 降级后端： ledongthuc/pdf 对部分中文字体（方正等自定义 CMap）解析失败（整页空或 乱码），而 poppler 的 pdftotext 是 Linux 生态最成熟的提取器，中文支持 完善。降级链路：ledongthuc（字符级精确字号/坐标）→ 提取为空或乱码超限 → pdftotext -bbox-layout（TOPLEFT 词盒转 BOTTOMLEFT，行高近似字号） → 外部 OCR 钩子。 pdftotext 为可选外部依赖（PATH 检测，缺失时降级链自动禁用）。

pdf_security.go 定义 PDF 解析的统一资源边界，并在任何文本、图片或 页级模型输入处理之前通过 pdfcpu 完成结构校验。pdfcpu Context 在一次 解析内复用，避免图片提取和单页 PDF 生成重复读取原始文件。

pdf_smask.go 是低位深（bpc=1/2/4）软蒙版合成的编排层。pdfcpu 提取 Image XObject 时只应用 bpc=8 的 SMask（源码标注 TODO），低位深软蒙版 被静默忽略、图片整体不透明；这里在 pdfcpu 提取结果之上解引用蒙版流， 由 internal/pdfenc 完成 alpha 展开与像素合成。

任何一步失败都保留原提取结果：软蒙版是增强信息，不能让图片整体丢失。

pdf_table.go 基于 PDF 词级坐标恢复保守的矩形表格网格，并从后续正文流移除 已消费的表格行。识别只接受至少两行两列且列起点稳定的连续区域，避免把普通 双栏长正文当成表格。

pdf_unicode_recover.go 承接 Unicode 恢复的版面编排层：判断页面是否值得 恢复、执行恢复并与既有文本行按乱码率择优。字节级字符映射见 internal/pdfenc。

pdf_visual.go 定义 PDF 复杂页面的质量评估与可选大模型结构化视觉协议。 纯 Go 坐标解析始终是主路径；只有页面存在扫描、乱码、疑似未恢复表格、 公式密集或栏位歧义时才建议调用钩子，结果无效时安全回退原解析结果。

pptx.go 实现 PPTX（PowerPoint OOXML）到 DoclingDocument 的 Go 本地解析后端， 复刻 docling mspowerpoint_backend.py 的核心行为（纯 Go：archive/zip + encoding/xml 手写 token 流状态机，不依赖 python-pptx）：

  • 每 slide 建 slide-N 分组（CHAPTER 组的 Go 侧用 AddSectionGroup 表达）并登记 页面尺寸（presentation.xml 的 sldSz EMU 原始值）；
  • 形状按视觉位置排序（top 分行 + 行内 left 升序，容差 45720 EMU=0.05"）；
  • title/ctrTitle 占位符 → title，其余有文本 shape → 逐段落 paragraph；
  • 段落 bullet（a:buChar/buAutoNum/buNone）判定列表项，连续列表段落共享一个 list 分组，有序 marker 自增，lvl>0 的段落作为子列表挂上一列表项下；
  • a:tbl 表格转 TableData：gridSpan/rowSpan → ColSpan/RowSpan（start 闭 end 开）， 空文本 cell 丢弃但 num_rows/num_cols 按全尺寸声明，全空表不建；
  • prov bbox 为 EMU 原始值 [l,t,l+w,t+h]，CoordOrigin=BOTTOMLEFT（pptx 页面 坐标系自底向上），无几何形状回退整页 (0,0,slideW,slideH)；
  • 文档元数据读 docProps/core.xml，PageCount 取 slide 数（P0 增强）。

有意简化（复刻边界，注释逐条记录）：

  • p:pic 图片提取为 picture 元素（r:embed 经 slide 关系表定位 ppt/media 部件内嵌 data URI，超限/缺失时 URI 留空；P0 增强，超出 docling 复刻 边界——Go 各后端原统一不做图片资产提取）；
  • 图表 graphicFrame 保留 chart 关系引用，并委托共享 OOXML 图表解析器产出图片项；
  • 备注取 notesSlide 的 body 占位符文本并写入 NOTES content layer；
  • 幻灯片旧式及 Office 2021+ 现代 comments 部件转为 NOTES 文本；现代 批注保留 authors、replyLst 与解决状态，按批注坐标关联最近正文项；
  • 空段落不产出元素（源码会产出空文本元素，知识库场景无需空块）。

sheet.go 实现 xlsx 与 csv 的纯规则表格解析后端，产出 DoclingDocument （详细 JSON 协议见 docling.go），逐条复刻 Docling 对应后端的规则行为。

xlsx 复刻 docling/backend/msexcel_backend.py：

  1. 每 sheet 产出一个页面（页号按工作簿顺序自增，尺寸=内容包络， 对齐 _find_page_size 取该页 prov bbox 的最大 r/b）与一个 sheet 分组 （AddSectionGroup，name=sheet 名）；
  2. 表格检测为 BFS flood fill 连通区域（_find_data_tables/_find_table_bounds， gap_tolerance=0：4 邻域相邻即连通），连通载体为"值非空 cell + 合并区域 全部位置"，一个连通区域产出一个 table_item，包围盒内空洞补空 cell 保持矩形；
  3. 合并单元格（GetMergeCells）：锚点承载行列跨度（end 开区间），影子位置 不产独立 cell；
  4. 表内首行 column_header=true；
  5. 表首行为"跨全列合并的单一标题"时拆出为 TEXT 元素（挂 sheet 分组下）， 表格锚点行下移（_split_leading_section_label）；
  6. prov 以 0-based 单元格索引坐标表达：bbox={l:起始列, t:起始行, r:起始列+列数, b:起始行+行数}，charspan=[0,0]；
  7. 隐藏 sheet 保留并标记 invisible，批注标记 notes，图片与图表保留锚点；
  8. 各元素按单元格/对象左上角坐标稳定排序，图表数据复用共享 OOXML helper；
  9. 值取 excelize 缓存结果（公式取缓存值，对齐 data_only 语义）。

csv 复刻 docling/backend/csv_backend.py：

  1. 分隔符嗅探：候选 ,;\t|: 逐个试解析，取各行字段数一致且列数最多者， 全部失败回退逗号；
  2. 整文件产出一个 table：首行 column_header、span 恒 1、num_cols 取最大 行宽、列数不齐不报错；
  3. 不生成 prov；
  4. 空文件返回空文档不报错。

与旧版（直出 content_list []Item）的差异：签名统一为 (*DoclingDocument, error)， 由 contentlist.go 的 ToContentList 统一简化；解析层不再按行数拆分大表 （分段语义下沉至知识库切片层）；空内容返回空文档不报错，与 markdown.go 样板一致，由调用方决定回退。

xlsx_collaboration.go 解析 Excel 365 threaded comments 与 persons 部件， 将回复链转换为 notes 层 comment_section，并保留单元格锚点和协作元数据。

Index

Constants

View Source 
const (
	// DocChunkMetaSchemaName 是官方 DocMeta 的固定 schema_name。
	DocChunkMetaSchemaName = "docling_core.transforms.chunker.DocMeta"
	// DocChunkMetaVersion 是当前对齐的官方 DocMeta schema 版本。
	DocChunkMetaVersion = "1.0.0"
)
View Source 
const (
	// DefaultContentChunkMaxRunes 是普通检索分块的默认字符上限。
	DefaultContentChunkMaxRunes = 900
	// DefaultContentTableMaxRows 是单个表格分块允许包含的默认数据行数。
	DefaultContentTableMaxRows = 100
)
View Source 
const (
	// SourceGolight Go 本地轻量解析（docling 各后端）。
	SourceGolight = "golight"
	// SourceDocling Docling 高级解析（docling-serve HTTP）。
	SourceDocling = "docling"
)

解析器来源标记，写入 Item.Source，供下游区分 go_light 与 Docling 产物 （如多模态分流按 SourceDocling 判断）。

View Source 
const (
	// DoclingSchemaName schema 固定字面量。
	DoclingSchemaName = "DoclingDocument"
	// DoclingSchemaVersion 当前 schema 版本。
	DoclingSchemaVersion = "1.10.0"
)

Docling schema 固定值（docling_core/types/doc/common/constants.py）。

View Source 
const (
	// DefaultHybridMaxTokens 是 HybridChunks 未显式配置时的 token 上限。
	DefaultHybridMaxTokens = 512
)
View Source 
const PDFStructuredVisualPrompt = `` /* 1053-byte string literal not displayed */

PDFStructuredVisualPrompt 是结构化视觉模型的内置严格提示词。

Variables

View Source 
var ErrPDFResourceLimit = errors.New("pdf resource limit exceeded")

ErrPDFResourceLimit 表示 PDF 输入超过 Docling 的安全资源边界。

Functions

func ContextualizeDocChunk 

func ContextualizeDocChunk(chunk DocChunk) string

ContextualizeDocChunk 把标题路径与正文组合为 embedding 模型应消费的文本。

func ExportHTML 

func ExportHTML(doc *DoclingDocument) string

ExportHTML 把 DoclingDocument 导出为完整 HTML 文档（<!DOCTYPE html>）。 doc 或 body 为空时返回仅含骨架的空文档；<title> 优先取 Meta.Title， 缺省回退文档名。

func ExportHTMLWithOptions 

func ExportHTMLWithOptions(doc *DoclingDocument, options ExportOptions) string

ExportHTMLWithOptions 按指定内容层把文档导出为完整 HTML 文档。

func ExportMarkdown 

func ExportMarkdown(doc *DoclingDocument) string

ExportMarkdown 把 DoclingDocument 还原为完整 Markdown 文档。 doc 或 body 为空时返回空串。

func ExportMarkdownWithOptions 

func ExportMarkdownWithOptions(doc *DoclingDocument, options ExportOptions) string

ExportMarkdownWithOptions 按指定内容层把文档还原为 Markdown。

func HealthCheckDoclingService 

func HealthCheckDoclingService(ctx context.Context, opts DoclingServiceOptions) error

HealthCheckDoclingService 检查 docling-serve 服务是否可达（启动预热与运行时探测）。

func ItemHeadingPath 

func ItemHeadingPath(item Item) string

ItemHeadingPath 把元素的章节路径拼接成字符串（"A > B" 形式）。

func ItemToText 

func ItemToText(item Item) string

ItemToText 把任意 Item 转换成可入向量库的纯文本表示。 图片/表格/公式的详细描述由上层按需生成，这里只输出已有文本字段。

func JoinItemTexts 

func JoinItemTexts(items []Item) string

JoinItemTexts 把多个元素文本按阅读顺序拼接，用换行分隔。

func ParseByExtToMarkdown 

func ParseByExtToMarkdown(name string, data []byte) (string, error)

ParseByExtToMarkdown 按文件扩展名分发解析并直接返回 Markdown 文本 （AI 场景一步到位，等价 ParseByExt 后调用 ToMarkdown）；未知扩展名 返回错误，解析成功但文档为空时返回仅含换行的空文档文本。

func ParseMarkdownTable 

func ParseMarkdownTable(md string) [][]string

ParseMarkdownTable 把 Markdown 表格文本解析成二维字符串数组。 优先使用 goldmark 的 GFM 严格解析，正确处理 \| 转义与单元格边界； 输入不含合法 GFM 表格（如缺失分隔行的宽松格式）时回退按行切分的宽松解析， 保证行为不劣化。分隔行不进入数据数组。

func ParseWithDoclingService 

func ParseWithDoclingService(ctx context.Context, docName string, data []byte, opts DoclingServiceOptions) (*DoclingDocument, *DoclingServeResult, error)

ParseWithDoclingService 把单个文件提交给 docling-serve 解析，返回统一 DoclingDocument。 与 golight 各 ParseXxx 并列：复杂版面/扫描件/中文正式文档建议走本入口（质量显著优于规则提取）。

func RenderMarkdownTable 

func RenderMarkdownTable(rows [][]string) string

RenderMarkdownTable 把二维数组渲染为 Markdown 表格字符串。

Types

type BBox 

type BBox struct {
	Left   float64 `json:"l"`
	Top    float64 `json:"t"`
	Right  float64 `json:"r"`
	Bottom float64 `json:"b"`
}

BBox 表示元素在页面内的边界框（left/top/right/bottom）。

type BaseMeta 

type BaseMeta map[string]json.RawMessage

BaseMeta 保存节点级官方元数据及命名空间扩展字段。 使用 RawMessage 保证当前解析器尚不理解的官方或自定义字段可无损往返。

type ContentChunk 

type ContentChunk struct {
	// Content 是进入向量检索的纯文本内容。
	Content string `json:"content"`
	// ChunkIndex 保留历史序号字段；content_list 路径保持零值。
	ChunkIndex int64 `json:"chunk_index,omitempty"`
	// CharStart 保留历史字符起点字段；content_list 路径保持零值。
	CharStart int64 `json:"char_start,omitempty"`
	// CharEnd 保留历史字符终点字段；content_list 路径保持零值。
	CharEnd int64 `json:"char_end,omitempty"`
	// TokenEstimate 保留历史 token 估算字段；由上层需要时填充。
	TokenEstimate int64 `json:"token_estimate,omitempty"`
	// HeadingPath 是用“ > ”连接的章节路径。
	HeadingPath string `json:"heading_path,omitempty"`
	// PageIdx 是分块首个元素的页码。
	PageIdx int64 `json:"page_idx,omitempty"`
	// OrderIndex 是分块首个元素的阅读顺序。
	OrderIndex int64 `json:"order_index,omitempty"`
	// BBox 是同组元素边界框的并集。
	BBox *BBox `json:"bbox,omitempty"`
}

ContentChunk 是 content_list 的知识库检索分块，字段与历史 knowledgeChunkSpan 对齐，便于迁移时无损映射来源位置和阅读顺序。

func ChunkContentList 

func ChunkContentList(items []Item, options ContentChunkOptions) []ContentChunk

ChunkContentList 把历史 content_list 转为知识库检索分块。 相邻且章节路径、标题层级、来源及 label 相同的文本先合并；普通内容再按 rune 数切分，表格按数据行切分并在每段重复标题、表头和脚注。

type ContentChunkOptions 

type ContentChunkOptions struct {
	// MaxRunes 指定普通分块字符上限；小于等于零时使用 900。
	MaxRunes int
	// TableMaxRows 指定表格每段的数据行上限；小于等于零时使用 100。
	TableMaxRows int
	// IncludeDoclingMultimodal 为 true 时把 Docling 图片、表格和公式也
	// 输出为普通检索分块；默认 false，以避免与多模态 artifact 重复。
	IncludeDoclingMultimodal bool
	// NoiseLabels 指定不进入检索的 label；nil 使用页眉、页脚和目录默认值，
	// 非 nil 空切片可显式关闭噪声过滤。
	NoiseLabels []string
}

ContentChunkOptions 控制 content_list 到知识库分块的兼容策略。 零值默认口径：900 rune、表格每段 100 个数据行、过滤 页眉/页脚/目录，并把 Docling 图片、表格和公式交给多模态模块。

type ContentLayer 

type ContentLayer string

ContentLayer 内容层：正文/版式家具/不可见/备注，对齐 docling-core ContentLayer。 

const (
	LayerBody       ContentLayer = "body"
	LayerFurniture  ContentLayer = "furniture"
	LayerBackground ContentLayer = "background"
	LayerInvisible  ContentLayer = "invisible"
	LayerNotes      ContentLayer = "notes"
)

ContentLayer 取值。

type CoordOrigin 

type CoordOrigin string

CoordOrigin bbox 坐标原点：TOPLEFT（默认）/ BOTTOMLEFT（pptx 等页面坐标系使用）。 

const (
	CoordOriginTopLeft    CoordOrigin = "TOPLEFT"
	CoordOriginBottomLeft CoordOrigin = "BOTTOMLEFT"
)

CoordOrigin 取值。

type DocChunk 

type DocChunk struct {
	Text string       `json:"text"`
	Meta DocChunkMeta `json:"meta"`
}

DocChunk 表示一个不经过长度切分的层级语义块。

func HierarchicalChunks 

func HierarchicalChunks(doc *DoclingDocument) []DocChunk

HierarchicalChunks 按 Docling 文档树生成官方语义 chunk。标题依据 level 替换当前路径，列表分组整体成块，其他可序列化正文元素各自成块。

func HybridChunks 

func HybridChunks(doc *DoclingDocument, options HybridChunkOptions) []DocChunk

HybridChunks 先调用 HierarchicalChunks 生成文档语义块，再按用户 tokenizer 切分超限块，最后尽量合并具有相同标题的相邻小块。

type DocChunkMeta 

type DocChunkMeta struct {
	SchemaName string            `json:"schema_name"`
	Version    string            `json:"version"`
	DocItems   []json.RawMessage `json:"doc_items"`
	DocRefs    []string          `json:"doc_refs"`
	Headings   []string          `json:"headings,omitempty"`
	Provenance []ProvenanceItem  `json:"provenance"`
	Origin     *DocumentOrigin   `json:"origin,omitempty"`
}

DocChunkMeta 保存 chunk 的标题上下文和可回溯来源。DocItems 对齐官方 DocMeta 必填字段；DocRefs 与 Provenance 是 Go 适配层保留的便捷溯源视图。

type DocItemLabel 

type DocItemLabel string

DocItemLabel 元素细粒度分类，取值对齐 docling-core DocItemLabel 的常用子集。 

const (
	LabelTitle              DocItemLabel = "title"
	LabelSectionHeader      DocItemLabel = "section_header"
	LabelText               DocItemLabel = "text"
	LabelParagraph          DocItemLabel = "paragraph"
	LabelListItem           DocItemLabel = "list_item"
	LabelCode               DocItemLabel = "code"
	LabelFormula            DocItemLabel = "formula"
	LabelCaption            DocItemLabel = "caption"
	LabelFootnote           DocItemLabel = "footnote"
	LabelReference          DocItemLabel = "reference"
	LabelHandwrittenText    DocItemLabel = "handwritten_text"
	LabelEmptyValue         DocItemLabel = "empty_value"
	LabelFieldKey           DocItemLabel = "field_key"
	LabelFieldValue         DocItemLabel = "field_value"
	LabelFieldHint          DocItemLabel = "field_hint"
	LabelFieldHeading       DocItemLabel = "field_heading"
	LabelMarker             DocItemLabel = "marker"
	LabelCheckboxSelected   DocItemLabel = "checkbox_selected"
	LabelCheckboxUnselected DocItemLabel = "checkbox_unselected"
	LabelTable              DocItemLabel = "table"
	LabelPicture            DocItemLabel = "picture"
	// LabelChart 仅用于兼容旧 Docling 文档；新图表必须使用 LabelPicture
	// 并通过 PictureMeta.Classification 标注图表类型。
	LabelChart          DocItemLabel = "chart"
	LabelForm           DocItemLabel = "form"
	LabelKeyValueRegion DocItemLabel = "key_value_region"
	LabelGradingScale   DocItemLabel = "grading_scale"
	LabelFieldRegion    DocItemLabel = "field_region"
	LabelFieldItem      DocItemLabel = "field_item"
	// 版式家具与目录细分类（docling-core 枚举存在；PDF 后端用于
	// 页眉/页脚跨页指纹与目录点线区域的行级标注）。
	LabelPageHeader    DocItemLabel = "page_header"
	LabelPageFooter    DocItemLabel = "page_footer"
	LabelDocumentIndex DocItemLabel = "document_index"
)

DocItemLabel 常用取值。

type DocMeta 

type DocMeta struct {
	Title     string `json:"title,omitempty"`     // 文档标题（dc:title / 邮件 Subject）
	Author    string `json:"author,omitempty"`    // 作者（dc:creator / 邮件 From 显示名）
	Subject   string `json:"subject,omitempty"`   // 主题（dc:subject / 邮件 Subject）
	Language  string `json:"language,omitempty"`  // 语言（dc:language）
	PageCount int    `json:"pageCount,omitempty"` // 页数（PDF 页数 / pptx slide 数 / xlsx 可见 sheet 数）
	CreatedAt string `json:"createdAt,omitempty"` // 创建时间（dcterms:created / 邮件 Date，RFC3339 UTC）
}

DocMeta 文档级元数据：各解析器尽力填充（OOXML docProps/core.xml、 PDF 页数、EML 邮件头等），取不到的字段留空不序列化。

type DoclingBBox 

type DoclingBBox struct {
	L           float64     `json:"l"`
	T           float64     `json:"t"`
	R           float64     `json:"r"`
	B           float64     `json:"b"`
	CoordOrigin CoordOrigin `json:"coord_origin"`
}

DoclingBBox 页面/页内坐标边界框；坐标原点由 CoordOrigin 决定（默认 TOPLEFT）。

func (DoclingBBox) MarshalJSON 

func (b DoclingBBox) MarshalJSON() ([]byte, error)

MarshalJSON 为未显式设置坐标原点的旧对象补齐 Docling 默认 TOPLEFT。

type DoclingDocument 

type DoclingDocument struct {
	SchemaName    string              `json:"schema_name"`
	Version       string              `json:"version"`
	Name          string              `json:"name"`
	Origin        *DocumentOrigin     `json:"origin,omitempty"`
	Meta          *DocMeta            `json:"-"`
	Body          *GroupItem          `json:"body"`
	Furniture     *GroupItem          `json:"furniture"`
	Groups        []GroupItem         `json:"groups"`
	Texts         []TextItem          `json:"texts"`
	Pictures      []PictureItem       `json:"pictures"`
	Tables        []TableItem         `json:"tables"`
	KeyValueItems []json.RawMessage   `json:"key_value_items"`
	FormItems     []json.RawMessage   `json:"form_items"`
	FieldRegions  []json.RawMessage   `json:"field_regions,omitempty"`
	FieldItems    []json.RawMessage   `json:"field_items,omitempty"`
	Pages         map[string]PageItem `json:"pages"`
}

DoclingDocument 顶层文档结构（详细 JSON 协议），与 docling-core DoclingDocument.export_to_dict() 产物同构。

func NewDoclingDocument 

func NewDoclingDocument(name string) *DoclingDocument

NewDoclingDocument 创建空文档，body/furniture 初始化对齐 docling-core （name="_root_"，self_ref="#/body"/"#/furniture"）。

func ParseAsciiDoc 

func ParseAsciiDoc(data []byte) (*DoclingDocument, error)

ParseAsciiDoc 解析 AsciiDoc 为 DoclingDocument（复刻 docling asciidoc_backend）。 逐行状态机天然容错，畸形输入不报错；空输入返回元素为空的文档。

func ParseByExt 

func ParseByExt(name string, data []byte) (*DoclingDocument, error)

ParseByExt 按文件扩展名分发的统一解析入口，产出 DoclingDocument （详细 JSON 协议）；content_list 可经 ToContentList(doc, source) 派生， Markdown 文本可经 ParseByExtToMarkdown 一步取得。 供 CLI、双跑对比与调用方按文件类型统一解析使用；未知扩展名返回错误。

func ParseByExtWithOptions 

func ParseByExtWithOptions(name string, data []byte, options ParseOptions) (*DoclingDocument, error)

ParseByExtWithOptions 按扩展名和选项统一解析文档，并补齐官方 origin。

func ParseCSV 

func ParseCSV(data []byte) (*DoclingDocument, error)

ParseCSV 解析 csv 为单 table 文档：整文件一个 table，首行 column_header、 span 恒 1、num_cols 取最大行宽、列数不齐不报错、不生成 prov；空文件返回 空文档不报错。

func ParseDoclingDocument 

func ParseDoclingDocument(raw json.RawMessage) (*DoclingDocument, error)

ParseDoclingDocument 解析 DoclingDocument JSON（新版 docling-core 形态）， 并兼容线上 docling-serve v1.21 的旧版差异：

  • 旧版标题 label 为 "heading-N"，归一化为 section_header + TextLevel=N；
  • 旧版公式 LaTeX 存独立 latex 字段，归一化到 Text/Formula 消费语义。

func ParseDocx 

func ParseDocx(data []byte) (*DoclingDocument, error)

ParseDocx 解析 docx（zip 打包的 WordprocessingML）为 DoclingDocument。 参数 data 为 docx 文件字节流；返回文档树与错误。 word/document.xml 缺失、zip 损坏或 XML 畸形时返回 error； 文档内容为空时返回元素为空的文档（不视为错误）。 word/styles.xml 与 word/numbering.xml 缺失或畸形时忽略（按无样式/无编号处理）。 解析完成后若全文档零 heading/title 元素，触发无样式标题 fallback （手工加粗/大字号短段重判为标题，超出 Docling msword 后端的增强）。

func ParseEML 

func ParseEML(data []byte) (*DoclingDocument, error)

ParseEML 解析 EML 邮件（RFC 5322 头 + MIME 正文）为 DoclingDocument。 产出结构：Subject 标题项 → From/To/Date 引用头键值文本项 → 各 part 正文 （按 MIME 顺序并入 body）；顶层头解析失败返回 error，正文 part 解析失败 时跳过该 part（不视为错误）。

func ParseHTML 

func ParseHTML(data []byte) (*DoclingDocument, error)

ParseHTML 解析 HTML 为 DoclingDocument（复刻 docling html_backend 语义）。 html 解析器自容错，畸形输入不报错；空输入或无有效内容时返回元素为空的文档。

func ParseImage 

func ParseImage(data []byte) (*DoclingDocument, error)

ParseImage 解析图片字节为 DoclingDocument（无 OCR 钩子的便捷版）。

func ParseImageWithOptions 

func ParseImageWithOptions(data []byte, opt PDFOptions) (*DoclingDocument, error)

ParseImageWithOptions 解析图片字节为单页 DoclingDocument：魔数检测 PNG/JPEG/BMP/WEBP（其余格式拒绝）；始终产出单页 PictureItem。新旧 OCR 钩子存在时以 pageNo=1 调用，失败或无效不影响图片文档返回。

func ParseMarkdown 

func ParseMarkdown(data []byte) (*DoclingDocument, error)

ParseMarkdown 用 goldmark（GFM 扩展）把 Markdown 解析为 DoclingDocument， 复刻 Docling md_backend 的 label 规则：一级标题→title、其余标题→section_header、 围栏代码块→code（带语言）、列表→list_group+list_item（嵌套列表挂上一列表项， 对齐 md_backend 嵌套组织）、GFM 表格→table（首行 column_header，行列为表内偏移）。 标题按 Docling Markdown 后端平铺到 body：H1→title，H2-H6→level 1-5； content_list 的章节路径由 ToContentList 根据平铺标题顺序推导。 输入为空白或解析后无有效内容时返回元素为空的文档（不视为错误），由调用方回退。

func ParsePDF 

func ParsePDF(data []byte) (*DoclingDocument, error)

ParsePDF 解析 PDF 为 DoclingDocument（复刻 docling pypdfium2_backend 的 PDF 纯文本路径，label/层级与 prov 为本项目有意增强）：

  • 基于 ledongthuc/pdf 的 Content() 拿到带字号与坐标的字符，按 Y 聚合成行；
  • 以全文档行字号中位数为正文字号，字号显著更大且行长短的行识别为标题， 字号降序映射层级（最大 1 级，最多 3 级），标题按层级父挂接表达章节路径；
  • 正文挂最近的祖先标题（无则挂 body），单页正文超长时分段， 元素 prov 取段内各行 bbox 的并集；
  • 无字符内容（扫描件）的页回退整页纯文本，产出无 prov 的 text 元素兜底；
  • 每个有效页按可见 CropBox、UserUnit 和 Rotate 登记显示尺寸， 文本、表格、图片与视觉结果共用从零开始的 BOTTOMLEFT 坐标。

解析失败或解析后无文本内容时返回 error。 需要外部 OCR（扫描页/乱码页回调识别服务）时使用 ParsePDFWithOptions。

func ParsePDFWithOptions 

func ParsePDFWithOptions(data []byte, opt PDFOptions) (*DoclingDocument, error)

ParsePDFWithOptions 解析 PDF 并支持外部 OCR 钩子（能力全集入口）； ParsePDF 等价于 ParsePDFWithOptions(data, PDFOptions{})。

触发时机（逐页）：

  • 无字符内容的扫描兜底页（GetPlainText 亦为空）→ 调 hook；
  • 页文本乱码率（textGarbageRatio）超过 GarbageThreshold → 调 hook 重识别；

hook 成功且返回非空文本时，识别文本经 ParseMarkdown 转为结构化子文档， 按页序并入主文档（元素 prov 标注实际页号）；失败或未设置钩子时维持 原有行为（扫描页无内容、乱码页保留原文本）。

func ParsePPTX 

func ParsePPTX(data []byte) (*DoclingDocument, error)

ParsePPTX 解析 PPTX（OOXML zip）为 DoclingDocument，复刻 docling mspowerpoint_backend.py 的 slide 遍历与形状处理行为（详见文件头注释）。 非 pptx / 损坏 zip / 缺少 presentation.xml 返回 error； slide 集合为空时返回元素为空的文档（不视为错误）。

func ParseText 

func ParseText(data []byte) (*DoclingDocument, error)

ParseText 解析纯文本为单 text 元素的 DoclingDocument（不做结构识别）， 复刻 Docling 纯文本行为：整文件一个 TEXT 元素、无层级、无 prov。 输入为空白时返回元素为空的文档（不视为错误），由调用方决定回退或报错。

func ParseXLSX 

func ParseXLSX(data []byte) (*DoclingDocument, error)

ParseXLSX 解析 xlsx 工作簿为 DoclingDocument：每个 sheet 依次产出 页面与 sheet 分组，sheet 内按 BFS 连通区域切分表格，并保留图片、 图表与批注。隐藏 sheet 使用 invisible 层；空内容不视为错误。

func (*DoclingDocument) AddCheckbox 

func (d *DoclingDocument) AddCheckbox(checked bool, text string, prov []ProvenanceItem, parent *RefItem) RefItem

AddCheckbox 追加复选框（选中/未选中），并清除文本中的 ☐☑☒ 前缀符号。

func (*DoclingDocument) AddCode 

func (d *DoclingDocument) AddCode(text, language string, prov []ProvenanceItem, parent *RefItem) RefItem

AddCode 追加代码块（label=code，可携带语言标记）。

func (*DoclingDocument) AddFormula 

func (d *DoclingDocument) AddFormula(text string, prov []ProvenanceItem, parent *RefItem) RefItem

AddFormula 追加公式（label=formula，text 存 LaTeX 源码）。

func (*DoclingDocument) AddHeading 

func (d *DoclingDocument) AddHeading(level int64, text string, prov []ProvenanceItem, parent *RefItem) RefItem

AddHeading 追加章节标题（label=section_header，level 从 1 起）。

func (*DoclingDocument) AddListGroup 

func (d *DoclingDocument) AddListGroup(name string, parent *RefItem) RefItem

AddListGroup 追加列表分组（label=list），返回分组引用。

func (*DoclingDocument) AddListItem 

func (d *DoclingDocument) AddListItem(group RefItem, text string, enumerated bool, marker string, prov []ProvenanceItem) RefItem

AddListItem 向列表分组追加列表项（label=list_item）。

func (*DoclingDocument) AddPage 

func (d *DoclingDocument) AddPage(pageNo int64, width, height float64)

addPage 登记页面尺寸（页号从 1 起）。

func (*DoclingDocument) AddPicture 

func (d *DoclingDocument) AddPicture(img *ImageRef, prov []ProvenanceItem, parent *RefItem) RefItem

AddPicture 追加图片元素。

func (*DoclingDocument) AddSectionGroup 

func (d *DoclingDocument) AddSectionGroup(name string, parent *RefItem) RefItem

AddSectionGroup 追加隐式 section 分组（标题层级树中用于跳级补位， 对齐 msword_backend 的 SECTION group 与 html_backend 的跳级行为）。

func (*DoclingDocument) AddTable 

func (d *DoclingDocument) AddTable(cells []DoclingTableCell, numRows, numCols int64, prov []ProvenanceItem, parent *RefItem) RefItem

AddTable 追加表格元素（cells 的行列偏移须 start 闭 end 开）。

func (*DoclingDocument) AddText 

func (d *DoclingDocument) AddText(label DocItemLabel, text string, prov []ProvenanceItem, parent *RefItem) RefItem

AddText 追加文本元素并挂到 parent（nil 则挂 body），返回元素自身引用。

func (*DoclingDocument) AddTitle 

func (d *DoclingDocument) AddTitle(text string, prov []ProvenanceItem, parent *RefItem) RefItem

AddTitle 追加文档主标题（label=title）。

func (DoclingDocument) MarshalJSON 

func (d DoclingDocument) MarshalJSON() ([]byte, error)

MarshalJSON 在输出前复制并规范化文档，确保旧字段只读兼容且不修改调用方对象。

func (*DoclingDocument) SortPageNos 

func (d *DoclingDocument) SortPageNos() []int64

SortPageNos 返回升序页号列表（pages 键为字符串化数字）。

func (*DoclingDocument) Text 

func (d *DoclingDocument) Text() string

Text 聚合全文档纯文本（按阅读顺序拼接各元素文本）， 与 ToContentList 后 JoinItemTexts 的结果一致，供调用方取得兜底纯文本。

func (*DoclingDocument) ToHTML 

func (d *DoclingDocument) ToHTML() string

ToHTML 导出 HTML 的方法形式入口（等价 ExportHTML）。

func (*DoclingDocument) ToHTMLWithOptions 

func (d *DoclingDocument) ToHTMLWithOptions(options ExportOptions) string

ToHTMLWithOptions 按指定内容层导出 HTML。

func (*DoclingDocument) ToMarkdown 

func (d *DoclingDocument) ToMarkdown() string

ToMarkdown 把文档还原为 Markdown 的方法形式入口（等价 ExportMarkdown）， 与 ToHTML/ToContentList 一同构成导出方法族。

func (*DoclingDocument) ToMarkdownWithOptions 

func (d *DoclingDocument) ToMarkdownWithOptions(options ExportOptions) string

ToMarkdownWithOptions 按指定内容层导出 Markdown。

func (*DoclingDocument) UnmarshalJSON 

func (d *DoclingDocument) UnmarshalJSON(data []byte) error

UnmarshalJSON 兼容读取旧版顶层 meta；该内部元数据不会再写入 Docling JSON。

type DoclingPageInfo 

type DoclingPageInfo struct {
	PageIdx int64   `json:"page_idx"`
	Width   float64 `json:"width"`
	Height  float64 `json:"height"`
}

DoclingPageInfo 单页尺寸信息（页号从 1 起）。

type DoclingServeResult 

type DoclingServeResult struct {
	// Pages 页尺寸摘要（页号从 1 起）
	Pages []DoclingPageInfo
	// ProcessingTime 服务端处理耗时（秒）
	ProcessingTime float64
	// RawJSON docling-serve 返回的原始 DoclingDocument JSON（可二次解析或归档）
	RawJSON json.RawMessage
}

DoclingServeResult docling-serve 解析结果摘要：除 DoclingDocument 外的派生信息。

type DoclingServiceOptions 

type DoclingServiceOptions struct {
	// ServiceURL docling-serve 服务地址（如 http://docling-parser:5001），必填
	ServiceURL string
	// Timeout 单次 HTTP 请求超时，<=0 时默认 120s（文档解析较慢）
	Timeout time.Duration
	// Retry 失败重试次数，<0 视为 0
	Retry int
	// ImageExportMode 图片导出模式：placeholder（默认）/ embedded / referenced
	ImageExportMode string
	// DoOCR 是否启用服务端 OCR，默认 true
	DoOCR *bool
	// TableMode 表格解析模式：fast（默认）/ accurate
	TableMode string
}

DoclingServiceOptions docling-serve HTTP 服务连接与请求参数。

type DoclingTableCell 

type DoclingTableCell struct {
	BBox              *DoclingBBox `json:"bbox,omitempty"`
	RowSpan           int64        `json:"row_span"`
	ColSpan           int64        `json:"col_span"`
	StartRowOffsetIdx int64        `json:"start_row_offset_idx"`
	EndRowOffsetIdx   int64        `json:"end_row_offset_idx"`
	StartColOffsetIdx int64        `json:"start_col_offset_idx"`
	EndColOffsetIdx   int64        `json:"end_col_offset_idx"`
	Text              string       `json:"text"`
	ColumnHeader      bool         `json:"column_header"`
	RowHeader         bool         `json:"row_header"`
	RowSection        bool         `json:"row_section"`
	Fillable          bool         `json:"fillable"`
	Ref               *RefItem     `json:"ref,omitempty"`
}

DoclingTableCell 表格单元格；行列偏移 start 闭 end 开（end=普通单元格 start+1）。

func (DoclingTableCell) MarshalJSON 

func (c DoclingTableCell) MarshalJSON() ([]byte, error)

MarshalJSON 为旧表格单元格补齐官方默认跨度。

type DocumentOrigin 

type DocumentOrigin struct {
	Mimetype   string `json:"mimetype"`
	BinaryHash uint64 `json:"binary_hash"`
	Filename   string `json:"filename"`
	URI        string `json:"uri,omitempty"`
}

DocumentOrigin 文档来源信息（mimetype/文件名等）。

func (*DocumentOrigin) UnmarshalJSON 

func (o *DocumentOrigin) UnmarshalJSON(data []byte) error

UnmarshalJSON 兼容 Docling 接受的十六进制字符串 binary_hash 输入。

type ExportOptions 

type ExportOptions struct {
	Layers []ContentLayer
}

ExportOptions 控制文档导出范围；Layers 为空时只导出正文层。

type FineRef 

type FineRef struct {
	RefItem
	Range *[2]int64 `json:"range,omitempty"`
}

FineRef 是可选携带字符区间的细粒度引用，用于评论等注释关系。

func (FineRef) MarshalJSON 

func (r FineRef) MarshalJSON() ([]byte, error)

MarshalJSON 输出 Docling 的 {$ref, range?} 形态。

func (*FineRef) UnmarshalJSON 

func (r *FineRef) UnmarshalJSON(data []byte) error

UnmarshalJSON 解析 Docling 的细粒度引用。

type Formatting 

type Formatting struct {
	Bold          bool           `json:"bold"`
	Italic        bool           `json:"italic"`
	Underline     bool           `json:"underline"`
	Strikethrough bool           `json:"strikethrough"`
	Script        ScriptPosition `json:"script"`
}

Formatting 表示单个文本元素的统一样式。

func (Formatting) MarshalJSON 

func (f Formatting) MarshalJSON() ([]byte, error)

MarshalJSON 为旧对象补齐官方默认 baseline。

type GroupItem 

type GroupItem struct {
	SelfRef      string       `json:"self_ref"`
	Parent       *RefItem     `json:"parent,omitempty"`
	Children     []RefItem    `json:"children"`
	ContentLayer ContentLayer `json:"content_layer"`
	Meta         BaseMeta     `json:"meta,omitempty"`
	Label        GroupLabel   `json:"label"`
	Name         string       `json:"name"`
}

GroupItem groups[] 分组节点：标题隐式 section、列表 group、sheet/slide 组等。

type GroupLabel 

type GroupLabel string

GroupLabel 分组节点类型，对齐 docling-core GroupLabel 常用子集。 

const (
	GroupLabelUnspecified    GroupLabel = "unspecified"
	GroupLabelList           GroupLabel = "list"
	GroupLabelOrderedList    GroupLabel = "ordered_list" // 仅兼容官方已弃用取值
	GroupLabelChapter        GroupLabel = "chapter"
	GroupLabelSection        GroupLabel = "section"
	GroupLabelSheet          GroupLabel = "sheet"
	GroupLabelSlide          GroupLabel = "slide"
	GroupLabelFormArea       GroupLabel = "form_area"
	GroupLabelKeyValueArea   GroupLabel = "key_value_area"
	GroupLabelCommentSection GroupLabel = "comment_section"
	GroupLabelInline         GroupLabel = "inline"
	GroupLabelPictureArea    GroupLabel = "picture_area"
)

GroupLabel 常用取值。

type HybridChunkOptions 

type HybridChunkOptions struct {
	// MaxTokens 是每个“标题上下文 + 正文”的 token 上限；非正数使用 512。
	MaxTokens int
	// CountTokens 返回文本的 token 数，应与下游 embedding 模型一致；nil 时按 rune 数估算。
	CountTokens func(text string) int
	// DisablePeerMerge 关闭同标题下相邻小块的贪心合并。
	DisablePeerMerge bool
	// DisableTableHeaderRepeat 关闭大表切分后的 Markdown 表头重复。
	DisableTableHeaderRepeat bool
}

HybridChunkOptions 控制 token 感知分块。

type ImageRef 

type ImageRef struct {
	Mimetype string     `json:"mimetype"`
	Dpi      int64      `json:"dpi"`
	Size     *ImageSize `json:"size"`
	URI      string     `json:"uri"`
}

ImageRef 图片资产引用：内嵌为 base64 data URI，也可为 http(s)/路径引用。

func (ImageRef) MarshalJSON 

func (r ImageRef) MarshalJSON() ([]byte, error)

MarshalJSON 为旧图片引用补齐官方必需的 size 对象。

type ImageSize 

type ImageSize struct {
	Width  float64 `json:"width"`
	Height float64 `json:"height"`
}

ImageSize 图片像素尺寸。

type Item 

type Item struct {
	Type          ItemType `json:"type"`
	PageIdx       int64    `json:"page_idx,omitempty"`
	Text          string   `json:"text,omitempty"`           // text / equation 的文本或 LaTeX
	TextLevel     int64    `json:"text_level,omitempty"`     // text 标题层级（0=正文，1=一级标题，以此类推）
	Label         string   `json:"label,omitempty"`          // 细粒度元素分类，page_header/page_footer/document_index/list_item/code 等非通用 label 时填充，供下游过滤/分流
	LaTeX         string   `json:"latex,omitempty"`          // equation 的 LaTeX 源码
	ImgPath       string   `json:"img_path,omitempty"`       // image 资源路径（对象存储 key 或相对路径）
	ImageCaption  string   `json:"image_caption,omitempty"`  // image 标题
	ImageFootnote string   `json:"image_footnote,omitempty"` // image 脚注
	TableBody     string   `json:"table_body,omitempty"`     // table，Markdown 格式
	TableCaption  string   `json:"table_caption,omitempty"`  // table 标题
	TableFootnote string   `json:"table_footnote,omitempty"` // table 脚注
	SectionPath   []string `json:"_section_path,omitempty"`  // 章节路径，如 ["1 引言", "1.1 背景"]
	BBox          *BBox    `json:"_bbox,omitempty"`          // 页面内边界框
	OrderIndex    int64    `json:"_order_index,omitempty"`   // 阅读顺序序号
	Source        string   `json:"source,omitempty"`         // 解析器来源（golight/docling），供下游分流
}

Item 是 content_list 中的单个元素，覆盖文本、图片、表格、公式等模态。 字段按需填充：文本类型填 Text；图片类型填 ImgPath/ImageCaption； 表格类型填 TableBody/TableCaption；公式类型填 LaTeX。 JSON 标签为 content_list 持久化协议，变更需保证向后兼容。

func ToContentList 

func ToContentList(doc *DoclingDocument, source string) []Item

ToContentList 把 DoclingDocument 简化为扁平 content_list：先按 body 树先序 遍历，再从 furniture 树兼容追加页眉页脚；HTML title 等其他家具项保持不进入 知识正文。source 写入每个 Item.Source，doc/Body 为空时返回 nil。

type ItemType 

type ItemType string

ItemType 定义 content_list 中元素的模态类型。 

const (
	// ItemTypeText 普通文本段落或标题
	ItemTypeText ItemType = "text"
	// ItemTypeImage 图片及其说明
	ItemTypeImage ItemType = "image"
	// ItemTypeTable 表格及其说明
	ItemTypeTable ItemType = "table"
	// ItemTypeEquation 公式（LaTeX 形式）
	ItemTypeEquation ItemType = "equation"
	// ItemTypeGeneric 其他通用内容块
	ItemTypeGeneric ItemType = "generic"
)

type OCRHook 

type OCRHook func(request OCRRequest) (string, error)

OCRHook 是带完整上下文的新 OCR 钩子；与 PageOCRHook 同时配置时优先使用。

type OCRRequest 

type OCRRequest struct {
	PageNo             int64  // PageNo 是从 1 开始的页号；独立图片固定为 1。
	MIMEType           string // MIMEType 是原文件 MIME。
	Filename           string // Filename 是原文件名。
	Data               []byte // Data 是原始文件字节，作为现有调用方兼容字段保留。
	PageData           []byte // PageData 是 Docling 安全抽取的单页 PDF；图片输入为空。
	ExistingText       string // ExistingText 是 Go Docling 或 Poppler 已提取的页面文本。
	Attempt            int    // Attempt 是从 1 开始的本页调用次数。
	ValidationFeedback string // ValidationFeedback 是前一次失败的纠错提示，首次为空。
}

OCRRequest 描述一次页级或图片 OCR 请求，向实现方提供文件上下文与当前 规则解析文本，便于实现方选择正确输入方式并做质量比较。

type PDFLimits added in v1.2.0 

type PDFLimits struct {
	MaxFileBytes int64 // MaxFileBytes 是原始 PDF 最大字节数。
	MaxPages     int   // MaxPages 是最大页数。
}

PDFLimits 是调用方可覆盖的 PDF 高层资源限制。非正值使用安全默认值， 不表示无限制；pdfcpu 的底层对象、流、图片和递归限制由 Docling 固定维护。

func DefaultPDFLimits added in v1.2.0 

func DefaultPDFLimits() PDFLimits

DefaultPDFLimits 返回 Docling 的默认 PDF 资源限制。

type PDFOptions 

type PDFOptions struct {
	// Limits 是 PDF 文件与页数限制；非正字段使用 DefaultPDFLimits。
	Limits PDFLimits
	// VisualHook 是复杂页面的结构化视觉钩子；nil 时完全保持纯 Go 路径。
	VisualHook PDFVisualHook
	// VisualAlways 要求对每个有效页尝试结构化视觉；主要用于调用方已自行
	// 控制页范围或图像型表格。默认仅对质量评估命中的疑难页调用。
	VisualAlways bool
	// MaxVisualPages 限制单文档最多调用的视觉页数；0 表示不额外限制。
	MaxVisualPages int
	// OCRHook 是新版 OCR 钩子，优先于 PageOCRHook。
	OCRHook OCRHook
	// PageOCRHook 扫描页/高乱码页识别钩子；nil 时维持纯文本兜底行为。
	PageOCRHook PageOCRHook
	// MIMEType 是原文件 MIME；为空时 PDF 默认 application/pdf。
	MIMEType string
	// Filename 是原文件名，供模型侧保留输入上下文。
	Filename string
	// DisablePopplerFallback 禁用 poppler（pdftotext -bbox-layout）降级提取。
	// 默认（false）启用：ledongthuc 提取为空或乱码超限时自动降级，环境缺失
	// pdftotext 时自动跳过（LookPath 检测，无副作用）。
	DisablePopplerFallback bool
	// DisableEmbeddedImageExtraction 禁用 PDF Image XObject 像素解码；页面
	// 图片几何仍参与质量评估和视觉路由。默认启用纯 Go 图片资产提取。
	DisableEmbeddedImageExtraction bool
	// GarbageThreshold 页乱码率超过该值时触发 hook 重识别；
	// 0（零值）= 仅对无字符内容的扫描兜底页触发。
	GarbageThreshold float64
}

PDFOptions PDF 解析可选能力。

type PDFPageQuality 

type PDFPageQuality struct {
	Score              float64  `json:"score"`
	GarbageRatio       float64  `json:"garbage_ratio"`
	TextRunes          int      `json:"text_runes"`
	WordCount          int      `json:"word_count"`
	LineCount          int      `json:"line_count"`
	CandidateTableRows int      `json:"candidate_table_rows"`
	DetectedTables     int      `json:"detected_tables"`
	FormulaDensity     float64  `json:"formula_density"`
	ColumnConfidence   float64  `json:"column_confidence"`
	ImageCount         int      `json:"image_count"`        // ImageCount 是实际绘制的图片次数。
	LargeImageCount    int      `json:"large_image_count"`  // LargeImageCount 是达到视觉路由阈值的图片数。
	ImageCoverage      float64  `json:"image_coverage"`     // ImageCoverage 是图片 bbox 并集占页面面积的比例。
	MaxImageCoverage   float64  `json:"max_image_coverage"` // MaxImageCoverage 是单张图片的最大页面覆盖率。
	PageRotation       int      `json:"page_rotation"`      // PageRotation 是 PDF 页顺时针旋转角度。
	UserUnit           float64  `json:"user_unit"`          // UserUnit 是 PDF 用户坐标的物理缩放倍率。
	NeedsVisual        bool     `json:"needs_visual"`
	Reasons            []string `json:"reasons"`
}

PDFPageQuality 保存纯 Go 页面提取的质量信号；Score 越高越可靠。

type PDFResourceLimitError added in v1.2.0 

type PDFResourceLimitError struct {
	Resource string // Resource 是超限资源名称。
	Actual   int64  // Actual 是实际值；未知时为 0。
	Limit    int64  // Limit 是限制值；未知时为 0。
	Cause    error  // Cause 是底层校验错误；直接检查输入时为空。
}

PDFResourceLimitError 描述具体超限资源。Actual 与 Limit 可用于调用方 生成稳定提示；底层 pdfcpu 无法暴露精确数值时保留 Cause 的原始错误。

func (*PDFResourceLimitError) Error added in v1.2.0 

func (e *PDFResourceLimitError) Error() string

Error 返回适合日志和最终用户提示的超限说明。

func (*PDFResourceLimitError) Unwrap added in v1.2.0 

func (e *PDFResourceLimitError) Unwrap() []error

Unwrap 同时暴露稳定哨兵和底层原因，便于 errors.Is 分类处理。

type PDFVisualHook 

type PDFVisualHook func(request PDFVisualRequest) (PDFVisualResult, error)

PDFVisualHook 对疑难页面执行结构化视觉识别。

type PDFVisualImage 

type PDFVisualImage struct {
	Image *ImageRef    `json:"image"`
	BBox  *DoclingBBox `json:"bbox"`
}

PDFVisualImage 描述页面内一个已由纯 Go 解码的图片资产；Image 保存像素 引用，BBox 保存该资源在 PDF 页面上的实际绘制区域。

type PDFVisualItem 

type PDFVisualItem struct {
	Label      DocItemLabel `json:"label"`
	Text       string       `json:"text,omitempty"`
	Level      int64        `json:"level,omitempty"`
	BBox       *DoclingBBox `json:"bbox"`
	Confidence float64      `json:"confidence"`
	TableData  *TableData   `json:"table_data,omitempty"`
	Enumerated bool         `json:"enumerated,omitempty"`
	Marker     string       `json:"marker,omitempty"`
}

PDFVisualItem 是模型返回的单个版面对象。

type PDFVisualRequest 

type PDFVisualRequest struct {
	PageNo             int64            `json:"page_no"`                       // PageNo 是从 1 开始的页号。
	MIMEType           string           `json:"mimetype"`                      // MIMEType 是原文件 MIME。
	Filename           string           `json:"filename"`                      // Filename 是原文件名。
	Data               []byte           `json:"-"`                             // Data 是原始 PDF 字节。
	PageData           []byte           `json:"-"`                             // PageData 是 Docling 安全抽取的单页 PDF。
	Width              float64          `json:"width"`                         // Width 是页面宽度，单位为 point。
	Height             float64          `json:"height"`                        // Height 是页面高度，单位为 point。
	ExistingText       string           `json:"existing_text"`                 // ExistingText 是现有规则文本。
	Quality            PDFPageQuality   `json:"quality"`                       // Quality 是纯 Go 页面质量信号。
	EmbeddedImages     []PDFVisualImage `json:"embedded_images,omitempty"`     // EmbeddedImages 是已解码图片及其页面位置。
	Prompt             string           `json:"prompt"`                        // Prompt 是严格结构化输出提示词。
	Attempt            int              `json:"attempt"`                       // Attempt 是从 1 开始的调用次数。
	ValidationFeedback string           `json:"validation_feedback,omitempty"` // ValidationFeedback 是前一次失败原因。
}

PDFVisualRequest 描述一次页级结构化视觉请求。

type PDFVisualResult 

type PDFVisualResult struct {
	Items []PDFVisualItem `json:"items"`
}

PDFVisualResult 是结构化视觉钩子的返回协议。

type PageItem 

type PageItem struct {
	Size   *ImageSize `json:"size"`
	PageNo int64      `json:"page_no"`
	Image  *ImageRef  `json:"image,omitempty"`
}

PageItem 单页信息；pages 以字符串化页号为键。

func (PageItem) MarshalJSON 

func (p PageItem) MarshalJSON() ([]byte, error)

MarshalJSON 为旧页面记录补齐官方必需的 size 对象。

func (*PageItem) UnmarshalJSON 

func (p *PageItem) UnmarshalJSON(data []byte) error

UnmarshalJSON 兼容旧版 docling-serve 的平铺页结构 {"width":..,"height":..} （新版为 {"size":{"width","height"},"page_no":N}）。

type PageOCRHook 

type PageOCRHook func(pageNo int64, pdfBytes []byte) (string, error)

PageOCRHook 扫描页/高乱码页识别兼容钩子：pageNo 从 1 起，pdfBytes 为 原始 PDF 全量字节。新调用方应优先使用 OCRHook 的安全单页 PageData； 本钩子返回该页识别文本（推荐 Markdown，可携带标题层级/表格/列表）， 返回空文本或错误时该页维持原有兜底行为。

type ParseOptions 

type ParseOptions struct {
	// OriginURI 指定文档来源 URI；为空时不输出 origin.uri。
	OriginURI string
	// PDFLimits 指定 PDF 文件与页数限制；非正字段使用安全默认值。
	PDFLimits PDFLimits
	// OCRHook 是带完整文件上下文的新 OCR 钩子，优先于 PageOCRHook。
	OCRHook OCRHook
	// PageOCRHook 是旧版页级 OCR 钩子，供 PDF 与图片解析复用。
	PageOCRHook PageOCRHook
	// PDFVisualHook 是 PDF 疑难页面的结构化视觉钩子。
	PDFVisualHook PDFVisualHook
	// PDFVisualAlways 强制所有 PDF 页尝试视觉解析；默认仅按质量信号触发。
	PDFVisualAlways bool
	// MaxPDFVisualPages 限制单文档最多尝试的视觉页数；0 表示不额外限制。
	MaxPDFVisualPages int
	// DisablePopplerFallback 禁用 PDF 的可选 Poppler 降级提取。
	DisablePopplerFallback bool
	// DisablePDFEmbeddedImageExtraction 禁用 PDF 内嵌图片资产的纯 Go 提取。
	DisablePDFEmbeddedImageExtraction bool
	// GarbageThreshold 指定 PDF 文本乱码率触发 OCR 的阈值。
	GarbageThreshold float64
}

ParseOptions 是统一解析入口的可选配置；PageOCRHook 作为兼容钩子保留。

type PictureClassificationMetaField 

type PictureClassificationMetaField struct {
	Predictions []PictureClassificationPrediction `json:"predictions"`
}

PictureClassificationMetaField 保存图片分类预测列表。

type PictureClassificationPrediction 

type PictureClassificationPrediction struct {
	PredictionMeta
	ClassName string `json:"class_name"`
}

PictureClassificationPrediction 表示图片分类的一项预测。

type PictureItem 

type PictureItem struct {
	SelfRef      string            `json:"self_ref"`
	Parent       *RefItem          `json:"parent,omitempty"`
	Children     []RefItem         `json:"children"`
	ContentLayer ContentLayer      `json:"content_layer"`
	Meta         *PictureMeta      `json:"meta,omitempty"`
	Label        DocItemLabel      `json:"label"`
	Prov         []ProvenanceItem  `json:"prov"`
	Source       []json.RawMessage `json:"source,omitempty"`
	Comments     []FineRef         `json:"comments,omitempty"`
	Captions     []RefItem         `json:"captions"`
	References   []RefItem         `json:"references"`
	Footnotes    []RefItem         `json:"footnotes"`
	Annotations  []json.RawMessage `json:"annotations"`
	Caption      string            `json:"-"` // 旧版字符串 caption，仅兼容读取
	Image        *ImageRef         `json:"image,omitempty"`
}

PictureItem pictures[] 图片元素（Go 各后端暂不产出，结构先行）。

func (*PictureItem) UnmarshalJSON 

func (p *PictureItem) UnmarshalJSON(data []byte) error

UnmarshalJSON 兼容旧版字符串 caption，并保留官方图片元数据。

type PictureMeta 

type PictureMeta struct {
	Classification *PictureClassificationMetaField `json:"classification,omitempty"`
	TabularChart   *TabularChartMetaField          `json:"tabular_chart,omitempty"`
	Description    json.RawMessage                 `json:"description,omitempty"`
	Molecule       json.RawMessage                 `json:"molecule,omitempty"`
	Code           json.RawMessage                 `json:"code,omitempty"`
	Extra          map[string]json.RawMessage      `json:"-"`
}

PictureMeta 保存图片专属官方元数据，并无损保留命名空间扩展字段。

func (PictureMeta) MarshalJSON 

func (m PictureMeta) MarshalJSON() ([]byte, error)

MarshalJSON 合并标准字段与命名空间扩展字段。

func (*PictureMeta) UnmarshalJSON 

func (m *PictureMeta) UnmarshalJSON(data []byte) error

UnmarshalJSON 解析标准图片元数据并保存未知扩展字段。

type PredictionMeta 

type PredictionMeta struct {
	Confidence *float64 `json:"confidence,omitempty"`
	CreatedBy  string   `json:"created_by,omitempty"`
}

PredictionMeta 是带可选置信度和来源的预测元数据基类。

type ProvenanceItem 

type ProvenanceItem struct {
	PageNo   int64        `json:"page_no"`
	BBox     *DoclingBBox `json:"bbox"`
	CharSpan [2]int64     `json:"charspan"`
}

ProvenanceItem 元素来源证据：页号 + 页内 bbox + 字符偏移区间（0 起，[start,end)）。 一个元素跨行/跨页时可有多段。

func (ProvenanceItem) MarshalJSON 

func (p ProvenanceItem) MarshalJSON() ([]byte, error)

MarshalJSON 为旧来源记录补齐官方必需的 bbox 对象。

type RefItem 

type RefItem struct {
	Kind docRefKind `json:"-"`
	Idx  int64      `json:"-"`
}

RefItem 文档树内引用，JSON 形态为 {"$ref": "#/texts/0"}；body 恒为 "#/body"。

func (RefItem) MarshalJSON 

func (r RefItem) MarshalJSON() ([]byte, error)

MarshalJSON 序列化为 {"$ref": "#/texts/0"} 形态。

func (RefItem) String 

func (r RefItem) String() string

String 输出 cref 字符串形式（#/texts/0），便于日志与调试。

func (*RefItem) UnmarshalJSON 

func (r *RefItem) UnmarshalJSON(data []byte) error

UnmarshalJSON 解析 "#/texts/0" 形式的引用。

type ScriptPosition 

type ScriptPosition string

ScriptPosition 表示文本相对基线的位置。 

const (
	ScriptBaseline ScriptPosition = "baseline"
	ScriptSub      ScriptPosition = "sub"
	ScriptSuper    ScriptPosition = "super"
)

ScriptPosition 取值对齐 docling-core Script。

type TableData 

type TableData struct {
	TableCells  []DoclingTableCell `json:"table_cells"`
	NumRows     int64              `json:"num_rows"`
	NumCols     int64              `json:"num_cols"`
	Orientation TableOrientation   `json:"orientation"`
}

TableData 表格数据；grid 为序列化时由 table_cells 按 offset 现算的 computed 字段。

func (TableData) MarshalJSON 

func (t TableData) MarshalJSON() ([]byte, error)

MarshalJSON 输出 table_cells/num_rows/num_cols 并现算 grid 矩阵， 对齐 docling-core TableData.grid computed field 的序列化行为。

type TableItem 

type TableItem struct {
	SelfRef      string            `json:"self_ref"`
	Parent       *RefItem          `json:"parent,omitempty"`
	Children     []RefItem         `json:"children"`
	ContentLayer ContentLayer      `json:"content_layer"`
	Meta         BaseMeta          `json:"meta,omitempty"`
	Label        DocItemLabel      `json:"label"`
	Prov         []ProvenanceItem  `json:"prov"`
	Source       []json.RawMessage `json:"source,omitempty"`
	Comments     []FineRef         `json:"comments,omitempty"`
	Captions     []RefItem         `json:"captions"`
	References   []RefItem         `json:"references"`
	Footnotes    []RefItem         `json:"footnotes"`
	Image        *ImageRef         `json:"image,omitempty"`
	Annotations  []json.RawMessage `json:"annotations"`
	Caption      string            `json:"-"` // 旧版字符串 caption，仅兼容读取
	Data         *TableData        `json:"data"`
}

TableItem tables[] 表格元素。

func (*TableItem) UnmarshalJSON 

func (t *TableItem) UnmarshalJSON(data []byte) error

UnmarshalJSON 兼容旧版字符串 caption。

type TableOrientation 

type TableOrientation string

TableOrientation 表示表格在页面中的逆时针旋转角度。 

const (
	TableOrientation0   TableOrientation = "rot_0"
	TableOrientation90  TableOrientation = "rot_90"
	TableOrientation180 TableOrientation = "rot_180"
	TableOrientation270 TableOrientation = "rot_270"
)

TableOrientation 取值对齐 docling-core Orientation。

type TabularChartMetaField 

type TabularChartMetaField struct {
	PredictionMeta
	Title     string     `json:"title,omitempty"`
	ChartData *TableData `json:"chart_data"`
}

TabularChartMetaField 保存图表标题和表格化数据。

type TextItem 

type TextItem struct {
	SelfRef      string            `json:"self_ref"`
	Parent       *RefItem          `json:"parent,omitempty"`
	Children     []RefItem         `json:"children"`
	ContentLayer ContentLayer      `json:"content_layer"`
	Meta         BaseMeta          `json:"meta,omitempty"`
	Label        DocItemLabel      `json:"label"`
	Prov         []ProvenanceItem  `json:"prov"`
	Source       []json.RawMessage `json:"source,omitempty"`
	Comments     []FineRef         `json:"comments,omitempty"`
	Orig         string            `json:"orig"`
	Text         string            `json:"text"`
	// —— 以下为按 label 分派的专属字段 ——
	TextLevel    int64       `json:"level,omitempty"`         // section_header：标题层级（1 起）
	Enumerated   *bool       `json:"enumerated,omitempty"`    // list_item：是否有序
	Marker       string      `json:"marker,omitempty"`        // list_item：序号标记（"1."/"·"）
	CodeLanguage string      `json:"code_language,omitempty"` // code：代码语言
	Hyperlink    string      `json:"hyperlink,omitempty"`     // 行内链接目标
	Formatting   *Formatting `json:"formatting,omitempty"`    // 统一文本样式
	Latex        string      `json:"-"`                       // formula：旧版 schema 的独立 latex 字段（仅兼容读取）
	Captions     []RefItem   `json:"captions,omitempty"`      // code：标题说明引用
	References   []RefItem   `json:"references,omitempty"`    // code：相关内容引用
	Footnotes    []RefItem   `json:"footnotes,omitempty"`     // code：脚注引用
	Image        *ImageRef   `json:"image,omitempty"`         // code：可选渲染图
}

TextItem texts[] 元素：单结构体覆盖 title/section_header/text/paragraph/ list_item/code/formula/checkbox 等八类 Union，专属字段按 label 填充。

func (TextItem) MarshalJSON 

func (t TextItem) MarshalJSON() ([]byte, error)

MarshalJSON 为各文本 Union 补齐官方 label 专属默认字段。

func (*TextItem) UnmarshalJSON 

func (t *TextItem) UnmarshalJSON(data []byte) error

UnmarshalJSON 兼容旧 text_level/latex，同时以官方 level/text 作为规范字段。

Source Files

View all Source files

Directories

Path Synopsis
Package cli 导出 docling CLI 的通用输出辅助：Outline 生成渐进式披露的 结构地图（标题树/表格/图片/分组），RenderItemsMarkdown 把过滤后的条目 渲染为简化 Markdown，FilterItems 按章节/分组过滤，ParseLayers 解析内容层。
 Package cli 导出 docling CLI 的通用输出辅助：Outline 生成渐进式披露的 结构地图（标题树/表格/图片/分组），RenderItemsMarkdown 把过滤后的条目 渲染为简化 Markdown，FilterItems 按章节/分组过滤，ParseLayers 解析内容层。
cmd
docling command
docling CLI：把文档解析为 outline / markdown / content-list / Docling JSON 四种形态。
 docling CLI：把文档解析为 outline / markdown / content-list / Docling JSON 四种形态。
internal
ooxml
strict.go 实现 DOCX/PPTX/XLSX 共用的 Strict OOXML 命名空间 归一化。
 strict.go 实现 DOCX/PPTX/XLSX 共用的 Strict OOXML 命名空间 归一化。
pdfenc
codecs.go 提供 PDF 内嵌图片的字节级编解码：JPEG 2000（JPXDecode）与 JBIG2（JBIG2Decode）的纯 Go 解码，以及软蒙版的 alpha 展开与合成。
 codecs.go 提供 PDF 内嵌图片的字节级编解码：JPEG 2000（JPXDecode）与 JBIG2（JBIG2Decode）的纯 Go 解码，以及软蒙版的 alpha 展开与合成。
hook.go 把 LLMClient 适配为 docling 的 OCRHook 与 PDFVisualHook：负责单页 PageData 的 data URI 组装、提示词构建与视觉结果 JSON 解码；调用预算（页数上限） 在钩子闭包内计数，超限后返回空结果交还 docling 内置的纯 Go 兜底路径。
 hook.go 把 LLMClient 适配为 docling 的 OCRHook 与 PDFVisualHook：负责单页 PageData 的 data URI 组装、提示词构建与视觉结果 JSON 解码；调用预算（页数上限） 在钩子闭包内计数，超限后返回空结果交还 docling 内置的纯 Go 兜底路径。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.