Unlimited-OCR-2 GGUF

繁體中文 | English

---

繁體中文

baidu/Unlimited-OCR-2 的 GGUF 版本，提供 BF16（無損）、Q8_0、Q4_K_M 三種精度，外加視覺投影器（mmproj）與多模態 imatrix。

[!IMPORTANT] 需要套用本 repo 附的 patch 的 llama.cpp 才能執行。 主線 llama.cpp 目前只支援 Unlimited-OCR v1 / DeepSeek-OCR，不支援 v2，也不會載入這些檔案（架構名稱為 unlimited-ocr2）。LM Studio、Ollama 等使用主線 llama.cpp 的軟體目前同樣無法載入。 套用方式見下方〈套用 patch 並編譯 llama.cpp〉。測試版本：llama.cpp b11913。

為什麼不能直接用 v1 的轉換方式？

Unlimited-OCR-2 的解碼器跟 v1 長得一樣（DeepSeek-V2 MoE，12 層），但注意力機制完全不同：

1. 頁面 2D 位置編碼（page-2D RoPE）：位置不是「第幾個 token」，而是「(頁內第幾個 token, 第幾頁的奇偶)」，63 對頻率給頁內位置、1 對給頁碼。
2. DASH 稀疏路由注意力（SR-SWA）：每個 token 只看「最近 128 個 token」＋「由路由器挑出、本頁影像中最相關的 12 個區塊（每塊 32 token）」，挑選用 entmax-1.5 機率並轉成 log 偏置加到注意力分數上。

如果把 v2 當成 v1 轉換（一般全注意力＋一般 RoPE），模型雖然跑得起來，輸出卻是錯的。實測（HF 原版程式碼，改掉注意力後與原版比對）：

本 repo 的 patch 在 llama.cpp 裡完整實作了上面兩項（路由器、區塊摘要、entmax、同頁影像候選、局部視窗），並保留全部路由權重（BF16，不量化）。

檔案

Q4_K_M 量化配方（盡量保真）

• MoE 路由專家（佔 9 成以上參數）：依 Q4_K_M 規則（Q4_K / Q5_0 / Q8_0）
• 注意力 q/k/v/o、共享專家、第 0 層 dense FFN、詞嵌入、輸出層：Q8_0（參數少，只多約 190 MiB）
• DASH 路由器（q/k 投影、norm、head_cls）：BF16 / F32，不量化（路由決策不受量化影響）
• imatrix：用 48 頁 OmniDocBench 文件（論文、教科書、報紙、筆記、簡報、考卷、財報，中英文）連同影像一起計算，目標文字為 BF16 模型的 OCR 輸出（teacher forcing），共約 12.3 萬 token

準確度

BF16 GGUF vs HF 原版（transformers，bf16）

座標 ±1 屬於 bf16/f16 浮點誤差造成的近似平手，文字內容完全相同。

量化版 vs BF16（64 頁 OmniDocBench 評估集，未用於校準）

「全文」含版面標籤與座標；「文字」只比辨識出的文字（去除 <BLOCK>…<FORK> 標籤、座標與空白）。

文字中位數為 100%：超過一半的頁面，量化版辨識出的文字與 BF16 完全一致。差異多半是版面切分粒度不同（同樣的文字被切成不同數量的區塊）或框座標偏移，而不是認錯字。

Q4 配方比較（同一評估集，用來決定上面的配方）：

單用 imatrix 反而略差，跟關鍵層 Q8_0 搭配才有幫助，最差頁的分數也明顯提高。

套用 patch 並編譯 llama.cpp

patch 檔記錄了「在官方 llama.cpp 原始碼上要改哪些地方」。流程是：下載官方原始碼 → 用 git apply 把修改套上去 → 編譯。

需要：git、cmake、C++ 編譯器（Windows：Visual Studio 2022 的「使用 C++ 的桌面開發」；Linux：build-essential；macOS：Xcode Command Line Tools），要用 NVIDIA GPU 另需 CUDA Toolkit。

# 1. 下載官方 llama.cpp，切到測試過的版本
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
git checkout b11913   # = commit 7aca0d2，發行日 2026-10-26

# 2. 套上 patch（路徑換成你下載的 patch 位置）
git apply --check /path/to/unlimited-ocr2.patch   # 先檢查，沒有輸出就代表可以套
git apply /path/to/unlimited-ocr2.patch

# 3. 編譯
cmake -B build -DGGML_CUDA=ON          # 沒有 NVIDIA GPU 就拿掉 -DGGML_CUDA=ON；Mac 會自動用 Metal
cmake --build build --config Release -j --target llama-mtmd-cli llama-server

• patch 可以在本 repo 的 Files 頁面下載，或用 hf download RX5950XT/Unlimited-OCR-2-GGUF llama.cpp-patch/unlimited-ocr2.patch --local-dir .。
• 編譯好的程式在 build/bin/（Windows 是 build/bin/Release/）。
• 已確認此 patch 也能直接套在 2026-10-27 的 llama.cpp master 上；若日後主線改動導致 git apply --check 失敗，請改用上面的 b11913。
• 想撤銷修改：git checkout .（加上 git clean -fd 移除新增的檔案）。

使用方式

單頁（與原版預設相同：gundam 切塊模式）

./build/bin/llama-mtmd-cli \
  -m Unlimited-OCR-2-Q8_0.gguf --mmproj mmproj-Unlimited-OCR-2-F16.gguf \
  --jinja --temp 0 -c 32768 -n 8000 \
  --image page.png \
  -p "<PAGE><__media__>Multi page parsing."

多頁（與原版預設相同：base 模式，每頁一個 1024×1024 全域視圖）

./build/bin/llama-mtmd-cli \
  -m Unlimited-OCR-2-Q8_0.gguf --mmproj mmproj-Unlimited-OCR-2-F16.gguf \
  --jinja --temp 0 -c 65536 -n 24000 \
  --image-max-tokens 273 \
  --image p1.png,p2.png,p3.png \
  -p "<PAGE><__media__><PAGE><__media__><PAGE><__media__>Multi page parsing."

重點：

• 一定要加 --jinja（模型內建的模板只是把內容原樣串接）。
• 每一頁前面放一個 <PAGE>，最後接 Multi page parsing.，這是原版訓練時的格式。
• 多張圖片用逗號分隔（重複寫 --image 只會取最後一張）。
• --image-max-tokens 273：只送全域視圖、不切塊（＝原版 base 模式，多頁時的預設）。單頁不加則是 gundam 模式（最多 16 塊）。
• 輸出每頁以 <PAGE> 開頭，區塊格式為 <BLOCK>類型[x0, y0, x1, y1]<FORK>內容，座標是 0–1000 的相對座標。

OpenAI 相容伺服器

./build/bin/llama-server \
  -m Unlimited-OCR-2-Q8_0.gguf --mmproj mmproj-Unlimited-OCR-2-F16.gguf \
  -np 1 -c 32768 --port 8080

import base64, requests
img = base64.b64encode(open("page.png", "rb").read()).decode()
r = requests.post("http://127.0.0.1:8080/v1/chat/completions", json={
    "temperature": 0, "max_tokens": 8000,
    "messages": [{"role": "user", "content": [
        {"type": "text", "text": "<PAGE>"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64," + img}},
        {"type": "text", "text": "Multi page parsing."},
    ]}],
})
print(r.json()["choices"][0]["message"]["content"])

多頁就重複 <PAGE> 文字段＋圖片段。伺服器端的 base／gundam 模式同樣由 --image-max-tokens 決定。

限制

• 只支援單一序列：llama-server 請用 -np 1。頁碼與位置是從 KV cache 裡的 token 序列推算的。
• DASH 以「完整注意力＋路由遮罩」實作：數學上等同原版的稀疏讀取，但沒有稀疏運算帶來的加速；文件越長越吃記憶體。
• 純文字輸入（沒有圖片）不在原模型的使用範圍內，結果不保證與原版一致。
• 原版服務端（SGLang/vLLM）預設會加 no-repeat n-gram（35）與頁數守衛；llama.cpp 沒有，極少數頁面可能出現重複迴圈，可用 -n 限制輸出長度。
• 視覺編碼器以 F16 儲存（原版為 BF16）。

重現

scripts/reproduce.sh 列出從原始權重到所有 GGUF 的完整指令；scripts/ 另有評估用腳本（batch_ocr.py、eval_dir.py、compare.py、ref_infer.py）。calibration/sources.json 是校準與評估所用 OmniDocBench 頁面的原始檔名（影像本身請從 opendatalab/OmniDocBench 下載）。

授權與致謝

模型權重沿用原模型的 MIT 授權；patch 與腳本同樣以 MIT 釋出。感謝 baidu/Unlimited-OCR-2（Baidu ERNIE Team）、llama.cpp、OmniDocBench（校準與評估資料）。

---

English

GGUF conversion of baidu/Unlimited-OCR-2 in BF16 (lossless), Q8_0 and Q4_K_M, plus the vision projector (mmproj) and a multimodal imatrix.

[!IMPORTANT] These files require llama.cpp with the patch included in this repo. Mainline llama.cpp currently supports Unlimited-OCR v1 / DeepSeek-OCR only, not v2, and will not load these files (architecture name unlimited-ocr2). Apps built on mainline llama.cpp (LM Studio, Ollama, ...) cannot load them either. See Apply the patch and build llama.cpp below. Tested with llama.cpp b11913.

Why not convert it like v1?

The Unlimited-OCR-2 decoder has the same shape as v1 (DeepSeek-V2 MoE, 12 layers), but its attention is different:

1. Page-2D RoPE: a position is not "token index" but "(token index within the page, page parity)". 63 frequency pairs encode the in-page position, 1 pair encodes the page.
2. DASH routed attention (SR-SWA): each token attends to the last 128 tokens plus the 12 most relevant 32-token blocks of the current page's image, chosen by a small router. The router's entmax-1.5 probabilities are added to the attention scores as a log bias.

Converting v2 the v1 way (dense attention + plain RoPE) runs, but the output is wrong. Measured with the original HF code, swapping out the attention:

The patch in this repo implements both parts in llama.cpp (router, block summaries, entmax, same-page image candidates, local window) and keeps all router weights unquantized (BF16).

Files

Q4_K_M recipe (max fidelity)

• Routed MoE experts (90%+ of parameters): standard Q4_K_M rules (Q4_K / Q5_0 / Q8_0)
• Attention q/k/v/o, shared experts, layer-0 dense FFN, token embedding, output: Q8_0 (few parameters, about +190 MiB)
• DASH router (q/k projections, norms, head_cls): BF16 / F32, not quantized, so routing decisions are unaffected
• imatrix: computed with images on 48 OmniDocBench pages (papers, textbooks, newspapers, notes, slides, exams, financial reports; Chinese and English), teacher-forcing the BF16 model's OCR output as targets, about 123k tokens

Accuracy

BF16 GGUF vs original HF model (transformers, bf16)

The ±1 coordinate differences are near-ties from bf16/f16 rounding; the text is identical.

Quants vs BF16 (64 OmniDocBench pages, not used for calibration)

"Full" includes layout tags and coordinates; "Text" compares only the recognized text (tags <BLOCK>...<FORK>, coordinates and whitespace removed).

A text median of 100% means that on more than half of the pages the quantized model recognizes exactly the same text as BF16. Most differences are layout granularity (the same text split into a different number of blocks) or shifted boxes, not misread characters.

Q4 recipe comparison (same eval set, used to pick the recipe above):

imatrix alone is slightly worse; combined with Q8_0 key layers it helps, and clearly lifts the worst page.

Apply the patch and build llama.cpp

The patch file lists the changes to make to the official llama.cpp source. The steps are: get the official source, apply the changes with git apply, build.

You need git, cmake and a C++ compiler (Windows: Visual Studio 2022 "Desktop development with C++"; Linux: build-essential; macOS: Xcode Command Line Tools), plus the CUDA Toolkit for NVIDIA GPUs.

# 1. Get official llama.cpp at the tested commit
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
git checkout b11913   # = commit 7aca0d2, released 2026-10-26

# 2. Apply the patch (use the path where you saved it)
git apply --check /path/to/unlimited-ocr2.patch   # dry run; no output means OK
git apply /path/to/unlimited-ocr2.patch

# 3. Build
cmake -B build -DGGML_CUDA=ON          # drop -DGGML_CUDA=ON without an NVIDIA GPU; Metal is used on Mac automatically
cmake --build build --config Release -j --target llama-mtmd-cli llama-server

• Download the patch from this repo's Files tab, or with hf download RX5950XT/Unlimited-OCR-2-GGUF llama.cpp-patch/unlimited-ocr2.patch --local-dir ..
• Binaries end up in build/bin/ (build/bin/Release/ on Windows).
• The patch also applies cleanly to llama.cpp master as of 2026-10-27. If a later master makes git apply --check fail, check out b11913 as above.
• To undo: git checkout . (plus git clean -fd to remove added files).

Usage

Single page (original default: gundam tiling)

./build/bin/llama-mtmd-cli \
  -m Unlimited-OCR-2-Q8_0.gguf --mmproj mmproj-Unlimited-OCR-2-F16.gguf \
  --jinja --temp 0 -c 32768 -n 8000 \
  --image page.png \
  -p "<PAGE><__media__>Multi page parsing."

Multiple pages (original default: base mode, one 1024x1024 global view per page)

./build/bin/llama-mtmd-cli \
  -m Unlimited-OCR-2-Q8_0.gguf --mmproj mmproj-Unlimited-OCR-2-F16.gguf \
  --jinja --temp 0 -c 65536 -n 24000 \
  --image-max-tokens 273 \
  --image p1.png,p2.png,p3.png \
  -p "<PAGE><__media__><PAGE><__media__><PAGE><__media__>Multi page parsing."

Notes:

• --jinja is required (the built-in template just concatenates the content).
• Put one <PAGE> before each page and end with Multi page parsing.; this is the training format.
• Separate multiple images with commas (repeating --image keeps only the last one).
• --image-max-tokens 273: global view only, no tiles (= original base mode, the default for multiple pages). Without it, a single page uses gundam mode (up to 16 tiles).
• Each output page starts with <PAGE>; blocks look like <BLOCK>type[x0, y0, x1, y1]<FORK>content, coordinates normalized to 0-1000.

OpenAI-compatible server

./build/bin/llama-server \
  -m Unlimited-OCR-2-Q8_0.gguf --mmproj mmproj-Unlimited-OCR-2-F16.gguf \
  -np 1 -c 32768 --port 8080

import base64, requests
img = base64.b64encode(open("page.png", "rb").read()).decode()
r = requests.post("http://127.0.0.1:8080/v1/chat/completions", json={
    "temperature": 0, "max_tokens": 8000,
    "messages": [{"role": "user", "content": [
        {"type": "text", "text": "<PAGE>"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64," + img}},
        {"type": "text", "text": "Multi page parsing."},
    ]}],
})
print(r.json()["choices"][0]["message"]["content"])

For multiple pages, repeat the <PAGE> text part + image part. Base / gundam mode on the server is also controlled by --image-max-tokens.

Limitations

• Single sequence only: use -np 1 with llama-server. Page numbers and positions are derived from the token sequence in the KV cache.
• DASH is implemented as full attention + a routing mask: mathematically the same as the original sparse gather, but without the sparse speed-up; memory grows with document length.
• Text-only input (no image) is outside the original model's scope; parity with the original is not guaranteed.
• The original serving stack (SGLang/vLLM) adds a no-repeat n-gram (35) and a page guard by default; llama.cpp does not, so rare pages may loop. Limit output with -n.
• The vision encoder is stored in F16 (original is BF16).

Reproduce

scripts/reproduce.sh has the full commands from the original weights to every GGUF; scripts/ also has the evaluation scripts (batch_ocr.py, eval_dir.py, compare.py, ref_infer.py). calibration/sources.json lists the OmniDocBench pages used for calibration and evaluation (get the images from opendatalab/OmniDocBench).

License and credits

Model weights keep the original MIT license; the patch and scripts are also MIT. Thanks to baidu/Unlimited-OCR-2 (Baidu ERNIE Team), llama.cpp and OmniDocBench (calibration and evaluation data).