Hugging Face Trackio 实验指标记录实战：从本地 SQLite 到 HF Space 实时看板

Hugging Face Trackio 实验指标记录实战从本地 SQLite 到 HF Space 实时看板【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills本文以 Hugging Face 轻量级实验追踪库 Trackio 为核心系统讲解如何在模型训练中通过trackio.init()/trackio.log()/trackio.finish()记录指标如何用space_id把指标同步到 Hugging Face Space 实现持久化看板以及与 TRL Trainer 的report_totrackio深度集成方案。读完本文你将掌握一套本地优先、可随时同步云端、且与 wandb 兼容的训练指标记录体系并能在 Hugging Face Jobs 等远程训练场景中正确配置避免指标因实例销毁而丢失。Trackio 是什么Trackio 是 Hugging Face 提供的轻量、免费的实验追踪库采用本地优先local-first设计默认情况下指标写入本地 SQLite 数据库并可在本机启动实时看板当传入space_id时指标会同步到 Hugging Face Space从而获得可分享、可持久化的远程看板。其 API 与 wandb 兼容可作为 wandb 的 drop-in 替换无需修改既有调用习惯。在本仓库中Trackio 相关能力被沉淀在 huggingface-trackio 这一技能中整体分为三个接口面任务接口参考文档训练中记录指标Python APIreferences/logging_metrics.md训练中触发告警Python APIreferences/alerts.md训练中/后查询指标与告警CLIreferences/retrieving_metrics.md本文聚焦第一个接口面指标记录logging metrics。安装Trackio 可以通过 pip 或 uv 安装pip install trackio # 或 uv pip install trackio在仓库的训练示例脚本中Trackio 被列为显式依赖。例如 train_sft_example.py 顶部使用 PEP 723 内联依赖声明# /// script # requires-python 3.10 # dependencies [ # trl0.12.0, # peft0.7.0, # transformers4.36.0, # accelerate0.24.0, # trackio, # ] # ///这意味着通过uv run或hf_jobs提交脚本时Trackio 会被自动安装在视觉训练等场景的依赖清单中也同样声明了trackio见 reliability_principles.md。核心 APIinit / log / finish基本用法Trackio 的核心调用模型与 wandb 一致分为三步初始化、反复记录、收尾。import trackio # Initialize a run trackio.init( projectmy-project, config{learning_rate: 0.001, epochs: 10} ) # Log metrics during training for epoch in range(10): loss train_epoch() trackio.log({loss: loss, epoch: epoch}) # Finalize the run trackio.finish()关键函数函数作用trackio.init(...)开启一次新的追踪 runtrackio.log(dict)记录指标训练过程中反复调用trackio.finish()结束 run确保所有指标被保存远程场景下会 drain 掉待同步指标trackio.show()启动本地看板trackio.sync(...)将本地项目同步到 HF Space从仓库的技能定义SKILL.md可以看到官方推荐的指标记录流程即用trackio.init()初始化 → 用trackio.log()或 TRL 的report_totrackio记录 → 用trackio.finish()收尾。trackio.init() 参数详解trackio.init()是配置一次实验 run 的核心入口参数如下trackio.init( projectmy-project, # 项目名将多个 run 归组 namerun-name, # 可选本次 run 的名称 config{...}, # 要记录的超参数与配置 space_idusername/trackio, # 可选同步到 HF Space获得远程看板 privateTrue, # 可选自动创建的 Space 是否私有。 # 默认 PUBLIC除非你的组织默认私有 bucket_idusername/my-bucket, # 可选固定指标存储所用的 HF Bucket。 # 默认由 space_id 自动推导 groupexperiment-group, # 可选将相关 run 归组 )参数语义补充说明project必填用于把多个 run 聚合到同一个项目下是后续 CLI 查询trackio list projects、trackio get project --project name的组织单元name可选给当前 run 一个便于识别的名称例如baseline-lr2e5不传时 Trackio 会生成默认名称config记录的超参数与元信息模型名、数据集、学习率、epochs 等这些信息会随 run 一起保存在数据库中并可在看板中用于对比space_id用户名/space名形式。传了才会启用远程同步如果对应 Space 不存在Trackio 会自动创建private仅影响自动创建的 Space 的可见性若 Space 已存在则该参数被忽略bucket_id用于固定指标存储所用的 HF Bucket不传时由space_id自动推导group把相关 run 在侧边栏中归组展示便于按实验类型或超参数对比详见下文对 run 归组。本地看板与远程看板本地模式默认默认情况下Trackio 把指标存储在本地 SQLite 数据库中并在本机启动看板trackio.init(projectmy-project) # ... training ... trackio.finish() # 启动本地看板 trackio.show()也可以在终端中启动trackio show --project my-projectshow命令还支持--theme自定义主题、--color-palette自定义颜色、--mcp-server启用 MCP server 模式等选项详见 retrieving_metrics.md。远程模式HF Space传入space_id后指标会同步到 Hugging Face Space获得持久化、可分享的看板trackio.init( projectmy-project, space_idusername/trackio, # 若 Space 不存在会自动创建 privateTrue, # Space 默认 PUBLIC需要可分享看板时可不传 )⚠️远程训练云端 GPU、HF Jobs 等必须使用space_id远程实例是临时的本地存储会在实例终止时丢失。如果不希望指标公开同时传入privateTrue——因为自动创建的 Space 默认是公开的除非你的组织默认私有若 Space 已存在该参数会被忽略。这一警告在仓库的 trackio_guide.md 中有更详细的展开Jobs 训练发生在临时的云端 runner 上而非本地机器Trackio 通过 Space 实时同步指标没有 Space指标会在任务结束时丢失而 Space 看板可以永久保存训练指标。本地同步到远程如果已经在本地积累了项目数据可以用sync将本地项目同步到某个 Spacetrackio.sync(projectmy-project, space_idusername/my-experiments)对应 CLI 形式为trackio sync --project name --space-id space_id还支持--private创建私有 Space、--force覆盖已有数据库见 retrieving_metrics.md。wandb 兼容性一行代码替换Trackio 与 wandb 的 API 兼容可以直接作为 drop-in 替换import trackio as wandb wandb.init(projectmy-project) wandb.log({loss: 0.5}) wandb.finish()只需把import wandb改为import trackio as wandb原有调用即可无缝迁移且数据默认留在本地无需注册账号。与 TRL Trainer 集成在 TRL 训练器中使用report_totrackio即可自动记录指标无需手动在训练循环里打点from trl import SFTConfig, SFTTrainer import trackio trackio.init( projectsft-training, space_idusername/trackio, privateTrue, # Space 默认公开需要可分享看板时不传 config{model: Qwen/Qwen2.5-0.5B, dataset: trl-lib/Capybara} ) config SFTConfig( output_dir./output, report_totrackio, # 自动指标记录 # ... 其他配置 ) trainer SFTTrainer(modelmodel, argsconfig, ...) trainer.train() trackio.finish()仓库中的真实集成范例仓库的完整 SFT 训练脚本 train_sft_example.py 展示了生产级用法——除了report_totrackio外还同时设置了project与run_name直接映射到 Trackio 的项目与 run 名称# Monitoring report_totrackio, # Integrate with Trackio projectmeaningful_project_name, # project name for the training name (trackio) run_namebaseline-run, #Descriptive name for this training run训练结束后调用trackio.finish()确保指标被完整同步然后打印看板地址# Finish Trackio tracking trackio.finish() print(✅ Complete! Model at: https://huggingface.co/username/qwen-capybara-sft) print( View metrics at: https://huggingface.co/spaces/username/trackio)同样的集成模式也出现在 train_dpo_example.pyDPOTrainer和 train_grpo_example.pyGRPOTrainer中说明report_totrackio对 TRL 的 SFT / DPO / GRPO 三大训练器均适用。此外 unsloth_sft_example.py 展示了将 Trackio 与 TensorBoard 同时启用report_to[tensorboard, trackio]的组合用法并通过--trackio-space命令行参数设置TRACKIO_SPACE_ID环境变量。在 Hugging Face Jobs 上的推荐配置当通过hf_jobs在远程 GPU 上运行时trackio_guide.md 给出了完整流程添加依赖在dependencies中加入trackio准备 Space一次性推荐直接传space_id让 Trackio 自动创建也可手动通过 Hub UI 或hf repos create my-trackio-dashboard --type space --space-sdk gradio创建初始化trackio.init(projectmy-training, space_idusername/trackio, privateTrue, config{...})——对 Jobs 而言space_id是关键参数配置 TRLSFTConfig(report_totrackio, ...)收尾trainer.train()之后调用trackio.finish()确保最终指标被同步。同时注意通过secrets传递HF_TOKEN是 Space 自动创建与 Bucket 写入的前提hf_jobs(uv, { script: ..., secrets: { HF_TOKEN: $HF_TOKEN # 支持 Space 创建与 Hub 推送 } })自动记录与手动记录的内容TRL / Transformers 集成时自动记录使用 TRL/Transformers 集成时Trackio 自动捕获训练损失training loss学习率learning rate评估指标eval metrics训练吞吐量training throughput在检测到 NVIDIA GPU 且安装了nvidia-ml-py的环境下标准的 Jobs GPU 规格即是如此还会自动记录 GPU 利用率与显存占用见 trackio_guide.md。手动记录任意数值指标手动打点时可以记录任何数值型指标trackio.log({ train_loss: 0.5, train_accuracy: 0.85, val_loss: 0.4, val_accuracy: 0.88, epoch: 1 })数据落盘机制对于远程场景Trackio 的数据流是分层的见 trackio_guide.md训练运行 → 指标以亚秒级小批量流式写入正在运行的 SpaceSpace 不可达或仍在构建 → 指标回落到 HF Bucket默认由space_id自动推导也可用bucket_id固定约每 30 秒一次Space 看板 → 将 SQLite 数据库存放在 Bucket 中并约每 15 秒摄取回落的指标任务完成 →trackio.finish()排空所有待同步指标确保全部持久化。这一机制解释了为什么space_id在远程训练中如此重要它是 Space 看板、Buckets 存储以及bucket_id推导三者之间的纽带。对 run 归组Grouping用group参数可以在看板侧边栏中把相关实验组织到一起适合超参数扫描或对照实验# 按实验类型归组 trackio.init(projectmy-project, namebaseline-v1, groupbaseline) trackio.init(projectmy-project, nameaugmented-v1, groupaugmented) # 按超参数归组 trackio.init(projecthyperparam-sweep, namelr-0.001, grouplr_0.001) trackio.init(projecthyperparam-sweep, namelr-0.01, grouplr_0.01)归组的典型用途是同一项目下运行多个配置不同的实验时通过group把它们在侧边栏中归类便于横向对比见 trackio_guide.md。配置最佳实践配置项应保持精简——只记录对 run 间对比有用的信息trackio.init( projectqwen-sft-capybara, namebaseline-lr2e5, config{ model: Qwen/Qwen2.5-0.5B, dataset: trl-lib/Capybara, learning_rate: 2e-5, num_epochs: 3, batch_size: 8, } )仓库推荐的默认模式总结如下见 trackio_guide.mdSpace ID使用{username}/trackio默认 Space 名为trackioRun 命名除非用户另有要求用用户能识别的描述性名称命名 runConfig保持最小化除非用户要求不自动捕获任务元数据Grouping仅当用户要求组织相关实验时才使用私有性注意自动创建的 Space 默认公开需要私密指标时传入privateTrue。在看板中嵌入指标Space 看板支持通过查询参数嵌入网站iframe srchttps://username-trackio.hf.space/?projectmy-projectmetricstrain_loss,val_losssidebarhidden stylewidth:1600px; height:500px; border:0; /iframe查询参数说明project过滤到指定项目metrics逗号分隔的指标名控制展示哪些曲线sidebarhidden或collapsedsmoothing0-20平滑滑块值xmin、xmaxX 轴范围记录之后的闭环CLI 查询与告警记录只是实验追踪的第一步。仓库把查询和告警作为另外两个接口面与本文的 logging 形成完整闭环查询指标trackio get metric --project name --run name --metric loss --json支持--step、--around、--at-time、--window等按步/按时间窗过滤详见 retrieving_metrics.md告警在训练代码中插入trackio.alert(title..., leveltrackio.AlertLevel.WARN)告警会打印到终端、存入数据库、展示在看板并可经 webhook 转发到 Slack/Discord详见 alerts.md。对于 LLM Agent 自主跑实验的场景SKILL.md 给出了推荐闭环插入告警 → 后台启动训练 → 用trackio list alerts --project name --json --since ts轮询告警 → 用trackio get metric ...读取指标 → 根据结果调整超参并重新启动 run。总结Trackio 为 Hugging Face 生态提供了一条零账号、本地优先、可远程的训练指标记录路径日常开发用trackio.init()trackio.log()trackio.finish()三步记录配合trackio.show()本地看板即可满足需求一旦进入 HF Jobs 等远程训练务必传入space_id必要时配合privateTrue让指标落到 Space/Bucket配合report_totrackio自动捕获损失、学习率、评估指标与吞吐量。本文对应的完整可运行示例位于 train_sft_example.pyTRL 集成要点可进一步查阅 trackio_guide.md。【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考