在 4GB 显存 GPU 上跑 Unlimited-OCR-2:踩坑记录、性能实测与使用建议
测试环境: Windows 11、GTX 1650 Ti 4GB、32GB 内存、驱动 621.24、Python 3.10

一、为什么值得尝试:什么是 Unlimited-OCR-2?
传统的 OCR 1.0 流水线(如 Tesseract、PaddleOCR)将检测、识别、版面分析拆为多步,链路繁琐且误差层层累加;而以 GOT-OCR、DeepSeek-OCR 为代表的 OCR 2.0 虽实现了端到端转录,但在面对长文档时,全注意力机制又会导致显存与计算量二次方膨胀。
2026 年 10 月,百度开源了 Unlimited-OCR-2(论文标榜开启 OCR 3.0 无限视野解析时代)。相比传统管线与同类模型,它的核心优势非常鲜明:
1. 核心优势与特点
- 首创 SR-SWA 稀疏注意力(突破长文档瓶颈):模拟人类抄书“聚焦当前页、偶瞥前文”的阅读直觉,通过页面门控与块稀疏路由把活跃视觉池固定在常数容量($O(1)$ 复杂度),彻底解决长文档显存爆炸与降速问题;百页基准下单步解码提速 7 倍,轻松应对超长篇幅。
- 3.3B MoE 极致能效比(活跃仅 0.5B):SAM+CLIP 视觉编码器搭配 DeepSeek-V2 MoE 解码器,总参数 3.3B 但每个 token 仅激活约 500M 参数,Q4 量化后权重仅 2.0GB,兼顾大模型理解力与极低硬件门槛。
- 端到端「全要素」结构化输出:一次推理直接输出正文、层级标题、阅读顺序及各区块坐标;复杂表格直接还原为 HTML/Markdown,数学公式转录为 LaTeX,无需拼装任何后处理检测模型。
- 兼顾精细与快速的双视觉模式:既支持密集小字/公式优先的 gundam 动态切块模式,也支持速度提升数倍、显存极度友好的 base 全局模式。
2. 为什么还要折腾在 4GB 笔记本 GPU 上跑?
Unlimited-OCR-2 原生基于 HuggingFace Transformers,官方推荐跑在配有 A800/H800 的 SGLang/vLLM 高性能服务器上。
但既然它的 总参数仅 3.3B、激活仅 0.5B,如果能把它量化压进消费级边缘显卡,无疑意味着我们无需云端 API 费用、无需昂贵工作站、不用担心敏感文档外泄,就能在本地拥有一台完全离线的高性能专业级 OCR 引擎。
本文便记录在配置极为紧凑的一块 4GB 显存笔记本独立显卡(GTX 1650 Ti) 上,通过 llama.cpp GGUF 量化运行时把 Unlimited-OCR-2 跑起来的全过程、性能测试及避坑指南。
二、模型架构关键点
在进入部署之前,有几个概念值得先理解,不然后面的配置选项会显得莫名其妙。
1. 解码器是 DeepSeek-V2 MoE,12 层
每个 token 只激活少量专家,推理时活跃参数量远小于总参数。Q4_K_M 量化后权重文件约 2GB,但实际 VRAM 占用要加上 KV Cache、视觉编码器和激活值缓冲区。
2. 注意力机制是自研的 DASH (SR-SWA)
这是 v2 和 v1 最本质的区别,也是不能直接用普通 llama.cpp 加载的原因: - 位置编码不是普通的 token 序号 RoPE,而是「页面 2D RoPE」:每个 token 携带「页内第几个 token」和「第几页」两个维度。 - 注意力不是全注意力,而是路由稀疏注意力(DASH):每个 token 只看最近 128 个 token,加上路由器从当前页图像里选出的最相关 12 个 32-token 块。
用 v1 的方式转换 v2 能跑,但单页只有约 5.6% 的准确率;正确实现后单页字符相似度能达到 100%。
3. 视觉编码器是 SAM + CLIP
存在独立的 mmproj-Unlimited-OCR-2-F16.gguf 文件(787MB),每种精度的主模型都要搭配它。它可以放在 GPU 或 CPU 上运行,是 4GB 显存下最关键的调节旋钮之一。
三、安装部署流程
3.1 运行时选型:为什么不自己编译
第一直觉是拉 llama.cpp 源码、应用补丁、自行编译。这条路在 Windows 上会撞上一个隐蔽的硬墙:
CUDA 12.1 对 MSVC 编译器版本有硬限制。host_config.h 里写着 _MSC_VER < 1940,而 VS2022 17.10 以后 MSVC 的版本就超过了这个上限(实测 17.11 对应 _MSC_VER 1941)。加上 -allow-unsupported-compiler 能绕过第一个报错,但紧接着会撞上 MSVC 19.41 STL 头文件的不兼容,依然无法编译通过。
好消息是,社区已经把这条路打通了。RX5950XT/Unlimited-OCR-2-GGUF 仓库提供了一个 2MB 的 Windows 叠加包 llama-b11913-unlimited-ocr2-win-x64.zip,里面只有两个文件:打了补丁的 llama.dll 和 mtmd.dll,覆盖到官方 b11913 预编译包上即可,完全不需要自己编译。
另外,VS2022 自带了 cmake(路径在 ...CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe),只是不在 PATH 里,这个坑也不少人踩。
3.2 实际安装步骤
# 1. 建独立虚拟环境(base 环境有 torch/transformers,直接装 gradio 易冲突)
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
# 2. 下载运行时
# 优先 CUDA 13.4(官方 b11913 包),驱动 621.24 实测可用
# 备选:-Variant vulkan(无需 CUDA,纯 Vulkan)
powershell -ExecutionPolicy Bypass -File scripts\setup_llama.ps1
# 3. 下载模型(2.0GB Q4_K_M + 787MB mmproj,共约 2.8GB)
# 若下载慢,可设 $env:HF_ENDPOINT="https://hf-mirror.com" 再跑
.\.venv\Scripts\python.exe scripts\download_models.py
HF 缓存默认被重定向到项目的
.cache/hf目录,C 盘只剩 11GB 的机器不用担心撑爆系统盘。
3.3 目录结构
Unlimited-OCR-2/
├── bin/llama-cuda-13.4/ # 运行时(llama-server.exe + patched DLLs)
├── models/ # Unlimited-OCR-2-Q4_K_M.gguf + mmproj
├── ocr/ # 核心模块:config / server / client / parser / batch
├── ui/ # Gradio 页面
├── app.py # 启动入口
├── logs/llama-server.log # 服务日志(排查 OOM 看这里)
└── outputs/ # 识别结果
3.4 启动
.\.venv\Scripts\python.exe app.py
# 打开 http://127.0.0.1:7860
界面启动后会自动在后台拉起 llama-server,退出时自动清理进程(Windows 下用 taskkill /F /T /PID 确保连同子进程一起结束,不留占用显存的孤儿进程)。
四、踩过的坑
坑 1:源码编译在 Windows 上必然失败(CUDA 12.x + VS2022 17.10+)
见 3.1 节。解法:用预编译包 + 叠加 DLL,完全绕开编译。
坑 2:两个 HuggingFace 仓库,行为不一样
HF 上有两个 Unlimited-OCR-2-GGUF 仓库:
AtomicChat/Unlimited-OCR-2-GGUF:GGUF 嵌入的 chat template 会自动补<PAGE>和Multi page parsing.,所以空消息也能工作。RX5950XT/Unlimited-OCR-2-GGUF:模板只是原样拼接,必须加--jinja启动参数,客户端也必须显式发送<PAGE>+ 图片 +Multi page parsing.。
后者的模型质量更好(带 imatrix 校准、关键层 Q8_0、64 页独立评估集文字中位相似度 100%),且与补丁同源,所以推荐用后者,但要记住显式构造消息格式:
messages = [{"role": "user", "content": [
{"type": "text", "text": "<PAGE>"},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
{"type": "text", "text": "Multi page parsing."},
]}]
坑 3:没有 no-repeat n-gram 守卫,极少数页面可能复读卡死
原版服务端(SGLang/vLLM)预设了 no-repeat-ngram-size=35 和页数守卫,llama.cpp 没有对等实现。遇到某类页面时模型可能进入重复输出的死循环,单槽服务永久阻塞。
应对:每次请求强制设 max_tokens(6000 左右)和 HTTP timeout(300s),这样即使进入复读也会被截断。输出被截断时 finish_reason 为 length,可以在日志或 UI 里标出来。
坑 4:客户端缩图适得其反
mtmd 的 gundam 模式会自己做动态切块,把页面细分为多块分别编码,之后再拼进上下文。如果在送图前先缩小,等于主动损失了小字和细线信息,让 gundam 白切了一堆低质量块。
正确做法: 只做 EXIF 方向矫正和透明底转白底 RGB,不主动缩放(除非图片长边超过 4096px,大多数扫描仪输出不会到这个量级)。
坑 5:显存余量极其有限
4GB 显存在当前桌面/IDE/其他应用占用约 1GB 后,只剩约 3GB。账面上:
- Q4_K_M 权重约 2.0GB
- mmproj 视觉编码器约 787MB(如果也放 GPU)
- KV Cache + 激活值缓冲
三者加起来已经非常接近上限。初次尝试时用默认 -c 32768(3.2 万 token 上下文)直接 OOM,调到 -c 8192 才稳定。
五、性能实测(GTX 1650 Ti 4GB,Turing sm_75)
5.1 视觉输入的两种模式
这里先解释 gundam 和 base 是什么。
gundam 模式(默认):mtmd 把输入图片动态切成多块(最多约 16 块),每块独立编码后拼进上下文。等价于原版单页推理的默认行为。视觉 token 多,细节保留好,但编码阶段慢、显存峰值高。
base 模式(--image-max-tokens 273):每页压成一张 1024×1024 整页图,不切块,只送 273 个视觉 token。等价于原版多页推理里每页的全局视图。速度约快 4 倍,但密集小字、细线和公式精度会明显下降。
5.2 速度对比
| 配置 | 样例图 | 总耗时 | 显存峰值 |
|---|---|---|---|
| gundam + mmproj CPU | 1240×1000 / 194 tokens | 81s | 3.6GB |
| gundam + mmproj GPU | 同上 | 58s | 3.9GB |
gundam + GPU + -fa on |
同上 | 44s | 3.9GB |
| base + GPU | 同上 | 13s | 3.9GB |
gundam + GPU + -fa on |
A4 密集页 2480×3508 / 1937 tokens | 59s | 3.9GB |
几个结论:
-fa on(Flash Attention)实测兼容,且有效。同一张图 gundam 模式从 58s 降到 44s,约快 24%,补丁自定义的注意力算子经过了 Vulkan/CUDA 后端验证。- base 模式极快。同一张图 13s 完成,适合「先粗扫一遍,确认值得精读」的流程。
- mmproj 放 CPU 节省 ~300MB 显存,但慢了约 40%。4GB 显存在关闭其他程序后通常够用,仅在系统重负载下才建议切 CPU。
- 密集 A4 页速度其实不慢:2480×3508 的高密度扫描件,gundam 模式 59s 跑完 1937 个输出 token,decode 阶段约 61 tokens/s,说明解码速度是 Q4_K_M 量化带来的稳定收益。
5.3 识别质量(合成测试图主观观察)
在自制的中英混排合成测试页上,以下内容识别正确:
- 中英文正文段落,含数字和特殊符号(
$3.4 million、百分号等) - 标题层级(模型能区分
title和text类型) - 版面坐标(归一化到 0–1000 的相对坐标,肉眼对比位置准确)
- 列表项(
-开头的行) - 段落内换行
受限于合成图本身质量和测试样本数量,这里不给出量化指标——真实文档的评估数据可参考 RX5950XT/Unlimited-OCR-2-GGUF 的 README,该仓库用 64 页 OmniDocBench 评估集报告:Q4_K_M 文字中位相似度 100%,平均相似度 99.18%,最差页 79.39%(差异主要来自版面分块粒度,不是认错字)。
5.4 原始输出格式
模型输出是带版面标签的结构化文本,直接落盘可读性差:
<PAGE><BLOCK>title[62, 74, 361, 115]<FORK>Quarterly Report 2026
<BLOCK>text[62, 260, 828, 304]<FORK>Revenue grew 12.5% year over year, reaching $3.4 million.
<BLOCK>title[62, 385, 208, 425]<FORK>2. 项目进展
工具已自动生成三份文件:
- .raw.txt:保留全部标签和坐标(调试用)
- .txt:只留文字,多页之间加分隔线
- .md:title 转 ##,可直接粘贴到笔记软件
六、使用场景推荐
场景 A:个人使用(文档整理、学习笔记提取)
推荐配置:base 模式 + GPU,-fa on
$env:OCR_IMAGE_MAX_TOKENS="273"
.\.venv\Scripts\python.exe app.py
理由:个人文档通常是清晰扫描的教材、论文或报告,字号不会太小;13s 一页的速度体验流畅,可以在识别的同时阅读上一页的结果。批量时开启断点续跑,中途关闭不丢进度。
工作流建议:
1. 把 PDF 先转成 PNG(pdftoppm、WPS 等工具,DPI 150–200 即可)
2. 拖到界面的批量标签页,填上文件夹路径,开始
3. 识别完从 outputs/ 取 .md 文件,粘贴到 Obsidian / Notion 等
场景 B:生产/批处理(批量数字化档案、文件归档)
推荐配置:gundam 模式 + GPU + -fa on,OCR_MAX_TOKENS=8000,不开 mmproj CPU
$env:OCR_EXTRA_ARGS="-fa on"
$env:OCR_MAX_TOKENS="8000"
.\.venv\Scripts\python.exe app.py
理由:生产场景更在意准确率而非速度;gundam 切块保留最多细节;密集扫描件(A4 双栏、表格密集型文档)44–60s/页在夜间批量处理时是可接受的。
注意事项:
| 事项 | 建议 |
|---|---|
| 显存管理 | 批量前关闭浏览器、微信等占显存的程序,给模型腾出余量 |
| 单槽限制 | llama-server 只支持 -np 1,工具已串行化,不要同时开两个界面实例 |
| OOM 应对 | 若出现 OOM(日志里看 out of memory),设 OCR_MMPROJ_CPU=1 或降 OCR_CTX 至 4096 |
| 超长文档 | 单页调用没有多页共享 KV Cache,每页独立推理;上下文长度 8192 足以覆盖绝大多数单页输出 |
| 断点续跑 | 默认开启,中断后重跑会跳过已完成的页,summary.csv 累计记录所有历史 |
| 结果审核 | .raw.txt 保留了版面类型和坐标,可用脚本做二次校验(如过滤 image 块、检查坐标连续性) |
不适合的场景:
- 需要同时处理大量并发请求(模型架构限制,单槽串行)
- 需要识别手写体(模型针对印刷/扫描文档训练,手写效果未测)
- 生产环境有严格 SLA 要求(单页 44–60s,100 页约需 1.5 小时)——这种情况应该换更好的 GPU 或走 API
七、总结
Unlimited-OCR-2 在 4GB 显存的消费级 GPU 上可以稳定运行,Q4_K_M 量化版基本不损失精度(64 页测试集文字中位相似度保持 100%)。部署的主要门槛不在显存,而在运行时选型:Windows 上避免源码编译,直接用预编译包 + 补丁叠加;注意选对 HuggingFace 仓库;启动参数必须加 --jinja。
从速度来看,gundam 模式 + Flash Attention 大约 44s/页,base 模式约 13s/页,对于个人文档整理完全够用;批量夜跑或偶发性的文件归档也可以接受。对于更高吞吐需求,建议搭配 RTX 3080/4070 以上的显卡(扩展上下文、开多页联合识别、速度快一个数量级)。
评论 (0)
还没有评论,来说两句吧!