crawl4ai

Crawl4AI

crawl4ai を基準に検証済みです。 VERSION。scripts/*.py と tests/*.py の PEP 723 のピン留めでは、このバージョン以上を指定しています。

概要

Crawl4AI はヘッドレスブラウザー（Playwright）と、Markdown を考慮したコンテンツパイプラインを組み合わせたものです。defuddle や curl ではコンテンツにアクセスできない場合に使用します。たとえば、JavaScript でレンダリングされるページ、ログインが必要なコンテンツ、無限スクロール、複数 URL の並列処理、再利用可能なスキーマベースの抽出などが該当します。

このスキルでは、基盤となるライブラリの 2 つのインターフェースを利用できます。

• CLI（crwl）— 手早くスクリプト化できるコマンド：CLI ガイド
• Python SDK — プログラムからの完全な制御：SDK ガイド

URL 引数を指定して呼び出す場合

ユーザーが URL を 1 つだけ指定し、追加の条件なしで /crawl4ai <url> を実行した場合は、JavaScript を多用するページの取得ケースとして扱い、次をデフォルトにします。

crwl <url> -c "wait_until=networkidle,page_timeout=60000" -o markdown

wait_until=networkidle は、読み込み後にネットワークが約 500 ミリ秒間静かになるまで待機します。JavaScript でレンダリングされるページで、ユーザーが特定の要素を指定していない場合に適したデフォルトです。（wait_for=css:body は避けてください。すべての HTML レスポンスで <body> は時刻 0 に存在するため、JavaScript がコンテンツをレンダリングする前に条件が満たされます。）その後、Markdown をエージェントのコンテキストに返します。ユーザーが特定の要素を指定した場合は、wait_for=css:<selector> に変更します。抽出、バッチ処理／複数 URL、ログイン／セッション、スクリーンショット／PDF、URL 検出を含むタスクでは、デフォルトを使わず、以下の該当セクションに進みます。それぞれ独自のパイプラインがあります。URL が明らかに静的なページ（ドキュメントページ、ブログ記事など）の場合は、以下の「このスキルを使用しない場合」に従って、ユーザーを /fetch-web に案内します。

このスキルを使用しない場合

• 静的 HTML ページ（ほとんどのドキュメントサイト、ブログ記事、ニュース記事、ツイート）— /fetch-web または defuddle を直接使用します。静的抽出のコールドスタートは約 0 ミリ秒ですが、crawl4ai ではブラウザーの起動に約 2 秒かかります。
• ローカルファイルの変換（.pdf、.docx、.pptx、.epub）— /markdown-convert を使用します。
• 1 つの URL をエージェントのコンテキストに読み込む場合（エージェントがこのページを読むだけでよい場合）— /fetch-web を使用し、defuddle に処理を振り分けます。
• UI を変更する操作（フォーム入力、複数ステップのクリック、ログインとナビゲーション）— 永続的なヘッドレス Chromium を使用する gstack の /browse が適しています。

行き詰まった場合

不明な crwl／SDK フラグ、スクレイピングの失敗、またはリファレンスでカバーされていない抽出時の特殊ケースについては、references/escalation.md を参照してください。参照先を探す順序（qmd の解決策 → 上流のドキュメント → GitHub のイシュー → ユーザーへの確認）と、具体例が記載されています。

---

クイックスタート

インストール

pip install crawl4ai
crawl4ai-setup

# Verify installation
crawl4ai-doctor

CLI（推奨）

# Basic crawling - returns markdown
crwl https://example.com

# Get markdown output
crwl https://example.com -o markdown

# JSON output with cache bypass
crwl https://example.com -o json -v --bypass-cache

# See more examples
crwl --example

Python SDK

import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun("https://example.com")
        print(result.markdown[:500])

asyncio.run(main())

SDK の設定の詳細：SDK ガイド - 設定。

---

基本概念

設定レイヤー

CLI と SDK は、どちらも同じ基盤設定を使用します。

概念	CLI	SDK
ブラウザー設定	-B browser.yml または -b "param=value"	BrowserConfig(...)
クロール設定	-C crawler.yml または -c "param=value"	CrawlerRunConfig(...)
抽出	-e extract.yml -s schema.json	extraction_strategy=...
コンテンツフィルター	-f filter.yml	markdown_generator=...

主なパラメーター

ブラウザー設定：

• headless：GUI の有無を指定します
• viewport_width/height：ブラウザーのサイズ
• user_agent：カスタムユーザーエージェント
• proxy_config：プロキシ設定

クローラー設定：

• page_timeout：ページ読み込みの最大時間（ミリ秒）
• wait_for：待機する CSS セレクターまたは JS 条件
• cache_mode：バイパス、有効、無効
• js_code：実行する JavaScript
• css_selector：特定の要素に対象を絞ります

すべてのパラメーター：CLI 設定 | SDK 設定

出力内容

各クロールで次の内容が返されます。

• markdown - 整形済みのクリーンな Markdown
• html - 生の HTML
• links - 検出された内部リンクと外部リンク
• media - 見つかった画像、動画、音声
• extracted_content - 構造化データ（抽出を設定した場合）

---

Markdown の生成（主なユースケース）

Crawl4AI は、クリーンで適切に整形された Markdown の生成に優れています。

CLI

crwl https://docs.example.com -o markdown                              # raw markdown
crwl https://docs.example.com -o markdown-fit                          # filtered (noise removed)
crwl https://docs.example.com -f templates/filter_bm25.yml -o markdown-fit   # BM25-relevance filter
crwl https://docs.example.com -f templates/filter_pruning.yml -o markdown-fit # quality-based filter

フィルターテンプレート：templates/filter_bm25.yml（クエリに対する関連度スコアを付与）、 templates/filter_pruning.yml（クエリ不要。品質の低いブロックを除去）。

Python SDK

from crawl4ai.content_filter_strategy import BM25ContentFilter
from crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerator

bm25_filter = BM25ContentFilter(user_query="machine learning", bm25_threshold=1.0)
md_generator = DefaultMarkdownGenerator(content_filter=bm25_filter)

config = CrawlerRunConfig(markdown_generator=md_generator)
result = await crawler.arun(url, config=config)

print(result.markdown.fit_markdown)  # Filtered
print(result.markdown.raw_markdown)  # Original

フィルターの選択と設定フィールドのリファレンスについては、コンテンツフィルターを参照してください。

---

データ抽出

1. スキーマベースの CSS 抽出（最も効率的）

抽出時に LLM は不要 です。高速で決定論的、コストもかかりません。スキーマの導出に一度だけ LLM のコストがかかりますが、その後は何度でも再利用できます。付属スクリプトでは、パイプラインを役割ごとに分割しています。

./scripts/generate_schema.py https://shop.example.com "products with name, price, image" shop_schema.json
./scripts/extract_with_schema.py https://shop.example.com shop_schema.json products.json

または、YAML 戦略テンプレートと保存済みスキーマを使って CLI から実行できます。

crwl https://shop.example.com -e templates/extract_css.yml -s shop_schema.json -o json

スキーマのひな形：templates/css_schema.json。戦略 YAML： templates/extract_css.yml。

2. LLM ベースの抽出

CSS スキーマでは対応しにくい、一度限りまたは不規則なコンテンツの場合：

./scripts/extract_with_llm.py https://news.example.com "Extract headlines, dates, summaries" news.json

または、戦略テンプレートを使って CLI から実行できます。

crwl https://news.example.com -e templates/extract_llm.yml -o json

戦略 YAML：templates/extract_llm.yml。URL ごとに LLM 呼び出しのコストがかかります。繰り返し抽出する場合は、上記のスキーマパイプラインをお勧めします。

抽出戦略のリファレンスについては、抽出戦略を参照してください。

---

高度なパターン

動的コンテンツ（JavaScript を多用するサイト）

crwl https://example.com -c "wait_for=css:.ajax-content,scan_full_page=true,page_timeout=60000"
crwl https://example.com -C templates/crawler.yml                          # all options in a YAML file

クローラー設定テンプレート：templates/crawler.yml。

複数 URL の処理

./scripts/batch_crawl.py urls.txt --max-concurrent 5 --out batch_markdown/
./scripts/batch_extract.py urls.txt shop_schema.json --max-concurrent 5 --out products.json

2 つのスクリプトは役割ごとに分かれています。batch_crawl.py は URL ごとに Markdown を返し、batch_extract.py は URL ごとにスキーマで抽出した JSON を返します。Python では arun_many() を使います。

urls = ["https://site1.com", "https://site2.com", "https://site3.com"]
results = await crawler.arun_many(urls, config=config)

バッチ処理のリファレンスについては、arun_many() のリファレンスを参照してください。

クロール前の URL 検出

URL リストが既知のリストではなく、サイトマップやドメインから得られる場合は、まず検出を行い、その結果を batch_crawl.py / batch_extract.py に渡します。全機能についてはURL 検出を、簡単な使用例については次を参照してください。

from crawl4ai import AsyncUrlSeeder, SeedingConfig
seeds = await AsyncUrlSeeder().urls("example.com", SeedingConfig(
    source="sitemap+cc", pattern="*/blog/*", query="machine learning", score_threshold=0.3, live_check=True,
))
urls = [s["url"] for s in seeds]

クエリに対する BM25 スコアでフィルタリングする場合は AsyncUrlSeeder が適しています。1 つのドメインを最大限網羅する場合は DomainMapper が適しています。

セッションと認証

ログインテンプレートを入力してから、後続のクロールでセッション ID を再利用します。

crwl https://site.com/login -C templates/login_crawler.yml
crwl https://site.com/protected -c "session_id=user_session"

ログインテンプレート：templates/login_crawler.yml（使用前にフィールド ID のセレクターとログイン後の待機条件を入力してください）。

セッション管理のリファレンスについては、高度な機能を参照してください。

検出回避とプロキシ

crwl https://example.com -B templates/browser.yml

ブラウザー設定テンプレート：templates/browser.yml（必要に応じて proxy_config と init_scripts のコメントを解除してください）。ページ読み込み前にスクリプトを注入する場合（サイトのスクリプトより 前に 実行する必要があるフィンガープリントのパッチ）は、js_code: ではなく init_scripts: に入力してください（js_code: はページ読み込み後に実行されます）。proxy_config はブラウザー戦略と、ブラウザーを使用しない HTTPCrawlerStrategy の両方で動作します。後者は、企業プロキシ経由で静的コンテンツを取得する際の低コストな方法です。

全機能（CDP 接続、検出回避モード、初期化スクリプトのパターン）については、検出回避を参照してください。

キャッシュ済み HTML のレンダリング（raw: / file://）

エージェントがすでに HTML（たとえば defuddle や以前のクロールで取得したもの）を持っていて、スクリーンショット、PDF、または MHTML のレンダリングだけが必要な場合は、ネットワーク取得を省略し、HTML を直接渡します。base_url は相対リンクの解決方法を制御します。

result = await crawler.arun(
    url="raw:" + html_string,
    config=CrawlerRunConfig(base_url="https://example.com", screenshot=True, pdf=True),
)

result = await crawler.arun(
    url="file:///path/to/page.html",
    config=CrawlerRunConfig(screenshot=True),
)

---

一般的なユースケース

ドキュメントページ、JavaScript を多用する SPA、E コマース商品の抽出、ニュースの集約、トピックを限定したドメインのクロール、ログイン必須のコンテンツ、既存の HTML のレンダリング、Q&A という、エンドツーエンドの手順を解説した 8 つの例が レシピ集 にあります。目的に最も近いレシピを選び、必要に応じて調整してください。

---

リソース

提供スクリプト

スクリプト	用途
scripts/basic_crawler.py <url>	1 つの URL → Markdown とスクリーンショット
scripts/batch_crawl.py <urls.txt>	複数の URL → Markdown ファイル
scripts/batch_extract.py <urls.txt> <schema.json>	複数の URL + スキーマ → JSON
scripts/generate_schema.py <url> "<instruction>"	再利用可能な CSS スキーマを生成（LLM の呼び出しは 1 回）
scripts/extract_with_schema.py <url> <schema.json>	保存済みのスキーマを適用（LLM 不使用）
scripts/extract_with_llm.py <url> "<instruction>"	リクエストごとの LLM 抽出（高コスト。一度限りの用途のみ）

テンプレート

ユーザーがコピーして記入する YAML および JSON のひな形です。すべてスキルのルートにある templates/ の下にあります。

テンプレート	用途
templates/browser.yml	BrowserConfig（ヘッドレス、プロキシ、ユーザーエージェント、初期化スクリプト）
templates/crawler.yml	CrawlerRunConfig（キャッシュ、待機、タイムアウト、JS）
templates/extract_css.yml	JsonCssExtractionStrategy の宣言
templates/extract_llm.yml	LLMExtractionStrategy の宣言
templates/filter_bm25.yml	BM25 コンテンツフィルター（関連性スコア付き）
templates/filter_pruning.yml	Pruning コンテンツフィルター（品質ベース、クエリ不要）
templates/login_crawler.yml	セッションを確立するログインフロー
templates/css_schema.json	CSS スキーマのひな形

リファレンスドキュメント

ドキュメント	目的
CLI ガイド	コマンドラインインターフェースのリファレンス
SDK ガイド	Python SDK のクイックリファレンス
レシピ集	エンドツーエンドの手順を解説した 8 つの例
URL 検出	AsyncUrlSeeder、SeedingConfig、DomainMapper
コンテンツフィルター	BM25、Pruning、LLMContentFilter の使い分け
検出回避	init_scripts、proxy_config、検出回避モード、CDP 接続
トラブルシューティング	症状、原因、対処法。エスカレーション前に試すこと
SDK 完全リファレンス	API ドキュメント全文（5900 行以上）
エスカレーション	参照順序、厳守ルール、中止か続行か、解説付きの例

---

ベストプラクティス

1. 手早いタスクには CLI、自動化には SDK から始めます
2. スキーマベースの抽出を使用します。LLM より 10〜100 倍効率的です
3. 開発中はキャッシュを有効にします。必要な場合にのみ --bypass-cache を使用します
4. 適切なタイムアウトを設定します。通常は 30 秒、JavaScript を多用するサイトでは 60 秒以上です
5. コンテンツフィルターを使用して、より整理された、焦点の絞られた Markdown にします
6. レート制限を遵守します。リクエストの間に遅延を設けます

---

トラブルシューティング

症状 → 原因 → 修正の表（JavaScript が読み込まれない、ボット検出、抽出したコンテンツが空、セッションが保持されない、クロールが遅い、スキーマ生成結果が不適切、アップグレード後のリグレッション）については、トラブルシューティングを参照してください。リファレンスにない不明な問題については、エスカレーションに従ってください。

---

包括的な API ドキュメントについては、完全版 SDK リファレンスを参照してください。

ライセンス

MIT または Apache-2.0 のデュアルライセンスです（SPDX: MIT OR Apache-2.0）。説明および上流の内容をミラーした references/complete-sdk-reference.md に適用される例外については、LICENSE を参照してください。