# CLI

Python API: `modelconverter.__main__`

`modelconverter` 命令行界面的入口点。

定义了 CLI 公开的命令：为平台转换模型、运行推理、在设备上进行基准测试和分析、可视化分析结果、将模型打包到 NN Archive 中、在平台的容器中打开 shell 以及管理缓存。需要供应商转换工具的命令（`convert`、`infer` 和
`shell`）将在请求平台的 Docker 镜像中重新运行，除非它们已在其中运行；其他命令则在主机上运行。

## 函数

### analyze

```python
def analyze(*, device_ip: str | None = None, device_id: str | None = None, dlc_model_path: str, onnx_model_path: str, image_subset: int | None = None, image_dirs: Annotated[list[str], Parameter(negative_iterable=[], consume_multiple=True)], analyze_outputs: bool = True, analyze_cycles: bool = True):
```

对指定的 DLC 模型运行层和周期分析。

需要 RVC4 设备已连接并可通过 `adb` 命令访问。

参数

 * `device_ip` (`str | None`): 运行分析的设备的 IP 地址。可与 `device_id` 互换。如果两者都未提供，ADB 将选择第一个连接的设备。如果两者都提供，`device_id` 优先。
 * `device_id` (`str | None`): 运行分析的设备的唯一 ID。可与 `device_ip` 互换。如果两者都未提供，ADB 将选择第一个连接的设备。如果两者都提供，`device_id` 优先。
 * `dlc_model_path` (`str`): DLC 模型文件的路径。
 * `onnx_model_path` (`str`): 用于转换为 DLC 的相应 ONNX 模型文件的路径。
 * `image_subset` (`int | None`): 如果提供，则将分析限制为每个输入目录中前 N 个受支持的输入文件。
 * `image_dirs` (`Annotated[list[str], Parameter(negative_iterable=[], consume_multiple=True)]`): 包含模型每个输入的图像的目录名称和路径列表。
 * `analyze_outputs` (`bool`): 是否分析层输出。
 * `analyze_cycles` (`bool`): 是否分析层周期。

### archive

```python
def archive(path: str, *, save_path: str | None = None, put_file_plugin: str | None = None):
```

将模型文件转换为 Luxonis NN Archive。

参数

 * `path` (`str`): 模型文件的 URL 或路径。
 * `save_path` (`str | None`): 保存存档的路径或 URL。默认情况下，它会保存到当前目录，名称与模型名称相同。
 * `put_file_plugin` (`str | None`): 用于上传文件的插件名称。

### benchmark

```python
def benchmark(platform: Platform, /, *, model_path: str, full: bool = False, save: bool = False, repetitions: Annotated[int, Parameter(group=['RVC2', 'RVC4'])] = 10, benchmark_time: Annotated[int, Parameter(group=['RVC2', 'RVC4'])] = 20, input_fps: Annotated[float, Parameter(group=['RVC2', 'RVC4'])] = -1.0, num_threads: Annotated[int, Parameter(group=['RVC2', 'RVC4'])] = 2, num_messages: Annotated[int, Parameter(group=['RVC2', 'RVC4'])] = 50, requests: Annotated[int, Parameter(group='RVC3')] = 1, profile: Annotated[Literal['low_balanced', 'balanced', 'high_performance', 'sustained_high_performance', 'burst', 'low_power_saver', 'power_saver', 'high_power_saver', 'extreme_power_saver', 'system_settings'], Parameter(group='RVC4')] = 'balanced', runtime: Annotated[Literal['dsp', 'cpu'], Parameter(group='RVC4')] = 'dsp', num_images: Annotated[int, Parameter(group='RVC4')] = 500, device_ip: Annotated[str | None, Parameter(group='RVC4')] = None, device_id: Annotated[str | None, Parameter(group='RVC4')] = None, dai_benchmark: Annotated[bool, Parameter(group='RVC4')] = True, device_monitor: Annotated[bool, Parameter(group='RVC4')] = True):
```

在指定平台上运行基准测试。

参数

 * `platform` (`Platform`): 运行基准测试的平台。
 * `model_path` (`str`): 模型文件的 URL 或路径。
 * `full` (`bool`): 如果为 `True`，则使用所有配置运行完整基准测试。
 * `save` (`bool`): 如果为 `True`，则将基准测试结果保存到文件。
 * `repetitions` (`Annotated[int, Parameter(group=['RVC2', 'RVC4'])]`): 执行的重复次数。仅与 DAI 基准测试相关。
 * `benchmark_time` (`Annotated[int, Parameter(group=['RVC2', 'RVC4'])]`): 基于时间的基准测试持续时间（秒）（覆盖重复次数）。
 * `input_fps` (`Annotated[float, Parameter(group=['RVC2', 'RVC4'])]`): DAI 基准测试发送输入的速率。使用 `-1` 表示无限制。
 * `num_threads` (`Annotated[int, Parameter(group=['RVC2', 'RVC4'])]`): 用于推理的线程数。仅与 DAI 基准测试相关。
 * `num_messages` (`Annotated[int, Parameter(group=['RVC2', 'RVC4'])]`): 每个报告要测量的消息数。仅与 DAI 基准测试相关。
 * `requests` (`Annotated[int, Parameter(group='RVC3')]`): 执行的请求数。
 * `profile` (`Annotated[Literal['low_balanced', 'balanced', 'high_performance', 'sustained_high_performance', 'burst',
   'low_power_saver', 'power_saver', 'high_power_saver', 'extreme_power_saver', 'system_settings'], Parameter(group='RVC4')]`):
   用于推理的 SNPE 配置文件。
 * `runtime` (`Annotated[Literal['dsp', 'cpu'], Parameter(group='RVC4')]`): 用于推理的 SNPE 运行时（dsp 或 cpu）。
 * `num_images` (`Annotated[int, Parameter(group='RVC4')]`): 用于推理的图像数量。仅与 SNPE 后端相关。
 * `device_ip` (`Annotated[str | None, Parameter(group='RVC4')]`): 运行基准测试的设备的 IP 地址。可与 `device_id` 互换。如果两者都未提供，DAI
   将选择默认设备。如果两者都提供，`device_id` 优先。
 * `device_id` (`Annotated[str | None, Parameter(group='RVC4')]`): 运行基准测试的设备的唯一 ID。可与 `device_ip` 互换。如果两者都未提供，DAI
   将选择默认设备。如果两者都提供，`device_id` 优先。
 * `dai_benchmark` (`Annotated[bool, Parameter(group='RVC4')]`): 是否使用 DAI V3 运行基准测试。如果为 `False`，则使用 SNPE 工具。
 * `device_monitor` (`Annotated[bool, Parameter(group='RVC4')]`): 是否在基准测试期间监控设备性能并将其包含在结果中。仅与 RVC4 相关。

### cache_clean

```python
def cache_clean(*, yes: Annotated[bool, Parameter(name='-y', negative_bool=[])] = False):
```

删除整个 modelconverter 缓存。

参数

 * `yes` (`Annotated[bool, Parameter(name='-y', negative_bool=[])]`): 无需确认即可清除缓存。

### cache_info

```python
def cache_info():
```

报告 modelconverter 缓存的位置和磁盘使用情况。

### catch_exceptions

```python
def catch_exceptions():
```

记录块中引发的任何异常并退出。

如果发生 `ModelconverterException`，则以状态 1 退出；如果发生任何其他异常，则以状态 2 退出。

### convert

```python
def convert(platform: Platform, /, *opts: str, path: str | None = None, output_dir: str | None = None, to: Literal['native', 'nn_archive'] = 'nn_archive', main_stage: str | None = None, archive_preprocess: bool = False):
```

导出指定平台的模型。

参数

 * `platform` (`Platform`): 导出模型的平台。
 * `*opts` (`str`): 配置文件可选 CLI 覆盖的列表。
 * `path` (`str | None`): 配置文件、NN Archive 或独立模型文件的 URL 或路径。
 * `output_dir` (`str | None`): 导出模型将保存到的目录名称。
 * `to` (`Literal['native', 'nn_archive']`): 是将模型导出为简单的模型文件还是 Luxonis NN Archive。
 * `main_stage` (`str | None`): 包含主模型的阶段名称。仅在多阶段配置和转换为 NN Archive 时需要。从 NN Archive 转换时，阶段名称与不带后缀的模型文件同名。
 * `archive_preprocess` (`bool`): 强制将预处理嵌入到 NN Archive 元数据中，而不是嵌入到模型中。仅在 `to="nn_archive"` 时有效。如果没有此选项，预处理将首先在可能的情况下嵌入，否则对于 NN
   Archive 输出将回退到存档元数据。

### infer

```python
def infer(platform: Platform, /, *opts: str, model_path: str, input_path: Path, output_dir: str, config: str | None = None, path: str | None = None, stage: str | None = None):
```

在指定平台上运行推理。

参数

 * `platform` (`Platform`): 运行推理的平台。
 * `*opts` (`str`): 配置文件可选 CLI 覆盖的列表。
 * `model_path` (`str`): 模型文件的 URL 或路径。
 * `input_path` (`Path`): 包含推理数据的目录路径。该目录必须包含每个输入的一个子目录，名称与输入相同。文件可以是图像、`.npy` 数组或 `.raw` 缓冲区。
 * `output_dir` (`str`): 推理结果将保存到的目录名称。
 * `config` (`str | None`): 配置文件的 URL 或路径。
 * `path` (`str | None`): `config` 的别名。已弃用。
 * `stage` (`str | None`): 要运行的阶段名称。仅在多阶段配置时需要。如果未提供，将使用第一个阶段。

### launcher

```python
def launcher(*tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True, json_dict=False, json_list=False)], dev: Annotated[bool, Parameter(group=docker_parameters)] = False, gpu: Annotated[bool, Parameter(group=docker_parameters)] = True, tool_version: Annotated[str | None, Parameter(group=docker_parameters)] = None, image: Annotated[str | None, Parameter(['image', 'docker-image'], group=docker_parameters)] = None, memory: Annotated[str | None, Parameter(group=docker_parameters)] = None, cpus: Annotated[float | None, Parameter(group=docker_parameters)] = None):
```

为 Luxonis 设备转换神经网络模型。

`convert`、`infer` 和 `shell` 命令在 docker 容器中运行，除非它们已在其中运行。其他命令在主机上运行。

参数

 * `*tokens` (`Annotated[str, Parameter(show=False, allow_leading_hyphen=True, json_dict=False, json_list=False)]`):
   命令及其参数，由包装的应用程序解析。
 * `dev` (`Annotated[bool, Parameter(group=docker_parameters)]`): 如果为 `True`，则构建并运行平台的 `dev` 镜像，该镜像还将主机的源、测试和 `pyproject.toml`
   挂载到其中。
 * `gpu` (`Annotated[bool, Parameter(group=docker_parameters)]`): 如果为 `True`，则使用 `nvidia` 运行时运行容器。仅对 `hailo` 平台有效。
 * `tool_version` (`Annotated[str | None, Parameter(group=docker_parameters)]`): 要使用的底层转换工具的版本。可用选项因平台而异。
 * `image` (`Annotated[str | None, Parameter(['image', 'docker-image'], group=docker_parameters)]`): 要使用的 docker
   镜像的完整名称。如果名称包含标签（例如 `:latest`），则将按原样使用，并忽略 `--tool-version` 参数。
 * `memory` (`Annotated[str | None, Parameter(group=docker_parameters)]`): 分配给 docker 容器的内存量，以带可选二进制单位的数字表示：`4g` 表示 4
   gibibytes，`512m`，`2GiB`，或裸字节数。默认情况下，使用所有可用的系统内存。
 * `cpus` (`Annotated[float | None, Parameter(group=docker_parameters)]`): 分配给 docker 容器的 CPU 核心数。可以是小数，例如 `0.5`
   表示半个核心。默认情况下，使用所有可用的 CPU 核心。

### shell

```python
def shell(platform: Platform, /, *, command: Annotated[str | None, Parameter(name=['-c', '--command'])] = None):
```

在指定平台的 docker 容器中启动 shell。

参数

 * `platform` (`Platform`): 平台。
 * `command` (`Annotated[str | None, Parameter(name=['-c', '--command'])]`): 要在 shell 中运行的命令。如果未提供，则启动 bash
   shell。如果要运行带参数的命令，请在命令周围使用引号。

### visualize

```python
def visualize(dir_path: str):
```

可视化分析结果。

参数

 * `dir_path` (`str`): 包含分析 CSV 文件的目录路径。分析器将它们写入 `output/analysis/<model_name>`。

## 属性

### app

### cache_app

### device_commands

### docker_commands

### docker_parameters
