model-verify-flagos

目标模型验证

采用与 env-verify 相同的分层排查方法，但使用可能需要多 GPU 张量并行的真实目标模型。运行模型两次（一次不使用多芯片栈，一次使用多芯片栈），并比较结果以定位故障。

技能组件

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，比较两次运行：

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