data-gen-ebd/docs/architecture.md
amos b773033658 Record model requests and payloads as prefix deltas in the native trace
Each model_request/model_payload repeated the full context, so the trace
grew with the square of the request count: batch 6 Qwen runs hit 64 MiB
at ~75 requests and 14 attempts (13 graded PASS) were discarded.
Requests now record only items after the common prefix with the previous
one (schema embedded-rollout.pi/2), and pi_run.expand rebuilds full
payloads before the unchanged broker/feedback checks. Needs a new image
(trace6) and recalibration before use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 10:50:56 +08:00

89 lines
13 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.

# Rollout 架构与验收
本阶段提供一个任务、`doctor / calibrate / run` 三个 Python 3.9+ 标准库入口、管理 Pi 闭环的 `rollout.pi_run` controller,以及已有 Pi SDK 的原生 adapter。当前只做真实 rollout 采集,不实现模型训练。完整扩量设计见 [rollout-plan.md](rollout-plan.md)。
机器分工、当前与建议部署图、镜像和轨迹位置见 [deployment.md](deployment.md)。任务作者的交付与准入标准见 [task-authoring.md](task-authoring.md),可复制的任务设计表见 [templates/task-spec.md](templates/task-spec.md)。
## 任务包
```text
task.json 身份、候选文件、校准样例、私有评分附件与执行期限
prompt.md Agent 可见的需求
template/ 缺陷初态:完整工作区,全部文件复制给 Agent
gold/ 可信正确样例,只含 candidate_files
noop/ 无功能样例
cheat/ 伪造或绕过需求的样例;可另加其他样例目录
verify.py 正式行为验收器;grader_files 列出的私有附件同权限进入 /grader
dataset.json 可选的 argv 参考快照,见 data-format.md
```
`candidate_files` 是 1–16 个不重复的安全相对路径,必须同时存在于 template 和每个非 template 样例目录;Agent 结束后只冻结这些文件,评分容器也只挂载它们。template 内最多 64 个常规文件,全部进入工作区,其余文件和 Agent 新建文件不属于正式候选。`fixtures` 可选,键为样例目录名、值为预期 `PASS`/`FAIL`;省略时为 gold/template/noop/cheat 四类,自定义时仍必须含这四类及原预期,可增加多个作弊样例或合法替代解,最多 12 类。`grader_files` 可选,列出任务根目录下与 verify.py 一起以 0600 复制到 `/grader` 的私有文件。task 摘要覆盖 template、全部样例、verify.py 与私有附件。
首题是 C frame-decoder 修复。实际协议与断言以题面和 verifier 为准;它验证软件解析与错误恢复,不证明串口电气或实板通信。样例用于校准验收器,不能作为唯一正确补丁标准。Bos-qiao 导入任务沿用原 `final_targets`、判据与对照样例,见 [task-authoring.md](task-authoring.md)。
## 执行边界
```mermaid
flowchart LR
T[冻结任务] --> W[新候选工作区]
W --> A[Docker Pi Agent 容器]
A <--> P[host 私有模型代理]
P <--> M[GLM-5.3 Chat Completions]
A --> S[冻结最终候选]
S --> V[新无网评分容器]
V --> R[receipt 与证据]
A --> E[原生模型/工具事件与监督日志]
E --> R
```
控制端持有任务包、正式测试和参考样例;Agent 容器只有候选工作区与只读题面。正式 Agent 镜像不能包含 grader/gold。评分容器挂载只读候选;正式 verifier 另受保护,候选进程不能读取它的测试和预期结果。候选代码也属于不可信执行内容,单纯把 grader 与候选放进同容器、同 UID 并不足以隔离。
Docker grade 使用 `--user 0:0`,私有 grader 目录0700、verify 文件0600;全部 capabilities 默认移除,仅 grader 容器增加 SETUID/SETGID/DAC_OVERRIDE/CHOWN。grader 使用 `python3 -I`,编译器与候选降 UID/GID 65534 并清除补充组。运行前主动验证该身份读取 `/grader/verify.py` 触发 PermissionError,否则 UNVERIFIED。可信 host 样例不降权。
Bos 导入题的 [verify.py](../rollout/bos_verify.py) 以 root 原样运行原 check.py:grader 副本归 root、目录 0700,临时根目录 0711,只有候选副本 `work/` 交给 UID 65534。包装器让 check.py 经 `subprocess.Popen` 启动的每个子进程降为 UID/GID 65534 并清除补充组;`tempfile.mkdtemp` 新建的目录改归 65534,供子进程编译和运行候选。子进程与 check 进程 UID 不同,读不到 grader 副本,也读不到 `/proc/<check>/cwd`、内存与环境。check 进程装有 audit hook:执行来自候选或这些临时目录的代码、从中导入或加载动态库,以及隔离模式下绕过 Popen 的 `os.system/exec/spawn/fork/posix_spawn`,都以 UNVERIFIED 结束,因此候选代码不会以 root 运行。隐藏测试与候选同进程的判据(tests.py 型及在候选进程内断言的探针)靠 UID 无法隔离:任务带私有 `isolation-blocked.txt`,verify 直接返回 UNVERIFIED,校准不能 PASS,须重写判据并升版本后再准入;导入器遇到根目录有 check.py 以外的 `*.py` 时自动加此标记。剩余限制:root 身份的 check 仍会跟随候选在共享临时目录里放的符号链接。36 Docker 29.5.2 上已完成正式镜像 20 次正负例校准并 PASS;原件与清理详情见 [acceptance.md](acceptance.md)。
`doctor` 显示 Python 版本并检查 Docker 命令/daemon,不验证镜像或 C 编译器。`calibrate` 分别验任务声明的每类样例(默认 gold/template/noop/cheat),各在新工作区重复五次;可信 host 后端只供维护本仓库样例,实际调用编译器和候选程序。`run` 将已有 Agent 的 argv 放进 Docker,再对最终 `candidate_files` 独立评分。缺 Docker 时不能退回 host 执行 Agent。
`run --calibration` 接收校准 attempt 目录,必须校验同 task/verifier/image 身份、Docker 后端、每类样例五次的完整试验(默认 20 次)及整体 PASS。缺 C 编译器的可信校准记 UNVERIFIED,不能把环境缺失当任务失败。
Pi 工作容器固定 2 GiB、1 CPU,`--agent-timeout` 默认 900 秒,独立于评分期限;评分容器固定 512 MiB、1 CPU,首题 `timeout_seconds=60` 用于每次 grade;verifier 单例 5 秒、编译 30 秒,留出主机负载余量,避免正确解因超时被判 FAIL。用户当前不设费用或模型轮数上限,执行超时防止挂死,不能记作费用预算。扩量前按真实耗时、峰值与轨迹体积测容量。
磁盘:输出盘(36 为多人共享的 `/home`)剩余低于 30 GiB(用户 2026-10-17 由 50 GiB 调低)时不启动任何容器,记 `termination=disk_low`。Agent 运行中每 2 秒检查一次:剩余低于 30 GiB 记 `disk_low`,本次 attempt 目录(工作区、`/trace`、host 保存的 stdout/stderr)超过 2 GiB 记 `attempt_size`,随即停止容器。处理与超时相同:容器清理记 unknown,候选不冻结,回执为 INFRA_ERROR。检查间隔内的写入仍会落盘,实际可超出约 2 秒的写入量(36 实测连续写零约 2 GB)。目录统计跳过 Agent 设为不可读的子目录,由剩余空间下限兜底。超限目录可能含容器 root 所有的文件,按精确路径清理。
## 模型通道与 Salty
Pi 0.73.1 默认使用固定 GLM-5.3 Chat Completions,也通过已有 SDK Responses adapter 接入用户指定的 Qwen `qwen3.8-27b-nvfp4`。模型能力与请求设置由 [adapter](../agent/pi.mjs) 明确记录。可信 host 从私有文件读上游 key,本次专用 Docker bridge 上的代理只接受该网络来源,不监听公网。Agent 不持有上游 key,只接收 `--model-base-url` 的非敏感地址;当前 Pi adapter 要求 IP 形式 HTTP URL。`--agent-network` 引用已创建的 internal 网络:controller 以 `--internal` 创建,`run` 拒绝非 internal 网络,未指定时 Agent 无网络,因此 Agent 不能直连外网。控制端核对证据后回收 proxy 和网络。
[Pi controller](../rollout/pi_run.py) 用私有凭据文件路径启动 [ModelProxy](../rollout/model_proxy.py),`--model` 仅接受 GLM 与 Qwen 两个固定身份及各自上游路由。controller 创建带所有权标签的新网络、自动校准或验证已有回执,运行固定 Pi argv;结束时停止 proxy、核对仅属本次的 network 与容器清理,保存 controller receipt。普通调用不手工传代理地址或网络。Qwen broker 另确认 Responses 流完整结束、唯一 `response.completed`、服务返回模型与状态,提前断流或 incomplete/failed 不得计为 VERIFIED;归档缺旧模型字段时按 GLM 身份复核,不能跳过检查。
模型代理的上游 socket 空闲期限由 `UPSTREAM_IDLE_SECONDS` 固定为 900 秒,避免 Qwen 流式响应在服务长暂停时被原 300 秒期限过早截断。
Pi 原生轨迹输出 `/trace/native.jsonl`:header 中记录模型、system prompt 和工具 schema;每轮记录 context、wire payload、HTTP 状态、原生事件及 session entries/end;context 消息与 payload 输入列表只记录相对上一轮新增的部分,读取时按 [agent.md](../agent.md) 的前缀增量规则重建全量后再核对。自动压缩、重试与外部扩展关闭,工具固定 read/edit/write/bash。控制端在容器退出并确认清理后检查轨迹常规文件及大小、计算摘要;`AVAILABLE` 只表示文件可读,不能代替语义与因果验收。真实采集需要核对调用 ID、结果和后续输入,缺费用字段记未知。
controller 另核对每个线上 payload 的输出上限等于回执记录的 `model_max_tokens`,对原生文件与 host 保存的 stdout 逐字节核对,将 model payload 摘要和顺序与 host broker 观察记录对账,并检查每个工具结果进入后续 model request。`pi_evidence=VERIFIED` 与任务 PASS 分开;总体 PASS 或 FAIL 都还要求证据 VERIFIED、Agent 正常结束和 cleanup confirmed。否则评分只留在 `task_verdict`,总体记 UNVERIFIED;broker 中有非 200 的模型请求时记 INFRA_ERROR(模型通道故障,不是任务失败)。代理只在开始回传前对上游 429/5xx 与连接错误最多重试两次(间隔 2、5 秒),每次状态写入 broker 的 `upstream_statuses`,Pi 只看到最终一次真实响应。Agent 内文件可以被其工具修改,因此保留 host 与 broker 侧证据,不只相信容器内终态字段。
36 Docker 的真实 Pi/GLM-5.3 单任务闭环已通过,Salty 已通过 CPU 镜像/存储探针及合格轨迹归档复核;探针临时资源已清理。实际模型/工具因果证据、独立评分和清理结论见 [acceptance.md](acceptance.md)、[现场回执](rollout-receipt.json) 与 [运行审阅](runtime-review.md),不以本地跳过的 SDK 检查代替镜像内实测。首次异常轨迹不计合格。
当前已验收的正式判分使用 36 Docker。Salty 正式 Agent 后端尚未完成,不假定支持 Secret、嵌套 Docker、无网 grader 或所需 capabilities,不能将 host bridge 代理直接当作可跨平台使用。其 Agent 模型通道、候选交接和清理单独验收,正式测试留在可信评分侧,不上传 Agent 也可读的个人盘。固定镜像身份与清理例外见 [onboarding.md](onboarding.md)。
## 身份、证据与终态
每个 attempt 创建新目录,保存任务/评分器/初始与最终候选摘要、解析后的实际 image ID、执行 argv、`events.jsonl`、阶段日志、原生轨迹和 `receipt.json`。`--agent-id` 是自报版本标签,需结合 Pi 原生身份与调用证据,不用监督日志替代真实多轮轨迹。回执沿用 `NOT_TRAIN_READY` 字段,本项目不执行训练转换或权重更新。
| 结果 | 含义 |
| --- | --- |
| PASS | 有效环境下,所有必需行为断言通过 |
| FAIL | 有效环境下,候选未满足需求 |
| UNVERIFIED | 缺依赖、必需能力或证据,无法裁决 |
| INFRA_ERROR | worker、容器、模型通道等执行故障 |
任务评分与 Agent 终止、清理结果分开保存。Bos 导入题的 verify.py 原样运行原 check.py,只把失败子进程 stderr 尾部抄到 `grade.stderr` 供私有分诊(可能引用隐藏测试,与 dataset.jsonl 同属可信处理端材料),批次报告的 `fail_detail` 取其最后一行;判定条件不变。超时、异常与中断不删除已有证据;独立命名的工作容器和评分容器在结束时回收。任务或镜像变更要重新校准,不能沿用旧 PASS。
Docker CLI 非正常结束时,daemon 创建请求可能仍在途,瞬时 rm/inspect 的不存在结果不足以确认容器清理;该次容器与总体 cleanup 记 unknown,自动校准的清理不确定性传播到 Pi controller。专属 network 创建的 CLI 未正常结束时同样处理;后续按唯一名称/ID 复核,可精确删除迟到资源并另存最终清理事实,原回执保留,不用全局 prune 掩盖残留。
`rollout.archive` 重新核对 controller、attempt、校准、候选、grade 及 host/native/broker 证据,仅封存显式文件清单,不递归导出工作区或隐藏测试。正常结束、证据 VERIFIED 且清理确认的 PASS/FAIL 均可封存;归档摘要上传后重读核对,合同见 [artifacts.md](artifacts.md)。
不先建设任务队列、共享数据库或硬件调度,不实现训练代码。Bos-qiao 任务由 [bos_import](../rollout/bos_import.py) 逐题导入并重新校准;批量采集用 `xargs -P` 并发多个独立 controller,[report](../rollout/report.py) 汇总完整轨迹、排除原因、用量与耗时。活跃 runs 放在执行主机本地盘,避免共享文件系统停顿影响时限与清理判断。M3 的质量与扩量阶段门仍以实际批次证据验收。
Git remote 为用户 2026-10-13 指定的 `origin`(`https://gitea.d-robotics.cc/ming01.wang/data-gen-ebd.git`),只推送 main,不改写已推送历史;用户已授权本项目资源接入和试跑。host 与 Salty 测试产物在核对必要证据后清理,Salty 持久文件集中于唯一个人目录,不动已有作业或其他项目资源。