wunu commited on
Commit
b546dcf
·
verified ·
1 Parent(s): b2890ab

Add Chinese model card and usage guide banner

Browse files

Changes:
- README.md: replace the top link row with a Usage Guide panel (Free API / Agent Skill / Self-hosting / Mobile App), keep the body untouched.
- README_zh.md: new Chinese model card, section-by-section match with the English card.

Files changed (2) hide show
  1. README.md +41 -1
  2. README_zh.md +326 -0
README.md CHANGED
@@ -23,7 +23,47 @@ library_name: minicpm-ocr
23
  <a href="https://github.com/OpenBMB/MiniCPM"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/minicpm-logo.jpg" width="300" alt="MiniCPM logo"></a>
24
  </p>
25
 
26
- Demo ([CN](https://platform.modelbest.cn/console/playground/document-parse) / [Global](https://platform.modelbest.ai/console/playground/document-parse)) · [GitHub](https://github.com/OpenBMB/MiniCPM-OCR) · [Free API](https://platform.modelbest.ai/console/docs/api/document-parse) · [SDK usage](#use-with-the-minicpm-ocr-sdk) · [DSpark](https://huggingface.co/openbmb/MiniCPM-OCR-1.0-DSpark) · [Skill](https://github.com/OpenBMB/MiniCPM-OCR#skill)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
27
 
28
  </div>
29
 
 
23
  <a href="https://github.com/OpenBMB/MiniCPM"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/minicpm-logo.jpg" width="300" alt="MiniCPM logo"></a>
24
  </p>
25
 
26
+ <p align="center">
27
+ <b>Usage Guide</b>
28
+ </p>
29
+
30
+ <table align="center" width="100%">
31
+ <tr>
32
+ <td align="center" width="25%" valign="top">
33
+ <b>🚀 Free API</b><br/>
34
+ <sub>Try it online for free, then call the API from your own code.</sub><br/>
35
+ Playground (<a href="https://platform.modelbest.cn/console/playground/document-parse">CN</a> /
36
+ <a href="https://platform.modelbest.ai/console/playground/document-parse">Global</a>)<br/>
37
+ API docs (<a href="https://platform.modelbest.cn/console/docs/api/document-parse">CN</a> /
38
+ <a href="https://platform.modelbest.ai/console/docs/api/document-parse">Global</a>)
39
+ </td>
40
+ <td align="center" width="25%" valign="top">
41
+ <b>🤖 Agent Skill</b><br/>
42
+ <sub>One prompt: the agent installs it and parses your first document.</sub><br/>
43
+ <a href="https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/SKILL_en.md">SKILL.md</a>
44
+ </td>
45
+ <td align="center" width="25%" valign="top">
46
+ <b>💻 Self-hosting</b><br/>
47
+ <sub>vLLM / SGLang / llama.cpp / Ollama, plus an official Docker image. Data stays on your side.</sub><br/>
48
+ <a href="https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_tutorial_en.md">Deployment guide</a>
49
+ </td>
50
+ <td align="center" width="25%" valign="top">
51
+ <b>📱 Mobile App</b><br/>
52
+ <sub>On-device and offline. Document parsing is iOS-only for now.</sub><br/>
53
+ <a href="https://github.com/OpenBMB/MiniCPM-V-Apps/blob/main/README.md#11-ios-demo">iOS Demo</a>
54
+ </td>
55
+ </tr>
56
+ </table>
57
+
58
+ <p align="center">
59
+ Demo (<a href="https://platform.modelbest.cn/console/playground/document-parse">CN</a> /
60
+ <a href="https://platform.modelbest.ai/console/playground/document-parse">Global</a>) &nbsp;·&nbsp;
61
+ <a href="https://github.com/OpenBMB/MiniCPM-OCR">GitHub</a> &nbsp;·&nbsp;
62
+ <a href="#use-with-the-minicpm-ocr-sdk">SDK usage</a> &nbsp;·&nbsp;
63
+ <a href="https://huggingface.co/openbmb/MiniCPM-OCR-1.0-DSpark">DSpark</a> &nbsp;·&nbsp;
64
+ <a href="https://discord.gg/JE8KQqtdn">Discord</a>
65
+ &nbsp;|&nbsp; <a href="https://huggingface.co/openbmb/MiniCPM-OCR-1.0/blob/main/README_zh.md">中文</a>
66
+ </p>
67
 
68
  </div>
69
 
README_zh.md ADDED
@@ -0,0 +1,326 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <div align="center">
2
+
3
+ <p align="center">
4
+ <img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/release-hero.svg" alt="MiniCPM-OCR:快速、准确地将文档解析为文本、表格和公式,通过闪电箭头连接文档与结构化结果;decision model 辅助标出需要复核的区域(示意图)。" width="100%">
5
+ </p>
6
+
7
+ <p align="center">
8
+ <a href="https://github.com/OpenBMB/MiniCPM"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/minicpm-logo.jpg" width="300" alt="面壁小钢炮 MiniCPM"></a>
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_1dot0_zh.md"><strong>MiniCPM-OCR 1.0 模型指南</strong></a>&ensp;<a href="https://huggingface.co/openbmb/MiniCPM-OCR-1.0" title="Hugging Face"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/huggingface_logo-noborder.svg" width="19" height="18" alt="Hugging Face"></a>&ensp;<a href="https://modelscope.cn/models/OpenBMB/MiniCPM-OCR-1.0" title="ModelScope"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/modelscope_logo_padded.svg" width="25" height="14" alt="ModelScope"></a>
13
+ &emsp;
14
+ <a href="https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_jev_zh.md"><strong>MiniCPM-OCR Jev 模型指南</strong></a>&ensp;<a href="https://huggingface.co/openbmb/MiniCPM-OCR-Jev" title="Hugging Face"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/huggingface_logo-noborder.svg" width="19" height="18" alt="Hugging Face"></a>&ensp;<a href="https://modelscope.cn/models/OpenBMB/MiniCPM-OCR-Jev" title="ModelScope"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/modelscope_logo_padded.svg" width="25" height="14" alt="ModelScope"></a>
15
+ </p>
16
+
17
+ <p align="center">
18
+ <b>使用指南</b>
19
+ </p>
20
+
21
+ <table align="center" width="100%">
22
+ <tr>
23
+ <td align="center" width="25%" valign="top">
24
+ <b>🚀 免费 API</b><br/>
25
+ <sub>零部署,先在线免费体验,再调接口。</sub><br/>
26
+ 体验(<a href="https://platform.modelbest.cn/console/playground/document-parse">国内</a> /
27
+ <a href="https://platform.modelbest.ai/console/playground/document-parse">海外</a>)<br/>
28
+ API 文档(<a href="https://platform.modelbest.cn/console/docs/api/document-parse">国内</a> /
29
+ <a href="https://platform.modelbest.ai/console/docs/api/document-parse">海外</a>)
30
+ </td>
31
+ <td align="center" width="25%" valign="top">
32
+ <b>🤖 Agent Skill</b><br/>
33
+ <sub>一句话,让编码 Agent 自己装好环境、跑通第一篇文档。</sub><br/>
34
+ <a href="https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/SKILL.md">SKILL.md</a>
35
+ </td>
36
+ <td align="center" width="25%" valign="top">
37
+ <b>💻 本地部署</b><br/>
38
+ <sub>vLLM / SGLang / llama.cpp / Ollama,另有官方 Docker 镜像,数据不出内网。</sub><br/>
39
+ <a href="https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_tutorial.md">部署教程</a>
40
+ </td>
41
+ <td align="center" width="25%" valign="top">
42
+ <b>📱 手机 APP</b><br/>
43
+ <sub>端侧运行,断网可用。文档解析目前仅 iOS。</sub><br/>
44
+ <a href="https://github.com/OpenBMB/MiniCPM-V-Apps/blob/main/README.md#11-ios-demo">iOS Demo</a>
45
+ </td>
46
+ </tr>
47
+ </table>
48
+
49
+ <p align="center">
50
+ 体验平台(<a href="https://platform.modelbest.cn/console/playground/document-parse">国内</a> /
51
+ <a href="https://platform.modelbest.ai/console/playground/document-parse">海外</a>) &nbsp;·&nbsp;
52
+ <a href="https://github.com/OpenBMB/MiniCPM-OCR">GitHub</a> &nbsp;·&nbsp;
53
+ <a href="https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_tutorial.md">SDK</a> &nbsp;·&nbsp;
54
+ <a href="https://huggingface.co/openbmb/MiniCPM-OCR-1.0-DSpark">DSpark</a> &nbsp;·&nbsp;
55
+ <a href="https://discord.gg/JE8KQqtdn">Discord</a>
56
+ &nbsp;|&nbsp; <a href="https://huggingface.co/openbmb/MiniCPM-OCR-1.0/blob/main/README.md">English</a>
57
+ </p>
58
+
59
+ </div>
60
+
61
+ **MiniCPM-OCR 1.0**(1.3B)是 [MiniCPM-V/o](https://github.com/openbmb/MiniCPM-V) 系列中首个 OCR 专用模型,聚焦于以文字为中心的文档理解——文字、表格、公式、图表、印章与结构化信息抽取——并在真实拍摄场景下兼顾解析质量与处理速度。
62
+
63
+ ## 核心亮点
64
+
65
+ - 🏆 **SOTA 级文档解析**:在面向真实场景文档解析的基准 **Real5-OmniDocBench 上取得 93.68**,并在 OmniDocBench v1.6、Wild-OmniDocBench 和 olmOCR-Bench 上取得领先结果。支持中英文文档与 PDF,涵盖扫描件、弯曲页面、拍摄照片、倾斜页面和翻拍文档。
66
+ - ⚡ **高效推理**:借助 DSpark 解码加速([BF16](https://huggingface.co/openbmb/MiniCPM-OCR-1.0-DSpark)、[GGUF](https://huggingface.co/openbmb/MiniCPM-OCR-1.0-DSpark-gguf)),端到端处理效率提升 **55%**;吞吐量约为 PaddleOCR-VL-1.6 的 **1.49 倍**、MinerU2.5 Pro 的 **3.62 倍**。
67
+ - 🔍 **通用识别与信息抽取**:**OCRBench v2 得分 54.7**,并提供关键信息抽取(KIE),便于下游自动化处理。
68
+ - 🛠️ **易部署、易开发**:发布首日即支持 **vLLM、SGLang、llama.cpp 和 Ollama**,提供多种量化版本与多芯片适配。支持二次微调,并提供 pip SDK、完整 API 和 Agent 工作流。在线体验:[HF Spaces](https://huggingface.co/spaces/openbmb/MiniCPM-OCR) · [CN](http://82.157.64.212:10111/playground/document-parse) · [官方国内](https://platform.modelbest.cn/console/playground/document-parse) · [官方海外](https://platform.modelbest.ai/console/playground/document-parse)。
69
+
70
+ ## 更高吞吐下的 SOTA 解析质量
71
+
72
+ 在所比较的开源 OCR 模型中,MiniCPM-OCR 1.0 达到 **1.2 页/秒**,并在 OmniDocBench v1.6、Real5-OmniDocBench、Wild-OmniDocBench 和 olmOCR-Bench 四个基准上取得最高的等权平均分。
73
+
74
+ <p align="center"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/efficiency-performance-en.png" alt="开源 OCR 模型的吞吐与解析质量对比。横轴:每秒页数(对数刻度)。纵轴:四个文档解析基准的等权平均分。" width="90%"></p>
75
+
76
+ <sub>平均分为四个基准的等权平均,所有模型均采用加速配置。配置与复现方式见[复现指南](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/benchmark_reproduction_en.md);各模型吞吐量见[模型指南](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_1dot0_en.md#throughput)。</sub>
77
+
78
+ ## 基准评测对比
79
+
80
+ <p align="center"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/benchmark-radar.png" alt="MiniCPM-OCR 1.0 与其他 OCR 模型在六个基准上的雷达图对比。" width="80%"></p>
81
+
82
+ ### MiniCPM-OCR 1.0 完整评测结果
83
+
84
+ <p align="center"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/ocr-benchmarks.png" alt="OmniDocBench v1.6、Real5-OmniDocBench、Wild-OmniDocBench、olmOCR-Bench、CHAOS-Bench 与 OCRBench v2 上的详细 OCR 模型评测结果。" width="100%"></p>
85
+
86
+ <p align="center"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/benchmark-comparison.png" alt="Real5-OmniDocBench、Wild-OmniDocBench、OmniDocBench v1.6、olmOCR-Bench、OCRBench v2 与 CHAOS-Bench 的逐基准柱状图。" width="100%"></p>
87
+
88
+ 每个子图保留各自基准的原始分数,分数越高越好;不同基准之间的分数不可直接比较。测试配置与复现步骤见[复现指南](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/benchmark_reproduction_en.md),逐基准的讨论见[模型指南](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_1dot0_en.md#evaluation)。
89
+
90
+ ### 吞吐量
91
+
92
+ 在 NVIDIA GeForce RTX 5090 上,使用 OmniDocBench v1.6 的全部 1651 张图片、图片级并发数为 1、并采用各系统自身的加速配置,MiniCPM-OCR 1.0 达到 **1.2 页/秒**(相对吞吐量 **1.00×**,数值越大越快)。
93
+
94
+ <p align="center"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/throughput-comparison.png" alt="采用加速配置的 OCR 系统吞吐量对比;MiniCPM-OCR 1.0 达到 1.2 页/秒。" width="100%"></p>
95
+
96
+ 并发数 1 指图片级并发:同一页内的各个区域仍会并行识别。实际吞吐量还取决于页面内容、推理后端、并发数和硬件。
97
+
98
+ ## 效果示例
99
+
100
+ 从左到右依次为:原始文档、检测到的版面、渲染后的 Markdown。
101
+
102
+ **英文文档**
103
+
104
+ <p align="center"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/minicpm-english-examples-3-column.gif" alt="英文文档动图:原始文档、检测到的版面、渲染后的 Markdown。" width="100%"></p>
105
+
106
+ **中文文档**
107
+
108
+ <p align="center"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/minicpm-chinese-examples-3-column.gif" alt="中文文档动图:原始文档、检测到的版面、渲染后的 Markdown。" width="100%"></p>
109
+
110
+ <details>
111
+ <summary><b>更多示例</b></summary>
112
+
113
+ 原始文档与解析结果并排展示。
114
+
115
+ **英文文档**
116
+
117
+ <p align="center"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/minicpm-ocr-english-cases.png" alt="英文示例的输入与结果对比:手写体、历史与扫描文档、报纸、财务报表及关键信息抽取。" width="100%"></p>
118
+
119
+ **中文文档**
120
+
121
+ <p align="center"><img src="https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/assets/minicpm-ocr/minicpm-ocr-chinese-cases.png" alt="中文示例的输入与结果对比:手写笔记、复杂公式、报纸、财务报表、盖章文档、插图及关键信息抽取。" width="100%"></p>
122
+
123
+ </details>
124
+
125
+ ## 模型架构
126
+
127
+ | 项目 | 说明 |
128
+ | :--- | :--- |
129
+ | 参数量 | 1.3B |
130
+ | 基座 | 在 MiniCPM-V 4.6 基础上针对 OCR 训练 |
131
+ | 组件 | SigLIP 视觉编码器 + Qwen3.5 语言模型 |
132
+ | 主要语言 | 中文、英文 |
133
+ | 任务 | 文字、表格、公式、图表、印章和关键信息抽取 |
134
+ | 解析流程 | MiniCPM-OCR 1.0 + PP-DocLayoutV3 版面模型 + `minicpmvocr` SDK |
135
+ | 视觉 token | 4× 压缩,`scale_resolution` 448,最多 9 个切片 |
136
+
137
+ ### 解析流程
138
+
139
+ 整页解析由 [`minicpm-ocr` SDK](https://pypi.org/project/minicpm-ocr/) 统一编排为**两阶段流水线**:两个阶段使用不同的模型、运行在相互独立的环境中,也可以部署在不同的机器上:
140
+
141
+ - **阶段一 · 版面检测(SDK 环境)**:PP-DocLayoutV3 版面模型检测文档区域(文字、表格、公式、图表、印章等)并确定阅读顺序,SDK 按区域切块。该阶段在 SDK 环境中本地运行,依赖 PaddlePaddle / PaddleX。
142
+ - **阶段二 · 区域识别(推理服务)**:SDK 通过 HTTP 将每个切块发送给 MiniCPM-OCR 1.0 推理服务(由 vLLM、SGLang、llama.cpp 或 Ollama 部署),提示词按区域类型选择,最后按阅读顺序拼接为 Markdown / JSON。
143
+
144
+ <p align="center"><img src="https://huggingface.co/openbmb/MiniCPM-OCR-1.0/resolve/main/assets/parsing_pipeline.svg" alt="解析流程图:在 minicpm-ocr SDK 环境中,PP-DocLayoutV3 版面模型检测并切分文档区域;每个切块通过 HTTP 发送给独立的 MiniCPM-OCR 1.0 识别服务(vLLM、SGLang、llama.cpp 或 Ollama);SDK 再按阅读顺序拼接为 Markdown 与 JSON。" width="90%"></p>
145
+
146
+ 更多关于架构、解析流程、部署方式和评测拆解,见[模型指南](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_1dot0_en.md)。
147
+
148
+ ## 快速开始
149
+
150
+ ### 在线体验
151
+
152
+ 要快速体验以文字为中心的文档理解与结构化信息抽取,推荐使用 [HF Spaces](https://huggingface.co/spaces/openbmb/MiniCPM-OCR)、[CN](http://82.157.64.212:10111/playground/document-parse)、[官方国内](https://platform.modelbest.cn/console/playground/document-parse)、[官方海外](https://platform.modelbest.ai/console/playground/document-parse) / [API](https://platform.modelbest.ai/console/docs/api/document-parse)。
153
+
154
+ ### 使用 MiniCPM-OCR SDK
155
+
156
+ > **使用 CLI 或 Python API 前的必要步骤:** 请先部署并启动 OCR 模型服务,等待其可以正常接收请求。下面的 SDK 示例是该服务的客户端,不会自动部署或启动 OCR 模型服务。
157
+
158
+ 使用官方 `minicpm-ocr` SDK 解析本地图片或 PDF:它会用 PP-DocLayoutV3 检测版面、逐区域识别,并按阅读顺序保存结构化 JSON 和 Markdown。
159
+
160
+ 安装 Python 3.10+ 与 SDK:
161
+
162
+ ```bash
163
+ pip install "minicpm-ocr[all]"
164
+ ```
165
+
166
+ 按你的平台参考[安装指南](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_tutorial_en.md#1-set-up-the-sdk-environment)安装 minicpm-ocr。
167
+
168
+ #### 前置条件:部署并启动模型服务
169
+
170
+ 在运行 CLI 或 Python API 之前,请先按[部署指南](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_tutorial_en.md#3-start-the-service)为 `openbmb/MiniCPM-OCR-1.0` 部署并启动一个 vLLM 识别服务。示例假设服务地址为 `http://127.0.0.1:8080`、服务模型名为 `minicpm-ocr`、版面检测使用 NVIDIA GPU。请按实际部署调整地址、后端与设备;若希望示例无需改动即可运行,请把服务配置为监听 `8080` 端口并以 `minicpm-ocr` 作为模型名。
171
+
172
+ #### CLI
173
+
174
+ **运行以下命令前,请先启动上文所述的模型服务并等待其就绪。** 将一张本地图片保存为 `demo.png`,然后执行:
175
+
176
+ ```bash
177
+ minicpmvocr parse demo.png \
178
+ --backend vllm \
179
+ --server-url http://127.0.0.1:8080 \
180
+ --model minicpm-ocr \
181
+ --device cuda:0 \
182
+ --set run.run_root=output \
183
+ --output output/demo.md
184
+ ```
185
+
186
+ CLI 会在需要时自动把 PP-DocLayoutV3 下载到 `models/PP-DocLayoutV3_infer/`。最终 Markdown 保存到 `output/demo.md`;结构化 JSON 和逐页 Markdown 保存在 `output/<run_tag>/results_json/` 与 `output/<run_tag>/output/`。
187
+
188
+ 解析 PDF 时,把 `demo.png` 换成本地 PDF 路径即可。使用 `--device cpu` 可在 CPU 上做版面检测。运行 `minicpmvocr parse --help` 查看全部 CLI 选项。
189
+
190
+ #### Python API
191
+
192
+ **执行本 Python 示例前,上文所述的模型服务必须已经在运行。** 请把 `engine.server_url` 和 `engine.model_name` 设置为与该服务一致。
193
+
194
+ 将一张本地图片保存为 `demo.png`,然后执行:
195
+
196
+ ```python
197
+ from importlib.resources import files
198
+ from pathlib import Path
199
+
200
+ from minicpmvocr import load_config, pipelined_run
201
+ from minicpmvocr.layouts.download import ensure_layout_model
202
+
203
+
204
+ def main():
205
+ layout_model = ensure_layout_model(Path("models/PP-DocLayoutV3_infer"))
206
+
207
+ cfg = load_config(
208
+ str(files("minicpmvocr").joinpath("configs/minicpmvocr.yaml")),
209
+ overrides={
210
+ "input": {"file_path": str(Path("demo.png").resolve())},
211
+ "engine": {
212
+ "type": "vllm",
213
+ "server_url": "http://127.0.0.1:8080",
214
+ "model_name": "minicpm-ocr",
215
+ },
216
+ "layout": {
217
+ "model_dir": str(layout_model),
218
+ "device": "cuda:0",
219
+ },
220
+ "pipeline": {"overlap_layout": True},
221
+ "run": {"run_root": str(Path("output").resolve())},
222
+ },
223
+ )
224
+
225
+ pipelined_run(cfg)
226
+
227
+ print("JSON directory:", cfg["_meta"]["result_json_dir"])
228
+ print("Markdown directory:", cfg["_meta"]["output_dir"])
229
+
230
+
231
+ if __name__ == "__main__":
232
+ main()
233
+ ```
234
+
235
+ `ensure_layout_model()` 会在缺失时下载官方版面模型。结果写入 `output/<run_tag>/results_json/` 和 `output/<run_tag>/output/`。解析 PDF 时,把 `demo.png` 换成本地 PDF 路径即可。
236
+
237
+ 若要在 CPU 上做版面检测,把 `layout.device` 设为 `cpu`。若使用 llama.cpp 提供的 [GGUF 权重](https://huggingface.co/openbmb/MiniCPM-OCR-1.0-gguf),把 `engine.type` 设为 `llamacpp`,并用 `engine.max_model_len` 匹配服务的上下文长度。
238
+
239
+ 配置说明与文档级 Markdown 导出见 [SDK API 参考](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_sdk_api_en.md)。
240
+
241
+ ### Agent Skill
242
+
243
+ 也可以让编码 Agent 按 [Agent Skill](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/SKILL_en.md) 配置环境、下载模型并解析第一篇文档。
244
+
245
+ ```text
246
+ Read and execute https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/SKILL_en.md
247
+ ```
248
+
249
+ ### 模型微调
250
+
251
+ [LLaMA-Factory](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/llamafactory_minicpm_ocr_french_en.md) · [ms-swift](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/swift_minicpm_ocr_french_en.md) —— 数据准备、冻结多模态投影器的全参数 SFT、训练与评测(法文手写文本行)。
252
+
253
+ ### 识别指南
254
+
255
+ <table>
256
+ <thead>
257
+ <tr>
258
+ <th>任务</th>
259
+ <th>区域</th>
260
+ <th>提示词</th>
261
+ <th>输出</th>
262
+ </tr>
263
+ </thead>
264
+ <tbody>
265
+ <tr>
266
+ <td rowspan="6">以文字为中心的文档理解</td>
267
+ <td>文本块 / 段落 / 标题 / 页面</td>
268
+ <td><code>Text Recognition:</code></td>
269
+ <td>纯文本</td>
270
+ </tr>
271
+ <tr>
272
+ <td>表格</td>
273
+ <td><code>Table Recognition:</code></td>
274
+ <td>HTML 表格(SDK 后处理)</td>
275
+ </tr>
276
+ <tr>
277
+ <td>公式</td>
278
+ <td><code>Formula Recognition:</code></td>
279
+ <td>LaTeX</td>
280
+ </tr>
281
+ <tr>
282
+ <td>行内公式</td>
283
+ <td><code>Text Recognition:</code></td>
284
+ <td>LaTeX</td>
285
+ </tr>
286
+ <tr>
287
+ <td>印章</td>
288
+ <td><code>Seal Recognition:</code></td>
289
+ <td>纯文本</td>
290
+ </tr>
291
+ <tr>
292
+ <td>图表</td>
293
+ <td><code>Chart to Table:</code></td>
294
+ <td>HTML 表格(SDK 后处理)</td>
295
+ </tr>
296
+ <tr>
297
+ <td>结构化信息抽取</td>
298
+ <td>指定字段</td>
299
+ <td><code>Extract the "field", .... Format the output as a JSON object with keys: "field", .... If an item is not in the image, use "###".</code></td>
300
+ <td>JSON</td>
301
+ </tr>
302
+ </tbody>
303
+ </table>
304
+
305
+ ## 相关权重
306
+
307
+ | 格式 | Hugging Face | ModelScope |
308
+ | :--- | :--- | :--- |
309
+ | BF16(原始)**(本仓库)** | [🤗](https://huggingface.co/openbmb/MiniCPM-OCR-1.0) | [ModelScope](https://modelscope.cn/models/OpenBMB/MiniCPM-OCR-1.0) |
310
+ | GGUF(llama.cpp) | [🤗](https://huggingface.co/openbmb/MiniCPM-OCR-1.0-gguf) | [ModelScope](https://modelscope.cn/models/OpenBMB/MiniCPM-OCR-1.0-gguf) |
311
+ | AWQ W4A16 | [🤗](https://huggingface.co/openbmb/MiniCPM-OCR-1.0-AWQ) | [ModelScope](https://modelscope.cn/models/OpenBMB/MiniCPM-OCR-1.0-AWQ) |
312
+ | GPTQ W4A16 | [🤗](https://huggingface.co/openbmb/MiniCPM-OCR-1.0-GPTQ) | [ModelScope](https://modelscope.cn/models/OpenBMB/MiniCPM-OCR-1.0-GPTQ) |
313
+ | DSpark 草稿模型(BF16) | [🤗](https://huggingface.co/openbmb/MiniCPM-OCR-1.0-DSpark) | [ModelScope](https://modelscope.cn/models/OpenBMB/MiniCPM-OCR-1.0-DSpark) |
314
+ | DSpark 草稿模型(GGUF) | [🤗](https://huggingface.co/openbmb/MiniCPM-OCR-1.0-DSpark-gguf) | [ModelScope](https://modelscope.cn/models/OpenBMB/MiniCPM-OCR-1.0-DSpark-gguf) |
315
+
316
+ DSpark **要求主模型与草稿模型来自同一发布版本** —— 不要把草稿权重与其他主权重混用。详见 [DSpark 加速](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_tutorial_en.md#3-start-the-service)。
317
+
318
+ 如需对 OCR 质量进行评估(自动接受、人工复核路由、跨模型 best-of-N),参见 [MiniCPM-OCR Jev](https://huggingface.co/openbmb/MiniCPM-OCR-Jev)。
319
+
320
+ ## 常见问题
321
+
322
+ 安装、模型下载、显存、输入格式与异常输出:[FAQ](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/faq_en.md)。
323
+
324
+ ## 许可
325
+
326
+ 模型权重、代码与文档均按 [Apache License 2.0](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/LICENSE) 发布。