# upgrade

Python API: `luxonis_train.upgrade`

升级旧配置和已安装的软件包。

[upgrade_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/upgrade.md)
将旧版本配置迁移到已安装版本的架构。[Config.get_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/config.md)
为其加载的每个配置文件或字典调用它。`luxonis_train upgrade config`
命令将结果写入文件。[upgrade_installation](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/upgrade.md)
使用 `pip` 升级软件包。

## 类

### NestedDict

一个包装器，用于处理带有点键的嵌套字典。

键 `"trainer.optimizer.name"` 代表 `config["trainer"]["optimizer"]["name"]`。读取缺失的键返回 `None`，写入则创建缺失的字典。包装器不复制字典，因此每个更改都会进入包装的字典。

> **示例**
> ```pycon
>>> from luxonis_train.upgrade import NestedDict
>>> config = {"trainer": {"epochs": 10}}
>>> cfg = NestedDict(config)
>>> cfg["trainer.epochs"], cfg["trainer.batch_size"]
(10, None)
>>> cfg["model.name"] = "detector"
>>> config
{'trainer': {'epochs': 10}, 'model': {'name': 'detector'}}
```

#### 方法

##### get

```python
def get(key: str, default: Any = None) -> Any:
```

返回点键下的值，或默认值。

参数

 * `key` (`str`): 点键，例如 `"model.nodes"`。
 * `default` (`Any`): 当 `key` 不存在时返回的值。

返回

 * `Any`: `key` 下的值，或当 `key` 不存在时返回 `default`。存储的 `None` 返回 `None`。

##### log_change

```python
def log_change(old_field: str, new_field: str):
```

以 `INFO` 级别记录配置字段具有新键。

参数

 * `old_field` (`str`): 旧的点键。
 * `new_field` (`str`): 新的点键。

##### pop

```python
def pop(key: str, default: Any = ...) -> Any:
```

删除点键并返回其值。

该方法仅删除 `key` 的最后一部分。父字典保留，即使它们变为空。

> **示例**
> ```pycon
>>> from luxonis_train.upgrade import NestedDict
>>> config = {"exporter": {"output_names": ["boxes"]}}
>>> cfg = NestedDict(config)
>>> cfg.pop("exporter.output_names")
['boxes']
>>> config
{'exporter': {}}
>>> cfg.pop("exporter.output_names", None) is None
True
```

参数

 * `key` (`str`): 点键，例如 `"exporter.output_names"`。
 * `default` (`Any`): 当 `key` 不存在时返回的值。默认 `...` 表示没有默认值。

返回

 * `Any`: 删除的值，或当 `key` 不存在时返回 `default`。

引发

 * `KeyError`: 当 `key` 不存在且 `default` 为 `...` 时。

##### replace

```python
def replace(old_key: str, new_key: str, value: ParamValue | EllipsisType | None = ...):
```

将值移动到新的点键并记录移动。

当 `old_key` 不存在时，该方法不执行任何操作。否则，它会像
[pop](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/upgrade.md)
那样删除 `old_key`，并像 `self[new_key] = value` 那样设置 `new_key`。然后它调用
[log_change](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/upgrade.md)。

参数

 * `old_key` (`str`): 要删除的点键。
 * `new_key` (`str`): 要设置的点键。
 * `value` (`ParamValue | EllipsisType | None`): `new_key` 的值。默认 `...` 保留旧值。任何其他值，包括 `None`，都会替换它。

##### update

```python
def update(key: str, value: Any):
```

设置点键下的值并记录更改。

该方法以 `INFO` 级别记录消息。对于缺失的 `key`，消息表示该字段是新的。否则，它显示旧值和新值。然后该方法像 `self[key] = value` 那样设置值。

参数

 * `key` (`str`): 点键，例如 `"version"`。
 * `value` (`Any`): 新值。

## 函数

### get_latest_version

```python
def get_latest_version() -> Version | None:
```

获取 PyPI 上最新 `luxonis-train` 版本的版本。

该函数从 PyPI JSON API 读取 `info.version`。请求超时为 5 秒。

返回

 * `Version | None`: 最新版本。当请求失败或响应状态不是 `200` 时，它为 `None`。当响应正文不是带有有效 `info.version` 的 JSON 时，它也为 `None`。

### upgrade_config

```python
def upgrade_config(config: PathType | Params) -> Params:
```

将配置迁移到已安装版本的架构。

当文件后缀为 `.json` 时，该函数将其读取为 JSON，否则读取为 YAML。它不会将文件写回。它不复制字典：它就地更改字典并返回它。

没有 `version` 的配置算作 `0.3.0` 版本。该函数总是删除已弃用的 `config_version` 字段。当 `version` 是已安装版本或更新版本时，该函数不进行其他更改。否则，它执行以下步骤：

 * 它重命名这些字段： * `trainer.use_rich_progress_bar` 到 `rich_logging`。
    * `preprocessing.train_rgb` 到 `preprocessing.color_space`。真值给出 `"RGB"`，假值给出 `"BGR"`。
    * `model.predefined_model.params.variant` 到 `model.predefined_model.variant`。
    * `tuner.storage.storage_type` 到 `tuner.storage.backend`。`"local"` 给出 `"sqlite"`，任何其他值给出 `"postgresql"`。
 * 它删除值为 `None` 的 `tuner` 字段。
 * 在 `model.nodes` 的每个节点中，它将 `params.variant` 移动到 `variant`。对于 `FOMOHead`，它将 `params.num_conv_layers` 重命名为
   `params.n_conv_layers`。它删除 `params.download_weights`，当该值为真时，它将 `params.weights` 设置为 `"download"`。
 * 当模型只有一个头时，它将 `exporter.output_names` 移动到头的 `params.export_output_names`。否则，它会记录错误并删除名称。
 * 它将 `model.losses`、`model.metrics` 和 `model.visualizers` 的每个模块移动到模块的 `attached_to` 字段命名的头。模块进入头的 `losses`、`metrics` 或
   `visualizers` 列表，不带 `attached_to`。
 * 它将 `version` 设置为已安装版本。

当节点的 `name` 包含 `"Head"` 时，该节点是一个头。该函数通过其 `alias` 查找头，或者当头没有别名时通过其 `name` 查找头。

当找到 `config_version` 时，该函数以 `INFO` 级别记录消息。当配置已是最新时，它也会记录一条消息，当升级开始时也会记录一条消息。在同一级别，它记录每个重命名的字段、每个移动的 `params.variant`、每个移动的模块和新的
`version`。`tuner` 的删除、`params.download_weights` 的更改以及 `exporter.output_names` 的移动没有 `INFO` 消息。

参数

 * `config` (`PathType | Params`): 本地 YAML 或 JSON 配置文件的路径，或作为字典的配置。

返回

 * `Params`: 迁移后的配置。

引发

 * `ValueError`: 当 `model.losses`、`model.metrics` 或 `model.visualizers` 中的模块没有 `attached_to` 字段，或者当 `attached_to` 未命名头时。

### upgrade_installation

```python
def upgrade_installation():
```

从 PyPI 升级已安装的 `luxonis-train` 软件包。

如果存在较新的版本，则使用当前的 Python 解释器升级 `pip`、`luxonis_train` 和 `luxonis_ml[data]`。版本检查失败将被记录并保持安装不变。
