zai-org/GLM-OCR
GitHub: zai-org/GLM-OCR
GLM-OCR 是一个基于 GLM-V 架构的轻量级多模态文档 OCR 模型，专注于复杂文档的高精度识别与结构化输出。
Stars: 5313 | Forks: 464
## GLM-OCR
[中文阅读](README_zh.md)
[🤖 ModelScope](https://modelscope.cn/models/ZhipuAI/GLM-OCR) | BF16 | ## GLM-OCR SDK 我们提供了一个 SDK，以便更高效、更便捷地使用 GLM-OCR。 ### 安装 SDK 选择适合您场景的最轻量安装方式： ``` # 云端 / MaaS + 本地图像 / PDF（安装最快） pip install glmocr # 自托管 Pipeline（布局检测） pip install "glmocr[selfhosted]" # Flask 服务支持 pip install "glmocr[server]" ``` 从源码安装以进行开发： ``` # 从源码安装 git clone https://github.com/zai-org/glm-ocr.git cd glm-ocr uv venv --python 3.12 --seed && source .venv/bin/activate uv pip install -e . ``` ### 模型部署 使用 GLM-OCR 的两种方式： #### 方式 1：Zhipu MaaS API（推荐用于快速入门） 使用托管的云端 API —— 无需 GPU。云服务在内部运行完整的 GLM-OCR pipeline，SDK 只需转发您的请求并返回结果。 1. 从 https://open.bigmodel.cn 获取 API key 2. 配置 `config.yaml`： ``` pipeline: maas: enabled: true # Enable MaaS mode api_key: your-api-key # Required ``` 完成！当 `maas.enabled=true` 时，SDK 充当一个轻量级封装，它会： - 将您的文档转发到 Zhipu 云 API - 直接返回结果（Markdown + JSON 布局详情） - 无需本地处理，无需 GPU 输入说明（MaaS）：上游 API 接受 `file` 作为 URL 或 `data:;base64,...` 数据 URI。
如果您有原始 base64（不带 `data:` 前缀），请将其封装为数据 URI（推荐）。SDK 在调用 MaaS 时会自动将本地文件路径 / 字节 / 原始 base64 封装为数据 URI。
API 文档：https://docs.bigmodel.cn/cn/guide/models/vlm/glm-ocr
#### 方式 2：使用 vLLM / SGLang 自托管
在本地部署 GLM-OCR 模型以获得完全控制权。SDK 提供完整的 pipeline：布局检测、并行区域 OCR 和结果格式化。
首先安装自托管额外依赖：
```
pip install "glmocr[selfhosted]"
```
##### 使用 vLLM
安装 vLLM：
```
docker pull vllm/vllm-openai:nightly
```
或使用 pip 安装：
```
pip install -U "vllm>=0.17.0"
```
启动服务：
```
pip install "transformers>=5.3.0"
vllm serve zai-org/GLM-OCR --allowed-local-media-path / --port 8080 --speculative-config '{"method": "mtp", "num_speculative_tokens": 1}' --served-model-name glm-ocr
```
##### 使用 SGLang
安装 SGLang：
```
docker pull lmsysorg/sglang:dev
```
或使用 pip 安装：
```
pip install "sglang>=0.5.9"
```
启动服务：
```
pip install "transformers>=5.3.0"
sglang serve --model zai-org/GLM-OCR --port 8080 --speculative-algorithm NEXTN --speculative-num-steps 3 --speculative-eagle-topk 1 --speculative-num-draft-tokens 4 --served-model-name glm-ocr
```
##### 更新配置
启动服务后，配置 `config.yaml`：
```
pipeline:
maas:
enabled: false # Disable MaaS mode (default)
ocr_api:
api_host: localhost # or your vLLM/SGLang server address
api_port: 8080
```
#### 方式 3：Ollama/MLX
对于特定的部署场景，请参阅详细指南：
- **[Apple Silicon 配合 mlx-vlm](examples/mlx-deploy/README.md)** - 针对 Apple Silicon Mac 优化
- **[Ollama 部署](examples/ollama-deploy/README.md)** - 使用 Ollama 进行简单的本地部署
### SDK 使用指南
#### CLI
```
# 解析单张图像
glmocr parse examples/source/code.png
# 解析目录
glmocr parse examples/source/
# 设置输出目录
glmocr parse examples/source/code.png --output ./results/
# 使用自定义 config
glmocr parse examples/source/code.png --config my_config.yaml
# 启用 debug 日志记录与性能分析
glmocr parse examples/source/code.png --log-level DEBUG
# 在 CPU 上运行布局检测（保持 GPU 空闲用于 OCR 模型）
glmocr parse examples/source/code.png --layout-device cpu
# 在特定 GPU 上运行布局检测
glmocr parse examples/source/code.png --layout-device cuda:1
# 通过 --set 覆盖任何 config 值（点分隔路径，可重复）
glmocr parse examples/source/code.png --set pipeline.ocr_api.api_port 8080
glmocr parse examples/source/ --set pipeline.layout.use_polygon true --set logging.level DEBUG
```
#### Python API
```
from glmocr import GlmOcr, parse
# 简单函数
result = parse("image.png")
result = parse(["img1.png", "img2.jpg"])
result = parse("https://example.com/image.png")
result.save(output_dir="./results")
# 注意：列表被视为单个文档的页面。
# 基于类的 API
with GlmOcr() as parser:
result = parser.parse("image.png")
print(result.json_result)
result.save()
# 将布局模型放置在 CPU 上（当 GPU 专为 OCR 保留时有用）
with GlmOcr(layout_device="cpu") as parser:
result = parser.parse("image.png")
# 将布局模型放置在特定 GPU 上
with GlmOcr(layout_device="cuda:1") as parser:
result = parser.parse("image.png")
```
#### Flask 服务
首先安装可选的服务器依赖：
```
pip install "glmocr[server]"
```
```
# 启动服务
python -m glmocr.server
# 带 debug 日志记录
python -m glmocr.server --log-level DEBUG
# 调用 API
curl -X POST http://localhost:5002/glmocr/parse \
-H "Content-Type: application/json" \
-d '{"images": ["./example/source/code.png"]}'
```
语义说明：
- `images` 可以是字符串或列表。
- 列表被视为单个文档的页面。
- 对于多个独立的文档，请多次调用端点（每个请求一个文档）。
### 配置
配置优先级（从高到低）：
1. CLI `--set` 覆盖
2. Python API 关键字参数
3. `GLMOCR_*` 环境变量 / `.env` 文件
4. YAML 配置文件
5. 内置默认值
`glmocr/config.yaml` 中的完整配置：
```
# 服务器（用于 glmocr.server）
server:
host: "0.0.0.0"
port: 5002
debug: false
# 日志记录
logging:
level: INFO # DEBUG enables profiling
# Pipeline
pipeline:
# OCR API connection
ocr_api:
api_host: localhost
api_port: 8080
api_key: null # or set API_KEY env var
connect_timeout: 30
request_timeout: 120
# Page loader settings
page_loader:
max_tokens: 8192
temperature: 0.0
image_format: JPEG
min_pixels: 12544
max_pixels: 71372800
# Result formatting
result_formatter:
output_format: both # json, markdown, or both
# Layout model device placement
layout:
# device: null # null=auto, "cpu", "cuda", or "cuda:N"
```
有关所有选项，请参阅 [config.yaml](glmocr/config.yaml)。
### 输出格式
以下是两种输出格式的示例：
- JSON
```
[[{ "index": 0, "label": "text", "content": "...", "bbox_2d": null }]]
```
- Markdown
```
# 文档标题
Body...
| Table | Content |
| ----- | ------- |
| ... | ... |
```
### 完整 Pipeline 示例
您可以像这样运行示例代码：
```
python examples/example.py
```
输出结构（每个输入一个文件夹）：
- `result.json` – 结构化 OCR 结果
- `result.md` – Markdown 结果
- `imgs/` – 裁剪的图像区域（当启用布局模式时）
### 模块化架构
GLM-OCR 使用可组合的模块，便于自定义：
| 组件 | 描述 |
| --------------------- | -------------------------------- |
| `PageLoader` | 预处理和图像编码 |
| `OCRClient` | 调用 GLM-OCR 模型服务 |
| `PPDocLayoutDetector` | PP-DocLayout 布局检测 |
| `ResultFormatter` | 后处理，输出 JSON/Markdown |
您可以通过创建自定义 pipeline 来扩展行为：
```
from glmocr.dataloader import PageLoader
from glmocr.ocr_client import OCRClient
from glmocr.postprocess import ResultFormatter
class MyPipeline:
def __init__(self, config):
self.page_loader = PageLoader(config)
self.ocr_client = OCRClient(config)
self.formatter = ResultFormatter(config)
def process(self, request_data):
# Implement your own processing logic
pass
```
## 致谢
本项目受到以下项目和社区优秀工作的启发：
- [PP-DocLayout-V3](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3)
- [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)
- [MinerU](https://github.com/opendatalab/MinerU)
## 许可证
本仓库的代码遵循 Apache License 2.0。
GLM-OCR 模型根据 MIT License 发布。
完整的 OCR pipeline 集成了 [PP-DocLayoutV3](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3) 用于文档布局分析，该组件根据 Apache License 2.0 授权。用户在使用本项目时应遵守这两项许可证。
## 引用
如果您在研究中发现 GLM-OCR 有用，请引用我们的技术报告：
```
@misc{duan2026glmocrtechnicalreport,
title={GLM-OCR Technical Report},
author={Shuaiqi Duan and Yadong Xue and Weihan Wang and Zhe Su and Huan Liu and Sheng Yang and Guobing Gan and Guo Wang and Zihan Wang and Shengdong Yan and Dexin Jin and Yuxuan Zhang and Guohong Wen and Yanfeng Wang and Yutao Zhang and Xiaohan Zhang and Wenyi Hong and Yukuo Cen and Da Yin and Bin Chen and Wenmeng Yu and Xiaotao Gu and Jie Tang},
year={2026},
eprint={2603.10910},
archivePrefix={arXiv},
primaryClass={cs.CL},
url={https://arxiv.org/abs/2603.10910},
}
```
👋 Join our WeChat and Discord community
📖 Check out the GLM-OCR technical report
📍 Use GLM-OCR's API
[🤖 ModelScope](https://modelscope.cn/models/ZhipuAI/GLM-OCR) | BF16 | ## GLM-OCR SDK 我们提供了一个 SDK，以便更高效、更便捷地使用 GLM-OCR。 ### 安装 SDK 选择适合您场景的最轻量安装方式： ``` # 云端 / MaaS + 本地图像 / PDF（安装最快） pip install glmocr # 自托管 Pipeline（布局检测） pip install "glmocr[selfhosted]" # Flask 服务支持 pip install "glmocr[server]" ``` 从源码安装以进行开发： ``` # 从源码安装 git clone https://github.com/zai-org/glm-ocr.git cd glm-ocr uv venv --python 3.12 --seed && source .venv/bin/activate uv pip install -e . ``` ### 模型部署 使用 GLM-OCR 的两种方式： #### 方式 1：Zhipu MaaS API（推荐用于快速入门） 使用托管的云端 API —— 无需 GPU。云服务在内部运行完整的 GLM-OCR pipeline，SDK 只需转发您的请求并返回结果。 1. 从 https://open.bigmodel.cn 获取 API key 2. 配置 `config.yaml`： ``` pipeline: maas: enabled: true # Enable MaaS mode api_key: your-api-key # Required ``` 完成！当 `maas.enabled=true` 时，SDK 充当一个轻量级封装，它会： - 将您的文档转发到 Zhipu 云 API - 直接返回结果（Markdown + JSON 布局详情） - 无需本地处理，无需 GPU 输入说明（MaaS）：上游 API 接受 `file` 作为 URL 或 `data:
标签：AI, AI风险缓解, DLL 劫持, GLM, OCR, vLLM, 信息抽取, 光学字符识别, 公式识别, 多模态模型, 大语言模型, 布局分析, 强化学习, 文档理解, 智能文档处理, 深度学习, 知识提取, 编码器-解码器, 自动化代码审查, 表格识别, 计算机视觉, 请求拦截, 轻量级模型, 边缘计算, 逆向工具