Docling 转换

在为大语言模型和 AI 应用准备内容时，一项重要任务是文档解析与转换。文档通常以 PDF、DOCX、HTML 或其他格式存在，而这些格式不易被 LLM 或下游处理系统直接使用。将这些文档转换为干净、统一的结构化文本表示，对于有效的内容分析和信息提取至关重要。

Debezium 提供了一个内置功能，可借助 Docling——一个强大的文档理解框架——将文档字段转换为干净、统一、格式一致的结构化文本。Docling 能够解析多种文档格式，并将其转换为 HTML、Markdown 或纯文本等结构化输出格式，使内容更便于 LLM 及其他 AI 应用使用。

Debezium 可以使用单条消息转换（SMT）来执行 Docling 转换。该转换会连接到 Docling Serve API，由其处理文档并返回结构化输出。

	Docling 转换需要 Java 21 或更高版本。

行为

Docling 转换以原始事件记录中的某个特定字段作为输入，该字段包含文档内容或文档的 URL。SMT 会将此输入发送到已配置的 Docling Serve API 进行转换。生成的结构化文档随后会追加到记录中，也可以替换整条记录。使用追加模式时，原始源字段会被保留。

源字段必须是字符串字段。使用 text 输入源模式时，该字段应直接包含文档内容；使用 link 输入源模式时，该字段应包含文档的 URL。

结果记录中的 Docling 字段是一个结构化对象，其模式如下：

type：输出格式类型（html、markdown 或 text）
content：转换后的文档内容

记录中 Docling 字段的模式类型为 io.debezium.ai.docling.DoclingDocument。

源字段和 Docling 字段的规范都支持嵌套结构，例如 after.document 或 after.document_parsed。

配置

要配置连接器以使用 Docling 转换，请在连接器配置中添加以下内容：

transforms=docling
transforms.docling.type=io.debezium.ai.docling.FieldToDocling

您必须指定源字段、Docling Serve URL、输入源类型以及输入格式：

transforms.docling.field.source=after.document
transforms.docling.serve.url=http://localhost:5001
transforms.docling.input.source=text
transforms.docling.input.format=pdf

可选地，你可以为 Docling 的输出指定目标字段。若未指定，记录值中将仅包含 Docling 文档本身：

transforms.docling.field.docling=after.document_parsed

你还可以配置输出格式以及是否包含图片：

transforms.docling.output.format=markdown
transforms.docling.include.images=true

以下示例展示了将 PDF 文档转换为 Markdown 的完整配置：

transforms=docling
transforms.docling.type=io.debezium.ai.docling.FieldToDocling
transforms.docling.field.source=after.document
transforms.docling.field.docling=after.document_parsed
transforms.docling.serve.url=http://localhost:5001
transforms.docling.input.source=text
transforms.docling.input.format=pdf
transforms.docling.output.format=markdown
transforms.docling.include.images=true

配置选项

表 1. Docling SMT 配置选项说明

选项	默认值	说明
`field.source`	无默认值	指定源记录中作为 Docling 转换输入的字段。指定字段的数据类型必须为 `string`。当 `input.source` 设置为 `text` 时，该字段应包含文档内容；当 `input.source` 设置为 `link` 时，该字段应包含文档的 URL。支持嵌套字段（例如 `after.document`）。
`field.docling`	无默认值	指定 SMT 向记录中添加的字段名称，用于存放 Docling 文档。如果未指定该值，则结果记录仅包含 Docling 文档的值。支持嵌套字段（例如 `after.document_parsed`），但嵌套结构必须存在（例如，对于 `after.document_parsed.markdown`，`after.document_parsed` 必须存在）。
`serve.url`	无默认值	Docling Serve API 服务器的 URL，包含协议和端口（例如 `http://localhost:5001` 或 `https://docling.example.com`）。出于安全原因，仅允许 HTTP 和 HTTPS 协议。
`input.source`	`text`	指定 Docling 应如何解释源字段。有效值： `text` - 源字段直接包含文档内容。 `link` - 源字段包含文档的 URL。
`input.format`	无默认值	输入文档的格式。必须与 Docling 服务器支持的某种格式匹配。常见格式包括：`pdf`、`docx`、`pptx`、`html`、`asciidoc`、`md`（Markdown）、`xlsx` 等。完整的支持格式列表请参阅 Docling 文档。
`include.images`	`true`	指定是否在结果文档中包含图片。设置为 `true` 时，源文档中的图片会在输出中保留；设置为 `false` 时，转换结果中将不包含图片。
`output.format`	`text`	Docling 生成的输出文档格式。有效值： `html` - 结构化的 HTML 输出。 `markdown` - Markdown 格式的输出。 `text` - 纯文本输出。

simple.schema.lookup

false

用于模式缓存的性能优化。设置为 true 时，模式将按名称缓存，而不是按完整的模式结构缓存。只有在确定 Debezium 连接器执行期间不会发生模式演进时，才启用此选项。在模式稳定的环境中，这可以提升性能。

Docling Serve API

Docling 转换需要一个正在运行的 Docling Serve API 实例。Docling Serve 是一个通过 REST API 提供 Docling 文档理解能力的服务。

要设置 Docling Serve 实例，请参阅 Docling 项目文档。

	出于安全考虑，`serve.url` 配置选项仅接受 HTTP 和 HTTPS URL。不允许使用文件路径、FTP URL 或其他协议方案。

输入源模式

Docling 转换支持两种输入源模式：

文本模式

当 input.source 设置为 text 时，源字段应直接包含文档内容。此模式适用于以下情况：

文档内容已存储在数据库中
需要转换小型文档或文本片段
文档是动态生成的

在文本模式下，内容会先在内部进行 base64 编码，然后再发送到 Docling Serve API。

配置示例：

transforms.docling.input.source=text
transforms.docling.field.source=after.pdf_content

链接模式

当 input.source 设置为 link 时，source 字段应包含文档的 URL。此模式适用于以下情况：

文档存储在外部（例如 S3、HTTP 服务器）
希望避免将大文档存储在数据库中
文档已可通过 HTTP/HTTPS 访问

在链接模式下，URL 会经过验证，以出于安全原因确保其使用 HTTP 或 HTTPS 协议。

示例配置：

transforms.docling.input.source=link
transforms.docling.field.source=after.document_url

输出格式

Docling 支持三种输出格式，每种格式适用于不同的使用场景：

纯文本

text 输出格式生成不带任何格式或结构标记的干净纯文本。这是默认格式，适用于：

简单的文本分析
向不需要结构的 LLM 提供内容
尽量减小输出体积

Markdown

markdown 输出格式生成保留文档结构的 Markdown 格式文本。该格式适用于：

保留标题、列表和基本格式
便于人类阅读的输出
能从结构化标记中获益的 LLM

HTML

html 输出格式生成保留文档视觉结构的结构化 HTML。该格式适用于：

保留复杂的文档版式
基于网页的渲染
需要详细结构信息的应用

示例用例

处理数据库中的 PDF 文档

转换存储在 PostgreSQL 数据库中的 PDF 文档：

transforms=docling
transforms.docling.type=io.debezium.ai.docling.FieldToDocling
transforms.docling.field.source=after.pdf_content
transforms.docling.field.docling=after.text_content
transforms.docling.serve.url=http://docling:5001
transforms.docling.input.source=text
transforms.docling.input.format=pdf
transforms.docling.output.format=text

处理来自 URL 的文档

转换数据库中通过 URL 引用的文档：

transforms=docling
transforms.docling.type=io.debezium.ai.docling.FieldToDocling
transforms.docling.field.source=after.document_url
transforms.docling.field.docling=after.document_content
transforms.docling.serve.url=https://docling.example.com
transforms.docling.input.source=link
transforms.docling.input.format=pdf
transforms.docling.output.format=markdown
transforms.docling.include.images=false

用解析后的内容替换记录

创建一个仅包含已解析文档内容的新流：

transforms=docling
transforms.docling.type=io.debezium.ai.docling.FieldToDocling
transforms.docling.field.source=after.document
transforms.docling.serve.url=http://docling:5001
transforms.docling.input.source=text
transforms.docling.input.format=docx
transforms.docling.output.format=html
# Note: field.docling is not specified, so the record contains only the Docling document

Docling 转换

Docling 转换

行为

配置

配置选项

Docling Serve API

输入源模式

文本模式

链接模式

输出格式

纯文本

Markdown

HTML

示例用例

处理数据库中的 PDF 文档

处理来自 URL 的文档

用解析后的内容替换记录

评论