Burn 框架 Record 机制与 burnpack 序列化格式深度解析【免费下载链接】burnBurn is a next generation tensor library and Deep Learning Framework that doesnt compromise on flexibility, efficiency and portability.项目地址: https://gitcode.com/GitHub_Trending/bu/burn导读本文围绕 Burn 深度学习框架的Record记录机制展开讲解训练状态如何以与后端解耦的纯张量数据形式被保存与加载并深入剖析其底层容器格式burnpack.bpk的三段式文件结构。读完本文你将掌握ModuleRecord、OptimizerRecord、LrSchedulerRecord三种记录类型的使用方法含save/load与内存字节缓冲两种 I/O 路径、加载期行为配置部分加载、校验开关、dtype 策略以及如何借助Learner检查点机制自动完成训练中断与恢复——同时理解这些 API 背后burn-core、burn-pack、burn-optim各 crate 的源码实现。一、Record 是什么训练状态的可移植快照在 Burn 中Record 是训练状态模型参数、优化器状态、学习率调度器状态的序列化载体。它的核心设计有两点与后端解耦Record 持有的是纯张量数据TensorData而不是绑定在某个后端上的张量对象。因此用burn-cuda训练保存的权重可以直接加载到burn-ndarray或burn-wgpu上运行无需任何转换。参数初始化保持惰性加载 Record 时并不真正触发张量分配或内核执行只是把参数值登记到模块上实际计算要等到模块真正被使用才发生详见下文从记录的权重初始化一节。所有 Record 统一序列化为burnpack格式扩展名.bpk该格式由独立的burn-packcrate 实现。burn-pack刻意保持极简且与张量库无关它只依赖burn-std提供DType/Bytes、serde和一个 CBOR 编解码器本身并不理解 Burn 的模块或张量概念而是由上层如burn-core在Tensor条目与自身记录类型之间做桥接见 crates/burn-pack/src/lib.rs 的 crate 文档。从源码结构看crates/burn-core/src/store/mod.rs 的模块文档burn-core中的 Record 系统被刻意设计得小而直白通过ModuleVisitor/ModuleMapper按参数路径遍历模块不做过滤、适配器或惰性快照——更丰富的快照与导入工具过滤、键重映射、PyTorch/SafeTensors 适配器、跨框架存储全部集中在burn-storecrate 中。二、burnpack 文件格式三段式二进制容器一个 burnpack 文件由三个部分组成所有多字节整数均为小端序组成部分内容说明固定大小头部Header10 字节魔数BURN0x4255524E、格式版本u16、元数据长度u32头部各字段字节范围由magic_range()、version_range()、metadata_size_range()定义元数据块CBOR每个张量的描述名称、dtype、shape、数据偏移、可选参数 id、任意命名类型化标量、用户自定义 key/value 对使用 CBOR 序列化长度记录在头部张量数据区每个张量的原始字节起始位置对齐到256 字节边界支持零拷贝 / 内存映射mmap读取对应实现位于 crates/burn-pack/src/base.rsMAGIC_NUMBER: u32 0x4255524E即 ASCII 的BURN写成小端字节时文件里呈现为NRUBFORMAT_VERSION: u16 0x0001HEADER_SIZE 4 2 4 10字节TENSOR_ALIGNMENT: u64 256数据区起点通过aligned_data_section_start(metadata_size)计算确保所有张量偏移相对数据区换算成绝对文件位置后依然满足 256 字节对齐。为什么是 256 字节对齐对齐到 256 字节边界带来多重收益见base.rs中TENSOR_ALIGNMENT的注释满足所有元素类型的指针对齐要求如f64需要 8 字节对齐缓存行友好主流 CPU 缓存行为 64 字节GPU 合并访存友好CUDA 偏好 256 字节对齐为更宽的 SIMD 预留空间AVX-512 为 64 字节未来的 AVX-1024 为 128 字节与业界主流格式保持一致GGUF、MLX、ncnn、MNN、TNN、vLLM-AWQ、Marlin 等 15 格式均采用 256 字节对齐而 SafeTensors 采用 64 字节AVX-512 最低要求Core ML 采用 4096 字节。256 字节对齐对典型张量尺寸而言开销可忽略不计同时最大程度兼容当前与未来的硬件。元数据中的类型化标量Scalarburnpack 的元数据区不仅描述张量还支持存储命名类型化标量——包括有符号整数、无符号整数、浮点数、布尔值Scalar枚举的Int(i64)、UInt(u64)、Float(f64)、Bool(bool)四个变体。标量存放在 CBOR 元数据区而非张量数据区因此不产生对齐开销。正是这一能力让优化器和学习率调度器能够把非张量状态步数计数器、当前学习率、动量超参数等用同一种格式持久化。对于纯标量状态Scalar的转换是类型安全的例如i32::try_from(Scalar::from(-5i32))可以成功但u8::try_from(Scalar::from(300u32))会因超出范围而失败i64::try_from(Scalar::Float(1.5))会因变体不匹配而失败相关测试见base.rs的scalar_tests模块。内置安全限制为防止恶意或损坏的输入导致资源耗尽burnpack 读取端在分配内存前会拒绝超出以下任一上限的文件见 crates/burn-pack/src/lib.rs 的Safety limits一节常量限制值目的MAX_METADATA_SIZE100 MB防止过大的元数据声明耗尽内存MAX_TENSOR_COUNT100,000防止过多张量导致资源耗尽MAX_TENSOR_SIZE32 位平台 2 GB / 64 位平台 10 GB防止单个张量声明过大MAX_CBOR_RECURSION_DEPTH128 层防止深层 CBOR 嵌套导致栈溢出MAX_FILE_SIZE100 GB仅 std文件加载器的文件大小上限同时读取器还会校验文件大小是否足以容纳其声明的每个张量否则返回Error::ValidationError。延迟张量字节写入值得一提的实现细节张量的字节并不需要在写入时已经存在。Reader只在访问时才从数据源读取张量字节而调用方如果已知张量长度却尚未持有其数据例如模块快照、ONNX 初始化器可以用Tensor::deferred构造条目把大于宿主内存的模型流式写入文件相关契约见 crates/burn-pack/src/lib.rs 的 crate 文档。三、三种 Record 类型Burn 将训练状态划分为三类 Record分别对应训练中三个不同角色的持久化需求Record持有内容产生方式ModuleRecord模块的参数module.into_record()OptimizerRecord优化器状态optimizer.to_record()LrSchedulerRecord学习率调度器状态scheduler.to_record()每种 Record 都支持两条 I/O 路径文件路径save(path)/load(path)——当路径没有扩展名时自动追加.bpk内存字节缓冲into_bytes()/from_bytes(bytes)——对no-std部署特别有用字节可以被include_bytes!直接嵌入编译产物例如 examples/mnist-inference-web 中嵌入model.bpk的做法。四、ModuleRecord模块参数的保存与加载ModuleRecord位于burn::store以模块内参数路径为键持有模块的参数。在源码中每个被记录的张量是一个RecordTensor { path, id, data }三元组crates/burn-core/src/store/mod.rspath是模块内的点分路径id是参数 idParamIddata是TensorData。它通过Moduletrait 自身产生和应用use burn::store::ModuleRecord; // 取出记录并保存写出 model.bpk model.into_record().save(model)?; // writes model.bpk // 加载回来并应用到已初始化的模块 let record ModuleRecord::load(model)?; let model ModelConfig::new().init(device).load_record(record);收集与回放的实现原理收集方向ModuleRecord::from_module通过Collector实现ModuleVisitor在enter_module/exit_module时维护路径栈遇到Float/Int/Bool参数时调用record()把(路径, 参数id, 张量数据)压入列表。注意它记录的是参数的保存形态transform_for_save这正是加载端校验与回放所依据的形态——对于像Col布局Linear权重这种通过 mapper 改变形状的参数这一选择保证了形状映射参数能正确往返有专门的round_trip_a_shape_mapped_param测试佐证。回放方向ModuleRecord::apply通过ModuleRecordMapper实现ModuleMapper按模块路径查找记录中的张量命中则把张量装载回参数同时恢复持久化的ParamId。这一点很关键优化器状态是按ParamId索引的恢复参数 id 才能让优化器状态在保存/加载循环后依然有效对应load_record_preserves_param_id测试。加载期行为配置保存时忽略ModuleRecord提供一组 builder 方法用于配置加载时的行为这些设置在保存时被忽略.allow_partial(true)—— 即使记录中缺少某些模块参数也允许加载例如加载用into_record_group取得的局部记录或把旧版本 checkpoint 加载到新增了层的新模型上.allow_unused(true)—— 允许记录中含有匹配不到任何模块参数的张量。它与allow_partial互为镜像默认被拒绝一条落不到任何位置的记录条目意味着目标模块并非该记录来源看似成功的加载其实静默少做了事情。仅在明确场景下放开——把 checkpoint 加载到它来源模块的一部分上.validate(false)—— 跳过形状不匹配 / 张量缺失的校验.cast_to_module_dtype()/.with_dtype_policy(..)—— 加载时把记录数据转换为模块参数的 dtype默认策略是参数采用记录的 dtype。对应的DTypePolicy枚举定义了两个变体crates/burn-core/src/store/mod.rs策略行为FromRecord默认模块参数采用记录的 dtype数据原样加载CastToModule记录数据在加载时转换为模块参数当前的 dtype会物化目标参数以读取其 dtype// 允许部分加载 转换为模块 dtype let model ModelConfig::new() .init(device) .load_record(record.allow_partial(true).cast_to_module_dtype());保存侧 dtype 不可配置保存侧的 dtype 是不可配置的记录保存的是模块当前持有的 dtype。若要控制加载时的 dtype有两个入口保存前调用model.cast(dtype)让记录直接保存目标 dtype加载时使用.cast_to_module_dtype()/.with_dtype_policy(..)做转换。store/mod.rs的测试给出了两种策略的行为差异记录保存 f32 数据目标模块参数是 f64——默认策略FromRecord加载后参数保持 f32数据原样而.cast_to_module_dtype()会把 f32 数据转换为 f64 并保持数值不变。失败处理try_load_recordload_record在校验失败时会 panic需要可失败语义时使用try_load_record它返回ResultSelf, RecordError。RecordError有两个变体Io(String)—— 读写记录时的 I/O 或格式错误由burn_pack::Error转换而来Validation(String)—— 应用记录时校验失败形状不匹配、不允许部分加载时张量缺失、不允许未使用条目时记录张量无参数匹配。match model.clone().try_load_record(record) { Ok(model) { /* 加载成功 */ } Err(e) eprintln!(加载失败: {e}), }从源码看apply的校验逻辑会汇总三类问题errors形状不匹配、missing缺失张量、unused记录中无参数匹配的条目排序后命名输出分别由validate、allow_partial、allow_unused三个开关控制是否放行。用into_record_group记录模块的局部当只需要记录模块的某一部分参数时可以用into_record_group(ParamGroup)。从Collector的实现看ParamGroup会在读取参数数据之前就过滤掉不匹配的参数因此一个组的记录永远不会物化模块的其余部分crates/burn-core/src/module/base.rs 中into_record_group的文档。对应的测试验证只记录weight组的记录应用回完整模块时weight落地、bias保持原初始化值且需配合.allow_partial(true)使用。从记录的权重初始化一个实用技巧由于参数初始化是惰性的init(device)后紧跟load_record(record)并不会产生实际的张量分配与 GPU/CPU 内核执行开销。因此完全可以用Model::init(device).load_record(record)这种先初始化再覆盖的方式加载权重而不必担心性能代价。更完整的保存/加载流程见 Burn 中的模型保存与加载。五、OptimizerRecord与LrSchedulerRecord检查点与恢复训练优化器和学习率调度器暴露了形状相同的 API用于训练检查点与恢复// 优化器状态加载时无需设备状态会在下一步迁移到每个参数的设备上 optimizer.save(optim)?; let optimizer optimizer.load(optim)?; // 学习率调度器状态仅标量 scheduler.to_record().save(scheduler)?; let scheduler scheduler.load_record(LrSchedulerRecord::load(scheduler)?);OptimizerRecord按参数键控的状态分解与按模块路径键控的ModuleRecord不同OptimizerRecord按参数ParamId键控crates/burn-optim/src/optim/module/record/mod.rs每个参数的优化器状态被分解为名为{param_id}.{field}的张量携带来源param_id外加若干存放在 burnpack 标量图中的类型化标量条目结构包含tensors状态张量、scalars类型化标量、paths元数据字符串映射。从ModuleOptimizer::to_record取到记录后同样支持save/load文件与into_bytes/from_bytes内存。加载时不需要设备状态张量会在优化器下一步step时迁移到每个参数所在的设备上。LrSchedulerRecord纯标量状态学习率调度器的状态只是少量标量步数计数器、当前学习率等因此LrSchedulerRecord的 burnpack 记录只含命名类型化标量、不含张量crates/burn-optim/src/lr_scheduler/base.rswith_scalar(key, value)/scalar(key)读写单个标量组合式调度器如ComposedLrScheduler通过with_record(prefix, record)/record(prefix)以索引前缀嵌套子调度器的记录from_state/into_state复用与优化器状态相同的RecordState分解机制state_flatten/state_unflatten并在 debug 构建中断言不会产生张量叶子节点——调度器状态应为纯标量这一不变量由代码强制保证。lr_scheduler/base.rs的测试工具check_save_load验证了保存/加载往返的正确语义先推进若干步保存并重新加载记录后调度器必须从离开的位置继续产生与未保存副本完全一致的学习率序列。Learner自动检查点当使用Learner训练时上述三类记录由检查点机制checkpointer自动保存与恢复无需手工管理。相关用法详见 Learner 指南LearnerConfig的num_epochs、checkpoint配置与save/load流程可参考 crates/burn-train/src/learner/base.rs 及 crates/burn-train/src/checkpoint 目录下的实现。六、跨框架格式burn-storeModuleRecordAPI 适用于基本的保存/加载但以下高级需求需要使用burn-storecrate基于同一 burnpack 格式从其他生态导入权重PyTorch.pt/.pth只读、SafeTensors.safetensors更高级的 store 功能键重映射with_key_remapping/KeyRemapper、过滤with_regex/with_full_path、半精度存储HalfPrecisionAdapter、零拷贝内存映射加载、部分加载与ApplyResult结构化结果检查、模型手术快照收集与重放。例如从 PyTorch 加载并重映射键名use burn_store::{ModuleSnapshot, PytorchStore}; let mut model MyModel::init(device); let mut store PytorchStore::from_file(pytorch_model.pt) .with_top_level_key(state_dict) .with_key_remapping(r^model\., ); model.load_from(mut store)?;完整的示例含 PyTorch 导出注意事项、SafeTensors 适配器、元数据写入、大模型流式保存、非连续层索引映射等见 Burn 中的模型保存与加载对应实现位于 crates/burn-store其pytorch-tests与safetensors-tests目录包含与 PyTorch 导出脚本对应的端到端测试。仓库中的可运行示例还包括 examples/import-model-weightsPyTorch/SafeTensors 权重导入与 examples/mnist-inference-web.bpk模型嵌入 WebAssembly 推理。七、典型工作流总结保存模型model.into_record().save(model)—— 得到model.bpk加载模型Model::init(device).load_record(ModuleRecord::load(model)?)迁移精度保存前model.cast(dtype)或加载时record.cast_to_module_dtype()部分加载record.allow_partial(true)配合try_load_record断点续训用Learner检查点自动持久化ModuleRecordOptimizerRecordLrSchedulerRecord三类状态嵌入式 / no-stdinto_bytes()/from_bytes()在内存中完成序列化字节可嵌入编译产物跨框架互操作通过burn-store的PytorchStore/SafetensorsStore导入导出权重。无论选择哪条路径底层都是同一种紧凑、可零拷贝读取、具备安全上限校验的 burnpack 容器——这正是 Burn 训练状态可移植、可恢复、可互操作的根基。【免费下载链接】burnBurn is a next generation tensor library and Deep Learning Framework that doesnt compromise on flexibility, efficiency and portability.项目地址: https://gitcode.com/GitHub_Trending/bu/burn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Burn 框架 Record 机制与 burnpack 序列化格式深度解析
Burn 框架 Record 机制与 burnpack 序列化格式深度解析【免费下载链接】burnBurn is a next generation tensor library and Deep Learning Framework that doesnt compromise on flexibility, efficiency and portability.项目地址: https://gitcode.com/GitHub_Trending/bu/burn导读本文围绕 Burn 深度学习框架的Record记录机制展开讲解训练状态如何以与后端解耦的纯张量数据形式被保存与加载并深入剖析其底层容器格式burnpack.bpk的三段式文件结构。读完本文你将掌握ModuleRecord、OptimizerRecord、LrSchedulerRecord三种记录类型的使用方法含save/load与内存字节缓冲两种 I/O 路径、加载期行为配置部分加载、校验开关、dtype 策略以及如何借助Learner检查点机制自动完成训练中断与恢复——同时理解这些 API 背后burn-core、burn-pack、burn-optim各 crate 的源码实现。一、Record 是什么训练状态的可移植快照在 Burn 中Record 是训练状态模型参数、优化器状态、学习率调度器状态的序列化载体。它的核心设计有两点与后端解耦Record 持有的是纯张量数据TensorData而不是绑定在某个后端上的张量对象。因此用burn-cuda训练保存的权重可以直接加载到burn-ndarray或burn-wgpu上运行无需任何转换。参数初始化保持惰性加载 Record 时并不真正触发张量分配或内核执行只是把参数值登记到模块上实际计算要等到模块真正被使用才发生详见下文从记录的权重初始化一节。所有 Record 统一序列化为burnpack格式扩展名.bpk该格式由独立的burn-packcrate 实现。burn-pack刻意保持极简且与张量库无关它只依赖burn-std提供DType/Bytes、serde和一个 CBOR 编解码器本身并不理解 Burn 的模块或张量概念而是由上层如burn-core在Tensor条目与自身记录类型之间做桥接见 crates/burn-pack/src/lib.rs 的 crate 文档。从源码结构看crates/burn-core/src/store/mod.rs 的模块文档burn-core中的 Record 系统被刻意设计得小而直白通过ModuleVisitor/ModuleMapper按参数路径遍历模块不做过滤、适配器或惰性快照——更丰富的快照与导入工具过滤、键重映射、PyTorch/SafeTensors 适配器、跨框架存储全部集中在burn-storecrate 中。二、burnpack 文件格式三段式二进制容器一个 burnpack 文件由三个部分组成所有多字节整数均为小端序组成部分内容说明固定大小头部Header10 字节魔数BURN0x4255524E、格式版本u16、元数据长度u32头部各字段字节范围由magic_range()、version_range()、metadata_size_range()定义元数据块CBOR每个张量的描述名称、dtype、shape、数据偏移、可选参数 id、任意命名类型化标量、用户自定义 key/value 对使用 CBOR 序列化长度记录在头部张量数据区每个张量的原始字节起始位置对齐到256 字节边界支持零拷贝 / 内存映射mmap读取对应实现位于 crates/burn-pack/src/base.rsMAGIC_NUMBER: u32 0x4255524E即 ASCII 的BURN写成小端字节时文件里呈现为NRUBFORMAT_VERSION: u16 0x0001HEADER_SIZE 4 2 4 10字节TENSOR_ALIGNMENT: u64 256数据区起点通过aligned_data_section_start(metadata_size)计算确保所有张量偏移相对数据区换算成绝对文件位置后依然满足 256 字节对齐。为什么是 256 字节对齐对齐到 256 字节边界带来多重收益见base.rs中TENSOR_ALIGNMENT的注释满足所有元素类型的指针对齐要求如f64需要 8 字节对齐缓存行友好主流 CPU 缓存行为 64 字节GPU 合并访存友好CUDA 偏好 256 字节对齐为更宽的 SIMD 预留空间AVX-512 为 64 字节未来的 AVX-1024 为 128 字节与业界主流格式保持一致GGUF、MLX、ncnn、MNN、TNN、vLLM-AWQ、Marlin 等 15 格式均采用 256 字节对齐而 SafeTensors 采用 64 字节AVX-512 最低要求Core ML 采用 4096 字节。256 字节对齐对典型张量尺寸而言开销可忽略不计同时最大程度兼容当前与未来的硬件。元数据中的类型化标量Scalarburnpack 的元数据区不仅描述张量还支持存储命名类型化标量——包括有符号整数、无符号整数、浮点数、布尔值Scalar枚举的Int(i64)、UInt(u64)、Float(f64)、Bool(bool)四个变体。标量存放在 CBOR 元数据区而非张量数据区因此不产生对齐开销。正是这一能力让优化器和学习率调度器能够把非张量状态步数计数器、当前学习率、动量超参数等用同一种格式持久化。对于纯标量状态Scalar的转换是类型安全的例如i32::try_from(Scalar::from(-5i32))可以成功但u8::try_from(Scalar::from(300u32))会因超出范围而失败i64::try_from(Scalar::Float(1.5))会因变体不匹配而失败相关测试见base.rs的scalar_tests模块。内置安全限制为防止恶意或损坏的输入导致资源耗尽burnpack 读取端在分配内存前会拒绝超出以下任一上限的文件见 crates/burn-pack/src/lib.rs 的Safety limits一节常量限制值目的MAX_METADATA_SIZE100 MB防止过大的元数据声明耗尽内存MAX_TENSOR_COUNT100,000防止过多张量导致资源耗尽MAX_TENSOR_SIZE32 位平台 2 GB / 64 位平台 10 GB防止单个张量声明过大MAX_CBOR_RECURSION_DEPTH128 层防止深层 CBOR 嵌套导致栈溢出MAX_FILE_SIZE100 GB仅 std文件加载器的文件大小上限同时读取器还会校验文件大小是否足以容纳其声明的每个张量否则返回Error::ValidationError。延迟张量字节写入值得一提的实现细节张量的字节并不需要在写入时已经存在。Reader只在访问时才从数据源读取张量字节而调用方如果已知张量长度却尚未持有其数据例如模块快照、ONNX 初始化器可以用Tensor::deferred构造条目把大于宿主内存的模型流式写入文件相关契约见 crates/burn-pack/src/lib.rs 的 crate 文档。三、三种 Record 类型Burn 将训练状态划分为三类 Record分别对应训练中三个不同角色的持久化需求Record持有内容产生方式ModuleRecord模块的参数module.into_record()OptimizerRecord优化器状态optimizer.to_record()LrSchedulerRecord学习率调度器状态scheduler.to_record()每种 Record 都支持两条 I/O 路径文件路径save(path)/load(path)——当路径没有扩展名时自动追加.bpk内存字节缓冲into_bytes()/from_bytes(bytes)——对no-std部署特别有用字节可以被include_bytes!直接嵌入编译产物例如 examples/mnist-inference-web 中嵌入model.bpk的做法。四、ModuleRecord模块参数的保存与加载ModuleRecord位于burn::store以模块内参数路径为键持有模块的参数。在源码中每个被记录的张量是一个RecordTensor { path, id, data }三元组crates/burn-core/src/store/mod.rspath是模块内的点分路径id是参数 idParamIddata是TensorData。它通过Moduletrait 自身产生和应用use burn::store::ModuleRecord; // 取出记录并保存写出 model.bpk model.into_record().save(model)?; // writes model.bpk // 加载回来并应用到已初始化的模块 let record ModuleRecord::load(model)?; let model ModelConfig::new().init(device).load_record(record);收集与回放的实现原理收集方向ModuleRecord::from_module通过Collector实现ModuleVisitor在enter_module/exit_module时维护路径栈遇到Float/Int/Bool参数时调用record()把(路径, 参数id, 张量数据)压入列表。注意它记录的是参数的保存形态transform_for_save这正是加载端校验与回放所依据的形态——对于像Col布局Linear权重这种通过 mapper 改变形状的参数这一选择保证了形状映射参数能正确往返有专门的round_trip_a_shape_mapped_param测试佐证。回放方向ModuleRecord::apply通过ModuleRecordMapper实现ModuleMapper按模块路径查找记录中的张量命中则把张量装载回参数同时恢复持久化的ParamId。这一点很关键优化器状态是按ParamId索引的恢复参数 id 才能让优化器状态在保存/加载循环后依然有效对应load_record_preserves_param_id测试。加载期行为配置保存时忽略ModuleRecord提供一组 builder 方法用于配置加载时的行为这些设置在保存时被忽略.allow_partial(true)—— 即使记录中缺少某些模块参数也允许加载例如加载用into_record_group取得的局部记录或把旧版本 checkpoint 加载到新增了层的新模型上.allow_unused(true)—— 允许记录中含有匹配不到任何模块参数的张量。它与allow_partial互为镜像默认被拒绝一条落不到任何位置的记录条目意味着目标模块并非该记录来源看似成功的加载其实静默少做了事情。仅在明确场景下放开——把 checkpoint 加载到它来源模块的一部分上.validate(false)—— 跳过形状不匹配 / 张量缺失的校验.cast_to_module_dtype()/.with_dtype_policy(..)—— 加载时把记录数据转换为模块参数的 dtype默认策略是参数采用记录的 dtype。对应的DTypePolicy枚举定义了两个变体crates/burn-core/src/store/mod.rs策略行为FromRecord默认模块参数采用记录的 dtype数据原样加载CastToModule记录数据在加载时转换为模块参数当前的 dtype会物化目标参数以读取其 dtype// 允许部分加载 转换为模块 dtype let model ModelConfig::new() .init(device) .load_record(record.allow_partial(true).cast_to_module_dtype());保存侧 dtype 不可配置保存侧的 dtype 是不可配置的记录保存的是模块当前持有的 dtype。若要控制加载时的 dtype有两个入口保存前调用model.cast(dtype)让记录直接保存目标 dtype加载时使用.cast_to_module_dtype()/.with_dtype_policy(..)做转换。store/mod.rs的测试给出了两种策略的行为差异记录保存 f32 数据目标模块参数是 f64——默认策略FromRecord加载后参数保持 f32数据原样而.cast_to_module_dtype()会把 f32 数据转换为 f64 并保持数值不变。失败处理try_load_recordload_record在校验失败时会 panic需要可失败语义时使用try_load_record它返回ResultSelf, RecordError。RecordError有两个变体Io(String)—— 读写记录时的 I/O 或格式错误由burn_pack::Error转换而来Validation(String)—— 应用记录时校验失败形状不匹配、不允许部分加载时张量缺失、不允许未使用条目时记录张量无参数匹配。match model.clone().try_load_record(record) { Ok(model) { /* 加载成功 */ } Err(e) eprintln!(加载失败: {e}), }从源码看apply的校验逻辑会汇总三类问题errors形状不匹配、missing缺失张量、unused记录中无参数匹配的条目排序后命名输出分别由validate、allow_partial、allow_unused三个开关控制是否放行。用into_record_group记录模块的局部当只需要记录模块的某一部分参数时可以用into_record_group(ParamGroup)。从Collector的实现看ParamGroup会在读取参数数据之前就过滤掉不匹配的参数因此一个组的记录永远不会物化模块的其余部分crates/burn-core/src/module/base.rs 中into_record_group的文档。对应的测试验证只记录weight组的记录应用回完整模块时weight落地、bias保持原初始化值且需配合.allow_partial(true)使用。从记录的权重初始化一个实用技巧由于参数初始化是惰性的init(device)后紧跟load_record(record)并不会产生实际的张量分配与 GPU/CPU 内核执行开销。因此完全可以用Model::init(device).load_record(record)这种先初始化再覆盖的方式加载权重而不必担心性能代价。更完整的保存/加载流程见 Burn 中的模型保存与加载。五、OptimizerRecord与LrSchedulerRecord检查点与恢复训练优化器和学习率调度器暴露了形状相同的 API用于训练检查点与恢复// 优化器状态加载时无需设备状态会在下一步迁移到每个参数的设备上 optimizer.save(optim)?; let optimizer optimizer.load(optim)?; // 学习率调度器状态仅标量 scheduler.to_record().save(scheduler)?; let scheduler scheduler.load_record(LrSchedulerRecord::load(scheduler)?);OptimizerRecord按参数键控的状态分解与按模块路径键控的ModuleRecord不同OptimizerRecord按参数ParamId键控crates/burn-optim/src/optim/module/record/mod.rs每个参数的优化器状态被分解为名为{param_id}.{field}的张量携带来源param_id外加若干存放在 burnpack 标量图中的类型化标量条目结构包含tensors状态张量、scalars类型化标量、paths元数据字符串映射。从ModuleOptimizer::to_record取到记录后同样支持save/load文件与into_bytes/from_bytes内存。加载时不需要设备状态张量会在优化器下一步step时迁移到每个参数所在的设备上。LrSchedulerRecord纯标量状态学习率调度器的状态只是少量标量步数计数器、当前学习率等因此LrSchedulerRecord的 burnpack 记录只含命名类型化标量、不含张量crates/burn-optim/src/lr_scheduler/base.rswith_scalar(key, value)/scalar(key)读写单个标量组合式调度器如ComposedLrScheduler通过with_record(prefix, record)/record(prefix)以索引前缀嵌套子调度器的记录from_state/into_state复用与优化器状态相同的RecordState分解机制state_flatten/state_unflatten并在 debug 构建中断言不会产生张量叶子节点——调度器状态应为纯标量这一不变量由代码强制保证。lr_scheduler/base.rs的测试工具check_save_load验证了保存/加载往返的正确语义先推进若干步保存并重新加载记录后调度器必须从离开的位置继续产生与未保存副本完全一致的学习率序列。Learner自动检查点当使用Learner训练时上述三类记录由检查点机制checkpointer自动保存与恢复无需手工管理。相关用法详见 Learner 指南LearnerConfig的num_epochs、checkpoint配置与save/load流程可参考 crates/burn-train/src/learner/base.rs 及 crates/burn-train/src/checkpoint 目录下的实现。六、跨框架格式burn-storeModuleRecordAPI 适用于基本的保存/加载但以下高级需求需要使用burn-storecrate基于同一 burnpack 格式从其他生态导入权重PyTorch.pt/.pth只读、SafeTensors.safetensors更高级的 store 功能键重映射with_key_remapping/KeyRemapper、过滤with_regex/with_full_path、半精度存储HalfPrecisionAdapter、零拷贝内存映射加载、部分加载与ApplyResult结构化结果检查、模型手术快照收集与重放。例如从 PyTorch 加载并重映射键名use burn_store::{ModuleSnapshot, PytorchStore}; let mut model MyModel::init(device); let mut store PytorchStore::from_file(pytorch_model.pt) .with_top_level_key(state_dict) .with_key_remapping(r^model\., ); model.load_from(mut store)?;完整的示例含 PyTorch 导出注意事项、SafeTensors 适配器、元数据写入、大模型流式保存、非连续层索引映射等见 Burn 中的模型保存与加载对应实现位于 crates/burn-store其pytorch-tests与safetensors-tests目录包含与 PyTorch 导出脚本对应的端到端测试。仓库中的可运行示例还包括 examples/import-model-weightsPyTorch/SafeTensors 权重导入与 examples/mnist-inference-web.bpk模型嵌入 WebAssembly 推理。七、典型工作流总结保存模型model.into_record().save(model)—— 得到model.bpk加载模型Model::init(device).load_record(ModuleRecord::load(model)?)迁移精度保存前model.cast(dtype)或加载时record.cast_to_module_dtype()部分加载record.allow_partial(true)配合try_load_record断点续训用Learner检查点自动持久化ModuleRecordOptimizerRecordLrSchedulerRecord三类状态嵌入式 / no-stdinto_bytes()/from_bytes()在内存中完成序列化字节可嵌入编译产物跨框架互操作通过burn-store的PytorchStore/SafetensorsStore导入导出权重。无论选择哪条路径底层都是同一种紧凑、可零拷贝读取、具备安全上限校验的 burnpack 容器——这正是 Burn 训练状态可移植、可恢复、可互操作的根基。【免费下载链接】burnBurn is a next generation tensor library and Deep Learning Framework that doesnt compromise on flexibility, efficiency and portability.项目地址: https://gitcode.com/GitHub_Trending/bu/burn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考