# config

Python API: `modelconverter.utils.config`

描述转换的配置模型。

转换由 YAML 文件（参见 `configs/defaults.yaml`）描述，该文件被解析为此处定义的 pydantic 模型。顶层
[Config](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md)
为每个阶段包含一个
[SingleStageConfig](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md)，每个阶段描述输入模型、其输入和输出、校准数据以及平台特定选项（[HailoConfig](https://docs.luxonis.com/zh/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md)、[RVC2Config](https://docs.luxonis.com/zh/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md)、[RVC3Config](https://docs.luxonis.com/zh/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md)
和
[RVC4Config](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md)）。

用户未提供的值将从输入模型本身的元数据中填充，以便在每个后端 Docker 映像中运行的导出器接收到模型的完全解析描述。

## 类

### BlobBaseConfig

OpenVINO 平台共享的选项。

RVC2 和 RVC3 配置的基类，它们都通过 OpenVINO 将模型转换为 blob。

#### 属性

##### compile_tool_args

传递给 OpenVINO `compile_tool` 的附加参数。它们优先于默认参数。

##### compress_to_fp16

是否将原始模型的 FP32 权重和偏差压缩为 FP16。所有中间数据都保持原始精度。

##### mo_args

传递给 OpenVINO 模型优化器的附加参数。它们优先于默认参数。

### Config

转换的顶层配置。

也接受单阶段配置：阶段字段可以在顶层给出，并在验证期间封装到单个阶段中，因此简写

```yaml
input_model: models/yolov6n.onnx
encoding:
  from: RGB
  to: BGR
calibration:
  path: models/coco128
```

等同于在 `stages` 的单个条目下嵌套的相同字段。有关每个字段及其默认值，请参阅 `configs/defaults.yaml`。

#### 方法

##### get_stage_config

```python
def get_stage_config(stage: str | None) -> SingleStageConfig:
```

返回给定阶段的配置。

参数

 * `stage` (`str | None`): 阶段名称。只有当配置只有一个阶段时才能为 `None`。

返回

 * `SingleStageConfig`: 所请求阶段的配置。

引发

 * `ValueError`: 如果未给出阶段名称且配置有多个阶段。
 * `KeyError`: 如果不存在给定名称的阶段。

#### 属性

##### name

模型名称。默认为用破折号连接的阶段名称，或者对于单个未命名阶段，默认为输入模型的词干。

##### rich_logging

是否对日志消息使用富格式。

##### stages

各个阶段的配置，以阶段名称为键。

### EncodingConfig

为输入请求的颜色编码转换。

`from` 字段（在 Python 中命名为 `from_`）是原始模型期望的编码。`to` 字段是转换后的模型在运行时接收的编码。如果两者不同，则在输入前添加通道反转，以便转换后的模型接收 `to` 数据，而原始图仍接收 `from` 数据。

#### 属性

##### from_

### Encodings

覆盖计算出的量化编码集。

#### 属性

##### activation_encodings

激活张量的编码，以张量名称为键。

##### param_encodings

参数张量的编码，以张量名称为键。

### HailoConfig

Hailo 转换的选项。

#### 属性

##### alls

传递给模型优化器的 Hailo 模型脚本 (`alls`) 的附加行。

##### batch_size

用于校准的批大小。

##### compression_level

压缩级别，介于 `0` 和 `5` 之间。

##### disable_compilation

是否在量化后停止，而不编译模型。

##### force_onnx_names

是否强制在生成的 `.har` 和 `.hef` 模型上使用 ONNX 名称。

##### hw_arch

要编译的 Hailo 硬件架构。

##### optimization_level

优化级别，介于 `0` 和 `4` 之间，或 `-100` 以禁用所有优化。

### ImageCalibrationConfig

从文件目录读取的校准数据。

#### 属性

##### generated_from_random

此文件源是否由随机校准生成。

##### generated_layout

生成张量校准时使用的布局。

##### max_images

要使用的校准数据文件数量。负值表示全部。

##### path

校准数据的路径。可以是本地目录、远程 URL 或 `<dataset_name>:<split>` 形式的 LDF 数据集标识符；它在验证期间下载并存储为本地路径。

##### resize_method

如何将图像调整为输入形状。

### InputConfig

模型单个输入的描述。

扩展
[OutputConfig](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md)，包含输入的预处理和校准设置。每个转换都以自己的方式应用
`mean_values` 和 `scale_values`：RVC4 导出器将它们烘焙到 ONNX 图中，RVC2 和 RVC3 将它们传递给 OpenVINO 模型优化器，Hailo 将它们放入模型脚本中。

#### 方法

##### requires_input_preprocessing

```python
def requires_input_preprocessing(*, reverse_only: bool = False) -> bool:
```

检查是否为此输入请求了预处理。

参数

 * `reverse_only` (`bool`): 如果为 `True`，则只考虑通道反转，忽略均值和比例值。

返回

 * `bool`: 如果编码不同，或者（除非设置了 `reverse_only`）如果设置了任何非中性均值或比例值，则为 `True`。

##### validate_input_contract

```python
def validate_input_contract(*, validate_values: bool = True):
```

根据已知通道轴验证编码和预处理。

##### validate_preprocessing

```python
def validate_preprocessing(*, reverse_only: bool = False) -> int:
```

验证请求的预处理并返回通道计数。

参数

 * `reverse_only` (`bool`): 仅验证请求的编码转换。

返回

 * `int`: 已解析的输入通道数。

引发

 * `ValueError`: 如果输入契约不足或不一致。

#### 属性

##### calibration

此输入的校准数据源。

##### calibration_preprocessing

从模型中移出但保留用于校准的预处理。

##### channel_count

当 `C` 可信时返回正通道计数。

##### encoding

此输入的颜色编码转换。

##### encoding_mismatch

返回 `from` 和 `to` 编码是否不同。

##### frozen_value

输入被冻结到的常量值列表。仅由基于 OpenVINO 的转换（RVC2 和 RVC3）使用，它们将其传递给模型优化器。

##### is_color_input

返回输入是否接收彩色图像数据。

##### is_raw_input

返回输入是否接收非图像数据。

##### mean_values

从输入中减去的每通道值，与 `scale_values` 具有相同的选项。

##### scale_values

在减去 `mean_values` 后，输入被除以的每通道值。可以作为单个数字、列表或预设名称（例如 `"imagenet"`）给出。

### LinkCalibrationConfig

由转换的另一个阶段生成的校准数据。

用于多阶段模型，其中一个阶段的校准数据是通过运行先前转换的阶段的推理获得的。

#### 属性

##### output

用作校准数据的 `stage` 输出的名称。

##### script

后处理 `stage` 输出的 Python 脚本。可以是源代码本身，也可以是 `.py` 文件的路径，其内容在验证期间读取。必须提供 `output` 或 `script`。

##### stage

从中获取校准数据的阶段名称。

### ONNXOptimizationsConfig

单个 ONNX 图优化的开关。

优化在 ONNX 模型移交给平台特定转换之前应用。默认情况下，所有优化都启用。

#### 方法

##### all_disabled

```python
def all_disabled(self) -> bool:
```

检查是否所有优化都已关闭。

#### 属性

##### fuse_add_mul_to_bn

是否将 `Conv` 节点后面的 `Add`/`Sub` 和 `Mul` 节点融合到 `BatchNormalization` 节点中。

##### fuse_comb_add_mul_to_conv

是否将 `Conv` 节点前面的 `Add` 和 `Mul` 节点的组合融合到 `Conv` 节点中。

##### fuse_single_add_mul_to_conv

是否将 `Conv` 节点前面的单个 `Add` 或 `Mul` 节点融合到 `Conv` 节点中。

##### fuse_split_concat_to_conv

是否将 `Conv` 节点前面的 `Split` 和 `Concat` 节点融合到 `Conv` 节点中。

##### substitute_div_with_mul

是否将第二个操作数是浮点常量的 `Div` 节点替换为 `Mul` 节点和该常量的倒数副本。

##### substitute_sub_with_add

是否将第二个操作数是常量的 `Sub` 节点替换为 `Add` 节点和该常量的负数副本。

### OutputConfig

模型单个输出的描述。

#### 方法

##### validate_layout

```python
def validate_layout(self) -> Self:
```

检查布局和形状是否具有相同的长度。

返回

 * `Self`: 经过验证的模型。

引发

 * `ValueError`: 如果布局的长度与形状的长度不匹配。

#### 属性

##### data_type

输出的数据类型。

##### layout

布局的字母代码表示，例如 `"NCHW"`。需要提供 `shape`；如果只给出 `shape`，则从形状推断默认布局。

##### name

输出张量或节点的名称。

##### shape

输出的形状。如果未提供，则从模型推断。

### PlatformConfig

阶段平台特定部分的基类。

#### 属性

##### disable_calibration

是否跳过校准，以及模型的量化。

### QuantizationOverrides

传递给 SNPE 的原始 RVC4 量化覆盖。

有效负载要么保留为用户提供的映射，要么保留为用户提供的文件的路径。除非调用者已经提供了 `Encodings` 对象，否则它不会有意地通过 `Encodings` 强制转换。

#### 方法

##### from_path

```python
def from_path(path: Path) -> QuantizationOverrides:
```

从 JSON 文件路径构建覆盖。

##### from_payload

```python
def from_payload(payload: dict[str, Any]) -> QuantizationOverrides:
```

从内联 JSON 有效负载构建覆盖。

##### load_payload

```python
def load_payload(self) -> dict[str, Any]:
```

返回 JSON 有效负载而不改变存储的源。

##### serialize

```python
def serialize(self) -> dict[str, Any] | str:
```

像用户可见的 `rvc4.encodings` 值一样序列化。

#### 属性

##### payload

##### source_path

### QuantizationOverridesItem

单个张量的量化编码。

遵循 AIMET 编码规范，用于覆盖 RVC4 转换期间计算的量化参数。

#### 方法

##### serialize_is_symmetric

```python
def serialize_is_symmetric(value: bool | None) -> str | None:
```

将 `is_symmetric` 序列化为 JSON 输出中的字符串。

参数

 * `value` (`bool | None`): `is_symmetric` 字段的值。

返回

 * `str | None`: 值的字符串表示，如果值为 `None`，则为 `None`。

#### 属性

##### bitwidth

用于表示张量的位数。

##### dtype

张量是量化为整数还是浮点数。

##### is_symmetric

量化是否对称。

##### max

最大可表示值。

##### min

最小可表示值。

##### offset

量化网格的零点偏移。

##### scale

量化网格的步长。

### RandomCalibrationConfig

从正态分布生成的校准数据。

在未提供校准数据时使用。生成的值从正态分布中抽取并裁剪到允许的范围。

#### 属性

##### data_type

生成的样本被转换为的数据类型。

##### max_images

要生成的样本数。

##### max_value

生成的值被裁剪到的上限。

##### mean

正态分布的均值。

##### min_value

生成的值被裁剪到的下限。

##### std

正态分布的标准差。

### RVC2Config

RVC2 转换的选项。

#### 属性

##### n_workers

用于并行 superblob 编译的工作器数量。覆盖自动确定的数量。

##### number_of_shaves

blob 编译的 SHAVE 核心数量。当启用 `superblob` 时强制为 `8`。

##### superblob

是否生成 `.superblob` 文件而不是常规 `.blob`。

### RVC3Config

RVC3 转换的选项。

#### 属性

##### pot_target_device

OpenVINO 训练后优化工具的目标设备。

### RVC4Config

RVC4 转换的选项。

#### 方法

##### validate_encodings

```python
def validate_encodings(value: ParamValue | QuantizationOverrides | Encodings) -> QuantizationOverrides | Encodings | None:
```

保留配置中的量化编码。

参数

 * `value` (`ParamValue | QuantizationOverrides | Encodings`): `None`、JSON 字符串、JSON 文件路径或已解析的映射。

返回

 * `QuantizationOverrides | Encodings | None`: 原始编码源，如果未给出值，则为 `None`。

##### validate_quantization_overrides

```python
def validate_quantization_overrides(self) -> Self:
```

将原始量化覆盖参数规范化为 `encodings`。

`--quantization_overrides PATH` 和 `--quantization_overrides=PATH` 形式都从 `snpe_onnx_to_dlc_args` 中删除，并且引用的 JSON 文件存储为原始 `encodings`
源。

返回

 * `Self`: 经过验证的模型。

引发

 * `ValueError`: 如果缺少原始覆盖路径，提供了多个原始覆盖，或者原始覆盖与 `encodings` 结合使用。

#### 属性

##### disable_calibration

##### encodings

传递给 SNPE 的原始量化覆盖。当启用严格验证时，ModelConverter 只检查名称，当启用 IO 规范化时，只重写暴露的 IO 条目。

##### htp_socs

预计算 DLC 图的平台。

##### keep_raw_images

是否在中间输出中保留原始校准图像。它们可能会变得非常大。

##### normalize_io_encodings

是否将暴露的输入/输出激活编码替换为默认的 8 位整数编码。

##### optimization_level

DLC 图准备的优化级别。级别越高，所需时间越长，但生成的图速度越快。

##### quantization_mode

预定义的量化模式。除 `CUSTOM` 外的所有模式都覆盖用户提供的 SNPE 参数。

##### snpe_dlc_graph_prepare_args

传递给 SNPE `snpe-dlc-graph-prepare` 的附加参数。

##### snpe_dlc_quant_args

传递给 SNPE `snpe-dlc-quant` 的附加参数。

##### snpe_onnx_to_dlc_args

传递给 SNPE `snpe-onnx-to-dlc` 的附加参数。它们优先于默认参数。

##### strict_quantization_overrides

是否根据有效 ONNX 模型中的激活/参数组验证配置的量化覆盖名称。

##### use_per_channel_quantization

是否对支持的层类型的权重和偏差使用逐轴元素量化。

##### use_per_row_quantization

是否对 `MatMul` 和 `FullyConnected` 操作使用逐行量化。

### SingleStageConfig

转换单个阶段的描述。

包含转换一个模型所需的一切：模型本身、其输入和输出，以及每个受支持平台的选项。大多数字段在未明确给出时从输入模型的元数据中填充。

#### 方法

##### get_platform_config

```python
def get_platform_config(platform: Platform) -> PlatformConfig:
```

返回给定平台的平台配置。

##### validate_disable_onnx_optimizations

```python
def validate_disable_onnx_optimizations(data: Params) -> Params:
```

翻译已弃用的 `disable_onnx_optimizations`。

> **已弃用**
> 自 0.5.6 版起已弃用：请改用 `onnx_optimizations: false`。

参数

 * `data` (`Params`): 原始阶段配置。

返回

 * `Params`: 如果启用了已弃用选项，则所有 ONNX 优化都已禁用的配置。

引发

 * `ValueError`: 如果启用了 `disable_onnx_optimizations` 并且也指定了 `onnx_optimizations`。

##### validate_onnx_optimizations

```python
def validate_onnx_optimizations(data: Params) -> Params:
```

展开 `onnx_optimizations` 的简写值。

参数

 * `data` (`Params`): 原始阶段配置。

返回

 * `Params`: 如果使用了简写值，则 `onnx_optimizations` 被替换为
   [ONNXOptimizationsConfig](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md)
   的配置，所有优化都已启用或禁用。

##### validate_onnx_simplification

```python
def validate_onnx_simplification(data: Params) -> Params:
```

翻译已弃用的 `disable_onnx_simplification`。

> **已弃用**
> 自 0.5.6 版起已弃用：请改用 `onnx_simplification: false`。

参数

 * `data` (`Params`): 原始阶段配置。

返回

 * `Params`: 如果启用了已弃用选项，则 `onnx_simplification` 设置为 `False` 的配置。

引发

 * `ValueError`: 如果启用了 `disable_onnx_simplification` 并且也指定了 `onnx_simplification`。

#### 属性

##### hailo

Hailo 转换的选项。

##### input_bin

OpenVINO IR 模型的 `.bin` 文件路径。对于 IR 模型，从 `input_model` 派生。

##### input_file_type

输入模型的类型，从 `input_model` 的后缀派生。

##### input_model

要转换的模型的路径。在验证期间下载到本地模型目录。

##### inputs

模型输入的描述。

##### intermediate_outputs_remote_url

上传中间输出的远程 URL。

##### keep_intermediate_outputs

是否保留转换期间创建的文件。

##### onnx_optimizations

ONNX 图优化的开关。

##### onnx_simplification

要使用的 ONNX 简化方法，或 `False` 以禁用简化。

##### output_remote_url

上传转换后的模型的远程 URL。

##### outputs

模型输出的描述。

##### put_file_plugin

用于上传的注册插件名称。

##### rvc2

RVC2 转换的选项。

##### rvc3

RVC3 转换的选项。

##### rvc4

RVC4 转换的选项。

## 函数

### broadcast_preprocessing_values

```python
def broadcast_preprocessing_values(values: list[float], channels: int | None) -> list[float]:
```

将标量预处理值扩展到已解析的通道计数。

### generate_renamed_onnx

```python
def generate_renamed_onnx(onnx_path: PathType, rename_dict: dict[str, str], output_path: PathType):
```

保存一个 ONNX 模型的副本，其中包含重命名的节点连接。

名称出现在 `rename_dict` 中的每个节点输入和输出都替换为新名称。如果原始模型使用了外部数据，则模型将保存为外部数据。

参数

 * `onnx_path` (`PathType`): 要重命名的 ONNX 模型的路径。
 * `rename_dict` (`dict[str, str]`): 从旧张量名称到新张量名称的映射。
 * `output_path` (`PathType`): 保存重命名模型的路径。

## 属性

### NAMED_VALUES

### TRUSTWORTHY_INFERRED_CHANNEL_LAYOUTS
