glmocrdemojava/AGENTS.md

# 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