训练、执行与评估

QML 训练可以使用标准 PyTorch 循环，也可以使用 Trainer、梯度工具、回调和指标组成可复用流程。

最小训练示例


from unitarylab.library.qml.examples.classification import (
    build_classifier,
    train_classifier,
)
from unitarylab.library.qml.examples.datasets import load_toy_multiclass
 
dataset = load_toy_multiclass(samples_per_class=2, seed=0)
model = build_classifier("vqc", seed=0)
loss_history = train_classifier(
    model,
    dataset.features,
    dataset.targets,
    epochs=1,
    learning_rate=0.03,
)
print(loss_history)

这是完整的 PyTorch 训练流程：模型拥有可训练参数，损失执行反向传播，优化器更新参数。随机初始化和数据生成均使用显式种子。

训练组件


from unitarylab.library.qml.engine import (
    Trainer,
    TorchOptimizer,
    TorchScheduler,
    EarlyStopping,
    ModelCheckpoint,
    evaluate,
    save_parameters,
    load_parameters,
)

组件	作用
`Trainer`	组织训练步、验证、历史记录和回调
`TorchOptimizer`、`TorchScheduler`	包装 PyTorch 优化器和学习率计划
`EarlyStopping`	根据监控指标提前停止
`ModelCheckpoint`	保存最佳或周期性参数
`NoiseScheduler`	训练期间调整噪声强度
`evaluate()`	在数据集上计算损失和指标
`save_parameters()`、`load_parameters()`	保存和恢复参数

训练器需要模型、目标函数、优化器和数据。分类任务应选择与输出匹配的二元或多类损失；回归任务应保证预测与目标 shape 可广播或完全一致。

梯度方法

方法	特点
`autograd_gradient()`	使用后端或 PyTorch 自动微分
`backend_vjp_loss_gradient()`	使用后端向量–雅可比积
`parameter_shift_gradient()` / `parameter_shift_jacobian()`	参数移位，适合支持移位规则的门
`batched_parameter_shift_gradient()` / `parallel_parameter_shift_gradient()`	批量或并行执行参数移位线路
`finite_difference_gradient()`	通用数值差分，调用次数较多
`spsa_gradient()`	随机近似，适合参数较多或有采样噪声的情况
`mixed_parameter_gradient()`	按参数类型组合多种梯度策略

参数移位只适用于具有已知移位规则的参数化门。有限 shots 下梯度存在统计波动，应固定种子、记录 shots，并通过多次运行评估方差。

指标与目标函数


from unitarylab.library.qml.metrics import (
    multiclass_accuracy,
    mean_squared_error,
)
from unitarylab.library.qml.objectives import (
    SupervisedObjective,
    BornMachineNLLObjective,
)

分类指标包括准确率、精确率、召回率、F1、混淆矩阵和 ROC AUC；回归指标包括 MAE、MSE、RMSE 和 $R^{2}$ 。生成任务可使用 Born Machine 的 NLL、KL 散度或 MMD 目标，以及 QGAN 生成器/判别器损失。

诊断与持久化

gradient_variance_report()、per_sample_gradient_norms() 和 trainability_report() 可用于检查梯度消失、样本梯度差异和参数块训练性。检查点文件只应从可信来源加载；恢复时模型结构和参数 shape 必须与保存时一致。

资源建议

先用极小 batch 和一个 epoch 做形状、dtype、设备检查。
状态向量模拟的内存随量子比特数指数增长；参数移位每步还会增加多次线路执行。
训练集、验证集和测试集应分离；调参不得使用测试指标。
同时记录随机种子、后端、shots、dtype 和模型结构，确保实验可复现。