ツール

MarkItDown入門──LLMに渡す前に通したい、ドキュメント→Markdown変換の定番

Microsoft発のMarkItDownは、PDFやOffice文書、画像、音声、YouTubeリンクをMarkdownへ一括変換するオープンソースツール。RAGやAgentのデータ前処理パイプラインの最前段に位置する。

文字サイズ

RAGやAgentを組むとき、最初の工程は「embedding」だと思われがちだ。ところが実際に動かすと、embeddingの前にもう一段階ある。PDF・Word・PPTの中身を、モデルが安定的に読み取れるテキストに整える工程だ。

PDFは複数段組や表、脚注が混在する。PPTにはタイトル階層と箇条書きがある。Wordにはスタイル情報が紛れ込む。元のファイルをそのままモデルに渡しても、解析結果は予測しづらい。

Microsoftが公開しているMarkItDownは、まさにこの位置に差し込まれるツールだ。人間の閲覧用フォーマット変換でも、pixel-perfectな保真が目的でもない。さまざまなファイルをLLMが消費しやすいMarkdownへと圧縮することに特化している。

GitHubのStar数は174k以上(リポジトリの状況は随時変動するため、最新値はリポジトリページで確認してほしい)。対応フォーマットは以下のとおり。

  • PDF
  • Word
  • Excel
  • PowerPoint
  • 画像(EXIF・OCR対応)
  • 音声(EXIF・文字起こし対応)
  • HTML、CSV、JSON、XML
  • ZIP、EPub
  • YouTubeリンク

設計方針は明快で、出力は人間向けの整形済みドキュメントではなく、LLM向けの構造化テキストとなっている。

何の問題を解決するのか

embeddingの前処理としては、一般に次の3ステップが必要だ。

  1. 本文の抽出
  2. 見出し・リスト・表などの構造の保持
  3. 結果をモデルが扱えるサイズに分割

MarkItDownは主に最初の2ステップを担う。

同種のツールと比べると、textractはやや古く、出力が素のテキストになりがちで構造情報を多く失う。pandocはドキュメント変換と版面の保真に強みがあり、原稿に近いレイアウトを保ちたい場面に向く。unstructuredも機能は豊富だが、仕組みはより重く、独自の抽象レイヤーを備えている。

MarkItDownはその中間の路線を取る。

  • 十分に軽量
  • ある程度の文書構造を保持
  • LLM 친화的なMarkdownを出力
  • CLIとPython APIの両方を提供

Markdownは、複雑なHTMLや大量の書式タグ付きテキストと比べると、LLMにとって一般的にtoken消費を抑えられる。GPT-4oのようなモデルは、Markdownの見出し・リスト・表・コードブロックをネイティブに理解できる。

ただし、Markdownが常に最短の表現とは限らない。複雑なWordスタイルやPDFのヘッダ・フッタ、座標ベースのレイアウトは、変換後もノイズを残しがちだ。それでも、十分に安定した中間フォーマットを提供してくれる。以降のチャンク分割や検索・生成は、このテキストを基準に進められる。

使い方

Python 3.10以上が必要。全機能インストールは次のとおり。

pip install 'markitdown[all]'

PDFのみを扱いたい場合はこちら。

pip install 'markitdown[pdf]'

他にも[docx]、[pptx]、[xlsx]、[audio]などのグループがある。OCRや音声書き起こし、すべてのフォーマットを一律に入れる必要はない。

CLIは次のとおり。

markitdown file.pdf > out.md

Python APIは次のとおり。

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("report.pdf")
print(result.text_content[:500])

# 入力ソースを限定:ローカルファイルのみ
from markitdown import MarkItDown, convert_local
result = convert_local("report.pdf")
print(result.text_content[:500])

MarkItDown().convert()は入力に応じて適切な変換方式を選ぶ高レベルなAPIだ。convert_local()はより範囲を絞り、ローカルファイルのみを処理する。

セキュリティ面には注意が必要だ。READMEの冒頭にも明記されているが、MarkItDownはI/Oを伴うため、権限リスクはPythonのopen()やrequests.get()などのネットワークリクエストと同水準と考えてほしい。単なるドキュメント変換ライブラリだからと信頼できない入力や任意のURL、高権限のAgent環境に直接組み込むのは避けたほうがよい。

仕組み

コアの構造はシンプルだ。

  • MarkItDownクラスがひとつ
  • 複数のConverterサブクラス
  • 拡張子またはMIMEタイプに応じてConverterを振り分け
  • 各Converterがフォーマットごとの処理を担当

PDFはPdfConverter、WordはDocxConverter、PPTはPptxConverter、YouTubeリンクはYoutubeConverterが担当する。

この設計は、1つの大きな関数にif/elseを積み上げる方式より拡張しやすい。新フォーマットを追加するには、Converterを追加して振り分けロジックに繋ぐだけで済む。

APIは3層構成になっている。

  • 高層:MarkItDown().convert()
  • 中层:convert_local()
  • 低層:convert_stream()

呼び出し階層を下げるほど権限範囲は狭くなり、ローカルファイル・外部ネットワーク・ストリーム入力を明確に区別できる。Agentにとっては、この区別は装飾ではなく本質的な機能だ。Agentがユーザーの代理でファイルを読み、ネットワークにアクセスし、信頼できないURLを処理する以上、権限設計は中核機能になる。

画像と音声の経路はやや異なる。画像はEXIFを抽出し、設定に応じてOCRを実行する。音声はメタデータの抽出と音声認識を行う。これらは外部サービスに依存することが多いため、導入前にサービス仕様・コスト・データの流れを確認しておきたい。

得意な点・苦手な点

得意な点

対応範囲が広い。PDF、Office、画像、音声、Web、圧縮ファイル、YouTubeリンクを1つのツールで処理できる。

APIが段階的になっている。もっとも手軽なのは1行のCLI。組み込みたいときはMarkItDown().convert()。入力ソースを限定したいときはconvert_local()やconvert_stream()に降りる。

セキュリティへの言及が実践的。READMEはローカルファイル・ネットワーク・外部サービスのリスクを率直に説明している。

インストールが依存関係に配慮している。全量インストールは手軽で、フォーマット別の部分インストールは環境を軽量に保てる。

苦手な点

第一に、複雑なレイアウトの保真度はpandocに劣る。PDFの表組みがページをまたぐケース、脚注、フローティング画像、複雑なヘッダ、多段組レイアウトでは、変換後の順序が崩れることがある。OCRの精度も画像の文字品質に依存する。

第二に、画像OCRと音声書き起こしはAzureやOpenAIなどの外部サービスに依存することがある。完全ローカル・完全CPU運用・データ送信不可といった要件がある場合は、モデルや依存関係を自前で補う必要がある。

第三に、Excelは巨大なファイルをそのまま放り込むのに向かない。大きなワークブック、結合セル、関数、非表示シートは処理速度を落とすだけでなく、無関係な内容を大量に取り込んでしまう。本番環境では、シートの選別や行列範囲の絞り込み、関数のクリア、あるいは表単位の分割をあらかじめ施しておきたい。

つまりMarkItDownはpandocの代替でも、「あらゆる文書を完璧に復元する」パーサでもない。RAGパイプラインにおける最初の洗浄フィルタに近い立ち位置のツールだ。

実際に試してみた

ローカル環境にmarkitdown[pdf,docx,pptx]をインストールし、以下の3種類のドキュメントを試した。

  • 20ページ・表を含む決算報告PDF
  • 20ページのPPT
  • 5ページのWord

結果は以下のとおり。

  • PDFの表はほぼ保持され、見出し階層も正しかった
  • PPTは箇条書きの構造を保っていた
  • Wordは段落と見出しが安定して出力された
  • PDFは約2秒
  • PPTは約1秒
  • Wordは1秒未満

処理速度はファイル複杂度に大きく左右される。今回の環境ではPDF解析の主なコストはPyMuPDFのページ処理だった。パイプライン全体を遅くするボトルネックは、巨大なExcelであることが多い。

RAGに投入する際は、result.text_contentの後に2ステップを踏みたい。まずは見出しと段落でチャンクを切り、次に表・ページ番号・ファイル名をメタデータとして付与する。500ページのPDFをまとめて1回のconvert()に放り込み、检索品質の安定を期待するのは避けたほうがよい。

どんな人に向くか

向いているケース。

  • RAGのドキュメント前処理
  • Agentツールチェーンのデータ入り口
  • 大量のドキュメントを一括洗净したい場面
  • PDF・Word・PPTをMarkdownへ統一したいスクリプト
  • 拡張子やMIMEタイプで変換器を振り分けたいプロジェクト

向いていないケース。

  • ピクセル単位・出版品質のレイアウト保真が要求される場面
  • 完全オフラインが必須の画像OCR・音声書き起こし
  • 複雑なExcel帳票のファイル一括変換
  • 座標単位でのPDF位置特定、読み順の厳密な復元、厳格なテーブル意味論が求められるプロジェクト

使い分けの基準はシンプルで、LLMにテキストを食わせたいならまずMarkItDownを試す。レイアウトをできる限り保ちたいならpandoc。複雑な文書分区や重いデータ処理が必要ならunstructuredを検討する、という方針になる。

MarkItDownの価値は「対応フォーマット数の多さ」自体にはない。Agentが世界を受け取る方法を、ファイルが入ってMarkdownが出てくる、という1ステップに集約している点にある。

出典: https://github.com/microsoft/markitdown