MarkPDFDownとは：PDFを画像化してMarkdownへ変換するLLMツールの使い方¶

対象 / ポイント

対象: 図表や数式を含むPDFを、RAG、検索、要約に使えるMarkdownへ変換したい開発者。

ポイント:

MarkPDFDownは各ページを画像化し、マルチモーダルLLMへ転記を依頼するOSSだ
複雑な見た目を扱いやすい一方、ページ数に応じてAPI送信と処理時間が増える
導入前に機密性を確認し、変換後はページ数、表、数式を原本と照合する

MarkPDFDownは、PDFの文字列をそのまま抜き出すツールではない。 PDFを300dpiのページ画像へ変換し、画像を1ページずつマルチモーダルLLMへ送ってMarkdownを書かせる¹²。この仕組みなら表や数式、段組みを見た目から読み取れるが、PDFの内容は設定したLLM事業者へ送信される。

この記事の問いは1つだ。MarkPDFDownはどのPDFに向き、どんな確認をすればLLMの入力データとして使えるのか。

結論：レイアウトが難しいPDFを少量から試すツール¶

MarkPDFDownが向くのは、通常のテキスト抽出では読む順番や構造が壊れるPDFだ。たとえば2段組みの論文、罫線が複雑な表、数式、画像として保存されたスキャン資料が候補になる。

反対に、テキスト層がきれいな大量PDFへ最初から使う必要はない。ローカル抽出で十分なら、外部APIへの画像送信とページ単位の推論コストを避けられる。

PDFの状態	最初の選択	MarkPDFDownの位置づけ
テキストを選択でき、段組みも単純	ローカルのテキスト抽出	読み順が崩れる場合だけ比較する
スキャン画像で文字中心	OCR	表や数式の構造が落ちる場合に試す
表、数式、図、複雑な段組みが多い	視覚対応の変換	有力な候補になる
機密情報を含む	承認済みの閉じた処理	外部API設定のまま使わない

重要なのは、OSSだからローカル完結とは限らない点だ。 MarkPDFDown本体はApache License 2.0で公開されている。変換処理はLiteLLMを通じてOpenAIまたはOpenRouterへ画像を送る構成である¹³。

仕組みは「ページ画像を順番に転記する」¶

処理の流れは単純で、挙動を予測しやすい。 PDF全体を一度にモデルへ渡さず、ページ単位の画像と転記指示に分ける。

PDF
  ↓ PyMuPDFで300dpi画像へ変換
page_0001.jpg, page_0002.jpg, ...
  ↓ LiteLLM経由で1ページずつ送信
ページごとのMarkdown
  ↓ 空行で連結
output.md

転記プロンプトは、見出し、文字装飾、数式、表の行列を識別し、数式はLaTeXで出力するよう求める⁴。入力はPDFに加え、JPG、JPEG、PNG、BMP、GIFにも対応する¹。

実装上、ページは順番に1件ずつ処理される。そのため、処理時間とAPI利用量はおおむねページ数に比例すると考えるのが安全だ。これは料金保証ではなく、現行コードから導ける運用上の見積もりである⁴。

最小導入はリポジトリを取得してuvで実行する¶

公式READMEが推奨するCLI導入は、リポジトリを取得してuvで依存関係を用意する方法だ¹。 Python 3.9以上と、利用するLLM事業者のAPIキーが必要になる。

git clone https://github.com/MarkPDFdown/markpdfdown.git
cd markpdfdown
uv sync
uv pip install -e .
cp .env.sample .env

.envではモデルとAPIキーを指定する。次はOpenAIを使う最小例だが、モデル名と料金、提供状況は実行時点の公式情報で確認する。

MODEL_NAME=gpt-4o
OPENAI_API_KEY=your-openai-api-key
TEMPERATURE=0.3
MAX_TOKENS=8192
RETRY_TIMES=3

基本の変換コマンドは次の形になる。

markpdfdown --input document.pdf --output document.md

大きなPDFは、まず5ページほどに絞る。開始と終了は1始まりで指定でき、--end 0は最終ページを意味する⁵。

markpdfdown \
  --input document.pdf \
  --output sample.md \
  --start 1 \
  --end 5

Dockerやパイプ入力にも対応するが、最初の評価ではファイルモードが失敗箇所を追いやすい。 GUI版は別リポジトリで公開され、npx -y markpdfdownから起動できる⁶。

変換後は4項目を原本と照合する¶

Markdownファイルが生成されたことは、変換が完全だった証明にならない。現行実装では、あるページのLLM呼び出しに失敗するとエラーを記録して空文字を返し、内容があるページだけを連結する⁴。つまり、コマンド全体が出力を作っても途中ページが欠ける可能性を考える必要がある。

最低限の確認項目は4つだ。

ページ対応: 原本の各ページに対応する内容が存在するか
表: 行列の数、セル結合、単位、注記が残っているか
数式: 記号、添字、分数、式番号が原本と一致するか
読み順: 段組み、脚注、図のキャプションが正しい順序か

RAGへ投入する場合は、ページ境界を示すコメントやメタデータを後処理で加えると追跡しやすい。 MarkPDFDownの現行出力は、ページごとの結果を空行で連結するため、引用元ページを厳密に残す処理は利用側で設計する必要がある⁴。

まず5ページで正解率ではなく、どの種類の欠落が起きるかを見る。

MarkItDownとは名前も設計も異なる¶

MarkPDFDownとMicrosoftのMarkItDownは別プロジェクトだ。 MarkPDFDownはPDFや画像を視覚モデルでMarkdownへ転記することに集中する。

Microsoft MarkItDownは、PowerPoint、Word、Excel、PDF、画像、音声などをMarkdownへ変換するPythonツールだ⁷。名称が似ているため、インストール手順やGitHubリポジトリを取り違えないようにする。

	MarkPDFDown	Microsoft MarkItDown
主対象	PDF、画像	Office、PDF、画像、音声など
中心設計	ページ画像をマルチモーダルLLMで転記	形式別コンバーターでMarkdown化
外部LLM	変換の中心	一部機能で任意利用
選び方	視覚構造を優先	多形式を共通入口へ集める

どちらを選ぶかはスター数では決まらない。視覚的な読み取りが必要か、複数形式を同じパイプラインへ入れたいかで決まる。

まとめ：本番導入では「変換」と「採用」を分ける¶

PDFからMarkdownを作る工程と、そのMarkdownを検索や回答生成に採用する工程は分けた方がよい。変換直後のファイルを自動で本番インデックスへ入れると、欠落や誤転記も検索知識として固定される。

実務では、原本のハッシュ、ページ数、利用モデル、変換日時、確認結果をマニフェストへ残す。同じPDFを別モデルで再変換したときも、差分を追える。

MarkPDFDownの価値は、複雑なPDFを「読める形」にする入口にある。 信頼できる知識へ変えるには、ページ単位の照合と採用判定を別工程として足す必要がある。