Blog

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

Audrey Lopez

Audrey Lopez

18 يوليو 2025

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

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

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API) تقوم بإنشاء توثيق API جميل؟

هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بأقصى قدر من الإنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر أقل بكثير!
button

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

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

يهدف 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 الرئيسية:

كيف يعمل كائن Crawl4AI CrawlResult؟

كل استدعاء ناجح للدالة arun أو arun_many يعيد كائنًا واحدًا أو أكثر من نوع CrawlResult، والتي تغلف جميع المعلومات التي تم جمعها أثناء عملية الزحف.

يحتوي كائن CrawlResult على سمات مختلفة، بما في ذلك:

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

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

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

تحتوي السمة result.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:

كيفية التعامل مع المحتوى الديناميكي والتفاعلات باستخدام 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:

خلاصة Crawl4AI

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

💡
هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API) تقوم بإنشاء توثيق API جميل؟

هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بأقصى قدر من الإنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر أقل بكثير!
button

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل