flagrelease-entrance-flagos

FlagRelease 流水线编排器

面向多芯片 GPU 后端的端到端大模型部署与测试流水线。 按顺序编排 4 个子技能并生成最终报告。

技能组件

flagrelease/
├── SKILL.md                            # This file — orchestration flow
└── references/
    └── pipeline-state.md               # Pipeline state schema, gate logic, data flow

子技能（均可独立调用）：

../install-stack/                       # Step 2: Install 5 packages
│   ├── SKILL.md
│   ├── scripts/
│   │   ├── detect_network.py           # Probe GitHub/PyPI, return mirror config
│   │   ├── collect_env_info.py         # Python/glibc/arch/vendor/disk info
│   │   ├── select_flagtree_wheel.py    # Match vendor+python+glibc → wheel
│   │   └── validate_packages.py        # Import-test all 5 packages
│   └── references/
│       ├── vendor-mappings.md          # FlagCX make flags, adaptor names
│       └── network-mirrors.md          # Mirror config rules

../env-verify/                          # Step 3: Qwen3-0.6B smoke test
│   ├── SKILL.md
│   ├── scripts/
│   │   ├── run_offline_inference.py    # Phase A: offline inference test
│   │   └── test_serve_mode.py          # Phase B: serve + health + chat test
│   └── references/
│       └── error-classification.md     # Layer-based error classification

../model-verify/                        # Step 4: Target model ± multi-chip
│   ├── SKILL.md
│   ├── scripts/
│   │   └── diff_analysis.py            # Compare Run A vs Run B results
│   └── references/
│       └── multichip-errors.md         # Multi-chip error patterns

../perf-test/                           # Steps 5+6: Accuracy + Performance
│   ├── SKILL.md
│   ├── scripts/
│   │   ├── run_benchmark.py            # Run single benchmark profile
│   │   └── run_all_benchmarks.py       # Run all profiles + summarize
│   └── references/
│       └── benchmark-profiles.md       # Profile definitions and metrics

流水线概览

[Prerequisite: /gpu-container-setup already done by another team]
       │
       ▼
  install-stack   →  Install 5 packages (vLLM, FlagTree, FlagGems, FlagCX, plugin)
       │                scripts: detect_network, collect_env_info, select_flagtree_wheel
       │
       │  GATE: vLLM + plugin must succeed
       ▼
  env-verify      →  Smoke test with Qwen3-0.6B (FlagGems/CX OFF)
       │                scripts: run_offline_inference, test_serve_mode
       │
       │  Verify Layers 0-3
       ▼
  model-verify    →  Target model test (OFF then ON), diff analysis
       │                scripts: run_offline_inference, test_serve_mode, diff_analysis
       │
       │  Determine which stack works (full vs base)
       ▼
  perf-test       →  Accuracy (placeholder) + Performance benchmarks
       │                scripts: run_benchmark, run_all_benchmarks
       ▼
  Final Report

前提条件

运行中的 Docker 容器，且具备：

• 已安装 PyTorch，并可访问 GPU
• 已知容器名称（例如 flagrelease-worker）

此容器由 /gpu-container-setup 创建（由另一个团队维护）。

执行流程

阅读 references/pipeline-state.md，了解完整的状态架构和门控逻辑。

步骤 0：收集初始信息

向用户询问容器名称（或检测正在运行的容器）：

docker ps --format '{{.Names}}' | head -10

确认容器正在运行：

docker inspect --format='{{.State.Status}}' <CONTAINER> | grep -q running

初始化流水线状态（参见 references/pipeline-state.md）。

步骤 1：安装软件栈

阅读并遵循 ../install-stack/SKILL.md。

install-stack 技能将：

1. 将 scripts/collect_env_info.py 复制到容器中 → 获取厂商、Python 和 glibc 信息
2. 将 scripts/detect_network.py 复制到容器中 → 获取镜像配置
3. 按顺序安装 5 个包，并使用 scripts/select_flagtree_wheel.py 安装 FlagTree
4. 在容器内运行 scripts/validate_packages.py → 获取最终状态

门控检查： 如果 gate_passed 为 false（vLLM 或插件安装失败）→ 停止流水线。 报告失败，并提供安装错误。

将结果保存到流水线状态中。

步骤 2：环境验证

阅读并遵循 ../env-verify/SKILL.md。

env-verify 技能将：

1. 下载 Qwen3-0.6B（如果尚未缓存）
2. 将 scripts/run_offline_inference.py 复制到容器中 → 阶段 A
3. 将 scripts/test_serve_mode.py 复制到容器中 → 阶段 B
4. 使用 references/error-classification.md 对错误进行分类

决策： 遇到致命错误时停止。遇到非致命错误时记录并继续。

将结果保存到流水线状态中。

步骤 3：模型验证

阅读并遵循 ../model-verify/SKILL.md。

此步骤为交互式——将询问用户模型路径。

model-verify 技能将：

1. 获取用户提供的模型信息（AskUserQuestion）
2. 对运行 A 和运行 B 重用 run_offline_inference.py 和 test_serve_mode.py
3. 运行 scripts/diff_analysis.py 比较结果
4. 确定 recommended_stack（full/base/none）

决策： 如果 recommended_stack 为 none（运行 A 失败）→ 停止。

将结果保存到流水线状态中（包括 model_path、tp_size、recommended_stack）。

步骤 4：性能测试

阅读并遵循 ../perf-test/SKILL.md。

perf-test 技能将：

1. 使用推荐的软件栈启动 vllm serve
2. 将 scripts/run_all_benchmarks.py 复制到容器中 → 运行 5 种配置
3. 收集指标并生成汇总表

将结果保存到流水线状态中。

步骤 5：最终报告

将流水线状态中的所有结果汇总为最终报告：

{
  "status": "PASS | PARTIAL | FAIL",
  "pipeline": "flagrelease",
  "container": "<name>",
  "vendor": "<vendor>",
  "model": "<path>",
  "tensor_parallel_size": 8,
  "steps": {
    "install_stack": { "status": "...", "packages": {...} },
    "env_verify":    { "status": "...", "phase_a": "...", "phase_b": "..." },
    "model_verify":  { "status": "...", "run_a": "...", "run_b": "...", "recommended_stack": "..." },
    "perf_test":     { "status": "...", "profiles_passed": "5/5", "summary_table": "..." }
  },
  "errors": [...],
  "conclusion": "Pipeline completed. ..."
}

向用户清晰地展示以下摘要：

1. 安装成功或失败的包
2. 基础软件栈是否正常工作
3. 多芯片软件栈是否正常工作（若否，指出失败组件）
4. 性能数据（汇总表）
5. 按层分类的所有错误

总体状态：

• PASS — 所有步骤均通过，多芯片软件栈完整可用
• PARTIAL — 模型可在降级软件栈下运行，或部分性能配置测试失败
• FAIL — 模型无法提供服务（门控失败或运行 A 失败）

设计规则

• 每项操作都有超时时限——不允许卡住
• 捕获每个错误，并准确记录位置（步骤、阶段、层、原因）
• 流水线始终会完成，并生成成功报告或结构化错误报告
• 某个子步骤失败不会导致无关步骤跳过（门控失败除外）
• 直接访问失败时使用网络镜像
• 脚本生成 JSON——结构化、可解析且可跨运行比较