CharlesZhang-USTC/snf_experiments

SNF五模型镜像与自动实验

本目录把研究方案6.1–6.5中的Meissonic、Self Forcing、MoMask、SD3.5 Medium和原版Show-o组织为同一个Docker镜像。运行目标是Linux x86_64、4张RTX PRO 6000 96GB。镜像基础为CUDA 12.8.1、Ubuntu 22.04、Python 3.10、PyTorch 2.7.1/cu128。统一基础层共享CUDA和PyTorch；Show-o的旧版Transformers/Diffusers使用独立虚拟环境，模型进程彼此隔离。

验收状态：本地已执行CPU核心检查和源码完整性检查。当前电脑没有Docker和可用CUDA GPU，因此尚未构建出可分发的镜像tar，也尚未完成五模型真实推理验收。下面提供完整构建上下文、自动脚本和租赁服务器验收入口。环境是候选兼容配置，只有GPU验收通过后才能称为已验证配置。

1. 包里有什么

• 根目录Dockerfile和.dockerignore。
• vendor/中四个官方项目的完整源码快照，保留其许可证；SD3.5的模型实现随锁定的Diffusers 0.31.0安装进镜像。
• sources.lock.json记录上游commit；sources.manifest.json校验397个上游文件。
• requirements-common.txt、install_environments.sh：共享GPU依赖及五个模型环境。
• suite/：权重下载、任务清单、采样器控制、实验规划、GPU任务调度、断点续跑、数据保存、绘图、开发集调参、测试集校准和质量诊断。
• build.sh、start.sh、run_all.sh、validate_gpu.sh、export.sh。另有Windows构建和启动脚本。

模型权重、数据和输出通过/weights、/data、/outputs挂载。权重不嵌入源码包或镜像，SD3.5等模型的访问权限须由租赁账户的HF_TOKEN提供。首次下载将Hugging Face权重固定到具体revision；后续推理读取该revision的本地快照。MoMask使用官方Google Drive模型包，保存下载文件校验值。

2. 租赁服务器第一次启动

先确保服务器nvidia-smi识别所有GPU，且已安装Docker与NVIDIA Container Toolkit。宿主驱动必须支持该显卡和CUDA 12.8；容器不会替换宿主驱动。

cd snf-five-models
export HF_TOKEN='你的HuggingFace访问令牌'
export SNF_STORAGE=/mnt/snf-runtime
bash packaging/build.sh
bash packaging/start.sh doctor
bash packaging/start.sh fetch --models all
bash packaging/start.sh run --profile smoke --output /outputs/smoke --render-motion --resume

doctor检查模型导入、显卡信息、CUDA内核和源码校验。构建阶段的导入检查不下载权重，也不伪装成模型推理验收。

完整GPU验收可以一条命令执行：

bash packaging/validate_gpu.sh

任何模型导入或推理失败都会返回非零状态。详细信息保存在outputs/acceptance/logs/和各任务的result.json，不会用模拟图片掩盖失败。

3. 自动执行五个实验

先做smoke，再做pilot，再放开full。不要第一次租机就直接启动完整扫描。

bash packaging/start.sh create-tasks --output /data/tasks.curated.jsonl
bash packaging/start.sh plan --profile full --tasks /data/tasks.curated.jsonl --output /outputs/full-plan
bash packaging/start.sh run --profile pilot --tasks /data/tasks.curated.jsonl --output /outputs/pilot --render-motion --resume
bash packaging/start.sh run --profile full --tasks /data/tasks.curated.jsonl --output /outputs/full --render-motion --resume

tasks.curated.jsonl包含60个图像任务、60个时序任务和8个独立开发集任务；参考由各模型单独生成。它是透明标记的作者自建任务集，不能写成公开基准结果。动作任务里的人物描述及动作自然度需要人工审查；Self Forcing与MoMask使用相同动作语义，但不共享同一参考状态。

你可以替换为真实数据的JSONL清单，指定reference_path，路径必须是容器内的/data/...。图像须与模型原生分辨率一致；Self Forcing参考须为81帧、480×832、16fps；MoMask参考须为[196,263]的HumanML3D原始动作特征，不能直接传XYZ关节坐标。脚本不静默缩放或改帧率。

主实验默认规模：Meissonic 48任务×3种子×4顺序×17刻度；Self Forcing 24×3×3控制方式×9刻度；MoMask 60×3×4顺序×17刻度；SD3.5 24×3×2控制入口×9刻度；Show-o 16×3×4顺序×9刻度。主实验共27,000条生成，full还加入额外扫描，因此总量更大；以plan打印的条数为准。

只跑主实验：

bash packaging/start.sh run --profile full --no-extras --tasks /data/tasks.curated.jsonl --output /outputs/main-only --render-motion --resume

一键按顺序执行环境检查、下载、smoke、pilot、full、恢复调参、恢复测试和质量诊断：

bash packaging/run_all.sh
# 或传入你自己的容器内任务清单：
bash packaging/run_all.sh /data/tasks.paper.jsonl

控制刻度有外部明确含义时，可额外自动执行held-out isotonic校准：

export SNF_CALIBRATION_TARGETS='-0.4,-0.3,-0.2,-0.1'
bash packaging/run_all.sh /data/tasks.paper.jsonl

这里beta使用“负目标区域L1距离”的单位。不同模态的L1不具有统一感知含义；这些数值只是示例，正式实验应事先声明各任务的评价量及公共目标区间。脚本报告不可达目标，绝不截断后宣称校准成功。

4. 已实现的实验与边界

• masked模型的置信度优先、随机、目标优先、目标最后顺序；同一场、同一提交数量和同一模型调用预算，完整位置数组绑定随机数。
• Self Forcing保持原生因果顺序，比较局部注入、局部注入加弱前缀引导、完整前缀注入；不会把视频时间逆序称为合法顺序对照。
• SD3.5比较同步状态注入与预测引导，作为无永久提交的对照。
• 主曲线、65点密集扫描、多生成种子、固定生成种子下的参考噪声重抽、软/硬释放对照。
• 图像小/大中心、边缘和全局mask；时序早/中/晚和全局目标区域的独立几何扫描。
• masked模型的8/18/32/64步扫描、离散logit-bias入口、上下文遮蔽干预、延迟永久提交。上下文遮蔽是输入干预，不能据此声称模型能力发展规律。
• 开发集前缀引导强度/时长网格，按预先写明的收益减副作用目标选参数；参数固定后生成独立测试任务。
• 2/4/8次完整候选重采样，按参考区域距离选择并记录总调用数。这是参考可见的重采样基线，不是因果视频的缓存回退实现。
• Self Forcing另有1/2/4块有限回退：重新开放目标前的后缀，调用官方initial_latent接口重置并重建前缀缓存，记录所有cache-refresh与denoise调用；还提供1/3/7帧块大小压力测试，非原生3帧配置明确标为分布变化。
• 独立开发集isotonic拟合、测试集按requested beta计算误差；不冒称正式FreeSliders ASTD。
• CLIP、图像LPIPS、动作速度/加速度/jerk质量诊断入口；默认仅评估主实验seed=0、alpha=0/0.5/1，--all-jobs可扩大范围。
• 既有Gaussian/toy分析代码随镜像保存，可用analytic写入挂载结果目录。
• masked图像/动作/Show-o提供固定状态KL耦合探针：全MASK状态逐组揭示参考，测量对其他组预测分布的影响，在主输出生成前保存矩阵和顺序加权分数。这个分数是探索性非线性代理，不是Gaussian的精确total_I；置信度顺序仅使用初始置信度。探针前向调用单独记账，参考生成不计为免费。

以下研究方案仍需要针对真实模型进一步实现或独立复现，当前包没有把它们标成已完成：正式ASTD、非线性耦合代理的预测有效性验证与连续/因果模型拓展、FID/FVD和HumanML3D官方检索/FID全套评价，以及Show-o的理解/交错生成分支。回退和块大小干预虽然已有代码，但尚须GPU检查基础质量及缓存行为。原版Show-o这里实验的是多模态模型的图像生成分支，不能支持“所有多模态生成都成立”的结论。

5. 结果在哪里

宿主机$SNF_STORAGE/outputs/<run>/里保存：

• run.json：代码/参数/权重身份；plan.jsonl：全部生成任务。
• references/：参考样本及任务说明；baselines/：官方原生采样与研究采样alpha=0分开保存。
• jobs/<id>/output.png或output.mp4；动作还保存output.joints.npy。
• 动作视频使用实际XYZ关节的正交投影骨架渲染，并保存关键帧条带；不依赖上游旧BVH导出器的私有NumPy接口，也不渲染不存在的外观细节。
• state.npy、mask.npy、masked模型commit.npy；图像/动作另存output.npy。视频保存MP4和latent，不默认存每次生成的未压缩视频数组。
• trace.jsonl、trace.png、commit.png；result.json记录目标变化、副作用、耗时、显存和环境。
• control_loop_model_evaluations是控制循环的去噪器调用数，Self Forcing包含缓存刷新；不把tokenizer/文本编码器或MoMask residual decoder伪装成同一个NFE单位。端到端工作耗时另行记录。
• summary/metrics.json、curves.json、各模型控制/副作用曲线、index.html浏览页。
• noise.json按任务/刻度记录重抽噪声的响应标准差与极差；校准测试另保存calibration.json及requested beta/achieved response散点图。
• 重采样的候选种子和全部过程记录在resampling.json。

浏览器打开summary/index.html即可查看真实保存的媒体。汇总中的L1是诊断量，不能代替感知质量或官方基准分数。曲线阴影是任务/种子样本的标准差，不是论文置信区间。

视频编码有压缩；CLIP视频诊断在解码的MP4上计算，并记录该事实。要做像素精度的后续视频评价，应额外导出无损视频，或从保存的latent按相同VAE解码。完整扫描建议预留0.5–2TB结果空间，实际消耗以pilot实测外推。

6. 断点续跑与GPU调度

默认发现容器中的全部GPU；--gpus 0,1,2,3可显式指定容器设备编号。每GPU一次只运行一个模型worker，每worker加载一次模型，任务按模型/任务分组分发。这里利用四卡并行跑独立任务，单个模型不做四卡张量并行。

--resume跳过状态为complete的任务，失败任务重试。run目录的代码、任务、配置或权重身份发生变化时，拒绝混入原结果，必须换新的--output。

创建outputs/<run>/STOP会在当前生成任务结束后停止。重新运行前删除自己创建的STOP文件。不要删除已有模型文件或结果来“修复”错误。

bash packaging/start.sh analyze --output /outputs/full
bash packaging/start.sh evaluate --run /outputs/full
bash packaging/start.sh analytic --output /outputs/analytic

已有toy代码的gate泄漏和lead-in饱和潜力当实际reach的问题已修正；旧CSV的数值不能直接当作修正版本结果，须重新运行并审查输出。既有toy的recalibration脚本保留为历史实现，不用于替代新held-out校准。

本次CPU试跑还实际执行了run_laws和修正后的run_leadin。后者在这个版本和共同评价口径下，基线实际reach约0.316，测试的最大实际reach约0.452，没有任何测试组恢复到0.99。因此先前摘要里的“完全恢复”不能沿用为本版本结论。该试跑仍是toy实验，不是五个真实模型的GPU结果；运行说明中的主扫描没有预置任何有利结论。

7. 输出可搬运的实际镜像

bash packaging/export.sh /mnt/snf-five-models-cu128.tar
# 另一台服务器：
docker load -i /mnt/snf-five-models-cu128.tar

这是实际Docker镜像导出入口。当前提交的ZIP是构建源码包，不是已经构建并通过GPU验收的镜像tar。

Self Forcing启用明确记录的SDPA替代注意力，不安装旧FlashAttention/xformers二进制；masked模型提交顺序研究使用显式研究采样循环。所有模型的官方native输出另外保存，以便在租机后检查研究采样是否明显损害基础质量。安装日志和每模型pip freeze在镜像内/opt/envs/<model>/installed.freeze.txt，供实际验收时归档。