6.9 KiB

Raw Blame History

GLM-OCR Java服务 - 项目上下文文档

项目概述

这是一个基于DJL (Deep Java Library) 的纯Java实现的GLM-OCR本地部署服务，提供REST API接口进行文档识别。该项目不依赖任何外部服务（如vLLM、Ollama或Python环境），完全使用Java技术栈运行。

核心特性

纯Java实现，无需外部服务依赖
支持多种OCR任务：文本识别、公式识别、表格识别、信息提取
基于DJL框架，使用PyTorch引擎
支持CPU和GPU推理
提供完整的REST API和Swagger文档
Apache 2.0开源协议

技术栈

Java: 17
构建工具: Maven 3.6+
Web框架: Spring Boot 3.2.0
深度学习框架: DJL 0.27.0 (PyTorch引擎)
PyTorch: 2.1.1 (CPU版本)
分词器: HuggingFace Tokenizers
图像处理: TwelveMonkeys ImageIO
API文档: SpringDoc OpenAPI 2.3.0
其他工具: Lombok, Jackson, Commons IO

项目结构

glmocrdemojava/
├── pom.xml                          # Maven项目配置文件
├── README.md                        # 项目说明文档
├── api-test.http                    # API测试示例（VS Code REST Client格式）
├── AGENTS.md                        # 本文件，AI代理上下文文档
├── scripts/                         # 脚本目录（当前为空）
└── src/main/
    ├── java/com/example/glmocr/
    │   ├── GlmOcrApplication.java   # Spring Boot主应用类
    │   ├── config/
    │   │   └── GlmOcrConfig.java    # GLM-OCR配置类
    │   ├── controller/
    │   │   ├── OcrController.java   # REST API控制器
    │   │   └── GlobalExceptionHandler.java  # 全局异常处理器
    │   ├── dto/
    │   │   ├── OcrRequest.java      # OCR请求DTO
    │   │   ├── OcrResponse.java     # OCR响应DTO
    │   │   └── HealthResponse.java  # 健康检查响应DTO
    │   ├── model/
    │   │   ├── GlmOcrModel.java     # DJL模型封装类
    │   │   └── GlmOcrTranslator.java  # 图像预处理和结果翻译器
    │   ├── service/
    │   │   └── GlmOcrService.java   # OCR服务层
    │   └── tokenizer/
    │       └── TokenizerService.java  # 分词器服务
    └── resources/
        └── application.yml          # 应用配置文件

构建和运行

环境要求

Java 17+
Maven 3.6+
GLM-OCR模型文件（需从ModelScope下载）

构建项目

mvn clean package -DskipTests

构建完成后，JAR文件位于 target/glm-ocr-service-1.0.0.jar

运行应用

java -jar target/glm-ocr-service-1.0.0.jar

服务将在 http://localhost:9090 启动。

测试

mvn test

首次运行前的准备

下载GLM-OCR模型：

git lfs install
git clone https://modelscope.cn/ZhipuAI/GLM-OCR.git ./models/GLM-OCR

修改配置文件 src/main/resources/application.yml 中的模型路径（如果需要）

配置说明

配置文件位于 src/main/resources/application.yml

核心配置项

配置项	说明	默认值
`server.port`	服务端口	9090
`glm-ocr.model-path`	模型本地路径	./models/GLM-OCR
`glm-ocr.device`	推理设备 (cpu/gpu(0)/gpu(1))	cpu
`glm-ocr.precision`	精度 (fp32/fp16/bf16/int8)	fp32
`glm-ocr.max-tokens`	最大生成token数	8192
`glm-ocr.batch-size`	批次大小	1
`glm-ocr.image-size`	图像预处理大小	448
`glm-ocr.temperature`	温度参数	0.1
`glm-ocr.top-p`	Top P采样参数	0.95
`glm-ocr.timeout`	请求超时时间（秒）	120

API接口

基础信息

Base URL: http://localhost:9090
API前缀: /api/v1
Swagger文档: http://localhost:9090/swagger-ui.html
OpenAPI规范: http://localhost:9090/api-docs

主要接口

方法	路径	说明
GET	`/api/v1/health`	健康检查
POST	`/api/v1/ocr/text`	文本识别
POST	`/api/v1/ocr/formula`	公式识别
POST	`/api/v1/ocr/table`	表格识别
POST	`/api/v1/ocr/extract`	信息提取
POST	`/api/v1/ocr`	通用OCR识别
POST	`/api/v1/model/reload`	重新加载模型

请求示例

文本识别

POST /api/v1/ocr/text
Content-Type: application/json

{
  "image": "iVBORw0KGgoAAAANSUhEUg...",
  "imageType": "base64"
}

信息提取

POST /api/v1/ocr/extract
Content-Type: application/json

{
  "image": "iVBORw0KGgoAAAANSUhEUg...",
  "imageType": "base64",
  "extractionTemplate": "{\n  \"name\": \"\",\n  \"id_number\": \"\"\n}"
}

响应格式

成功响应：

{
  "success": true,
  "result": "识别结果文本",
  "processingTimeMs": 1234
}

失败响应：

{
  "success": false,
  "error": "错误信息"
}

开发约定

代码风格

使用Lombok简化代码（@Data, @RequiredArgsConstructor等）
使用SLF4J进行日志记录
遵循Spring Boot最佳实践
使用Jakarta EE（而非javax）注解

包结构说明

config: 配置类，使用@ConfigurationProperties绑定配置
controller: REST控制器，处理HTTP请求
dto: 数据传输对象，使用Swagger注解描述API
model: 模型相关类，包括模型加载和翻译器
service: 业务逻辑层
tokenizer: 分词器服务

错误处理

使用GlobalExceptionHandler统一处理异常
返回格式统一的错误响应
模型初始化失败不阻止服务启动，允许后续手动加载

日志配置

DEBUG级别：com.example.glmocr包
INFO级别：ai.djl包
使用模式化日志输出

重要说明

模型依赖

模型文件需要从ModelScope下载
默认路径：./models/GLM-OCR
模型文件包括：config.json, model.safetensors, tokenizer.json等

图像输入

目前仅支持Base64编码的图像
图像格式支持：PNG, JPEG, GIF, WebP
URL方式暂不支持

性能考虑

默认使用CPU推理，可在配置中切换到GPU
图像预处理大小默认为448x448
批次大小默认为1

GPU支持

需要配置CUDA环境
在配置文件中设置 device: gpu(0)
需要使用GPU版本的PyTorch原生库

常见问题

模型加载失败

检查模型路径配置是否正确
确认模型文件完整下载
检查文件权限

内存不足

减小批次大小
降低图像预处理尺寸
减小最大token数

推理速度慢

考虑使用GPU加速
降低精度设置（fp16/bf16）
优化图像尺寸

参考资料

开源协议

本项目：MIT License
DJL：Apache License 2.0
GLM-OCR模型：MIT License

6.9 KiB Raw Blame History Unescape Escape