build-eye

# Build-Eye CI 監視システム **ビルド鷹の目** - vLLM-Ascend CI ビルド自動監視・根本原因分析システム ## システム概要 Build-Eye は vLLM-Ascend プロジェクト専用に設計された CI ビルド監視システムで、以下が可能です： - vllm-project/vllm-ascend リポジトリの CI ビルドを**自動監視** - ビルド失敗の根本原因（コード問題/インフラ問題/干渉問題）を**インテリジェントに分類** - 低コストで実行可能な修正案を**生成** - 標準化レポートを build-eye リポジトリに**自動アーカイブ** ## 監視対象 - 主力監視リポジトリ: https://github.com/vllm-project/vllm-ascend - アーカイブホスティングリポジトリ: https://github.com/winson-00178005/build-eye.git ## 失敗根本原因の分類 ### 1. PR コード問題 - テストアサーション失敗 - コンパイルエラー（CMake、clang） - Python インポートエラー - vLLM API 非互換 - Ascend kernel コンパイル問題 ### 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 ワークフロー システムは 2 つのトリガーモードをサポートしています： ### 定期ポーリング 6 時間ごとに最近のビルド失敗を自動チェックします。 ワークフローファイル: `.github/workflows/monitor.yml` ### 手動トリガー GitHub Actions の `workflow_dispatch` による手動トリガー。 オプションパラメータ： - `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 アクセス token - `ARCHIVE_TOKEN`: アーカイブリポジトリ書き込み token - `TARGET_REPO_OWNER`: 対象リポジトリ owner - `TARGET_REPO_NAME`: 対象リポジトリ名 ## レポート形式 各レポートに含まれるもの： - YAML frontmatter（メタデータ） - 概要（1〜2 文） - 根本原因分析（分類、信頼度、推論） - 証拠（マッチパターン、リンク、ログ断片） - 修正提案（優先提案、詳細手順） - 関連 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