# predefined

Python API: `luxonis_train.config.predefined`

查找包中预定义模型的配置文件。

`luxonis_train` 命令的 `--model` 和 `--variant` 选项，以及
[LuxonisModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
的 `model` 和 `variant` 参数，都通过
[resolve_predefined_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md)
进行处理。[luxonis_train.configs](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/configs.md)
中的打包文件 `<model>_<variant>_model.yaml` 或 `<model>_model.yaml` 定义了模型名称及其变体。

## 类

### ResolvedPredefinedConfig

打包的配置文件及其附带的覆盖。

#### 属性

##### opts

配置覆盖，以交替的键和值表示，例如 `model.predefined_model.variant` 后跟 `medium`。当文件不需要覆盖时，此列表为空。

##### path

打包的 YAML 文件的路径。

## 函数

### class_family

```python
def class_family(model: str) -> str | None:
```

返回模型默认配置文件中的类名。

该函数从
[default_config_path](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md)
的文件中读取 `model.predefined_model.name`。

> **示例**
> ```pycon
>>> class_family("keypoint_bbox")
'KeypointDetectionModel'
>>> print(class_family("unknown"))
None
```

参数

 * `model` (`str`): 模型名称，不带版本后缀。

返回

 * `str | None`: `model.predefined_model.name` 的值。当 `model` 不是打包模型时为 `None`。当函数无法读取文件、文件不是有效的 YAML 或文件没有此类键时也为 `None`。

### configs_dir

```python
def configs_dir() -> Path:
```

返回打包配置文件所在的目录。

> **示例**
> ```pycon
>>> configs_dir().name
'configs'
```

返回

 * `Path`:
   [luxonis_train.configs](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/configs.md)
   包的目录。

### default_config_path

```python
def default_config_path(model: str) -> Path:
```

返回模型默认变体的配置文件。

默认变体是
[list_predefined_models](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md)
为 `model` 提供的第一个变体。

> **示例**
> ```pycon
>>> default_config_path("detection").name
'detection_light_model.yaml'
```

参数

 * `model` (`str`): 模型名称，不带版本后缀。

返回

 * `Path`: 打包的 YAML 文件的路径。

引发

 * `KeyError`: 当 `model` 不是打包模型时。

### list_predefined_models

```python
def list_predefined_models() -> dict[str, list[str | None]]:
```

列出打包的模型和具有文件的变体。

该函数读取 [configs_dir](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md) 中以 `_model.yaml` 结尾的文件名。它跳过 `complex_model.yaml` 和其他示例文件。以 `_<variant>_model.yaml` 结尾的名称（其中 `variant` 在 [VARIANT_ORDER](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md) 中）给出模型和该变体。任何其他名称 `<model>_model.yaml` 给出模型和变体 `None`。该列表不包含仅由模型类声明的变体。[list_variants](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md) 会添加它们。

> **示例**
> ```pycon
>>> models = list_predefined_models()
>>> models["detection"], models["embeddings"]
(['light', 'heavy'], [None])
```

返回

 * `dict[str, list[str | None]]`: 每个模型名称映射到其变体，按
   [VARIANT_ORDER](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md)
   的顺序。第一个变体是默认变体。模型按字母顺序排列。

### list_variants

```python
def list_variants(model: str) -> list[str | None]:
```

列出打包模型接受的每个变体。

该列表包含
[list_predefined_models](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md)
的变体，以及模型类的 `get_variants` 声明的变体。模型类来自
[class_family](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md)，采用其最新注册版本。该函数导入预定义模型以查找它。当函数无法解析该类，或者该类没有变体时，该列表仅包含具有文件的变体。

> **示例**
> ```pycon
>>> list_variants("detection")
['light', 'medium', 'heavy']
>>> list_variants("anomaly_detection")
['light', 'heavy', None]
```

参数

 * `model` (`str`): 模型名称，不带版本后缀。

返回

 * `list[str | None]`: 变体按 [VARIANT_ORDER](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md) 的顺序排列。`None` 表示没有变体名称的文件。当 `model` 不是打包模型时，列表为空。

### parse_model_spec

```python
def parse_model_spec(model: str) -> tuple[str, str | None]:
```

将模型名称与其可选版本后缀分开。

后缀跟在 `:` 后面。它是带有 ASCII 数字的 `v`，或者是 `latest`。

> **示例**
> ```pycon
>>> parse_model_spec("detection:v2")
('detection', '2')
>>> parse_model_spec("detection")
('detection', None)
```

参数

 * `model` (`str`): 模型名称，格式为 `"<name>"`, `"<name>:v<N>"` 或 `"<name>:latest"`。

返回

 * `tuple[str, str | None]`: 名称和版本。版本是 `v` 后面的数字、`"latest"`，或者当 `model` 没有 `:` 时为 `None`。

引发

 * `ValueError`: 当 `:` 后面的文本既不是带有数字的 `v` 也不是 `latest` 时。

### resolve_predefined_config

```python
def resolve_predefined_config(model: str, variant: str | None) -> ResolvedPredefinedConfig:
```

查找模型和变体的配置文件和覆盖。

该函数按以下方式选择文件和覆盖：

 * 除了 `latest` 之外的版本成为覆盖 `model.predefined_model.version`。
 * 没有 `variant` 时，文件是模型的默认配置文件，如
   [default_config_path](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md)
   中所示。
 * 具有自己文件的变体选择该文件。
 * 仅由模型类声明的变体选择默认配置文件。

在后两种情况下，`variant` 也成为覆盖 `model.predefined_model.variant`，因此它替换了文件设置的变体。

> **示例**
> ```pycon
>>> path, opts = resolve_predefined_config("detection:v1", "medium")
>>> path.name
'detection_light_model.yaml'
>>> opts
['model.predefined_model.version', '1',
 'model.predefined_model.variant', 'medium']
```

参数

 * `model` (`str`): 模型名称，带有可选版本后缀，如 [parse_model_spec](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md) 中所示。
 * `variant` (`str | None`): 变体。`None` 选择默认配置文件，不添加变体覆盖。

返回

 * `ResolvedPredefinedConfig`: 文件的路径和覆盖。

引发

 * `ValueError`: 当版本后缀格式错误，当 `model` 不是打包模型，或者当 `variant` 不在 [list_variants](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined.md) 中时。

## 属性

### CONFIGS_PACKAGE

### VARIANT_ORDER
