Multi-URL Crawler with LLM Analysis

複数のURLをクロールし、LLM（OpenRouter経由のGemini 2.5 Flash Lite）を使用して検索条件に基づいた分析を行うツールです。

特徴

• 🚀 高速: Python 3.13 + UV + venv + Crawl4AI による高速なクロール処理
• 🤖 LLM統合: OpenRouter経由でGemini 2.5 Flash Liteを使用した高度な内容分析
• 📦 構造化出力: Pydanticスキーマによる型安全な構造化JSON出力
• ♻️ インスタンス再利用: 効率的なCrawl4AIインスタンスの再利用
• ⚡ 並列実行対応: 複数インスタンスによる並列処理をサポート
• 🐳 Docker対応: 簡単なデプロイと環境分離

出力形式

{
  "results": [
    {
      "url": "https://example.com",
      "is_update_required": true,
      "part": "関連するテキスト部分（オプション）",
      "comment": "LLMがis_update_requiredをtrueにした理由"
    }
  ]
}

フィールド説明

• url: 分析対象のURL
• is_update_required: 検索条件に該当し更新が必要か（true/false）
• part: 検索条件に関連する重要なテキスト部分（オプション）
• comment: LLMの判断理由

セットアップ

1. 環境変数の設定

cp .env.example .env

.envファイルを編集してOpenRouter APIキーを設定:

OPENROUTER_API_KEY=your_actual_api_key_here

OpenRouter APIキーは https://openrouter.ai/keys から取得できます。

2. Docker Composeを使用する場合（推奨）

# 実行例: 単一URL
docker-compose run --rm multicrawler \
  -u "https://example.com" \
  -c "新しい製品情報があるか確認"

# 実行例: 複数URL
docker-compose run --rm multicrawler \
  -u "https://site1.com" "https://site2.com" "https://site3.com" \
  -c "価格変更の有無を確認"

3. Dockerを直接使用する場合

# イメージのビルド
docker build -t multicrawler .

# 実行
docker run --rm \
  -e OPENROUTER_API_KEY=your_api_key \
  multicrawler \
  -u "https://example.com" \
  -c "在庫状況の確認"

4. ローカル環境で実行する場合

# Python 3.13以降が必要
python -m venv .venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate

# UVのインストール
pip install uv

# 依存関係のインストール
uv pip install -e .

# Playwrightブラウザとcrawl4aiのセットアップ
python -m playwright install chromium
crawl4ai-setup

# 実行
python -m src.main \
  -u "https://example.com" \
  -c "新しい情報があるか確認"

使用方法

コマンドライン引数

python -m src.main [オプション]

必須引数:
  -u, --urls URL [URL ...]     分析対象のURL（1つ以上指定可能）
  -c, --condition TEXT          検索条件（自然言語で記述）

オプション引数:
  -k, --api-key TEXT           OpenRouter APIキー
                               （環境変数OPENROUTER_API_KEYでも指定可能）
  -h, --help                   ヘルプメッセージを表示

使用例

例1: 単一URLの分析

python -m src.main \
  -u "https://news.example.com" \
  -c "AI技術に関する新しい記事があるか確認"

例2: 複数URLの並列分析

python -m src.main \
  -u "https://shop1.com/product" "https://shop2.com/product" "https://shop3.com/product" \
  -c "商品の価格が10000円以下になったか確認"

例3: APIキーを直接指定

python -m src.main \
  -u "https://blog.example.com" \
  -c "過去1週間以内の投稿があるか" \
  -k "sk-or-v1-xxxxxxxxxxxx"

並列実行

パターン1: 単一インスタンス内での並列URL処理（推奨）

デフォルトの動作。複数URLを1つのサービスインスタンスで効率的に並列処理します。

# Crawl4AIインスタンスを1つ作成し、内部で3つのURLを並列処理
docker-compose run --rm multicrawler \
  -u "https://site1.com" "https://site2.com" "https://site3.com" \
  -c "更新確認"

パターン2: 複数インスタンスでの独立並列処理

異なる検索条件で複数のクローラーを同時実行する場合:

# docker-compose.ymlの parallel プロファイルを使用
docker-compose --profile parallel up

# または、個別に起動
docker-compose up multicrawler-instance-1 multicrawler-instance-2

プログラムからの利用

import asyncio
from src import URLAnalyzerService

async def main():
    urls = [
        "https://example1.com",
        "https://example2.com",
    ]
    search_condition = "新製品の発表情報"

    # サービスインスタンスの作成と再利用
    async with URLAnalyzerService() as service:
        # 複数URLを並列分析
        response = await service.analyze_urls(urls, search_condition)

        # 結果の処理
        for result in response.results:
            print(f"URL: {result.url}")
            print(f"更新必要: {result.is_update_required}")
            print(f"理由: {result.comment}")
            if result.part:
                print(f"関連部分: {result.part}")
            print("---")

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

アーキテクチャ

コンポーネント構成

multicrawler/
├── src/
│   ├── __init__.py           # パッケージ初期化
│   ├── models.py             # Pydanticモデル定義
│   ├── crawler_service.py    # メインクローラーサービス
│   └── main.py               # CLIエントリーポイント
├── Dockerfile                # Dockerイメージ定義
├── docker-compose.yml        # Docker Compose設定
├── pyproject.toml            # プロジェクト・依存関係定義
└── .env.example              # 環境変数テンプレート

動作フロー

1. 初期化: URLAnalyzerServiceがAsyncWebCrawlerインスタンスを作成
2. URL処理: 各URLに対して並列でクロール実行
3. LLM分析: クロール結果をOpenRouter (Gemini 2.5 Flash Lite)に送信
4. 構造化出力: Pydanticスキーマに基づいてLLM応答をパース
5. 結果集約: すべての結果を1つのAnalysisResponseとして返却

インスタンス管理

• 単一インスタンス再利用: async withコンテキストマネージャーでCrawl4AIインスタンスを効率的に再利用
• 並列インスタンス: Docker Composeで複数コンテナを起動し、完全に独立した並列処理が可能

環境変数

変数名	説明	必須	デフォルト
OPENROUTER_API_KEY	OpenRouter APIキー	✅ Yes	-
CRAWL4AI_HEADLESS	ヘッドレスモード	No	true
CRAWL4AI_VERBOSE	詳細ログ出力	No	false

トラブルシューティング

よくある問題

1. APIキーエラー

ValueError: OpenRouter API key is required

解決方法: .envファイルにAPIキーが正しく設定されているか確認してください。

2. Playwrightブラウザのインストールエラー

Playwright browser not found

解決方法:

python -m playwright install chromium
crawl4ai-setup

3. LLM応答のパースエラー

LLM応答のパースエラー: ...

解決方法: LLMが構造化出力に対応していない可能性があります。APIキーとモデル設定を確認してください。

技術スタック

• Python: 3.13
• パッケージマネージャー: UV
• クローラー: Crawl4AI (Playwright-based)
• LLM: OpenRouter (google/gemini-2.5-flash-lite)
• スキーマ: Pydantic v2
• コンテナ: Docker + Docker Compose

ライセンス

MIT

参考リンク

• Crawl4AI Documentation
• OpenRouter
• UV Package Manager