data-gen-ebd/docs/architecture.md
amos ef3c173fa6 Owe again the attempts stopped because the host disk ran low
A batch paused at the free-space floor recorded its in-flight attempts as disk_limit,
which paid their JOBS lines, so rerunning the same command would have skipped them.
Host disk stops are now their own exclusion, disk_low, and count like interrupted
attempts; attempt_size stays disk_limit and still pays its line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 11:13:19 +08:00

20 KiB
Raw Blame History

Rollout 架构与验收

本阶段提供一个任务、doctor / calibrate / run 三个 Python 3.9+ 标准库入口、管理 Pi 闭环的 rollout.pi_run controller,以及已有 Pi SDK 的原生 adapter。当前只做真实 rollout 采集,不实现模型训练。完整扩量设计见 rollout-plan.md。

机器分工、当前与建议部署图、镜像和轨迹位置见 deployment.md。任务作者的交付与准入标准见 task-authoring.md,可复制的任务设计表见 templates/task-spec.md。

任务包

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。

执行边界

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 以 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。

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 明确记录。可信 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 用私有凭据文件路径启动 ModelProxy,--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 的前缀增量规则重建全量后再核对。自动压缩、重试与外部扩展关闭,工具固定 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(模型通道故障,不是任务失败)。代理在 Pi 收到任何生成内容之前,对上游 429/5xx、连接错误和停滞最多重试两次(间隔 2、5 秒),每次结果写入 broker 的 upstream_statuses(停滞记 stalled),Pi 只看到最终一次真实响应。SSE 流先压住开头的非生成事件(Responses 的 response.created/response.in_progress),收到第一个生成事件才连同开头一起转发;180 秒内没有生成事件,或在此之前上游断开,即算停滞并重试,broker 的 first_event_seconds 记录实际等待。上游静默期间代理每 30 秒向 Pi 写一行 SSE 注释保持连接,Pi(Node fetch 默认 300 秒收不到数据即断开)因此不会先于代理超时;开始生成后不再重试,静默上限仍为 900 秒。Agent 内文件可以被其工具修改,因此保留 host 与 broker 侧证据,不只相信容器内终态字段。

36 Docker 的真实 Pi/GLM-5.3 单任务闭环已通过,Salty 已通过 CPU 镜像/存储探针及合格轨迹归档复核;探针临时资源已清理。实际模型/工具因果证据、独立评分和清理结论见 acceptance.md、现场回执 与 运行审阅,不以本地跳过的 SDK 检查代替镜像内实测。首次异常轨迹不计合格。

当前已验收的正式判分使用 36 Docker。Salty 正式 Agent 后端尚未完成,不假定支持 Secret、嵌套 Docker、无网 grader 或所需 capabilities,不能将 host bridge 代理直接当作可跨平台使用。其 Agent 模型通道、候选交接和清理单独验收,正式测试留在可信评分侧,不上传 Agent 也可读的个人盘。固定镜像身份与清理例外见 onboarding.md。

Salty Agent 后端(2026-10-28 验收,批量使用中)

Salty controller 在 36 运行,只把 Agent 一步换到 Salty,校准、评分、证据对账与 pi_run 相同;rollout.batch --backend salty 逐题调用它。

  1. 模型通道:本次尝试在 36 起专用 ModelProxy,只监听 127.0.0.1 的随机端口,要求 Authorization: Bearer 等于本次随机令牌(错/缺令牌 401,不触达上游);令牌经 salty run -e 传入,结束即随 proxy 作废,上游 key 不离开 36。/health 只校验令牌、不转发、不入 broker,供作业确认隧道。
  2. 隧道:36 安全组只对 Salty 放行 22,因此每次尝试生成一次性 ed25519 钥匙,写入 ming01.wang 的 authorized_keys,选项为 restrict,port-forwarding,permitopen="127.0.0.1:<端口>",expiry-time=...,command="/bin/false";结束后删除并确认。作业经平台代理 apt 装 openssh-client,ssh -N -L 127.0.0.1:18080:127.0.0.1:<端口> 先连内网 172.16.0.6,不通再连公网 36.144.20.182,断线自动重连;启动 Pi 前清掉代理变量。
  3. 题面与初始工作区打成一个 tar 上传到 personal:/er-stage-<hex>/in(Salty 存储删不掉空目录,所以不传目录树);正式测试和参考解不上传。
  4. Salty 作业用 CCR VPC 地址按校准镜像 digest 拉取;启动脚本把材料复制到 /workspace、/task/prompt.md、/trace,以 uid 65534 运行与 Docker 相同的 Pi argv,1 CPU、2Gi。stdout/stderr 由 root 父进程写入 Agent 不可读的文件;超时杀掉 uid 65534 的全部进程。结束后工作区、轨迹与退出信息打成 result.tar,连同 sha256 清单写到 out/。
  5. controller 取回 out/,核对清单后安全解包(拒绝绝对路径、..、经符号链接写入与特殊文件),按原流程冻结候选、在 36 无网 Docker 中评分,并与 broker 逐条对账。
  6. 污染检查:工具参数或结果出现 /data/personal、/data/shared、/data 路径或 http(s):// 时,记 contamination 并把总体结论降为 UNVERIFIED(评分留在 task_verdict),不计入。
  7. 清理:删除作业与 stage 并确认不存在,撤销钥匙(key_cleanup),关闭 proxy;任一未确认记 INFRA_ERROR。

Salty 作业以 root 启动、全量挂载个人盘与共享盘且可访问外网,这些边界弱于 36 Docker,只能由 uid 降权、事后污染检查与 broker 对账兜底。Agent 可读到令牌,但每个经令牌的请求都进 broker,多出的请求使对账失败。一次性私钥在作业存在期间可经 salty describe 看到,它只能转发到本次网关端口且自动过期。

批量采样的冻结快照

正式批量采样不在主工作副本上直接跑。开跑前在 36 建 .tmp/<批次>/:

  • code/:起点提交的代码和 tasks/ 的完整复制。COMMIT 记录起点,以及中途同步过的文件版本。
  • JOBS-*:每行“题号 校准目录”,由 rollout.catalog jobs 从当时重建的目录导出。

rollout.batch 在 code/ 下运行,--tasks 指向 code/tasks。2026-10-28 的 Salty 全量采样就是 .tmp/salty-full-20261028/,起点 c64c79b3,共 1037 条。

  • 开跑后 main 新合入或修改的题不会进入本批。要采新题,另开一批:新快照、重建目录、新 JOBS。

  • 本批结束前,以下内容只可复制,不可移动或删除:

    • JOBS 引用的校准目录,可能在热盘的 worktree 里,也可能在冷盘。缺了校准,剩余尝试会变成校准错误。
    • 本批的 runs/ 输出和 .tmp/<批次>/。续跑要靠已有的尝试目录判断。

    冷迁和清理都等本批结束再做。

  • 制题可以和采样并行。新题在独立 worktree 里制作,校准和审阅后才合入 main,不影响正在跑的批次。但要给采样留出 /home 余量:剩余低于 30 GiB 时采样会自动暂停。

身份、证据与终态

每个 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。

不先建设任务队列、共享数据库或硬件调度,不实现训练代码。Bos-qiao 任务由 bos_import 逐题导入并重新校准;批量采集用 batch:读 JOBS(每行“任务名 校准目录”,按轮次重复即为多次采样),以子进程并发运行多个独立 pi_run controller。每次启动先按回执计算仍欠的行,已启动 Agent 且 task digest 与当前任务一致的尝试才抵扣,未启动、无回执、被中断或因执行主机剩余空间不足(disk_low)而停下的不算,因此中断后重跑同一命令即续跑。排除原因为 stream_cut、model_http、trace_limit、cleanup、infra、grade_timeout 的尝试属基础设施失败,自动补采,每行最多补 --retries 次(默认 2);其余结果(任务 FAIL、timeout、output_limit、evidence 等)照实计数,不补采,以免只重抽不利结果。最近 3 次结束的尝试都因环境原因失败(上述基础设施原因、calibration 或无回执),或输出盘剩余低于下限时,停止启动新尝试,等进行中的结束后写报告,以退出码 3 打印原因;修好后重跑同一命令。收到 SIGTERM/SIGINT 时向全部 controller 转发 SIGTERM,等其写完中断回执。结束时在批次目录写一份新报告 report-<UTC 时间>.json。同一批次目录只能由一个 batch 进程写入。report 汇总完整轨迹、排除原因、用量与耗时。每条未计入完整轨迹的尝试按顺序取第一条命中的排除原因(exclusion):no_receipt 无 controller 回执(仍在运行或进程被杀)、interrupted controller、Agent、评分或自动校准被中断、timeout Agent 超时、disk_low 执行主机剩余空间低于下限、disk_limit 尝试体积超限、grade_timeout 评分容器超时、cleanup 清理未确认、trace_limit 原生轨迹最后的 session_end 为 TRACE_LIMIT_EXCEEDED、model_http broker 有非 200 模型请求、stream_cut Responses 流 HTTP 200 后没有终止事件或未正常读完、output_limit broker response_status=incomplete 或最后 stop reason 为 length、calibration 校准阶段失败或回执不匹配、infra 其他执行故障、evidence 其余证据不全(见 evidence_reason)。归类只用于统计、排查和 batch 补采,不改变 controller 状态、证据判定或归档准入。活跃 runs 放在执行主机本地盘,避免共享文件系统停顿影响时限与清理判断。M3 的质量与扩量阶段门仍以实际批次证据验收。

Git remote 为用户 2026-10-13 指定的 origin(https://gitea.d-robotics.cc/ming01.wang/data-gen-ebd.git),只推送 main,不改写已推送历史;用户已授权本项目资源接入和试跑。host 与 Salty 测试产物在核对必要证据后清理,Salty 持久文件集中于唯一个人目录,不动已有作业或其他项目资源。