model-verify-flagos

ターゲットモデルの検証

env-verify と同じレイヤーごとに切り分ける手法を、マルチ GPU のテンソル並列が必要になる場合がある実際のターゲットモデルで実行します。モデルを 2 回（マルチチップスタックなしとあり）実行し、結果を比較して障害の原因を特定します。

スキルの構成要素

model-verify/
├── SKILL.md                            # This file — execution flow
├── scripts/
│   └── diff_analysis.py                # Compare Run A vs Run B, classify errors (JSON)
└── references/
    └── multichip-errors.md             # Multi-chip error patterns and diff truth table

env-verify から再利用するもの：

• env-verify/scripts/run_offline_inference.py — フェーズ A のテスト（パラメーター化済み）
• env-verify/scripts/test_serve_mode.py — フェーズ B のテスト（パラメーター化済み）
• env-verify/references/error-classification.md — レイヤー別のエラー判定ルール

前提条件

• ソフトウェアスタックをインストール済みの実行中コンテナ（install-stack でインストール）
• env-verify が完了していること（少なくともフェーズ A に合格）
• ユーザーがモデルのパスを指定すること

単独で呼び出された場合は、コンテナ名、ベンダー、モデルのパスを尋ねてください。 /flagrelease から呼び出された場合、これらはコンテキストとして渡されます。

実行フロー

ステップ 1：ユーザーからモデル情報を取得する

ユーザーに以下を尋ねてください（指定されていない場合は AskUserQuestion を使用）：

1. モデルのパス（必須）— コンテナ内のローカルパス、または ModelScope/HuggingFace ID
2. --tensor-parallel-size（任意）— デフォルトは GPU 数
3. 追加の vllm 引数（任意）

デフォルトの TP サイズを取得します：

docker exec <CONTAINER> python3 -c "
import torch; print(torch.cuda.device_count() if torch.cuda.is_available() else 1)
"

ユーザーがモデルのパスを指定しない場合 → 尋ねて回答を待ちます。推測しないでください。

ステップ 2：モデルをダウンロードする（必要な場合）

モデルのパスがリモート ID（/ で始まらない）の場合：

docker exec <CONTAINER> python3 -c "
from modelscope import snapshot_download
snapshot_download('<MODEL_ID>', local_dir='/data/models/<MODEL_NAME>')
"

ローカルディレクトリの場合は、config.json が存在することを確認します：

docker exec <CONTAINER> test -f <MODEL_PATH>/config.json

タイムアウト： 大規模モデルのダウンロードには 600s を設定します。

ステップ 3：実行 A — マルチチップスタックなし

env-verify からテストスクリプトをコンテナにコピーします（まだ存在しない場合）：

docker cp <ENV_VERIFY_DIR>/scripts/run_offline_inference.py <CONTAINER>:/tmp/
docker cp <ENV_VERIFY_DIR>/scripts/test_serve_mode.py <CONTAINER>:/tmp/

フェーズ A（オフライン）：

docker exec <CONTAINER> bash -c '
export USE_FLAGGEMS=0
unset FLAGCX_PATH
timeout 300 python3 /tmp/run_offline_inference.py \
    --model <MODEL_PATH> \
    --tp <TP_SIZE> \
    --trust-remote-code
' > /tmp/run_a_offline.json

フェーズ B（サーブ）：

docker exec <CONTAINER> bash -c '
export USE_FLAGGEMS=0
unset FLAGCX_PATH
timeout 360 python3 /tmp/test_serve_mode.py \
    --model <MODEL_PATH> \
    --tp <TP_SIZE> \
    --trust-remote-code \
    --health-timeout 300
' > /tmp/run_a_serve.json

ステップ 4：実行 B — マルチチップスタック全体を有効化

スキップ条件： FlagGems、FlagTree、FlagCX のすべてのインストールに失敗した場合は、実行 B をスキップします。 次のように報告します："Run B skipped: no multi-chip packages installed." 判定には install-stack の結果を確認します。

フェーズ A（オフライン）：

docker exec <CONTAINER> bash -c '
export USE_FLAGGEMS=1
export FLAGCX_PATH=/tmp/FlagCX
export VLLM_PLUGINS=fl
timeout 300 python3 /tmp/run_offline_inference.py \
    --model <MODEL_PATH> \
    --tp <TP_SIZE> \
    --trust-remote-code
' > /tmp/run_b_offline.json

フェーズ B（サーブ）：

docker exec <CONTAINER> bash -c '
export USE_FLAGGEMS=1
export FLAGCX_PATH=/tmp/FlagCX
export VLLM_PLUGINS=fl
timeout 360 python3 /tmp/test_serve_mode.py \
    --model <MODEL_PATH> \
    --tp <TP_SIZE> \
    --trust-remote-code \
    --health-timeout 300
' > /tmp/run_b_serve.json

ステップ 5：差分分析

scripts/diff_analysis.py をコピーして実行し、2 回の実行結果を比較します：

docker cp <SKILL_DIR>/scripts/diff_analysis.py <CONTAINER>:/tmp/
docker exec <CONTAINER> python3 /tmp/diff_analysis.py \
    --run-a /tmp/run_a_offline.json \
    --run-b /tmp/run_b_offline.json

references/multichip-errors.md を読み、差分を解釈してエラーを分類します。

ステップ 6：レポートを作成する

{
  "status": "PASS | PARTIAL | FAIL",
  "stage": "model-verify",
  "model": "<MODEL_PATH>",
  "tensor_parallel_size": 8,
  "run_a_without_multichip": {
    "flags": {"USE_FLAGGEMS": "0", "FLAGCX_PATH": "unset"},
    "phase_a_offline": "PASS | FAIL",
    "phase_b_serve": "PASS | FAIL",
    "output_sample": "...",
    "errors": []
  },
  "run_b_with_multichip": {
    "flags": {"USE_FLAGGEMS": "1", "FLAGCX_PATH": "/tmp/FlagCX"},
    "skipped": false,
    "phase_a_offline": "PASS | FAIL",
    "phase_b_serve": "PASS | FAIL",
    "output_sample": "...",
    "errors": []
  },
  "diff_analysis": {
    "conclusion": "BOTH_PASS | MULTICHIP_ERROR | SAME_ERROR | DIFFERENT_ERRORS",
    "detail": "...",
    "multichip_component": "FlagGems | FlagTree | FlagCX | plugin | null",
    "recommended_stack": "full | base | none"
  }
}

recommended_stack — 後続のスキルで使用するスタックを指定します：

• full — 実行 B に合格（USE_FLAGGEMS=1、FLAGCX_PATH を設定）
• base — 実行 A のみ合格（USE_FLAGGEMS=0、FLAGCX_PATH は未設定）
• none — 実行 A も失敗（モデルをサーブできない）

ステータスの判定：

• PASS — 実行 A と実行 B の両方が成功
• PARTIAL — 実行 A は合格、実行 B は失敗
• FAIL — 実行 A が失敗

エラー処理

失敗	対応
モデルのパスが指定されていない	ユーザーに尋ねて回答を待つ
モデルのパスが見つからない	正確なパスを報告し、エラーで終了
モデルがメモリに収まらない	OOM を報告し、TP または dtype の縮小を提案
TP > 利用可能な GPU 数	"requested TP=X but only Y available" と報告
サーバーが応答しない	タイムアウト後に停止し、最後のログを取得
実行 A と実行 B の両方が失敗	両方のエラーを個別に報告

ルール： 個々の実行の成否にかかわらず、両方の実行を行います。エラーをできるだけ広く把握してください。

タイムアウトのルール

操作	タイムアウト
モデルのダウンロード	600s
フェーズ A（オフライン）	300s
フェーズ B（サーブ＋テスト）	360s