# utils

Python API: `modelconverter.cli.utils`

`modelconverter` CLI 命令共享的辅助函数。

将用户在命令行中输入的内容转换为平台包期望的内容：运行结果写入的目录、解析后的配置（来自配置文件或 NN Archive），以及交给 NN Archive 而不是烘焙到模型中的预处理。

## 函数

### display_output_path

```python
def display_output_path(path: Path) -> str:
```

在可用时返回输出路径的主机可见表示。

参数

 * `path` (`Path`): 当前转换环境生成的工件路径。

返回

 * `str`: 当映射上下文可用时，Docker 输出的主机可见路径，否则为原始路径表示。

### extract_preprocessing

```python
def extract_preprocessing(cfg: Config) -> tuple[Config, dict[str, PreprocessingBlock]]:
```

将预处理从配置中移出到存档块中。

每个配置输入上的均值、比例值和颜色编码都会被清除——因此它们不会烘焙到转换后的模型中——并作为 `PreprocessingBlock` 对象返回，以便存储在 NN Archive 中。原始输入只有在具有均值或比例值时才会获得一个块。

参数

 * `cfg` (`Config`): 用于从中获取预处理的单阶段配置。其输入会就地修改。

返回

 * `tuple[Config, dict[str, PreprocessingBlock]]`: 修改后的配置和以输入名称为键的预处理块的元组。

引发

 * `ValueError`: 如果配置有多个阶段。

### get_configs

```python
def get_configs(platform: Platform, path: str | None, opts: list[str] | Params | None = None) -> tuple[Config, NNArchiveConfig | None, str | None]:
```

设置配置。

参数

 * `platform` (`Platform`): 配置所构建的平台。
 * `path` (`str | None`): 配置文件或 NN Archive 的路径。如果为 `None`，则仅从覆盖项构建配置。
 * `opts` (`list[str] | Params | None`): 配置文件的可选 CLI 覆盖项。可以是映射，也可以是键和值交替的平面列表。

返回

 * `tuple[Config, NNArchiveConfig | None, str | None]`: 解析后的 modelconverter
   [Config](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/config.md)、如果输入是
   NN Archive 则为 `NNArchiveConfig` 否则为 `None`，以及主阶段的键的元组——对于未识别主阶段的多阶段配置，则为 `None`。

引发

 * `ValueError`: 如果 `opts` 是奇数长度的列表。

### get_output_dir_name

```python
def get_output_dir_name(platform: Platform, name: str, output_dir: str | None) -> Path:
```

确定转换结果写入的目录。

现有目标目录会首先被清除，但仅当它是以前转换生成的目录（包含
[CONVERSION_MARKER](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/constants.md)
文件）或空目录时。

参数

 * `platform` (`Platform`): 模型转换的平台，用于生成的名称。
 * `name` (`str`): 模型的名称，使用前会进行清理。
 * `output_dir` (`str | None`): 用户命名的目录，在
   [OUTPUTS_DIR](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/constants.md)
   下解析。如果为 `None`，则使用名为 `<name>_to_<platform>_<timestamp>` 的目录。

返回

 * `Path`: 输出目录的路径。此处不创建。

引发

 * `ModelconverterException`: 如果在容器化运行中，`output_dir` 为空、绝对路径或包含 `..`；或者如果目标存在但不是目录，或者是未包含先前转换结果的非空目录。

### init_dirs

```python
def init_dirs():
```

创建转换读取和写入的目录。

### resolve_output_dir

```python
def resolve_output_dir(output_dir: str) -> Path:
```

在
[OUTPUTS_DIR](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/constants.md)
下解析用户提供的 `--output-dir`。

只有主机的 `./output` 会挂载到容器中，因此绝对路径（`pathlib` 会让它优先于挂载点）或通过 `..`
向上逃逸的路径会写入到仅容器可见的位置，并在容器移除时丢失。原生运行直接写入主机文件系统，用户命名的任何路径都可访问，因此任何路径都会在那里得到遵守。
