دليل المبتدئين لـ Crawl4AI: شرح خطوة بخطوة

في عصر الذكاء الاصطناعي، أصبح الوصول إلى بيانات الويب ومعالجتها بكفاءة أمرًا بالغ الأهمية. يبرز Crawl4AI كأداة قوية مفتوحة المصدر لزحف الويب وكشطه، تم تصميمها بدقة للمطورين الذين يعملون مع نماذج اللغات الكبيرة (LLMs)، وعوامل الذكاء الاصطناعي، وخطوط بيانات العصر الحديث. يقدم هذا البرنامج التعليمي غوصًا عميقًا في Crawl4AI، ويغطي كل شيء بدءًا من التثبيت وصولًا إلى تقنيات الزحف المتقدمة.

لماذا تختار Crawl4AI لمشاريعك؟

Crawl4AI هو أكثر من مجرد كاشط ويب قياسي. إنه مصمم من الألف إلى الياء ليكون متوافقًا مع نماذج اللغات الكبيرة (LLM-friendly). هذا يعني أنه يركز على:

• توليد Markdown نظيف: إنتاج Markdown منظم وموجز ومُحسن لأنظمة التوليد المعزز بالاسترجاع (RAG) والضبط الدقيق للنماذج عن طريق إزالة النصوص المتكررة والضوضاء.
• استخراج البيانات المهيكلة: تمكين استخراج نقاط بيانات محددة بتنسيقات مثل JSON باستخدام الطرق التقليدية (محددات CSS، XPath) أو الاستفادة من نماذج اللغات الكبيرة (LLMs) لمهام الاستخراج الدلالي الأكثر تعقيدًا.
• أداء عالٍ: استخدام مكتبة asyncio في بايثون وإطار عمل أتمتة المتصفح القوي Playwright لزحف سريع وغير متزامن.
• تحكم متقدم في المتصفح: توفير تحكم دقيق في مثيل المتصفح، بما في ذلك تنفيذ JavaScript، والتعامل مع المحتوى الديناميكي، وإدارة الجلسات (ملفات تعريف الارتباط، التخزين المحلي)، واستخدام الوكلاء (proxies)، ومحاكاة بيئات مستخدم مختلفة (وكلاء المستخدم، المواقع الجغرافية).
• مفتوح المصدر ومرونة: كونه مفتوح المصدر بالكامل (Apache 2.0 مع الإسناد) دون الاعتماد على مفاتيح API خارجية أو خدمات مدفوعة. يوفر مرونة في النشر عبر Docker أو التثبيت المباشر عبر pip.

يهدف Crawl4AI إلى إضفاء الطابع الديمقراطي على الوصول إلى البيانات، وتمكين المطورين من جمع وتشكيل بيانات الويب بسرعة وكفاءة.

تثبيت وإعداد Crawl4AI

تشغيل Crawl4AI أمر بسيط، حيث يوفر خياري pip و Docker.

الطريقة 1: التثبيت عبر Pip (موصى به للاستخدام كمكتبة)

تثبيت الحزمة: افتح الطرفية (terminal) الخاصة بك وقم بتشغيل:

# تثبيت أحدث إصدار مستقر
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 الخام والمصفى
            print(f"Fit 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"عدد كلمات Fit 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 يعيد كائنًا واحدًا أو أكثر من نوع 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: ملفات تعريف الارتباط للمتصفح بعد الزحف.
• screenshot_path: المسار إلى لقطة الشاشة إذا تم التقاطها.
• network_log_path: المسار إلى ملف HAR للشبكة إذا تم التقاطه.
• console_log_path: المسار إلى ملف سجل وحدة التحكم إذا تم التقاطه.

فحص هذا الكائن هو المفتاح للوصول إلى البيانات المحددة التي تحتاجها من عملية زحف Crawl4AI.

كيفية توليد Markdown جاهز للذكاء الاصطناعي باستخدام Crawl4AI

إحدى نقاط القوة الأساسية في Crawl4AI هي قدرته على توليد Markdown نظيف مناسب لـ نماذج اللغات الكبيرة (LLMs).

تحتوي السمة result.markdown على:

• result.markdown.raw_markdown: التحويل المباشر وغير المصفى لمنطقة المحتوى الأساسية للصفحة إلى Markdown.
• result.markdown.fit_markdown: إصدار مصفى من Markdown. غالبًا ما يكون هذا هو الأكثر فائدة لنماذج اللغات الكبيرة (LLMs)، حيث يطبق Crawl4AI مرشحات استدلالية (مثل PruningContentFilter أو BM25ContentFilter) لإزالة الفوضى الشائعة في الويب (القوائم، الإعلانات، التذييلات، الأشرطة الجانبية).
• 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"طول Raw Markdown: {len(result.markdown.raw_markdown)}")
            print(f"طول Fit 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())

من خلال ضبط content_filter داخل markdown_generator، يمكنك التحكم في مدى قوة Crawl4AI في تنظيف المحتوى قبل إنتاج fit_markdown.

كيفية استخدام الزحف العميق في Crawl4AI

Crawl4AI لا يقتصر على الصفحات الفردية. يمكنه إجراء زحف عميق، والتنقل عبر موقع ويب عن طريق اتباع الروابط.

استخدم الدالة adeep_crawl (أو العلامة --deep-crawl في واجهة سطر الأوامر crwl):

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}, طول Fit 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: استخدم أنماط regex لتصفية عناوين URL التي يتم اتباعها.

كيفية التعامل مع المحتوى الديناميكي والتفاعلات باستخدام Crawl4AI

تعتمد المواقع الحديثة بشكل كبير على JavaScript لتحميل المحتوى. يتعامل Crawl4AI مع هذا من خلال قدرات Playwright.

يمكنك تنفيذ JavaScript عشوائي أو الانتظار لشروط محددة باستخدام CrawlerRunConfig:

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('Clicking load more button...');
            loadMoreButton.click();
            // انتظر قليلاً لتحميل المحتوى بعد النقر
            await new Promise(resolve => setTimeout(resolve, 2000));
            console.log('Waited after click.');
        } else {
            console.log('Load more button not found.');
        }
    })();
    """

    run_conf = CrawlerRunConfig(
        cache_mode=CacheMode.BYPASS,
        js_code=[js_to_run], # قائمة بمقاطع JS لتنفيذها
        wait_for_timeout=3000, # انتظر 3 ثوانٍ بعد التحميل الأولي وبعد تنفيذ JS
        # wait_for_selector="div.newly-loaded-content", # أو انتظر عنصرًا محددًا
        extraction_strategy=css_extractor, # استخراج البيانات بعد تشغيل JS
        output_formats=['markdown', 'extracted_content']
    )

    # تأكد من تمكين JS في BrowserConfig (هو كذلك افتراضيًا)
    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"طول Fit 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' وإلغاء التعليق على السطر أعلاه لتشغيل المثال الديناميكي.")

معلمات تفاعل Crawl4AI الرئيسية في CrawlerRunConfig:

• js_code: قائمة بسلاسل JavaScript لتنفيذها في سياق الصفحة.
• wait_for_timeout: عدد المللي ثانية للانتظار بعد تحميل الصفحة وبعد تنفيذ JS.
• wait_for_selector: محدد CSS للانتظار حتى يظهر قبل اعتبار الصفحة محملة/التفاعل مكتملًا.
• page_interaction_hooks: خطافات (hooks) أكثر تقدمًا للتفاعلات المعقدة.

خلاصة Crawl4AI

يوفر Crawl4AI حلاً شاملاً، بلغة بايثون، ومرتكزًا على الذكاء الاصطناعي لزحف الويب وكشطه. تركيزه على توليد Markdown نظيف، استخراج بيانات مهيكلة مرنة (سواء بناءً على CSS أو LLM)، التعامل القوي مع المحتوى الديناميكي، والعمليات غير المتزامنة الفعالة يجعله خيارًا ممتازًا للمشاريع التي تتضمن RAG، الضبط الدقيق لـ LLM، أو أي مهمة تتطلب معلومات مهيكلة من الويب. من خلال الاستفادة من واجهة برمجة التطبيقات الواضحة، خيارات التكوين (BrowserConfig، CrawlerRunConfig)، وكائن CrawlResult المفصل، يمكن للمطورين بناء سير عمل لجمع البيانات معقد وفعال.