OCR 如何讀取掃描 PDF，以及本工具為何回傳 Markdown

掃描 PDF 把頁面存成點陣影像，也就是文字的照片，而不是可以選取的字元。OCR（光學字元辨識）去看這些像素，猜哪些形狀是字，再輸出真正的文字。在 PDF123 上，它既是免費的瀏覽器工具，也是 POST /api/v1/misc/ocr-pdf；回傳的是 Markdown，不是重寫過的 PDF。

掃描件仍然是一張圖

OCR 不會清理、不會銳化，也不會替換點陣圖。一張被 OCR 讀錯的清晰掃描件，看起來仍然清晰。影像從來不是品質瓶頸，辨識才是：同一批掃描件換一個辨識引擎，準確率可能差出一大截，像素本身並未改變。

傳統 PDF OCR 會在影像底下寫入一層不可見的文字，並與影像對齊，讓選取和搜尋落在正確的字上。示意圖畫的就是這個做法，如今許多桌面工具仍然這樣做。

這個端點實際回傳什麼

OCR 路由呼叫的是 /api/v1/misc/ocr-pdf，伺服器端跑的是一個獨立的 Rust crate，pdf-inspector（啟用了它的 ocr feature）。處理方式不是把整份 PDF 丟給一個辨識模型：pdf-inspector 會先逐頁判斷哪些頁已經能直接抽出原生文字、哪些頁只有影像。能抽出文字的頁沿用原生文字，不會碰到辨識模型；只有影像的頁才會轉入辨識管線：先由 PDFium（Chrome 內部用來渲染 PDF 的同一套開源函式庫）把頁面轉成點陣圖，再交給 ONNX Runtime 跑 PP-OCRv6 Small 模型進行推論。兩種頁面的結果會依頁序拼接、融合成一份 Markdown，這就是回應內容型別是 text/markdown、下載檔名以 .md 結尾的原因。

這份輸出契約是這次重寫後才有的。倉庫裡原本的 Java/Spring Boot 後端呼叫的是 OCRmyPDF，走的正是「影像加隱藏文字層」那條老路，輸出仍然是 PDF；Rust 重寫把這條路徑整個換成 pdf-inspector 的選擇性 OCR，輸出也跟著從 PDF 換成 Markdown。舊的 Java 後端已經從倉庫裡移除，不是一個還能切回去的選項。

如果你要的是可搜尋的 PDF（影像加文字層），這個端點給不出來。它給你的是 Agent 或資料流程可以直接使用的文字。

Auto 與 Force 的差別

表單裡有一個 ocrType 欄位：

• Normal（除了 force-ocr 以外的任何值）走 Auto：檔案本來就有文字的地方沿用既有文字，只對純影像頁跑 OCR。在乾淨的電子版 PDF 上，Auto 不會載入 OCR 執行環境。
• Force OCR（ocrType=force-ocr）對每一頁重跑辨識，包括已經有文字層的頁面。在真正的純影像頁上，你多付的是時間而不是精確度；換來的一輪辨識會忽略破損或殘缺的既有文字層。

入口網站的預設值是 Force OCR。這裡沒有語言選項：舊 Java 路徑遺留下來的語言參數會被伺服器忽略。

Auto 與 Force 的分野只發生在請求內部，入口網站和 API 的能力探測介面並不會替你先把關：GET /api/v1/settings/get-endpoints-status 對 ocr-pdf 永遠回答「已啟用」，並不會實際檢查 PDFium、ONNX Runtime 或 PP-OCRv6 模型是否已經裝好。真正的檢查要等到請求觸發辨識的那一刻才會發生：只要缺了其中一項，端點就直接回傳 503，不會退化成一份只含原生文字的半成品 Markdown。PP-OCRv6 Small 模型本身約 31 MB，部署時如果沒有預先放進本機快取，會在第一個真正需要辨識的頁面上連網下載；一台離線又沒有預置模型的機器，第一次 Force 請求多半會卡在這一步，而不是慢慢跑完。

辨識是機率性的

辨識引擎把像素樣式比對到字母與詞的模型上。它們在乾淨、高對比、標準字型的印刷件上表現良好，遇到下面這些情況就變差：

• 低解析度或低對比度的掃描（傳真品質對上 300 DPI 原件）
• 手寫、裝飾字型、奇特版面（多欄表格、旋轉文字、密集表單）
• 傾斜的頁面把字形扭曲到剛好足以干擾比對

無論 Auto 還是 Force，模糊的傳真件都不會像清晰掃描件那樣被準確辨識。這是模型本身的能力邊界，不是調整參數能解決的。

OCR 不做什麼

OCR 給你文字，不會重建段落、標題、表格，也不會產生可重新排版的 Word 文件。可編輯版面是在辨識誤差之上再做一次轉換的問題，和讀掃描件不是同一份工作。

OCR PDF 在伺服器端執行，不需要帳號。下載結果是 Markdown。如果檔案裡既有的文字層看起來不對，請用 Force OCR，讓 Auto 不要去信任那一層；想確認某台機器到底有沒有裝好 PDFium 和模型，直接跑一次真實請求比看探測介面的狀態更可靠，後者只回報端點存在，不回報執行環境是否就緒。自動化金鑰與 OpenAPI 見開發者。