Umi-OCR HTTP接口调用问题解析与解决方案

问题背景

在使用Umi-OCR进行批量文档处理时，开发者遇到了通过HTTP命令方式调用批量文档接口的异常情况。具体表现为调用"addDocs"方法时返回"Calling 'addDocs' in main thread"提示，以及后续使用Java调用上传接口时遇到的"File extension '' is not allowed"错误。

问题分析与解决方案

1. 旧版批量文档接口调用问题

在Umi-OCR v2.1.2.7版本中，通过HTTP命令行方式调用批量文档接口时，虽然返回了"Calling 'addDocs' in main thread"的提示，但这实际上并非错误信息，而是表明指令已被调度到主线程执行。这种调用方式本质上是模拟人工操作，将PDF文档添加到软件的"批量文档识别"界面。

解决方案：

• 这种调用方式只能添加任务，无法实时获取任务状态，需要手动在软件界面查看任务进度
• 可以通过脚本检查输出文件是否存在来判断任务是否完成（如检查"[OCR]_文件名"前缀的文件）

2. 新版HTTP接口的使用

对于需要更完善功能的需求，建议升级到v2.1.3版本（当前可通过获取main分支源码更新），该版本提供了更强大的HTTP PDF接口，支持：

• 文件上传
• 任务进度查询
• 多种OCR文件格式生成
• 生成文件下载

接口特点：

• 提供RESTful风格的API端点
• 支持JSON格式的请求和响应
• 支持多部分表单数据上传

3. Java调用上传接口问题

在使用Java调用上传接口时，开发者遇到了文件扩展名不被允许的错误。这主要是由于请求构造方式不当导致的。

正确实现方案：

使用Java标准HttpClient库构建多部分表单请求：

// 构建请求URL和文件路径
String url = "http://127.0.0.1:1224/api/doc/upload";
String path = "测试文件.pdf";
String options_json = "{\"doc.extractionMode\": \"fullPage\"}";

// 创建HttpClient实例
HttpClient client = HttpClient.newHttpClient();

// 生成boundary用于分隔表单数据
String boundary = UUID.randomUUID().toString();

// 构建multipart/form-data请求体
StringBuilder sb = new StringBuilder();
// 添加JSON参数部分
sb.append("--").append(boundary).append("\r\n");
sb.append("Content-Disposition: form-data; name=\"json\"\r\n");
sb.append("Content-Type: application/json\r\n");
sb.append("\r\n");
sb.append(options_json).append("\r\n");

// 添加文件部分
sb.append("--").append(boundary).append("\r\n");
sb.append("Content-Disposition: form-data; name=\"file\"; filename=\"")
  .append(Paths.get(path).getFileName()).append("\"\r\n");
sb.append("Content-Type: application/pdf\r\n"); // 明确指定PDF类型
sb.append("\r\n");

// 读取文件内容并构建完整请求体
byte[] fileBytes = Files.readAllBytes(Paths.get(path));
byte[] requestBody = new byte[sb.toString().getBytes().length + fileBytes.length
        + ("\r\n--" + boundary + "--\r\n").getBytes().length];
System.arraycopy(sb.toString().getBytes(), 0, requestBody, 0, sb.toString().getBytes().length);
System.arraycopy(fileBytes, 0, requestBody, sb.toString().getBytes().length, fileBytes.length);
System.arraycopy(("\r\n--" + boundary + "--\r\n").getBytes(), 0, requestBody,
        sb.toString().getBytes().length + fileBytes.length,
        ("\r\n--" + boundary + "--\r\n").getBytes().length);

// 创建并发送请求
HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("Content-Type", "multipart/form-data; boundary=" + boundary)
        .POST(HttpRequest.BodyPublishers.ofByteArray(requestBody))
        .build();

// 处理响应
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("响应状态码: " + response.statusCode());
System.out.println("响应内容: " + response.body());

关键点说明：

1. 必须正确设置Content-Type头部，包含boundary信息
2. 文件部分需要明确指定文件名和内容类型
3. 各部分数据需要用boundary分隔
4. 最后需要添加结束boundary标记

最佳实践建议

1. 版本选择：

   • 对于生产环境，建议等待v2.1.3正式发布
   • 开发环境可使用main分支代码进行测试

2. 错误处理：

   • 增加对网络异常和IO异常的处理
   • 检查响应状态码，非200状态需要特别处理
   • 解析响应JSON获取详细错误信息

3. 性能优化：

   • 复用HttpClient实例
   • 对于大文件，考虑使用流式上传
   • 实现异步调用避免阻塞主线程

4. 任务管理：

   • 保存返回的任务ID用于后续查询
   • 实现轮询机制检查任务状态
   • 设置合理的超时时间

总结

Umi-OCR提供了灵活的接口用于批量文档处理，但在使用时需要注意版本差异和正确的API调用方式。通过本文提供的解决方案，开发者可以正确实现Java程序与Umi-OCR的集成，完成PDF文档的批量OCR处理任务。对于更复杂的需求，建议参考官方文档了解完整的API规范。