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

# 给硬件与 RTL 工作打分

> VerilogEval v2、RTLLM v2、RTL-Repo、CVDP —— 编译 Verilog、跑 testbench 判功能

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf bench run my-bench -m run:run-4f2a91 --suites verilogeval-v2
```

RTL 评测和文本评测不是同一类东西。GSM8K 判的是答案对不对；
VerilogEval 判的是**生成的电路能不能编译、能不能通过它的 testbench**。
这需要仿真器，还需要在重复采样上算 pass\@k——是一条完全不同的执行链。

平台为它准备了第三个 runner，`rtl`，与 lm-eval 和 evalscope 并列。
分数落进同一张看板，所以同一个模型的 RTL 分数和 GSM8K 分数在同一行上。

## 可评的基准

| 基准                          | 测什么                                             | 主指标           |
| --------------------------- | ----------------------------------------------- | ------------- |
| `verilogeval-v2`            | 自然语言规格 → Verilog 模块（spec-to-RTL）                | `pass@1`      |
| `verilogeval-v2-completion` | 给模块头补完实现                                        | `pass@1`      |
| `rtllm-v2`                  | 设计级任务（ALU、FIFO、流水线单元…），要求可综合                    | `func_pass`   |
| `rtl-repo`                  | 真实仓库上下文里的补全，测长上下文与工程约定                          | `exact_match` |
| `cvdp`                      | NVIDIA 综合设计题：写、改 bug、补 testbench、读规格（非 agent 轨） | `pass@1`      |

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf bench run my-bench -m run:<RUN_ID> --suites verilogeval-v2,rtllm-v2
```

一次评测只能用一个 runner，所以 RTL 基准与 GSM8K 这类要分成两个作业提交。

<Note>
  **`rtl-repo` 的指标不能和别的比。** 它不跑仿真（没有 testbench），报的是文本相似度；
  把它的 `exact_match` 和 VerilogEval 的 `pass@1` 放在一张表上排名是错的——两者衡量的
  不是同一件事。
</Note>

## 管理员：镜像里要装什么

两样东西。

**仿真器**已经在 `deploy/docker/Dockerfile.evalkit` 里了（`iverilog` + `verilator`）。

**harness 要你自己装。** VerilogEval、RTLLM、CVDP 各自带着题库与 testbench（各自的 GitHub 仓库）。平台**不复制**它们的题目——上游改题时那份副本就成了另一个基准，而分数还挂着原来的名字。所以平台只定契约：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
$FORGE_RTL_HARNESS --benchmark <名字> --model <路径> --output-dir <目录> \
                   [--samples N] [--limit N]
```

harness 写出 `<目录>/rtl_report.json`：

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{"results": {"verilogeval-v2-spec": {"pass@1": 0.42, "syntax_pass": 0.90}}}
```

Dockerfile 里有装法示例（注释掉的）。**把上游 commit 钉死**——评测结论要跨月可比，题库浮动一次，之前所有分数就都不能拿来对照了。

没装 harness 时作业会以一句明确的错误失败（「未产出 rtl\_report.json；确认镜像里装了 harness」），而不是产出一份空报告。

## CVDP 的 agent 轨：能接，但不是这条路

CVDP 有两条轨。**非 agent 轨**就是上面那样：一次生成、判功能，走 `rtl` runner。

**agent 轨**要求模型在解题过程中反复调工具（读文件、跑仿真、看波形、改代码再试）。它有两个特点决定了接法不同：

1. **它要起容器。** 官方 harness 为每道题拉一个 Docker 容器做隔离沙箱。而平台的评测作业**本身就跑在容器里**——在 KubeRay 或 Slurm 上做 Docker-in-Docker 需要特权容器或 sysbox，多数内网集群不给，也不该给。
2. **它要一个能调的模型端点**，而不是一个权重路径。

第二点平台正好有现成的：[模型部署](/zh-Hans/guides/model-registry)给出稳定的内网地址与可撤销的 token。所以 agent 轨的正确形态是：

<Steps>
  <Step title="先部署">
    把要评的版本部署成一个 Model Deployment，拿到端点与 token。
  </Step>

  <Step title="在有 Docker 的机器上跑 harness">
    CVDP harness 指向那个端点。这台机器要能起容器——通常是一台专门的评测机，
    而不是训练集群的节点。
  </Step>

  <Step title="分数回灌平台">
    harness 产出的报告按上面的 `rtl_report.json` 契约上报，进同一张看板。
  </Step>
</Steps>

也就是说：**agent 轨的评测不该是一个训练作业**，它是一个外部流程 + 一次分数回灌。硬把它塞进作业调度里，换来的是一个需要特权容器的评测链路——那个代价比它省下的编排工作大得多。

### 具体怎么跑

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 1. 平台侧开一次外部评测，拿回 run_id 与只能上报分数的 token
sf bench external create --model alice/qa@v3 --harness cvdp --train-run <TRAIN_RUN_ID>

# 2. 评测机上（要有 Docker）：把平台的部署端点转发给 agent 容器
export OPENAI_BASE_URL=https://<console>/api/inference/<deployment-id>/v1
export OPENAI_API_KEY=<deployment token>
export CVDP_AGENT_ENV=OPENAI_BASE_URL,OPENAI_API_KEY
./run_benchmark.py -f <dataset> -l -g <你的 agent 镜像> -p work/

# 3. 分数回灌（也可以在评测机上用 token 直接打 /api/ingest/benchmark）
sf bench external submit <RUN_ID> -f scores.json --harness cvdp
```

`--train-run` 不是可选装饰：给了它，这次外部分数才会被门禁与模型注册表认到那次训练头上；不给，它只是一个孤立的数字。

<Note>
  **入口只收结构化分数，不解析 harness 的报告文本。** CVDP 产出的是 `report.txt`
  与 `composite_report.txt`（文本，不是 JSON）。那段转换放在你自己的脚本里——
  上游改一行格式，你改脚本；而平台的入口不用动。反过来做的话，上游每次调整格式
  都会让回灌链路挂掉。
</Note>

<Note>
  token 的权限只有「上报分数」（scope=benchmark）。它会被贴进评测机的环境变量，
  不该顺带能写日志、改作业状态、传产物。
</Note>