AI パイプラインにドキュメントを取り込む — Python から直接、オンプレミスで、pip install ひとつで。

本日、GroupDocs.Markdown for Python via .NET の 初のパブリックリリース を PyPI で提供開始しました。このライブラリは PDF、Word、Excel、EPUB など 20 以上のフォーマットを、LLM や RAG パイプライン、静的サイトジェネレータが最も扱いやすいクリーンでセマンティックな Markdown に変換します。

もし .NET の 9 月リリース（または 26.3 のフル API オーバーホール）を追ってきたなら、理由は同じです。ドキュメントの書式はセマンティクスを保持しており、その構造を保つことが RAG システムで良い回答を得る鍵となります。前回の記事では 問題点（OCR が構造を平坦化し、LLM が Markdown を必要とする）と 解決策（ドキュメントを走査して Markdown を出力する DOM ベースのレンダラ）を詳しく解説しましたので、ここでは繰り返しません。

代わりに、Python 開発者向けの新機能に焦点を当てます。

What you get

  • 単一の wheel、ランタイム依存なし。 pip install groupdocs-markdown-net で .NET ランタイムと必要なすべてのネイティブライブラリをバンドルした自己完結型の wheel が取得できます。dotnet のインストールも、Microsoft Office も、Adobe Acrobat も、クラウドサービスも不要です。
  • クロスプラットフォーム。 Windows x64/x86、Linux x64、macOS x64、Apple Silicon (ARM64)。Python 3.5 から 3.14 まで対応。
  • Pythonic な API。 クラスは PascalCase、メソッドとプロパティは snake_case、列挙型の値は UPPER_SNAKE_CASE を使用。コンテキストマネージャでロードしたドキュメントを決定的に破棄できます。
  • 真の非同期対応。 すべての静的・インスタンスメソッドに _async バージョンがあります。ファイル I/O は非同期で、CPU バウンドな変換はワーカースレッドで実行されるため、asyncio イベントループはブロックされません。
  • AI エージェントに優しい。 インストールされた wheel には AGENTS.md が同梱されており、コーディングアシスタント（Claude Code、Cursor、GitHub Copilot、Codex）が API の全体像、慣用的な使用パターン、トラブルシューティング情報を自動的に取得できます。ドキュメントは llms.txt、単一ファイルコーパス (llms-full.txt)、ページ単位の Markdown、MCP サーバーとしても公開されます — 詳細は下記 AI-friendly by design を参照してください。

Get started

pip install groupdocs-markdown-net

最もシンプルな変換はワンライナーです。

from groupdocs.markdown import MarkdownConverter

# 文字列として取得
md = MarkdownConverter.to_markdown("business-plan.docx")

# 直接ファイルに書き出し
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

これだけです — 設定不要、オプション不要、ボイラープレート不要。評価モードでは最初の 3 ページが処理され、透かしが付与されます。制限を外すにはライセンスを適用します。

from groupdocs.markdown import License

License().set_license("path/to/license.lic")

または環境変数 GROUPDOCS_LIC_PATH を設定すれば、インポート時に自動的に適用されます。

サポートされているフォーマット

Python パッケージは .NET ライブラリと同等のフォーマットを扱えます。

  • PDF — .pdf
  • Word / リッチテキスト — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • スプレッドシート — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • 電子書籍 — .epub, .mobi
  • テキスト / マークアップ / ヘルプ — .txt, .xml, .chm

Pythonic な例

変換オプションと画像戦略

from groupdocs.markdown import (
    MarkdownConverter,
    ConvertOptions,
    MarkdownFlavor,
    ExportImagesToFileSystemStrategy,
)

strategy = ExportImagesToFileSystemStrategy("output/images")
strategy.images_relative_path = "images"  # ![](images/img-001.png)

options = ConvertOptions()
options.flavor = MarkdownFlavor.GIT_HUB
options.heading_level_offset = 1      # # Title -> ## Title
options.include_front_matter = True    # YAML メタデータを先頭に付加
options.image_export_strategy = strategy

MarkdownConverter.to_file("report.docx", "output/report.md", convert_options=options)

変換せずにドキュメント情報を取得

from groupdocs.markdown import MarkdownConverter

info = MarkdownConverter.get_info("business-plan.docx")
print(f"{info.file_format}, {info.page_count} pages, author: {info.author}")

パスワード保護されたファイルの読み込み

from groupdocs.markdown import MarkdownConverter, LoadOptions, FileFormat

load_opts = LoadOptions(FileFormat.DOCX)
load_opts.password = "secret"

MarkdownConverter.to_file("protected.docx", "output.md", load_options=load_opts)

ストリームとコンテキストマネージャ

from groupdocs.markdown import MarkdownConverter

with open("document.docx", "rb") as stream:
    with MarkdownConverter(stream) as converter:
        converter.convert("document.md")

非同期 API — 複数ドキュメントを同時に変換

ファイル I/O が非同期なので、asyncio.gather() を使って単一ワーカーが多数の変換をブロックせずに処理できます。

import asyncio
from groupdocs.markdown import MarkdownConverter

async def convert_many():
    await asyncio.gather(
        MarkdownConverter.to_file_async("a.docx", "a.md", None),
        MarkdownConverter.to_file_async("b.pdf",  "b.md", None),
        MarkdownConverter.to_file_async("c.xlsx", "c.md", None),
    )

asyncio.run(convert_many())

この特性により、FastAPI などの ASGI フレームワークでも、単一ワーカーが多数の同時変換リクエストをスレッド競合なしで処理できます。

エラーハンドリング

すべての変換メソッドは失敗時に例外をスローし、一般的なシナリオに対しては専用の例外型が用意されています。

from groupdocs.markdown import (
    MarkdownConverter,
    DocumentProtectedException,
    InvalidFormatException,
    GroupDocsMarkdownException,
)

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("Wrong or missing password.")
except InvalidFormatException:
    print("File is corrupt or unsupported.")
except GroupDocsMarkdownException as ex:
    print(f"Conversion failed: {ex}")

RAG と LLM パイプライン向けに構築

Markdown は埋め込みモデルや検索パイプラインの推奨入力形式です。見出し、リスト、テーブル、強調表現を保持しつつ、チャンク化やトークナイズが容易です。典型的な RAG インジェストは次のようになります。

import re
from groupdocs.markdown import MarkdownConverter, ConvertOptions, SkipImagesStrategy, MarkdownFlavor

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # RAG 用にテキストのみ
options.flavor = MarkdownFlavor.COMMON_MARK

MarkdownConverter.to_file("business-plan.pdf", "business-plan.md", convert_options=options)

with open("business-plan.md", "r", encoding="utf-8") as f:
    markdown = f.read()

# トップレベル見出しで分割し、各チャンクを埋め込み/インデックス化
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

ライブラリは完全にオンプレミスで動作するため、機密文書が外部に流出することはありません。これは規制産業、法務チーム、社内ナレッジベースなどで特に重要です。

AI-friendly by design

多くの Python SDK は AI コーディングアシスタントを後付けで扱っていますが、開発者はドキュメントを指し示したり、例を貼り付けたり、試行錯誤でデバッグする必要があります。GroupDocs.Markdown for Python via .NET は逆です。エージェント（Claude Code、Cursor、GitHub Copilot、Codex）が手動設定なしで利用できるよう設計されています。

AGENTS.md が wheel に同梱

これは GroupDocs パッケージ初の試みで、インストールされた wheel 内に AGENTS.md が含まれます。このファイルは新興の AGENTS.md 仕様 に準拠した、AI コーディングアシスタント向けのプレーン Markdown README です。

pip install groupdocs-markdown-net を実行すると、次の場所に配置されます。

site-packages/groupdocs/markdown/AGENTS.md

AI アシスタントがプロジェクトを開くと、即座に以下を学習できます。

  • 完全な 公開 API（クラス、メソッド、列挙型、例外）とその関係性
  • 慣用的な使用パターン（静的 vs インスタンス API、同期 vs 非同期、画像戦略、フロントマター、エラーハンドリング）
  • よくある落とし穴 と回避策（例：ConvertOptions のオーバーロードが None を受け付けるか、パスワード保護ファイルの扱い方、変換警告の取得方法）
  • プラットフォーム固有のトラブルシューティング（macOS の libSkiaSharp、Linux の ICU など）

実際、エージェントに 「groupdocs-markdown-net を使って PDF フォルダーを RAG パイプライン用の Markdown に変換して」 と指示すれば、最初の試みで動くコードが生成されます — 方法名の妄想や引数順の誤り、インポート忘れがありません。

機械可読ドキュメント

AGENTS.md に無い情報を探すエージェント向けに、製品ドキュメントは機械可読形式でも提供しています。

  • 単一ファイルコーパス — すべてのドキュメントを結合した Markdown ファイル。エージェントのコンテキストウィンドウにそのまま投入可能:
    https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • ページ単位 Markdown — 任意のドキュメント URL に .md を付加すると生のソースが取得できます:
    https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • llms.txt インデックス — エージェントが必要なページへ誘導する llms.txt 形式の目次:
    https://docs.groupdocs.com/markdown/python-net/llms.txt

MCP サーバーによるライブドキュメント参照

Model Context Protocol に対応したエージェント向けに、ドキュメントを MCP サーバーとして公開しています。Claude Code や Cursor の設定に次を追加してください。

{
  "mcpServers": {
    "groupdocs-docs": {
      "url": "https://docs.groupdocs.com/mcp"
    }
  }
}

これでエージェントはトレーニングデータに依存せず、必要に応じて最新ドキュメントを問い合わせられます。

入力も出力も Markdown

ライブラリの 出力 が Markdown であり、LLM が RAG で最も扱いやすい形式です。また、ドキュメント自体 も Markdown で提供され、単一ファイルとして簡単にコンテキストウィンドウに取り込めます。エージェントがライブラリを使うコードを書く場合でも、エージェントが文書を理解する場合でも、共通の媒体は Markdown です。

Export Example

上記スニペットは、ライブラリで書ける最小限の実用プログラムに近いです。ここでは、同じアイデアを実行可能なプロジェクトとしてまとめました — ソースドキュメント、Python スクリプト、事前生成済み出力、requirements.txt、Dockerfile — 何も書かずにエンドツーエンドで試せます。

ソース DOCX

ソースファイル business-plan.docx は、見出し、テーブル、画像、メタデータを豊富に含む短いビジネスプランです。

Python スクリプト

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """GitHub フレーバーと YAML フロントマター付きで Word 文書を Markdown に変換するサンプル。"""

    # ワンライナー — Markdown 文字列を取得
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # オプション付き — ファイルに書き出し
    options = ConvertOptions()
    options.flavor = MarkdownFlavor.GIT_HUB
    options.include_front_matter = True
    options.heading_level_offset = 1
    MarkdownConverter.to_file("business-plan.docx", "quick-example.md", convert_options=options)

if __name__ == "__main__":
    quick_example()

出力 Markdown

quick-example.md の出力は、ドキュメントメタデータから自動抽出された YAML フロントマターで始まり、GitHub Flavored テーブルと見出し階層が 1 段階上がった形で変換されたコンテンツが続きます（大きな文書に埋め込む準備ができています）。

実行可能サンプルアプリ

すべてが同梱されたパッケージ: sample-app.zip。解凍後、次の手順で実行できます。

cd src
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python quick_example.py

または Docker で実行 — 同梱の Dockerfile は Linux 上でバンドルされた .NET ランタイムが必要とする ICU 依存関係を設定します。

cd src
docker build -t groupdocs-markdown-python-example .
docker run --rm -v "$(pwd)/output:/app/output" groupdocs-markdown-python-example

Summary

GroupDocs.Markdown for Python via .NET は、外部ランタイムやクラウド不要の自己完結型 wheel として、ドキュメントから Markdown への変換エンジンを Python に提供します。Pythonic な API、非同期サポート、そして AI ツールとのファーストクラス統合により、RAG システム、静的サイトジェネレータ、ドキュメント処理パイプラインを構築する Python チームにとって実用的な選択肢となります。

Learn more

Support & feedback

質問や技術的な支援が必要な場合は、Free Support Forum をご利用ください — 喜んでサポートいたします。