عن المشروع

# نظام مراقبة Build-Eye CI **عين الصقر للبناء** - نظام مراقبة وتحليل السبب الجذري لأتمتة بناء CI الخاص بـ vLLM-Ascend ## نظرة عامة على النظام Build-Eye هو نظام مراقبة بناء CI مصمم خصيصًا لمشروع vLLM-Ascend، وهو قادر على: - **المراقبة التلقائية** لعمليات بناء CI في مستودع vllm-project/vllm-ascend - **التصنيف الذكي** لأسباب فشل البناء (مشكلات الكود/مشكلات البنية التحتية/مشكلات التداخل) - **توليد اقتراحات** لحلول إصلاح منخفضة التكلفة وقابلة للتنفيذ - **أرشفة التقارير** تلقائيًا بتقارير موحدة إلى مستودع build-eye ## أهداف المراقبة - مستودع المراقبة الرئيسي: https://github.com/vllm-project/vllm-ascend - مستودع الأرشفة والاستضافة: https://github.com/winson-00178005/build-eye.git ## تصنيف الأسباب الجذرية للفشل ### 1. مشكلات كود PR - فشل تأكيدات الاختبار - أخطاء الترجمة (CMake، clang) - أخطاء استيراد Python - عدم توافق واجهة برمجة تطبيقات vLLM - مشكلات ترجمة نواة Ascend ### 2. مشكلات البنية التحتية - فشل K8s cache-service (cache-service.nginx-pypi-cache) - عدم توفر Runner - مشكلات أجهزة NPU (910B/910C/310P) - مشكلات CANN toolkit - فشل اتصال HCCL متعدد البطاقات - فشل سحب صورة Docker - فشل ذاكرة Csrc المؤقتة - انتهاء مهلة البناء ### 3. تداخل تزامن PR متعددة - دمج عدة PR خلال فترة زمنية قصيرة - اختلافات مصفوفة إصدارات vLLM - تنافس موارد Runner - تأثير تحديثات صورة CANN ## البدء السريع ### 1. تكوين GitHub Token راجع `docs/token-setup.md` لتكوين المفاتيح المطلوبة. ### 2. تثبيت التبعيات ```bash pip install -r requirements.txt ``` ### 3. تشغيل المراقبة يدويًا ```bash python scripts/monitor/fetch_runs.py --output data/workflow_runs.json python scripts/monitor/collect_metadata.py --input data/workflow_runs.json --output data/build_metadata.json python scripts/classify/classifier.py --input data/build_metadata.json --output data/classifications.json python scripts/recommend/recommender.py --input data/classifications.json --output data/recommendations.json python scripts/report/generator.py --input data/recommendations.json --output reports/ ``` ### 4. أرشفة التقارير ```bash python scripts/archive/archiver.py --input reports/ --repo https://github.com/winson-00178005/build-eye.git ``` ## سير عمل GitHub Actions يدعم النظام وضعي تشغيل: ### الاستقصاء المجدول فحص حالات فشل البناء الأخيرة تلقائيًا كل 6 ساعات. ملف سير العمل: `.github/workflows/monitor.yml` ### التشغيل اليدوي التشغيل يدويًا عبر `workflow_dispatch` في GitHub Actions. المعاملات الاختيارية: - `lookback_hours`: عدد الساعات الماضية للفحص (الافتراضي 24) - `dry_run`: وضع التشغيل التجريبي (بدون أرشفة) - `target_repo`: المستودع الهدف ## هيكل المشروع ``` build-eye/ ├── .github/workflows/ │ └── monitor.yml # سير عمل GitHub Actions ├── scripts/ │ ├── monitor/ # وحدة مراقبة CI │ │ ├── github_client.py # عميل GitHub API │ │ ├── fetch_runs.py # جلب workflow runs │ │ ├── collect_metadata.py # جمع البيانات الوصفية │ │ └── config_loader.py # تحميل التكوين │ ├── classify/ # وحدة تصنيف الفشل │ │ ├── classifier.py # محرك التصنيف │ │ ├── code_detector.py # كشف مشكلات الكود │ │ ├── infra_detector.py # كشف البنية التحتية │ │ └── interference_detector.py # كشف التداخل │ ├── recommend/ # وحدة اقتراحات الإصلاح │ │ ├── recommender.py # مولّد الاقتراحات │ │ └── templates.py # قوالب الاقتراحات │ ├── report/ # وحدة توليد التقارير │ │ ├── generator.py # مولّد التقارير │ │ ├── formatter.py # أدوات التنسيق │ │ └── summary.py # توليد الملخص │ └── archive/ # وحدة أرشفة التقارير │ ├── archiver.py # المؤرشف │ └── git_client.py # عميل Git ├── config/ │ └── config.yaml # تكوين النظام ├── templates/ │ └ example_reports.py # أمثلة التقارير ├── tests/ # دليل الاختبارات ├── docs/ │ └ token-setup.md # دليل تكوين Token ├── reports/ # دليل إخراج التقارير └ requirements.txt # تبعيات Python └ requirements-dev.txt # تبعيات التطوير └ README.md # هذه الوثيقة ``` ## خيارات التكوين ### config/config.yaml ```yaml target_repository: owner: vllm-project repo: vllm-ascend url: https://github.com/vllm-project/vllm-ascend branch: main monitored_workflows: - pr_test_full.yaml - pr_test_light.yaml archive_repository: owner: winson-00178005 repo: build-eye url: https://github.com/winson-00178005/build-eye.git monitoring: polling_interval_hours: 6 lookback_hours: 24 ``` ### متغيرات البيئة - `GITHUB_TOKEN`: رمز الوصول إلى GitHub API - `ARCHIVE_TOKEN`: رمز الكتابة إلى مستودع الأرشفة - `TARGET_REPO_OWNER`: مالك المستودع الهدف - `TARGET_REPO_NAME`: اسم المستودع الهدف ## تنسيق التقرير يتضمن كل تقرير: - YAML frontmatter (البيانات الوصفية) - ملخص (جملة إلى جملتين) - تحليل السبب الجذري (التصنيف، درجة الثقة، الاستدلال) - الأدلة (أنماط المطابقة، الروابط، مقتطفات السجل) - اقتراحات الإصلاح (الاقتراح المفضل، الخطوات التفصيلية) - PR ذات الصلة (لتصنيف التداخل فقط) مسار أرشفة التقرير: `reports/YYYY/MM/DD/<التصنيف>-pr-<الرقم>.md` ## تشغيل الاختبارات ```bash pip install -r requirements-dev.txt pytest tests/ ``` ## توسيع خط أنابيب nightly تم تصميم النظام لدعم مراقبة خط أنابيب nightly، ما عليك سوى الإضافة في التكوين: ```yaml target_repository: monitored_workflows: - schedule_nightly_test_a2.yaml - schedule_nightly_test_a3.yaml ``` ## الصيانة والتوسيع ### إضافة قواعد تصنيف جديدة أضف كاشفًا جديدًا في `scripts/classify/`: ```python def detect_new_pattern(log_excerpt: str) -> dict: patterns = [...] # تنفيذ منطق الكشف ``` ثم استدعِه في `classifier.py`. ### إضافة قوالب اقتراحات جديدة أضف قالبًا جديدًا في `scripts/recommend/templates.py`. ## الترخيص Apache License 2.0 - راجع ملف LICENSE للتفاصيل ## معلومات الاتصال الإبلاغ عن المشكلات: https://github.com/winson-00178005/build-eye/issues