Rukopys-OCR-4B

Rukopys-OCR-4B

从图片中读取乌克兰语手写文档，找出每个文字区域、标注类型，并以结构化 JSON 返回转写内容。这是用于手写数字化的开放 4B 视觉语言模型。

由 ebinan92 在 Hugging Face 上制作。这些说明是 Mindket 根据它的模型页面和模型卡写的，模型自己的文件和许可证在 Hugging Face 上。

简介

它是什么：Rukopys-OCR-4B 用来读取乌克兰语手写文档的图片。它会找出页面上的每个区域，标注类型，并把每个区域转写出的文字以结构化 JSON 返回。ebinan92 为一场手写识别比赛调整了 Qwen3.5-4B 的全部权重来训练它，模型卡称它是获得第三名的参赛方案的一部分。

适合谁：适合需要把乌克兰语手写内容变成数据的人，例如档案管理员、研究人员和搭建文档流程的开发者。

行业 | 谁在用 | 怎么用 | 例子
档案 | 数字化团队 | 把手写页面变成可搜索的文字 | 转写一页扫描的笔记本
教育 | 学校和研究人员 | 数字化学生的手写作业 | 读取一页学校笔记本
软件 | 文档流程开发者 | 把区域框和文字交给其他工具 | 把 JSON 输出载入数据库
研究 | OCR 研究人员 | 研究西里尔文字的手写识别 | 对比公式和表格上的结果

使用其他语言或只处理印刷文字的人可以跳过它，因为它是针对乌克兰语手写调校的。

用在哪里：它通过 Transformers 或 vLLM 在 Python 里运行，模型卡为两者各给了一个脚本。

• 带 Hugging Face Transformers 5.8.1 或更新版本的 Python
• vLLM，使用模型卡里的第二个示例脚本
• Windows、macOS 或 Linux，配合 Python 下载文件

用例 | 谁用 | 得到什么
手写转写 | 档案管理员 | 每个手写区域的文字
页面版面检测 | 开发者 | 归一化 0 到 1000 网格上的区域框
公式和表格 | 研究人员 | 用 LaTeX 写的公式文字，以及用竖线字符分隔的表格文字

如何设置：你需要 Python、较新的 Transformers 和一张文档图片。

• 带 pip 的 Python
• Transformers 5.8.1 或更新版本
• 示例脚本导入的 PIL 和 torch 包
• 存放权重的磁盘空间，BF16 约 9.1 GB
• 一张手写文档的照片或扫描件

1. 用 pip 安装 Hugging Face 的 hub 工具。
2. 用 hf 命令下载模型文件。
3. 确认你的 Transformers 版本是 5.8.1 或更新。
4. 保存下一节的 Python 脚本，并让它指向你的图片。

pip install -U huggingface_hub
hf download ebinan92/Rukopys-OCR-4B

如何使用：用模型卡里的 Transformers 脚本处理你的图片。提示词要原样保留，因为模型卡说训练时用的提示词不应更改。脚本会发送图片和提示词，不采样地生成最多 8192 个新 token，然后打印 JSON。

from PIL import Image
import torch
from transformers import AutoModelForMultimodalLM, AutoProcessor

MODEL_ID = "ebinan92/Rukopys-OCR-4B"
PROMPT = (
    "Detect every text region in this Ukrainian handwritten document and "
    "return a JSON array of regions. Each region has bbox (x1 y1 x2 y2 in "
    "0..1000 normalized image coordinates), type (handwritten | printed | "
    "formula | table | annotation | image | graph), and text (transcription; "
    "empty for image/graph; LaTeX for formula; pipe-separated for table)."
)

processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForMultimodalLM.from_pretrained(
    MODEL_ID, dtype=torch.bfloat16, device_map="auto"
)
image = Image.open("document.jpg").convert("RGB")
messages = [{
    "role": "user",
    "content": [{"type": "image"}, {"type": "text", "text": PROMPT}],
}]
text = processor.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True, enable_thinking=False
)
inputs = processor(text=[text], images=[image], return_tensors="pt").to(model.device)

with torch.inference_mode():
    output_ids = model.generate(**inputs, max_new_tokens=8192, do_sample=False)

new_tokens = output_ids[:, inputs["input_ids"].shape[1]:]
print(processor.batch_decode(new_tokens, skip_special_tokens=True)[0])

工具 | 作用
AutoProcessor | 把图片和提示词变成模型输入
AutoModelForMultimodalLM | 以 bfloat16 在可用设备上加载模型权重
apply_chat_template | 生成关闭思考模式的聊天文本
generate | 生成转写结果，最多 8192 个新 token

模型卡还给了一个 vLLM 脚本，做同样的事，最大长度为 16384，每个提示一张图片。

区域类型 | 文字内容
handwritten, printed, annotation | 转写出的文字
formula | 用 LaTeX 写的公式
table | 表格文字，单元格用竖线字符分隔
image, graph | 空文本

示例：你把一张乌克兰语手写页面的照片连同模型卡里的提示词一起交给它。它返回一个 JSON 列表，每个区域一项，每项有框、类型和文字，就像下面这个手写行的例子。

[
  {
    "bbox": [84, 107, 912, 168],
    "type": "handwritten",
    "text": "Приклад рукописного тексту"
  }
]

新手与专家：这是一个读手写字的模型。你给它看一页手写内容的图片，它会交还文字以及文字所在的位置。第一件可以试的小事，就是在一张清晰的照片上运行示例脚本，读一读它打印出的 JSON。

它只回答一条固定的提示词，并把每个区域放在 0 到 1000 的网格上。解码是贪心的，思考模式关闭，vLLM 示例则通过最小和最大像素数来限制图片大小。训练混合了 RUKOPYS 的金标和银标数据、外部的西里尔手写数据集和伪标签，其中一部分来自 Gemini。

给它一张手写页面的照片
发送固定的训练提示词
模型找出文字区域
每个区域得到一个类型
你收到带框和文字的 JSON

注意事项：它面向乌克兰语手写，精度降低后权重会更轻。

Title: 权重大小估算
BF16: 9.1 GB
4 位估算: 2.3 GB

• 语言：为乌克兰语手写而做，记录中列出乌克兰语和俄语。
• 提示词：保持训练提示词不变。
• License: 权重使用 Apache 2.0。
• 训练数据：这些数据集不会再分发，并保留各自的许可证，包括 CC BY 4.0、CC BY-SA 4.0、MIT 和 Apache 2.0。
• Cost to run: 没有提到费用。
• Data it reaches: 你交给它的图片和你下载的模型文件。模型卡没有提到联网或账号访问。

Hugging Face 上的数据（2026年11月13日）

• 任务：image text to text
• 框架：transformers
• 参数量：4.5B
• Weights: about 9.1 GB in BF16; about 2.3 GB at 4-bit (estimate)
• Formats: Safetensors
• 最近 30 天下载：86
• 点赞：7
• 许可证：apache-2.0
• 语言：uk, ru
• 基于：Qwen/Qwen3.5-4B
• Quantized versions: 1
• 标签：transformers, safetensors, qwen3_5, image-text-to-text, handwritten-text-recognition, ukrainian, cyrillic, document-ai, layout-analysis, qwen3.5, conversational

链接

• 模型：https://huggingface.co/ebinan92/Rukopys-OCR-4B
• 文件：https://huggingface.co/ebinan92/Rukopys-OCR-4B/tree/main

获取模型

用 Hugging Face 的命令行下载它的文件：

pip install -U huggingface_hub
hf download ebinan92/Rukopys-OCR-4B

然后按它的模型卡使用它。这个工具包里没有会自己运行的东西。