StarForge 各部分怎么拼在一起

CLI → 控制平面 → 执行器 → Job Capsule。一份 JobSpec 契约。

StarForge 是四层，中间一份契约（JobSpec + recipe catalog）。加一种方法、换一个集群后端，不应该逼着别的层一起改。

​

各层

层	位置	职责
CLI	core/starforge/cli/，包 starforge-core	实验、本地校验、打包、JobSpec。不碰集群凭据。
控制平面	server/，包 starforge-console	鉴权、配额、catalog 握手、出队、执行器投放、ingest、UI
执行器	server/executors/	把 LaunchRequest 变成 docker run / agent HTTP / RayJob / slurmrestd。看状态、回收资源。
训练运行时	服务端注入的 Job Capsule	bootstrap.sh 校验 manifest，再用镜像自带的 Python 跑 runner.pex。训练镜像不预装平台包。

​

提交路径

1. 客户端组 JobSpec

   sf submit 读实验目录和 recipe.lock.json，按硬件注册表展开 --profile，校验超参，按清单打包工作区（含 git 溯源）。

2. 服务端准入

   catalog 握手（方法和框架版本必须已发布）、配额、镜像 allowlist、HuggingFace 预检。任一不过就拒绝提交。

3. 排队和装配

   作业停在 QUEUED，调度器出队。装配把 JobSpec + 服务端配置收成 LaunchRequest，注入 capsule.json、bootstrap.sh 和内容寻址的 runner.pex。

4. 执行器投放

   local：docker run，GPU 分配和起容器同一把锁。agent：HTTP 打到节点上的 forgelet。kuberay：RayJob CR。slurm：slurmrestd 申请 allocation，再 srun + Ray（多池走 hetjob）。

5. 容器启动

   入口是 bash .starforge/capsule/bootstrap.sh → python runner.pex run。runner 校验文件摘要和 Python/框架能力，按 recipe adapter 选入口，上报 lifecycle。

6. 回传

   stdout 进日志页。曲线走 starforge.report（目录方法已接好；custom 要自己调）。失败可以触发诊断。

​

日常会碰到的设计选择

密钥只在服务端

集群地址、HF token、对象存储钥匙在控制平面。客户端只有个人 access token。训练容器拿到的是按 run 签发、收窄 scope 的 ingest token。

不静默回退

平台不猜框架、不猜入口。方法必须在 catalog 里发布。custom 必须声明 train.sh 和镜像。锁文件和 catalog 对不上就拒提交——用 sf recipe upgrade 升级。

换执行器，不换作业语义

装配产出与后端无关的 LaunchRequest。执行器实现 launch / observe / stop / cleanup。用哪一个，取决于作业被放到的 Fleet 的 kind。配错了不会偷偷落到另一个后端。

提交可追溯

每次 run 记下 git commit、配置快照、recipe digest、runner/capsule digest、镜像 digest。脏工作区默认拒提交，除非 --allow-dirty。

​

作业状态

台账状态（不是 Docker / Ray / Slurm 的原生状态）：

QUEUED 还没上集群。PAUSED 已经还卡、留着 checkpoint。自动重试和维护排空走同一条暂停/恢复路径。

​

下一步

Recipe

catalog、锁文件、框架版本矩阵

资源

profile、配额、时段、多池