273 lines
6.9 KiB
Markdown
273 lines
6.9 KiB
Markdown
# 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下载）
|
||
|
||
### 构建项目
|
||
|
||
```bash
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
构建完成后，JAR文件位于 `target/glm-ocr-service-1.0.0.jar`
|
||
|
||
### 运行应用
|
||
|
||
```bash
|
||
java -jar target/glm-ocr-service-1.0.0.jar
|
||
```
|
||
|
||
服务将在 `http://localhost:9090` 启动。
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
mvn test
|
||
```
|
||
|
||
### 首次运行前的准备
|
||
|
||
1. 下载GLM-OCR模型：
|
||
```bash
|
||
git lfs install
|
||
git clone https://modelscope.cn/ZhipuAI/GLM-OCR.git ./models/GLM-OCR
|
||
```
|
||
|
||
2. 修改配置文件 `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` | 重新加载模型 |
|
||
|
||
### 请求示例
|
||
|
||
#### 文本识别
|
||
|
||
```http
|
||
POST /api/v1/ocr/text
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"image": "iVBORw0KGgoAAAANSUhEUg...",
|
||
"imageType": "base64"
|
||
}
|
||
```
|
||
|
||
#### 信息提取
|
||
|
||
```http
|
||
POST /api/v1/ocr/extract
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"image": "iVBORw0KGgoAAAANSUhEUg...",
|
||
"imageType": "base64",
|
||
"extractionTemplate": "{\n \"name\": \"\",\n \"id_number\": \"\"\n}"
|
||
}
|
||
```
|
||
|
||
### 响应格式
|
||
|
||
成功响应：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"result": "识别结果文本",
|
||
"processingTimeMs": 1234
|
||
}
|
||
```
|
||
|
||
失败响应：
|
||
```json
|
||
{
|
||
"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原生库
|
||
|
||
## 常见问题
|
||
|
||
### 模型加载失败
|
||
|
||
1. 检查模型路径配置是否正确
|
||
2. 确认模型文件完整下载
|
||
3. 检查文件权限
|
||
|
||
### 内存不足
|
||
|
||
1. 减小批次大小
|
||
2. 降低图像预处理尺寸
|
||
3. 减小最大token数
|
||
|
||
### 推理速度慢
|
||
|
||
1. 考虑使用GPU加速
|
||
2. 降低精度设置（fp16/bf16）
|
||
3. 优化图像尺寸
|
||
|
||
## 参考资料
|
||
|
||
- [GLM-OCR模型](https://modelscope.cn/models/ZhipuAI/GLM-OCR)
|
||
- [DJL文档](https://djl.ai/)
|
||
- [Spring Boot文档](https://spring.io/projects/spring-boot)
|
||
- [SpringDoc OpenAPI](https://springdoc.org/)
|
||
|
||
## 开源协议
|
||
|
||
- 本项目：MIT License
|
||
- DJL：Apache License 2.0
|
||
- GLM-OCR模型：MIT License |