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

# Rubric

> 把「你的团队认为什么算正确答案」写下来，然后同时用作 reward 和评测标准。

rubric 是你团队关于「什么算正确答案」的成文标准：命名的评分维度、它们的权重，以及一个量表。
它有主人、有版本，引用形式为 `<owner>/<name>`。

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl -X PUT https://starforge.your-company.com/api/rubrics/alice/answer-quality \
  -H "Authorization: Bearer $SF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Scoring customer-support answers.",
    "visibility": "private",
    "scale_min": 0,
    "scale_max": 5,
    "criteria": [
      {"name": "Factually correct", "weight": 3.0,
       "description": "Every claim about the product is true and current."},
      {"name": "Answers the question asked", "weight": 2.0,
       "description": "Addresses the customer'\''s actual problem, not an adjacent one."},
      {"name": "Cites the handbook", "weight": 1.0,
       "description": "Points to the section a human could check."}
    ]
  }'
```

控制台的 Rubrics 页用表单做同样的事。两者随便用——多数人在控制台起草，用 API 做版本管理。

## 结构

<ParamField path="criteria" type="array" required>
  每一条是 `{"name": string, "weight": number, "description": string}`。

  `description` 要写成给一位细心读者的指令，而不是一个标签。
  「产品相关的每一条陈述都真实且是当前的」告诉裁判该看什么；「准确性」不告诉。
</ParamField>

<ParamField path="scale_min / scale_max" type="number">
  每个维度的打分区间。`0`–`5` 是常见选择；`0`–`1` 会让加权总分读起来就是一个比例。
</ParamField>

<ParamField path="visibility" type="private | public" default="private">
  `private`：主人和管理员可读。`public`：所有人可读，写仍然只归主人。
</ParamField>

<ParamField path="description" type="string">
  这份 rubric 是干什么的。列表里会显示，值得认真写——
  一份名字含糊又没有描述的 rubric，就是半年后被别人复制一份的那一份。
</ParamField>

## 一份 rubric 用在哪

同一份 rubric 服务三个地方，这也正是它是一个对象、而不是复制粘贴进两份配置的提示词的原因：

| 用作        | 怎么用                                                                         | 产出                  |
| --------- | --------------------------------------------------------------------------- | ------------------- |
| 训练 reward | [环境 verifier](/zh-Hans/extend/verifiers) 的 `kind: rubric`                   | 每次 rollout 的 reward |
| 评测基准      | [benchmark 包](/zh-Hans/extend/benchmark-packs) 的 `runner: judge` + `rubric` | 看板上的一个分数            |
| 安全评测      | `runner: safety` 的包                                                         | 该拒的有没有拒             |

因为它是同一个对象，模型据以训练的标准和据以打分的标准不会悄悄分家。

## 版本

每次编辑版本号加一，旧版本的全文会被保留。

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl -H "Authorization: Bearer $SF_TOKEN" \
  https://starforge.your-company.com/api/rubrics/alice/answer-quality/revisions
```

这件事比听起来重要。`rubrics` 表只存当前版本，每次编辑都覆盖它的 criteria——
那会让「版本化」这个词对版本号成立、对内容不成立。
一次按 v2 打过分的 run，在 rubric 走到 v5 之后就再也说不出 v2 当时到底写了什么。
保留修订全文，是「版本计数器」和「可审计资产」之间的差别。

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl -H "Authorization: Bearer $SF_TOKEN" \
  https://starforge.your-company.com/api/rubrics/alice/answer-quality/usage
```

列出哪些 run 引用了哪个版本，以及是作为训练 reward 还是作为评测分数。

<Note>
  编辑 rubric 会让裁判对它的分数缓存失效——缓存键带着 owner 和版本。
  磨细一个维度不会让旧分数悄悄留在原地。
</Note>

## 为什么 rubric 要有主人

<Accordion title="全局唯一的名字会把每份 rubric 冻结在第一版">
  什么算正确答案，是每个团队的判断，不是平台的判断。如果 rubric 名字是全局的、
  写入还需要管理员，那么一个想把某条维度改精确一点的研究员就得走流程——
  于是他不会走，rubric 停在第一版。

  一份停在第一版的 rubric，会被训练和评测双双绕开，各自写一份自己的打分逻辑——
  而这恰恰是这个对象存在要防的那种分家。所以所有权沿用数据集那一套：
  主人持有写权限，可见性决定还有谁能读。
</Accordion>

## 怎么写出一份管用的 rubric

* **维度少而边界清楚。** 三条描述清晰的维度胜过八条互相重叠的。
  让裁判分别给「清晰度」和「可读性」打分，你会得到同一个数的两份拷贝。
* **按你真正愿意做的取舍来定权重。** 如果一个事实错误但文笔优美的回答一文不值，
  事实那一条的权重就要能说明这一点。
* **描述失败，而不只是描述成功。** 「不编造不存在的产品功能」比「准确」更容易被稳定地执行。
* **有意识地升版本。** 一次只磨一条维度，这样使用记录才能告诉你是哪次改动挪动了分数。

## 确认成功

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl -H "Authorization: Bearer $SF_TOKEN" \
  "https://starforge.your-company.com/api/rubrics/resolve?ref=alice/answer-quality"
```

按作业的方式解析这个引用。它能答，环境或 benchmark 包就能引用它。