Hugging Face's logo

PatSnap
/
Hiro-MOSS-OCR-0.3B

Image-to-Text
Safetensors
moss_v1d6
custom_code
Model card Files
xet
 Community
Hiro-MOSS-OCR-0.3B / README_zh.md
wwjiang's picture
wwjiang
Update README_zh.md
f833fe4 verified
preview code
|
Raw
History Blame Contribute Delete
11.5 kB

MOSS🍀：面向结构化标记序列的多模态 OCR

English | 简体中文

License Python OCR Model Github OCR Model Huggingface Hugging Face Spaces

MOSS 是一个基于 50M+ 训练数据从零训练、面向块级文档理解的多模态 OCR 模型。它可以将文档图像区域转换为结构化标记：公式输出为 LaTeX，表格输出为 HTML，正文输出为 Markdown。模型支持日文、中文和英文。

新闻与更新

近期更新
  • 2026-07-02 - 新增 OmniDocBench v1.6 评测结果，采用真实版面标注和官方归一化规则。
  • 2026-05-28 - CUDA Graph 和 vLLM 推理现已支持直接解析 Hugging Face Hub repo id，可直接使用 PatSnap/Hiro-MOSS-OCR-0.3B，无需先手动下载 checkpoint。
  • 2026-05-28 - 新增 Transformers AutoModelForCausalLM 快速调用方式，适合快速验证；该方式使用方便，但推理效率低于 CUDA Graph 和 vLLM 后端。
  • 2026-05-26 - Hiro-MOSS-OCR-0.3B 已在 Hugging Face 开放。
  • 2026-05-26 - 仓库已提供本地 CUDA Graph 推理和 vLLM 服务部署示例。

亮点

  • 从零训练，训练数据 50M+： 面向结构化 OCR 和文档图像理解场景专门构建。
  • 结构化输出： 支持公式识别、表格还原和正文抽取，并为不同任务生成对应的标记格式。
  • 模型轻量： 总参数量约 320.8M。
  • 支持任意分辨率图像： 基于 NaViT 风格视觉编码，并使用 2D RoPE。
  • 多种推理方式： 支持 Transformers 快速调用、本地 CUDA Graph 推理，也支持通过 vLLM 部署为 OpenAI 兼容服务。

模型概览

模块 说明
训练 基于 50M+ 训练数据从零训练，支持任意分辨率图像
编码器（约 90M） NaViT with 2D RoPE
连接器（约 13.5M） SwiGLU with patch merger
解码器（约 216.6M） Transformer decoder with pre-norm, RoPE, GQA, and SwiGLU
总参数量 约 320.8M

支持任务

任务 输出格式
math LaTeX
table HTML
text Markdown

支持语言： 日文、中文、英文。

相关文档

  • 免责声明 - 使用条款、责任限制和数据处理责任说明。
  • 许可证 - 源代码许可证。

评测结果

OmniDocBench v1.5

使用真实版面标注进行评测。

模型 参数量 Table (TEDS) Math (CDM) Text (Edit Similarity) Overall
dolphin 0.3B 77.08 93.88 90.96 87.31
Monkey OCR Pro 1.2B 1.2B 83.89 94.31 93.07 90.42
Mineru 2.5 1.2B 87.90 95.94 93.25 92.36
Mineru 2.5 Pro 1.2B 92.46 97.24 93.98 94.56
Paddle VL 0.9B 90.57 96.87 94.34 93.93
Paddle VL 1.5 0.9B 90.79 97.28 94.56 94.21
GLM-OCR 0.9B 93.71 97.74 96.44 95.96
MOSS-OCR-0.3B 0.3B 90.33 95.56 95.01 93.63

OmniDocBench v1.6

使用真实版面标注和官方归一化规则进行评测。

模型 参数量 Table (TEDS) Math (CDM) Text (Edit Similarity) Overall
dolphin 0.3B 76.54 89.52 95.94 87.33
Monkey OCR Pro 1.2B 1.2B 82.95 95.80 97.11 91.95
Mineru 2.5 1.2B 88.41 97.44 97.53 94.46
Mineru 2.5 Pro 1.2B 93.31 97.50 98.26 96.36
Paddle VL 0.9B 90.52 96.97 98.29 95.26
Paddle VL 1.5 0.9B 92.04 96.48 98.32 95.61
GLM-OCR 0.9B 92.06 97.62 98.57 96.08
MOSS-OCR-0.3B 0.3B 89.92 95.66 97.80 94.46

内部专利领域评测

模型 参数量 Table (TEDS) Math (CDM) Overall
dolphin 0.3B 75.97 94.36 85.17
Monkey OCR Pro 1.2B 1.2B 78.39 93.01 85.70
Mineru 2.5 1.2B 84.27 95.28 89.78
Mineru 2.5 Pro 1.2B 87.97 96.56 92.27
Paddle VL 0.9B 85.27 94.85 90.06
Paddle VL 1.5 0.9B 81.76 94.72 88.24
GLM-OCR 0.9B 86.58 96.07 91.33
MOSS-OCR-0.3B 0.3B 91.64 95.34 93.49

单张 RTX 4090 上的推理速度

基于 vLLM 服务的吞吐量。

模型 参数量 QPS (it/s)
Mineru 2.5 1.2B 29.49
MOSS-OCR-0.3B 0.3B 58.77

环境要求

  • Python >= 3.12，推荐使用 uv。
  • 如需加速本地推理或使用 vLLM 部署，需要支持 CUDA 的 GPU。
  • 使用 vLLM 服务时，需要运行仓库内置的适配脚本，让 vLLM 能够注册 MOSS 模型。

固定依赖版本见 pyproject.toml。

模型权重

模型 下载地址 精度
Hiro-MOSS-OCR-0.3B PatSnap/Hiro-MOSS-OCR-0.3B FP32 / BF16

可以直接使用 Hugging Face repo id PatSnap/Hiro-MOSS-OCR-0.3B，也可以将 checkpoint 下载到本地目录用于离线部署。下面的 CUDA Graph 和 vLLM 示例都支持将这两种形式作为 MODEL_PATH。

安装

从源码安装：

git clone https://github.com/patsnap/Hiro-MOSS-OCR
cd Hiro-MOSS-OCR

uv python pin 3.12
uv venv .venv
source .venv/bin/activate
uv sync

# 将 MOSS 适配文件复制到当前环境中的 vLLM 包内。
bash scripts/vllm_adapter.sh

scripts/vllm_adapter.sh 会把 moss_ocr/static/vllm_patches/ 中与当前固定 vLLM 版本匹配的文件复制到已安装的 vllm 包内。请在 uv sync 后运行该脚本；如果重新安装或升级 vLLM，也需要重新运行。

使用方式

1. 快速调用（Transformers AutoModelForCausalLM）

如果只是想快速验证模型，可以直接通过 Hugging Face Transformers 加载并调用：

这个方式实现简单，但推理效率相对较慢，适合快速试用、功能验证或小规模单张图片调用。生产服务、高吞吐或批量推理建议使用下面的 CUDA Graph 或 vLLM 方式。快速调用建议放在单张 GPU 上运行，不建议依赖自动多卡拆分。

import os
os.environ.setdefault("CUDA_VISIBLE_DEVICES", "0")  # 必须在 import torch 前设置

import torch
from transformers import AutoModelForCausalLM

model_id = "PatSnap/Hiro-MOSS-OCR-0.3B"
img_path = "/path/to/your/image.png"
task = "text"  # "math" | "table" | "text"

model = AutoModelForCausalLM.from_pretrained(
    model_id,
    trust_remote_code=True,
    dtype=torch.bfloat16,
    device_map={"": 0},
).eval()

with torch.inference_mode():
    texts = model.generate(img_path, task=task)
print(texts[0])

也可以直接运行仓库内置示例：

uv run python moss_ocr/examples/run_with_transformers.py \
  --model_path PatSnap/Hiro-MOSS-OCR-0.3B \
  --task text \
  --img_path /path/to/your/image.png

2. 使用 CUDA Graph + Transformers 本地推理

可以使用 MOSSv1d6Runner 进行单进程本地推理：

from moss_ocr.inferer.cuda_graph import MOSSv1d6Runner

model_path = "PatSnap/Hiro-MOSS-OCR-0.3B"
# 或：model_path = "/path/to/Hiro-MOSS-OCR-0.3B"
runner = MOSSv1d6Runner(model_path=model_path)

img_path = "/path/to/your/image.png"
task = "text"  # "math" | "table" | "text"

output = runner.run(img=img_path, task=task)
print(output)

也可以直接运行仓库内置示例：

uv run python moss_ocr/examples/run_with_cuda_graph.py \
  --model_path PatSnap/Hiro-MOSS-OCR-0.3B \
  --task text \
  --img_path /path/to/your/image.png

3. 使用 vLLM 服务和 OpenAI 兼容客户端

首先使用 Hugging Face repo id 或本地 checkpoint 启动 vLLM：

# 请先确认当前环境中已经运行过 `bash scripts/vllm_adapter.sh`。
export MODEL_PATH=PatSnap/Hiro-MOSS-OCR-0.3B
# 或：export MODEL_PATH=/path/to/Hiro-MOSS-OCR-0.3B

uv run vllm serve "$MODEL_PATH" \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.9 \
  --max-num-batched-tokens 16384 \
  --port 8088 \
  --served-model-name moss-v1d6-0.3b

然后用 MOSSOCRv1d6vLLMRunner 调用服务。注意 url 需要包含 /v1 后缀：

from moss_ocr.inferer.vllm import MOSSOCRv1d6vLLMRunner

runner = MOSSOCRv1d6vLLMRunner(url="http://0.0.0.0:8088/v1")

img_path = "/path/to/your/image.png"
task = "text"  # "math" | "table" | "text"

response = runner.run(img=img_path, task=task)
print(response.result if response.is_succeed else response.error_message)

CLI 示例：

uv run python moss_ocr/examples/run_with_vllm.py \
  --url http://0.0.0.0:8088/v1 \
  --task text \
  --img_path /path/to/your/image.png

默认的 --served-model-name 应与客户端模型名 moss-v1d6-0.3b 保持一致。如果你修改了服务端名称，请在构造 MOSSOCRv1d6vLLMRunner 时传入 model_path="<your-served-name>"。

4. Web Demo

Gradio Web Demo 会在 demo 进程内使用本地 CUDA Graph 后端。--model_path 可以传入 Hugging Face repo id，也可以传入本地 checkpoint 路径：

uv run python moss_ocr/deploy/moss_ocr_demo.py \
  --model_path PatSnap/Hiro-MOSS-OCR-0.3B \
  --host 0.0.0.0 \
  --port 7788

启动后打开 http://127.0.0.1:7788；如果绑定到 0.0.0.0，也可以直接访问服务器 IP。你可以上传图片，在任务选择中切换公式、表格或段落文本 OCR，也可以展开 Examples 加载仓库内置的示例图片；示例图片位于 moss_ocr/static/img_examples/。

如果需要生成更长结果，可以调大 --max_length；如需调整本地批处理上限，可以设置 --max_batch_size。

注意事项

  • OCR 输出可能存在错误、不完整或结构不准确的情况。用于法律、合规、归档、无障碍、客户交付或其他高风险场景前，请务必人工复核。
  • 请确认你对待处理的图片或文档拥有必要的权利、授权和处理依据。
  • 完整条款和限制请阅读 免责声明。

版权声明

Copyright (c) 2026 Patsnap. 除非适用许可条款明确授权，保留所有权利。

Hiro-MOSS-OCR、Patsnap 以及任何相关名称、徽标、产品名称、服务名称、设计和标语均为 Patsnap 或其关联公司的商标或注册商标。除非明确说明，开源许可证或任何模型许可证均不授予任何商标许可。

致谢