install-stack-flagos

安装多芯片软件栈

按依赖顺序在运行中的 GPU 容器内安装 5 个软件包，并逐个验证并结构化报告错误。

技能组件

install-stack/
├── SKILL.md                           # This file — execution flow
├── scripts/
│   ├── detect_network.py              # Probe GitHub/PyPI, return mirror config (JSON)
│   ├── collect_env_info.py            # Python/glibc/arch/vendor/disk info (JSON)
│   ├── select_flagtree_wheel.py       # Match vendor+python+glibc → wheel specifier (JSON)
│   └── validate_packages.py           # Import-test all 5 packages, report status (JSON)
└── references/
    ├── vendor-mappings.md             # FlagCX make flags, adaptor names, dependency chain
    └── network-mirrors.md             # GitHub/PyPI mirror config rules

前置条件

• 一个可访问 PyTorch 和 GPU 的运行中 Docker 容器（来自 /gpu-container-setup）
• 知道容器名称和GPU 厂商

如果单独调用，请向用户询问容器名称和 GPU 厂商。 如果由 /flagrelease 编排器调用，这些信息会作为上下文传入。

执行流程

步骤 0：解析容器和厂商

验证容器是否正在运行：

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

将 scripts/collect_env_info.py 复制到容器内并运行，以获取厂商、Python 版本、glibc 版本、架构和可用磁盘空间：

docker cp <SKILL_DIR>/scripts/collect_env_info.py <CONTAINER>:/tmp/
docker exec <CONTAINER> python3 /tmp/collect_env_info.py

如果厂商为 unknown 且用户未提供 --vendor，请询问用户。

步骤 1：检测网络环境

将 scripts/detect_network.py 复制到容器内并运行：

docker cp <SKILL_DIR>/scripts/detect_network.py <CONTAINER>:/tmp/
docker exec <CONTAINER> python3 /tmp/detect_network.py

解析 JSON 输出，获取后续所有命令要使用的 GITHUB_PREFIX 和 PIP_INDEX。回退规则见 references/network-mirrors.md。

步骤 2：检查磁盘空间

根据 collect_env_info.py 的输出，确认至少有 10GB 可用空间。如果不足，请警告用户并询问是否继续。

步骤 3：安装软件包（按依赖顺序）

依赖链和安装顺序见 references/vendor-mappings.md： vLLM → FlagTree → FlagGems → FlagCX → vllm-plugin-FL

---

3.1：vLLM 0.13.0

docker exec <CONTAINER> pip install ${PIP_INDEX} vllm==0.13.0

快速验证：

docker exec <CONTAINER> python3 -c "import vllm; assert vllm.__version__ == '0.13.0'"

关卡：如果 vLLM 安装失败 → 记录错误并退出技能。

---

3.2：FlagTree（预编译 wheel）

运行 scripts/select_flagtree_wheel.py 查找匹配的 wheel：

python3 <SKILL_DIR>/scripts/select_flagtree_wheel.py \
    --vendor <VENDOR> --python <PY_VER> --glibc <GLIBC_VER>

如果状态为 FOUND，卸载原版 triton 并安装该 wheel：

docker exec <CONTAINER> bash -c '
python3 -m pip uninstall -y triton
python3 -m pip uninstall -y triton
python3 -m pip install <SPECIFIER> <PIP_ARGS>
'

如果状态为 NOT_FOUND，记录不匹配情况并继续（不要退出）。

---

3.3：FlagGems

docker exec <CONTAINER> bash -c "
cd /tmp && git clone ${GITHUB_PREFIX}/FlagOpen/FlagGems
cd FlagGems && pip install ${PIP_INDEX} -e .
"

失败 → 记录并继续。

---

3.4：FlagCX（两阶段构建）

阅读 references/vendor-mappings.md，查找适用于检测到的厂商的 Make 标志和 FLAGCX_ADAPTOR。

**阶段 1：**构建 C++ 库：

docker exec <CONTAINER> bash -c "
cd /tmp && git clone ${GITHUB_PREFIX}/flagos-ai/FlagCX
cd FlagCX && git submodule update --init --recursive
make <MAKE_FLAG> -j\$(nproc)
"

**阶段 2：**安装 PyTorch 插件：

docker exec <CONTAINER> bash -c "
cd /tmp/FlagCX/plugin/torch
FLAGCX_ADAPTOR=<ADAPTOR> pip install -e . --no-build-isolation
"

失败 → 记录并继续。

---

3.5：vllm-plugin-FL

docker exec <CONTAINER> bash -c "
cd /tmp && git clone ${GITHUB_PREFIX}/flagos-ai/vllm-plugin-FL
cd vllm-plugin-FL
pip install ${PIP_INDEX} -r requirements.txt
pip install --no-build-isolation -e .
"

对于 Iluvatar，如果 requirements.txt 安装失败，请使用 requirements_iluvatar.txt 重试。

关卡：如果 vllm-plugin-FL 安装失败 → 记录错误并退出技能。

---

步骤 4：验证所有软件包

将 scripts/validate_packages.py 复制到容器内并运行：

docker cp <SKILL_DIR>/scripts/validate_packages.py <CONTAINER>:/tmp/
docker exec <CONTAINER> python3 /tmp/validate_packages.py

此操作会生成一份全面的 JSON 报告，涵盖全部 5 个软件包的导入状态、版本和关卡检查结果。

步骤 5：设置运行时环境

如果 FlagCX 安装成功，请持久化 FLAGCX_PATH：

docker exec <CONTAINER> bash -c "echo 'export FLAGCX_PATH=/tmp/FlagCX' >> ~/.bashrc"

步骤 6：生成最终报告

将所有结果合并为结构化输出：

{
  "status": "PASS | PARTIAL | FAIL",
  "stage": "install-stack",
  "container": "<name>",
  "vendor": "<vendor>",
  "network": {"github_mirror": true, "pypi_mirror": true},
  "python_version": "3.11",
  "glibc_version": "2.34",
  "packages": {
    "vllm": {"status": "PASS", "version": "0.13.0"},
    "flagtree": {"status": "PASS", "version": "0.4.1+ascend3.2"},
    "flaggems": {"status": "PASS", "version": "..."},
    "flagcx": {"status": "PASS", "version": "0.10.0"},
    "vllm_plugin_fl": {"status": "PASS", "version": "..."}
  },
  "flagcx_path": "/tmp/FlagCX",
  "gate_passed": true,
  "errors": []
}

状态逻辑：

• PASS — 全部 5 个软件包均已安装并通过验证
• PARTIAL — vLLM 和插件已安装，但 FlagTree/FlagGems/FlagCX 中有部分安装失败
• FAIL — vLLM 或插件安装失败（未通过关卡）

错误处理

失败情况	处理方式
容器未运行	报告错误并退出
网络不可访问（直连和镜像均不可用）	报告并退出
pip 安装失败	报告软件包、完整错误信息并继续（关卡检查除外）
源码构建失败	报告编译器错误并继续
没有匹配的 FlagTree wheel	报告厂商/Python/glibc 不匹配情况并继续
安装后导入失败	报告回溯信息并继续
磁盘空间 < 10GB	警告用户并询问是否继续
超时（任何命令）	所有命令均设置超时；报告超时的步骤

超时规则

操作	超时时间
pip 安装（每个软件包）	300s
git clone	120s
make（FlagCX）	300s
网络探测	5s
验证（导入）	30s