GiteeClient 文档解析与图片 OCR

java-openai 提供 GiteeClient，可以提交文档解析任务、查询任务状态，也可以调用同步图片 OCR。文档模型常量存在，并不代表该模型支持所有接口。

配置

在应用配置或本地 secrets.txt 中设置 GITEE_API_KEY，启动时调用 EnvUtils.load()。读取配置使用 EnvUtils.get。不要将真实密钥放入测试源码、日志或提交到仓库。

EnvUtils.load();
String apiKey = EnvUtils.get("GITEE_API_KEY");
GiteeClient client = new GiteeClient(apiKey);

GITEE_BASE_URL 是默认构造方法读取的服务根地址配置；GITEE_API_URL 用于模型列表等 OpenAI 兼容接口，二者用途不同。

文档解析模型

以下模型使用异步接口 POST /v1/async/documents/parse：

模型常量
MinerU2.5-ProGiteeModels.MINERU2_5_PRO
Unlimited-OCRGiteeModels.UNLIMITED_OCR
PaddleOCR-VL-1.5GiteeModels.PADDLEOCR_VL_1_5
DeepSeek-OCRGiteeModels.DEEPSEEK_OCR
MinerU2.5GiteeModels.MINERU2_5
PDF-Extract-Kit-1.0GiteeModels.PDF_EXTRACT_KIT_1_0
import java.io.File;
import nexus.io.gitee.GiteeClient;
import nexus.io.gitee.GiteeDocumentParseRequest;
import nexus.io.gitee.GiteeModels;
import nexus.io.gitee.GiteeTaskResponse;
import nexus.io.tio.utils.environment.EnvUtils;

EnvUtils.load();
GiteeDocumentParseRequest request = new GiteeDocumentParseRequest();
request.setModel(GiteeModels.MINERU2_5_PRO);
GiteeClient client = new GiteeClient();
GiteeTaskResponse task = client.parseDocument(new File("data/sample.pdf"), request);
String taskId = task.getTask_id();
GiteeTaskResponse latest = client.getTask(taskId);

任务创建后通常处于 waiting 或 in_progress。业务侧应设置轮询间隔和总超时，并分别处理 success、failure 等终态。HTTP 200 也可能携带 status: failure，例如运行任务数超限。此时应检查原始响应的 output.error，不要把请求成功当成解析成功。

解析结果可能放在 output.pages 或 output.segments。可用 GiteeSimpleMarkdownUtils.toMarkdown(task.getOutput()) 提取内容；分段索引可能随内部批次从零重新开始，不要按 segment.index 对整个文档重新排序。部分模型会过滤只有页脚的页面，不能仅凭任务成功或分段数判断内容完整性。

Unlimited-OCR 的分段内容可能包含布局类型和坐标。Markdown 工具会连接分段内容，但不会自动清理该模型的全部布局标记；用于检索前应做独立清理，并保留原始响应。

HunyuanOCR 使用同步图片接口

HunyuanOCR 的常量是 GiteeModels.HUNYUAN_OCR，调用的是 POST /v1/images/ocr。它接收 model 和 image 两个 multipart 字段，不支持直接通过上述异步 PDF 接口提交。

import java.io.File;
import nexus.io.gitee.GiteeClient;
import nexus.io.gitee.GiteeModels;
import nexus.io.gitee.GiteeOcrResponse;
import nexus.io.tio.utils.environment.EnvUtils;

EnvUtils.load();
GiteeOcrResponse response = new GiteeClient().ocr(
    new File("data/page.png"), GiteeModels.HUNYUAN_OCR);
System.out.println(response.getText());

PDF 需要先按页渲染为图片，再逐页调用。另有 ocr(byte[] image, String filename, String model) 重载。官方接口示例返回 text，实测也会返回 text_result 和 prompt；getText() 兼容这两种文本字段。若服务返回图片尺寸超限，应依据错误信息等比例缩小图片并记录处理参数，以免将预处理差异误认为模型差异。

自定义 HTTP 客户端

GiteeClient(apiKey, baseUrl, httpClient) 可注入自定义 OkHttpClient，配置超时和响应拦截器。异步请求默认携带 X-Failover-Enabled: true，评测需要通过拦截器改为 false，避免实际使用降级模型。

相关文档