> ## 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.

# 常见问题

> 关于平台设计与使用方式的高频疑问

<AccordionGroup>
  <Accordion title="为什么我不能直接 ray job submit / kubectl / sbatch？">
    集群凭据只在服务端：这换来配额执法、审计、统一观测与可追溯性。平台的代理提交在功能上是超集——你失去的只是绕过配额的能力。
  </Accordion>

  <Accordion title="为什么每次提交都要求 git 干净？">
    每个 run 记录确切 commit + 配置快照 + recipe digest。三个月后复现「当时那个好结果」时，这是唯一可靠的路径。赶时间用 `--allow-dirty`，但请理解代价。
  </Accordion>

  <Accordion title="锁文件（recipe.lock.json）总提示过期，能不能自动升级？">
    不能自动——升级可能改变训练行为（入口、默认值、镜像），必须显式确认。`sf submit --upgrade-recipe` 已经把显式确认压缩到一个 flag 了。
  </Accordion>

  <Accordion title="支持哪些框架版本？会跟进上游新版本吗？">
    看 `sf methods`：每个方法列出已发布版本（如 verl 0.8.0 / 0.9.0）。上游新版本按[采纳 SOP](/zh-Hans/ops/upgrades) 进入 catalog——多数情况只是声明 YAML + 发布镜像，平台代码不动。
  </Accordion>

  <Accordion title="我的自定义框架 / 私有代码怎么跑？">
    `custom/custom` + 加白仓库里的自备镜像，实验里写 `train.sh`。镜像装 Python、框架和依赖，不必装 CLI。catalog custom 是 `external` 观测：提交带 `--observability-url`，要看控制台曲线就在镜像里装 `starforge-core`。细节：[自定义训练](/zh-Hans/guides/custom-training)。
  </Accordion>

  <Accordion title="训练数据放哪里？">
    三选一：HF dataset id（公开/gated 数据）、平台数据集（内部数据，版本化 + 自动分发）、共享盘绝对路径（临时）。推荐前两种——路径引用无法追溯版本。
  </Accordion>

  <Accordion title="GPU 用量怎么计费/统计？">
    每作业记录 gpu\_seconds（占卡时长 × 卡数），控制台用量页与每日报表可查。排队不计费，PENDING 起容器后开始计。
  </Accordion>

  <Accordion title="平台没有 GPU 的环境能开发/测试吗？">
    能。E2E 闭环在无 GPU 机器上可跑（GPU 仿真开关保留全部调度/配额语义），见 [E2E 闭环测试](/zh-Hans/ops/e2e-testing)。
  </Accordion>

  <Accordion title="文档里的控制台截图/入口和我看到的不一样？">
    部分功能按部署配置开关（HF 集成、Playground、插件中心、MCP 写工具）。入口不显示 = 该部署未启用，联系管理员。
  </Accordion>
</AccordionGroup>