Skip to content

README_CN.md

Latest commit

 

History

History
123 lines (89 loc) · 5.01 KB

README_CN.md

File metadata and controls

123 lines (89 loc) · 5.01 KB
Raw

oh-my-gpustack

GPUStack v2 的环境预检工具—— 把 GPUStack 自己要到很晚才会报错的环境问题提前找出来。

English | 简体中文

GPUStack 本身一条 docker run 就能装好。难的是它脚下的地基：驱动版本恰好比要求低两个 CUDA 版本、容器工具包装了却没注册到 docker daemon、5432 端口早被本机的 Postgres 占了、 worker 一直连不上而原因只是这台机器跑的是 Docker Desktop。

oh-my-gpustack 就是这一层的体检工具。

$ omg doctor --role worker

── operating system
  · Ubuntu 24.04  (amd64)
  ✔ architecture amd64 is supported
  ✔ Linux — supported for worker nodes

── accelerator
  · NVIDIA GeForce RTX 4090  ×2
  ✘ NVIDIA driver 535.183.01 is too old
      GPUStack v2 needs a driver supporting CUDA 12.8+ (>= 570.26).

安装

除了 bash、awk、curl 之外没有任何依赖。

git clone https://github.com/zxcrf/oh-my-gpustack.git
cd oh-my-gpustack
./omg doctor

检查哪些东西

每一项都对应 GPUStack 官方 安装要求文档里的明文规定， 不是经验之谈。

检查项 能抓到的问题
操作系统与角色 拿 macOS / Windows 当 worker（不支持）；WSL2 的注意事项
容器运行时 没装 docker、daemon 连不上、worker 上用了 Docker Desktop
加速卡 驱动低于 CUDA 12.8 / ROCm 7.0；容器工具包没注册到 daemon
时间同步 缺少 NTP 或未同步——GPUStack 明确要求各节点时钟一致
端口 官方文档里全部 21 个 server / worker / 网关端口
磁盘 docker 数据目录的剩余空间（模型权重实际落在这里，不是 $HOME）
网络 Docker Hub 与 quay.io 镜像源、Hugging Face 与 ModelScope 的可达性

doctor 不会改动系统。install 默认只打印将要执行的命令，加 --yes 才真正执行。

角色决定成败

GPUStack v2 对两种角色的要求差别很大，同一台机器很可能"作 server 合格、作 worker 不合格"：

omg doctor --role server   # 任何装了 Docker 的系统，不需要 GPU
omg doctor --role worker   # 仅限 Linux，需要真驱动 + 真容器工具包

这一点搞错是最容易浪费一下午的地方：Mac 或 Docker Desktop 主机完全可以跑 GPUStack server，但根本不能作 worker。

示例配置（实验性）

仓库里次要的、且坦白说并不完整的一部分。recipes/ 用一种很小的 YAML 格式存放部署配置， render 会按 GPUStack UI 表单字段的顺序打印出来，你照着抄就行，不用自己翻译。

$ omg recipe list
$ omg recipe render nvidia/qwen3-8b-single-rtx4090

unverified 这个状态请按字面理解。 这里每一份配置都是根据模型大小、显存容量和推理 后端的文档行为推算出来的，一份都没有真的跑过。它们能帮你省掉一些算术，但不是实测 数据，也完全可能是错的。

最初的设想是攒一个"有人真的跑过并记录下来"的配置库。那需要维护者没有的硬件，所以配方只有 在贡献者真的跑过并报回实际数字时才会变成 verified——CI 会拒绝没有数据却声称已验证的提交。 这个库最终能不能成型是个开放问题，ROADMAP.md 里对成功概率写得很直白。

如果你手上有 GPU、能腾出 45 分钟， 验证类 issue 里写明了要跑哪些命令、要贴回什么。字段规范见 docs/recipe-format.md，提交方式见 CONTRIBUTING.md。

命令

omg doctor [--role server|worker|both]   跑全部预检，只读
omg install server [--port N] [--yes]    打印/执行 server 容器命令
omg install worker --server-url U --token T [--advertise-address IP] [--yes]
omg ports                                完整端口清单
omg recipe list | show <id> | render <id>

边界

这是 GPUStack 的配套工具，不是它的分支，也不是对它 API 的封装。它不管理集群、不替你部署 模型、不保存任何状态——这些 GPUStack 自己的 UI 和 API 做得很好，重复实现只会多出一个需要 同步维护的东西。

预检工具是现在真正能用、值得你花时间的部分。 配置库是一个可能达不到临界规模的实验—— 原因和"需要什么才能改变"都写在 ROADMAP.md 里。

当前对齐 GPUStack v2.2.x。所有与版本相关的事实（端口、驱动下限、平台支持）都在源码里 标注了出处，方便上游变动时复核。

许可

MIT，见 LICENSE。

本项目与 GPUStack 官方无隶属关系。GPUStack 使用 Apache-2.0 许可。