Tech-Renaissance API 参考文档

概述

单人团队以 AI 技术开发的超轻量级高性能深度学习训练框架。

Tech-Renaissance 采用静态图编译执行、CUDA Graph 全捕获、FP16 AMP 混合精度训练、分布式数据并行等先进技术，在训练吞吐量上相比传统深度学习框架具有显著优势。在 A100 × 8 平台上，VGG16BN 训练吞吐量比 PyTorch + torch.compile 快 26.65%；在七个不同 GPU 平台上，MLP 训练加速比达到 6.90x - 13.58x。

本文档为 Tech-Renaissance V4.20.692 的完整 API 参考，涵盖七大核心模块的所有公开接口。

版本：V4.20.692

依赖项

配置与运行

推荐以 Docker 容器方式运行，可确保环境一致并省去手动安装依赖的步骤。

# 1. 克隆项目
mkdir -p /opt/tr4 && cd /opt/tr4
git clone https://gitee.com/tech-renaissance/renaissance.git

# 2. 拉取镜像并启动容器
docker pull crpi-vbtd6yj00u83ugqk.cn-beijing.personal.cr.aliyuncs.com/tech-renaissance/tr4:v4.20
docker run -d -it --name tr4-dev --gpus all --cap-add SYS_NICE -v /opt/tr4:/opt/tr4 -w /opt/tr4 \
    crpi-vbtd6yj00u83ugqk.cn-beijing.personal.cr.aliyuncs.com/tech-renaissance/tr4:v4.20 \
    tail -f /dev/null
docker exec -it tr4-dev bash

# 3. 配置与编译
cd /opt/tr4/renaissance && python configure.py
./build.sh

# 4. 运行示例
/opt/tr4/renaissance/build/bin/tests/example/mlp_mnist

注意：configure.py 会从当前环境自动查找依赖并生成编译脚本。若不使用 Docker，需手动安装所有依赖项（见上表）并确保 GPU 驱动、CUDA、NVIDIA Container Toolkit 已正确配置。

代码示例

以下示例展示从引入头文件到完成训练的最短路径（训练 MLP 至 99.4% 以上的 MNIST 准确率）：

#include <renaissance.h>

using namespace tr;

int main() {
    // 1. 全局训练环境配置
    GLOBAL_SETTING
        .use_gpu("0")          // 使用 GPU 0
        .amp(true)             // 启用 FP16 自动混合精度训练
        .manual_seed(123)      // 固定随机种子，保证结果可复现
        .global_batch_size(200)
        .input_resolution(28);

    // 2. 数据预处理配置
    PREPROCESSOR_SETTING
        .dataset("mnist", std::string(TR_PROJECT_ROOT) + "/data/mnist")
        .download(true)
        .preprocess_workers(8)
        .normalization(NormMode::MNIST)
        .train_transforms(
            Pad(2),
            RandomCrop(28),
            RandomRotation(20.0f, 0),
            RandomScale(0.8f, 1.2f),
            RandomErasing(0.5f)
        )
        .commit();

    // 3. 模型定义：4 层 MLP
    //    输入 [28, 28] -> Flatten -> 1024 -> 512 -> 256 -> 10 (SoftmaxCE)
    BluePrint mlp = seq(
        fc(1024, true), relu(),
        fc(512, true), relu(),
        fc(256, true), relu(),
        fc(10, true)
    );

    constexpr int kTotalEpochs = 100;

    // 4. 训练任务配置
    DeepLearningTask task;
    task.model(mlp)
        .loss(CrossEntropyLoss().label_smoothing(0.1f))
        .total_epochs(kTotalEpochs)
        .optimizer(AdamW().weight_decay(1e-4f))
        .scheduler(CosineAnnealingLR().base_lr(0.001f).warmup(5));

    // 编译：默认仅打印 ArchPlan，适合普通用户快速查看模型结构。
    // 需要调试时，可改为 task.compile(CompileInfo::ALL);
    task.compile();

    // 5. 执行训练
    auto result = task.run();

    // 6. 输出训练结果
    std::cout << "Best Top-1: " << result.best_top1 * 100.0f << "%\n";

    return 0;
}

七大模块

Tech-Renaissance 采用模块化架构，分为七大核心模块：

Core 模块

提供基础类型定义（Shape、DType、Region、Phase、StreamKind）、高性能可复现 RNG、线程安全日志系统、统一异常体系和全局配置管理。

Data 模块

负责数据加载与预处理，支持 MNIST、CIFAR、ImageNet 等数据集，提供完整的图像增强操作链（RandomResizedCrop、ColorJitter、Normalize 等），采用多线程流水线架构实现高效传输。

Tensor 模块

提供 CPU 端数据容器 Tensor（紧凑布局、移动语义、TSR 格式序列化）和分布式张量描述符 DTensor（多卡统一内存视图、对齐计算、槽位管理）。

Graph 模块

实现计算图编译与捕获，提供 BluePrint DSL 定义模型、五阶段编译管线、多流 CUDA Graph 捕获、基于 69-Region 规范的显存布局引擎。

Algo 模块

提供训练算法配置接口，包括 SGD/LARS/Adam/AdamW 优化器、支持 Warmup 的多种学习率调度器（PolynomialLR、CosineAnnealingLR、StepLR 等）、交叉熵损失函数。

Task 模块

提供训练/推理任务门面与生命周期管理，SimpleTask 用于手动构图场景，DeepLearningTask 封装完整训练循环（验证、SEMA、早停、指标收集、模型保存）。

Backend 模块

作为执行引擎，管理硬件设备、内存/显存池、算子执行和多流调度，提供 DeviceContext、MemoryArena、GraphExecutor、算子注册表等核心组件。

Core

板块介绍

Core 模块是 Tech-Renaissance 框架的核心基础设施，提供基础类型定义、随机数生成、日志记录、异常处理、全局配置管理等功能。

该模块对外提供的核心能力包括：

• 基础数据类型定义（Shape、DType、Region、枚举类型等）
• 高性能可复现的随机数生成（基于 Philox4x32-10 算法）
• 线程安全的日志系统（支持编译期级别过滤）
• 统一的异常体系和错误处理机制
• 全局配置管理（GlobalRegistry 单例）
• 张量初始化配置和管理
• GPU/CPU 设备配置和 Staging 内存管理
• 文件下载工具（Downloader）

关键头文件路径：

• include/renaissance/core/types.h - 基础类型定义
• include/renaissance/core/rng.h - 随机数生成器
• include/renaissance/core/logger.h - 日志系统
• include/renaissance/core/tr_exception.h - 异常体系
• include/renaissance/core/global_registry.h - 全局配置管理
• include/renaissance/core/initializer.h - 初始化器
• include/renaissance/core/init_config.h - 初始化配置
• include/renaissance/core/global_config.h - 全局配置常量

内部实现位置：src/core/

struct Shape

概述

Shape 是表示张量形状的结构体，采用 NHWC（Batch-Height-Width-Channel）格式，支持 4 维张量的形状描述。

所属头文件：#include

设计定位：值类型，可拷贝，可移动

常用使用路径：作为 Tensor 构造参数、数据层配置、模型输入输出形状描述

典型使用代码片段：

// 默认构造：标量 [1,1,1,1]
tr::Shape scalar;

// 从4个元素构造：[N,H,W,C]
tr::Shape image_batch(32, 224, 224, 3);

// 从初始化列表构造（右对齐填充）
tr::Shape vector{128};        // [1,1,1,128]
tr::Shape matrix{64, 128};    // [1,1,64,128]
tr::Shape tensor{8, 28, 28, 64};  // [8,28,28,64]

构造与赋值

Shape::Shape()

Shape() = default;

功能简介 默认构造函数，创建标量形状 [1,1,1,1]。

参数 无

返回值 无

异常 无

Shape::Shape(int n, int h, int w, int c)

TR_NOINLINE Shape(int n, int h, int w, int c);

功能简介 从 4 个显式参数构造 Shape [N,H,W,C]。使用 TR_NOINLINE 和 volatile 写入修复 MSVC /O2 优化问题。

参数

返回值 无

异常 无

注意事项

• 非正值（<=0）会自动修正为 1
• TR_NOINLINE 防止 MSVC Release 模式下的优化错误
• volatile 写入强制内存写入，防止参数传递错误

Shape::Shape(std::initializer_list list)

Shape(std::initializer_list<int> list);

功能简介 从初始化列表构造 Shape，支持 1-4 个元素，右对齐填充。

参数

返回值 无

异常 无

注意事项 填充规则（右对齐）：

• 1 个元素 {C} → [1,1,1,C]
• 2 个元素 {W,C} → [1,1,W,C]
• 3 个元素 {H,W,C} → [1,H,W,C]
• 4 个元素 {N,H,W,C} → [N,H,W,C]

非正值（<=0）会自动修正为 1。

示例

tr::Shape s1{128};           // [1,1,1,128]
tr::Shape s2{64, 128};       // [1,1,64,128]
tr::Shape s3{28, 28, 3};     // [1,28,28,3]
tr::Shape s4{32, 224, 224, 3}; // [32,224,224,3]

数据访问

int& Shape::operator[](size_t i)

int& operator[](size_t i);
const int& operator[](size_t i) const;

功能简介 访问第 i 个维度（0-based）。

参数

返回值 对应维度的引用

异常 无（不进行边界检查）

int Shape::n() const

int n() const;

功能简介 获取 Batch 大小 N（维度 0）。

参数 无

返回值 Batch 大小

异常 无

int Shape::h() const

int h() const;

功能简介 获取高度 H（维度 1）。

参数 无

返回值 高度值

异常 无

int Shape::w() const

int w() const;

功能简介 获取宽度 W（维度 2）。

参数 无

返回值 宽度值

异常 无

int Shape::c() const

int c() const;

功能简介 获取通道数 C（维度 3）。

参数 无

返回值 通道数

异常 无

int64_t Shape::numel() const

int64_t numel() const noexcept;

功能简介 计算总元素数量 N×H×W×C。

参数 无

返回值 总元素个数（int64_t）

异常 无

运算符

bool Shape::operator==(const Shape& other) const

bool operator==(const Shape& other) const noexcept;

功能简介 相等比较运算符。

参数

返回值 所有维度是否完全相同

异常 无

bool Shape::operator!=(const Shape& other) const

bool operator!=(const Shape& other) const noexcept;

功能简介 不等比较运算符。

参数

返回值 是否有任何维度不同

异常 无

工具方法

std::string Shape::to_string() const

std::string to_string() const;

功能简介 转换为字符串表示，如 "[32,224,224,3]"。

参数 无

返回值 字符串表示

异常 无

static constexpr size_t Shape::ndim()

static constexpr size_t ndim();

功能简介 获取维度数量（总是返回 4）。

参数 无

返回值 维度数量（4）

异常 无

enum class DType

概述

数据类型枚举，表示张量的元素类型。

所属头文件：#include

enum class NormMode

概述

归一化模式枚举，指定数据预处理的归一化方式。

所属头文件：#include

enum class Region

概述

显存区域枚举，定义了 69 个显存区域（Region），用于显存池管理和张量分配。按功能分为多个系列：B 系列（BN 统计量）、W 系列（主模型权重）、E 系列（EMA 权重）、A 系列（AMP FP16 权重）、G 系列（梯度）、M 系列（一阶动量）、V 系列（二阶动量）、N 系列（LARS 范数）、I 系列（输入缓冲区）、F 系列（特征图）、S 系列（标量）、T 系列（临时张量）、R 系列（结果区）。

所属头文件：#include

struct PlanConfig

概述

内存规划配置结构体，用于指示 MemoryPlan 需要为哪些类型的张量分配显存。

所属头文件：#include

设计定位：值类型，8 个布尔/整数字段，直接传递给内存规划器

成员

enum class GraphMode

概述

图模式枚举，表示计算图的工作模式。

所属头文件：#include

enum class Phase

概述

任务生命周期枚举，表示任务的不同阶段。

所属头文件：#include

enum class StreamKind

概述

CUDA 流类型枚举，定义 5 个物理非阻塞流。

所属头文件：#include

enum class OptimizerKind

概述

优化器类型枚举，用于配置优化器。

所属头文件：#include

enum class NormalizePreset

概述

归一化预设配置枚举，定义常用的数据集归一化参数。

所属头文件：#include

enum class ConvSearchMode

概述

卷积搜索模式枚举，控制 cuDNN 卷积算法选择策略。

所属头文件：#include

enum class Metric

概述

指标位掩码枚举，用于指定需要计算的评估指标。

所属头文件：#include

enum class TTA

概述

TTA（Test Time Augmentation）模式枚举，测试时数据增强技术。

所属头文件：#include

struct InputSpec

概述

输入规格结构体，描述模型输入的默认维度。

所属头文件：#include

设计定位：值类型，4 字段 POD

成员

struct TrainingResult

概述

训练结果结构体，由 Task::run() 返回，汇总训练过程中的最佳指标。

所属头文件：#include

设计定位：值类型，返回结果容器

成员

工厂方法

static TrainingResult TrainingResult::debug_stub()

static TrainingResult debug_stub();

功能简介 返回一个默认构造的 TrainingResult，用于调试占位。

参数 无

返回值 默认 TrainingResult

异常 无

enum class LogLevel

概述

日志级别枚举，控制日志输出的详细程度。

所属头文件：#include

enum class InitKind

概述

初始化方法枚举，定义 8 种张量初始化策略，覆盖 MLPerf 全部需求。

所属头文件：#include

enum class FanMode

概述

Fan 计算模式枚举，用于卷积初始化时的 fan_in/fan_out 计算。

所属头文件：#include

struct InitConfig

概述

初始化配置结构体，8 字节紧凑布局，描述张量的初始化策略。

所属头文件：#include

设计定位：值类型，可通过 NCCL Broadcast 一次性传输

常用使用路径：作为 Initializer::derive() 的返回值

成员

总大小：8 bytes（含 2 字节 padding）

数据访问

bool InitConfig::needs_init() const

bool needs_init() const noexcept;

功能简介 判断是否需要执行初始化。

参数 无

返回值 kind != NONE 时返回 true

异常 无

const char* InitConfig::to_string() const

const char* to_string() const noexcept;

功能简介 转换为可读字符串（调试用）。

参数 无

返回值 格式化的字符串（静态缓冲区）

异常 无

class Generator

概述

Generator 是基于 Philox4x32-10 算法的伪随机数生成器，支持多线程可复现、高性能、跨平台。

所属头文件：#include

设计定位：有状态（stateful），使用 Pimpl 模式避免 MUSA SDK 的 冲突

常用使用路径：

• 全局随机种子设置：通过 GlobalRegistry::manual_seed()
• 独立生成器：多线程数据加载（每个线程独立 Generator）

典型使用代码片段：

// 全局设置（推荐）
tr::GlobalRegistry::instance().manual_seed(42);

// 使用默认生成器
tr::cpu_rand_normal_float(ptr, count, 0.0f, 1.0f);

// 使用独立生成器（多线程）
tr::Generator gen(1234);
tr::cpu_rand_normal_float(ptr, count, 0.0f, 1.0f, gen);

构造与赋值

Generator::Generator(uint64_t seed)

explicit Generator(uint64_t seed = 0) noexcept;

功能简介 构造函数，创建指定种子的生成器。

参数

返回值 无

异常 无

Generator::~Generator()

~Generator();

功能简介 析构函数。

参数 无

返回值 无

异常 无

Generator::Generator(Generator&& other)

Generator(Generator&& other) noexcept;

功能简介 移动构造函数。

参数

返回值 无

异常 无

注意事项 源对象的 impl_ 自动置为 nullptr

Generator& Generator::operator=(Generator&& other)

Generator& operator=(Generator&& other) noexcept;

功能简介 移动赋值运算符。

参数

返回值 *this

异常 无

注意事项 禁止拷贝（拷贝构造和拷贝赋值已删除）

种子管理

void Generator::set_seed(uint64_t seed)

void set_seed(uint64_t seed);

功能简介 设置种子（重置 offset 为 0）。

参数

返回值 无

异常 无

注意事项 线程安全，但会短暂阻塞其他操作

uint64_t Generator::seed() const

uint64_t seed() const noexcept;

功能简介 获取当前种子。

参数 无

返回值 种子值

异常 无

状态管理（用于 Checkpoint）

std::pair Generator::get_state() const

std::pair<uint64_t, uint64_t> get_state() const;

功能简介 获取完整状态 {seed, offset}。

参数 无

返回值 {seed, offset} 对

异常 无

void Generator::set_state(uint64_t seed, uint64_t offset)

void set_state(uint64_t seed, uint64_t offset);

功能简介 设置完整状态。

参数

返回值 无

异常 无

偏移量管理（核心方法）

uint64_t Generator::next_offset(uint64_t count)

uint64_t next_offset(uint64_t count);

功能简介 原子预留偏移量区间，实现多线程可复现的关键。

参数

返回值 本次预留的起始 offset

异常 无

注意事项

• 调用者获得 [返回值, 返回值+count) 区间的独占使用权
• 多线程并发调用时，每个调用获得的区间互不重叠
• 相同的调用序列产生相同的区间分配

uint64_t Generator::current_offset() const

uint64_t current_offset() const noexcept;

功能简介 获取当前偏移量（不修改状态）。

参数 无

返回值 当前 offset

异常 无

辅助方法

int Generator::random_int(int low, int high)

int random_int(int low, int high);

功能简介 生成 [low, high] 范围的随机整数（包含两端）。

参数

返回值 [low, high] 范围内的随机整数

异常 无

注意事项 可复现：相同的 seed 和 offset 序列产生相同的结果，用于 Fisher-Yates 洗牌等场景

class Logger

概述

Logger 是轻量级、线程安全、可编译关闭的日志系统，支持四级日志（DEBUG/INFO/WARN/ERROR）和模块化标记。

所属头文件：#include

设计定位：单例模式，线程安全，支持编译期级别过滤

常用使用路径：

• 运行时配置：Logger::instance().set_level()
• 宏使用：TR_LOG_INFO("Module") << "message"

典型使用代码片段：

// 设置日志级别
tr::Logger::instance().set_level(tr::LogLevel::INFO);

// 设置输出文件
tr::Logger::instance().set_output_file("app.log");

// 使用日志宏
TR_LOG_INFO("TR") << "Training started";
LOG_WARN << "Low memory detected";

构造与析构

Logger& Logger::instance()

static Logger& instance() noexcept;

功能简介 获取 Logger 单例实例（Meyers 单例，线程安全）。

参数 无

返回值 Logger 单例引用

异常 无

Logger::~Logger()

~Logger();

功能简介 析构函数，自动关闭日志文件。

参数 无

返回值 无

异常 无

注意事项 禁止拷贝和赋值

配置方法

void Logger::set_level(LogLevel level)

void set_level(LogLevel level) noexcept;

功能简介 设置日志级别，低于此级别的日志将被过滤。

参数

返回值 无

异常 无

void Logger::set_output_file(const std::string& filename)

void set_output_file(const std::string& filename);

功能简介 设置日志输出文件。

参数

返回值 无

异常 无

void Logger::set_quiet_mode(bool quiet)

void set_quiet_mode(bool quiet) noexcept;

功能简介 设置静默模式。

参数

返回值 无

异常 无

核心日志方法

void Logger::log(LogLevel level, const char module, const char file, int line, const std::string& message)

void log(LogLevel level, const char* module, const char* file,
         int line, const std::string& message);

功能简介 核心日志方法，输出日志消息。

参数

返回值 无

异常 无

注意事项 线程安全，内部使用互斥锁保护

查询方法

LogLevel Logger::level() const

LogLevel level() const noexcept;

功能简介 获取当前日志级别。

参数 无

返回值 当前日志级别

异常 无

内部生命周期方法

void Logger::init()

void init();

功能简介 初始化 Logger（供 Initializer 调用）。

参数 无

返回值 无

异常 无

注意事项 空实现，保留接口一致性。实际初始化由 Logger::instance() 的 Meyers 单例完成。

void Logger::cleanup()

void cleanup();

功能简介 清理 Logger（供 Initializer 调用）。

参数 无

返回值 无

异常 无

注意事项 空实现，保留接口一致性。

void Logger::log_exception(const TRException& e)

[[deprecated]] void log_exception(const TRException& e);

功能简介 将异常信息记录到日志。

参数

返回值 无

异常 无

注意事项 【已废弃】自 V4.20.1 起，异常不再自动记录到 Logger。此方法仅保留给特殊场景，新代码应避免使用。

宏定义

概述

框架提供的日志、线程安全输出及平台兼容宏定义。

头文件：

• renaissance/core/logger.h - 日志宏与线程安全输出宏
• renaissance/core/types.h - 平台兼容属性宏

日志宏

所属头文件：#include

编译期过滤宏

编译期日志过滤由 TR_LOG_LEVEL 控制（定义于 renaissance/core/logger.h）：
- TR_LOG_LEVEL <= 0：DEBUG 及以上启用
- TR_LOG_LEVEL <= 1：INFO 及以上启用
- TR_LOG_LEVEL <= 2：WARN 及以上启用
- TR_LOG_ERROR 始终保留，不受该宏影响
- 未定义时，Debug 模式默认为 0，Release 模式默认为 2

TR_LOG_DEBUG(module)

TR_LOG_DEBUG(module)

签名 宏调用形式：TR_LOG_DEBUG(module)

功能简介 DEBUG 级别日志宏，编译期可过滤。在 Release 模式下完全消失（零开销）。

参数

返回值 LogStream 或 NullStream（支持流式操作）

异常 无

注意事项

• TR_LOG_LEVEL <= 0 时启用
• Debug 模式下等同于 TR_LOG_INFO
• 支持 << 流式语法

TR_LOG_INFO(module)

TR_LOG_INFO(module)

签名 宏调用形式：TR_LOG_INFO(module)

功能简介 INFO 级别日志宏。

参数

返回值 LogStream 或 NullStream

异常 无

注意事项 TR_LOG_LEVEL <= 1 时启用

TR_LOG_WARN(module)

TR_LOG_WARN(module)

签名 宏调用形式：TR_LOG_WARN(module)

功能简介 WARN 级别日志宏。

参数

返回值 LogStream 或 NullStream

异常 无

注意事项 TR_LOG_LEVEL <= 2 时启用

TR_LOG_ERROR(module)

TR_LOG_ERROR(module)

签名 宏调用形式：TR_LOG_ERROR(module)

功能简介 ERROR 级别日志宏，始终保留（不可编译期过滤）。

参数

返回值 LogStream

异常 无

便捷宏（自动推断模块）

LOG_DEBUG / LOG_INFO / LOG_WARN / LOG_ERROR

#define LOG_DEBUG TR_LOG_DEBUG("TR")
#define LOG_INFO  TR_LOG_INFO("TR")
#define LOG_WARN  TR_LOG_WARN("TR")
#define LOG_ERROR TR_LOG_ERROR("TR")

签名 宏调用形式：LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR

功能简介 便捷日志宏，自动使用 "TR" 作为模块名。

参数 无

返回值 LogStream 或 NullStream

异常 无

示例

LOG_INFO << "Training started";
LOG_WARN << "GPU memory usage: " << usage << "%";
LOG_ERROR << "Failed to load model";

线程安全原子性输出宏

所属头文件：#include

TR_ATOMIC_COUT

TR_ATOMIC_COUT

签名 宏调用形式：TR_ATOMIC_COUT

功能简介 线程安全原子性标准输出宏，直接输出到 stdout，不经过日志级别过滤、不附加时间戳/模块名。通过全局互斥锁保证多线程下整行/整块输出不被打断。

参数 无

返回值 AtomicCoutStream（支持流式操作）

异常 无

注意事项

• 不受日志级别过滤影响
• 不添加时间戳、模块名等元信息
• 适用于需要原始输出的场景

示例

TR_ATOMIC_COUT << "Progress: " << percent << "%" << std::endl;

平台兼容属性宏（实现细节）

所属头文件：#include

以下宏为框架内部平台兼容/编译器控制宏，普通用户通常无需直接使用。

TR_NOINLINE

#ifdef _MSC_VER
    #define TR_NOINLINE __declspec(noinline)
#elif defined(__GNUC__) || defined(__clang__)
    #define TR_NOINLINE __attribute__((noinline))
#else
    #define TR_NOINLINE
#endif

功能简介 禁止编译器内联当前函数。用于修复特定平台/优化级别下的正确性问题。

使用位置 主要在 Shape::Shape(int n, int h, int w, int c) 构造函数中使用，避免 MSVC /O2 优化导致的参数传递错误。

注意事项

• 属于实现细节，不建议用户在自己的代码中使用
• 删除该属性可能导致 Release 模式下 Shape 构造异常

struct ExceptionContext

概述

异常上下文信息结构体，用于记录异常发生时的文件、函数和消息。

所属头文件：#include

设计定位：值类型，构成 TRException 的上下文链

成员

工具方法

std::string ExceptionContext::to_string() const

std::string to_string() const;

功能简介 将上下文格式化为可读字符串。

参数 无

返回值 格式：message (at file :: func())

异常 无

class TRException

概述

TRException 是框架统一异常基类，支持 Context Chain（多层上下文叠加）、延迟构建 what()、线程安全。

所属头文件：#include

设计定位：异常基类，所有框架异常的根

常用使用路径：通过 TR_THROW() 宏抛出，通过 catch 块捕获

典型使用代码片段：

// 抛出异常
TR_THROW(ValueError, "Invalid batch size: " << batch_size);

// 条件检查
TR_CHECK(ptr != nullptr, MemoryError, "null pointer");

// 重新抛出并添加上下文
try {
    // ...
} catch (tr::TRException& e) {
    TR_RETHROW(e, "While loading model from " << path);
}

构造与析构

TRException::TRException(const char type_name, const std::string& message, const char file, const char* func)

TRException(const char* type_name,
            const std::string& message,
            const char* file,
            const char* func);

功能简介 构造异常对象。

参数

返回值 无

异常 无

TRException::~TRException()

virtual ~TRException() noexcept = default;

功能简介 虚析构函数。

参数 无

返回值 无

异常 无

TRException::TRException(const TRException& other)

TRException(const TRException& other) noexcept;

功能简介 拷贝构造函数（MSVC C5272 警告修复，noexcept）。

参数

返回值 无

异常 无

注意事项 mutex_ 成员不可复制，需要在新对象中重新初始化

TRException& TRException::operator=(const TRException& other)

TRException& operator=(const TRException& other) noexcept;

功能简介 拷贝赋值运算符（MSVC C5272 警告修复，noexcept）。

参数

返回值 *this

异常 无

核心方法

const char* TRException::what() const

const char* what() const noexcept override;

功能简介 获取完整错误描述（线程安全 + OOM 安全）。

参数 无

返回值 包含 Context Chain 的完整消息

异常 无

注意事项

• 首次调用时构建完整消息并缓存
• 后续调用直接返回缓存
• 线程安全（使用 mutex 保护）

void TRException::add_context(const std::string& ctx_message, const char file, const char func)

void add_context(const std::string& ctx_message,
                 const char* file,
                 const char* func);

功能简介 添加上下文信息（线程安全，支持重新抛出）。

参数

返回值 无

异常 无

注意事项 通过 TR_RETHROW 宏使用，不要手动调用

const char* TRException::type() const

const char* type() const noexcept;

功能简介 获取异常类型名。

参数 无

返回值 异常类型字符串

异常 无

const std::string& TRException::message() const

const std::string& message() const noexcept;

功能简介 获取根消息。

参数 无

返回值 根消息字符串引用

异常 无

std::vector TRException::get_contexts() const

std::vector<ExceptionContext> get_contexts() const;

功能简介 获取上下文链（线程安全，返回拷贝）。

参数 无

返回值 上下文链的副本

异常 无

注意事项 推荐使用此方法而非已废弃的 contexts()

const std::vector& TRException::contexts() const

[[deprecated]] const std::vector<ExceptionContext>& contexts() const;

功能简介 获取上下文链的常量引用。

参数 无

返回值 上下文链的常量引用

异常 无

注意事项 【已废弃】直接返回内部 vector 引用，存在线程安全和生命周期风险。请改用 get_contexts()。

具体异常类型

概述

框架提供的具体异常类型，均继承自 TRException。

所属头文件：#include

异常宏

概述

框架提供的异常抛出、条件检查与消息构建宏。

所属头文件：#include

核心异常宏

TR_THROW(ExceptionType, msg_stream)

#define TR_THROW(ExceptionType, msg_stream)

签名 宏调用形式：TR_THROW(ExceptionType, msg_stream)

功能简介 抛出异常的核心宏。

参数

返回值 无（抛出异常）

异常 抛出指定的异常类型

示例

TR_THROW(ValueError, "Invalid size: " << size);
TR_THROW(ShapeError, "Expected shape " << expected << ", got " << actual);

TR_CHECK(condition, ExceptionType, msg_stream)

#define TR_CHECK(condition, ExceptionType, msg_stream)

签名 宏调用形式：TR_CHECK(condition, ExceptionType, msg_stream)

功能简介 条件检查（所有模式都执行），条件为 false 时抛出异常。

参数

返回值 无（条件为 false 时抛出异常）

异常 条件为 false 时抛出指定异常

注意事项

• 适用场景：外部输入校验、关键不变量检查
• Release 模式下仍保留完整检查

示例

TR_CHECK(x > 0, ValueError, "x must be positive, got " << x);
TR_CHECK(ptr != nullptr, MemoryError, "null pointer");

TR_DEBUG_CHECK(condition, ExceptionType, msg_stream)

#define TR_DEBUG_CHECK(condition, ExceptionType, msg_stream)

签名 宏调用形式：TR_DEBUG_CHECK(condition, ExceptionType, msg_stream)

功能简介 防御性检查（仅 Debug 模式执行），Release 模式下完全消失（零开销）。

参数

返回值 无（Debug 模式下条件为 false 时抛出异常）

异常 Debug 模式下条件为 false 时抛出指定异常

注意事项

• 适用场景：热路径防御性断言、边界检查
• Release 模式下完全消失，零开销

TR_RETHROW(exception, ctx_stream)

#define TR_RETHROW(exception, ctx_stream)

签名 宏调用形式：TR_RETHROW(exception, ctx_stream)

功能简介 重新抛出并添加上下文（带引用安全检查）。

参数

返回值 无（重新抛出异常）

异常 重新抛出输入的异常

注意事项

• 必须在 catch 块中使用
• exception 参数必须是左值引用（catch TRException& e）
• 编译期检查防止值捕获错误

示例

try {
    // Some operation
} catch (tr::TRException& e) {
    TR_RETHROW(e, "While loading model from " << path);
}

便捷异常宏

所属头文件：#include

TR_MSG(...)

#define TR_MSG(...)

签名 宏调用形式：TR_MSG(...)

功能简介 构建异常消息字符串，供 TR_THROW 系列宏内部使用。

参数

返回值 std::string 形式的消息字符串

异常 无

注意事项 通常不直接调用，由 TR_THROW 和便捷异常宏自动展开。

以下宏是 TR_THROW 的便捷版本，自动指定异常类型：

#define TR_NOT_IMPLEMENTED(...) TR_THROW(NotImplementedError, TR_MSG(__VA_ARGS__))
#define TR_VALUE_ERROR(...) TR_THROW(ValueError, TR_MSG(__VA_ARGS__))
#define TR_SHAPE_ERROR(...) TR_THROW(ShapeError, TR_MSG(__VA_ARGS__))
#define TR_TYPE_ERROR(...) TR_THROW(TypeError, TR_MSG(__VA_ARGS__))
#define TR_INDEX_ERROR(...) TR_THROW(IndexError, TR_MSG(__VA_ARGS__))
#define TR_DEVICE_ERROR(...) TR_THROW(DeviceError, TR_MSG(__VA_ARGS__))
#define TR_FILE_NOT_FOUND(...) TR_THROW(FileNotFoundError, TR_MSG(__VA_ARGS__))
#define TR_ZERO_DIVISION(...) TR_THROW(ZeroDivisionError, TR_MSG(__VA_ARGS__))
#define TR_MEMORY_ERROR(...) TR_THROW(MemoryError, TR_MSG(__VA_ARGS__))
#define TR_TIMEOUT_ERROR(...) TR_THROW(TimeoutError, TR_MSG(__VA_ARGS__))
#define TR_GPU_OOM(...) TR_THROW(GPUOutOfMemoryError, TR_MSG(__VA_ARGS__))
#define TR_DISTRIBUTED_ERROR(...) TR_THROW(DistributedError, TR_MSG(__VA_ARGS__))
#define TR_RUNTIME_ERROR(...) TR_THROW(RuntimeError, TR_MSG(__VA_ARGS__))

class GlobalRegistry

概述

GlobalRegistry 是全局配置管理类，线程安全的单例，存储训练过程中需要共享的配置信息。

所属头文件：#include

设计定位：单例模式，线程安全，分类管理（fixed 固定型 + alterable 可变型）

常用使用路径：

• 链式配置：GLOBAL_SETTING.use_gpu().manual_seed(42)
• 直接访问：GlobalRegistry::instance()

典型使用代码片段：

// 链式配置
GLOBAL_SETTING
    .use_gpu("0,1,2,3")
    .manual_seed(42)
    .global_batch_size(128);

// 查询配置
bool using_gpu = GLOBAL_SETTING.using_gpu();
int batch_size = GLOBAL_SETTING.get_local_batch_size();

单例访问

GlobalRegistry& GlobalRegistry::instance()

static GlobalRegistry& instance();

功能简介 获取单例实例。

参数 无

返回值 GlobalRegistry 单例引用

异常 无

注意事项 禁止拷贝和移动

初始化方法

void GlobalRegistry::initialize()

void initialize();

功能简介 初始化全局注册表，检查所有 fixed 变量是否已赋值。

参数 无

返回值 无

异常 ValueError - 如果有 fixed 变量未赋值

注意事项

• 只在首次调用时生效
• 后续调用无效果

void GlobalRegistry::init()

void init();

功能简介 初始化（供 Initializer 调用），空实现，保留接口一致性。

参数 无

返回值 无

异常 无

注意事项 实际初始化由 begin_train() / begin_val() 触发

void GlobalRegistry::cleanup()

void cleanup();

功能简介 清理（供 Initializer 调用），空实现，保留接口一致性。

参数 无

返回值 无

异常 无

阶段管理方法

void GlobalRegistry::begin_train()

void begin_train();

功能简介 开始训练阶段。

参数 无

返回值 无

异常 无

注意事项

• train_counter_ 加一
• 如果尚未初始化，会自动调用 initialize()

void GlobalRegistry::end_train()

void end_train();

功能简介 结束训练阶段。

参数 无

返回值 无

异常 ValueError - 如果 train_counter_ 减到负数

void GlobalRegistry::begin_val()

void begin_val();

功能简介 开始验证阶段。

参数 无

返回值 无

异常 无

注意事项

• val_counter_ 加一
• 如果尚未初始化，会自动调用 initialize()

void GlobalRegistry::end_val()

void end_val();

功能简介 结束验证阶段。

参数 无

返回值 无

异常 ValueError - 如果 val_counter_ 减到负数

链式配置方法

GlobalRegistry& GlobalRegistry::manual_seed(uint64_t seed)

GlobalRegistry& manual_seed(uint64_t seed);

功能简介 设置全局随机种子。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 无

注意事项 调用 rng_set_seed() 设置全局随机数生成器的种子

GlobalRegistry& GlobalRegistry::auto_seed()

GlobalRegistry& auto_seed();

功能简介 使用时间种子自动初始化随机数生成器。

参数 无

返回值 GlobalRegistry 引用，支持链式调用

异常 无

注意事项 使用当前时间戳作为种子调用 manual_seed()

GlobalRegistry& GlobalRegistry::reproducible()

GlobalRegistry& reproducible();

功能简介 确保可复现性（启用可复现性保险）。

参数 无

返回值 GlobalRegistry 引用，支持链式调用

异常 无

注意事项 只要调用了 manual_seed() 或 auto_seed()，就会自动启用可复现模式

void GlobalRegistry::set_reproducibility_insurance(bool value)

void set_reproducibility_insurance(bool value);

功能简介 设置是否启用可复现性保险。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

void GlobalRegistry::ensure_reproducibility(bool value)

void ensure_reproducibility(bool value);

功能简介 set_reproducibility_insurance 的别名。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

bool GlobalRegistry::reproducibility_insurance() const

bool reproducibility_insurance() const;

功能简介 获取可复现性保险是否启用。

参数 无

返回值 启用返回 true

异常 无

GlobalRegistry& GlobalRegistry::amp(bool value)

GlobalRegistry& amp(bool value);

功能简介 设置是否使用混合精度训练（AMP）。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 ValueError - 初始化后对 AMP 设置进行非幂等修改时

GlobalRegistry& GlobalRegistry::use_tf32(bool value)

GlobalRegistry& use_tf32(bool value = true);

功能简介 设置是否允许 cuDNN 使用 TF32 Tensor Core 加速。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 无

注意事项 必须在第一个 cuDNN Graph 构建之前调用

GlobalRegistry& GlobalRegistry::local_batch_size(int value)

GlobalRegistry& local_batch_size(int value);

功能简介 设置本地 batch size。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 ValueError - 对 fixed batch size 进行非幂等修改时

GlobalRegistry& GlobalRegistry::global_batch_size(int value)

GlobalRegistry& global_batch_size(int value);

功能简介 设置全局 batch size（自动计算本地 batch size）。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 DeviceError - 如果尚未调用 use_gpu() 或 use_cpu() ValueError - 如果 value 不能被 world_size 整除

注意事项 将 global_batch_size / world_size 的商作为 local_batch_size 设置

状态查询方法

bool GlobalRegistry::is_training() const

bool is_training() const;

功能简介 是否处于训练阶段。

参数 无

返回值 训练阶段返回 true

异常 无

bool GlobalRegistry::is_validating() const

bool is_validating() const;

功能简介 是否处于验证阶段。

参数 无

返回值 验证阶段返回 true

异常 无

bool GlobalRegistry::is_busy() const

bool is_busy() const;

功能简介 是否忙碌（有对象正在训练或验证）。

参数 无

返回值 忙碌状态返回 true

异常 无

bool GlobalRegistry::is_initialized() const

bool is_initialized() const;

功能简介 是否已初始化。

参数 无

返回值 已初始化返回 true

异常 无

GPU 配置高层接口

GlobalRegistry& GlobalRegistry::use_gpu()

GlobalRegistry& use_gpu();

功能简介 配置 GPU 使用模式（无参数版本，自动使用所有可见 GPU）。

参数 无

返回值 GlobalRegistry 引用，支持链式调用

异常 ValueError - 当可见 GPU 数量为 0、不是 2 的幂或超过 16 时

注意事项

• 探测可见 GPU 数量（通过 CUDA/MUSA）
• 如果可见 GPU 数量为 0，自动改为 CPU 模式
• 自动使用所有可见 GPU
• GPU 数量必须小于 16

GlobalRegistry& GlobalRegistry::use_cpu()

GlobalRegistry& use_cpu();

功能简介 配置为 CPU 模式。

参数 无

返回值 GlobalRegistry 引用，支持链式调用

异常 无

GlobalRegistry& GlobalRegistry::use_gpu(const std::string& gpu_id_str)

GlobalRegistry& use_gpu(const std::string& gpu_id_str);

功能简介 配置 GPU 使用模式（字符串版本）。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 ValueError - 如果 GPU ID 无效或数量不是 2 的幂

注意事项

• 解析逗号分隔的 GPU ID 字符串
• 自动去重并排序
• 验证 GPU ID 在可见范围内

示例

GLOBAL_SETTING.use_gpu("0,1,2,3");    // 使用 GPU 0-3
GLOBAL_SETTING.use_gpu("0-7");        // 使用 GPU 0-7

分辨率配置方法

GlobalRegistry& GlobalRegistry::train_resolution(int value)

GlobalRegistry& train_resolution(int value);

功能简介 设置训练分辨率（非渐进式）。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 ValueError - 如果 value 不大于 0

注意事项

• 调用 set_using_progressive_resolution(false)
• 将值赋给 train_sample_resolution_begin_ 和 train_sample_resolution_end_

GlobalRegistry& GlobalRegistry::val_resolution(int value)

GlobalRegistry& val_resolution(int value);

功能简介 设置验证分辨率。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 ValueError - 如果 value 不大于 0

GlobalRegistry& GlobalRegistry::input_resolution(int value)

GlobalRegistry& input_resolution(int value);

功能简介 同时设置训练和验证分辨率。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 ValueError - 如果 value 不大于 0

注意事项 依次调用 train_resolution(value) 和 val_resolution(value)

GlobalRegistry& GlobalRegistry::train_resolution(std::pair pair_begin, std::pair pair_end)

GlobalRegistry& train_resolution(std::pair<int, int> pair_begin, std::pair<int, int> pair_end);

功能简介 设置渐进式训练分辨率。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 ValueError - 如果参数不合法

注意事项

• starting_epoch 必须为 0
• boundary_epoch 必须大于 0
• 调用 set_using_progressive_resolution(true)

锁页内存管理

GlobalRegistry& GlobalRegistry::allocate_staging_memory(size_t bytes_per_device)

GlobalRegistry& allocate_staging_memory(size_t bytes_per_device);

功能简介 为所有活跃设备分配 Staging 内存。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 ValueError - 如果 bytes_per_device 为 0、或已分配但大小不同

注意事项

• GPU 场景使用 cudaHostAlloc/musaHostAlloc
• CPU 场景使用 malloc
• 幂等设计：若已分配且大小相同，直接返回

void* GlobalRegistry::staging_memory_ptr(int rank) const

void* staging_memory_ptr(int rank) const;

功能简介 按 RANK 获取 Staging 内存指针。

参数

返回值 Staging 内存指针

异常 RuntimeError - 如果尚未分配 Staging 内存 IndexError - 如果 rank 越界

GlobalRegistry& GlobalRegistry::allocate_staging_params(size_t bytes_per_rank)

GlobalRegistry& allocate_staging_params(size_t bytes_per_rank = 256);

功能简介 分配 Staging 参数区（StagingParamPool）。

参数

返回值 GlobalRegistry 引用，支持链式调用

异常 无

注意事项

• 专用于 RANGE_H2D_COPY_DTENSOR 算子的 per-rank 标量参数传输
• 独立于 StagingBufferPool，两次不同的分配

void* GlobalRegistry::staging_params_ptr(int rank) const

void* staging_params_ptr(int rank) const;

功能简介 获取 rank 对应的 Staging 参数区指针。

参数

返回值 Staging 参数区指针

异常 RuntimeError - 如果尚未分配 IndexError - 如果 rank 越界

bool GlobalRegistry::has_staging_memory() const

bool has_staging_memory() const;

功能简介 是否已分配 Staging 内存。

参数 无

返回值 已分配返回 true

异常 无

size_t GlobalRegistry::staging_memory_size() const

size_t staging_memory_size() const;

功能简介 获取每 GPU Staging 内存字节数。

参数 无

返回值 字节数；未分配时返回 0

异常 无

int GlobalRegistry::staging_memory_numa_node(int rank) const

int staging_memory_numa_node(int rank) const;

功能简介 按 RANK 获取 Staging 内存所在 NUMA 节点编号。

参数

返回值 NUMA 节点编号；查询失败返回 -1

异常 RuntimeError - 如果尚未分配 Staging 内存 IndexError - 如果 rank 越界

bool GlobalRegistry::has_staging_params() const

bool has_staging_params() const;

功能简介 是否已分配 Staging 参数区。

参数 无

返回值 已分配返回 true

异常 无

size_t GlobalRegistry::staging_params_bytes() const

size_t staging_params_bytes() const;

功能简介 获取每 rank Staging 参数区字节数。

参数 无

返回值 字节数；未分配时返回 0

异常 无

void GlobalRegistry::clear_staging_memory()

void clear_staging_memory();

功能简介 显式释放所有 Staging 内存。

参数 无

返回值 无

异常 无

注意事项 析构时会自动释放，此方法用于提前释放

常用配置查询与设置

以下方法在 GlobalRegistry 的已有文档中未完整覆盖，但属于用户常见查询/配置入口。

GlobalRegistry& GlobalRegistry::setup()

GlobalRegistry& setup();

功能简介 入口方法（空实现），仅返回引用以支持链式配置语法。

参数 无

返回值 GlobalRegistry 引用，支持链式调用

异常 无

static int GlobalRegistry::get_visible_gpu_count()

static int get_visible_gpu_count();

功能简介 获取当前环境可见的 GPU 数量。

参数 无

返回值 可见 GPU 数量；CPU 模式或无可用 GPU 时返回 0

异常 无

void GlobalRegistry::set_dataset_type(DatasetType value)

void set_dataset_type(DatasetType value);

功能简介 设置数据集类型。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

DatasetType GlobalRegistry::dataset_type() const

DatasetType dataset_type() const;

功能简介 获取数据集类型。

参数 无

返回值 当前数据集类型

异常 ValueError - 尚未设置时

void GlobalRegistry::set_num_classes(int value)

void set_num_classes(int value);

功能简介 设置分类数量。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

int GlobalRegistry::num_classes() const

int num_classes() const;

功能简介 获取分类数量。

参数 无

返回值 分类数量

异常 ValueError - 尚未设置时

void GlobalRegistry::set_num_color_channels(int value)

void set_num_color_channels(int value);

功能简介 设置颜色通道数。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

int GlobalRegistry::num_color_channels() const

int num_color_channels() const;

功能简介 获取颜色通道数。

参数 无

返回值 颜色通道数

异常 ValueError - 尚未设置时

void GlobalRegistry::set_num_load_workers(int value)

void set_num_load_workers(int value);

功能简介 设置 DataLoader 加载线程数。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

int GlobalRegistry::num_load_workers() const

int num_load_workers() const;

功能简介 获取 DataLoader 加载线程数。

参数 无

返回值 加载线程数

异常 ValueError - 尚未设置时

void GlobalRegistry::set_num_preproc_workers(int value)

void set_num_preproc_workers(int value);

功能简介 设置 Preprocessor 预处理线程数。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

int GlobalRegistry::num_preproc_workers() const

int num_preproc_workers() const;

功能简介 获取 Preprocessor 预处理线程数。

参数 无

返回值 预处理线程数

异常 ValueError - 尚未设置时

int GlobalRegistry::world_size() const

int world_size() const;

功能简介 获取分布式训练的 world size（RANK 总数）。

参数 无

返回值 world size

异常 ValueError - 尚未配置 GPU/CPU 时

int GlobalRegistry::get_local_batch_size() const

int get_local_batch_size() const;

功能简介 获取每个 RANK 的本地 batch size。

参数 无

返回值 本地 batch size

异常 ValueError - 尚未设置时

void GlobalRegistry::set_batch_size(int value)

void set_batch_size(int value);

功能简介 设置本地 batch size（fixed 变量底层 setter）。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

注意事项 普通用户建议使用链式方法 local_batch_size(value)。

void GlobalRegistry::set_optimizer_kind(OptimizerKind kind)

void set_optimizer_kind(OptimizerKind kind);

功能简介 设置优化器类型。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

OptimizerKind GlobalRegistry::optimizer_kind() const

OptimizerKind optimizer_kind() const;

功能简介 获取优化器类型。

参数 无

返回值 当前优化器类型

异常 ValueError - 尚未设置时

int GlobalRegistry::optimizer_kind_raw() const

[[nodiscard]] int optimizer_kind_raw() const noexcept;

功能简介 获取优化器类型的原始整数值（不抛异常）。

参数 无

返回值 优化器类型原始值；-1 表示未设置

异常 无

bool GlobalRegistry::using_gpu() const

bool using_gpu() const;

功能简介 是否使用 GPU。

参数 无

返回值 GPU 模式返回 true

异常 无

const std::vector& GlobalRegistry::gpu_ids() const

const std::vector<int>& gpu_ids() const;

功能简介 获取当前配置的 GPU ID 列表。

参数 无

返回值 GPU ID 列表的常量引用

异常 无

void GlobalRegistry::set_using_gpu(bool value)

void set_using_gpu(bool value);

功能简介 设置是否使用 GPU（fixed 变量底层 setter）。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

注意事项 普通用户建议使用链式方法 use_gpu() 或 use_cpu()。

void GlobalRegistry::set_gpu_ids(const std::vector& ids)

void set_gpu_ids(const std::vector<int>& ids);

功能简介 设置 GPU ID 列表（fixed 变量底层 setter）。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

注意事项 普通用户建议使用链式方法 use_gpu(const std::string&)。

bool GlobalRegistry::using_amp() const

bool using_amp() const;

功能简介 是否启用混合精度训练（AMP）。

参数 无

返回值 启用 AMP 返回 true

异常 无

bool GlobalRegistry::has_amp_set() const

bool has_amp_set() const;

功能简介 AMP 标志是否已被用户显式设置。

参数 无

返回值 已调用 amp(true/false) 返回 true

异常 无

void GlobalRegistry::set_num_train_samples(size_t count)

void set_num_train_samples(size_t count);

功能简介 设置训练集样本总数。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

size_t GlobalRegistry::num_train_samples() const

size_t num_train_samples() const;

功能简介 获取训练集样本总数。

参数 无

返回值 训练集样本总数

异常 ValueError - 尚未设置时

void GlobalRegistry::set_num_val_samples(size_t count)

void set_num_val_samples(size_t count);

功能简介 设置验证集样本总数。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

size_t GlobalRegistry::num_val_samples() const

size_t num_val_samples() const;

功能简介 获取验证集样本总数。

参数 无

返回值 验证集样本总数

异常 ValueError - 尚未设置时

int GlobalRegistry::get_train_steps() const

int get_train_steps() const;

功能简介 获取训练总 batch 数（steps）。

参数 无

返回值 训练 steps

异常 ValueError - 依赖项未设置时

int GlobalRegistry::get_val_steps() const

int get_val_steps() const;

功能简介 获取验证总 batch 数（steps）。

参数 无

返回值 验证 steps

异常 ValueError - 依赖项未设置时

其他 fixed 配置查询与设置

void GlobalRegistry::set_sdmp_factor(int value)

void set_sdmp_factor(int value);

功能简介 设置 SDMP（Spatially Distributed Multi-Path）因子。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

int GlobalRegistry::sdmp_factor() const

int sdmp_factor() const;

功能简介 获取 SDMP 因子。

参数 无

返回值 SDMP 因子

异常 ValueError - 尚未设置时

void GlobalRegistry::set_using_cpvs(bool value)

void set_using_cpvs(bool value);

功能简介 设置是否使用 CPVS（Cross-Parallel Validation Strategy）。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

bool GlobalRegistry::using_cpvs() const

bool using_cpvs() const;

功能简介 是否使用 CPVS。

参数 无

返回值 启用返回 true

异常 无

void GlobalRegistry::set_using_drop_last(bool value)

void set_using_drop_last(bool value);

功能简介 设置是否丢弃最后不完整的 batch。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

bool GlobalRegistry::using_drop_last() const

bool using_drop_last() const;

功能简介 是否丢弃最后不完整的 batch。

参数 无

返回值 丢弃返回 true

异常 无

void GlobalRegistry::set_train_with_rhf(bool value)

void set_train_with_rhf(bool value);

功能简介 设置训练集是否包含 RandomHorizontalFlip。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

bool GlobalRegistry::train_with_rhf() const

bool train_with_rhf() const;

功能简介 训练集是否包含 RandomHorizontalFlip。

参数 无

返回值 包含返回 true

异常 无

void GlobalRegistry::set_val_with_rhf(bool value)

void set_val_with_rhf(bool value);

功能简介 设置验证集是否包含 RandomHorizontalFlip。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

bool GlobalRegistry::val_with_rhf() const

bool val_with_rhf() const;

功能简介 验证集是否包含 RandomHorizontalFlip。

参数 无

返回值 包含返回 true

异常 无

void GlobalRegistry::set_shuffle_train(bool value)

void set_shuffle_train(bool value);

功能简介 设置训练集是否洗牌。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

bool GlobalRegistry::shuffle_train() const

bool shuffle_train() const;

功能简介 训练集是否洗牌。

参数 无

返回值 洗牌返回 true

异常 无

void GlobalRegistry::set_initializer_inited(bool value)

void set_initializer_inited(bool value);

功能简介 设置框架初始化标志（仅供 Initializer 内部调用）。

参数

返回值 无

异常 无

注意事项 普通用户无需调用。

bool GlobalRegistry::initializer_inited() const

bool initializer_inited() const;

功能简介 框架是否已调用 Initializer::init()。

参数 无

返回值 已初始化返回 true

异常 无

void GlobalRegistry::set_is_deployment_mode(bool value)

void set_is_deployment_mode(bool value);

功能简介 设置是否为 Deployment（推理部署）模式。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

bool GlobalRegistry::is_deployment_mode() const

bool is_deployment_mode() const;

功能简介 是否为 Deployment 模式。

参数 无

返回值 部署模式返回 true

异常 无

void GlobalRegistry::set_cpu_binding_enabled(bool value)

void set_cpu_binding_enabled(bool value);

功能简介 设置是否启用 CPU 绑核。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

bool GlobalRegistry::cpu_binding_enabled() const

bool cpu_binding_enabled() const;

功能简介 是否启用 CPU 绑核。

参数 无

返回值 启用返回 true

异常 无

void GlobalRegistry::set_cpu_binding_map(const std::vector& map)

void set_cpu_binding_map(const std::vector<int>& map);

功能简介 设置 CPU 绑核映射表（worker_id → CPU 核心 ID）。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

const std::vector& GlobalRegistry::cpu_binding_map() const

const std::vector<int>& cpu_binding_map() const;

功能简介 获取 CPU 绑核映射表。

参数 无

返回值 绑核映射表的常量引用

异常 无

void GlobalRegistry::set_fixed_s_original_indices(const std::vector& indices)

void set_fixed_s_original_indices(const std::vector<int>& indices);

功能简介 设置 S 区原始索引向量（用于 S 区洗牌）。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

const std::vector& GlobalRegistry::fixed_s_original_indices() const

const std::vector<int>& fixed_s_original_indices() const;

功能简介 获取 S 区原始索引向量。

参数 无

返回值 原始索引向量的常量引用

异常 无

样本统计与 last batch

int GlobalRegistry::get_last_train_batch_size() const

int get_last_train_batch_size() const;

功能简介 获取训练最后一个 batch 的本地样本数。

参数 无

返回值 最后一个 batch 样本数

异常 ValueError - 依赖项未设置时

int GlobalRegistry::get_last_val_batch_size() const

int get_last_val_batch_size() const;

功能简介 获取验证最后一个 batch 的本地样本数。

参数 无

返回值 最后一个 batch 样本数

异常 ValueError - 依赖项未设置时

size_t GlobalRegistry::padded_train_samples() const

size_t padded_train_samples() const;

功能简介 获取 pad 到 world_size 整数倍后的训练集总样本数。

参数 无

返回值 pad 后训练样本总数

异常 ValueError - 依赖项未设置时

size_t GlobalRegistry::padded_val_samples() const

size_t padded_val_samples() const;

功能简介 获取 pad 到 world_size 整数倍后的验证集总样本数。

参数 无

返回值 pad 后验证样本总数

异常 ValueError - 依赖项未设置时

size_t GlobalRegistry::train_samples_per_rank() const

size_t train_samples_per_rank() const;

功能简介 获取每个 RANK 的训练样本数（已 pad 后）。

参数 无

返回值 每 RANK 训练样本数

异常 ValueError - 依赖项未设置时

size_t GlobalRegistry::val_samples_per_rank() const

size_t val_samples_per_rank() const;

功能简介 获取每个 RANK 的验证样本数（已 pad 后）。

参数 无

返回值 每 RANK 验证样本数

异常 ValueError - 依赖项未设置时

void GlobalRegistry::set_aligned_max_output_size(size_t size)

void set_aligned_max_output_size(size_t size);

功能简介 设置 S/C 区单个样本对齐后字节数（64 字节对齐）。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

size_t GlobalRegistry::aligned_max_output_size() const

size_t aligned_max_output_size() const;

功能简介 获取 S/C 区单个样本对齐后字节数。

参数 无

返回值 对齐后字节数

异常 ValueError - 尚未设置时

渐进式分辨率与输出尺寸

void GlobalRegistry::set_using_progressive_resolution(bool value)

void set_using_progressive_resolution(bool value);

功能简介 设置是否启用渐进式分辨率。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

bool GlobalRegistry::using_progressive_resolution() const

bool using_progressive_resolution() const;

功能简介 是否启用渐进式分辨率。

参数 无

返回值 启用返回 true

异常 无

int GlobalRegistry::max_sample_resolution() const

int max_sample_resolution() const;

功能简介 获取所有训练和验证分辨率中的最大值。

参数 无

返回值 最大分辨率

异常 ValueError - 尚未设置时

int GlobalRegistry::train_sample_resolution_begin() const

int train_sample_resolution_begin() const;

功能简介 获取训练起始分辨率（渐进式）。

参数 无

返回值 训练起始分辨率

异常 ValueError - 尚未设置时

int GlobalRegistry::train_sample_resolution_end() const

int train_sample_resolution_end() const;

功能简介 获取训练结束分辨率（渐进式）。

参数 无

返回值 训练结束分辨率

异常 ValueError - 尚未设置时

int GlobalRegistry::get_train_sample_resolution_by_epoch(int epoch) const

int get_train_sample_resolution_by_epoch(int epoch) const;

功能简介 根据 epoch 获取训练集分辨率（渐进式）。

参数

返回值 该 epoch 对应的训练分辨率

异常 ValueError - 依赖项未设置时

int GlobalRegistry::get_val_sample_resolution() const

int get_val_sample_resolution() const;

功能简介 获取验证集分辨率。

参数 无

返回值 验证分辨率

异常 ValueError - 尚未设置时

int GlobalRegistry::boundary_epoch() const

int boundary_epoch() const;

功能简介 获取渐进式分辨率切换的边界 epoch。

参数 无

返回值 边界 epoch

异常 ValueError - 尚未设置时

int GlobalRegistry::get_train_sample_resolution_begin() const

int get_train_sample_resolution_begin() const;

功能简介 获取训练集起始分辨率（渐进式）。

参数 无

返回值 训练起始分辨率

异常 ValueError - 尚未设置时

int GlobalRegistry::get_train_sample_resolution_end() const

int get_train_sample_resolution_end() const;

功能简介 获取训练集结束分辨率（渐进式）。

参数 无

返回值 训练结束分辨率

异常 ValueError - 尚未设置时

int GlobalRegistry::val_sample_resolution() const

int val_sample_resolution() const;

功能简介 获取验证集分辨率（get_val_sample_resolution 的别名）。

参数 无

返回值 验证集分辨率

异常 ValueError - 尚未设置时

void GlobalRegistry::set_current_resolution_train(int value)

void set_current_resolution_train(int value);

功能简介 设置当前训练分辨率（alterable）。

参数

返回值 无

异常 ValueError - is_busy() 为 true 时

int GlobalRegistry::current_resolution_train() const

int current_resolution_train() const;

功能简介 获取当前训练分辨率。

参数 无

返回值 当前训练分辨率

异常 无

void GlobalRegistry::set_current_resolution_val(int value)

void set_current_resolution_val(int value);

功能简介 设置当前验证分辨率（alterable）。

参数

返回值 无

异常 ValueError - is_busy() 为 true 时

int GlobalRegistry::current_resolution_val() const

int current_resolution_val() const;

功能简介 获取当前验证分辨率。

参数 无

返回值 当前验证分辨率

异常 无

void GlobalRegistry::set_train_crop_output(int value)

void set_train_crop_output(int value);

功能简介 设置训练集 crop 输出尺寸（alterable）。

参数

返回值 无

异常 ValueError - is_busy() 为 true 时

int GlobalRegistry::train_crop_output() const

int train_crop_output() const;

功能简介 获取训练集 crop 输出尺寸。

参数 无

返回值 crop 输出尺寸

异常 无

void GlobalRegistry::set_train_resize_output(int value)

void set_train_resize_output(int value);

功能简介 设置训练集 resize 输出尺寸（alterable）。

参数

返回值 无

异常 ValueError - is_busy() 为 true 时

int GlobalRegistry::train_resize_output() const

int train_resize_output() const;

功能简介 获取训练集 resize 输出尺寸。

参数 无

返回值 resize 输出尺寸

异常 无

void GlobalRegistry::set_val_crop_output(int value)

void set_val_crop_output(int value);

功能简介 设置验证集 crop 输出尺寸（alterable）。

参数

返回值 无

异常 ValueError - is_busy() 为 true 时

int GlobalRegistry::val_crop_output() const

int val_crop_output() const;

功能简介 获取验证集 crop 输出尺寸。

参数 无

返回值 crop 输出尺寸

异常 无

void GlobalRegistry::set_val_resize_output(int value)

void set_val_resize_output(int value);

功能简介 设置验证集 resize 输出尺寸（alterable）。

参数

返回值 无

异常 ValueError - is_busy() 为 true 时

int GlobalRegistry::val_resize_output() const

int val_resize_output() const;

功能简介 获取验证集 resize 输出尺寸。

参数 无

返回值 resize 输出尺寸

异常 无

void GlobalRegistry::set_user_epoch_id(int value)

void set_user_epoch_id(int value);

功能简介 用户手动设置 Epoch ID（仅供调试）。

参数

返回值 无

异常 ValueError - is_busy() 为 true 时

注意事项 框架内部不应依赖此数值。

int GlobalRegistry::user_epoch_id() const

int user_epoch_id() const;

功能简介 获取用户手动设置的 Epoch ID。

参数 无

返回值 用户 epoch ID

异常 无

注意事项 仅供调试，框架代码不要依赖。

初始化策略配置

void GlobalRegistry::set_conv_init_kind(InitKind kind)

void set_conv_init_kind(InitKind kind);

功能简介 设置卷积层初始化策略。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

InitKind GlobalRegistry::conv_init_kind() const

InitKind conv_init_kind() const;

功能简介 获取卷积层初始化策略。

参数 无

返回值 卷积初始化策略

异常 ValueError - 尚未设置时

void GlobalRegistry::set_fc_init_kind(InitKind kind)

void set_fc_init_kind(InitKind kind);

功能简介 设置全连接层初始化策略。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

InitKind GlobalRegistry::fc_init_kind() const

InitKind fc_init_kind() const;

功能简介 获取全连接层初始化策略。

参数 无

返回值 全连接初始化策略

异常 ValueError - 尚未设置时

void GlobalRegistry::set_bn_init_kind(InitKind kind)

void set_bn_init_kind(InitKind kind);

功能简介 设置 BN 层初始化策略（STANDARD 或 ZERO_GAMMA）。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

InitKind GlobalRegistry::bn_init_kind() const

InitKind bn_init_kind() const;

功能简介 获取 BN 层初始化策略。

参数 无

返回值 BN 初始化策略

异常 ValueError - 尚未设置时

void GlobalRegistry::set_conv_search_mode(ConvSearchMode mode)

void set_conv_search_mode(ConvSearchMode mode);

功能简介 设置 cuDNN 卷积算法搜索模式。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

ConvSearchMode GlobalRegistry::conv_search_mode() const

ConvSearchMode conv_search_mode() const;

功能简介 获取卷积搜索模式。

参数 无

返回值 当前搜索模式；未设置时返回 HEURISTIC_B

异常 无

void GlobalRegistry::set_fan_mode(FanMode mode)

void set_fan_mode(FanMode mode);

功能简介 设置 Kaiming/Xavier 初始化时的 fan 计算模式。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

FanMode GlobalRegistry::fan_mode() const

FanMode fan_mode() const;

功能简介 获取 fan 计算模式。

参数 无

返回值 当前 fan 模式

异常 无

数据增强与损失参数

void GlobalRegistry::set_random_erasing_p(float value)

void set_random_erasing_p(float value);

功能简介 设置 Random Erasing 概率参数。

参数

返回值 无

异常 ValueError - is_busy() 为 true 时

float GlobalRegistry::random_erasing_p() const

float random_erasing_p() const;

功能简介 获取 Random Erasing 概率。

参数 无

返回值 当前概率 [0.0, 1.0]

异常 无

void GlobalRegistry::set_label_smoothing(float value)

void set_label_smoothing(float value);

功能简介 设置 Label Smoothing 系数。

参数

返回值 无

异常 ValueError - 初始化后修改或非幂等赋值时

float GlobalRegistry::label_smoothing() const

[[nodiscard]] float label_smoothing() const;

功能简介 获取 Label Smoothing 系数。

参数 无

返回值 当前标签平滑系数 [0, 0.2]

异常 无

bool GlobalRegistry::has_label_smoothing_set() const

[[nodiscard]] bool has_label_smoothing_set() const;

功能简介 Label Smoothing 是否已被显式设置。

参数 无

返回值 已调用 setter 返回 true

异常 无

优化器超参数

void GlobalRegistry::set_momentum(float value)

void set_momentum(float value);

功能简介 设置优化器动量系数。

参数

返回值 无

异常 无

float GlobalRegistry::momentum() const

[[nodiscard]] float momentum() const;

功能简介 获取优化器动量系数。

参数 无

返回值 当前动量值

异常 无

void GlobalRegistry::set_weight_decay(float value)

void set_weight_decay(float value);

功能简介 设置优化器权重衰减系数。

参数

返回值 无

异常 无

float GlobalRegistry::weight_decay() const

[[nodiscard]] float weight_decay() const;

功能简介 获取优化器权重衰减系数。

参数 无

返回值 当前权重衰减值

异常 无

void GlobalRegistry::set_trust_coefficient(float value)

void set_trust_coefficient(float value);

功能简介 设置 LARS trust coefficient。

参数

返回值 无

异常 无

float GlobalRegistry::trust_coefficient() const

[[nodiscard]] float trust_coefficient() const;

功能简介 获取 LARS trust coefficient。

参数 无

返回值 当前 trust coefficient

异常 无

void GlobalRegistry::set_eps(float value)

void set_eps(float value);

功能简介 设置优化器 epsilon（数值稳定小量）。

参数

返回值 无

异常 无

float GlobalRegistry::eps() const

[[nodiscard]] float eps() const;

功能简介 获取优化器 epsilon。

参数 无

返回值 当前 epsilon

异常 无

void GlobalRegistry::set_beta2(float value)

void set_beta2(float value);

功能简介 设置 Adam/AdamW 的 beta2 系数。

参数

返回值 无

异常 无

float GlobalRegistry::beta2() const

[[nodiscard]] float beta2() const;

功能简介 获取 Adam/AdamW 的 beta2 系数。

参数 无

返回值 当前 beta2

异常 无

void GlobalRegistry::set_grad_clip_max_abs(float value)

void set_grad_clip_max_abs(float value);

功能简介 设置梯度裁剪的最大绝对值阈值。

参数

返回值 无

异常 无

float GlobalRegistry::grad_clip_max_abs() const

[[nodiscard]] float grad_clip_max_abs() const;

功能简介 获取梯度裁剪的最大绝对值阈值。

参数 无

返回值 当前阈值；小于 0 表示不裁剪

异常 无

TransferStation 指针

void GlobalRegistry::set_transfer_station_ptr(size_t index, void* ptr)

void set_transfer_station_ptr(size_t index, void* ptr);

功能简介 设置 TransferStation 指针数组中的某个元素。

参数

返回值 无

异常 ValueError - is_busy() 为 true 或 index 越界时

void* GlobalRegistry::transfer_station_ptr(size_t index) const

void* transfer_station_ptr(size_t index) const;

功能简介 获取 TransferStation 指针数组中的某个元素。

参数

返回值 TransferStation 指针

异常 IndexError - index 越界时

std::atomic> GlobalRegistry::transfer_station_ptrs() const

std::atomic<void*>* transfer_station_ptrs() const;

功能简介 获取 TransferStation 指针数组的指针（固定大小 16）。

参数 无

返回值 指向指针数组的指针

异常 无

注意事项 该数组固定大小为 16，未使用的位置为 nullptr。

字符串命名访问

int GlobalRegistry::get_value_int(const std::string& name) const

int get_value_int(const std::string& name) const;

功能简介 通过名称获取整数值。

参数

返回值 变量值

异常 ValueError - 变量不存在时

float GlobalRegistry::get_value_float(const std::string& name) const

float get_value_float(const std::string& name) const;

功能简介 通过名称获取浮点数值。

参数

返回值 变量值

异常 ValueError - 变量不存在时

bool GlobalRegistry::get_value_bool(const std::string& name) const

bool get_value_bool(const std::string& name) const;

功能简介 通过名称获取布尔值。

参数

返回值 变量值

异常 ValueError - 变量不存在时

void GlobalRegistry::set_value_int(const std::string& name, int value)

void set_value_int(const std::string& name, int value);

功能简介 通过名称设置整数值。

参数

返回值 无

异常 ValueError - 变量不存在或 is_busy() 为 true 时

void GlobalRegistry::set_value_float(const std::string& name, float value)

void set_value_float(const std::string& name, float value);

功能简介 通过名称设置浮点数值。

参数

返回值 无

异常 ValueError - 变量不存在或 is_busy() 为 true 时

void GlobalRegistry::set_value_bool(const std::string& name, bool value)

void set_value_bool(const std::string& name, bool value);

功能简介 通过名称设置布尔值。

参数

返回值 无

异常 ValueError - 变量不存在或 is_busy() 为 true 时

语法糖

概述

全局注册表 GlobalRegistry 的引用与访问语法糖。

所属头文件：#include

全局注册表语法糖

the_registry

inline GlobalRegistry& the_registry = GlobalRegistry::instance();

功能简介 全局 GlobalRegistry 引用，提供更简洁的访问方式。

类型 GlobalRegistry&

示例

the_registry.use_gpu().manual_seed(42);
bool amp = the_registry.using_amp();

GLOBAL_SETTING

#define GLOBAL_SETTING (::tr::the_registry)

签名 宏定义

功能简介 进一步简化调用，提供更直观的链式配置语法。

示例

GLOBAL_SETTING.use_gpu().manual_seed(42);
GLOBAL_SETTING.use_cpu().auto_seed();
GLOBAL_SETTING.ensure_reproducibility().use_gpu("0,1,2,3").manual_seed(12345);

enum class StreamType

概述

流类型枚举，用于指定异步操作使用的 CUDA/MUSA 流。

所属头文件：#include

enum class DatasetType

概述

数据集类型枚举。

所属头文件：#include

enum class LoadMode

概述

数据加载模式枚举。

所属头文件：#include

全局配置宏

概述

常用枚举值和常量的便捷别名宏。

所属头文件：#include

以下宏为常用枚举值和常量的便捷别名：

#define TR_DEFAULT_STREAM   tr::StreamType::default_stream
#define TR_TRANSFER_STREAM  tr::StreamType::transfer_stream
#define TR_COMPUTE_STREAM   tr::StreamType::compute_stream
#define TR_COMM_STREAM      tr::StreamType::comm_stream

#define TR_NO_DATASET   tr::DatasetType::no_dataset
#define TR_IMAGENET  tr::DatasetType::imagenet
#define TR_MNIST   tr::DatasetType::mnist
#define TR_CIFAR_10      tr::DatasetType::cifar_10
#define TR_CIFAR_100      tr::DatasetType::cifar_100

#define TR_AMP_INITIAL_SCALING  8192.0f

class Initializer

概述

Initializer 是张量初始化器，非单例值类型，负责策略推导和数学工具。

所属头文件：#include

设计定位：可复制值类型，非单例

常用使用路径：

• 链式配置初始化策略
• 通过 derive() 推导具体张量的 InitConfig

典型使用代码片段：

tr::Initializer init;
init.conv(tr::InitKind::TRUNC_NORMAL)
    .fc(tr::InitKind::KAIMING_UNIFORM)
    .bn(tr::InitKind::STANDARD);

tr::InitConfig config = init.derive(tr::Region::W_FIRST_CONV);

构造与赋值

Initializer::Initializer()

Initializer() = default;

功能简介 默认构造函数。

参数 无

返回值 无

异常 无

链式 API

Initializer& Initializer::conv(InitKind k)

Initializer& conv(InitKind k);

功能简介 设置卷积层初始化策略。

参数

返回值 *this，支持链式调用

异常 无

Initializer& Initializer::fc(InitKind k, float param)

Initializer& fc(InitKind k, float param = 0.01f);

功能简介 设置全连接层初始化策略。

参数

返回值 *this，支持链式调用

异常 无

Initializer& Initializer::bn(InitKind k)

Initializer& bn(InitKind k = InitKind::STANDARD);

功能简介 设置批归一化层初始化策略。

参数

返回值 *this，支持链式调用

异常 ValueError - 当 k 不是 InitKind::STANDARD 或 InitKind::ZERO_GAMMA 时

Initializer& Initializer::zero_gamma(bool on)

Initializer& zero_gamma(bool on = true);

功能简介 设置 BN ZERO_GAMMA 策略。

参数

返回值 *this，支持链式调用

异常 无

Initializer& Initializer::fan(FanMode m)

Initializer& fan(FanMode m);

功能简介 设置 fan 模式（FAN_IN/FAN_OUT/FAN_AVG）。

参数

返回值 *this，支持链式调用

异常 无

Initializer& Initializer::scale(float s)

Initializer& scale(float s);

功能简介 设置全局 gain 倍数。

参数

返回值 *this，支持链式调用

异常 ValueError - 当 s < 0 时

Initializer& Initializer::nonlinearity(float a)

Initializer& nonlinearity(float a);

功能简介 设置 Kaiming 初始化的非线性参数 a（负斜率）。

参数

返回值 *this，支持链式调用

异常 无

注意事项

• a=0（默认）→ gain=√2（ReLU）
• a=√5 ≈ 2.236 → gain=√(2/6)（PyTorch nn.Linear 默认）

核心方法

InitConfig Initializer::derive(Region region) const

[[nodiscard]] InitConfig derive(Region region) const;

功能简介 根据 Region 推导初始化配置。

参数

返回值 对应的 InitConfig（8 字节）

异常 无

注意事项 穷举全部 69 Region，三段式结构：

1. 非参数区 → NONE
2. 偏置区 → ZEROS
3. 权重区 → 按层类型分发（CONV/FC/BN）

static int64_t Initializer::compute_fan(const Shape& shape, FanMode mode)

static int64_t compute_fan(const Shape& shape, FanMode mode);

功能简介 计算卷积权重的 fan_in/fan_out。

参数

返回值 fan 值

异常 无

注意事项 Conv weight 布局 = KRSC: [K=outC, R=kH, S=kW, C=inC]

static void Initializer::apply_to_tensor(Tensor& t, const Shape& shape, InitConfig cfg)

static void apply_to_tensor(class Tensor& t, const Shape& shape, InitConfig cfg);

功能简介 按 InitConfig 填充张量（CPU 端执行）。

参数

返回值 无

异常 无

注意事项 支持全部 InitKind，严格遵循 MLPerf 数学公式

调试方法

const char* Initializer::dump() const

[[nodiscard]] const char* dump() const;

功能简介 转储当前策略配置为字符串。

参数 无

返回值 配置字符串

异常 无

bool Initializer::is_zero_gamma() const

[[nodiscard]] bool is_zero_gamma() const noexcept;

功能简介 ZERO_GAMMA 策略是否激活。

参数 无

返回值 激活返回 true

异常 无

void Initializer::mark_bn3(int32_t id)

void mark_bn3(int32_t id);

功能简介 标记指定 DTensor 为 BN3 权重（由 Compiler 在 alloc 阶段调用）。

参数

返回值 无

异常 无

注意事项 expand_block_unfused 展开 RESNET_1_3_1 时，主干的最后一个 BN 命名为 "bn3"

const std::vector& Initializer::bn3_weight_ids() const

[[nodiscard]] const std::vector<int32_t>& bn3_weight_ids() const noexcept;

功能简介 获取所有 BN3 权重 DTensor ID（只读）。

参数 无

返回值 BN3 权重 ID 列表

异常 无

class Downloader

概述

Downloader 是基于 libcurl 的文件下载器，支持主 URL 和备用 URL 自动切换、自动创建目录、文件覆盖控制。

所属头文件：#include

设计定位：工具类，禁止拷贝和移动

常用使用路径：下载数据集文件、预训练模型

典型使用代码片段：

tr::Downloader downloader;
downloader.set_url("http://example.com/file.zip", "http://backup.com/file.zip");
bool success = downloader.download_to("downloads/", "myfile.zip", false);
if (success && downloader.already_exists()) {
    LOG_INFO << "File already exists, skipped download";
}

构造与析构

Downloader::Downloader()

Downloader();

功能简介 构造函数。

参数 无

返回值 无

异常 无

Downloader::~Downloader()

~Downloader();

功能简介 析构函数。

参数 无

返回值 无

异常 无

注意事项 禁止拷贝和移动

配置方法

void Downloader::set_url(const std::string& url, const std::string& spare_url)

void set_url(const std::string& url, const std::string& spare_url = "");

功能简介 设置下载 URL（主 URL 和可选备用 URL）。

参数

返回值 无

异常 ValueError - 当 url 为空时

注意事项

• URL 必须指向有效的 HTTP/HTTPS 地址
• 重复调用会覆盖之前的 URL 设置

void Downloader::set_progress_callback(std::function callback)

void set_progress_callback(std::function<void(size_t, size_t, int)> callback);

功能简介 设置进度回调函数。

参数

返回值 无

异常 无

注意事项

• 回调函数参数为 (已下载字节数, 总字节数, 0~100 进度百分比)
• 如果不设置，默认使用 LOG_INFO 每 10% 打印一次进度
• 设置为 nullptr 禁用进度显示
• 回调函数在下载线程中调用，应保持轻量

下载方法

bool Downloader::download_to(const std::string& dir_name, const std::string& file_name, bool cover)

bool download_to(const std::string& dir_name,
                 const std::string& file_name = "",
                 bool cover = false);

功能简介 下载文件到指定目录。

参数

返回值 true 表示成功（下载完成或文件已存在且 cover=false），false 表示失败

异常 ValueError - 如果未设置 URL 或 URL 为空 ValueError - 如果无法从 URL 提取文件名且 file_name 为空

注意事项

• 目录不存在时会自动创建（包括父目录）
• 文件已存在且 cover=false 时，返回 true，already_exists() 返回 true
• 下载失败时会尝试备用 URL（如果设置了）

bool Downloader::already_exists() const

bool already_exists() const;

功能简介 查询最后一次 download_to 是否因文件已存在而跳过。

参数 无

返回值 true 表示文件已存在且 cover=false，跳过下载

异常 无

注意事项 仅在 download_to 返回 true 时有意义

class StagingBufferPool

概述

StagingBufferPool 是 NUMA 感知的 Staging Buffer 池，为多 GPU 场景提供 NUMA 感知的 Staging Buffer 分配。

所属头文件：#include

设计定位：内部工具类，禁止拷贝

常用使用路径：通过 GlobalRegistry::allocate_staging_memory() 使用

构造与析构

StagingBufferPool::StagingBufferPool(const std::vector& gpu_ids, size_t bytes_per_block)

StagingBufferPool(const std::vector<int>& gpu_ids, size_t bytes_per_block);

功能简介 构造函数，为指定 GPU 分配 Staging Buffer。

参数

返回值 无

异常 ValueError - 当 gpu_ids 为空或 bytes_per_block 为 0 时 MemoryError - 当某块 Staging 内存分配失败时

注意事项

• 多线程分配：每 GPU 独立线程，各绑定自己的 NUMA 节点
• First Touch：全文 memset 触发物理页分配

StagingBufferPool::~StagingBufferPool()

~StagingBufferPool();

功能简介 析构函数。

参数 无

返回值 无

异常 无

注意事项 禁止拷贝和赋值

数据访问

void* StagingBufferPool::ptr(int rank) const

void* ptr(int rank) const;

功能简介 获取指定 rank 的 Staging Buffer 指针。

参数

返回值 Staging Buffer 指针

异常 IndexError - 当 rank 越界时

int StagingBufferPool::num_blocks() const

int num_blocks() const;

功能简介 获取块数量。

参数 无

返回值 块数量

异常 无

size_t StagingBufferPool::bytes_per_block() const

size_t bytes_per_block() const;

功能简介 获取每块字节数。

参数 无

返回值 每块字节数

异常 无

int StagingBufferPool::numa_node_for_rank(int rank) const

int numa_node_for_rank(int rank) const;

功能简介 获取指定 rank 的 NUMA 节点编号。

参数

返回值 NUMA 节点编号，查询失败时返回 -1

异常 IndexError - 当 rank 越界时

class StagingParamPool

概述

StagingParamPool 是 Per-RANK Staging 参数区，为 RANGE_H2D_COPY_DTENSOR 算子提供 per-rank 的小参数区（256 字节 = 64 × FP32）。

所属头文件：#include

设计定位：内部工具类，禁止拷贝

常用使用路径：通过 GlobalRegistry::allocate_staging_params() 使用

构造与析构

StagingParamPool::StagingParamPool(const std::vector& gpu_ids, size_t bytes_per_rank)

StagingParamPool(const std::vector<int>& gpu_ids, size_t bytes_per_rank = 256);

功能简介 构造函数。

参数

返回值 无

异常 DeviceError - 当 GPU 设备设置或锁页内存分配失败时 RuntimeError - 当 CPU 场景内存分配失败时

注意事项

• GPU 模式使用 cudaHostAlloc (pinned)
• CPU 模式使用 malloc

StagingParamPool::~StagingParamPool()

~StagingParamPool();

功能简介 析构函数。

参数 无

返回值 无

异常 无

注意事项 禁止拷贝和赋值

数据访问

void* StagingParamPool::ptr(int rank) const

void* ptr(int rank) const;

功能简介 获取 rank 对应的 Staging 参数区指针。

参数

返回值 Staging 参数区指针

异常 IndexError - 当 rank 越界时

void StagingParamPool::set_param(int rank, int slot, float value)

void set_param(int rank, int slot, float value);

功能简介 设置指定 rank 和 slot 的参数值。

参数

返回值 无

异常 IndexError - 当 rank 或 slot 越界时

float StagingParamPool::param(int rank, int slot) const

float param(int rank, int slot) const;

功能简介 获取指定 rank 和 slot 的参数值。

参数

返回值 参数值

异常 IndexError - 当 rank 或 slot 越界时

int StagingParamPool::num_ranks() const

int num_ranks() const;

功能简介 获取 rank 数量。

参数 无

返回值 rank 数量

异常 无

size_t StagingParamPool::bytes_per_rank() const

size_t bytes_per_rank() const;

功能简介 获取每 rank 字节数。

参数 无

返回值 每 rank 字节数

异常 无

预定义常量

概述

Core 模块提供的预定义常量，用于初始化配置。

所属头文件：#include

• kInitNone = {1.0f, InitKind::NONE, FanMode::FAN_IN} — 不初始化
• kInitZeros = {0.0f, InitKind::ZEROS, FanMode::FAN_IN} — 全零初始化

独立函数

概述

Core 模块提供一些不属于任何类的自由函数，包括内存对齐、CPU 随机数生成、Philox 算法等。

所属头文件：根据具体函数分别位于 types.h、initializer.h、rng.h、philox.h 等。

设计定位：无状态辅助函数，直接调用即可。

内存对齐

所属头文件：#include

utils::align_up_256(size_t size)

constexpr inline size_t align_up_256(size_t size) noexcept;

功能简介 将给定大小向上对齐到 256 字节的最小倍数。

参数

返回值 对齐后的 256 字节倍数

异常 无

示例

size_t aligned = tr::utils::align_up_256(100);  // 256
size_t aligned2 = tr::utils::align_up_256(512); // 512

InitConfig 相关函数

所属头文件：#include

kInitConstant(float v)

inline InitConfig kInitConstant(float v);

功能简介 创建常量初始化配置。

参数

返回值 InitConfig（kind=CONSTANTS, scale=v）

异常 无

to_string(InitKind kind)

inline const char* to_string(InitKind kind) noexcept;

功能简介 将 InitKind 转换为字符串。

参数

返回值 枚举值的字符串表示

异常 无

to_string(FanMode mode)

inline const char* to_string(FanMode mode) noexcept;

功能简介 将 FanMode 转换为字符串。

参数

返回值 枚举值的字符串表示

异常 无

Metric 位运算

所属头文件：#include

operator|(Metric a, Metric b)

inline Metric operator|(Metric a, Metric b);

功能简介 指标位掩码按位或运算，用于组合多个指标。

参数

返回值 组合后的 Metric 位掩码

异常 无

示例

tr::Metric m = tr::Metric::VAL_TOP1 | tr::Metric::VAL_TOP5;

has_metric(Metric flags, Metric m)

inline bool has_metric(Metric flags, Metric m);

功能简介 判断位掩码中是否包含指定指标。

参数

返回值 true 表示 flags 包含 m

异常 无

全局生成器访问

所属头文件：#include

get_default_generator()

Generator& get_default_generator();

功能简介 获取默认全局生成器（Meyers 单例，线程安全）。

参数 无

返回值 Generator 引用

异常 无

rng_set_seed(uint64_t seed)

void rng_set_seed(uint64_t seed);

功能简介 设置全局随机种子。

参数

返回值 无

异常 无

注意事项 等价于 get_default_generator().set_seed(seed)

CPU 随机数生成函数（核心 API）

所属头文件：#include

所有函数均提供两个版本：

1. 带 Generator& 参数的版本（独立生成器）
2. 不带参数的便捷版本（使用默认生成器）

cpu_rand_uint64(uint64_t* ptr, size_t count, Generator& gen)

void cpu_rand_uint64(uint64_t* ptr, size_t count, Generator& gen);

功能简介 生成 N 个随机 uint64 整数。

参数

返回值 无

异常 无

注意事项 多线程安全且可复现

cpu_rand_bernoulli_int8(int8_t* ptr, size_t count, float prob_one, Generator& gen)

void cpu_rand_bernoulli_int8(int8_t* ptr, size_t count, float prob_one, Generator& gen);

功能简介 生成 N 个伯努利分布的 INT8（0 或 1）。

参数

返回值 无

异常 无

cpu_rand_uniform_int8(int8_t* ptr, size_t count, int8_t low, int8_t high, Generator& gen)

void cpu_rand_uniform_int8(int8_t* ptr, size_t count, int8_t low, int8_t high, Generator& gen);

功能简介 生成 N 个均匀分布的 INT8。

参数

返回值 无

异常 无

cpu_rand_bernoulli_int32(int32_t* ptr, size_t count, float prob_one, Generator& gen)

void cpu_rand_bernoulli_int32(int32_t* ptr, size_t count, float prob_one, Generator& gen);

功能简介 生成 N 个伯努利分布的 INT32（0 或 1）。

参数

返回值 无

异常 无

cpu_rand_uniform_int32(int32_t* ptr, size_t count, int32_t low, int32_t high, Generator& gen)

void cpu_rand_uniform_int32(int32_t* ptr, size_t count, int32_t low, int32_t high, Generator& gen);

功能简介 生成 N 个均匀分布的 INT32。

参数

返回值 无

异常 无

注意事项 范围为 [low, high)，与 Python randint 语义一致

cpu_rand_uniform_float(float* ptr, size_t count, float low, float high, Generator& gen)

void cpu_rand_uniform_float(float* ptr, size_t count, float low, float high, Generator& gen);

功能简介 生成 N 个均匀分布的 FP32。

参数

返回值 无

异常 无

cpu_rand_normal_float(float* ptr, size_t count, float mean, float std, Generator& gen)

void cpu_rand_normal_float(float* ptr, size_t count, float mean, float std, Generator& gen);

功能简介 生成 N 个正态分布的 FP32。

参数

返回值 无

异常 无

便捷函数（使用默认生成器）

所属头文件：#include

以下函数使用默认全局生成器，参数列表省略 Generator& 参数：

inline void cpu_rand_uint64(uint64_t* ptr, size_t count);
inline void cpu_rand_bernoulli_int8(int8_t* ptr, size_t count, float prob_one);
inline void cpu_rand_uniform_int8(int8_t* ptr, size_t count, int8_t low, int8_t high);
inline void cpu_rand_bernoulli_int32(int32_t* ptr, size_t count, float prob_one);
inline void cpu_rand_uniform_int32(int32_t* ptr, size_t count, int32_t low, int32_t high);
inline void cpu_rand_uniform_float(float* ptr, size_t count, float low = 0.0f, float high = 1.0f);
inline void cpu_rand_normal_float(float* ptr, size_t count, float mean = 0.0f, float std = 1.0f);

Philox 算法函数（tr::detail）

所属头文件：#include

注意：以下函数位于 tr::detail 命名空间，主要供框架内部 RNG 实现使用，普通用户通常不需要直接调用。

Philox4x32-10 伪随机数生成算法，Counter-Based RNG，支持 CPU/GPU 并行可复现生成。

philox4x32_round(...)

TR_HOST_DEVICE TR_FORCEINLINE
void philox4x32_round(uint32_t* ctr0, uint32_t* ctr1, uint32_t* ctr2, uint32_t* ctr3,
                      uint32_t key0, uint32_t key1);

功能简介 Philox4x32 单轮函数。

philox4x32_10(...)

TR_HOST_DEVICE TR_FORCEINLINE
void philox4x32_10(uint32_t* ctr0, uint32_t* ctr1, uint32_t* ctr2, uint32_t* ctr3,
                  uint32_t key0, uint32_t key1);

功能简介 Philox4x32-10 核心函数（10 轮迭代）。

philox_generate_4x32(...)

TR_HOST_DEVICE TR_FORCEINLINE
void philox_generate_4x32(uint64_t seed, uint64_t offset, uint32_t* out);

功能简介 从 seed 和 offset 生成 4 个 uint32 随机数。

philox_uniform_float(...)

TR_HOST_DEVICE TR_FORCEINLINE
float philox_uniform_float(uint64_t seed, uint64_t offset);

功能简介 生成 [0, 1) 范围的 float。

philox_normal_pair(...)

TR_HOST_DEVICE TR_FORCEINLINE
void philox_normal_pair(uint64_t seed, uint64_t offset, float* out0, float* out1);

功能简介 Box-Muller 变换生成标准正态分布（一次生成两个）。

philox_uint64(...)

TR_HOST_DEVICE TR_FORCEINLINE
uint64_t philox_uint64(uint64_t seed, uint64_t offset);

功能简介 生成单个 uint64 随机数。

Data

板块介绍

Data 模块是 Tech-Renaissance 框架的数据处理核心，负责数据加载、预处理增强和高效传输。该模块采用多线程流水线架构，支持 JPEG 图像的局部解码、随机数据增强、双缓冲传输等高性能优化。

核心职责：

• 数据加载：支持 MNIST、CIFAR、ImageNet 等常用数据集，提供 DTS 压缩格式和原始格式
• 图像预处理：提供完整的图像增强操作链，包括裁剪、缩放、翻转、颜色抖动等
• 高效传输：采用双缓冲区和多流架构，实现计算与传输的重叠
• 随机可复现：通过 Philox RNG 确保数据增强的随机性可精确复现

对外提供的核心能力：

• 统一的数据加载接口：DataLoader 抽象基类定义了标准的数据加载规范
• 灵活的预处理流水线：Preprocessor 和 PreprocessOperation 支持可组合的数据增强
• 高性能多线程处理：支持 200+ 预处理线程的并发操作
• 部署场景支持：SampleLoader 专为单样本推理场景优化

关键类和组件：

• DataLoader：数据加载器抽象基类，定义统一接口
• Preprocessor：图像预处理器，管理多线程预处理流水线
• PreprocessOperation：预处理操作基类，所有数据增强操作的抽象
• TransferStation：双缓冲区管理器，实现 CPU-GPU 间的高效数据传输
• SampleInfo：样本信息结构体，用于 FULLY 模式的样本记录

关键头文件：

• include/renaissance/data/data_loader.h
• include/renaissance/data/preprocessor.h
• include/renaissance/data/preprocess_operation.h
• include/renaissance/data/transfer_station.h

内部实现位置：

• src/data/

DataLoader

概述

DataLoader 是数据加载器的抽象基类，定义了统一的数据加载接口规范。所有具体的数据加载器（如 MNISTLoaderDTS、CIFARLoaderDTS、ImageNetLoaderDTS 等）都必须继承此类并实现其纯虚函数。

设计特点：

• 线程安全：多个 Preprocessor worker 可并发调用 get_next_sample()
• 零拷贝：返回的样本数据直接指向内部缓冲区，避免内存复制
• 三级随机性：支持导出级、Block级、样本级的随机化，保证可复现性
• 单例模式：所有子类必须实现为全局单例

所属头文件： #include

继承关系：

• 具体数据加载器继承此类，如 MNISTLoaderDTS、CIFARLoaderDTS、ImageNetLoaderDTS 等

常用使用路径： 通过具体数据加载器的单例实例使用，如 MNISTLoaderDTS::instance()。

典型使用代码片段：

// 通过 Preprocessor 配置数据集时自动使用对应的 DataLoader
PREPROCESSOR_SETTING
    .dataset("mnist", "/data/mnist")
    .commit();

构造与析构

DataLoader::~DataLoader()

签名

virtual ~DataLoader() = default;

功能简介 虚析构函数，确保子类析构时正确释放资源。

返回值 无

异常 无

配置接口

DataLoader::configure(int, int, const std::string&, const std::string&, bool, bool, bool, bool)

签名

virtual void configure(
    int num_load_workers,
    int num_preproc_workers,
    const std::string& train_path,
    const std::string& val_path,
    bool shuffle_train = true,
    bool shuffle_val = false,
    bool skip_first = false,
    bool verify_crc = false
) = 0;

功能简介 配置 DataLoader 的运行参数，包括线程数、数据路径和随机化设置。

参数

返回值 无

异常 ValueError：如果参数值不合法（如线程数为负数）

生命周期管理

DataLoader::begin_epoch(int, bool)

签名

virtual void begin_epoch(int epoch_id, bool is_train) = 0;

功能简介 开始一个新的 epoch，用于随机化的 epoch ID 和训练/验证模式标识。

参数

返回值 无

异常 无

DataLoader::end_epoch()

签名

virtual void end_epoch() = 0;

功能简介 结束当前 epoch，清理状态并准备下一个 epoch。

返回值 无

异常 无

DataLoader::reset_after_warmup()

签名

virtual void reset_after_warmup();

功能简介 重置 DataLoader 状态（用于 warmup 和 test_dataloader 之后），释放 FULLY 模式分配的内存并重置所有加载标记。

返回值 无

异常 无

核心数据接口

DataLoader::get_next_sample(int, int32_t&, const uint8_t*&, size_t&)

签名

virtual bool get_next_sample(
    int preproc_worker_id,
    int32_t& label,
    const uint8_t*& data_ptr,
    size_t& data_size
) = 0;

功能简介 获取下一个样本（线程安全，零拷贝）。多个 Preprocessor worker 可并发调用此方法。

参数

返回值 true 表示成功获取样本，false 表示 epoch 结束。

异常 无

注意事项 返回的 data_ptr 指向 DataLoader 内部缓冲区，不应释放或修改。

状态查询

DataLoader::dataset_name()

签名

virtual const char* dataset_name() const = 0;

功能简介 获取数据集名称，用于日志和调试。

返回值 数据集名称字符串（如 "MNIST"、"CIFAR-10"、"ImageNet"）。

异常 无

DataLoader::num_train_samples()

签名

virtual size_t num_train_samples() const = 0;

功能简介 获取训练集样本总数。

返回值 训练集样本数量。

异常 无

DataLoader::num_val_samples()

签名

virtual size_t num_val_samples() const = 0;

功能简介 获取验证集样本总数。

返回值 验证集样本数量。

异常 无

DataLoader::is_loaded()

签名

virtual bool is_loaded() const = 0;

功能简介 检查数据集是否已加载完成。

返回值 true 表示已加载，false 表示未加载或加载中。

异常 无

DataLoader::set_train_mode(LoadMode)

签名

virtual void set_train_mode(LoadMode mode) = 0;

功能简介 设置训练集加载模式（AUTO / FULLY / PARTIAL）。

参数

返回值 无

异常 无

DataLoader::set_val_mode(LoadMode)

签名

virtual void set_val_mode(LoadMode mode) = 0;

功能简介 设置验证集加载模式（AUTO / FULLY / PARTIAL）。

参数

返回值 无

异常 无

DataLoader::load_next_buffer()

签名

virtual void load_next_buffer();

功能简介 加载下一个缓冲区（仅 PARTIAL 模式需要）。基类默认实现抛出 std::runtime_error。

返回值 无

异常 std::runtime_error：如果子类未实现此方法。

DataLoader::has_more_buffers() const

签名

virtual bool has_more_buffers() const;

功能简介 检查是否还有更多缓冲区需要加载（仅 PARTIAL 模式需要）。基类默认实现返回 false。

返回值 true 表示还有更多缓冲区，false 表示已完成。

异常 无

数据集下载和验证

DataLoader::download(const std::string&)

签名

virtual void download(const std::string& save_path) = 0;

功能简介 下载数据集（如果尚未下载）。支持开源数据集的自动下载。

参数