此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 函数
  • blobconverter_export
  • get_preprocessing
  • hubai_export
  • make_initializers_unique
  • rename_onnx_outputs
  • replace_weights
  • try_onnx_simplify
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

export_utils

最后更新
Python API: luxonis_train.core.utils.export_utilsONNX 导出及其后续转换的辅助函数。LuxonisModel.export、LuxonisModel.archive、LuxonisModel.convert 和 LuxonisModel.quantize 调用这些辅助函数。这些辅助函数执行以下步骤:
  • 简化 ONNX 图并复制其共享初始化器;
  • 重命名图输出;
  • 读取配置的归一化;
  • 使用 blobconverter 或 HubAI SDK 转换模型。
replace_weights 还为 LuxonisModel.test、LuxonisModel.infer 和 LuxonisModel.annotate 加载权重。

函数

blobconverter_export

Python
1def blobconverter_export(cfg: ExportConfig, scale_values: list[float] | None, mean_values: list[float] | None, reverse_channels: bool, export_path: PathType, onnx_path: PathType) -> Path:
使用 blobconverter 将 ONNX 模型转换为 .blob 文件。该函数使用 cfg.blobconverter.shaves 和 cfg.blobconverter.version 调用 blobconverter.from_onnx,并关闭缓存。它将 scale_values、mean_values 和 reverse_channels 作为 --scale_values=[...]、--mean_values=[...] 和 --reverse_input_channels 传递给模型优化器。它会忽略 None、空或 False 的值。blobconverter 将模型发送到其在线服务,因此转换需要网络访问。cfg.quantization_mode 选择数据类型。模式 "FP16_STANDARD" 给出 FP16,而 "FP32_STANDARD" 给出 FP32。任何其他模式,例如默认的 "INT8_STANDARD",都给出 FP16 并记录警告。参数
  • cfg (ExportConfig): 配置的 exporter 部分。
  • scale_values (list[float] | None): 输入归一化的比例,按通道,以 uint8 像素单位。get_preprocessing 中的标准差具有此格式。
  • mean_values (list[float] | None): 输入归一化的平均值,按通道,以 uint8 像素单位。get_preprocessing 中的平均值具有此格式。
  • reverse_channels (bool): 当为 True 时,传递 --reverse_input_channels,它会交换输入通道的顺序。
  • export_path (PathType): 接收 .blob 文件的目录。
  • onnx_path (PathType): 要转换的 ONNX 文件。
返回
  • Path: .blob 文件的路径。

get_preprocessing

Python
1def get_preprocessing(cfg: PreprocessingConfig, log_label: str | None = None) -> tuple[list[float] | None, list[float] | None, Literal['RGB', 'BGR', 'GRAY']]:
读取配置的归一化值和颜色空间。平均值和标准差来自 cfg.normalize.params,乘以 255 并四舍五入到小数点后五位,因此它们适用于 uint8 像素值。LuxonisModel 将这些值放入 modelconverter 配置和 NN Archive 中,并将它们传递给 blobconverter。当设置了 exporter.mean_values 和 exporter.scale_values 时,它们会替换那里的值。在以下情况下,值为 None:
  • cfg.normalize.active 为 False。此时两个值都为 None。
  • cfg.normalize.params 没有值的 "mean" 或 "std" 键。
  • 键下的值不是数字列表。
在后两种情况下,当 log_label 不为 None 时,函数会记录警告。警告会指明调用者和未设置的值。参数
  • cfg (PreprocessingConfig): 配置的 trainer.preprocessing 部分。
  • log_label (str | None): 警告中调用者的名称,例如 "Model export"。None 禁用警告。
返回
  • tuple[list[float] | None, list[float] | None, Literal['RGB', 'BGR', 'GRAY']]: 平均值、标准差值和 cfg.color_space。

hubai_export

Python
1def hubai_export(cfg: HubAIExportConfig, quantization_mode: str, archive_path: PathType, export_path: PathType, model_name: str, dataset_name: str | None = None) -> Path:
通过 HubAI SDK 转换设备的 ONNX NN Archive。该函数将 archive 作为名为 model_name 的模型的变体上传到 HubAI。它重用具有此名称的第一个模型,并在不存在时创建模型。当模型查找失败时,函数会记录警告并创建新模型。变体名为 <model_name>:<dataset_name>,当 dataset_name 为 None 或为空时为 model_name。cfg.platform 选择 SDK 的转换调用:RVC3 用于 "rvc3",RVC4 用于 "rvc4",RVC2 用于 "rvc2" 或 None。调用接收关键字参数 path、quantization_mode、name 和 model_id。cfg.params 的条目也传递给调用,并替换同名参数。SDK 下载转换后的 archive。函数将其移动到 export_path 中,并使用其自己的文件名。然后,当下载目录为空且不是工作目录时,它会删除下载目录。当设置了 cfg.delete_remote_model 时,函数会在结束时清理 HubAI:
  • 它会删除它创建的模型,即使转换引发错误。
  • 当模型之前存在时,它只删除新的变体。这只发生在转换调用返回时。
删除失败会记录警告,但不会引发错误。参数
  • cfg (HubAIExportConfig): 配置的 exporter.hubai 部分。
  • quantization_mode (str): 要转换的精度,例如 "INT8_STANDARD" 或 "FP16_STANDARD"。
  • archive_path (PathType): 要转换的 ONNX NN Archive。
  • export_path (PathType): 接收转换后的 archive 的目录。
  • model_name (str): HubAI 上的模型名称。
  • dataset_name (str | None): 训练数据集的名称。它是变体名称的第二部分。
返回
  • Path: export_path 中转换后的 archive 的路径。
引发
  • ValueError: 当 HUBAI_API_KEY 环境变量未设置或为空时。
  • NotImplementedError: 当 cfg.platform 为 "hailo" 时。

make_initializers_unique

Python
1def make_initializers_unique(onnx_path: PathType):
为每个节点输入提供其自己的共享 ONNX 初始化器副本。该函数计算主图的每个初始化器被多少个节点输入读取。它将两个或更多输入读取的初始化器替换为每个输入一个副本,命名为 <name>_unique_<i>。节点顺序中第 i 个此类输入(从 0 开始)读取索引为 i 的副本。读取一次或根本不读取的初始化器保留其名称。该函数将模型保存到 onnx_path 并使用 onnx.checker.check_model 进行检查。检查失败会记录警告。最后,函数会记录它复制了多少个初始化器。当图没有初始化器时,函数会记录警告并保持文件不变。参数
  • onnx_path (PathType): 要修改的 ONNX 文件。

rename_onnx_outputs

Python
1def rename_onnx_outputs(onnx_path: PathType, output_names: list[str]):
就地重命名 ONNX 模型中的图输出。该函数按顺序将图的输出与 output_names 配对。它重命名每个图输出以及生成它的每个节点的输出。它不重命名读取此类输出的节点的输入。当模型旁边存在文件 <onnx_path.name>.data 时,函数会在加载后删除它。然后,它将模型保存到 onnx_path,并将初始化器保存在该名称的新外部数据文件中。节点属性的张量保留在模型文件中。否则,函数将整个模型保存到 onnx_path。然后,它使用 onnx.checker.check_model 检查保存的文件。如果模型无效,检查会引发错误。参数
  • onnx_path (PathType): 要修改的 ONNX 文件。
  • output_names (list[str]): 新的输出名称,每个图输出一个,按图顺序。
引发
  • ValueError: 当 output_names 的长度与图输出的数量不同时。

replace_weights

Python
1def replace_weights(module: _WeightLoadable[_WeightsT_contra], weights: _WeightsT_contra | None = None) -> Generator[None, None, None]:
在 with 块中将 weights 加载到 module 中。进入时,当 weights 不为 None 时,管理器会保留 module.state_dict() 的深层副本。然后,它使用 LuxonisLightningModule.load_checkpoint 加载 weights,这也会将模块置于评估模式。它在模块上设置私有标志 _weights_explicitly_loaded。当该标志设置时,EMACallback 不会交换模块到 EMA 权重,也不会将其交换回来。退出时,即使块中出现错误,管理器也会清除标志并将保留的状态字典加载到模块中。它不会恢复模块在块之前所处的训练模式。当 weights 为 None 时,块在模块不变的情况下运行。参数
  • module (_WeightLoadable[_WeightsT_contra]): 接收权重的模块。
  • weights (_WeightsT_contra | None): 检查点文件的路径,或带有 state_dict 键的已加载检查点。None 使模块保持不变。
返回
  • Generator[None, None, None]
生成
  • 管理器不生成任何值。块在加载 weights 的情况下运行。

try_onnx_simplify

Python
1def try_onnx_simplify(onnx_path: PathType):
在可用时,使用 onnxsim 就地简化 ONNX 模型。该函数加载模型,运行 onnxsim.simplify,并将结果保存到 onnx_path。在以下情况下,它会记录错误并保持文件不变:
  • 未安装 onnxsim。函数还会记录警告。
  • onnxsim 的检查报告简化模型无效。
参数
  • onnx_path (PathType): 要简化的 ONNX 文件。