define_metric

此功能需要 swanlab >= 0.10.0。

define_metric(
    key: str,
    *,
    x_axis: Optional[str] = None,
    section_name: Optional[str] = None,
    hidden: Optional[bool] = None,
    step_sync: Optional[bool] = None,
    overwrite: bool = False,
) -> None

除 key 外的参数均为关键字参数。

参数	描述
key	指标名，支持精确 key 或末尾带单个 * 的 glob 匹配（如 "train/*"，单独的 "*" 匹配所有自定义指标）。"*loss"、"train/*/x"、"train/**" 等写法会被拒绝（仅给出告警，该条定义不生效）；系统指标 key 不参与匹配。
x_axis	自定义 X 轴的指标 key。为 None 时使用系统 step 作为 X 轴。兼容 step_metric 参数别名。
section_name	图表分组名。为 None 时使用默认分组（按指标名前缀分组）。
hidden	是否隐藏图表。为 True 时对 key 匹配过的图表放入 HIDDEN 分组，为 False 时取消隐藏。
step_sync	X 轴与 Y 轴指标分开 log 时，是否自动为 Y 值补上最近一次的 X 值。设置 x_axis 后默认开启，一般无需修改。
overwrite	False 时与已有定义合并；为 True 时将未指定的字段重置为默认值。默认为 False。仅影响未被 log 过的 key。

简介

swanlab.define_metric 用于在 swanlab.log 之前定义指标的图表行为，包括：

• 自定义 X 轴：用另一个指标（如 epoch）作为 X 轴，而不是默认的 step
• 图表分组：将指标图表归入自定义分组
• 隐藏图表：将不常用的图表放入 HIDDEN 分组

自定义 X 轴

将 train/loss 的 X 轴设置为 train/epoch：

import swanlab

swanlab.init(project="my-project")

swanlab.define_metric("train/loss", x_axis="train/epoch")

for epoch in range(num_epochs):
    swanlab.log({"train/epoch": epoch})
    # ... 训练 ...
    swanlab.log({"train/loss": loss})  # 自动同步 train/epoch 的值

X 轴指标和 Y 轴指标可以分开记录，step_sync 会自动给 Y 值补上最近一次的 X 值。建议每轮先 log X 轴指标、再 log Y 轴指标；如果 X 值比 Y 值晚记录，图表会沿用之前自动补上的 X 值，并给出告警提示。

x_axis 必须是合法的指标 key（或系统值 "_step"、"_relative_time"），且不能是系统指标 key；校验失败时整条定义不生效并给出报错。

自定义 X 轴默认假设单调递增：同一个 X 值只保留第一个 Y 点。如果 X 非单调（如 5→6→5），回退的 X 值会被当作新值接受，同一 X 值上可能出现多个 Y 点。

glob 批量定义

key 支持末尾带单个 * 的 glob 匹配，可批量定义一组指标：

# 将 val/ 下的所有指标放入 "Validation" 分组
swanlab.define_metric("val/*", section_name="Validation")

当一个指标同时命中多条规则时：精确匹配的 key 优先，其次是前缀更长的 glob，最后才是默认行为。例如：

swanlab.define_metric("train/stage/acc", x_axis="x1")
swanlab.define_metric("train/*", x_axis="x2")
swanlab.define_metric("train/stage/*", x_axis="x3")

• train/stage/acc 的 X 轴为 x1（精确匹配，最具体）
• train/stage/ 下的其他指标 X 轴为 x3（train/stage/* 比 train/* 更具体）
• train/ 下的其余指标 X 轴为 x2

隐藏图表

# 图表放入 HIDDEN 分组，默认不在看板中显示
swanlab.define_metric("debug/grad_norm", hidden=True)

被隐藏的指标数据仍会正常记录和上传，只是图表被折叠进 HIDDEN 分组，可随时在WebUI看板中取消。

不传 hidden 时会保留已有设置；如需取消之前的隐藏，显式传入 hidden=False 即可。

合并与覆盖

对同一个 key 多次调用 define_metric 时：

• overwrite=False（默认）：在已有定义的基础上合并，只更新这次指定的字段
• overwrite=True：覆盖，此次没指定的字段全部回到默认值

swanlab.define_metric("train/loss", x_axis="train/epoch")
swanlab.define_metric("train/loss", section_name="Train")  # 合并：x_axis 保留，新增分组
swanlab.define_metric("train/loss", section_name="Train", overwrite=True)  # 覆盖：x_axis 重置为默认 step

合并和覆盖只对还没有被 log 过的 key 有效。一旦指标被 log、图表已经创建，再调用 define_metric 不会生效，只能通过 WebUI 调整。

注意事项

1. 同一项目下，同一个指标只对应一张图表。例如 run1 中首次 define_metric("train/loss", x_axis="x1") 生效后，同项目的 run2 再定义 x_axis="x2" 不会生效。
2. 图片、音频等多媒体指标会忽略 x_axis（仍按 step 展示），只应用 section_name 和 hidden。
3. 通过 define_metric 图表定义只在「当前默认视图」和「复制视图」中生效，执行「复制/移动实验」、「添加对比实验」、「新建默认视图」时，分组关系会保留，但自定义的 X 轴关联会丢失，X 轴回退为默认的 step。