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

# 注册并推广模型

> 跨 run 的命名版本线：哪个模型在生产、上一版是哪次训练出的

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf model register alice/support-agent --run run-4f2a91 --notes "kl 0.01, 500 steps"
sf model promote alice/support-agent@3
sf model ls
```

run id 是关于某次实验的事实。模型版本是一个决定——**这一个**是我们愿意拿去服务的。
注册就是把前者变成后者。

没有它，「现在生产上跑的是哪个模型」和「上一个版本是哪次 run 产出的、谁在什么时候推广的」
这两个问题，只有还记得某个 run id 的人答得出来。
注册表把「我跑了 300 个作业」变成「我们有 5 个在用的模型」。

## 三个概念的分工

一个平台里同时有三种「版本」，各管各的：

| 概念               | 挂在哪    | 回答什么                 |
| ---------------- | ------ | -------------------- |
| 产物 `artifacts`   | 一次 run | 这次训练产出了什么            |
| **模型版本**（本页）     | 一个命名模型 | 我们有哪几个在用的模型，各自现在是哪一版 |
| 部署修订 `revisions` | 一个部署   | 线上这个服务现在跑的是什么配置      |

灰度与回滚在**部署修订**那一层，注册表不重复一套——两处都能表达「哪个在跑」会立刻分叉。

## 用起来

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 训练 → 导出 → 登记成模型的新版本（版本号自增，不用起名字）
sf export <RUN_ID>
sf model register qa-assistant --run <RUN_ID> --notes "换了数据配比"

# 看版本线
sf model ls                    # 所有模型，各自现在跑哪一版
sf model ls alice/qa-assistant # 这个模型的完整版本线

# 上线 / 下线
sf model promote alice/qa-assistant 3
sf model archive alice/qa-assistant 2
```

基座模型和外部权重也能登记，否则版本线上会缺第一格：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf model register qa-assistant --path /shared/models/qwen-base --notes "基座"
```

## 部署跟着注册表走

模型部署选「模型注册表」作为来源，**版本留空即跟随当前 production**：

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{ "kind": "model", "model": "alice/qa-assistant" }
```

之后换模型只需 `sf model promote`，不用改部署配置——部署不必知道它背后是哪次训练。要钉死某一版就显式写 `"version": 3`。

## 与评测门禁的关系

注册一个版本要求那次训练**通过了评测门禁**（声明了门禁的话）。注册表是资产目录，把一个明确不达标的产物登记成资产，等于让门禁白判一次。管理员可以越过（写审计）。

版本线上每一版都带着它那次训练的评测结论——版本线上的数字没有评测就只是路径。

<Note>
  **版本不可变**：一个版本钉住了 run id 与权重路径。要换权重就注册新版本。
  一个被部署引用过的版本若能改内容，「现在线上跑的是哪一版」就不再是可回答的问题。

  **同一时刻只有一个 production**：提升新版本会把旧的自动归档。两个都标 production
  之后，这张表存在的理由就没了。
</Note>