microsoft/markitdown

MarkItDown – LLM パイプライン向けファイルから Markdown への変換

これは何か – 幅広いドキュメントタイプ（PDF、Word、PowerPoint、Excel、画像、音声、HTML、JSON、CSV、ZIP、YouTube 動画、EPub など）を Markdown に変換する軽量な Python ライブラリおよび CLI です。出力は見出し、リスト、テーブル、リンクなどの構造的な手がかりを保持し、大規模言語モデルが取り込みやすくなります。

なぜ Markdown か？ – LLM は Markdown で大量にトレーニングされています。この形式はプレーンテキストでありながら表現力があり、トークン効率が良いため、生のファイルを Markdown に変換することで、下流のテキスト分析品質が向上します。

主な機能

• 一般的な Office 形式向けのローカル・オフラインコンバーター。
• オプションのクラウドバックエンド：
  • Azure Document Intelligence – レイアウト認識抽出。
  • Azure Content Understanding – マルチモーダル（ドキュメント、画像、音声、動画）変換。構造化フィールド抽出（YAML front-matter）とカスタムアナライザーを備えます。
• LLM 駆動の画像説明 – OpenAI 互換クライアント（例：gpt-4o）をプラグインして、埋め込み画像のキャプションを生成できます。
• OCR プラグイン（markitdown-ocr）は、LLM ビジョンモデルを使用して画像ベースのテキストを抽出し、追加のバイナリを必要としません。
• プラグインシステム – サードパーティの拡張機能で新しい形式を追加できます。#markitdown-plugin タグで発見可能です。
• セキュリティを意識した API – 狭い変換関数（convert_local、convert_stream、convert_response）により、呼び出し側は I/O スコープを制限できます。

インストール

# コア + すべてのオプション形式サポート
pip install 'markitdown[all]'
# または必要なものだけ選ぶ（例：PDF + DOCX）
pip install 'markitdown[pdf,docx]'

開発時は、リポジトリをクローンしてパッケージを編集可能モードでインストールします：

git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

コマンドラインでの使用

# 単純な変換、stdout → markdown
markitdown path/to/file.pdf > out.md

# 出力ファイルを指定
markitdown path/to/file.pdf -o out.md

# パイプでデータを渡す
cat file.pdf | markitdown > out.md

--use-plugins を追加するとインストール済みのプラグインを有効にでき、--list-plugins で利用可能なものを確認できます。

Python API（基本）

from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)   # プラグインを読み込むには True に設定
result = md.convert('report.xlsx')
print(result.markdown)

Azure Document Intelligence の例：

md = MarkItDown(docintel_endpoint='https://<resource>.cognitiveservices.azure.com/')
print(md.convert('file.pdf').markdown)

Azure Content Understanding とカスタムアナライザー：

md = MarkItDown(
    cu_endpoint='https://<cu>.cognitiveservices.azure.com/',
    cu_analyzer_id='my-invoice-analyzer'
)
print(md.convert('invoice.pdf').markdown)   # YAML front-matter を含む

LLM 駆動の画像説明：

from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model='gpt-4o')
print(md.convert('photo.jpg').markdown)

ツールの拡張

• サードパーティのプラグインをインストール（pip install markitdown-ocr など）。
• packages/markitdown-sample-plugin のサンプルに従って独自のプラグインを作成し、リポジトリに #markitdown-plugin タグを付けます。
• インストールするオプションの依存関係を制御して、環境を軽量に保ちます。

セキュリティに関する考慮事項 MarkItDown は、呼び出しプロセスと同じファイルシステムおよびネットワーク権限で実行されます。ユーザーは信頼できない入力をサニタイズし、パス/URL を制限し、最も狭い変換関数（convert_local、convert_stream など）を使用して露出を制限する必要があります。

テストの実行

cd packages/markitdown
pip install hatch
hatch shell
hatch test

または、提供されている DevContainer を使用します。

ライセンスと貢献 MIT ライセンスのオープンソース（PyPI ページによる）。貢献は歓迎しますが、ライブラリの範囲内に留めてください。Web サービス、GUI、ホスト型 API は受け付けません。PR には Contributor License Agreement が必要です。