MarkItDown ウェブスクレイピング: ページを LLM 対応 Markdown に変換する

TL;DR:

• MarkItDownは、スクレイピングしたHTMLページをMarkdownに変換し、言語モデルがよく読み取れる見出し、リンク、リストを保持します。
• スクレイピングはメモリ内にHTMLを取得するので、ガイドではファイルパスの代わりにBytesIOを使ったconvert_streamを使用します。
• MarkItDownにはブロックをクリアするフェッチ層がないため、Scrapelessがページを取得し、MarkItDownが変換します。
• 例のページでは、11,021文字のHTMLが2,973文字のMarkdownになり、実際の見出しで始まります。
• MarkItDownはドキュメント全体を構造化されたMarkdownに変換しますが、ボイラープレートが削除されたメイン記事だけが必要な場合はtrafilaturaを使用してください。
• Scrapelessの無料プランから始めて、最初のページを変換してください。

言語モデルは生のHTMLよりMarkdownをよく読み取ります。Markdownは、モデルが必要とする構造（見出し、リスト、リンク）を保持し、HTMLページを埋めるタグのスープ、スクリプトブロック、インラインスタイルは含まれていません。MarkItDownは、MicrosoftのドキュメントからMarkdownへの変換ツールで、この変換を行い、HTML、PDF、Officeドキュメントなどを1つのインターフェースで処理します。ページを取得することは行わないため、スクレイピングワークフローの半分は別途供給する必要があります。

このガイドでは、この二つを組み合わせます。Scrapeless Universal Scraping APIがページを取得し、MarkItDownが返されたHTMLをMarkdownに変換します。以下の数字はすべて、公開ページに対する実際の実行からのものです。

MarkItDownの機能

MarkItDownはドキュメントを受け取り、Markdownを返します。その存在理由はLLMの入力にあります：構造をトークン効率の良い形で保持するテキストを生成し、出力するMarkdownは一般的に実装されているCommonMark仕様に従います。MarkItDownリポジトリでは、受け入れる入力フォーマットがリストされています。これにはHTML、PDF、Word、PowerPoint、画像が含まれます。

MarkItDownはスクレイパーではありません。ブラウザもなく、アクセスチャレンジを回避する手段もないため、渡されたバイトを変換するだけです。ライブで時には保護されたページからこれらのバイトを取得するのは別の作業です。

インストール

MarkItDownは単一のpipインストールで行えます。

pip install markitdown

シェルでScrapelessキーを設定します。実行時には実際のキーを使用し、プレースホルダーはソースコードから除外してください。

export SCRAPELESS_API_KEY="sk_your_key_here"

スクレイピングしたHTMLをMarkdownに変換する

スクレイピングはHTML文字列を返し、ファイルではないため、適切なエントリーポイントはconvert_streamです。HTMLをBytesIOでラップし、MarkItDownがHTMLとして解析できるようにfile_extension=".html"を渡します。変換されたMarkdownは結果のtext_contentにあります。

import io
import json
import os
import urllib.request

from markitdown import MarkItDown

API_URL = "https://api.scrapeless.com/api/v2/unlocker/request"
TARGET = "https://quotes.toscrape.com/"


def fetch_html(url: str) -> str:
    payload = json.dumps(
        {"actor": "unlocker.webunlocker", "input": {"url": url, "js_render": False, "headless": False}}
    ).encode()
    request = urllib.request.Request(
        API_URL,
        data=payload,
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"], "Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=90) as response:
        return json.loads(response.read())["data"]


html = fetch_html(TARGET)
result = MarkItDown().convert_stream(io.BytesIO(html.encode("utf-8")), file_extension=".html")
markdown = result.text_content

print(f"生のHTML文字数: {len(html)}")
print(f"Markdown文字数: {len(markdown)}")
print(f"見出しで始まる: {markdown.lstrip().startswith('#')}")
print("--- Markdownの最初の行 ---")
for line in [line for line in markdown.splitlines() if line.strip()][:4]:
    print(line)

この実行結果ではサイズが報告され、Markdownの最初の部分が印刷されます。

生のHTML文字数: 11021
Markdown文字数: 2973
見出しで始まる: True
--- Markdownの最初の行 ---
# [Quotes to Scrape](/)
[Login](/login)
「私たちが創造した世界は、私たちの思考のプロセスです。それを変えることは、私たちの思考を変えない限りできません。」
アルバート・アインシュタイン

出力は実際のMarkdown見出しとリンクで始まり、ページの最初の引用が続きます。モデルが使用できる構造は変換を経て残り、11,021文字のHTMLは2,973文字のMarkdownに縮小されます。

なぜLLMにMarkdownなのか

Markdownは、ほとんどの言語モデルが読み取るために訓練されたフォーマットであるため、見出しはセクションになり、リンクは可読性を保ち、リストはリストのまま、元のHTMLよりもはるかに少ないトークンで表現されます。生のHTMLを渡すと、モデルが見る必要のあるタグやインラインスタイルにトークンを使うことになり、コンテンツを整理する助けとなる構造が埋もれてしまいます。最初にMarkdownに変換することは、すべての下流の呼び出しに対してリターンがある安価なステップです。

MarkItDownが止まるところ

MarkItDownは変換しますが、ブロックを超えて取得することはないため、このガイドはそれをリトリーバルツールと組み合わせています。MarkItDownにプレーンなクライアントで取得した保護されたページのHTMLを渡すと、忠実にチャレンジページをMarkdownに変換します。Scrapelessは実際のレンダリングされたHTMLを返し、MarkItDownがそれを変換します。ターゲットがJavaScriptでコンテンツを構築する場合、リクエストでjs_renderをTrueに設定すると、HTMLはすでにコンテンツを含みます; マークアップがサーバーでレンダリングされている場合は、ここでのようにFalseのままにします。

MarkItDownとtrafilaturaは異なる問題を解決します。MarkItDownはドキュメント全体を構造化されたMarkdownに変換し、ページの形を維持します。Trafilaturaはメインアーティクルを孤立させ、ボイラープレートを削除します。ページをMarkdownとして欲しい場合はMarkItDownを使用し、アーティクルボディだけを欲しい場合はtrafilaturaで抽出します。

サイト全体でこれを実行する前に、そのrobots.txtと利用規約を読みます。ロボット排除プロトコルは、サイトが自動クライアントに避けるように要求するパスを示しており、これを尊重することで、変換パイプラインを持続可能に保つことができます。より広いパターンについては、AIコンテンツパイプラインに関するガイドが、こうした変換ステップがどこに適合するかを示しています。

自分自身のページを変換する準備はできましたか？ 無料のScrapelessアカウントを作成し、ターゲットURLを変更してください。

結論

モデルにHTMLではなくMarkdownを渡すことは小さな変更ですが、実際の利点があります。必要なツールは2つあり、Scrapelessでページを取得し、MarkItDownで変換します。一度のconvert_stream呼び出しで、11,021文字のHTMLを2,973文字の構造化されたMarkdownに変換し、埋め込みステップやプロンプトに備えます。上記のスクリプトから始め、自分のURLに向けて、それをモデルにMarkdownとして渡してください。

Scrapelessの無料プランから始めることで、自分のページを取得し、定期的なジョブをサイズアップするときはScrapelessの価格を確認してください。

FAQ

Q: MarkItDownは自分でウェブページを取得しますか？

いいえ。MarkItDownは、与えられたドキュメントを変換するだけで、ブラウザやアンブロッキング機能は持っていません。そのため、保護されたページではコンテンツではなくチャレンジページを変換します。それをScrapelessのようなリトリーバルツールと組み合わせて、レンダリングされたHTMLを返し、それを変換します。

Q: スクレイピングしたHTMLをファイルを保存せずにMarkItDownに渡すにはどうすればよいですか？

convert_streamを使用し、HTMLをio.BytesIOでラップし、file_extension=".html"を指定してください。これにより、MarkItDownはメモリ内のバイトをHTMLとして解析します。スクレイピングしたページをディスクに書き込む必要がなく、そのMarkdownは結果のtext_contentにあります。

Q: MarkItDownはどのフォーマットを変換できますか？

MarkItDownはHTML、PDF、Word、PowerPoint、Excel、画像、その他いくつかのフォーマットを受け入れ、すべてを同じインターフェースを通じてMarkdownに変換します。ウェブスクレイピングにおいて関連する入力はHTMLですが、パイプラインがそれらを収集する場合は、スクレイピングされたPDFやスプレッドシートも同じコンバータが処理します。

Q: MarkItDownを使用すべきですか、それともtrafilaturaですか？

ドキュメント全体を構造化されたMarkdownに変換したい場合はMarkItDownを使用し、メインアーティクルとナビゲーションやフッターを削除したい場合はtrafilaturaを使用してください。異なる問題を解決します：1つはフォーマットコンバータであり、もう1つはメインコンテンツ抽出器です。

Q: モデルを呼び出す前にMarkdownに変換する理由は何ですか？

Markdownは、見出し、リスト、リンクをコンパクトな形式で保持しており、言語モデルが読み取りやすくなります。一方、生のHTMLはタグやスタイルにトークンを使うため、モデルが無視する必要があります。最初に変換することで、トークンコストを削減し、モデルが扱いやすいクリーンな構造を提供します。