unclecode/crawl4ai

⭐ 49,290 🍴 4,768 Python📄 Apache License 2.0 GitHubで見る →

主な特徴

  • **LLM最適化**: RAGや微調整アプリケーション向けのスマートで簡潔なMarkdown生成
  • **超高速パフォーマンス**: 競合他社と比較して6倍の速度でリアルタイム処理
  • **柔軟なブラウザ制御**: セッション管理、プロキシ、カスタムフック機能
  • **ヒューリスティックインテリジェンス**: 高価なモデルへの依存を減らす高度なアルゴリズム
  • **完全オープンソース**: APIキー不要、Dockerとクラウド統合対応
  • **アダプティブクローリング**: ウェブサイトのパターンを学習する革新的な機能（v0.7.0）
  • **Virtual Scroll対応**: 無限スクロールページの完全サポート
  • **リンクプレビュー**: 3層スコアリングによるインテリジェントなリンク分析
  • **非同期URL Seeder**: 大規模なURL発見のための機能
  • **20種類以上の抽出戦略**: CSS、XPath、LLM、正規表現ベースの抽出

リポジトリ解析: unclecode/crawl4ai

基本情報

  • リポジトリ名: unclecode/crawl4ai
  • 主要言語: Python
  • スター数: 49,290
  • フォーク数: 4,768
  • 最終更新: 2025年（活発に開発中）
  • ライセンス: Apache License 2.0
  • トピックス: web-scraping, llm, ai, crawling, markdown, data-extraction, playwright, async, python

概要

一言で言うと

LLMとAIアプリケーション向けに最適化された、高速で柔軟性の高いオープンソースウェブクローラー・スクレイパーで、きれいなMarkdownを生成し、6倍の速度で動作する。

詳細説明

Crawl4AIは、GitHubで#1トレンドとなった人気のオープンソースプロジェクトで、LLM（大規模言語モデル）、AIエージェント、データパイプライン向けに特別に設計された高速ウェブクローリングツールです。従来のウェブスクレイピングツールとは異なり、AIアプリケーションに適したクリーンで構造化されたMarkdownを生成することに重点を置いています。

開発者が2023年に$16のSaaSツールに不満を持ったことがきっかけで開発され、完全にオープンソースでAPIキー不要、セルフホスト可能な代替ソリューションとして誕生しました。プロジェクトのビジョンは「データの民主化」で、個人がデータにアクセスし、自分のAIモデルをトレーニングできるようにすることを目指しています。

主な特徴

  • LLM最適化: RAGや微調整アプリケーション向けのスマートで簡潔なMarkdown生成
  • 超高速パフォーマンス: 競合他社と比較して6倍の速度でリアルタイム処理
  • 柔軟なブラウザ制御: セッション管理、プロキシ、カスタムフック機能
  • ヒューリスティックインテリジェンス: 高価なモデルへの依存を減らす高度なアルゴリズム
  • 完全オープンソース: APIキー不要、Dockerとクラウド統合対応
  • アダプティブクローリング: ウェブサイトのパターンを学習する革新的な機能（v0.7.0）
  • Virtual Scroll対応: 無限スクロールページの完全サポート
  • リンクプレビュー: 3層スコアリングによるインテリジェントなリンク分析
  • 非同期URL Seeder: 大規模なURL発見のための機能
  • 20種類以上の抽出戦略: CSS、XPath、LLM、正規表現ベースの抽出

使用方法

インストール

前提条件

  • Python: >= 3.9
  • OS: Windows、Linux、macOS対応
  • 追加要件: Playwrightブラウザ（自動インストール）

インストール手順

# 方法1: pipインストール（推奨）
pip install -U crawl4ai

# プレリリース版を使用する場合
pip install crawl4ai --pre

# インストール後のセットアップ
crawl4ai-setup  # ブラウザの自動セットアップ

# インストール確認
crawl4ai-doctor

# 方法2: ソースからインストール（開発者向け）
git clone https://github.com/unclecode/crawl4ai.git
cd crawl4ai
pip install -e .  # 基本インストール

# オプション機能付きインストール
pip install -e ".[torch]"        # PyTorch機能付き
pip install -e ".[transformer]"  # Transformer機能付き
pip install -e ".[all]"          # 全機能インストール

基本的な使い方

Hello World相当の例

import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(
            url="https://www.nbcnews.com/business"
        )
        print(result.markdown[:500])  # 最初の500文字を表示

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

実践的な使用例

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig
from crawl4ai import DefaultMarkdownGenerator, PruningContentFilter

async def clean_content_extraction():
    # クリーンなコンテンツ抽出の設定
    crawler_config = CrawlerRunConfig(
        excluded_tags=["nav", "footer", "aside"],  # 不要なタグを除外
        remove_overlay_elements=True,
        markdown_generator=DefaultMarkdownGenerator(
            content_filter=PruningContentFilter(
                threshold=0.48, 
                threshold_type="fixed"
            )
        )
    )
    
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(
            url="https://en.wikipedia.org/wiki/Apple",
            config=crawler_config
        )
        print(f"フルMarkdown長: {len(result.markdown.raw_markdown)}")
        print(f"フィットMarkdown長: {len(result.markdown.fit_markdown)}")

asyncio.run(clean_content_extraction())

高度な使い方

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig
from crawl4ai import JsonCssExtractionStrategy, LLMExtractionStrategy
import json

async def advanced_extraction():
    # 構造化データ抽出（LLM不要）
    schema = {
        "name": "Product Listing",
        "baseSelector": ".product-item",
        "fields": [
            {"name": "title", "selector": ".product-title", "type": "text"},
            {"name": "price", "selector": ".price", "type": "text"},
            {"name": "image", "selector": "img", "type": "attribute", "attribute": "src"}
        ]
    }
    
    browser_config = BrowserConfig(
        headless=True,
        java_script_enabled=True
    )
    
    crawler_config = CrawlerRunConfig(
        extraction_strategy=JsonCssExtractionStrategy(schema),
        # JavaScriptコード実行
        js_code="""document.querySelectorAll('.load-more').forEach(btn => btn.click());""",
        wait_for="() => document.querySelectorAll('.product-item').length > 20"
    )
    
    async with AsyncWebCrawler(config=browser_config) as crawler:
        result = await crawler.arun(
            url="https://example-shop.com/products",
            config=crawler_config
        )
        
        products = json.loads(result.extracted_content)
        print(f"抽出した商品数: {len(products)}")
        
        # 複数URLの並列クローリング
        urls = ["https://site1.com", "https://site2.com", "https://site3.com"]
        results = await crawler.arun_many(urls, config=crawler_config)
        
        for result in results:
            if result.success:
                print(f"{result.url}: {len(result.markdown)} 文字")

asyncio.run(advanced_extraction())

ドキュメント・リソース

公式ドキュメント

  • README.md: プロジェクトの概要、クイックスタート、基本的な使用例
  • docs.crawl4ai.com: 包括的なドキュメントサイト（v2リニューアル済み）
  • CHANGELOG.md: 詳細なバージョン履歴と新機能の説明
  • ROADMAP.md: 将来の開発計画（Question-Based Crawler、Knowledge-Optimal Crawlerなど）

サンプル・デモ

  • quickstart.py: 基本的な使用例のコレクション
  • adaptive_crawling/: アダプティブクローリングの高度な例
  • amazon_product_extraction_*.py: EC商品情報抽出の実例
  • crypto_analysis_example.py: 暗号通貨データ分析の例
  • url_seeder_demo.py: URL発見機能のデモ
  • docker_example.py: Docker API使用例

チュートリアル・ガイド

  • Google Colab対応のインタラクティブノートブック
  • CLI使用ガイド（crwlコマンド）
  • Docker展開ガイド（ブラウザプール、APIゲートウェイ設定）
  • MCP統合ガイド（Claude Codeとの連携）
  • ベストプラクティスとパフォーマンス最適化ガイド

技術的詳細

アーキテクチャ

全体構造

Crawl4AIは非同期アーキテクチャを採用し、高パフォーマンスなウェブクローリングを実現しています。コアはAsyncWebCrawlerクラスで、Playwrightを使用したブラウザ制御、プラグ可能な抽出戦略、キャッシング、並列処理などを統合しています。

ディレクトリ構成

crawl4ai/
├── crawl4ai/              # メインパッケージ
│   ├── async_webcrawler.py    # コアクローラー実装
│   ├── async_configs.py       # 設定クラス定義
│   ├── extraction_strategy.py # 抽出戦略の実装
│   ├── markdown_generation_strategy.py # Markdown生成
│   ├── content_filter_strategy.py      # コンテンツフィルタリング
│   ├── chunking_strategy.py   # チャンキング戦略
│   ├── deep_crawling/         # ディープクローリング実装
│   ├── adaptive_crawler.py    # アダプティブクローリング
│   └── browser_manager.py     # ブラウザ管理
├── docs/                  # ドキュメントとサンプル
│   ├── examples/          # 使用例コレクション
│   └── assets/            # ドキュメント用アセット
├── deploy/                # デプロイメント設定
│   └── docker/            # Docker関連ファイル
└── tests/                 # テストスイート
    ├── async/             # 非同期テスト
    └── browser/           # ブラウザテスト

主要コンポーネント

  • AsyncWebCrawler: メインクローラークラス

    • 場所: crawl4ai/async_webcrawler.py
    • 依存: BrowserManager、ExtractionStrategy、CacheContext
    • インターフェース: arun(), arun_many(), arun_batch()

  • ExtractionStrategy: 抽出戦略の基底クラス

    • 場所: crawl4ai/extraction_strategy.py
    • 実装: LLMExtractionStrategy、JsonCssExtractionStrategy、RegexExtractionStrategy
    • インターフェース: extract(), run()

  • MarkdownGenerationStrategy: Markdown生成戦略

    • 場所: crawl4ai/markdown_generation_strategy.py
    • 依存: ContentFilterStrategy
    • インターフェース: generate_markdown(), convert_to_markdown()

  • AdaptiveCrawler: アダプティブクローリング実装

    • 場所: crawl4ai/adaptive_crawler.py
    • 特徴: ウェブサイトパターンの学習、効率的な抽出
    • インターフェース: learn(), extract(), update_knowledge_base()

技術スタック

コア技術

  • 言語: Python >= 3.9（非同期プログラミング、型ヒント活用）
  • ブラウザ自動化: Playwright（Chromium、Firefox、WebKit対応）
  • 非同期処理: asyncio、aiohttp、aiofiles
  • 主要ライブラリ:
    • playwright (>=1.49.0): ブラウザ自動化
    • litellm (>=1.53.1): LLM統合（OpenAI、Anthropic等対応）
    • beautifulsoup4 (~4.12): HTML解析
    • lxml (~5.3): 高速XML/HTML処理
    • rank-bm25 (~0.2): BM25アルゴリズムによる関連性スコアリング
    • sentence-transformers (>=2.2.0): セマンティック検索
    • pydantic (>=2.10): データバリデーション

開発・運用ツール

  • ビルドツール: setuptools、wheel（pyproject.toml設定）
  • テスト: pytest、包括的なテストスイート（async、browser、docker）
  • CI/CD: GitHub Actions（自動テスト、リリース）
  • デプロイ:
    • Docker（マルチアーキテクチャ対応: AMD64/ARM64）
    • FastAPI（REST API サーバー）
    • JWT認証（APIセキュリティ）

設計パターン・手法

  • Strategy Pattern: 抽出戦略、フィルタリング戦略、Markdown生成戦略で広範に使用
  • Decorator Pattern: DeepCrawlDecoratorによる機能拡張
  • Factory Pattern: BrowserManagerによるブラウザインスタンス生成
  • Context Manager: AsyncWebCrawlerのasync with構文サポート
  • Chain of Responsibility: FilterChainによるURL/コンテンツフィルタリング

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

  1. 初期化: AsyncWebCrawlerインスタンス作成、ブラウザプール初期化
  2. URL処理: URLの正規化、ロボット.txtチェック、キャッシュ確認
  3. ページ取得: Playwrightによるページロード、JavaScript実行
  4. コンテンツ抽出:
    • HTML取得と前処理
    • 指定された抽出戦略の適用
    • メディア（画像、動画）の抽出
  5. Markdown生成:
    • HTMLからMarkdownへの変換
    • コンテンツフィルタリング（Pruning/BM25）
    • リンクの番号付け参照リスト作成
  6. 後処理:
    • メタデータ抽出
    • キャッシュ保存
    • 結果オブジェクト（CrawlResult）の生成

API・インターフェース

公開API

AsyncWebCrawler.arun()

  • 目的: 単一URLの非同期クローリング
  • 使用例:
result = await crawler.arun(
    url="https://example.com",
    config=CrawlerRunConfig(
        cache_mode=CacheMode.BYPASS,
        word_count_threshold=10,
        excluded_tags=["nav", "footer"],
        extraction_strategy=JsonCssExtractionStrategy(schema)
    )
)

AsyncWebCrawler.arun_many()

  • 目的: 複数URLの並列クローリング
  • 使用例:
results = await crawler.arun_many(
    urls=["url1", "url2", "url3"],
    config=crawler_config,
    max_concurrent=5
)

設定・カスタマイズ

設定ファイル

# BrowserConfig - ブラウザ設定
browser_config = BrowserConfig(
    headless=True,
    viewport={"width": 1920, "height": 1080},
    user_agent="custom-agent",
    proxy_config=ProxyConfig(server="http://proxy:8080")
)

# CrawlerRunConfig - クローリング実行設定
crawler_config = CrawlerRunConfig(
    cache_mode=CacheMode.ENABLED,
    js_code="// カスタムJavaScript",
    wait_for="() => document.readyState === 'complete'",
    extraction_strategy=CustomExtractionStrategy(),
    markdown_generator=DefaultMarkdownGenerator()
)

拡張・プラグイン開発

カスタム抽出戦略の作成:

from crawl4ai import ExtractionStrategy

class CustomExtractionStrategy(ExtractionStrategy):
    def extract(self, html: str, url: str, **kwargs) -> str:
        # カスタム抽出ロジック
        return extracted_data

カスタムフィルターの作成:

from crawl4ai.content_filter_strategy import ContentFilterStrategy

class CustomFilter(ContentFilterStrategy):
    def filter_content(self, sections, **kwargs):
        # カスタムフィルタリングロジック
        return filtered_sections

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

パフォーマンス特性

  • ベンチマーク結果: 競合他社比6倍高速（公式ベンチマーク）
  • 最適化手法:
    • 非同期I/O処理による並列化
    • ブラウザプールとページ事前ウォーミング
    • インテリジェントキャッシング（TTL対応）
    • BM25による効率的なコンテンツフィルタリング
    • メモリアダプティブディスパッチャー

スケーラビリティ

  • 並列処理: arun_many()で数百URLの同時処理可能
  • ブラウザプール: 複数ブラウザインスタンスの効率的管理
  • レート制限: 組み込みのレート制限とバックプレッシャー制御
  • 分散処理: Docker APIによる水平スケーリング対応
  • メモリ管理: ストレステスト済み、大規模クローリング対応

制限事項

  • メモリ使用: ブラウザインスタンスごとに約100-200MB
  • 同時接続数: システムリソースに依存（推奨: 10-20並列）
  • JavaScript実行: 複雑なSPAでは追加の待機時間が必要
  • プロキシ制限: 一部のプロキシでPlaywrightの制限あり

評価・所感

技術的評価

強み

  • 圧倒的な処理速度: 非同期アーキテクチャによる高速処理
  • AI/LLM最適化: きれいなMarkdown生成、構造化データ抽出
  • 高い柔軟性: プラグ可能なアーキテクチャ、豊富な設定オプション
  • アクティブな開発: 頻繁なアップデート、コミュニティサポート
  • 完全オープンソース: 透明性、カスタマイズ性、ベンダーロックインなし

改善の余地

  • 学習曲線: 高度な機能を使いこなすには時間が必要
  • ドキュメント: 日本語ドキュメントが不足
  • エラーハンドリング: 一部のエッジケースでより詳細なエラー情報が必要

向いている用途

  • AIデータパイプライン構築: RAG、ファインチューニング用データ収集
  • 大規模ウェブスクレイピング: ニュース、EC、ソーシャルメディア
  • リアルタイムデータ収集: 価格監視、在庫チェック
  • 研究・分析: ウェブデータの体系的収集
  • コンテンツ監視: ウェブサイトの変更検知

向いていない用途

  • シンプルなスクレイピング: BeautifulSoupで十分な簡単なタスク
  • 非ウェブデータ: APIやデータベースからの直接取得
  • リソース制約環境: メモリやCPUが限られた環境

総評

Crawl4AIは、AI時代のウェブクローリングニーズに完璧に応えるツールです。特にLLMアプリケーション開発者にとって、きれいなMarkdown生成と高速処理は大きな価値があります。オープンソースで活発に開発されており、将来性も高く評価できます。初心者から上級者まで幅広く使える設計で、特にAI/MLプロジェクトでのデータ収集において第一選択となるツールです。