experiment-tracking
Instrument Python ML and data scripts with ClearML Task experiment tracking, Logger reports, artifacts, configs, models, offline mode, and tracking validation.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- experiment-tracking
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- description
- Instrument Python ML and data scripts with ClearML Task experiment tracking, Logger reports, artifacts, configs, models, offline mode, and tracking validation.
- disable-model-invocation
- true
02 资源文件 3
- 参考文档references/api-reference.md12.4 KB
- 参考文档references/troubleshooting.md10.3 KB
- 参考文档references/workflows.md9.5 KB
03 SKILL.md 正文
ClearML Experiment Tracking
Use this sub-skill when a user asks to add, review, or troubleshoot ClearML experiment tracking in a Python script. It covers Task.init, TaskTypes, connected hyperparameters/configuration, Logger reports, artifacts, model metadata, framework auto-logging, offline mode, task reuse, output_uri, and static validation.
When To Use
- Retrofit a training/evaluation script with ClearML tracking while preserving existing
argparse, config files, framework logging, and model save paths. - Add explicit reports for scalars, text, images, tables, Plotly, Matplotlib, artifacts, or model metadata.
- Make a script work without credentials by using offline mode and later import the offline session.
- Diagnose missing metrics, duplicate task reuse, upload failures, bad
output_uri, or logger calls made beforeTask.init. - Validate a candidate script without importing the user code or contacting a ClearML server.
Route Elsewhere
- Use
../data-storage/SKILL.mdforDataset,StorageManager,clearml-data, dataset versioning, cache/download, and object-storage data movement. - Use
../remote-execution-cli/SKILL.mdforclearml-task,Task.create,Task.enqueue, agents, queues, Docker execution, and remote execution packaging. - Use
../automation-pipelines/SKILL.mdforPipelineController,PipelineDecorator, HPO, schedulers, triggers, and pipeline orchestration. - Use
../routers-services/SKILL.mdforTask.get_http_router(), service endpoints, FastAPI/router integration, and theclearml[router]extra.
Essential References
- Read
references/api-reference.mdfor verified tracking/reporting signatures, parameter notes, and method-selection guidance. - Read
references/workflows.mdfor concrete instrumentation recipes, logging examples, offline fallback, and validation flow. - Read
references/troubleshooting.mdfor symptoms, likely causes, and fixes across credentials, config, uploads, reuse, offline mode, framework auto-connect, and logger misuse. - Run
scripts/validate_tracking_script.py --helpto inspect a Python file statically for likely ClearML tracking issues.
Minimal Instrumentation Pattern
Place Task.init near the start of executable code, before training starts and before framework writers, plots, or model checkpoints are created.
from clearml import Task, TaskTypes
task = Task.init(
project_name="my-project",
task_name="train-model",
task_type=TaskTypes.training,
reuse_last_task_id=False,
output_uri=True,
)
Use reuse_last_task_id=False for most repeatable local training runs so previous outputs are not overwritten. Use continue_last_task=True only when intentionally appending to an existing task, and prefer an explicit reuse_last_task_id="<task-id>" when continuing a known task.
Connect Inputs
- Let
Task.init(auto_connect_arg_parser=True)capture common CLI parsers automatically, or pass a dictionary to include/exclude specific arguments. - Use
task.connect(params, name="General")for dictionaries,argparse.Namespace,TaskParameters, model objects, or simple config classes. - Use
task.connect_configuration(config_path_or_dict, name="train_config")before reading a JSON/YAML/config file so remote overrides can replace the file or dictionary. - Use
ignore_remote_overrides=Trueonconnectorconnect_configurationonly when the script must not accept UI/backend overrides.
Report Outputs
- Get a logger with
logger = task.get_logger()or, inside helper functions after initialization,Task.current_task().get_logger(). - Report scalar curves with
logger.report_scalar(title="train", series="loss", value=loss, iteration=step). - Report text with
logger.report_text("message"); stdout, stderr, and Python logging are also captured whenauto_connect_streams=True. - Report images/plots/tables with
report_image,report_matplotlib_figure,report_plotly, andreport_table. - Upload one-time artifacts with
task.upload_artifact(name="metrics", artifact_object=metrics, wait_on_upload=True)when later code depends on upload success. - Register a live pandas DataFrame with
task.register_artifact(...)only when dynamic synchronization is intended; otherwise preferupload_artifact.
Model Tracking
- Let framework auto-connect track supported model files when possible through
auto_connect_frameworks=Trueor a framework-specific mapping such as{"pytorch": ["*.pt", "*.pth"]}. - Use
OutputModel(task=task, name="model")when manually registering or uploading model weights. - Call
output_model.update_labels(labels)for class mappings andoutput_model.update_weights(weights_filename="model.pt")for local weights; useregister_uri="..."for an existing remote model URL. - Use
InputModel(model_id=...)orInputModel(name=..., project=...)for existing model inputs, then connect it withtask.connect(input_model, name="pretrained")if the task should record it.
Offline And Credentials Pattern
Use offline mode when the script must run without credentials or network access:
from clearml import Task
Task.set_offline(True)
task = Task.init(project_name="offline", task_name="train")
# training and reporting here
task.close()
Task.set_offline(False)
Task.import_offline_session(task.get_offline_mode_folder())
Set offline mode before Task.init. Close the task before switching back online. Do not use Task.create for offline experiment capture.
Validation Checklist
from clearml import Taskexists andTask.init(...)is called exactly once for the main process.Task.inithas stableproject_name,task_name, and a suitabletask_typefromTaskTypes.Task.inithappens before parser parsing, framework logger/writer creation, Matplotlib plotting, model checkpoint setup, andLoggerreporting.- Repeated local runs use
reuse_last_task_id=False, unless intentional reuse/continue behavior is documented. - Artifact/model uploads have
output_uri=Trueor a configured storage URI when server file storage is not enough. - Offline fallback sets
Task.set_offline(True)beforeTask.initand closes/imports the session when appropriate. - Manual reports use
task.get_logger()orTask.current_task().get_logger()after initialization, notLogger()construction. - The script still runs without optional ML frameworks if the requested change is limited to ClearML instrumentation.
Static Helper
Run the bundled validator against a candidate script:
python scripts/validate_tracking_script.py path/to/train.py
The helper parses the file with ast, never imports the script, never imports ClearML, and never contacts a server. Treat warnings as review prompts; it cannot prove runtime server connectivity, storage credentials, optional framework installation, or remote override behavior.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.