data-gen-bpu/docs/extensions.md

224 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 扩展与迁移:接入方式及兼容约定
这一步保留现有 `registry → pipeline/scheduler → rollout → stages → verify → export` 分工。板卡和工具链执行仍属于 harness,runner 只负责进程、会话和原始轨迹适配,裁决仍来自独立 verifier。
`preflight` 按矩阵实际选中的 runner、policy 和工具链 profile 检查依赖。纯 OpenCode 不要求 Pi binary 或无关的 teacher 凭证;Oracle-only 不检查 runner 或 LLM 凭证。显式工具链 profile 按 backend、march、qcfg 校验,并检查对应 Python 文件存在;不会执行模型或编译。OpenCode 的启用、安装和固定版本检查仍是必要前置条件。
现有运行不需要原地升级。先在隔离副本完成验证;新运行使用候选版本。不要把候选版的 Docker 挂载、数据库或恢复命令指向正在运行的原部署。
## 四个扩展入口
| 扩展对象 | 修改入口 | 保留的公共职责 |
| --- | --- | --- |
| 同系列板卡 | `registry/boards.yaml` 的板型映射与独立 slot | target 冻结、调度锁、07/08 身份核验、verifier |
| 工具链版本 | `config.yaml` 的 `toolchains` 与 `toolchain_defaults` | backend 方法实现、阶段调度、证据与准入 |
| Agent 运行器 | `harness/runners/<name>.py`、`MODULES` 与模块的 `JAIL_POLICY` | collector、外部 Worker、预算、独立判定、导出 |
| 任务族 | `harness/eval/<task>.py` 和 `TASK_MODULES` | 输入身份、FP32/量化对照、冻结指标门槛 |
这些入口使用普通模块和函数,不需要继承新的框架。可信内置模型继续通过 `get()` 查找;新任务可显式选择下述任务内配方,不要求增加同名公共 adapter。家族归并要在权重、预处理、导出和指标等价性验证后单独做,不批量删除正在使用的实现。
### 板卡与目标
`bench capabilities --target s600` 只读预览目标、实际 qcfg、工具链以及登记/启用匹配板卡和凭据字段缺项。
资源数量是配置事实,不代表认证成功或实板已验收;`preflight` 同样显示这个区别。
新 run 用 `bench new-run --target s600` 冻结 nash-p;完整 run target 直接传入 job,不经 march 反查丢失身份。
S100/S100P 分别映射 nash-e/nash-m。当前矩阵中 S600 默认 fp16int8、S100P 默认 int8,换板不代表量化条件相同。
新增同系列物理板只需新登记项和从未使用的 slot;不要重排或复用旧 slot。`march` 可以由 `board_type` 推导,双写时必须一致。07 的性能测试和 08 的精度测试共用设备身份检查,在加载 HBM 前验证实际板型和 UCP;S100 不会匹配为 S100P。编译产物保存源路径、HBM SHA256 和工具链快照,阶段元数据携带 target、task_contract 与 model_runtime。
当前调度按 march 分配资源;若把不同板型映射到同一 march,会明确拒绝规划和选板,不能悄悄任选。
需要这一真实场景时再扩展对应资源过滤,新增同型物理板不受该限制。
X5 当前明确拒绝;不同 march、产物格式或 runtime 需要 backend、目标命名校验及板端执行器的实际适配。仅增加 YAML 映射不构成支持。真实编译、推理、精度、断连清理和多板互斥仍是新目标的验收门。本次未接触现网板卡。
### 工具链与模型环境
`BENCH_CONFIG` 指向完整的独立配置文件,不做隐式配置叠加。例如在新安装配置中增加:
```yaml
toolchains:
ptq_verified:
backend: ptq
version: "<实际验证过的版本>"
venv: /opt/toolchains/ptq-verified
marches: [nash-e, nash-m, nash-p]
qcfgs: [int8, fp16int8]
toolchain_defaults:
ptq: ptq_verified
model_runtimes:
resnet18: /opt/models/torch/bin/python
```
示例中的允许组合应按真实验证范围缩小。也可在已有 matrix override 中指定 `toolchain: ptq_verified`;未配置 profile 时保留原来的 `paths.venv[backend]`。同一目标允许不同版本的 profile,backend、march、qcfg 与版本分别校验,不把 march 当作唯一工具链索引。
新 job 保存解析后的路径、版本及安装包 METADATA 摘要,每个阶段检查是否漂移;不匹配时要求新 run。这个摘要不等于编译器二进制、系统库或整个环境镜像的完整摘要。新增 backend 需要真实方法实现,仅增加 profile 名称会被拒绝。模型 Python 可由 `model_runtimes` 配置并冻结;已有 job 继续遵守原 runtime。
profile 解决的是已实现 backend 协议内的环境选择,不是任意编译器 ABI 适配。04 的配置生成和 06 的输出解析仍遵守现有 PTQ/QAT 协议;第二工具链版本必须用真实安装完成这些阶段及板端验收后才能列入支持范围。离线命令中的 Python 路径正确,只证明路由正确。
新 job 用 `cache_contract.version: 1` 明确启用新缓存位置,同时冻结模型 Python 和 exporter 版本。
FP32 缓存身份包括相关 runtime、权重、任务实现、T1、输入及采样条件;ONNX 只包括相关 runtime、
权重、输入和导出条件。不同身份分别存放,命中前仍核对当前约束与元数据;旧无身份缓存不会被贴上新标签。
未带该契约的历史 job 继续使用原位置,读取或重复展开不移动、重建其缓存。PTQ/QAT 模型导出均选用
`model_python(job)`,编译 Python 仍由 backend/profile 负责。
此处路径身份不检测在同一 venv 内原地替换所有包的情况;环境升级应使用新的明确路径和新 run,
完整环境可复现仍需保留版本、安装包及编译产物证据。
### Pi 与 OpenCode
不写 runner 时仍使用 Pi;policy 继续表示 teacher/student。新部署的 matrix 可以在 e2e 配置下写 `runners: [pi, opencode]`,policy 与 k 沿用原结构;同一 job 的各组尝试共用唯一 kk 分配。不要修改已经冻结的 run 计划。
OpenCode 是默认禁用的原型,固定 CLI `1.18.31`。在独立副本按 `agent/opencode/package-lock.json` 执行 `npm ci` 后,配置:
```yaml
runners:
opencode:
enabled: true
bin: /opt/opencode/bin/opencode
```
端点复用 `endpoints.<policy>`;保持 `rollouts.jail: true`。领取前检查启用状态、版本和依赖。每个 attempt 拥有独立 HOME/XDG、配置与 session;禁用自动共享、自动升级和宿主项目配置。外部 Worker 继续执行编译/板端阶段;runner 无权直接写 verdict。预算由插件和外部 watchdog 两处约束,缺 claim 时补 ABSENT。
新增 runner 按现有模块提供检查、命令、环境、收尾及自身原始轨迹解析,并声明 `JAIL_POLICY = "private-home"`。CLI 选项直接来自注册表;隔离按可信模块策略执行,不依赖品牌名。`legacy-pi` 仅保留给 Pi 历史兼容;缺失、非法或与 rollout 冻结身份冲突的策略会拒绝启动。HOME、实际外置 state 和旧 state 都受保护。
不要把 CLI 进度当训练对话。OpenCode 明确保存 session ID,执行 `export ID`,并保存实际 system 与 JSON Schema;缺失、身份不符、未完成消息都不能冒充完整训练样本。
本次已用固定版本真实 CLI、Linux namespace 和仅返回 claim 的本地模拟 HTTP 端点验证:正常会话可完整导出;两轮预算到达后不再发第三次请求,保留 TIMEOUT 和 partial 标记。未调用真实模型、编译器或板卡。这项测试不是生产启用或真实模型质量验收。
### 新任务族
在 `TASK_MODULES` 注册普通模块,提供 `run_fp32(runner, t1, input_spec, out, resize=...)` 和 `run_quant(...)`。需要自己的 G2 输入时提供 `inputs(t1, item, input_spec, model)`,公共入口直接调用;原 cls/det 行为保留。模型特有输入仍可放在 adapter 的 `g2_input`。
同时在现有 datasets、gates、模型表中定义数据、指标和方向,完成 FP32/量化同输入对照、板端输入输出及失败反例验证;涉及新输入形状、时序状态或新运行时的任务还需扩展对应实际实现。当前模型表的 input_spec 校验仍是四维图像形状,不能仅登记名称就声称支持任意任务。
新 job 记录任务协议名和 evaluator 源文件摘要;该摘要不覆盖所有传递依赖,仍需保留 EVALUATOR_VERSION 与环境证据。旧门槛不改,新 job 缺少 SE 策略时明确冻结为零。
新 G3 快照冻结 `direction: higher` 或 `lower`;多指标可按名称写方向 mapping,支持混合方向。
未知新指标必须在任务配置或 matrix override 中声明方向;变更 metric 不会继承另一指标的方向。
旧快照仅按已支持的历史指标表回退,不猜测未知名称。测量指标与新冻结名称冲突时为 UNVERIFIED。
重复展开历史 job 时,等价的历史方向只在比较副本中归一化,原 job 字节及阈值不改。
所有正式判定入口都会核对当前 HBM、06 记录和被采纳的 G3/G4 的 SHA256。缺失或不一致的测量
保留原始记录,但不能让对应必需门通过;可选 G4 不因此变成全局必需门。
旧记录缺 06 摘要时,补测返回 `needs_hbm_revalidation`,须明确重新执行 06 才能继续,不能用今天的
文件摘要补造历史身份。补测沿用原 verifier 和阶段,不另开验收路径。
Docker、依赖挂载、迁移清单与独立验收见 [portability.md](portability.md)。
## 任务身份与计划
`job_id` 继续表示任务、模型、march、backend 和 qcfg 的组合。同一 `(run_id, job_id)` 下,所有 mode、policy、runner 共用一个递增 `kk` 空间。runner 与 teacher/student policy 是两个独立维度。
例如一个 job 同时需要 Pi teacher、Pi student 和 OpenCode teacher 各两次尝试,六条 rollout 的 kk 不重复。重复展开相同计划不会新增尝试,也不会更改已存在的状态。runner 的启用与配置检查发生在领取前;检查失败时保留 QUEUED。
collector 的 dry-run 使用只读数据库连接,不新增 schema、不领取任务,也不申请 Agent 池锁。
原有 `jobs`、`rollouts` 主表不改列或主键。附加 `rollout_context` 保存 runner 和领取进程的 host/pid;旧行缺少这份元数据时,runner 按 `pi` 解释。继续运行的旧程序无需读取此表。
`continuation` 的快照、计划、应用及身份检查均携带 runner。旧回执未记录 runner 时按 Pi 解释;新回执中的 OpenCode 任务不会在交接时改成 Pi。修改源 runner 会使已生成的计划失效,需要重新生成。
## 不可变快照先于领取
`expand` 先在内存构建完整 job 快照,校验整批已有文件,再在 SQLite 写事务内依次发布文件和任务行:
1. 将完整 JSON 写入同目录临时文件,刷新到磁盘,设为只读。
2. 用不覆盖目标的原子链接发布 `job.json`,刷新目录。
3. 最后写入 jobs/rollouts 并提交事务,任务才可领取。
中断留下一份已经发布的快照、却未提交 DB 时,同内容重试可以继续。不同内容会拒绝覆盖。已有 DB 身份缺失 `job.json` 被视为不完整状态,不能静默用当前配置重建历史快照。
已有 job 的 gates、输入集、任务/工具链快照和 rollout 计划保持冻结。选择已有计划的子集可重复展开;增加 runner、修改 k 或改变其他冻结内容,应创建新 run。显式 `coverage=all` 是已有的补采入口,继续通过统一 kk 分配并写 annotation,不能被当作修改快照的方式。
兼容规则只补默认语义,不补造历史证据:
| 旧内容 | 解释 |
| --- | --- |
| plan 或 rollout 未写 runner | Pi |
| 未写 toolchain,当前仍选 legacy-config 且无显式 profile | 保留原 backend→venv 兼容路径 |
| 未写 task_contract,当前仍使用原内置 evaluator 映射 | 可重复展开;不声称旧运行保存过源码指纹 |
| 未写 model_runtime,当前无单独 runtime,或仅把旧 model_spec.runtime_python 等价展开为新字段 | 保留原默认或自定义 runtime;不同 override 仍拒绝 |
| 新工具链 profile、不同快照内容或不同计划 | 拒绝原地覆盖,使用新 run |
## 稳定的数据集刷新
自动刷新和 `materialize(..., refresh=True)` 省略筛选参数时,沿用该数据集 manifest 中的 purpose、policy、版本筛选、最低 reward 和成本默认值。当前 `agent/VERSION` 的变化不会重新定义已有数据集。显式版本筛选或已有固定筛选不依赖当前 VERSION 文件存在。
显式传入筛选参数表示主动修改策略,manifest 的 `filter_history` 记录变更时间、显式字段和变更前后完整筛选。Python API 中显式 `policy=None`、`agent_version=None` 等可以取消相应筛选;省略参数表示沿用。manifest 最后发布,读取者可持有 `.export.lock` 或检查文件哈希。
新数据集的隐式 `agent/VERSION` 下限只作用于 Pi。用户显式指定 `min_agent_version` 时,该筛选作用于所有 runner;不会默默把 Pi 的默认下限用于 OpenCode。旧 manifest 没有 runner scope 时保留其原有全局筛选语义。
OpenCode 的训练消息来自其原始 session 导出,实际 system 分段来自 `raw-system.json`,工具定义来自本次 `tools.json` 快照;导出记录 runner、runner_version、session 身份和 system 来源。缺少真实 system 或工具定义时,不标记为 SFT 候选,也不调用 Pi 重建工具定义。坏 session 身份或不可解析轨迹有明确排除原因。原始轨迹及 verdict 不因导出而修改。
## stale 诊断和显式恢复
默认命令只读诊断,不写 DB、不修改锁、不停止进程:
```bash
bench recover-rollout --run RUN_ID
bench recover-rollout --run RUN_ID --job JOB_ID --kk 0
```
报告列出领取 owner、经过时间、DB stages、handle/队列状态及未完成证据。经过时间只用于诊断,不是进程死亡的证明。其他机器的 PID、缺失 owner、权限不足都属于 unknown。可见存活 owner 或未完成 handle 中的存活 PID 会阻止恢复,即使指定人工确认也不能覆盖。
恢复必须同时给出 `--apply --job --kk --reason`,并指定 `--confirm-work-stopped`,表示操作者已经确认 Agent 子进程、工具链阶段、票据和远端工作全部停止。owner 状态未知时,还必须给 `--confirm-owner-dead`。这些参数是人工确认,不是自动证明。
恢复只处理明确指定的 RUNNING/VERIFYING 行:原行标记 ABANDONED,原 kk、文件和阶段记录保留;另建一个全新 kk 的 QUEUED 行,并写入关联原尝试、原因和诊断的 annotation。不会清空全部 RUNNING,不会复用已执行的 kk,也不会自动杀进程。`reset-stale` 是既有 Oracle 入口,不可代替 rollout 恢复。
## 已验证的范围
可靠性回归使用临时目录及 SQLite fixture,覆盖组合编号、并发展开、中断续发、内容冲突、旧行兼容、runner 领取前拒绝、continuation 身份、稳定导出、原生上下文和显式恢复。测试本身不访问板卡、LLM 或编译工具链。
这些离线测试不能替代真实 runner、隔离环境、工具链及板卡的端到端验收。新增板型、工具链 profile、runner 或 task evaluator,仍需分别记录实际支持范围和证据;配置里出现一个名称不表示已完成该目标验收。
## 任务内模型配方与 ONNX 迭代
公共 adapter 是可复用工具,不是新增模型的必经入口。Agent 可以读取、复制修改已有实现,也可以自行实现。当前正式接入范围仍为 **e2e、PTQ、语义分割、单个静态 float32 NCHW 输入**;模型代码在 CPU 上执行。旧任务与共享缓存路径保持兼容。
平台只固定任务目标、参考身份、评测数据、指标及运行环境。新任务在已有 matrix override 的 `model_recipe.reference` 中记录 `entrypoint`、`files`(路径到 SHA256 的映射)、`weights_sha256`,可选 `input_spec` 和 `preprocess`。参考来源由平台核实;Agent 不能自行改参考或标签。
### 按实际操作提交材料
配方只是提交文件清单,不规定探索顺序。只要求 `schema`、`files`;例如已经有图时:
```json
{"schema":"bench.recipe/1","files":["edited.onnx"],"onnx":"edited.onnx"}
```
所有路径相对 workspace 根,清单本身不列入 files;ONNX 外部张量也须列入。`input_spec` / `preprocess` 省略时采用任务默认值,有变化时写实际声明。
| 操作 | 当时需要的材料 |
| --- | --- |
| 接收现有 ONNX | 图和外部张量,不需要参考源码、权重或先跑 baseline |
| 从代码导出 | `entrypoint` 与实际依赖文件;沿用 `export(weights, input_spec, output_path)` 或 `build(weights, input_spec)`,build 需要权重 |
| 编译 | 03 的图和实际校准输入;数值、layout、归一化配置可以尝试,工具链路径和目标由平台固定 |
| 独立基线 | 完整的平台固定参考代码与匹配权重;已有同参考/环境/数据基线可复用 |
| 正式评测 | 对应 HBM、独立基线和产生完整预测的 `preprocess(image, input_spec)`、可选 `decode(outputs, input_spec)` |
例如先试编译:
```sh
bench stage run export --recipe recipe.json
bench stage wait HANDLE
bench stage run compile --submission HANDLE --config compile.yaml
```
HANDLE 是 export 实际返回的提交标识。后续按需要调用原 `baseline`、`hbm`、`board`、`eval`;`fetch` 不是必经步骤。使用某步结果前等待该步结束。compile 仍自动通过 04 准备配置和校准。03 只检查图结构和已支持的 I/O;图不等价、精度下降不会预先阻止编译,08 与 verifier 独立给出结果。
有前处理代码时,04 用平台固定训练原图生成任务内校准;同一提交再次试编译配置时复用已验证的校准字节。纯图提交可试用平台已有校准:记录 `calibration_mode=platform`、原 manifest 和实际文件摘要,不宣称这些张量符合新的前处理。缺少可用校准时记录失败。
### 冻结提交,继续探索
提交后 workspace 仍可修改;改代码或 ONNX 后再带 `--recipe` 得到新 handle。平台保存独立快照、命令、stdout/stderr、退出状态、超时和实际产物。无效请求也保存在原 Worker 日志里,但不成为已接受的提交。
移除图内后处理、输出节点或辅助分支可以尝试;正式评分仍要求完整任务预测。缺预测头又未恢复输出会评测失败,不影响保留这次图和日志。
产物记录明确的父 attempt。历史 HBM 沿当时的 05→04→03 找图和校准,不随其他阶段重跑而失效;修改历史文件或记录会失效。直接请求某阶段仍取本提交最新尝试,最新失败不会自动回退。新提交不能混用旧 HBM/成绩。
### 隔离与迁移
新配方任务复用现有 private-home jail:workspace、私有 HOME/venv 可试验,公共源码与共享环境只读,其他任务及宿主 HOME 隐藏,公共 adapters 只读可复制。只有实际建立隔离后才撤去限制 `cd`、变量和私有安装的 shell 路径检查;历史 Pi 保留原策略。必要的当前模型端点凭据从环境传入,不复制宿主凭据目录。网络仍供 Agent 使用,不声称具备网络服务或全机资源配额隔离。
正式阶段执行候选 Python 时继续使用更小的 Linux user/mount/PID/network/IPC namespace:只读模型环境与提交输入、独立输出,无板卡凭据、标签或宿主 HOME。参考执行只见固定参考文件,平台从普通数值数组独立评分。运行环境及参考文件仅在一次 Runner 生命周期内复用校验;每次新阶段仍核验。大输出按实际字节分批,512 MiB 数组边界不放宽。
运行环境摘要覆盖解释器及包元数据/RECORD,不等于完整环境镜像摘要;环境变更应建立新版本。现有时间、内存、进程数、文件大小限制保留,尚无独立 cgroup 或总磁盘配额。迁移仍使用现有源码包、Docker 控制面与外置模型/工具链环境;宿主不支持 namespace 时明确失败。真实官方模型、04–08 板端闭环及新机器完整迁移须分别验收,单元测试不能替代。