OCRFlux 自架 PDF 轉 Markdown，把跨頁表格縫回完整文件

用 AI 摘要這篇文章：

ChatGPT Claude Perplexity Google Grok

先講 2026 年現在最重要的一件事：OCRFlux 已經沒有線上 demo 可以試了。我把官方文件上的體驗網址 ocrflux.pdfparser.io 打開，伺服器回了一個轉址，直接把你送回 GitHub 專案頁；對照程式碼提交記錄，2026 年 4 月的最後一筆修改，做的就是「從文件裡移除 demo 連結」這件事。README 裡另一個快速測試連結是臨時分享網址，現在打開是 404（HuggingFace 的模型卡上倒是還留著舊的 demo 連結，點下去同樣被送回倉庫）。所以它的身份需要重新描述：這是一個要自己準備 NVIDIA 顯示卡來跑的開源模型工具組，附一份相當漂亮的官方自評成績單，而不是點開網址就能用的線上服務。兩種身份的用途差很多，先認對再往下談。

OCRFlux 是 ChatDOC 開源的專案。ChatDOC 是一家做文件問答商業產品的公司，2025 年 6 月把這套 PDF 轉換工具組的程式碼以 Apache-2.0 授權放出來，模型本體拿 Qwen2.5-VL-3B-Instruct 當底微調，權重放在 HuggingFace 上讓人自由下載（權重的授權跟程式碼不是同一份，商用前要分清楚），做一件事：把 PDF 和圖片轉成乾淨的 Markdown，標榜跨頁表格與段落的自動合併。它的目標讀者很明確：手上有一堆論文、財報、技術報告，需要批次轉成結構化文字，餵給知識庫或檢索系統的人。三個問題決定你要不要碰它：官方數字到底贏在哪裡（以及輸在哪裡）、現在還有哪幾條路可以用它、以及自架要付出的真實成本。心急的讀者可以先記結論：長文件批次轉換的開發者值得研究，只是想偶爾轉幾份 PDF 的人，現成工具更實際。

官方成績單要連同輸掉的那一格一起看

品質數字全部來自官方自評。OCRFlux 發布時附了一套自己標註的測試集，2,000 頁英文中文各佔一半，經人工多輪校對，用編輯距離相似度（EDS，生成的 Markdown 與人工標準答案越接近，分數越高）當整頁轉換的指標。README 上的結果長這樣：

數字是官方 2025 年 6 月發布、截至 2026 年 9 月仍掛在 README 上的自評結果，三個對照組也是官方自己跑出來的分數，對照組都是 2025 年文件解析領域活躍的開源模型，權重同樣公開在 HuggingFace 上。0.967 對 0.872，差距確實大，而且模型只有 30 億參數，最大的對手 olmOCR 是 70 億參數等級，另一個對照組 Nanonets-OCR-s 跟它同樣以 Qwen2.5-VL 當底、同樣是 30 億級。換算成白話，EDS 0.967 大約等於每一千個字元需要人工再改三十多個；0.872 則是要改一百多個。落在文件管線裡，這個差距就是「抽檢幾頁就能放行」跟「每份都要人工掃一遍」的工作量差別。中文那一欄值得多看一眼：三個對照組的中文分數全部比自己的英文分數低，掉最多的 MonkeyOCR 差了快 0.1，而 OCRFlux 的中文 0.962 只比英文 0.971 低不到 0.01，中文文件上的相對優勢比英文更大。要動手驗證的話，四份測試集都公開在 HuggingFace 上，官方也聲明測試集不含在訓練與評估資料裡，這一點讓自評數字至少是可以被抓出來重算的。

Pin

但同一份 README 裡還有另一張表，講單頁表格辨識，用 TEDS（樹編輯距離相似度，把生成表格和標準答案各當成一棵樹比結構差異）在 9,064 個表格樣本上計分，樣本依有沒有跨列跨欄的合併儲存格分成簡單與複雜兩組：

把這張表讀完會看到另一個故事：簡單表格它最高，但「複雜表格」那一組，OCRFlux 的 0.807 輸給 MonkeyOCR 的 0.826，總分 0.861 對 0.853 也只是小幅領先。如果有人跟你說它贏在複雜表格解析，這個說法跟官方數字對不上；它真正拉開差距的，是整頁文字的完整還原，加上跨頁合併。如果你的文件痛點集中在單頁裡巢狀很深、合併儲存格很多的表格，這份官方數字反而提醒你要把 MonkeyOCR 一起放進候選名單比一比。

跨頁合併，才是它真正做的新東西

PDF 依頁切割，長表格常被攔腰切在兩頁之間，第二頁還會重複一次表頭；段落也一樣會在頁尾斷掉。多數開源解析工具的做法，是把每一頁各自轉完就結束，拼接這件事留給你自己寫程式處理。想像一份幾十頁的財報，資產負債表切在第 12 頁頁尾和第 13 頁頁首，如果工具只逐頁輸出，你拿到的是兩個半張表，後處理程式要自己猜「這兩塊是不是同一張表」「表頭要不要刪」「斷在儲存格中間的數字怎麼接」。OCRFlux 把這整段判斷做進管線裡：每一頁先轉成 Markdown 的元素清單，段落和表格各是一個元素；接著由模型判斷相鄰兩頁之間哪些元素應該合併，段落直接串接，表格的縫合另外處理，包括拆掉第二頁重複的表頭、把在儲存格中間斷掉的內容接回去，甚至處理欄位太多被直向切成兩頁的寬表。README 對此的說法是「就我們所知，這是第一個原生支援此功能的開源專案」，口徑是作者宣稱，但這個功能定位在同類工具裡確實少見。

跨頁偵測也有官方自評數字：1,000 組相鄰頁樣本上，判斷「哪些元素該合併」的準確率總分 0.986（英文 0.978、中文 0.994），合併後表格的 TEDS 總分 0.950。這是整份成績單裡最難被取代的一塊。單頁辨識的分數大家會互相追趕，文件級的組裝能力才是它跟其他工具拉開用途差距的地方：你要處理的文件裡跨頁表格越多，這個功能的價值越大。

demo 收起來之後，剩下兩條路

免費路是自架，付費路是 pdfparser.io。後者是 ChatDOC 的商業 API 產品，首頁列的賣點是掃描檔辨識、目錄階層理解、有框無框的表格辨識，定位寫的是把 PDF 接到檢索與知識庫管線，首頁就掛著直接上傳 PDF 試轉的入口。要畫清楚的是：開源倉庫和這個 API 是兩個不同的產品，文件、計費、模型版本都不一定同步，付費購買前要當成獨立產品分開試用。GitHub issue 裡有一條 2025 年 7 月開立的公開抱怨可以當參考：一位使用者先自架模型，覺得模型大小、回應速度、辨識效果都跟官網 demo 差一截；改買商業 API 之後又遇到配額判定異常、API 文件難讀，一頁表格只回傳幾條豎線（Markdown 表格的分隔符號），客服也沒能解決。這是單一使用者的經驗，不能推成普遍狀況，但至少提醒一件事：看到「同一家公司出品」不代表兩邊品質綁在一起。

Pin

自架的入場券：一張 NVIDIA 顯示卡，和一份乾淨環境

官方安裝文件列出的硬體門檻很明確：NVIDIA 顯示卡（官方測試過 RTX 3090、4090、L40S、A100、H100），VRAM 至少 12GB，但建議 24GB 以上；手上只有 12GB 等級的卡的話，要開張量並行把工作分給多張卡。推論引擎是 vllm，吃 CUDA，所以 Mac 和沒有 NVIDIA 卡的機器直接出局。issue 版的現實更直白：有人在顯示卡已被其他程序佔用記憶體的機器上跑到 CUDA out of memory，官方回覆 24GB 等級的卡跑得動，前提是卡上沒有其他程式在吃記憶體；V100 這類不支援 bf16 的舊卡要退回 float32，還有使用者回報轉換很慢、結果是空的。

軟體面的摩擦也不小。官方明講這套相依套件很難裝進既有的 Python 環境，要求另開一個乾淨的 conda 環境（Python 3.11），先裝好 poppler 和一串字型，模型加暫存會吃掉約 20GB 磁碟。不想折騰的話有官方 Docker 映像，但模型權重（放在 HuggingFace 上的 ChatDOC/OCRFlux-3B，每月下載約一千次）要自己先下載、掛載進容器。跑法是命令列管線：對單一 PDF 或整個資料夾下指令，輸出 JSONL 結果檔再轉出 Markdown。結果檔的設計有一個值得肯定的地方：轉換失敗的頁面會被記在 fallback_pages 欄位裡，不會假裝一切正常，你可以提高重試次數換取更好的結果，代價是時間；文件裡也提供跳過跨頁合併的參數，等於只做逐頁轉換，速度快一些。

要接進自己的程式的話，文件提供兩種整合姿勢。一種是離線推論，直接在 Python 裡呼叫解析函式，傳入模型和檔案路徑就拿到整份文件的 Markdown；另一種是把模型包成 vLLM 伺服器常駐，用 client 端發請求處理檔案，適合多人共用一張卡的場景。兩種姿勢都建立在 vLLM 之上，也就是說它不是那種裝完 pip 套件就能在筆電上跑的輕量庫，基礎設施的假設從安裝第一分鐘就存在。

Pin

它沒有做的事，和它停下來的時間點

輸出只有 Markdown 文字。結果檔裡沒有字元座標或框，issue 上有人問定位功能，維護者明確回覆模型不支援。這代表「點擊文字高亮原文」「引用時跳回原頁位置」這類應用，這套輸出不夠用，得另外搭配方案。辨識出文字和知道文字在哪裡，是兩件事，後者它目前不提供。

專案的節奏也要看清楚。2025 年 6 月 4 日建立倉庫，6 月 17 日宣布 v0.1.0，之後 GitHub 上沒有發布過任何正式 release 或標籤；提交記錄顯示 2025 年 8 月之後倉庫安靜了八個多月，直到 2026 年 4 月補了一筆移除 demo 連結的文件修訂，之後又安靜至今。目前累積 2,500 多顆星，未關閉的 issue 與 PR 合計約 70 個。它沒有消失，程式照文件可以跑，但「功能大致凍結」是比較誠實的描述：把它接進生產流程之前，要有自己扛維護的心理準備。另外提醒一個引用上的習慣：上面那些 benchmark 數字是 2025 年 6 月的快照，文件解析模型這一年汰換很快，對手清單早就跟當時不同，拿這些數字做簡報時記得附上時間點。

文件量和跨頁表格比例，決定值不值得養一張顯示卡

判斷軸其實只有一條：你的文件量和文件形態，值不值得養一張顯示卡。要把大批長文件（財報、論文、技術報告）批次轉成餵知識庫或 RAG 管線的 Markdown，而且跨頁表格比例高，這是它的主場，官方成績單的差異化剛好對上這個場景。反過來說，偶爾轉幾份 PDF、機器上沒有 N 卡的人，有更省事的路：先判斷文件本身有沒有文字層，Firecrawl PDF Inspector 這類工具幾十毫秒就能告訴你要不要 OCR；確定要辨識的話，RapidOCR 這類離線工具輕得多，Mac 也跑得動；轉出 Markdown 之後要交給同事編輯，再接 Markdown 轉 Word 的工具就行。習慣把雲端 API 當主力的團隊，Nano PDF CLI 那種用 API 處理文件的做法，也是另一條不必自架的路。

還要留意中文樣本的組成：官方測試集的中文樣本佔一半，但組成沒有詳述是簡體還是繁體文件，繁中文件的轉換品質要拿自己的文件抽驗過再決定要不要上量。這一步誰都代替不了你。

授權要拆成兩份看，商用前尤其要分清楚

這是整個專案最容易踩錯的地方。GitHub 倉庫的程式碼是 Apache-2.0，商用、修改、再散布都不需要另外取得授權；但 HuggingFace 上的模型權重，授權欄位宣告的是 Qwen Research License，也就是它拿來微調的底、阿里巴巴 Qwen2.5-VL-3B-Instruct 所附帶的研究授權。這份授權的白話意思是：研究與評估用途沒問題，商業用途需要向權利方（阿里巴巴雲）另行取得授權。對個人研究和內部評估來說不影響，但如果你計畫把它接進收費產品或商業服務，程式碼的 Apache-2.0 不會保護你，權重授權才是關鍵，這一步要自己找法務或直接洽談，不能只看倉庫的 LICENSE 檔案。

四份測試集同樣公開在 HuggingFace 上，官方聲明不包含在訓練與評估資料裡，模型卡的說明也交代了訓練資料的一部分來自 Allen AI 的 olmOCR 混合資料集，等於拿對手的公開資料練功再跟對手比評測，這在領域內不算罕見做法，但知道的話看數字會更冷靜。第一步很實際：先確認手上有 24GB VRAM 等級的顯示卡，再去倉庫 README 對照 Installation 一節；沒有 N 卡之前不必急著 clone，因為文件裡的每一條路都以它為前提。這個專案最好的使用方式，是把它當成一份公開完整、可自行驗證的文件解析方案來評估，而不是一個隨手可用的線上工具；入場成本先算清楚，分數的強項弱項也一併看懂，它就會是一個很好判斷的選項。