microsoft/markitdown

⭐ 66,854 🍴 3,545 Python📄 MIT License GitHubで見る →

主な特徴

  • 20以上のファイル形式をサポート（PDF、Word、Excel、PowerPoint、画像、音声など）
  • プラグインアーキテクチャによる拡張性
  • Azure Document Intelligenceとの統合
  • LLMを使用した画像説明生成
  • CLI、Python API、Docker、MCP（Model Context Protocol）サーバーの提供
  • ストリームベースの処理（一時ファイルを作成しない）
  • オプショナルな依存関係による軽量インストール

リポジトリ解析: microsoft/markitdown

基本情報

  • リポジトリ名: microsoft/markitdown
  • 主要言語: Python
  • スター数: 66,854
  • フォーク数: 3,545
  • 最終更新: 最新の活発な開発中
  • ライセンス: MIT License
  • トピックス: ドキュメント変換、Markdown、LLM、AutoGen Team、Microsoft、ファイル変換

概要

一言で言うと

MarkItDownは、様々なファイル形式をLLMやテキスト分析パイプラインで使用するためのMarkdownに変換する軽量なPythonユーティリティです。

詳細説明

MarkItDownは、Microsoft AutoGenチームによって開発された、多様なファイル形式をMarkdownに変換するツールです。textractと同様の目的を持ちながら、重要なドキュメント構造（見出し、リスト、表、リンクなど）をMarkdownとして保持することに重点を置いています。出力は人間にとって読みやすい形式ですが、主にテキスト分析ツールでの利用を想定して設計されています。

GPT-4oなどの主要なLLMがMarkdownを「ネイティブ言語」として理解し、トレーニングデータに大量のMarkdownが含まれていることから、Markdownフォーマットを採用しています。これにより、LLMとの高い互換性とトークン効率の良さを実現しています。

主な特徴

  • 20以上のファイル形式をサポート（PDF、Word、Excel、PowerPoint、画像、音声など）
  • プラグインアーキテクチャによる拡張性
  • Azure Document Intelligenceとの統合
  • LLMを使用した画像説明生成
  • CLI、Python API、Docker、MCP（Model Context Protocol）サーバーの提供
  • ストリームベースの処理（一時ファイルを作成しない）
  • オプショナルな依存関係による軽量インストール

使用方法

インストール

前提条件

  • Python 3.10以上
  • 仮想環境の使用を推奨（venv、uv、Anacondaなど）

インストール手順

# 方法1: pipを使用（全機能をインストール）
pip install 'markitdown[all]'

# 方法2: 特定の機能のみインストール
pip install 'markitdown[pdf, docx, pptx]'

# 方法3: ソースからインストール
git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

基本的な使い方

Hello World相当の例

# CLIでPDFをMarkdownに変換
markitdown example.pdf > output.md

# Python APIで変換
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("example.pdf")
print(result.text_content)

実践的な使用例

# 複数のファイル形式を処理
from markitdown import MarkItDown

md = MarkItDown(enable_plugins=True)

# Excelファイルを変換
result = md.convert("data.xlsx")
print(f"Title: {result.title}")
print(result.text_content)

# リモートURLから変換
result = md.convert("", url="https://example.com/document.pdf")

# ストリームから変換
with open("document.docx", "rb") as f:
    result = md.convert_stream(f, file_extension=".docx")

高度な使い方

# LLMクライアントを使用した画像説明生成
from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("complex_diagram.jpg")

# Azure Document Intelligenceを使用
md = MarkItDown(
    docintel_endpoint="https://your-resource.cognitiveservices.azure.com/"
)
result = md.convert("scanned_document.pdf")

# カスタムプラグインを有効化
md = MarkItDown(enable_plugins=True)
result = md.convert("custom_format.xyz")

ドキュメント・リソース

公式ドキュメント

  • README.md: プロジェクトの概要、インストール方法、基本的な使用方法
  • packages/markitdown-sample-plugin/README.md: プラグイン開発ガイド
  • packages/markitdown-mcp/README.md: MCP サーバーのセットアップと使用方法
  • CONTRIBUTING.md: コントリビューションガイドライン

サンプル・デモ

  • tests/test_files/: 各種ファイル形式のテストファイル
  • Docker サポート: Dockerfileによるコンテナ化された実行環境
  • MCP統合: Claude Desktopとの統合例

チュートリアル・ガイド

  • GitHub Issues/PRs: 「open for contribution」タグ付きのイシューとPR
  • プラグイン開発: #markitdown-pluginタグでGitHub検索
  • Azure Document Intelligence設定ガイド（README内）

技術的詳細

アーキテクチャ

全体構造

MarkItDownはプラグイン可能なコンバーターアーキテクチャを採用しています。中核となるMarkItDownクラスがコンバーターの登録と実行を管理し、各コンバーターはDocumentConverter基底クラスを継承して実装されます。

ディレクトリ構成

markitdown/
├── packages/
│   ├── markitdown/           # メインパッケージ
│   │   ├── src/markitdown/
│   │   │   ├── converters/  # 各種ファイル形式のコンバーター
│   │   │   ├── converter_utils/  # コンバーター用ユーティリティ
│   │   │   └── _markitdown.py   # メインクラス
│   │   └── tests/            # テストコードとテストファイル
│   ├── markitdown-mcp/       # MCPサーバー実装
│   └── markitdown-sample-plugin/  # プラグインサンプル
├── .github/workflows/         # CI/CD設定
└── Dockerfile                 # Dockerコンテナ定義

主要コンポーネント

  • MarkItDown: メインコンバーター管理クラス

    • 場所: _markitdown.py
    • 依存: DocumentConverter、StreamInfo
    • インターフェース: convert(), convert_stream(), register_converter()

  • DocumentConverter: コンバーター基底クラス

    • 場所: _base_converter.py
    • 依存: StreamInfo
    • インターフェース: accepts(), convert()

  • StreamInfo: ファイルメタデータ情報

    • 場所: _stream_info.py
    • 保持情報: mimetype, extension, charset, url

技術スタック

コア技術

  • 言語: Python 3.10+、型ヒントを使用
  • フレームワーク: 特定のフレームワークに依存せず、標準ライブラリを中心に構築
  • 主要ライブラリ:
    • beautifulsoup4: HTML/XML解析
    • markdownify: HTMLからMarkdownへの変換
    • magika (~0.6.1): ファイルタイプ検出
    • pdfminer.six: PDF解析 (オプション)
    • mammoth: Wordドキュメント変換 (オプション)
    • pandas: Excelファイル処理 (オプション)

開発・運用ツール

  • ビルドツール: Hatchを使用、pyproject.tomlベースの設定
  • テスト: pytest、パラメータライズドテストベクターを使用
  • CI/CD: GitHub ActionsでPython 3.10, 3.11, 3.12でのテスト、pre-commitチェック
  • デプロイ: PyPI、Docker Hub、MCPサーバーとしてのデプロイ

設計パターン・手法

  • プラグインアーキテクチャ: Pythonのエントリポイントを使用した動的プラグイン登録
  • Strategyパターン: 各コンバーターが共通インターフェースを実装
  • 優先度ベースコンバーター選択: ファイル形式に対して最適なコンバーターを選択
  • ストリーム処理: メモリ効率のためBinaryIOを使用

データフロー・処理フロー

  1. 入力: ファイルパス、URL、またはバイナリストリーム
  2. メタデータ抽出: magikaでファイルタイプを検出、StreamInfoを生成
  3. コンバーター選択: 登録されたコンバーターがaccepts()でチェック
  4. 変換実行: 選択されたコンバーターのconvert()で変換
  5. 出力: DocumentConverterResultとしてMarkdownとメタデータを返却

API・インターフェース

公開API

Python API

  • 目的: プログラムからのファイル変換
  • 使用例:
from markitdown import MarkItDown

# 基本的な変換
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

# ストリームからの変換
with open("document.xlsx", "rb") as f:
    result = md.convert_stream(f, file_extension=".xlsx")

# コンバーターの登録
md.register_converter(MyCustomConverter(), priority=5.0)

MCPサーバーAPI

  • 目的: LLMアプリケーションとの統合
  • ツール名: convert_to_markdown
  • サポートURI: http:, https:, file:, data:

設定・カスタマイズ

CLIオプション

# ファイルタイプヒント
markitdown -x .pdf -m application/pdf input

# Azure Document Intelligenceを使用
markitdown -d -e "https://resource.azure.com/" file.pdf

# プラグインを有効化
markitdown --use-plugins custom_file.xyz

拡張・プラグイン開発

  1. DocumentConverterを継承したクラスを作成
  2. accepts()とconvert()メソッドを実装
  3. pyproject.tomlにエントリポイントを定義
  4. __plugin_interface_version__ = 1をエクスポート

パフォーマンス・スケーラビリティ

パフォーマンス特性

  • ストリームベース処理によるメモリ効率性
  • magikaによる高速ファイルタイプ検出
  • 優先度ベースコンバーター選択で適切なコンバーターを迅速に選択
  • オプショナル依存関係による軽量インストール

スケーラビリティ

  • ZIPファイルの再帰的処理による大量ファイルのバッチ処理
  • MCPサーバーによるマイクロサービスアーキテクチャ対応
  • Dockerコンテナ化によるスケーラブルなデプロイ

制限事項

  • 高忠実度のドキュメント変換は主目的ではない（テキスト分析用）
  • 複雑なレイアウトや図表の完全な再現は保証されない
  • LLMやAzure Document Intelligenceを使用する場合はAPIコストが発生

評価・所感

技術的評価

強み

  • 幅広いファイル形式への対応（20以上の形式）
  • 明確なプラグインアーキテクチャによる高い拡張性
  • Microsoftによるメンテナンスと活発なコミュニティ
  • LLMとの高い親和性（Markdown出力）
  • ストリームベース処理によるメモリ効率性

改善の余地

  • 複雑なテーブルやレイアウトの変換精度
  • オフラインOCR機能の限定性（外部APIに依存）
  • パフォーマンスメトリクスのドキュメント化

向いている用途

  • LLMを使用したドキュメント分析・要約
  • RAG（Retrieval-Augmented Generation）システムでのデータ前処理
  • ドキュメントの内容検索・インデックス作成
  • バッチ処理による大量ドキュメントの変換
  • CI/CDパイプラインでのドキュメント処理

向いていない用途

  • 高忠実度のプリント用ドキュメント変換
  • 複雑なフォーマットを完全に保持したファイル変換
  • リアルタイム音声/動画ストリーミング処理

総評

MarkItDownは、多様なファイル形式をLLMが理解しやすいMarkdownに変換することに特化した優れたツールです。Microsoft AutoGenチームによる開発で、品質とメンテナンスの信頼性が高く、プラグインアーキテクチャによる拡張性も備えています。

LLMとの統合を前提とした設計は、現代のAIアプリケーション開発において大きな価値を提供しており、特にRAGシステムやドキュメント分析パイプラインの構築において重要なコンポーネントとなるでしょう。