# export_utils

Python API: `luxonis_train.core.utils.export_utils`

ONNX 导出及其后续转换的辅助函数。

[LuxonisModel.export](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)、[LuxonisModel.archive](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)、[LuxonisModel.convert](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
和
[LuxonisModel.quantize](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
调用这些辅助函数。这些辅助函数执行以下步骤：

 * 简化 ONNX 图并复制其共享初始化器；
 * 重命名图输出；
 * 读取配置的归一化；
 * 使用 `blobconverter` 或 HubAI SDK 转换模型。

[replace_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/export_utils.md)
还为
[LuxonisModel.test](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)、[LuxonisModel.infer](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
和
[LuxonisModel.annotate](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
加载权重。

## 函数

### blobconverter_export

```python
def 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](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/export_utils.md)
   中的标准差具有此格式。
 * `mean_values` (`list[float] | None`): 输入归一化的平均值，按通道，以 `uint8`
   像素单位。[get_preprocessing](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/export_utils.md)
   中的平均值具有此格式。
 * `reverse_channels` (`bool`): 当为 `True` 时，传递 `--reverse_input_channels`，它会交换输入通道的顺序。
 * `export_path` (`PathType`): 接收 `.blob` 文件的目录。
 * `onnx_path` (`PathType`): 要转换的 ONNX 文件。

返回

 * `Path`: `.blob` 文件的路径。

### get_preprocessing

```python
def 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](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
将这些值放入 `modelconverter` 配置和 NN Archive 中，并将它们传递给 `blobconverter`。当设置了 `exporter.mean_values` 和 `exporter.scale_values`
时，它们会替换那里的值。

在以下情况下，值为 `None`：

 * `cfg.normalize.active` 为 `False`。此时两个值都为 `None`。
 * `cfg.normalize.params` 没有值的 `"mean"` 或 `"std"` 键。
 * 键下的值不是数字列表。

在后两种情况下，当 `log_label` 不为 `None` 时，函数会记录警告。警告会指明调用者和未设置的值。

> **示例**
> ```pycon
>>> from luxonis_train.config.config import PreprocessingConfig
>>> get_preprocessing(PreprocessingConfig())
([123.675, 116.28, 103.53], [58.395, 57.12, 57.375], 'RGB')
```

```pycon
>>> get_preprocessing(PreprocessingConfig(normalize={"active": False}))
(None, None, 'RGB')
```

```pycon
>>> cfg = PreprocessingConfig(normalize={"params": {"mean": [0.5]}})
>>> get_preprocessing(cfg)
([127.5], None, 'RGB')
```

参数

 * `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
def 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
def 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
def 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
def 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](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md) 加载 `weights`，这也会将模块置于评估模式。它在模块上设置私有标志 `_weights_explicitly_loaded`。当该标志设置时，[EMACallback](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/ema.md) 不会交换模块到 EMA 权重，也不会将其交换回来。退出时，即使块中出现错误，管理器也会清除标志并将保留的状态字典加载到模块中。它不会恢复模块在块之前所处的训练模式。

当 `weights` 为 `None` 时，块在模块不变的情况下运行。

参数

 * `module` (`_WeightLoadable[_WeightsT_contra]`): 接收权重的模块。
 * `weights` (`_WeightsT_contra | None`): 检查点文件的路径，或带有 `state_dict` 键的已加载检查点。`None` 使模块保持不变。

返回

 * `Generator[None, None, None]`

生成

 * 管理器不生成任何值。块在加载 `weights` 的情况下运行。

### try_onnx_simplify

```python
def try_onnx_simplify(onnx_path: PathType):
```

在可用时，使用 `onnxsim` 就地简化 ONNX 模型。

该函数加载模型，运行 `onnxsim.simplify`，并将结果保存到 `onnx_path`。在以下情况下，它会记录错误并保持文件不变：

 * 未安装 `onnxsim`。函数还会记录警告。
 * `onnxsim` 的检查报告简化模型无效。

参数

 * `onnx_path` (`PathType`): 要简化的 ONNX 文件。
