企业官网建设流程全解析

如何中断与恢复 Spirula Studio 训练：checkpoint 断点续训完整指南

【免费下载链接】spirula-studioCross-vendor 3D Gaussian Splatting trainer - video to splat to mesh, Vulkan or CUDA.项目地址: https://gitcode.com/GitHub_Trending/sp/spirula-studio

Spirula Studio 是一款跨厂商（Vulkan / CUDA）的 3D Gaussian Splatting 训练器，覆盖"视频 → splat → 网格"的完整流程。面对动辄数万步的长训练，断电、显存不足或临时想调参都是家常便饭——本文将带你掌握它的 checkpoint 断点机制：如何优雅中断训练、checkpoint 目录里到底存了什么、以及怎样用--resume一键断点续训，让训练随时停、随时续。

训练中断的 3 种方式

Spirula Studio 的中断设计围绕一个核心思想：定期自动存档，任何时刻退出都能找回最近进度。

• CLI 直接退出：spirula train按Ctrl+C终止进程。训练器默认每steps_per_save步（默认 2000 步，见 src/config/TrainConfig.h）自动保存一次 checkpoint，即使进程被强制结束，也能回退到最近一次存档继续。
• GUI 停止训练：图形界面的训练会话支持 pause/stop，导航离开或退出时会弹出"停止并保存"确认框（实现见 src/app/gui/TrainRunner.h 与 src/app/README.md），确认后即可安全离开。
• 只留最新存档：save_only_latest_checkpoint默认为true，每次保存后自动清理旧 checkpoint 目录，磁盘上始终只保留最近一份，省去手动清理。

认识 checkpoint 目录：step-*.ckpt 里都有什么

每次存档都会在运行目录（run dir）下生成一个形如step-000002000.ckpt/的文件夹，结构如下（命名与解析逻辑见 src/checkpoint/Resume.h）：

<run_dir>/ ├── config.json # 本次运行的完整训练配置 ├── step-000002000.ckpt/ # 一个存档点 │ ├── state.tar # 续训载荷：state.json 清单 + 每块 GPU 缓冲一个 .npy │ └── splat.ply # 推理产物：过滤、反量化后可直接渲染/建网格的高斯 └── step-000004000.ckpt/ # 下一个存档点……

• state.tar是一个零依赖的 tar 包，内含state.json（步数、高斯数量、SH 阶数等运行时清单）和按池槽命名的扁平.npy数组。读写工具全部内建，无需 Python 环境，格式实现见 src/core/CheckpointIO.h 与 src/engine/EngineCheckpoint.cpp。
• splat.ply是"随时可交付"的成果：无论你是否续训，它都可以直接交给spirula-mesh做网格提取，或在 Web 查看器中查看。
• 存档时 GPU 缓冲分块拷回主机，不额外占用显存，多 GB 级别的状态也能稳定落盘。

断点续训的前提：先开启 save_full_checkpoint

这是新手最容易踩的坑 ⚠️

• 默认情况（save_full_checkpoint = false）：checkpoint 只保存推理/外观参数和splat.ply，不含世界高斯参数与优化器状态，无法恢复训练。
• 开启--save-full-checkpoint 1后，存档才会额外写入全部世界参数与优化器状态，成为"可续训"的完整 checkpoint。

恢复前程序会做资格检查（check_resumable，见 src/checkpoint/Resume.cpp）：若检测到该存档不可续训，会提前报出清晰错误并提示你重跑源训练时加上--save-full-checkpoint 1，而不是加载到一半才失败。这类存档仍然可用于推理和建网格。

💡 建议：任何预计要分阶段完成、或可能中途调整的长训练，都从启动就开启该开关。

一键恢复：--resume 的两种用法

恢复入口是--resume参数（解析与配置合并逻辑见 src/checkpoint/Resume.h 和 src/app/TrainerCore.cpp），支持两种写法：

1️⃣ 指向运行目录 —— 自动选最新存档

./build_vulkan/spirula train --resume outputs/myrun-20260925

程序会按step-*命名规则找到该目录下编号最大的 checkpoint（数字填充命名保证字典序即数值序，见 src/checkpoint/Resume.cpp）。

2️⃣ 指向具体存档 —— 精确回退到某一步

./build_vulkan/spirula train --resume outputs/myrun-20260925/step-000030000.ckpt

恢复时的配置合并规则

续训不是"盲恢复"，配置按以下优先级分层叠加：

1. checkpoint 自带的config.json作为基础——它记录了当初架构参数，因此续训时甚至不需要再传--data；
2. 输出目录默认回到原 run 文件夹，新存档、评估图与日志和旧的一起存放；
3. 命令行上指定的 preset 会重新施加其覆盖项；
4. 显式传入的命令行参数优先级最高（程序记录的是"你实际敲了哪些参数"，而非与默认值比较，因此把某项改回默认值也生效）。

恢复动作本身发生在引擎骨架搭建完成后：按state.json重建优化器布局，再逐块把.npy拷回 GPU，步数从存档处继续，优化器动量、学习率状态完整延续。

想改参数布局？checkpoint 会自动适配

续训时如果改变了模型布局，Spirula Studio 也能处理，适配逻辑在 src/checkpoint/Adapt.cpp：

• 调小cap_max：优先丢弃尾部未饱和的高斯，再按最低不透明度淘汰，其余参数无损迁移；
• 更换sh_degree、增删 bilagrid / PPISP 通道：缓冲在主机侧重写为目标布局，全程不分配显存——这正是为"上次训练显存爆了、换个更小布局续训"的场景设计的；
• 量化缓冲会经过引擎自己的编解码器解码再重编码，与训练核共用同一份代码路径。

适配完成后，引擎拿到的就是一个普通的state.tar，后续流程与同布局续训完全一致。

顺便区分：--init-ply 热启动 ≠ 断点续训

--init-ply <file.ply|run_dir|step-*.ckpt>用已训练好的 PLY 作为初始高斯启动全新训练：步数从 0 开始、优化器从零起步。适合数据集扩充后在旧模型上继续精修；而--resume才是"原封不动接着练"。两者同时给出时--resume优先并给出提示。

常见问题速查

小结

掌握 Spirula Studio 的断点续训只需要记住三步：

1. 训练前：预计长训练就加--save-full-checkpoint 1，这是续训的门票；
2. 中断时：随时Ctrl+C或 GUI 停止——每 2000 步（可调）的自动存档是天然的安全网；
3. 恢复时：--resume指向 run 目录（最新）或具体step-*.ckpt（定点），配置自动合并，布局变更还能自适应重写。

更多细节可参阅官方文档索引 docs/README.md 与应用说明 src/app/README.md 中的 Resume 章节，让长训练从此没有"从头再来"。

【免费下载链接】spirula-studioCross-vendor 3D Gaussian Splatting trainer - video to splat to mesh, Vulkan or CUDA.项目地址: https://gitcode.com/GitHub_Trending/sp/spirula-studio