getitune-training-a-model

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Training a model with getitune

使用getitune训练模型

getitune

is a low-code transfer-learning library. Training is driven by an

Engine

created with

create_engine(...)

, which pairs a model/recipe with a dataset and returns a runnable engine. Recipes (YAML under

library/src/getitune/recipe/<task>/

) bundle model + data pipeline + training config, so a model name alone gives a strong baseline.

There are two equal entry points that share the same objects and recipes:

Python API —

from getitune.engine import create_engine

, then

engine.train()

engine.test()

. Preferred for notebooks, scripts, tests, and library integration. See

library/README.md

("Quick Start") and

library/docs/source/guide/get_started/api_tutorial.rst

CLI —

getitune train --data_root <path> --model <name|recipe.yaml>

. Preferred for reproducible experiments and shell workflows. See

library/docs/source/guide/get_started/cli_commands.rst

Run everything from

library/

. Install with the extra that matches your hardware:

uv sync

(cpu),

uv sync --extra xpu

, or

uv sync --extra cuda

getitune

是一个低代码迁移学习库。训练由通过

create_engine(...)

创建的

Engine

驱动，它将模型/recipe与数据集配对，并返回一个可运行的引擎。Recipes（位于

library/src/getitune/recipe/<task>/

下的YAML文件）整合了模型、数据管道和训练配置，因此仅需指定模型名称就能获得一个性能不错的基线。

有两个等价的入口点，它们共享相同的对象和recipes：

Python API — 导入

from getitune.engine import create_engine

，然后调用

engine.train()

engine.test()

。适用于Notebook、脚本、测试和库集成场景。详见

library/README.md

（“快速开始”）和

library/docs/source/guide/get_started/api_tutorial.rst

。

CLI — 执行

getitune train --data_root <path> --model <name|recipe.yaml>

。适用于可复现的实验和Shell工作流。详见

library/docs/source/guide/get_started/cli_commands.rst

。

所有操作都在

library/

目录下执行。根据你的硬件安装对应的扩展包：

uv sync

（CPU）、

uv sync --extra xpu

或

uv sync --extra cuda

。

Python API workflow

Python API工作流

python

from getitune.engine import create_engine

engine = create_engine(
    model="efficientnet_b0",          # model name, recipe .yaml path, or model class
    data="/path/to/dataset_root",     # dataset root (COCO/YOLO/VOC/native), auto-detected
    work_dir="./my_workspace",        # checkpoints + logs; defaults to ./getitune-workspace
    device="auto",                    # "auto", "cpu", "gpu", "xpu", "cuda", "0", ...
)
engine.train(max_epochs=50)
engine.test()

Pick the model/recipe. Pass a model name (
```
"efficientnet_b0"
```
), a recipe path (
```
"src/getitune/recipe/detection/yolox_s.yaml"
```
), or a model class. If a name matches recipes under several tasks, pass
```
task=
```
(e.g.
```
task="DETECTION"
```
) to disambiguate. Use the
```
getitune-discovering-models
```
skill to list options.
- Done when:
```
create_engine(...)
```
  returns without a
```
ValueError
```
  /
```
FileNotFoundError
```
  .
Point
data=
at the dataset root. Format is auto-detected by Datumaro; see the
```
getitune-preparing-datasets
```
skill.
- Done when: the engine builds a datamodule without a format/feature error.
Smoke-test the wiring first with a tiny run (
```
engine.train(max_epochs=1)
```
or a small subset) before a long run.
- Done when: one train + one validation pass complete without shape errors.
Train, overriding hyperparameters as needed (
```
engine.train(max_epochs=50)
```
).
- Done when: checkpoints appear under
```
work_dir
```
  .
Evaluate with
```
engine.test()
```
and confirm the task metric moves, not just loss. Record the model +
```
work_dir
```
that produced it.

Warm-start from existing weights with

create_engine(..., checkpoint="/path/to/weights.pt")

python

from getitune.engine import create_engine

engine = create_engine(
    model="efficientnet_b0",          # 模型名称、recipe .yaml路径或模型类
    data="/path/to/dataset_root",     # 数据集根目录（COCO/YOLO/VOC/原生格式），会自动检测格式
    work_dir="./my_workspace",        # 检查点和日志存储目录；默认是./getitune-workspace
    device="auto",                    # "auto"、"cpu"、"gpu"、"xpu"、"cuda"、"0"等
)
engine.train(max_epochs=50)
engine.test()

选择模型/recipe。传入模型名称（
```
"efficientnet_b0"
```
）、recipe路径（
```
"src/getitune/recipe/detection/yolox_s.yaml"
```
）或模型类。如果一个名称对应多个任务下的recipe，需传入
```
task=
```
参数（例如
```
task="DETECTION"
```
）来消除歧义。使用
```
getitune-discovering-models
```
技能查看可选选项。
- 完成标志：
```
create_engine(...)
```
  执行后未抛出
```
ValueError
```
  /
```
FileNotFoundError
```
  。
将
data=
指向数据集根目录。格式由Datumaro自动检测；详见
```
getitune-preparing-datasets
```
技能。
- 完成标志：引擎成功构建数据模块，未出现格式/特征错误。
先进行冒烟测试：在长时间运行前，先执行一次小型运行（
```
engine.train(max_epochs=1)
```
或使用小数据集子集）。
- 完成标志：一次训练+一次验证过程顺利完成，未出现形状错误。
训练：根据需要覆盖超参数（
```
engine.train(max_epochs=50)
```
）。
- 完成标志：检查点出现在
```
work_dir
```
  目录下。
评估：调用
```
engine.test()
```
并确认任务指标有所变化，而不仅仅是损失值。记录生成该模型的模型名称和
```
work_dir
```
路径。

通过

create_engine(..., checkpoint="/path/to/weights.pt")

从已有权重热启动训练。

CLI workflow

CLI工作流

bash

undefined

bash

undefined

from library/

在library/目录下执行

1. Simplest: data only — getitune picks a default model for the task

1. 最简方式：仅指定数据集 — getitune会为任务选择默认模型

getitune train --data_root /path/to/dataset

2. Choose a model or recipe

2. 选择模型或recipe

getitune train --data_root /path/to/dataset --model yolox_s

3. Override hyperparameters

3. 覆盖超参数

getitune train --data_root /path/to/dataset --model yolox_s
--max_epochs 200 --checkpoint /path/to/weights.pt

4. Run a full, resolved config file

4. 使用完整的已解析配置文件运行

getitune train --data_root /path/to/dataset --config src/getitune/recipe/detection/yolox_s.yaml


`getitune test` and `getitune predict` share the same `--model` / `--data_root`
shape. Use `getitune <cmd> --help -v` (and `-vv`) for the full overridable
argument list.

getitune train --data_root /path/to/dataset --config src/getitune/recipe/detection/yolox_s.yaml


`getitune test`和`getitune predict`使用与上述相同的`--model` / `--data_root`参数格式。使用`getitune <cmd> --help -v`（以及`-vv`）查看所有可覆盖的参数列表。

Choosing a device

选择设备

```
device="auto"
```
selects an available accelerator; force with
```
"cpu"
```
,
```
"gpu"
```
,
```
"xpu"
```
,
```
"cuda"
```
, or an index like
```
"0"
```
.
The device must match the installed extra —
```
--extra xpu
```
for Intel GPUs,
```
--extra cuda
```
for NVIDIA. Guard nothing yourself; the library handles capability checks.

```
device="auto"
```
会自动选择可用的加速器；也可以强制指定为
```
"cpu"
```
、
```
"gpu"
```
、
```
"xpu"
```
、
```
"cuda"
```
或索引值如
```
"0"
```
。
设备必须与安装的扩展包匹配 — Intel GPU使用
```
--extra xpu
```
，NVIDIA GPU使用
```
--extra cuda
```
。无需自行检查兼容性，库会处理能力验证。

Debugging a run

调试训练运行

Run one epoch on a small dataset first to isolate construction vs. dataloading vs. training failures.
Shape/feature mismatches usually mean the dataset's labels or task disagree with the model — recheck
```
task=
```
and the dataset format (
```
getitune-preparing-datasets
```
).
Dataset auto-detection failures: confirm the folder matches one supported layout (COCO/YOLO/VOC/native).

先在小数据集上运行一个epoch，以区分是构建阶段、数据加载阶段还是训练阶段的错误。
形状/特征不匹配通常意味着数据集的标签或任务与模型不匹配 — 重新检查
```
task=
```
参数和数据集格式（参考
```
getitune-preparing-datasets
```
技能）。
数据集自动检测失败：确认文件夹结构符合支持的格式（COCO/YOLO/VOC/原生格式）。

Verify

验证

bash

undefined

bash

undefined

from library/

在library/目录下执行

just lint just test-unit -- -k engine # when you changed engine/training code


For API-facing work, add or run a short Python smoke test that calls
`create_engine(...)` + `engine.train(max_epochs=1)` on a tiny fixture rather than
a long real run.

just lint just test-unit -- -k engine # 当你修改了引擎/训练代码时执行


对于面向API的工作，添加或运行一个简短的Python冒烟测试，在小型测试数据上调用`create_engine(...)` + `engine.train(max_epochs=1)`，而不是运行长时间的真实训练。

getitune-training-a-model

Original

Translation

Training a model with getitune

使用getitune训练模型

Python API workflow

Python API工作流

CLI workflow

CLI工作流

from library/

在library/目录下执行

1. Simplest: data only — getitune picks a default model for the task

1. 最简方式：仅指定数据集 — getitune会为任务选择默认模型

2. Choose a model or recipe

2. 选择模型或recipe

3. Override hyperparameters

3. 覆盖超参数

4. Run a full, resolved config file

4. 使用完整的已解析配置文件运行

Choosing a device

选择设备

Debugging a run

调试训练运行

Verify

验证

from library/

在library/目录下执行

Related skills

相关技能