使用自定义 AI 模型回调

概述

从 v4.1 起，ComPDF Conversion SDK 提供了基于回调的扩展点，允许您为 OCR、版面分析和表格识别接入自己的 AI 推理引擎。相比加载内置 DocumentAI 模型（通过 SetDocumentAIModel），您可以：

• 使用任意您选择的模型或运行时进行推理（例如自研引擎、PaddleOCR、云端 OCR API 等）。
• 通过约定 JSON 格式把结果返回给 SDK。

当 ConvertCallback 中对应能力的回调对被设置后，SDK 在该阶段不再调用内置模型，而是使用您返回的 JSON。若未设置，则 SDK 仍按原有方式调用内置 DocumentAI 模型（前提是模型已加载）。

回调对

每个 AI 能力使用 两个回调：一个 触发回调（SDK 传入页面 PNG 临时文件路径）和一个 结果获取回调（SDK 紧随其后调用以拿到 JSON 字符串）。

能力	触发回调字段 / setter	结果获取回调字段 / setter	触发条件
OCR	ocr	get_ocr_result	开启 OCR
版面分析	layout	get_layout_result	开启版面分析（或在开启 OCR 时隐式开启）
表格识别	table	get_table_result	开启表格识别 且 版面分析报告了表格区域

规则：

• 触发回调接收 PNG 临时文件的 UTF-8 路径。推理成功返回 true，返回 false 则该页结果会被 SDK 忽略。
• 结果获取回调必须返回 UTF-8 JSON 字符串。SDK 会把内容拷贝到内部缓冲区后再消费。
• 同一能力的两个回调必须成对设置；若只设置其中一个，SDK 会回退到内置实现。
• JSON 中的坐标必须使用 触发回调收到的那张图像的像素空间（左上为原点，X 向右，Y 向下）。
• 置信度过滤：OCR 文本 confidence < 0.1、版面对象 confidence < 0.45 会被 SDK 丢弃。
• 当您需要的三种能力全部通过自定义回调接入时，可以不调用 SetDocumentAIModel。

示例

// Embed BaseCallback so you only override the methods you need.
type customAICallback struct {
    compdf.BaseCallback
    ocrJSON    string
    layoutJSON string
    tableJSON  string
}

func (c *customAICallback) OnOCR(imagePath string) bool {
    // Run your OCR engine on `imagePath`, cache the JSON result.
    c.ocrJSON = ""
    return true
}
func (c *customAICallback) OnLayout(imagePath string) bool {
    c.layoutJSON = ""
    return true
}
func (c *customAICallback) OnTable(imagePath string) bool {
    c.tableJSON = ""
    return true
}

func (c *customAICallback) GetOCRResult() string    { return c.ocrJSON }
func (c *customAICallback) GetLayoutResult() string { return c.layoutJSON }
func (c *customAICallback) GetTableResult() string  { return c.tableJSON }

callback := &customAICallback{}
wordOptions := compdf.NewWordOptions()
wordOptions.EnableOCR = true
wordOptions.EnableAILayout = true
wordOptions.EnableAITableRecognition = true
err := compdf.StartPDFToWord("input.pdf", "password", "path/output.docx", wordOptions, callback)

JSON 数据结构

各能力的 JSON 字段名、坐标空间（触发回调收到的图像的像素坐标）和取值范围在所有语言绑定中一致，详细约定参见 C++ 开发者指南中的「Use Custom AI Models via Callbacks」章节。