通过回调使用自定义 AI 模型

概述

从 SDK v4.1.0 开始，ComPDF Conversion SDK 暴露了一个基于回调的扩展点，允许您插入自己的 AI 推理引擎来进行 OCR、版面分析和表格识别。您可以不再依赖通过 setDocumentAIModel 加载的内置 DocumentAI 模型，而是：

• 使用您选择的任何模型或运行时运行推理（例如，您自己的内部引擎、PaddleOCR、云 OCR API）。
• 将结果以具有明确定义模式的 JSON 字符串返回给 SDK。

当 ConvertCallback 上注册了相关的回调对时，SDK 会跳过该能力的内置模型调用，转而使用您的 JSON 输出。如果回调对未设置，SDK 会回退到内置的 DocumentAI 模型（如果可用）。

回调对

每种 AI 能力使用两个回调：一个触发器（由 SDK 调用，传入保存为 PNG 的页面图像的临时目录路径）和一个结果获取器（由 SDK 紧接着调用以检索 JSON 字符串）。

能力	触发器字段/设置器	结果获取器字段/设置器	触发时机
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 向下）。
• 置信度过滤：confidence < 0.1 的 OCR 跨度和 confidence < 0.45 的版面对象将被 SDK 丢弃。
• 当您需要的所有三种能力都由您自己的回调覆盖时，无需调用 setDocumentAIModel。

示例

@interface CustomAICallback : NSObject <ConvertCallback>
@property (nonatomic, copy) NSString *ocrResultJson;
@property (nonatomic, copy) NSString *layoutResultJson;
@property (nonatomic, copy) NSString *tableResultJson;
@end

@implementation CustomAICallback
- (void)onProgress:(int)currentPage totalPage:(int)totalPage {}
- (BOOL)isCancelled { return NO; }

- (BOOL)onOcr:(NSString *)imagePath {
    // 在 `imagePath` 上运行您的 OCR 引擎，缓存 JSON 结果。
    self.ocrResultJson = @"{}";
    return YES;
}
- (BOOL)onLayout:(NSString *)imagePath {
    self.layoutResultJson = @"{}";
    return YES;
}
- (BOOL)onTable:(NSString *)imagePath {
    self.tableResultJson = @"{}";
    return YES;
}

- (NSString *)getOcrResult    { return self.ocrResultJson; }
- (NSString *)getLayoutResult { return self.layoutResultJson; }
- (NSString *)getTableResult  { return self.tableResultJson; }
@end

WordOptions *options = [[WordOptions alloc] init];
options.enableOCR = YES;
options.enableAILayout = YES;
options.enableAITableRecognition = YES;
CustomAICallback *callback = [[CustomAICallback alloc] init];
[CPDFConversion startPDFToWord:@"input.pdf"
                      password:@"password"
                    outputPath:@"path/output.docx"
                       options:options
                      callback:callback];

JSON 模式

每种能力的预期 JSON 模式，包括字段名称、坐标空间（触发器接收到的图像的像素空间）和值范围，在所有语言绑定中都是相同的。请参阅 C++ 指南中的“通过回调使用自定义 AI 模型”。