# 8卡4090托盘检测 baseline 任务说明

本交接为**正式数据、任务说明和当前源码快照**。目标服务器可联网，执行者在目标机完成新增接口并实际训练。新 `pallet.baselines` 统一入口尚未实现，实验清单为 pending/not_started；交接验收不冒充训练完成。机器可读任务配置见包根 `handoff_config.json`，环境步骤见 `ENVIRONMENT_zh.md`。

## 数据与来源

正式人工数据集 v1：10,374帧、10,111正例、263确认负例、12,344框、428采集组。严格保持原 train/val/test=6,552/1,455/2,367。训练包含6,358正例/194负例；验证1,424/31；测试2,329/38。标签是用户确认的模型辅助标注，审阅者声称数1，**independent_blind_reference=false**，不声称独立盲审或双审。

118帧重建强度及其专题人工框保留；240×96域300帧已经整体校正180°，不要二次旋转。148不可恢复黑图永久移除，其余协议排除和损坏隔离见包内溯源。仅2,034帧具有经过核验的深度，其余显式缺测。原始PCD/YAML路径只作溯源，目标训练不得依赖本机原始库或缓存。

数据ZIP SHA-256：`868259c08abad0f4f512c6de6b5f38bdafac94e8ae7cc792dbaeb9448f466c8b`。
冻结清单 SHA-256：`cb075be080cdd1255628d0f2ef1deec35a79314b64ab3d98d204d093d6d7a3f5`。
权威标签 SHA-256：`ccdd70c930cf1cf117a96f54dfdf4b858d3d1b2c589b2d8dadef851237a7f4bb`。

数据格式：

- `images/<split>`：原生强度PNG与同名AnyLabeling JSON；PNG使用显示强度映射，不等同于浮点原始强度。
- `labels/<split>`：YOLO class0，空TXT仅为人工确认负例。
- `annotations/<split>.coco.json`：COCO class1；**file_name 已包含 images/train等前缀，以 dataset 根目录解析**。接入官方框架如要求basename，另建有哈希绑定的派生COCO/软链接视图，不能重写冻结文件或重复拼接目录。
- `sensors/<split>/*.npz`：键 `frame` 为未归一化float32 H×W×4，顺序为深度(mm)、原始强度、深度有效掩码、强度有效掩码；键 `metadata` 是JSON标量字符串。`tensor_index.json` 路径相对数据集根目录。
- 根 `frames.jsonl` 保存原身份、采集组、配置域、哈希及当前相对路径；`annotations/frames.jsonl` 是权威框，`splits.json` 是固定划分。
- `auxiliary` 仅供预览，部分深度未核实；训练只能使用NPZ核验深度与掩码。`protocol` 内历史绝对原始路径不作为目标数据读取入口。

## 模型与八项实验

| ID | 官方模型 | 输入 | 用途 |
|---|---|---|---|
| 01 | YOLOv8s | 原生强度PNG复制为3通道 | 原论文基础对照 |
| 02 | YOLO26s | 同上 | 最新已发布Ultralytics YOLO |
| 03 | RF-DETR-Small | 同上 | DINOv2检测Transformer |
| 04 | EdgeCrafter ECDet-S | 同上 | 紧凑DINOv3蒸馏检测器 |
| 05 | YOLO26s | 浮点强度+掩码 | 控制浮点预处理与适配层 |
| 06 | YOLO26s | 浮点深度+强度+掩码 | 与05比较深度收益 |
| 07 | RF-DETR-Small | 浮点强度+掩码 | 传感器控制组 |
| 08 | RF-DETR-Small | 浮点深度+强度+掩码 | 与07比较深度收益 |

全部只跑seed42。YOLO26统一选择one-to-one无NMS推理分支；训练保留官方双分支损失与Progressive Loss状态。PNG主实验保留官方结构，只替换单类任务头；传感器实验每个模型对使用同一个 `ShallowFusion` 4→3适配结构和初始化，I-only将深度与深度掩码同时置0。P2、门控融合、深度边缘关闭。不得仅将PNG结果与D+I结果相减，宣称全部差异来自深度。

模型资料：[YOLOv8](https://docs.ultralytics.com/models/yolov8/)、[YOLO26](https://docs.ultralytics.com/models/yolo26/)、[RF-DETR](https://github.com/roboflow/rf-detr)、[EdgeCrafter](https://github.com/Intellindust-AI-Lab/EdgeCrafter)。DEIMv2在调研中，由其更新路线ECDet-S代表本轮；YOLO27尚未公开发布，不列入。公开COCO数值只作选型依据，不是本数据集成绩，不同Small模型参数量并不相同。

## 固定训练协议

- 全部从官方检测预训练权重重新初始化。禁止历史辅助模型、先导或教师权重；这些模型接触过原val/test。ECDet-S采用COCO检测权重，不采用额外Objects365检测权重；各骨干的预训练来源单独记录。
- 输入640×640，保持比例补边，不拉伸；PNG灰度复制3通道、除255。RF/EC的官方均值方差放在各模型入口。传感器归一化仅用6,552个train拟合并冻结，I-only/D+I对共享同一强度统计；缺测为0和显式掩码。
- 有效batch16，实际batch先试16/8/4/2，保留至少15%显存余量，按实测吞吐选定后冻结。累积为16/实际batch，尾批按实际样本数处理，不能丢失最后几张训练帧。PNG与float同一家族尽量使用相同实际batch，确有显存限制则记录差异。
- 最多300epoch，验证COCO AP50:95每轮计算，选择EMA最佳权重；严格提升才重置stale计数，连续50轮不提升早停。相同最佳AP保留更早轮次。
- 使用各官方损失、优化器分组、调度、warmup、梯度裁剪及EMA，显式记录源码、默认配置、实际数值和研究约束。现有YOLO/RF `official_research_constrained` 提供参考；新入口需真正接入，不把pilot AdamW方案当作官方配方。EC官方74轮配方需改为300轮预算并显式绑定调度总步数，不能在74轮隐式退出。
- 所有输入空间增强相同：fliplr概率0.5、scale[0.5,1.5]、translate±0.1；掩码、输入、框同步变换，信号采用有效支持插值，掩码nearest。关闭Mosaic、MixUp、多尺度、颜色增强及旋转。全部偏离官方默认的项目配置在报告列出。
- GPU训练用AMP，记录dtype、溢出与实际优化器步数，EMA只在成功更新后推进。恢复包含模型、EMA、优化器、调度器、AMP scaler、随机数、数据loader种子、best/stale及YOLO26损失更新计数。
- 输入、标签、划分、归一化、代码、模型初始化、训练配置都绑定哈希；同任务恢复不得换输入版本。完成文件绑定最佳权重哈希与终止原因，`best.pt`存在不等于训练完成。

## 目标机需要实现的接口与顺序

复制 `source` 到 `work/source` 后继续开发，保留原源码快照作为证据。新接口拟为 `python -m pallet.baselines prepare|preflight|train|evaluate|benchmark|report`，这些命令**当前不存在**，不要在接口完成前执行。

1. 安装两个独立环境，记录完整目标依赖freeze；校验外层包并解压正式数据，运行便携校验工具。不重新标注或重新划分。
2. 建立正式人工标签资格manifest：逐帧核验权威标签摘要、源身份、图像/NPZ尺寸、人工来源、正负例及原划分。明确新的 `formal_user_reviewed` 来源类型，允许原val/test参与相应评价；不关闭资格检查、不伪造双审、不放宽旧盲审接口。
3. 实现仅依赖包内数据的loader和单类映射，接入四个官方模型，审计精确迁移/新初始化参数比例。统一原坐标预测和COCO评分，兼容负例、RGB复制、4通道掩码和YOLO26两种输出形状。
4. 每个模型先使用真实正例/负例完成训练、验证与中断恢复检查；小样本只验证代码，试跑权重丢弃，正式重新从官方权重初始化。
5. 预试8卡并发读取和实际batch；冻结八项完整配置及固定验证测速帧，随后独立调度训练。
6. 每项前10个真实epoch后更新预计时长；先汇总四个PNG主baseline验证结果，随后补传感器结果。直到所有配置冻结、模型选择结束后再开展test评分。test不用于配置更改。
7. 全部训练结束后统一测速、bootstrap与报告。完成条件是实际训练/评分/产物齐全，不是实验矩阵生成。

当前参考代码：`pallet/experiments/train.py` 有YOLO/RF优化、EMA及恢复；`pallet/models/rfdetr.py` 当前强制4通道，PNG需要真实3通道入口；`PalletDataset` 当前仍有历史双审资格限制；`pallet/cli.py` 的历史evaluate要求盲审，不能直接套用正式人工版本。`pallet/formal_dataset.py` 的验证器可以只读正式包，构建器和旧 `load_protocol` 默认会查原始库。`pallet/devices.py` 已支持按实际PyTorch UUID解析，旧CUDA序号不可沿用。本包附的portable工具无需导入这些历史控制配置。

## 八卡调度、资源和故障处理

目标机枚举PyTorch实际UUID并排序，依次绑定01–08，一卡一进程，每进程只可见自己的UUID；单卡进程内使用cuda:0。**不把八卡合并为一项DDP训练，不将有效batch放大到128**。本机3090/4090D UUID和nvidia-smi序号不可移植。保存物理UUID、型号、显存、PyTorch逻辑编号映射。

每任务先4个loader worker；总worker超过可用CPU核数时均匀降低，pin_memory及预取按实测记录。八项共享只读数据，不每卡复制24GiB传感器数据；模型先在单独准备阶段下载、哈希登记，避免并发写同一权重。建议初始空闲≥120GiB，空闲<50GiB暂停新增大文件。检查点保留best、last及恢复所需版本，不保留所有epoch的大文件；每轮只记录摘要，逐帧预测在最佳验证与最终测试另存，避免日志爆炸。

记录每epoch训练/验证/保存时长、帧吞吐、显存及GPU利用率。OOM在预试调整actual batch并重新从官方权重启动正式run；运行中设备失败在完整checkpoint边界恢复，不能静默跳帧或重置优化器。未恢复错误标failed，不能计入完成。任务完成后不按test结果继续选择结构或增强。

## 评价与结果交付

- 统一pycocotools、原始坐标、GT category1 pallet，模型class0显式映射；COCO maxDets=[1,10,100]、IoU0.50:0.95步长0.05、101个召回点。各模型输出置信度≥0.001、最多300框用于原始预测记录；AP按COCO上限100。YOLOv8 NMS IoU0.7，YOLO26 one-to-one、RF/EC按官方无NMS解码，评价与测速使用相同分支。
- val上按score顺序一对一匹配IoU0.5选择F1最高阈值，平局取最高阈值；固定后用于test的precision/recall/F1/FP-per-frame。AP使用低阈值完整预测，不能使用运行阈值裁掉候选。处理确认负例，分别报告负例误检帧率和每负例误检数。
- 报告val和test的AP50/AP75/AP50:95、precision、recall、F1、每帧误检、帧/框数量；按配置域、训练已覆盖域/四个仅test域、原生分辨率、深度可用/缺测分项。未人工确认的堆叠、遮挡属性维持unknown，不臆造分项。配置域不等同于物理设备。
- 以采集组为单位bootstrap1000次、seed42，报告95%区间；重采样同组时赋不同COCO image_id。固定权重的组区间不是训练种子标准差，本轮没有跨seed标准差。保留成对bootstrap抽样以比较05/06、07/08。
- 八项训练全部结束，关闭其他GPU负载，在一张固定目标4090上batch1、FP32、TF32关闭测全部模型。用相同30张按域分层的val帧，预热50次、200次CUDA同步计时；报告forward、model+postprocess、文件读取到原图框端到端median/P95，记录缓存状态、参数量（训练/实际推理分支）、FLOPs及未支持算子、峰值显存。不得引用T4/TensorRT公开延迟当作本机结果。
- 每run交付绑定哈希的配置、目标环境、初始化迁移记录、归一化、epoch摘要、best/last及completed状态、最佳val和test原坐标逐帧预测、指标JSON。汇总交付CSV/JSON、中文报告、精度—延迟图和典型漏检/重框/背景误检图。
- CSV每行标明experiment_id、model、input、seed、actual/effective batch、best_epoch、actual_epochs、val/test三项AP、选定threshold、test精确率/召回率/FP、参数/FLOPs/延迟/显存、UUID、权重/数据/源码哈希。未完成项填状态与原因，不能填估计AP或0冒充结果。

## 必须通过的测试

正式人工资格与伪机器来源拒绝；原frame/group/source跨集合为0；train-only统计与目标域隔离；负例、尾批不丢失；三格式框一致性；mask与框空间变换及原坐标还原；拥挤目标一对一匹配；官方分类头重建/权重迁移比例；YOLO26分支输出；中断恢复与改变输入拒绝；八项唯一UUID任务互斥、失败重试和完成哈希；COCO AP及分组bootstrap。最终测试以2,367张全部成功预测为必要条件。

任务范围：当前八项单seedbaseline及传感器对照，不增加结构改造、额外留一域训练、三seed、叉孔或位姿。研究结论需注明人工模型辅助标注来源，历史辅助成绩不进入正式baseline表。
