此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 函数
  • annotate
  • archive
  • checkpoint
  • config
  • convert
  • create_model
  • export
  • infer
  • info
  • inspect
  • launcher
  • list_models
  • quantize
  • test
  • train
  • tune
  • upgrade
  • 属性
  • annotation_group
  • app
  • evaluation_group
  • export_group
  • LauncherSource
  • management_group
  • OptsType
  • training_group
  • upgrade_app
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_train.__main__luxonis_train 命令行界面。训练、评估、导出和标注命令从配置构建 LuxonisModel 并调用其方法之一。inspect 只读取模型的加载器。--model 和 --variant 选择一个打包的配置,因此 --config 是可选的。list-models 和 info 描述打包的模型。upgrade 组迁移配置、检查点或安装。全局 --source 选项在命令之前运行一个或多个带有自定义组件的 Python 文件,以便组件注册。

函数

annotate

Python
1def 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 替换了无法初始化的加载器,因此该命令在没有数据集的情况下运行。参数
  • 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
1def 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 替换了无法初始化的加载器,因此该命令在没有数据集的情况下运行。参数
  • 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
1def checkpoint(opts: OptsType = None, /, *, path: Annotated[Path, Parameter(validator=validators.Path(exists=True))], output: Path | None = None, config: Path | None = None):
将检查点文件升级到当前格式。该命令从 config 或从检查点中存储的配置构建模型,并将检查点加载到其中。然后它运行一次验证循环以将模型附加到训练器。它使用当前配置、执行顺序和数据集元数据再次保存检查点。没有存储配置的检查点需要 config。如果没有数据集,DummyLoader 将代替验证循环。该命令也命名为 ckpt。参数
  • opts (OptsType): 配置覆盖,作为交替的键和值标记,例如 trainer.epochs 10。
  • path (Annotated[Path, Parameter(validator=validators.Path(exists=True))]): 检查点路径。它必须存在。
  • output (Path | None): 写入升级后的检查点的位置。如果省略,命令将覆盖 path。
  • config (Path | None): 用于构建模型的配置文件。如果省略,则应用检查点中存储的配置。

config

Python
1def 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 的迁移步骤,并以输出后缀的格式写入结果。当文件已是最新时,命令会将其写回而不进行迁移。在这两种情况下,它都会删除已弃用的 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
1def 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 替换了无法初始化的加载器,因此该命令在没有数据集的情况下运行。参数
  • 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
1def 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。参数
  • config (PathType | Params | None): 配置文件路径或 URL,或作为字典的配置。如果为 None,则应用 model 的打包配置,否则应用 weights 检查点中存储的配置。如果没有这些,opts 单独从默认值构建配置,并且当 opts 也为 None 时,Config.get_config 会引发 ValueError。
  • opts (list[str] | None): 配置覆盖,作为交替的键和值标记,例如 ["trainer.epochs", "10"]。
  • weights (PathType | None): 检查点路径或 URL。其数据集元数据适用,并且一旦模型构建完成,其权重就会加载。
  • allow_empty_dataset (bool): 当为 True 时,DummyLoader 替换了无法初始化的加载器,因此模型在没有数据集的情况下构建。
  • model (str | None): 打包的预定义模型的名称,带有可选的版本后缀,例如 "detection:v1"。与 config 互斥。
  • variant (str | None): 打包模型的变体。需要 model。
返回
  • LuxonisModel: 模型,及其加载器和训练器已构建。

export

Python
1def 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 替换了无法初始化的加载器,因此该命令在没有数据集的情况下运行。参数
  • 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
1def 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 替换了无法初始化的加载器,因此图像或目录源在没有数据集的情况下运行。视频源需要一个真实的验证加载器,因为每一帧都通过其 augment_test_image 方法。DummyLoader 不实现该方法。参数
  • 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
1def info(*, model: str, variant: str | None = None):
打印打包的预定义模型的文档。第一个面板命名模型、变体和已解析模型类的注册表键。它显示类的文档字符串,如果类没有文档字符串,则显示一个备用句子。每个组件后面都有一个面板。一个简单的模型会得到主干、颈部(如果存在)和头部。任何其他模型都会得到每个节点。每个面板都命名节点类及其变体。它显示类的文档字符串,如果类没有文档字符串,则显示其 __init__ 的文档字符串,或者在两者都缺失时显示通知。未知模型、变体或版本会因 ValueError 停止命令。参数
  • model (str): 打包模型的名称,带有可选的版本后缀,例如 "detection:v1" 或 "detection:latest"。
  • variant (str | None): 要描述的变体。默认为模型的默认变体。

inspect

Python
1def 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
1def launcher(*tokens: LauncherToken, source: LauncherSource = None):
运行自定义组件文件,然后运行命令。这是 CLI 的入口点。启动器在命令运行之前将 source 中的每个文件作为模块执行。然后,这些文件中的自定义节点、损失和其他组件会注册。启动器会跳过无法解析为模块的文件。使用命令行上的 --source,luxonis_train 会在启动时导入每个子模块,因此文件可以从中导入。参数
  • *tokens (LauncherToken): 命令及其参数,不变地传递。
  • source (LauncherSource): 包含自定义组件的 Python 文件。每个文件使用一次 --source。

list_models

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

quantize

Python
1def 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
1def 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 替换了无法初始化的加载器,因此模型在没有有效数据集的情况下构建。

train

Python
1def 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 替换了无法初始化的加载器,因此模型在没有有效数据集的情况下构建。

tune

Python
1def 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 替换了无法初始化的加载器,因此模型在没有有效数据集的情况下构建。

upgrade

Python
1def 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