Crawl4AIチュートリアル：初心者向けガイド

AI時代において、ウェブデータへの効率的なアクセスと処理は非常に重要です。Crawl4AIは、大規模言語モデル（LLM）、AIエージェント、最新のデータパイプラインを扱う開発者向けに細心の注意を払って設計された、強力なオープンソースのウェブクローラー兼スクレーパーとして登場しました。このチュートリアルでは、Crawl4AIのインストールから高度なクロール技術まで、すべてを網羅して詳しく解説します

💡

美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか？

最大限の生産性で開発チームが連携するための、統合されたオールインワンプラットフォームをお探しですか？

Apidogはあなたのすべての要求を満たし、Postmanをはるかに手頃な価格で置き換えます！

button

プロジェクトにCrawl4AIを選ぶ理由

Crawl4AIは単なる標準的なウェブスクレーパーではありません。LLMフレンドリーになるようにゼロから設計されています。これは、以下の点に重点を置いていることを意味します。

クリーンなMarkdown生成: 定型文やノイズを除去することで、Retrieval-Augmented Generation (RAG)システムやモデルのファインチューニングに最適化された、構造化された簡潔なMarkdownを生成します。
構造化データ抽出: 従来のメソッド（CSSセレクター、XPath）を使用するか、より複雑で意味的な抽出タスクにLLMを活用して、特定のデータポイントをJSONのような形式で抽出できるようにします。
高いパフォーマンス: Pythonのasyncioライブラリと強力なPlaywrightブラウザ自動化フレームワークを利用して、高速な非同期クロールを実現します。
高度なブラウザ制御: JavaScript実行、動的コンテンツの処理、セッション管理（Cookie、ローカルストレージ）、プロキシの使用、異なるユーザー環境（ユーザーエージェント、地理位置情報）のシミュレーションなど、ブラウザインスタンスをきめ細かく制御できます。
オープンソースと柔軟性: 外部APIキーや有料サービスに依存しない、完全にオープンソース（帰属表示付きApache 2.0）です。Dockerまたは直接pipインストールによるデプロイの柔軟性を提供します。

Crawl4AIはデータアクセスを民主化し、開発者がウェブデータを迅速かつ効率的に収集・整形できるようにすることを目指しています。

Crawl4AIのインストールとセットアップ

Crawl4AIの実行は簡単で、pipとDockerの両方のオプションがあります。

方法1: Pipインストール (ライブラリ利用に推奨)

パッケージのインストール: ターミナルを開いて以下を実行します。

# 最新の安定版をインストール
pip install -U crawl4ai

# または、最新のプレリリース版をインストール (最先端の機能向け)
# pip install crawl4ai --pre

インストール後のセットアップ実行: この重要なステップは、必要なPlaywrightブラウザバイナリ（デフォルトはChromium）をインストールします。

crawl4ai-setup

確認: 診断ツールを使用してセットアップを確認します。

crawl4ai-doctor

トラブルシューティング: crawl4ai-setupで問題が発生した場合は、ブラウザの依存関係を手動でインストールします。

python -m playwright install --with-deps chromium

方法2: Dockerデプロイ (APIサービスに最適)

イメージのプル: 公式Dockerイメージを取得します（最新タグはGitHubで確認してください）。

# 例のタグです。必要に応じて置き換えてください。
docker pull unclecode/crawl4ai:latest

コンテナの実行: Crawl4AIサービスを開始し、APIを公開します（デフォルトポートは11235）。

docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g unclecode/crawl4ai:latest

これにより、Crawl4AIがFastAPIバックエンドで実行され、HTTP経由でのクロールリクエストを受け付ける準備ができます。対話型のAPIプレイグラウンドにはhttp://localhost:11235/playgroundでアクセスできます。

Crawl4AIで最初のクロールを実行する方法

Crawl4AIは、AsyncWebCrawlerを使用することで基本的なクロールを驚くほど簡単にします。

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode

async def run_basic_crawl():
    # --- 基本的な例 ---
    print("--- 基本的なクロールを実行中 ---")
    # ブラウザの自動起動とシャットダウンのために 'async with' を使用
    async with AsyncWebCrawler() as crawler:
        # arun() メソッドは単一の URL のクロールを実行します
        # CrawlResult オブジェクトを返します
        result = await crawler.arun(url="https://example.com")

        if result and result.success:
            # 生成された Markdown ('fit_markdown' が一般的) にアクセス
            print("クロール成功！")
            # result.markdown は生の Markdown とフィルタリングされた Markdown の両方を提供します
            print(f"フィット Markdown (最初の 300 文字): {result.markdown.fit_markdown[:300]}...")
        else:
            print(f"クロール失敗: {result.error_message}")

    # --- 基本的な設定を使った例 ---
    print("\n--- 基本的な設定を使ったクロールを実行中 ---")
    # ブラウザの動作を設定 (例: デバッグのためにヘッドフルで実行)
    browser_conf = BrowserConfig(headless=True) # ブラウザウィンドウを表示するには False に設定

    # 実行固有の設定を設定 (例: キャッシュをバイパス)
    # CacheMode.ENABLED (デフォルト), CacheMode.DISABLED, CacheMode.BYPASS
    run_conf = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)

    async with AsyncWebCrawler(config=browser_conf) as crawler:
        result = await crawler.arun(
            url="https://crawl4ai.com/", # 公式サイトをクロール
            config=run_conf # 実行設定を適用
        )
        if result and result.success:
            print("クロール成功！")
            print(f"フィット Markdown 単語数: {result.markdown.word_count}")
            print(f"クロールされた URL: {result.url}")
        else:
            print(f"クロール失敗: {result.error_message}")

if __name__ == "__main__":
    asyncio.run(run_basic_crawl())

Crawl4AIの主要コンセプト:

AsyncWebCrawler: クロールを開始するためのメインクラス。async withを使用することで、ブラウザが適切に管理されます。
arun(url, config=None): 単一のURLをクロールするためのコア非同期メソッド。
BrowserConfig: ブラウザレベルの設定（ヘッドレス、ユーザーエージェント、プロキシ）を制御します。AsyncWebCrawlerの初期化時に渡されます。
CrawlerRunConfig: 特定のクロールジョブの設定（キャッシュ、抽出戦略、タイムアウト、JavaScript実行）を制御します。arunメソッドに渡されます。
CacheMode: Crawl4AIがキャッシュとどのように連携するかを決定します（ENABLED、DISABLED、BYPASS）。BYPASSは開発中に最新のデータを確保するのに役立ちます。

Crawl4AIの`CrawlResult`オブジェクトの仕組み

成功したすべてのarunまたはarun_many呼び出しは、1つ以上のCrawlResultオブジェクトを返します。これらはクロール中に収集されたすべての情報をカプセル化します。

CrawlResultオブジェクトには、以下を含むさまざまな属性が含まれています。

url: クロールされた最終的なURL（リダイレクト後）。
success: クロールが成功したかどうかを示すブール値。
error_message: successがFalseの場合、エラーの詳細が含まれます。
status_code: レスポンスのHTTPステータスコード。
markdown: Markdownバージョンを含むオブジェクト（raw_markdown、fit_markdown、word_count）。
html: ページの生のHTMLコンテンツ。
text: ページから抽出されたプレーンテキストコンテンツ。
extracted_content: 設定された抽出戦略からの結果（例：JSON文字列）を格納します。
links: ページで見つかったリンクのリスト（internal、external）。
media: 抽出されたメディア（画像、テーブルなど）に関する情報。
metadata: ページのメタデータ（タイトル、説明など）。
cookies: クロール後のブラウザのCookie。
screenshot_path: スクリーンショットが撮られた場合のパス。
network_log_path: ネットワークHARファイルがキャプチャされた場合のパス。
console_log_path: コンソールログファイルがキャプチャされた場合のパス。

このオブジェクトを検査することは、Crawl4AIのクロールから必要な特定のデータにアクセスするための鍵です。

Crawl4AIでAI対応のMarkdownを生成する方法

Crawl4AIの核となる強みは、LLMに適したクリーンなMarkdownを生成する能力です。

result.markdown属性は以下を保持します。

result.markdown.raw_markdown: ページの主要コンテンツ領域をMarkdownに直接、フィルタリングせずに変換したもの。
result.markdown.fit_markdown: Markdownのフィルタリングされたバージョン。これはCrawl4AIが一般的なウェブの雑多なもの（メニュー、広告、フッター、サイドバー）を除去するためにヒューリスティックフィルター（PruningContentFilterやBM25ContentFilterなど）を適用するため、LLMにとって最も役立つことが多いです。
result.markdown.word_count: fit_markdownの単語数。

Crawl4AIではフィルタリングプロセスをカスタマイズできます。

import asyncio
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, CacheMode
# カスタマイズのための特定の戦略をインポート
from crawl4ai.content_filter_strategy import PruningContentFilter
from crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerator

async def run_custom_markdown_crawl():
    print("\n--- カスタム Markdown フィルタリングを使ったクロールを実行中 ---")

    # 特定のコンテンツフィルターを使った Markdown ジェネレーターを設定
    # PruningContentFilter は単語数の閾値に基づいて要素を削除します
    markdown_generator_with_filter = DefaultMarkdownGenerator(
        content_filter=PruningContentFilter(
            threshold=0.48, # 厳密さのために閾値 (0 から 1) を調整
            threshold_type="fixed" # 'fixed' または 'relative'
            )
    )

    # このジェネレーターを実行設定に適用
    run_conf = CrawlerRunConfig(
        cache_mode=CacheMode.BYPASS,
        markdown_generator=markdown_generator_with_filter
    )

    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(
            url="https://www.nbcnews.com/business", # ニュースサイトは雑多なものが多い
            config=run_conf
        )
        if result and result.success:
            print("クロール成功！")
            print(f"生の Markdown の長さ: {len(result.markdown.raw_markdown)}")
            print(f"フィット Markdown の長さ: {len(result.markdown.fit_markdown)}") # 通常は短い
            # raw_markdown と fit_markdown を比較してフィルターの効果を確認
        else:
            print(f"クロール失敗: {result.error_message}")

if __name__ == "__main__":
    asyncio.run(run_custom_markdown_crawl())

markdown_generator内のcontent_filterを調整することで、Crawl4AIがfit_markdownを生成する前にコンテンツをどれだけ積極的にクリーンアップするかを制御できます。

Crawl4AIのディープクロールを使用する方法

Crawl4AIは単一ページに限定されません。リンクをたどってウェブサイト内をナビゲートするディープクロールを実行できます。

adeep_crawlメソッド（またはcrwl CLIの--deep-crawlフラグ）を使用します。

import asyncio
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, CacheMode

async def run_deep_crawl():
    print("\n--- ディープクロールを実行中 ---")
    # 設定は通常通りグローバルまたは実行ごとに適用できます
    run_conf = CrawlerRunConfig(cache_mode=CacheMode.ENABLED)

    async with AsyncWebCrawler() as crawler:
        # adeep_crawl は非同期ジェネレーターを返し、ページが完了するにつれて結果を生成します
        crawl_generator = await crawler.adeep_crawl(
            start_url="https://docs.crawl4ai.com/", # 開始地点
            strategy="bfs", # 'bfs' (幅優先), 'dfs' (深さ優先), 'bestfirst'
            max_depth=2,    # たどるリンクの深さを制限
            max_pages=10,   # クロールする合計ページ数を制限
            config=run_conf
        )

        # 結果が届くにつれて処理
        pages_crawled = 0
        async for result in crawl_generator:
            if result.success:
                print(f"[OK] クロール済み: {result.url} (深さ: {result.depth}, フィット Markdown の長さ: {len(result.markdown.fit_markdown)})")
                pages_crawled += 1
            else:
                print(f"[FAIL] URL: {result.url}, エラー: {result.error_message}")

        print(f"\nディープクロールが終了しました。成功した合計クロールページ数: {pages_crawled}")

if __name__ == "__main__":
    asyncio.run(run_deep_crawl())

Crawl4AIディープクロールパラメータ:

start_url: クロールを開始する最初のURL。
strategy: リンクの発見と優先順位付けの方法（bfs、dfs、bestfirst）。
max_depth: start_urlからの最大リンク距離。
max_pages: このジョブでクロールする最大合計ページ数。
include_patterns、exclude_patterns: 正規表現パターンを使用して、どのURLをたどるかをフィルタリングします。

Crawl4AIで動的コンテンツとインタラクションを処理する方法

最新のウェブサイトは、コンテンツの読み込みにJavaScriptに大きく依存しています。Crawl4AIは、Playwrightの機能を通じてこれを処理します。

CrawlerRunConfigを使用して、任意のJavaScriptを実行したり、特定の条件を待機したりできます。

import asyncio
import json
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode
from crawl4ai.extraction_strategy import JsonCssExtractionStrategy # 例として

async def crawl_dynamic_page():
    print("\n--- JS インタラクションを使った動的ページのクロール ---")

    # CSS 抽出のスキーマ例 (ターゲットサイトに合わせて適応)
    schema = { "items": { "selector": "div.product-item", "type": "list", "fields": { "title": "h2", "price": ".price" } } }
    css_extractor = JsonCssExtractionStrategy(schema)

    # ページで実行する JavaScript (例: 'Load More' ボタンをクリック)
    # 注意: セレクターはターゲットウェブサイトと一致する必要があります
    js_to_run = """
    (async () => {
        const loadMoreButton = document.querySelector('button#load-more');
        if (loadMoreButton) {
            console.log('Load more button をクリックしています...');
            loadMoreButton.click();
            // クリック後にコンテンツが読み込まれるのを少し待つ
            await new Promise(resolve => setTimeout(resolve, 2000));
            console.log('クリック後に待機しました。');
        } else {
            console.log('Load more button が見つかりませんでした。');
        }
    })();
    """

    run_conf = CrawlerRunConfig(
        cache_mode=CacheMode.BYPASS,
        js_code=[js_to_run], # 実行する JS スニペットのリスト
        wait_for_timeout=3000, # 初期ロード後 および JS 実行後 に 3 秒待機
        # wait_for_selector="div.newly-loaded-content", # または特定の要素を待機
        extraction_strategy=css_extractor, # JS 実行後にデータを抽出
        output_formats=['markdown', 'extracted_content']
    )

    # BrowserConfig で JS が有効になっていることを確認 (デフォルトで有効)
    browser_conf = BrowserConfig(headless=True, java_script_enabled=True)

    async with AsyncWebCrawler(config=browser_conf) as crawler:
        result = await crawler.arun(
            url="URL_OF_DYNAMIC_PAGE_HERE", # 実際の URL に置き換えてください
            config=run_conf
        )

        if result and result.success:
            print("動的ページのクロール成功！")
            print(f"フィット Markdown の長さ: {len(result.markdown.fit_markdown)}")
            if result.extracted_content:
                try:
                    extracted_data = json.loads(result.extracted_content)
                    print(f"抽出コンテンツプレビュー: {json.dumps(extracted_data, indent=2)[:500]}...")
                except json.JSONDecodeError:
                    print(f"抽出コンテンツ (非 JSON): {result.extracted_content[:500]}...")
        else:
            print(f"クロール失敗: {result.error_message}")


if __name__ == "__main__":
    # テストのために動的にコンテンツを読み込む実際の URL に置き換えてください
    # asyncio.run(crawl_dynamic_page())
    print("'URL_OF_DYNAMIC_PAGE_HERE' を置き換え、上記の行のコメントを解除して動的例を実行してください。")

CrawlerRunConfigの主要なCrawl4AIインタラクションパラメータ:

js_code: ページコンテキストで実行するJavaScript文字列のリスト。
wait_for_timeout: ページロード後およびJS実行後に待機するミリ秒数。
wait_for_selector: ページがロード/インタラクションが完了したと見なす前に待機するCSSセレクター。
page_interaction_hooks: より複雑なインタラクションのための高度なフック。

Crawl4AIの結論

Crawl4AIは、ウェブクロールとスクレイピングのための包括的でPython的、そしてAI中心のソリューションを提供します。クリーンなMarkdown生成、柔軟な構造化データ抽出（CSSおよびLLMベースの両方）、動的コンテンツの堅牢な処理、効率的な非同期操作に重点を置いているため、RAG、LLMファインチューニング、またはウェブからの構造化情報を必要とするあらゆるタスクに関わるプロジェクトにとって優れた選択肢となります。明確なAPI、設定オプション（BrowserConfig、CrawlerRunConfig）、詳細なCrawlResultオブジェクトを活用することで、開発者は洗練された効率的なデータ収集ワークフローを構築できます。

💡