# tune_utils

Python API: `luxonis_train.core.utils.tune_utils`

配置的 `tuner.params` 与 Optuna 试验建议之间的转换。

## 函数

### get_trial_params

```python
def get_trial_params(all_augs: list[str], params: dict[str, Any], trial: optuna.trial.Trial) -> dict[str, Any]:
```

采样一个试验的配置覆盖。

`params` 的每个键都是一个带类型后缀的点式配置键，例如 `trainer.optimizer.params.lr_float`。最后一个 `_` 后缀选择采样方式：

 * `categorical`: 从列表中使用 `trial.suggest_categorical`。
 * `int`: 从 `[low, high]` 或 `[low, high, step]` 中使用 `trial.suggest_int`，作为整数。默认步长为 `1`。
 * `float`: 从 `[low, high]` 或 `[low, high, step]` 中使用 `trial.suggest_float`，作为浮点数。
 * `uniform`: 从 `[low, high]` 中使用 `trial.suggest_float`，作为浮点数。
 * `loguniform`: 从 `[low, high]` 中使用 `trial.suggest_float`，作为浮点数，`log=True`。
 * `subset`: 仅用于其最后一个点式部分为 `augmentations` 的键。该值是一个增强名称列表和一个计数。该函数使用 `random` 模块而不是 `trial` 随机选择这些名称中的多个。它会跳过 `Normalize`
   和未知名称并发出警告。

Optuna 参数的名称是不带后缀的键。

> **示例**
> ```pycon
>>> import optuna
>>> trial = optuna.trial.FixedTrial(
...     {"trainer.batch_size": 8, "trainer.optimizer.name": "SGD"}
... )
>>> params = {
...     "trainer.batch_size_int": [4, 16, 4],
...     "trainer.optimizer.name_categorical": ["Adam", "SGD"],
... }
>>> get_trial_params([], params, trial)
{'trainer.batch_size': 8, 'trainer.optimizer.name': 'SGD'}
```

参数

 * `all_augs` (`list[str]`): `trainer.preprocessing.augmentations` 中增强的名称，按配置顺序排列。`subset` 键使用它们来查找索引。
 * `params` (`dict[str, Any]`): 配置的 `tuner.params` 部分。
 * `trial` (`optuna.trial.Trial`): 采样值的试验。

返回

 * `dict[str, Any]`: 每个键的采样值，不带后缀。`subset` 键为每个保留的增强名称提供一个布尔条目 `<key>.<index>.active`。`True` 标记一个选定的增强。

引发

 * `ValueError`: 当结果没有条目时，例如空 `params`。当 `subset` 键的最后一个点式部分不是 `augmentations` 时，当 `subset` 键的计数大于保留名称的数量时，或者当 `float` 键的步长不是浮点数时。
 * `TypeError`: 当 `int` 键的步长不是整数时。
 * `KeyError`: 当后缀未知时，或者当值不符合其后缀时。

### rename_params_for_logging

```python
def rename_params_for_logging(params: dict, tuner_params: dict | None = None) -> dict:
```

替换键中的增强索引为名称，用于日志。

该函数读取 `tuner_params` 中 `trainer.preprocessing.augmentations_subset` 的名称列表。键 `trainer.preprocessing.augmentations.<index>.<field>` 变为 `trainer.preprocessing.augmentations.<name>.active`，其中 `<name>` 是该列表中 `<index>` 处的条目。当 `<index>` 不是整数或超出列表范围时，键保留其名称。其他键也保留其名称。

> **示例**
> ```pycon
>>> params = {
...     "trainer.preprocessing.augmentations.1.active": False,
...     "trainer.batch_size": 8,
... }
>>> tuner_params = {
...     "trainer.preprocessing.augmentations_subset": [
...         ["Defocus", "Sharpen"],
...         1,
...     ]
... }
>>> rename_params_for_logging(params, tuner_params)
{'trainer.preprocessing.augmentations.Sharpen.active': False,
 'trainer.batch_size': 8}
```

参数

 * `params` (`dict`): 试验的采样参数，如
   [get_trial_params](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/tune_utils.md)
   返回的那样。
 * `tuner_params` (`dict | None`): 配置的 `tuner.params` 部分。如果没有增强的 `subset` 条目，该函数不会更改任何键。

返回

 * `dict`: 一个新字典，其值与 `params` 相同。
