microsoft/markitdown

⭐ 65,383 🍴 3,467 Python📄 MIT License GitHubで見る →

主な特徴

PDF、PowerPoint、Word、Excel、画像、音声ファイルなど多様な形式に対応
画像のEXIFメタデータとOCR対応
音声の文字起こし機能
HTML、CSV、JSON、XMLなどのテキストベース形式のサポート
ZIPファイルの内容を反復処理
YouTubeのURL、EPubファイルにも対応
Azure Document Intelligenceとの統合
LLMを使用した画像の説明生成
サードパーティプラグインシステム
MCP（Model Context Protocol）サーバー統合

リポジトリ解析: microsoft/markitdown

基本情報

リポジトリ名: microsoft/markitdown
主要言語: Python
スター数: 65,383
フォーク数: 3,467
最終更新: 2025-06-03 21:09:25
ライセンス: MIT License
トピックス: ドキュメント変換、Markdown、LLM、テキスト抽出、AutoGen Team

概要

一言で言うと

様々なファイル形式をMarkdownに変換するPythonユーティリティで、LLMやテキスト分析パイプラインでの利用に最適化されています。

詳細説明

MarkItDownは、LLMや関連するテキスト分析パイプラインで使用するために、様々なファイルをMarkdownに変換する軽量なPythonユーティリティです。textractと比較されることが多いですが、重要なドキュメント構造とコンテンツをMarkdown（見出し、リスト、テーブル、リンクなど）として保持することに焦点を当てています。出力は人間にもある程度読みやすい形式ですが、主にテキスト分析ツールによる利用を想定しており、人間向けの高忠実度のドキュメント変換には最適ではない可能性があります。

Markdownを採用した理由は、主流のLLM（OpenAIのGPT-4oなど）がMarkdownを「ネイティブに理解」し、応答に自然に組み込むことが多いからです。これは、大量のMarkdown形式のテキストで訓練されていることを示唆しています。副次的な利点として、Markdownの規約はトークン効率も高いです。

主な特徴

PDF、PowerPoint、Word、Excel、画像、音声ファイルなど多様な形式に対応
画像のEXIFメタデータとOCR対応
音声の文字起こし機能
HTML、CSV、JSON、XMLなどのテキストベース形式のサポート
ZIPファイルの内容を反復処理
YouTubeのURL、EPubファイルにも対応
Azure Document Intelligenceとの統合
LLMを使用した画像の説明生成
サードパーティプラグインシステム
MCP（Model Context Protocol）サーバー統合

使用方法

インストール

前提条件

Python 3.10以上
仮想環境の使用を推奨（依存関係の競合を避けるため）

インストール手順

# 方法1: PyPIからインストール（すべての依存関係を含む）
pip install 'markitdown[all]'

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

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

基本的な使い方

Hello World相当の例

from markitdown import MarkItDown

# MarkItDownインスタンスを作成
md = MarkItDown(enable_plugins=False)

# ファイルを変換
result = md.convert("test.xlsx")
print(result.text_content)

実践的な使用例

from markitdown import MarkItDown
from openai import OpenAI

# LLMクライアントを使用した画像説明の生成
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)

# Azure Document Intelligenceを使用したPDF変換
md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

高度な使い方

# コマンドラインでの使用
markitdown path-to-file.pdf > document.md

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

# パイプを使用
cat path-to-file.pdf | markitdown

# Document Intelligenceを使用
markitdown path-to-file.pdf -o document.md -d -e "<endpoint>"

# プラグインを有効化
markitdown --use-plugins path-to-file.pdf

# Dockerを使用
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

ドキュメント・リソース

公式ドキュメント

README.md: インストール方法、使用方法、オプション依存関係、貢献ガイドラインを含む包括的なドキュメント
packages/markitdown/README.md: 基本的なインストールと使用方法
packages/markitdown-mcp/README.md: MCP（Model Context Protocol）サーバーのドキュメント
packages/markitdown-sample-plugin/README.md: プラグイン開発ガイド

サンプル・デモ

markitdown-sample-plugin: RTFコンバーターを実装したプラグインの完全な例
テストファイル: tests/test_filesディレクトリに様々なファイル形式の変換例
プラグインシステム: サードパーティプラグインの作成と配布方法

チュートリアル・ガイド

GitHubのREADMEに基本的な使用方法
Issues open for contribution - コミュニティ貢献のための課題
PRs open for reviewing - レビュー待ちのPR
Azure Document Intelligence設定の公式ドキュメント

技術的詳細

アーキテクチャ

全体構造

MarkItDownは、プラグインベースのアーキテクチャを採用しており、コンバーター登録システムによって拡張可能です。コアシステムはMarkItDownクラスが中心となり、様々なDocumentConverterサブクラスを優先度順に管理します。ファイルタイプの検出にはmagikaライブラリを使用し、各コンバーターは特定のファイル形式や条件に基づいて処理を行います。

ディレクトリ構成

markitdown/
├── packages/
│   ├── markitdown/            # メインパッケージ
│   │   ├── src/markitdown/    # ソースコード
│   │   │   ├── converters/    # 各種ファイル形式のコンバーター
│   │   │   └── converter_utils/# コンバーター用ユーティリティ
│   │   └── tests/             # テストスイート
│   ├── markitdown-mcp/        # MCPサーバー実装
│   └── markitdown-sample-plugin/ # プラグイン開発例
├── LICENSE                    # MITライセンス
├── README.md                  # メインドキュメント
└── Dockerfile                 # Docker設定

主要コンポーネント

MarkItDown: メインクラス、コンバーター管理とファイル変換の調整
- 場所: packages/markitdown/src/markitdown/_markitdown.py
- 依存: magika、requests、各種コンバーター
- インターフェース: convert(), convert_stream(), register_converter()
DocumentConverter: 全コンバーターの基底クラス
- 場所: packages/markitdown/src/markitdown/_base_converter.py
- 依存: なし
- インターフェース: convert(), handle()
各種コンバーター: PDF、DOCX、PPTX、画像、音声など
- 場所: packages/markitdown/src/markitdown/converters/
- 依存: 形式固有のライブラリ（pdfminer.six、python-docx等）
- インターフェース: 各コンバーター固有のhandle()メソッド

技術スタック

コア技術

言語: Python 3.10+ (型ヒント、async/await、データクラスなどのモダンな機能を使用)
フレームワーク: 特定のWebフレームワークは使用せず、純粋なPythonライブラリとして実装
主要ライブラリ:
- beautifulsoup4: HTML解析
- markdownify: HTMLからMarkdownへの変換
- magika (~0.6.1): ファイルタイプの検出
- charset-normalizer: 文字エンコーディングの検出
- defusedxml: 安全なXML解析
- requests: HTTP通信

開発・運用ツール

ビルドツール: hatchling (PEP 517準拠のビルドシステム)
テスト: pytest、テストベクトルによる包括的なファイル形式テスト
CI/CD: GitHub Actions（コード内の参照から推測）
デプロイ: PyPI、Docker、pipによるインストール

設計パターン・手法

Strategy パターン: 各ファイル形式に対応するコンバーターを個別のクラスとして実装
Registry パターン: コンバーターを優先度付きで登録・管理
Plugin アーキテクチャ: entry_pointsを使用したサードパーティプラグインのサポート
Dependency Injection: LLMクライアントやDocument Intelligenceエンドポイントの注入

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

入力受付: ファイルパス、URL、またはストリームを受け取る
ファイルタイプ検出: magikaライブラリとMIMEタイプで形式を特定
コンバーター選択: 登録されたコンバーターから優先度順に適切なものを選択
変換処理: 選択されたコンバーターがファイルをMarkdownに変換
後処理: データURIの処理、文字エンコーディングの正規化
結果返却: DocumentConverterResultオブジェクトとしてMarkdownとメタデータを返す

API・インターフェース

公開API

MarkItDownクラス

目的: メインのAPIインターフェース、ファイル変換の制御
使用例:

from markitdown import MarkItDown

# 基本的な使用
md = MarkItDown()
result = md.convert("document.pdf")

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

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

DocumentConverterResult

目的: 変換結果を格納するデータクラス
属性:
- text_content: 変換されたMarkdownテキスト
- markdown: text_contentのエイリアス

設定・カスタマイズ

オプション依存関係

# pyproject.tomlでの設定例
[project.optional-dependencies]
pptx = ["python-pptx"]
docx = ["mammoth", "lxml"]
xlsx = ["pandas", "openpyxl"]
pdf = ["pdfminer.six"]
audio-transcription = ["pydub", "SpeechRecognition"]

拡張・プラグイン開発

プラグインはmarkitdown.pluginエントリーポイントを使用して開発します：

# _plugin.py
from markitdown import DocumentConverter, DocumentConverterResult

class MyConverter(DocumentConverter):
    def handle(self, stream, source_info):
        # 変換ロジック
        return DocumentConverterResult(text_content="Converted content")

# pyproject.toml
[project.entry-points."markitdown.plugin"]
my-converter = "my_package._plugin:MyConverter"

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

パフォーマンス特性

ベンチマーク結果: 具体的な数値は公開されていないが、軽量設計を重視
最適化手法:
- ストリーム処理によるメモリ効率化（一時ファイルを作成しない）
- magikaによる高速なファイルタイプ検出
- オプション依存関係による最小限のメモリフットプリント

スケーラビリティ

純粋なPythonライブラリのため、水平スケーリングが容易
ステートレスな設計により、複数インスタンスでの並列処理が可能
大規模ファイルはストリーム処理で対応

制限事項

複雑なレイアウトやスタイリングの完全な保持は困難
一部のファイル形式では外部ツール（exiftool等）が必要
LLMベースの機能はAPIコストとレート制限に依存

評価・所感

技術的評価

強み

幅広いファイル形式のサポート（20種類以上）
拡張可能なプラグインアーキテクチャ
LLMとの統合が容易（Markdown出力のため）
活発な開発とMicrosoftによるサポート
シンプルで使いやすいAPI設計

改善の余地

専用のドキュメントサイトやチュートリアルの不足
一部の複雑なドキュメント構造の処理精度
パフォーマンスベンチマークの公開

向いている用途

LLMアプリケーションでのドキュメント処理
大量のファイルからのテキスト抽出とインデックス作成
RAG（Retrieval-Augmented Generation）システムの構築
ドキュメント変換パイプラインの構築
チャットボットやQ&Aシステムのデータ準備

向いていない用途

高忠実度のドキュメント変換（印刷品質）
複雑なレイアウトや書式の完全な保持が必要な場合
リアルタイムの大容量ファイル処理

総評

MarkItDownは、LLM時代に最適化された実用的なドキュメント変換ツールです。特にRAGシステムやLLMアプリケーションでの利用を想定した設計は秀逸で、Markdownという賢明な出力形式の選択により、様々なAIシステムとの統合が容易になっています。Microsoftの支援を受けた活発な開発とコミュニティ、プラグインシステムによる拡張性も魅力的です。ドキュメントの不足は課題ですが、シンプルなAPIと豊富なテストコードにより、実装は比較的容易です。