> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

> 装上 CLI、提交一个 GRPO 作业，看着第一个点落在 loss 曲线上。

十五分钟，从零到一次能看着跑的训练。下面这条路径是确定的：照抄就能跑通。

## 开始之前

<ParamField path="一个账号" type="必需">
  由管理员创建，或者你的部署接了单点登录。你还需要控制台地址。
</ParamField>

<ParamField path="配额和一个硬件 profile" type="必需">
  登录后 `sf status` 会把两者都打印出来。本站里所有 profile 名字——`h200:8` 之类——都是示意；
  请用你自己 `sf status` 打印出来的那些。
</ParamField>

<ParamField path="集群能拉到模型权重" type="必需">
  脚手架训的是 `Qwen/Qwen2.5-1.5B`，作业启动时从 Hugging Face 拉。
  内网环境下由管理员把部署指向内部镜像，见[离线内网部署](/zh-Hans/ops/airgapped)。
  没配的话，作业会启动、卡在下载权重，最后超时。
</ParamField>

<ParamField path="对象存储" type="可选">
  只有 `sf dataset push` 和「训练后自动评测」需要它。这条路径没有它也能走通。
</ParamField>

<Steps>
  <Step title="装 CLI 并创建项目">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    uv tool install starforge-core     # 或：pip install starforge-core
    sf init my-lab --yes
    cd my-lab
    ```

    不要 clone 平台仓库——创建项目的是 `sf init`。它在磁盘上放了什么见 [`sf init`](/zh-Hans/cli/init)。
    之后用 [`sf update`](/zh-Hans/cli/update) 升级，不要手工重装。
  </Step>

  <Step title="登录">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    sf login --server https://starforge.your-company.com
    ```

    会打开浏览器。SSH 会话加 `--device-flow`；CI 里用 `--token`。凭据存在 `~/.forge/`。

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    sf status
    ```

    打印你的账号、配额，以及这套部署真正拥有的 profile 名。记下来——下一步要用。

    <Frame caption="控制台登录页。用户名密码，或者部署接了单点登录时用 SSO。">
      <img src="https://mintcdn.com/starforge/GatXR2rI5-_Vm4_H/images/console/login.png?fit=max&auto=format&n=GatXR2rI5-_Vm4_H&q=85&s=2306521111801b18e089d0ddd58a6667" alt="StarForge 控制台登录页" width="2160" height="1350" data-path="images/console/login.png" />
    </Frame>
  </Step>

  <Step title="创建实验">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    sf new my-grpo --method nemo-rl/grpo
    ```

    生成 `experiments/my-grpo/`，里面有 `config.yaml`、`README.md` 和 `recipe.lock.json`。

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    sf methods                 # 这套部署提供的全部方法
    sf methods nemo-rl/grpo    # 能调什么，带取值范围和默认值
    ```
  </Step>

  <Step title="调参并校验">
    改 `experiments/my-grpo/config.yaml`。最常改的几个键——学习率、batch size、序列长度——
    都放在脚手架的最上面。

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    sf validate my-grpo
    ```

    按方法声明检查类型、取值范围和 batch size 整除关系。拼错的参数在这里几秒内就失败，
    而不是排完队之后。
  </Step>

  <Step title="提交">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    git add -A && git commit -m "first grpo run"
    sf submit my-grpo --profile h200:8
    ```

    会打印一个作业 id。`--profile` 是唯一的资源参数：`h200` 用注册表的默认形状，
    `h200:4` 要四张卡，`h200:16` 要两个满节点。

    工作树不干净会被拒绝，除非加 `--allow-dirty`——这样结果才追溯得到确切的 commit。

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    sf job logs        # 不带 id 就跟最新那个作业
    ```

    状态依次是 `QUEUED` → `SUBMITTED` → `PENDING` → `RUNNING`。
    QUEUED 表示已准入但还没上集群，见[作业状态](/zh-Hans/concepts/job-lifecycle)。
  </Step>

  <Step title="在控制台里看">
    打开控制台，进 **Jobs**，点开你那个作业。

    | 页签          | 显示什么                     |
    | ----------- | ------------------------ |
    | Charts      | loss、reward、KL、梯度范数，逐步展示 |
    | Logs        | 完整日志流，可搜索、可下载            |
    | Validation  | 样本对话和 reward 直方图         |
    | System      | GPU 利用率、显存、网络            |
    | Diagnostics | 失败或曲线异常时，一份报告加几个值得试的旋钮   |

    <Frame caption="GRPO 训练过程中的曲线页：reward、accuracy 和训练标量。">
      <img src="https://mintcdn.com/starforge/GatXR2rI5-_Vm4_H/images/console/job-charts.png?fit=max&auto=format&n=GatXR2rI5-_Vm4_H&q=85&s=f0cbc511c02bb6a4b59b74c5575899ce" alt="StarForge 作业曲线页" width="2160" height="1350" data-path="images/console/job-charts.png" />
    </Frame>
  </Step>
</Steps>

## 确认成功

按顺序对照下面几项。有一项对不上就停在那里——后面每一步都假设前一步真的成功了。

| 什么时候           | 应该看到                              | 对不上怎么办                                             |
| -------------- | --------------------------------- | -------------------------------------------------- |
| `sf status` 之后 | 你的用户名、配额，以及至少一个 profile 名         | 登录没走完，或者还没给你配额                                     |
| `sf submit` 之后 | 一个作业 id，状态 `QUEUED` 或 `SUBMITTED` | 被拒时错误里会点名是哪道闸，见[错误](/zh-Hans/api-reference/errors) |
| 1–3 分钟         | 状态变成 `RUNNING`                    | 一直 `QUEUED`：作业页会说明是哪道闸拦着                           |
| 3–8 分钟         | 日志里出现权重下载，然后 Ray 启动               | 卡在下载：镜像的问题，见[离线内网](/zh-Hans/ops/airgapped)         |
| 8–15 分钟        | **Charts 页上第一个数据点**               | 日志在滚但曲线是空的：ingest 问题，见下                            |

第一个点出现了，这条路径就走通了。

如果日志显示在训练而曲线一直是空的，说明回传调用没有发生。catalog 方法的话这是 ingest 配置问题；
自己的训练器的话，通常是 `starforge.report` 根本没被调用。见 [回传](/zh-Hans/api-reference/python-sdk)。

## 下一步

<Columns cols={2}>
  <Card title="提交的完整用法" icon="send" href="/zh-Hans/guides/submit" arrow="true">
    提交路径上的每一个参数：资源、覆盖、数据、镜像、后续动作。
  </Card>

  <Card title="用自己的训练器" icon="wrench" href="/zh-Hans/guides/custom-training" arrow="true">
    catalog 里没有你要的方法时怎么办。
  </Card>

  <Card title="Sweep" icon="grid-3x3" href="/zh-Hans/guides/sweep" arrow="true">
    一条命令，多个变体，在控制台里成组展示。
  </Card>

  <Card title="评测" icon="gauge" href="/zh-Hans/guides/benchmarks" arrow="true">
    用 GSM8K、MMLU、C-Eval 等给这次 run 打分。
  </Card>
</Columns>