Docling 教學｜PDF 轉 Markdown、繁體中文 OCR，與 MarkItDown 比較
Kyle 4,586 字 · 約 14 分鐘

Docling 是開源文件解析工具，能把 PDF、Word、Excel 與簡報轉成 Markdown、HTML 或結構化資料。處理雙欄 PDF、掃描文件或表格時，除了辨識文字，還需要還原閱讀順序與欄位關係，轉換後的內容才適合交給 AI 分析。

Microsoft MarkItDown 也能轉換文件。Docling 值得評估的地方，是可以保留文件階層與來源位置，並調整圖片文字辨識（OCR）、圖片與表格的處理方式。一般文件若已能順利轉換，繼續使用 MarkItDown 也合理；需要更細緻的解析與檢查時，再增加 Docling 這套流程。

Docling 是什麼

Docling 由 IBM Research Zurich 的 AI for knowledge 團隊發起，目前是 LF AI & Data Foundation 的專案。程式碼採 MIT 授權，使用到的模型則要分別查看模型授權。它主要用在文件搜尋、資料分析與 RAG 知識庫的資料前處理，可以在終端機透過命令列介面（CLI）轉換文件，也能用 Python API 整合到程式。 官方專案 列有功能與授權資訊。

Docling 從 PDF 整理標題與段落、表格結構和閱讀順序的示意圖
文件解析需要保留內容之間的關係。

RAG 是先搜尋相關文件，再讓語言模型依據搜尋結果回答問題的做法。Docling 負責把原始文件整理好，後續的向量化、資料庫、搜尋與回答仍需另外串接；安裝 Docling 不會直接得到聊天介面。

文件解析時，Docling 會建立 DoclingDocument，記錄文字、表格、圖片與章節關係；資料可取得時，也能保留頁碼和座標等來源資訊。這讓程式除了讀取一段文字，也能知道它屬於哪個章節、出自原文件哪裡。 文件資料模型 說明了這些欄位。

支援哪些檔案格式

類別常見輸入處理時的重點
PDF 與掃描圖PDF、PNG、JPEG、TIFF文字層、版面分析與 OCR 是不同工作
Office 文件DOCX、PPTX、XLSX抽取內容與結構，不保證重現原始外觀
網頁與文字HTML、Markdown、CSV原本有結構的資料可直接利用
其他文件EPUB、Apple Pages、部分 XML 格式依格式使用對應解析器；Pages 需 format-iwork 擴充

音訊與影片也有對應處理流程，但會涉及語音辨識等額外模型。本文集中在 PDF 與辦公文件，完整清單以 支援格式 為準；能接受某個副檔名，不代表所有內嵌物件與排版都能完整保留。

Docling 與 MarkItDown 的差別

MarkItDown 是微軟開源的 Python 工具，以把多種文件轉成 Markdown 為主要用途，同樣會保留標題、清單、表格與連結。本站的 MarkItDown 教學 有安裝、Office 文件轉換與延伸應用，可以搭配閱讀。

比較項目MarkItDownDocling
主要產物以 Markdown 為核心先建立 DoclingDocument，再匯出不同格式
文件結構保留 Markdown 能表達的重要結構另有文件階層、閱讀順序與可取得的來源位置
PDF 處理內建轉換器，可另接 Azure 服務提供版面、表格、OCR 與其他解析流程
掃描與圖片文字可用 OCR 外掛搭配視覺模型，或 Azure 服務可選 EasyOCR、Tesseract、OcrMac 等引擎
本機與雲端內建轉換可本機執行；Azure 整合另計費支援本機模型；遠端模型需另外啟用
適合先評估的需求多格式轉 Markdown、既有簡單轉檔流程複雜 PDF、表格抽取、需追溯來源的文件處理

MarkItDown 的 官方文件 已列出 OCR 外掛、Azure Document Intelligence 與 Azure Content Understanding，因此不能把差異簡化成「只有 Docling 能 OCR」。比較時也要固定條件：MarkItDown 內建轉換、外接付費服務與 Docling 本機流程，成本和資料流向都不同。

選擇工具時，先看文件種類與需要保留的資訊。如果只是把 Word、HTML 或 Excel 文字交給 AI，現有 MarkItDown 輸出正確就能繼續用。若經常遇到 PDF 欄位交錯、需要匯出表格，或回答必須能回到原頁面，Docling 的資料模型較符合這類需求。這是功能定位的比較，不代表已用相同文件證明哪個工具準確率較高。

安裝 Docling

截至 2026 年 9 月 8 日， 最新正式版為 2.126.0 ，需要 Python 3.10 以上。以下以 Python 3.12 建立獨立環境，固定 Docling 版本，方便對照參數；指令與程式依官方文件和該版本原始碼整理，未包含本機速度或辨識準確率實測。

交給 Agent 的安裝與轉換提示詞

使用具備檔案讀寫與終端機執行權限的 Agent（例如 Claude Code、Codex）時，可把下列整段文字貼進對話，將來源檔案改成 PDF 的完整路徑。提示詞已包含環境檢查、安裝、轉換與驗收要求，不必逐條輸入後面的指令；套件或模型尚未備妥時，提示詞要求 Agent 先確認下載需求。這是依本文流程整理的任務範本，並非 Docling 官方提示詞。

請使用 Docling 完成以下 PDF 的本機轉換。

來源檔案：[貼上 PDF 的完整路徑]
輸出資料夾：來源檔案旁新建 docling-output
處理範圍：前 3 頁；不足 3 頁就處理全部頁面
目標：Markdown、Docling JSON、圖片與表格 CSV

先檢查作業系統、Python、Docling 版本與可用資源。
路徑未填、找不到檔案或沒有終端機權限時，
請指出缺少的條件，等待補充。

缺少 Docling 時，使用獨立虛擬環境，
依官方文件準備 docling[easyocr]==2.126.0。
首次轉換可能下載版面、表格或 OCR 模型；
安裝或下載前，列出所需套件、模型、預估下載量、
記憶體需求、執行範圍與風險，取得同意再執行。
無法可靠估算的數值請標示未知。

檢查指定頁面是否有可用文字層。
文字型 PDF 使用 --no-ocr；掃描頁使用 EasyOCR，
語言設為 ch_tra,en，需要整頁辨識時使用
--ocr-mode full_page。依已安裝版本的 --help
確認 docling convert 參數，不要猜測旗標。

使用標準處理流程，一次只執行一份轉換。
保留來源檔案，輸出重名時另建資料夾。
圖片另存並保留相對引用，表格透過 Python API
匯出 CSV；只安裝本次流程需要的相依套件。
不額外載入大型語言模型，也不擴大頁數或批次範圍。

完成後檢查文字是否空白、圖片連結是否有效，
並對照原頁面的閱讀順序與表格欄位。
列出輸出檔案的完整路徑、實際處理頁數、
使用版本與 OCR 設定，以及錯誤和待人工核對處。
無法對照原頁面時，明確列為未驗證。

在輸出資料夾保存可重跑的指令或 Python 腳本。
以實際執行結果回報，失敗時保留錯誤訊息。

官方文件：
https://docling-project.github.io/docling/

預設先處理前 3 頁，適合確認輸出是否符合用途。完成後可沿用產生的指令或腳本，指定新的頁數範圍；一般聊天介面若沒有檔案與執行工具，只能提供操作建議，不能代替本機執行。

macOS 與 Linux

電腦需先有 Python 3.12。macOS 可開啟「終端機」，Linux 使用既有 shell；在準備放範例文件的位置建立工作資料夾：

# 建立專用資料夾與 Python 環境
mkdir docling-demo
cd docling-demo
python3.12 -m venv .venv
source .venv/bin/activate

# 安裝本文版本與 EasyOCR 支援
python -m pip install "docling[easyocr]==2.126.0"
python -m pip show docling
docling convert --help

Windows PowerShell

以下使用 Python Launcher 選擇已安裝的 Python 3.12，直接呼叫虛擬環境內的程式，不必修改 PowerShell 的執行原則。

# 建立環境並安裝
mkdir docling-demo
cd docling-demo
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install "docling[easyocr]==2.126.0"
.\.venv\Scripts\python.exe -m pip show docling
.\.venv\Scripts\docling.exe convert --help

後面的多行 shell 範例採 macOS／Linux 寫法，反斜線 \ 表示接到下一行。PowerShell 使用時可把同一指令合成一行，並將開頭的 docling 換成 .\.venv\Scripts\docling.exe。Python 範例則可跨平台使用。

第一次使用會下載模型

安裝 Python 套件與準備模型是兩件事。 官方進階設定 說明，相關模型預設會在第一次使用時自動下載，OCR 引擎也可能另外取得語言模型。因此首次轉換要有網路與足夠磁碟空間，不能把第一次等待時間直接當成每份文件的轉換時間。

macOS、Linux 與 Windows 都可使用，支援情況仍受所選引擎與相依套件影響。入門不必先設定遠端 API 或載入大型視覺語言模型；一般 PDF 可以先從標準流程開始。需要 GPU 時再依 安裝文件 配置相符的運算套件。

用 CLI 把 PDF 轉成 Markdown

準備一份至少 3 頁、可選取文字的 PDF，命名為 report.pdf，放在 docling-demo 資料夾。第一輪只處理前 3 頁，檢查品質後再移除頁數限制。若文件不足 3 頁，請把結束頁碼改成實際頁數。

單一文件與輸出目錄

# 文字型 PDF：先關閉 OCR，只處理前 3 頁
docling convert report.pdf \
  --to md \
  --output output \
  --page-range 1-3 \
  --no-ocr \
  --device cpu \
  --num-threads 2

這個指令會把 Markdown 寫到 output/report.md。--output 指定的是資料夾，與 MarkItDown 的 -o report.md 檔名參數不同；Docling 的 CLI 會自行寫檔，不需要用 > 擷取終端機輸出。參數以 CLI reference 為準。

關閉 OCR 只適用於已有可用文字層的文件。掃描 PDF、整頁圖片或文字層有問題時，應使用下一章的 OCR 設定；--no-ocr 也不等於整個標準流程完全不使用模型，版面與表格仍有自己的處理步驟。

同時保留 Markdown、JSON 與圖片

DoclingDocument 匯出 Markdown 與 JSON，分別用於閱讀及保存結構和來源位置
需要回查來源時，另外保存結構化資料。
# Markdown 供閱讀，JSON 保存文件結構
docling convert report.pdf \
  --to md --to json \
  --image-export-mode referenced \
  --output output-with-images \
  --page-range 1-3 \
  --no-ocr

--to 可重複指定。referenced 會將圖片另存 PNG，再由文件引用；embedded 把圖片資料嵌入檔案，檔案通常較大；placeholder 只標示圖片位置。需要把結果搬到其他電腦時，應連同圖片子資料夾一起搬移，保留相對路徑。

圖片匯出與圖片理解也要分開：把圖片存下來，不等於已經把圖中的折線、流程或圖例轉成文字。交給支援圖片的 AI 工具時，要一併提供圖檔；只讀純文字的系統則需另做圖片描述，並檢查描述是否正確。

整個資料夾批次轉換

# documents 只放本次要轉的 PDF
docling convert documents \
  --from pdf \
  --to md --to json \
  --image-export-mode referenced \
  --output batch-output \
  --abort-on-error

這裡使用 Docling 預設的 OCR 設定；需要固定繁體中文引擎時，再加下一章的參數。--abort-on-error 讓遇到明確轉換錯誤時停止；部分成功仍須查看終端機的失敗紀錄，不能只看見部分輸出就以為整批完成。不同來源若有相同檔名，建議分開輸出目錄，避免結果互相覆寫。

掃描 PDF 與繁體中文 OCR

Docling 的 OCR 能選擇不同引擎，但語言代碼與支援範圍由引擎決定。依前述指令安裝 EasyOCR 擴充後，可明確指定繁體中文 ch_tra 與英文 en，避免直接套用不適合文件的預設語言。 OCR 語言設定 也提供各引擎的代碼說明。

# scanned.pdf 為至少 3 頁的繁體中文掃描文件
docling convert scanned.pdf \
  --ocr-engine easyocr \
  --ocr-lang ch_tra,en \
  --ocr-mode full_page \
  --to md --to json \
  --output ocr-output \
  --page-range 1-3

--ocr-mode full_page 會以整頁 OCR 處理文字，適合掃描文件或原有文字層不可靠的情況。已有正常文字層的 PDF 不必一律強制 OCR，否則可能增加時間並引入辨識錯誤。舊範例中的 --force-ocr 已標示棄用，本文使用現行參數。

引擎繁中與英文代碼範例前提
EasyOCRch_tra,en安裝 easyocr 擴充，首次可能下載模型
Tesseract CLIchi_tra,eng另裝 Tesseract 與對應語言資料
OcrMaczh-Hant,en-US僅 macOS，安裝 ocrmac 擴充

不要把一套引擎的語言碼直接複製到另一套。橫排、直排、手寫、低解析度與特殊字型也會影響結果；語言設定正確仍不保證辨識無誤。若只有少數頁面出問題，先取出那些頁面重新處理，比整份文件重跑更容易定位原因。

Python API：匯出文件、圖片與表格

只需要轉檔時，CLI 就足夠。需要整合到程式、分類輸出或處理失敗紀錄時，再使用 Python API。以下範例都把原始檔和輸出目錄分開，避免修改來源文件。

Markdown 與 JSON 基本轉換

將下列內容存成 convert_document.py，與 report.pdf 放在同一資料夾。這份範例使用標準預設流程，沒有沿用前面 CLI 的 --no-ocr 設定。

from pathlib import Path
from docling.document_converter import DocumentConverter

# 建立輸出目錄；來源文件至少 3 頁
output = Path("python-output")
output.mkdir(exist_ok=True)

converter = DocumentConverter()
result = converter.convert("report.pdf", page_range=(1, 3))
document = result.document

# Markdown 供閱讀，JSON 保留 Docling 的資料結構
(output / "report.md").write_text(
    document.export_to_markdown(), encoding="utf-8"
)
document.save_as_json(output / "report.json")
print("已輸出至", output.resolve())
# macOS / Linux，在已啟用的虛擬環境執行
python convert_document.py

Windows 可改用 .\.venv\Scripts\python.exe convert_document.py。這個簡單範例沒有要求保存圖片；若需要圖文一起交付，使用下一個範例。DoclingDocument 的 JSON 能保存解析取得的資訊，但不會補出來源原本沒有、或轉換時未取得的座標。

保留圖片並將表格另存 CSV

下列範例依官方 圖片匯出 與 表格匯出 做法改寫，存成 export_assets.py。表格輸出使用 pandas，執行前先在同一虛擬環境安裝 python -m pip install pandas。

from pathlib import Path
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import (
    DocumentConverter, PdfFormatOption,
)
from docling_core.types.doc import ImageRefMode

output = Path("assets-output")
output.mkdir(exist_ok=True)

# 保存可供匯出的頁面與圖片資料
options = PdfPipelineOptions()
options.generate_page_images = True
options.generate_picture_images = True
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=options)
    }
)
document = converter.convert(
    "report.pdf", page_range=(1, 3)
).document

# 使用外部圖片引用，搬移時保留整個輸出資料夾
document.save_as_markdown(
    output / "report.md", image_mode=ImageRefMode.REFERENCED
)
document.save_as_json(
    output / "report.json", image_mode=ImageRefMode.REFERENCED
)

# 每個偵測到的表格各存一份 CSV
for number, table in enumerate(document.tables, start=1):
    frame = table.export_to_dataframe(doc=document)
    frame.to_csv(
        output / f"table-{number}.csv",
        index=False,
        encoding="utf-8-sig",
    )
# 來源 report.pdf 放在同一資料夾
python export_assets.py

CSV 適合交給 Excel 或後續分析，但它無法保存所有合併儲存格與視覺排版。匯出後應核對欄名、單位、負號與小數點；沒有偵測到表格時，這段迴圈不會產生 CSV，不能把零個輸出直接解讀成原文件沒有表格。

若多欄表格被錯誤合成一欄，官方提供的調整方式是關閉原文文字與表格儲存格的配對（cell matching），改用表格模型預測的文字儲存格。在上例建立 DocumentConverter 之前加入以下設定，再用同一頁比較結果；這是可嘗試的修正方式，並不保證所有表格都會改善。

# 放在 converter = DocumentConverter(...) 之前
options.table_structure_options.do_cell_matching = False

批次處理與失敗紀錄

這份 batch_convert.py 逐一處理 documents 內的 PDF，重用同一個轉換器。每份文件使用獨立輸出資料夾，最後列出失敗項目，適合接到自己的文件整理流程。

import json
from pathlib import Path
from docling.datamodel.base_models import ConversionStatus
from docling.document_converter import DocumentConverter

converter = DocumentConverter()
failures = []
files = sorted(Path("documents").glob("*.pdf"))
if not files:
    raise SystemExit("documents 內沒有 PDF")

for source in files:
    try:
        result = converter.convert(source, raises_on_error=False)
        if result.status != ConversionStatus.SUCCESS:
            raise RuntimeError(str(result.status))

        target = Path("batch-output") / source.stem
        target.mkdir(parents=True, exist_ok=True)
        result.document.save_as_markdown(target / "document.md")
        result.document.save_as_json(target / "document.json")
        print("完成：", source.name)
    except Exception as error:
        failures.append({"file": str(source), "error": str(error)})
        print("失敗：", source.name, error)

Path("conversion-failures.json").write_text(
    json.dumps(failures, ensure_ascii=False, indent=2),
    encoding="utf-8",
)
print("成功：", len(files) - len(failures), "失敗：", len(failures))
# 先在 documents 放入要轉換的 PDF
python batch_convert.py

這份腳本只處理第一層資料夾中符合 *.pdf 的檔案，且把部分成功也列為待處理；執行前可先用 CLI 確認代表性文件。它沒有啟用圖片保存，適合文字與結構資料；需要圖片時，將上一節的圖片生成與匯出設定一併加入。

轉換結果怎麼檢查

有產生檔案，不代表轉換內容可以直接使用。建議至少各挑一頁普通段落、雙欄內容、表格與掃描頁，對照原始文件驗收，再決定是否整批處理。

文件轉換後檢查閱讀順序、表格欄位與圖片連結的三項重點
抽樣對照原始文件，才能發現轉換錯誤。
檢查項目應該看什麼發現問題後的動作
閱讀順序雙欄是否混在一起、頁尾是否插進段落縮小到有問題的頁面，比對原文與 JSON
表格表頭、單位、合併欄位與數字是否對應另存 CSV 核對，必要時人工整理
OCR繁簡字、相似字、負號與小數點確認引擎及語言，重做問題頁
圖片Markdown 連結能否找到圖檔保留整個輸出資料夾與相對路徑
來源檔名、版本、頁碼能否回查保存原檔及 JSON，不只留 Markdown

常見問題與處理方式

  • 找不到 docling 指令：確認虛擬環境已啟用；Windows 使用完整的 .venv\Scripts\docling.exe 路徑。用同一環境的 python -m pip show docling 檢查版本。
  • 輸出空白或缺文字：先確認是否為掃描頁、是否關閉 OCR，再指定正確引擎與語言；不應只靠更換輸出格式處理。
  • 第一次停在下載：查看終端機訊息與網路連線，先完成需要的模型下載。正式離線部署前可依官方進階文件預先準備模型，並指定 --artifacts-path。
  • CPU 或記憶體占用過高：先限制 --page-range、--num-threads，不要同時啟動多份轉換；無需保留整頁圖片時不要啟用該選項。
  • 需要查看解析版面：可用 --to html_split_page --show-layout 匯出圖文分頁對照的 HTML，並在頁面圖上顯示版面框線。

需要離線處理繁體中文 PDF 時，可在有網路的環境先準備標準版面、表格與 EasyOCR 模型。以下依官方進階設定改寫，只下載此流程使用的模型；搬移到另一台電腦時，Python 套件與相依環境也須先備妥。

# 有網路時：準備本例需要的模型
docling-tools models download layout tableformer easyocr \
  --easyocr-lang ch_tra --easyocr-lang en \
  --output-dir ./models

# 離線環境：沿用前面的掃描 PDF 範例
docling convert scanned.pdf \
  --artifacts-path ./models \
  --ocr-engine easyocr --ocr-lang ch_tra,en \
  --ocr-mode full_page \
  --page-range 1-3 \
  --to md --to json --output offline-output

需要人工查看版面辨識結果時，可使用下列 HTML 對照輸出。html_split_page 才會搭配 --show-layout 顯示框線，單用 --to html 不會套用這個視覺化。

# 原始頁面與解析內容的對照檔
docling convert report.pdf \
  --to html_split_page --show-layout \
  --image-export-mode embedded \
  --page-range 1-3 --no-ocr \
  --output layout-output

品質有問題時，應先找出是文字辨識、閱讀順序、表格結構或圖片引用哪一層出錯。直接把整份錯誤輸出交給語言模型重寫，可能讓錯誤變得更流暢，卻更難回查。

交給 AI 與建立 RAG 知識庫

短文件可先檢查 Markdown，再交給既有 AI 工具摘要。大型知識庫則需要把文件分段、建立索引，並讓每個片段保留來源。文件解析正確，是後續回答可靠的必要條件之一。

Markdown 與 JSON 的保存方式

Markdown 適合閱讀與交換，JSON 適合保存結構。若系統需要顯示引用頁碼，建議把原始 PDF、DoclingDocument JSON、圖檔與轉換設定一起保存，並記錄文件版本。只留下重新整理過的 Markdown，往往不足以重建原本的定位資訊。

分段與 MCP 整合

Docling 的 chunking 功能 可依文件結構切段；HybridChunker 會用 tokenizer 計算文字拆成 token 後的長度，再依設定上限調整片段。分段後，還需要用 embedding 模型把文字轉成可搜尋的向量，並將片段、向量和來源資訊存進資料庫。

如果使用支援 MCP 的 Agent，也可透過 Docling MCP server 呼叫文件轉換。MCP 是工具連接方式，並不會自動增加辨識準確率。只想轉幾份文件時，直接用 CLI 產生檔案通常更容易檢查；需要讓 Agent 反覆讀取不同文件，才有必要整理工具權限與服務設定。

Docling 可以使用本機模型處理文件，但若設定遠端 OCR 或視覺模型，資料流向就不同。機密文件除了確認轉換階段，也要確認後續摘要、embedding 與搜尋服務的處理位置，不能因為第一步在本機就把整條流程視為離線。

常見問答

是否需要雲端、GPU 或更換既有工具，取決於文件類型與使用的處理流程。

Docling 免費嗎？

程式碼採 MIT 授權，可在授權條件下使用與修改；模型授權需另查。本機執行仍會使用磁碟與運算資源，外接雲端服務則依服務本身計費。

一定需要 GPU 或大型語言模型嗎？

不一定。標準文件處理可使用 CPU，並由版面、表格和 OCR 等元件分工。視覺語言模型（VLM）是另一種可選流程，不必為了把 PDF 轉 Markdown 就先部署大型聊天模型。

Markdown 會保留 PDF 的完整排版嗎？

不會。Markdown 能表達標題、清單與表格等結構，但無法完整重現字型、座標與所有合併儲存格。需要比對外觀時保留原始 PDF；需要程式回查結構時另外保存 JSON。

Docling 會讓 RAG 回答更準嗎？

當原本的問題是文件解析錯誤時，改善解析可能有幫助；但分段、搜尋、模型與問題本身也會影響回答。不能只憑換了轉換工具，就保證整體準確率提升。

已經使用 MarkItDown，需要改用 Docling 嗎？

如果現有輸出能正確保留需要的資訊，不必為換工具而重建流程。只有複雜 PDF、OCR 設定、表格匯出或來源定位的需求超出目前做法時，再用代表性文件評估 Docling。MarkItDown 的安裝與既有應用可參考 MarkItDown 教學 。

參考來源

Post Views: 44
Tags:
Sponsored Links

發佈留言