# tracker

Python API: `luxonis_ml.tracker`

Luxonis ML 工作流的实验跟踪门面。

luxonis_ml.tracker 包导出了
[LuxonisTracker](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)，这是一个用于
TensorBoard、Weights & Biases 和 MLflow 的统一日志接口。训练和评估代码可以通过一个 API 记录指标、超参数、图像、矩阵和工件，同时在运行时选择启用的后端。

在分布式训练中传递 `rank`。受 rank 限制的日志记录方法，例如
[LuxonisTracker.log_metric](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)，仅在
rank 0 上写入。保存或重放本地缓冲区的辅助函数不检查 rank。

> **示例**
> 启动一个由 TensorBoard 支持的运行并记录一个标量指标。

```python
from luxonis_ml.tracker import LuxonisTracker

tracker = LuxonisTracker(
    project_name="training",
    run_name="baseline",
    is_tensorboard=True,
)
tracker.log_metric("loss", 0.42, step=1)
tracker.close()
```

> **注意**
> `tracker` 额外功能不会安装此包的所有依赖项。该包在导入时导入 `mlflow` 和 `cv2`，因此也请安装 `mlflow` 和 `opencv-python`：

```bash
pip install "luxonis-ml[tracker,mlflow]" opencv-python
```

安装您启用的每个剩余后端的 SDK：

 * TensorBoard 需要 `torch`，因为写入器来自 `torch.utils.tensorboard`；
 * Weights & Biases 需要 `wandb`。

跟踪器仅在您启用这些后端时才导入 `torch` 和 `wandb`，因此缺少 SDK 仅对您打开的后端有影响。

目录

 * [启用后端](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker.md)
 * [日志记录
   API](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker.md)
 * [MLflow
   注意事项](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker.md)

## 启用后端

每个后端都有自己的标志。在一个运行中根据需要打开任意数量的后端：

```python
from luxonis_ml.tracker import LuxonisTracker

tracker = LuxonisTracker(
    project_name="my-project",
    run_name="baseline",
    is_tensorboard=True,
    is_wandb=True,
    wandb_entity="my-entity",
)

tracker.log_hyperparams({"lr": 1e-3, "batch_size": 32})
tracker.log_metrics({"acc": 0.92, "loss": 0.18}, step=1)
tracker.upload_artifact("model.onnx", name="model", typ="model")
tracker.close()
```

两个后端需要一个额外的参数，如果没有它，构造函数会引发 `ValueError`：

后端参数

| 标志 | 还需要 |
| --- | --- |
| `is_tensorboard` | 无。写入器使用 `<save_directory>/tensorboard_logs/<run_name>`。一个 sweep 运行会添加一个 `trial_<n>` 级别。 |
| `is_wandb` | `wandb_entity`，以及 `project_name` 或 `project_id`。 |
| `is_mlflow` | `mlflow_tracking_uri`，以及 `project_name` 或 `project_id`。 |

## 日志记录 API

[LuxonisTracker](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
将这些调用中的每一个发送到支持它的每个已启用后端：

 * [LuxonisTracker.log_hyperparams](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)；
 * [LuxonisTracker.log_metric](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
   和
   [LuxonisTracker.log_metrics](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)；
 * [LuxonisTracker.log_image](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
   和
   [LuxonisTracker.log_images](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)；
 * [LuxonisTracker.log_matrix](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)；
 * [LuxonisTracker.upload_artifact](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)。

TensorBoard 不接受工件，因此
[LuxonisTracker.upload_artifact](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
仅到达 Weights & Biases 和 MLflow。

[LuxonisTracker.close](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
不调用任何后端。当您启用 MLflow 时，它会将未发送的 MLflow 缓冲区写入磁盘。

图像是形状为 (H, W, C) 的 `numpy` 数组。

## MLflow 注意事项

MLflow 在首次访问
[LuxonisTracker.experiment](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
时启动。失败的 MLflow 调用不会引发异常。跟踪器会缓冲有效负载并在下一次成功调用后重试。

[LuxonisTracker.close](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
将仍未清空的缓冲区写入 `<save_directory>/<run_name>` 下：

 * `local_logs.json` 包含指标、参数、矩阵以及保存图像和工件的索引；
 * `images/` 包含缓冲的图像；
 * `artifacts/` 包含每个缓冲工件的副本，其源文件仍然存在。

为 Cloudflare Access 后面的 MLflow 服务器设置 `MLFLOW_CLOUDFLARE_ID` 和 `MLFLOW_CLOUDFLARE_SECRET`。在您的应用程序中注册
[LuxonisRequestHeaderProvider](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/mlflow_plugins.md)，因为
LuxonisML 没有为其声明 MLflow 入口点。

> **另请参阅**
> [luxonis_ml.tracker.tracker](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md) 用于日志记录实现，[luxonis_ml.tracker.mlflow_plugins](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/mlflow_plugins.md) 用于 MLflow 请求头支持。

## 子页面

 * [mlflow_plugins](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/mlflow_plugins.md)
 * [tracker](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
