# CLI

Python API: `luxonis_train.__main__`

`luxonis_train` 命令行界面。

训练、评估、导出和标注命令从配置构建
[LuxonisModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
并调用其方法之一。`inspect` 只读取模型的加载器。`--model` 和 `--variant` 选择一个打包的配置，因此 `--config` 是可选的。`list-models` 和 `info` 描述打包的模型。`upgrade`
组迁移配置、检查点或安装。

全局 `--source` 选项在命令之前运行一个或多个带有自定义组件的 Python 文件，以便组件注册。

## 函数

### annotate

```python
def annotate(opts: OptsType = None, /, *, dir_path: Path, dataset_name: str, config: str | None = None, model: str | None = None, variant: str | None = None, weights: str | None = None, bucket_storage: Literal['local', 'gcs'] = 'local', delete_local: bool = True, delete_remote: bool = True, team_id: str | None = None):
```

将图像目录标注为新数据集。

模型对 `dir_path` 中带有图像扩展名（如 `.jpg` 或 `.png`）的每个文件进行预测。每个头将其预测转换为标注。该命令将它们写入名为 `dataset_name` 的
`LuxonisDataset`，在它不为空时创建其拆分，并打印其摘要。图像通过一个名为 `infer_from_directory`
的临时数据集。该命令首先删除该名称的现有本地数据集，并在结束时删除临时数据集。[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
替换了无法初始化的加载器，因此该命令在没有数据集的情况下运行。

参数

 * `opts` (`OptsType`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `dir_path` (`Path`): 包含要标注图像的目录。它必须是一个目录。
 * `dataset_name` (`str`): 要创建的数据集的名称。
 * `config` (`str | None`): 配置文件路径或 URL。与 `model` 互斥。如果省略，则应用 `model` 的打包配置，否则应用 `weights` 检查点中存储的配置。
 * `model` (`str | None`): 打包的预定义模型的名称，例如 `"detection"` 或 `"detection:v1"`。运行 `luxonis_train list-models` 查看选项。
 * `variant` (`str | None`): 预定义模型的变体，例如 `"light"` 或 `"heavy"`。默认为模型的默认变体。
 * `weights` (`str | None`): 用于标注的检查点路径或 URL。如果省略，则应用配置的 `model.weights`。
 * `bucket_storage` (`Literal['local', 'gcs']`): 命令存储新数据集的位置。
 * `delete_local` (`bool`): 首先删除同名现有本地数据集。如果为 `False`，则命令将标注添加到现有数据集。
 * `delete_remote` (`bool`): 同时删除同名现有数据集的远程副本。
 * `team_id` (`str | None`): 拥有数据集的团队。`None` 从环境中读取 `LUXONISML_TEAM_ID`。

### archive

```python
def archive(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, executable: str | None = None, weights: str | None = None):
```

将导出的模型打包成 NN Archive。

存档包含可执行文件，如果存在，则包含其 `.data` 文件，以及一个包含输入、输出、预处理和头的配置。它会进入运行保存目录的 `archive` 目录。当 `archiver.upload_url` 设置时，命令会将存档上传到该 URL；当
`archiver.upload_to_run`
设置时，则上传到运行。[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
替换了无法初始化的加载器，因此该命令在没有数据集的情况下运行。

参数

 * `opts` (`OptsType`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `config` (`str | None`): 配置文件路径或 URL。与 `model` 互斥。如果省略，则应用 `model` 的打包配置，否则应用 `weights` 检查点中存储的配置。
 * `model` (`str | None`): 打包的预定义模型的名称，例如 `"detection"` 或 `"detection:v1"`。运行 `luxonis_train list-models` 查看选项。
 * `variant` (`str | None`): 预定义模型的变体，例如 `"light"` 或 `"heavy"`。默认为模型的默认变体。
 * `executable` (`str | None`): 导出的 ONNX 模型路径。其他格式会因 `NotImplementedError` 停止命令。如果省略，命令会首先将模型导出为 ONNX。
 * `weights` (`str | None`): 要存档的检查点路径或 URL。如果省略，则应用配置的 `model.weights`。

### checkpoint

```python
def checkpoint(opts: OptsType = None, /, *, path: Annotated[Path, Parameter(validator=validators.Path(exists=True))], output: Path | None = None, config: Path | None = None):
```

将检查点文件升级到当前格式。

该命令从 `config` 或从检查点中存储的配置构建模型，并将检查点加载到其中。然后它运行一次验证循环以将模型附加到训练器。它使用当前配置、执行顺序和数据集元数据再次保存检查点。没有存储配置的检查点需要
`config`。如果没有数据集，[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
将代替验证循环。该命令也命名为 `ckpt`。

参数

 * `opts` (`OptsType`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `path` (`Annotated[Path, Parameter(validator=validators.Path(exists=True))]`): 检查点路径。它必须存在。
 * `output` (`Path | None`): 写入升级后的检查点的位置。如果省略，命令将覆盖 `path`。
 * `config` (`Path | None`): 用于构建模型的配置文件。如果省略，则应用检查点中存储的配置。

### config

```python
def config(config: Annotated[Path, Parameter(validator=validators.Path(exists=True)), Parameter(validator=validators.Path(ext=set(['yaml', 'yml', 'json'])))], output: Annotated[Path | None, Parameter(validator=validators.Path(ext=set(['yaml', 'yml', 'json'])))] = None):
```

将配置文件升级到当前模式。

当文件后缀为 `.json` 时，命令将其读取为 JSON，否则读取为 YAML。它应用
[upgrade_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/upgrade.md)
的迁移步骤，并以输出后缀的格式写入结果。当文件已是最新时，命令会将其写回而不进行迁移。在这两种情况下，它都会删除已弃用的 `config_version` 字段。

参数

 * `config` (`Annotated[Path, Parameter(validator=validators.Path(exists=True)),
   Parameter(validator=validators.Path(ext=set(['yaml', 'yml', 'json'])))]`): 要升级的配置文件路径。它必须存在并以 `.yaml`、`.yml` 或 `.json` 结尾。
 * `output` (`Annotated[Path | None, Parameter(validator=validators.Path(ext=set(['yaml', 'yml', 'json'])))]`): 写入升级后的配置的位置。它必须以
   `.yaml`、`.yml` 或 `.json` 结尾。如果省略，命令将覆盖 `config`。

### convert

```python
def convert(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, save_dir: str | None = None, weights: str | None = None):
```

导出、存档并转换模型以用于目标平台。

该命令将模型导出为 ONNX，将其打包成 NN Archive，然后运行配置激活的转换：

 * `exporter.blobconverter.active`：通过 `blobconverter` 为 RVC2 生成 `.blob`，此功能已弃用。
 * `exporter.hubai.active`：通过 HubAI SDK 为 `exporter.hubai.platform`（`rvc2`、`rvc3` 或 `rvc4`）生成 NN Archive。

如果未安装某个转换所需的包，命令会跳过该转换并记录下来。[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
替换了无法初始化的加载器，因此该命令在没有数据集的情况下运行。

参数

 * `opts` (`OptsType`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `config` (`str | None`): 配置文件路径或 URL。与 `model` 互斥。如果省略，则应用 `model` 的打包配置，否则应用 `weights` 检查点中存储的配置。
 * `model` (`str | None`): 打包的预定义模型的名称，例如 `"detection"` 或 `"detection:v1"`。运行 `luxonis_train list-models` 查看选项。
 * `variant` (`str | None`): 预定义模型的变体，例如 `"light"` 或 `"heavy"`。默认为模型的默认变体。
 * `save_dir` (`str | None`): 所有输出的目录。如果省略，输出将进入运行保存目录。
 * `weights` (`str | None`): 要转换的检查点路径或 URL。如果省略，则应用配置的 `model.weights`。

### create_model

```python
def create_model(config: PathType | Params | None = None, opts: list[str] | None = None, weights: PathType | None = None, allow_empty_dataset: bool = False, *, model: str | None = None, variant: str | None = None) -> LuxonisModel:
```

构建 CLI 命令操作的模型。

CLI 在不带子模块的情况下导入 `luxonis_train`，以便快速启动。此函数重新加载包，运行完整的导入，然后构建
[LuxonisModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)。

参数

 * `config` (`PathType | Params | None`): 配置文件路径或 URL，或作为字典的配置。如果为 `None`，则应用 `model` 的打包配置，否则应用 `weights` 检查点中存储的配置。如果没有这些，`opts`
   单独从默认值构建配置，并且当 `opts` 也为 `None`
   时，[Config.get_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md)
   会引发 `ValueError`。
 * `opts` (`list[str] | None`): 配置覆盖，作为交替的键和值标记，例如 `["trainer.epochs", "10"]`。
 * `weights` (`PathType | None`): 检查点路径或 URL。其数据集元数据适用，并且一旦模型构建完成，其权重就会加载。
 * `allow_empty_dataset` (`bool`): 当为 `True`
   时，[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
   替换了无法初始化的加载器，因此模型在没有数据集的情况下构建。
 * `model` (`str | None`): 打包的预定义模型的名称，带有可选的版本后缀，例如 `"detection:v1"`。与 `config` 互斥。
 * `variant` (`str | None`): 打包模型的变体。需要 `model`。

返回

 * `LuxonisModel`: 模型，及其加载器和训练器已构建。

### export

```python
def export(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, save_path: str | None = None, weights: str | None = None, ckpt_only: bool = False):
```

将模型导出为 ONNX。

该命令写入 `<name>.onnx`。对于具有一个输入的模型，它还在旁边写入一个用于 `modelconverter` 的 `<name>.yaml` 配置。`<name>` 是 `exporter.name` 或 `model.name`。使用
`--ckpt-only`，命令只写入 `<name>.ckpt`。它使用当前配置、执行顺序和数据集元数据再次保存检查点，这会刷新旧的检查点。如果没有 `--ckpt-only`，当 `exporter.upload_to_run`
设置时，命令会将文件上传到运行；当 `exporter.upload_url` 设置时，则上传到该
URL。[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
替换了无法初始化的加载器，因此该命令在没有数据集的情况下运行。

参数

 * `opts` (`OptsType`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `config` (`str | None`): 配置文件路径或 URL。与 `model` 互斥。如果省略，则应用 `model` 的打包配置，否则应用 `weights` 检查点中存储的配置。
 * `model` (`str | None`): 打包的预定义模型的名称，例如 `"detection"` 或 `"detection:v1"`。运行 `luxonis_train list-models` 查看选项。
 * `variant` (`str | None`): 预定义模型的变体，例如 `"light"` 或 `"heavy"`。默认为模型的默认变体。
 * `save_path` (`str | None`): 导出文件的目录，或其词干命名文件的文件路径。如果省略，文件将进入运行保存目录的 `export` 目录。
 * `weights` (`str | None`): 要导出的检查点路径或 URL。如果省略，则应用配置的 `model.weights`。
 * `ckpt_only` (`bool`): 当为 `True` 时，只写入 `.ckpt` 文件。

### infer

```python
def infer(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, view: Literal['train', 'val', 'test'] = 'val', save_dir: Path | None = None, source_path: str | None = None, weights: str | None = None):
```

运行推理并显示或保存可视化结果。

如果没有 `source_path`，模型将在数据集视图上运行。如果有，模型将在一个图像、一个目录中的每个图像或一个视频的每一帧上运行。如果没有 `save_dir`，每个可视化器会打开一个名为 `<node>/<visualizer>` 的窗口，按 `q`
或 `Esc` 停止运行。图像或目录通过一个名为 `infer_from_directory`
的临时数据集。该命令首先删除该名称的现有本地数据集，并在结束时删除临时数据集。[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
替换了无法初始化的加载器，因此图像或目录源在没有数据集的情况下运行。视频源需要一个真实的验证加载器，因为每一帧都通过其 `augment_test_image`
方法。[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
不实现该方法。

参数

 * `opts` (`OptsType`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `config` (`str | None`): 配置文件路径或 URL。与 `model` 互斥。如果省略，则应用 `model` 的打包配置，否则应用 `weights` 检查点中存储的配置。
 * `model` (`str | None`): 打包的预定义模型的名称，例如 `"detection"` 或 `"detection:v1"`。运行 `luxonis_train list-models` 查看选项。
 * `variant` (`str | None`): 预定义模型的变体，例如 `"light"` 或 `"heavy"`。默认为模型的默认变体。
 * `view` (`Literal['train', 'val', 'test']`): 当 `source_path` 省略时使用的数据集视图。
 * `save_dir` (`Path | None`): 可视化结果的目录，可以是 `.png` 图像或 `.mp4` 视频。如果缺少，命令会创建它。
 * `source_path` (`str | None`): 图像文件、图像目录或视频文件的路径。目录贡献其中带有图像扩展名（如 `.jpg` 或 `.png`）的文件。扩展名标识视频：`.mp4`、`.mov`、`.avi`、`.mkv` 或
   `.webm`。
 * `weights` (`str | None`): 要运行的检查点路径或 URL。如果省略，则应用配置的 `model.weights`。

### info

```python
def info(*, model: str, variant: str | None = None):
```

打印打包的预定义模型的文档。

第一个面板命名模型、变体和已解析模型类的注册表键。它显示类的文档字符串，如果类没有文档字符串，则显示一个备用句子。每个组件后面都有一个面板。一个简单的模型会得到主干、颈部（如果存在）和头部。任何其他模型都会得到每个节点。每个面板都命名节点类及其变体。它显示类的文档字符串，如果类没有文档字符串，则显示其
`__init__` 的文档字符串，或者在两者都缺失时显示通知。未知模型、变体或版本会因 `ValueError` 停止命令。

参数

 * `model` (`str`): 打包模型的名称，带有可选的版本后缀，例如 `"detection:v1"` 或 `"detection:latest"`。
 * `variant` (`str | None`): 要描述的变体。默认为模型的默认变体。

### inspect

```python
def inspect(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, view: Literal['train', 'val', 'test'] = 'train', size_multiplier: Annotated[float, Parameter(['--size_multiplier', '-s'])] = 1.0, list_augmentations: bool = False):
```

显示数据集视图的样本及其绘制的标签。

一个名为 `Visualization` 的窗口一次显示一个样本。任意键移动到下一个样本，`q` 或 `Esc` 关闭窗口。加载器不规范化图像。

参数

 * `opts` (`OptsType`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `config` (`str | None`): 配置文件路径或 URL。与 `model` 互斥。如果省略，则应用 `model` 的打包配置，否则应用默认值。
 * `model` (`str | None`): 打包的预定义模型的名称，例如 `"detection"` 或 `"detection:v1"`。运行 `luxonis_train list-models` 查看选项。
 * `variant` (`str | None`): 预定义模型的变体，例如 `"light"` 或 `"heavy"`。默认为模型的默认变体。
 * `view` (`Literal['train', 'val', 'test']`): 要检查的数据集视图。
 * `size_multiplier` (`Annotated[float, Parameter(['--size_multiplier', '-s'])]`): 加载器返回的图像的缩放因子。`1.0` 保持其大小。标志是
   `--size_multiplier` 和 `-s`。
 * `list_augmentations` (`bool`): 当为 `True` 时，页脚会列出应用于样本的增强。当样本没有跟踪的增强时，页脚显示 `Augmentations: none`。不包装 `luxonis_ml`
   加载器的加载器永远不会有增强。

### launcher

```python
def launcher(*tokens: LauncherToken, source: LauncherSource = None):
```

运行自定义组件文件，然后运行命令。

这是 CLI 的入口点。启动器在命令运行之前将 `source` 中的每个文件作为模块执行。然后，这些文件中的自定义节点、损失和其他组件会注册。启动器会跳过无法解析为模块的文件。使用命令行上的 `--source`，`luxonis_train`
会在启动时导入每个子模块，因此文件可以从中导入。

参数

 * `*tokens` (`LauncherToken`): 命令及其参数，不变地传递。
 * `source` (`LauncherSource`): 包含自定义组件的 Python 文件。每个文件使用一次 `--source`。

### list_models

```python
def list_models():
```

列出打包的预定义模型。

该命令打印一个表格，每行一个模型，如果不存在打包模型则打印通知。`Variants` 列用 `*` 标记默认变体，对于没有变体名称的配置显示 `<default>`。`Versions` 列用 `*` 标记最新版本，当配置未命名注册模型类时显示
`-`。当省略选项时，标记的值适用。

### quantize

```python
def quantize(opts: list[str] | None = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, weights: str | None = None):
```

使用 AIMET 量化模型。

配置的 `exporter.aimet` 部分设置所有选项。该命令在验证视图上评估浮点模型。它运行后训练量化，在验证图像上校准，并评估结果。然后它在训练视图上运行量化感知训练并再次评估。它将量化后的 ONNX 及其 NN Archive 写入运行保存目录的
`aimet` 目录。该命令需要数据集和 `aimet` 额外项。

参数

 * `opts` (`list[str] | None`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `config` (`str | None`): 配置文件路径或 URL。与 `model` 互斥。如果省略，则应用 `model` 的打包配置，否则应用 `weights` 检查点中存储的配置。
 * `model` (`str | None`): 打包的预定义模型的名称，例如 `"detection"` 或 `"detection:v1"`。运行 `luxonis_train list-models` 查看选项。
 * `variant` (`str | None`): 预定义模型的变体，例如 `"light"` 或 `"heavy"`。默认为模型的默认变体。
 * `weights` (`str | None`): 要量化的检查点路径或 URL。如果省略，则应用配置的 `model.weights`。

### test

```python
def test(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, view: Literal['train', 'val', 'test'] = 'test', weights: str | None = None, debug: bool = False):
```

在数据集视图上评估模型。

该命令在 `view` 上运行训练器的测试循环并完成跟踪运行。

参数

 * `opts` (`OptsType`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `config` (`str | None`): 配置文件路径或 URL。与 `model` 互斥。如果省略，则应用 `model` 的打包配置，否则应用 `weights` 检查点中存储的配置。
 * `model` (`str | None`): 打包的预定义模型的名称，例如 `"detection"` 或 `"detection:v1"`。运行 `luxonis_train list-models` 查看选项。
 * `variant` (`str | None`): 预定义模型的变体，例如 `"light"` 或 `"heavy"`。默认为模型的默认变体。
 * `view` (`Literal['train', 'val', 'test']`): 要评估的数据集视图。
 * `weights` (`str | None`): 要评估的检查点路径或 URL。如果省略，则应用配置的 `model.weights`。
 * `debug` (`bool`): 当为 `True`
   时，[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
   替换了无法初始化的加载器，因此模型在没有有效数据集的情况下构建。

### train

```python
def train(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, weights: str | None = None, debug: bool = False):
```

训练模型。

运行将其日志、配置和检查点写入 `tracker.save_directory` 下的运行保存目录。

参数

 * `opts` (`OptsType`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `config` (`str | None`): 配置文件路径或 URL。与 `model` 互斥。如果省略，则应用 `model` 的打包配置，否则应用 `weights` 检查点中存储的配置。
 * `model` (`str | None`): 打包的预定义模型的名称，例如 `"detection"` 或 `"detection:v1"`。运行 `luxonis_train list-models` 查看选项。
 * `variant` (`str | None`): 预定义模型的变体，例如 `"light"` 或 `"heavy"`。默认为模型的默认变体。
 * `weights` (`str | None`): 检查点路径或 URL。如果配置中设置了 `trainer.resume_training`，则运行将从该检查点继续，并使用其优化器、调度器和 epoch 计数。否则只加载权重。
 * `debug` (`bool`): 当为 `True`
   时，[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
   替换了无法初始化的加载器，因此模型在没有有效数据集的情况下构建。

### tune

```python
def tune(opts: OptsType = None, /, *, config: str | None = None, model: str | None = None, variant: str | None = None, weights: str | None = None, debug: bool = False):
```

使用 Optuna 搜索超参数。

配置的 `tuner` 部分定义了研究。每个试验都使用采样值训练模型。试验结果会写入运行保存目录中的 `tuner_study.csv`，最佳参数会写入研究的父跟踪器。

参数

 * `opts` (`OptsType`): 配置覆盖，作为交替的键和值标记，例如 `trainer.epochs 10`。
 * `config` (`str | None`): 配置文件路径或 URL。与 `model` 互斥。如果省略，则应用 `model` 的打包配置，否则应用 `weights` 检查点中存储的配置。
 * `model` (`str | None`): 打包的预定义模型的名称，例如 `"detection"` 或 `"detection:v1"`。运行 `luxonis_train list-models` 查看选项。
 * `variant` (`str | None`): 预定义模型的变体，例如 `"light"` 或 `"heavy"`。默认为模型的默认变体。
 * `weights` (`str | None`): 检查点路径或 URL。当 `config` 和 `model` 都省略时，它提供配置。试验不加载其权重。
 * `debug` (`bool`): 当为 `True`
   时，[DummyLoader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/dummy_loader.md)
   替换了无法初始化的加载器，因此模型在没有有效数据集的情况下构建。

### upgrade

```python
def upgrade():
```

升级 `luxonis-train` 安装。

如果没有子命令，该命令会从 PyPI 读取最新版本。当它与已安装版本不同时，该命令会使用 pip 升级 `pip`、`luxonis_train` 和 `luxonis_ml[data]`。当检查失败时，该命令会记录一条消息并停止。`config` 和
`checkpoint` 子命令会升级用户文件。

## 属性

### annotation_group

### app

### evaluation_group

### export_group

### LauncherSource

### management_group

### OptsType

### training_group

### upgrade_app
