Trackio documentation

API 参考

Trackio

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

API 参考

运行

类 trackio.Run

( url: str | Noneproject: strclient: typing.Optional[typing.Any]name: str | None = Nonerun_id: str | None = Nonegroup: str | None = Noneconfig: dict | None = Nonespace_id: str | None = Nonebucket_id: str | None = Noneserver_base_url: str | None = Nonewrite_token: str | None = Noneexisting_runs: list[str] | None = Noneinitial_last_step: int | None = Noneauto_log_gpu: bool = Falsegpu_log_interval: float = 10.0auto_log_cpu: bool = Falsecpu_log_interval: float = 10.0webhook_url: str | None = Nonewebhook_min_level: trackio.alerts.AlertLevel | str | None = Nonecapture_console: bool = False )

link_artifact

( artifact: Artifacttarget_path: straliases: list[str] | None = Nonebucket_id: str | None = None )

参数

artifact (Artifact) — 要链接的 artifact 版本。必须是一个已记录或已获取的 Artifact。若要链接某个特定的现有版本，请先使用 use_artifact("my-model:v3") 获取它，然后链接返回的结果。如果某个 artifact 从未被记录过，则会先将其记录到当前运行的项目中。
target_path (str) — 要链接到的集合，格式为 "registry-<registry>/<collection>"，例如 "registry-models/my-model"。注册表必须已存在（参见 trackio.Api().create_registry）。集合在首次链接时创建，并采用该工件的类型；后续链接必须与该类型匹配。
aliases (list[str], 可选) — 要放置在关联版本上的别名，例如 ["staging"]。一个别名在每个 collection 中指向一个版本，因此将某个别名分配给另一个版本时，该别名会随之移动。latest 由系统自动管理，始终指向最新的关联版本；在此处传入该值不会产生任何效果。
bucket_id (str, 可选) — 存放注册表的 Hugging Face bucket，例如 "my-org/models-registry"。如果运行记录到 Space 或自托管服务器，则必须提供此参数以建立关联。对于本地注册表，请省略此参数；如果设置了 TRACKIO_REGISTRY_BUCKET_ID，则默认使用该值。

将工件版本链接到注册表集合中。

链接是指向源版本的指针：不会复制任何文件。该链接会获取集合中的下一个版本号（v0、v1、……），与源工件自身的版本号无关。链接一个已存在于集合中的版本不会创建新版本：你将获得现有的版本，而你传入的 aliases 仍会移动。

本地注册表会将链接与运行数据一起记录，因此仅对本机上的运行可用。若要发布到基于存储桶的注册表，请传入 bucket_id——记录到 Space 或自托管服务器的运行也是通过这种方式发布的，因为存储桶在两端均可访问。

use_artifact

( artifact_or_name: trackio.artifact.Artifact | strtype: str | None = None )

解析一个工件，并将此运行记录为该工件的消费者。

该规范可以是项目工件（"name"、"name:vN"、"name:alias"）或注册表位置（"registry-<registry>/<collection>[:vN|:alias]"），后者会通过集合的链接解析为其所指向的源版本。

init

trackio.init

( project: strname: str | None = Nonegroup: str | None = Nonespace_id: str | None = Noneserver_url: str | None = Nonedataset_id: str | None = Nonebucket_id: str | None = Noneconfig: dict | None = Noneresume: str = 'never'settings: typing.Any = Noneprivate: bool | None = Noneembed: bool = Trueauto_log_gpu: bool | None = Nonegpu_log_interval: float = 10.0auto_log_cpu: bool | None = Nonecpu_log_interval: float = 10.0webhook_url: str | None = Nonewebhook_min_level: trackio.alerts.AlertLevel | str | None = Nonecapture_console: bool | None = None ) → Run

参数

project (str) — 项目名称（可以是用于继续跟踪的现有项目，也可以是用于从头开始跟踪的新项目）。
name (str, 可选) — 运行的名称（如果未提供，将生成一个默认名称）。
group (str, optional) — 该运行所属的组名称，用于帮助将相关的运行组织在一起。您可以在仪表板中切换整个组的可见性。
space_id (str, 可选) — 如果提供此参数，项目将记录到 Hugging Face Space，而不是本地目录。应为完整的 Space 名称，例如 “username/reponame” 或 “orgname/reponame”，或者仅为 “reponame”，在这种情况下，Space 将在当前已登录的 Hugging Face 用户的命名空间中创建。如果该 Space 不存在，它将自动创建。如果该 Space 已存在，项目将记录到其中。也可以通过 TRACKIO_SPACE_ID 环境变量进行设置。您无法将项目记录到已 frozen（转换为静态 SDK）的 Space；请在完成记录后，仅使用 trackio.sync(..., sdk="static")。如果同时设置了多个，则优先于 server_url 和 TRACKIO_SERVER_URL。
server_url (str, optional) — 自托管 Trackio 服务器的基础 URL（http:// 或 https://），或来自 trackio.show() 的具有写入权限的 URL，该 URL 可能包含 write_token 查询参数。客户端会在每个请求中发送该令牌（X-Trackio-Write-Token）；您也可以设置 TRACKIO_WRITE_TOKEN 来代替在 URL 中嵌入令牌。设置后，指标将通过 HTTP 发送到该服务器，而不是创建或同步到 Hugging Face Space。也可以通过 TRACKIO_SERVER_URL 环境变量进行设置。当设置了 space_id 或 TRACKIO_SPACE_ID 时，此参数将被忽略。
dataset_id (str, 可选) — 已弃用：将 trackio 数据持久化到 Hugging Face Dataset 的功能将在 trackio 的后续版本中移除。请改用 bucket_id（一个 Hugging Face Bucket）。
bucket_id (str, optional) — 用于指标持久化的 Hugging Face Bucket 的 ID。默认情况下，当提供了 space_id 且未显式设置 bucket_id 时，会根据 space_id 自动生成一个 bucket。Bucket 提供类似 S3 的存储，且没有 git 开销——SQLite 数据库通过 hf-mount 直接存储在 Space 中。指定 Bucket 时，名称格式如 “username/bucketname” 或仅 “bucketname”。
config (dict，可选) — 配置选项字典。为兼容 wandb.init() 而提供。
resume (str, 可选, 默认为 “never”) — 控制如何处理恢复运行。可以是以下之一：
- “must”：必须使用给定的名称恢复运行，如果该运行不存在则引发错误
- “allow”：如果运行已存在，则恢复该运行；否则创建一个新的运行
- “never”：从不恢复运行，始终创建新的运行
private (bool, optional) — 是否将 Space 设为私有。如果为 None（默认值），除非组织的默认设置为私有，否则该仓库将是公开的。如果该仓库已存在，则此值将被忽略。
settings (Any，可选) — 未使用。为与 wandb.init() 保持兼容而提供。
embed (bool，可选，默认为 True) — 如果在 Jupyter/Colab 笔记本中运行，当调用 trackio.init() 时，是否应自动将仪表板嵌入到单元格中。对于本地运行，这会启动一个本地 Trackio 仪表板并将其嵌入。对于 Space 运行，这会嵌入 Space URL。在 Colab 中，当 share=True 时，本地仪表板将通过公共共享 URL 访问。
auto_log_gpu (bool 或 None，可选，默认为 None) — 控制自动记录 GPU 指标。如果为 None（默认值），当安装了 nvidia-ml-py 并检测到 NVIDIA GPU 或 Apple M 系列芯片时，将自动启用 GPU 记录。设置为 True 可强制启用，设置为 False 可禁用。
gpu_log_interval (float，可选，默认为 10.0) — 自动记录 GPU 指标日志的时间间隔（以秒为单位）。仅在 auto_log_gpu=True 时使用。
auto_log_cpu (bool 或 None，可选，默认为 None) — 控制自动记录 CPU 和 RAM 指标（利用率、内存、磁盘 I/O、网络 I/O 和传感器）。如果为 None（默认值），当安装了 psutil 时，会自动启用 CPU 记录。设置为 True 可强制启用，设置为 False 可禁用。
cpu_log_interval (float，可选，默认为 10.0) — 自动记录 CPU 指标日志的时间间隔（以秒为单位）。仅在启用 CPU 自动日志记录时使用。
webhook_url (str, 可选) — 当调用 trackio.alert() 时，用于 POST 警报负载的 webhook URL。原生支持 Slack 和 Discord 的 webhook URL（负载会自动格式化）。也可以通过环境变量 TRACKIO_WEBHOOK_URL 进行设置。单个警报可以通过向 trackio.alert() 传递 webhook_url 来覆盖此 URL。
webhook_min_level (AlertLevel 或 str，可选) — 应触发 webhook 投递的最低告警级别。例如，AlertLevel.WARN 仅将 WARN 和 ERROR 级别的告警发送到 webhook 目标地址。也可以通过 TRACKIO_WEBHOOK_MIN_LEVEL 进行设置。
capture_console (bool 或 None，可选，默认为 None) — 是否捕获脚本写入 stdout 和 stderr 的所有内容（包括 print() 和 logging 输出），并将其与运行记录一起存储。输出内容会显示在仪表板中该运行的页面上，并且可以在此处下载。如果为 None（默认值），则仅当环境变量 TRACKIO_CAPTURE_CONSOLE 设置为 1 或 true 时，才会启用控制台捕获。

返回值

运行

一个可用于记录指标并结束运行的 [Run] 对象。

创建一个新的 Trackio 项目并返回一个 [Run] 对象。

log

trackio.log

( metrics: dictstep: int | None = None )

参数

metrics (dict) — 要记录的指标字典。
step (int，可选) — 步骤编号。如果未提供，步骤将自动递增。

将指标记录到当前运行中。

log_gpu

trackio.log_gpu

( run: trackio.run.Run | None = Nonedevice: int | None = None ) → dict

参数

run — 可选的 Run 实例。如果为 None，则使用上下文中的当前 run。
device — 用于收集指标的 CUDA 设备索引（仅限 NVIDIA GPU）。如果为 None，则从该进程可见的所有 GPU 中收集。此参数在 Apple GPU 上会被忽略。

返回值

dict

已记录的 GPU 指标。

将 GPU 指标作为系统指标记录到当前或指定的运行中。自动检测是否有 NVIDIA 或 Apple GPU 可用，并调用相应的记录方法。

示例：

import trackio

run = trackio.init(project="my-project")
trackio.log({"loss": 0.5})
trackio.log_gpu()
trackio.log_gpu(device=0)

log_system

trackio.log_system

( metrics: dict )

参数

metrics (dict) — 要记录的系统指标字典。

使用时间戳而非步数，将系统指标（GPU 等）记录到当前运行中。

log_artifact

trackio.log_artifact

( artifact_or_path: trackio.artifact.Artifact | str | pathlib.Pathname: str | None = Nonetype: str | None = Nonealiases: list[str] | None = Noneoverwrite: bool = False )

参数

artifact_or_path (Artifact、str 或 Path) — 要记录的对象（必须已通过 add_file 或 add_dir 添加至少一个文件），或指向要作为新对象记录的文件或目录的路径。
name (str, 可选) — 记录路径时的工件名称。默认为 run-<run_id>-<basename>。不能与 Artifact 一起传递。
type (str, 可选) — 记录路径时的工件类型（例如 "model"、"dataset"）。默认为 "unspecified"。不能与 Artifact 一起传递。
aliases (list[str]，可选) — 要轮换到结果版本上的别名，与 latest 一起（每当创建新版本时会自动分配）。即使内容相同并被去重，您的别名也会轮换到该版本上。
overwrite (bool, 可选) — 如果为 True，则在记录新内容后删除此工件的所有其他版本。仍被其他工件使用的 Blob 会被保留，且版本号会继续递增。默认为 False。

将工件记录为当前运行的输出。

use_artifact

trackio.use_artifact

( artifact_or_name: trackio.artifact.Artifact | strtype: str | None = None )

参数

artifact_or_name (Artifact 或 str) — 一个已记录的 Artifact，或一个 artifact 名称。仅使用名称（"my-model"）时会解析为 :latest；您也可以固定版本（"my-model:v3"）或解析别名（"my-model:prod"）。
type (str，可选) — 如果提供，则与存储的工件类型进行比对，若不匹配则引发异常。

获取一个工件，并将其记录为当前运行的输入。

完成

trackio.finish

( )

结束当前运行。

显示

trackio.show

( project: str | None = Nonedashboard: str | None = Nonetheme: typing.Any = Nonemcp_server: bool | None = Nonefooter: bool = Truecolor_palette: list[str] | None = Noneopen_browser: bool = Trueblock_thread: bool | None = Nonehost: str | None = Noneshare: bool | None = Noneserver_port: int | None = Nonefrontend_dir: str | pathlib.Path | None = None ) → app

参数

project (str, 可选) — 要显示其运行记录的项目名称。如果未提供，将显示所有项目，用户可以从中选择一个。
dashboard (str, 可选) — 设置为 "registry" 以显示独立的 registry 仪表板。默认值为项目仪表板。
theme (Any，可选) — 已忽略。为保持向后兼容而保留；Trackio 不再使用 Gradio 主题。
mcp_server (bool, 可选) — 如果为 True，则在安装了可选依赖项 trackio[mcp] 时，仪表板会在 /mcp 处暴露一个 MCP 服务器。如果为 None（默认值），则使用 GRADIO_MCP_SERVER 环境变量（例如在 Spaces 上）。
footer (bool，可选，默认为 True) — 当值为 False 时，是否在写入令牌 URL 中包含 footer=false。也可以通过 URL 中的 footer 查询参数来控制此行为。
color_palette (list[str], 可选) — 用于绘图线条的十六进制颜色代码列表。如果未提供，将使用 TRACKIO_COLOR_PALETTE 环境变量（以逗号分隔的十六进制代码），如果该变量也未设置，则使用默认调色板。示例：['#FF0000', '#00FF00', '#0000FF']
open_browser (bool，可选，默认为 True) — 如果 True 且当前不在 notebook 中，将打开一个新的浏览器标签页以显示仪表板。如果 False，则不会打开浏览器。
block_thread (bool, 可选) — 如果为 True，主线程将被阻塞，直到仪表盘关闭。如果为 None（默认行为），则在笔记本中启动仪表盘时，主线程不会被阻塞；否则，主线程将被阻塞。
host (str, 可选) — 服务器绑定的主机地址。如果未提供，则默认为 '127.0.0.1'（仅限本地主机）。设置为 '0.0.0.0' 以允许远程访问。
share (bool, 可选) — 如果为 True，则创建一个临时的公共 URL（兼容 Gradio 的隧道）。在 Colab 或托管笔记本中，除非被覆盖，否则默认为 True。
server_port (int, 可选) — 要绑定的端口。如果未设置，则从 GRADIO_SERVER_PORT（默认 7860）开始扫描。
frontend_dir (str | Path, 可选) — 包含自定义静态前端的目录。必须包含 index.html。如果未提供，Trackio 会依次检查 TRACKIO_FRONTEND_DIR、持久化的 Trackio 配置，以及内置的前端。如果显式指定的 frontend_dir 指向一个缺失或为空的目录，Trackio 会将初始模板复制到该目录并从中提供服务。

返回值

app

仪表板句柄（.close() 会停止服务器）。 url：仪表板的本地 URL。 share_url：公共共享 URL（如果存在）。 full_url：包含写入令牌的完整 URL（共享时为共享 URL，否则为本地 URL）。

启动 Trackio 仪表板。

同步

trackio.sync

( project: strspace_id: str | None = Noneprivate: bool | None = Noneforce: bool = Falserun_in_background: bool = Falsesdk: str = 'gradio'dataset_id: str | None = Nonebucket_id: str | None = Nonefrontend_dir: str | pathlib.Path | None = None ) → str

参数

project (str) — 要上传的项目名称。
space_id (str, 可选) — 要上传到的 Space 的 ID（例如 “username/space_id”）。如果未提供，则先检查项目元数据，然后生成一个随机的 space_id。
private (bool, optional) — 是否将 Space 设为私有。如果为 None（默认值），除非组织的默认设置为私有，否则仓库将是公开的。如果仓库已存在，则忽略此值。由于静态 Trackio 仪表板直接从浏览器读取快照数据，因此不支持 sdk="static"。
force (bool，可选，默认为 False) — 如果为 True，则在不提示确认的情况下覆盖现有数据库。如果为 False，则在覆盖现有数据库之前提示用户。
run_in_background (bool，可选，默认为 False) — 如果为 True，Space 的创建和数据库上传将在后台线程中运行。如果为 False，所有步骤将同步运行。
sdk (str，optional，默认为 “gradio”) — 要部署的 Space 类型。“gradio” 部署带有实时服务器的 Gradio Space。“static” 冻结 Space：部署一个从 HF Bucket 读取的静态 Space（无需服务器）。
dataset_id (str, 可选) — 已弃用：将 trackio 数据持久化到 Hugging Face Dataset 的功能将在 trackio 的后续版本中移除。请改用 bucket_id（一个 Hugging Face Bucket）。
bucket_id (str, 可选) — 要同步到的 HF Bucket 的 ID。默认情况下，会根据 space_id 自动生成一个 bucket。

返回值

str

已同步项目的 Space ID。

将本地 Trackio 项目的数据库同步到 Hugging Face Space。如果该 Space 不存在，将会自动创建。本地数据永远不会被删除。

冻结：传入 sdk="static" 会部署一个由 HF Bucket 支持的静态 Space（只读仪表盘，无 Gradio 服务器）。之后你可以再次同步同一项目以刷新该静态 Space。如果你只想对现有的 Gradio Space 进行一次性快照，请改用 freeze()。

freeze

trackio.freeze

( space_id: strproject: strnew_space_id: str | None = Noneprivate: bool | None = Nonebucket_id: str | None = Nonefrontend_dir: str | pathlib.Path | None = None ) → str

参数

space_id (str) — 源 Gradio Space 的 ID（例如 "username/my-space"，或一个简短的仓库名称，其中登录的命名空间会被推断，如 init()）。必须是一个在 /data 处挂载了 bucket 的 Gradio Space。
project (str) — 要包含在冻结 Space 中的数据所属项目的名称。
new_space_id (str, 可选) — 新静态 Space 的 ID。如果未提供，则默认为 "{space_id}_static"。
private (bool，可选) — 不支持。冻结的静态仪表板直接从浏览器读取快照数据，因此目标快照必须是公开的。
bucket_id (str, 可选) — 用于新静态 Space 数据存储的 HF Bucket ID。如果未提供，则会根据新的 Space ID 自动生成一个。

返回值

str

新创建的静态 Space 的 Space ID。

创建一个包含指定项目数据只读快照的新静态 Hugging Face Space。数据在冻结时从源 Gradio Space 关联的存储桶中读取。原始 Space 不会被修改，且新的静态 Space 不会自动反映冻结完成后上传到原始 Gradio Space 的指标。

delete_project

trackio.delete_project

( project: strforce: bool = False ) → bool

参数

project (str) — 要删除的项目名称。
force (bool，可选，默认为 False) — 如果为 True，则直接删除项目，不提示确认。如果为 False，则在删除前提示用户确认。

返回值

bool

如果项目已删除，则返回 True，否则返回 False。

通过删除其本地 SQLite 数据库来删除项目。

import_csv

trackio.import_csv

( csv_path: str | pathlib.Pathproject: strname: str | None = Nonespace_id: str | None = Nonedataset_id: str | None = Noneprivate: bool | None = Noneforce: bool = False )

参数

csv_path (str 或 Path) — 要导入的 CSV 文件的 str 或 Path。
project (str) — 要导入 CSV 文件的项目名称。不能是已存在的项目。
name (str, 可选) — 要导入 CSV 文件的 Run 的名称。如果未提供，将生成一个默认名称。
name (str, 可选) — 运行的名称（如果未提供，将生成一个默认名称）。
space_id (str, 可选) — 如果提供，项目将记录到 Hugging Face Space 而非本地目录。应为完整的 Space 名称，如 "username/reponame" 或 "orgname/reponame"，或者仅为 "reponame"，此时 Space 将在当前登录的 Hugging Face 用户的命名空间中创建。如果该 Space 不存在，它将自动创建。如果该 Space 已存在，项目将记录到其中。
dataset_id (str, 可选) — 已弃用：将 trackio 数据持久化到 Hugging Face Dataset 的功能将在 trackio 的后续版本中移除。请改用 bucket_id（一个 Hugging Face Bucket）。
private (bool，可选) — 是否将 Space 设为私有。如果为 None（默认值），除非组织的默认设置为私有，否则仓库将是公开的。如果仓库已存在，则忽略此值。

将 CSV 文件导入 Trackio 项目。该 CSV 文件必须包含 "step" 列，可选包含 "timestamp" 列，其余所有列均被视为指标。文件还应包含带有列名的表头行。

TODO：调用 init() 并返回一个 Run 对象，以便用户能够继续向其记录指标。

import_tf_events

trackio.import_tf_events

( log_dir: str | pathlib.Pathproject: strname: str | None = Nonespace_id: str | None = Nonedataset_id: str | None = Noneprivate: bool | None = Noneforce: bool = False )

参数

log_dir (str 或 Path) — 包含 TensorFlow Events 文件的目录的 str 或 Path。
project (str) — 要导入 TensorFlow Events 文件的项目名称。不能是已存在的项目。
name (str, 可选) — 运行（runs）的名称前缀（如果未提供，将使用目录名称）。每个子目录都会创建一个独立的运行。
space_id (str, 可选) — 如果提供，项目将记录到 Hugging Face Space 而非本地目录。应为完整的 Space 名称，如 "username/reponame" 或 "orgname/reponame"，或者仅为 "reponame"，此时 Space 将在当前登录的 Hugging Face 用户的命名空间中创建。如果该 Space 不存在，它将自动创建。如果该 Space 已存在，项目将记录到其中。
dataset_id (str, 可选) — 已弃用：将 trackio 数据持久化到 Hugging Face Dataset 的功能将在 trackio 的后续版本中移除。请改用 bucket_id（一个 Hugging Face Bucket）。
private (bool，可选) — 是否将 Space 设为私有。如果为 None（默认值），除非组织的默认设置为私有，否则仓库将是公开的。如果仓库已存在，则忽略此值。

从目录导入 TensorFlow Events 文件到 Trackio 项目中。日志目录中的每个子目录都将作为独立的运行导入。

保存

trackio.save

( glob_str: str | pathlib.Pathproject: str | None = None ) → str

参数

glob_str (str 或 Path) — 要保存的文件路径或 glob 模式。可以是单个文件，也可以是匹配多个文件的模式（例如 "*.py"、"models/**/*.pth"）。
project (str, 可选) — 要保存文件的项目名称。如果未提供，则使用 trackio.init() 中的当前项目。如果未初始化任何项目，则引发错误。

返回值

str

文件保存的路径（项目的文件目录）。

将文件保存到项目（不关联到特定的运行）。如果 Trackio 在本地运行，文件将被复制到项目的文件目录中。如果 Trackio 在 Space 中运行，文件将被上传到 Space 的文件目录中。

示例：

import trackio

trackio.init(project="my-project")
trackio.save("config.yaml")
trackio.save("models/*.pth")

工件

类 trackio.Artifact

( name: strtype: strdescription: str | None = Nonemetadata: dict | None = None )

参数

name (str) — 工件名称，在项目内唯一。必须匹配 ^[A-Za-z0-9._-]+$（字母、数字、点、下划线、连字符）。
type (str) — 自由格式类别，例如 "model" 或 "dataset"，用于对工件进行分组。
description (str, 可选) — 该工件的人类可读描述。
metadata (dict, 可选) — 与版本一起存储的任意可 JSON 序列化的元数据。

附加到项目的带版本和名称的文件及引用捆绑包。

构建一个 Artifact，使用 add_file / add_dir（将字节暂存到内容寻址存储中）或 add_reference（记录外部 URI，不复制任何字节）向其添加文件，然后通过 trackio.log_artifact 将其持久化。记录操作会冻结该 artifact，并填充其只读的 version、aliases、size 和 manifest。

add_dir

( local_dir: str | pathlib.Pathname: str | None = None )

参数

local_dir (str 或 Path) — 指向现有目录的路径，该目录中的文件将被添加。
name (str, 可选) — 所添加文件的逻辑路径前缀。默认无前缀，因此文件将保留相对于 local_dir 的路径。

递归地暂存目录下的所有常规文件。

符号链接会被跳过。

add_file

( local_path: str | pathlib.Pathname: str | None = None )

参数

local_path (str 或 Path) — 要添加的现有常规文件的路径。
name (str, 可选) — 文件在制品内部存储的逻辑路径。默认为文件的基本名称。

将单个文件暂存以包含在制品中。

add_reference

( uri: strname: str | None = Nonechecksum: bool = Truemax_objects: int | None = None )

参数

uri (str) — 所引用数据的位置，需进行百分号编码（使用 pathlib.Path.as_uri() 构建本地 URI）。file://、http(s):// 和 hf:// 会被原生解析并获取；其他任何协议（s3://、gs://、Azure blob URL 等）都需要通过 trackio.register_reference_handler 注册自定义的 ReferenceHandler——请参阅 artifacts 文档以获取完整示例——否则将引发异常。
name (str, 可选) — 引用所存储的逻辑路径。默认为 uri 的最后一段；对于展开的前缀（以 / 结尾），它是每个对象的相对路径所嵌套的前缀。
checksum (bool，可选，默认为 True) — 当为 True 时，会探测源以推导其大小和校验和（并展开目录/前缀）：file:// 通过流式哈希计算 sha256，hf:// 使用其 LFS sha256 或 git blob id，而 http(s):// 则使用服务器的 ETag。此操作可能会读取文件系统或发起网络请求。如果无法为远程源获取校验和（例如没有 ETag），则直接使用 URI 本身作为 digest 并发出警告。如果本地 file:// 路径不存在，则会引发异常。传入 checksum=False 可完全跳过远程探测。
max_objects (int, 可选) — 目录/前缀展开为对象的数量上限（默认值为 10,000）；超出该值时会引发异常。

暂存对外部数据的引用，而不复制任何字节。

与 add_file/add_dir 不同，引用记录的是数据的 URI（在可用时还包括大小和校验和），而不会将字节暂存到内容寻址存储中。这是针对大型或已持久化存储、且不应被重复的数据集进行版本控制和血缘追踪的方式。

表示目录的 URI（file://、hf:// 或由自定义处理器展开的前缀）会展开为每个对象一个条目，上限为 max_objects。引用字节永远不会上传到 Space 或存储桶。

URI 会按原样存储在工件清单中，而清单可能会同步到共享的 Hugging Face Dataset——因此，出于安全考虑，签名 URI 会触发警告；请优先使用对象的规范无签名 URI（例如 s3://bucket/key）。

下载

( root: str | pathlib.Path | None = None )

参数

root (str 或 Path，可选) — 用于写入文件的目录。默认值为 ./.trackio/artifact-downloads/<project>/<name>_v<version>/，该路径以项目为键，确保来自不同项目的同名工件不会发生冲突；同时以解析后的版本为键，确保像 latest 这样会移动的别名不会遗留来自先前版本的过期文件。

将工件的文件物化到本地目录中。

文件会从 Trackio 的内容寻址缓存中复制（如果本地缺失，则从远程获取），因此重复调用成本低且是幂等的。

通过 add_reference 添加的引用条目也会在此处获取：每个引用 URI 处的对象都会被下载到目录中（对于 http(s):// 使用捆绑的 httpx2，对于 hf:// 使用 huggingface_hub，对于其他任何方案则使用已注册的自定义 ReferenceHandler）。每个对象都会以原子方式写入，且调用是幂等的。由于引用摘要是不透明的（即提供方的 ETag 或 URI 本身），因此假定已存在的文件是最新的，不会针对源进行重新验证；而对于重新探测的校验和与记录的校验和不再匹配的源，仍会照常下载并给出警告。下载过程可能会传输大量数据；若要处理这些 URI 而不进行下载，请改为从 references 属性或 get_entry_uri 中读取。如果源缺失、服务器无法访问，或者该方案没有注册的处理程序，则会引发异常。

get_entry_uri

( name: str )

返回逻辑路径 name 处引用条目所记录的 URI，如果不存在该名称的引用条目，则返回 None。

链接

( target_path: straliases: list[str] | None = Nonebucket_id: str | None = None )

参数

target_path (str) — 要链接到的集合，格式为 "registry-<registry>/<collection>"。注册表必须已经存在。
aliases (list[str]，可选) — 放置在关联版本上的别名。latest 由系统自动管理；传入该值不会产生任何效果。
bucket_id (str, 可选) — 用于存放注册表的存储桶，例如 "my-org/models-registry"。对于本地注册表，请省略此参数；如果设置了 TRACKIO_REGISTRY_BUCKET_ID，则默认使用该值。

将此工件版本链接到注册表集合中。

链接是指向此版本的指针：不会复制任何文件。有关完整语义（集合版本控制、别名以及返回的链接工件），请参阅 Run.link_artifact。

该工件必须已经记录或获取；与 Run.link_artifact 不同，此操作不会为您记录一个草稿工件，且该链接不记录任何发布运行。从 Space 或自托管服务器获取的工件只能链接到基于存储桶的注册表，因为本地注册表无法从其字节所在位置访问。

unlink

( )

移除此注册表链接。

请对 link 或 Run.link_artifact 返回的关联工件调用此方法，而不是对源工件版本调用。源工件及其文件保持不变；仅移除集合成员资格。指向该链接的别名会随之移除，且集合版本号永远不会被重用。如果该版本持有 latest，则该别名将移至剩余的最高版本。

等待

( timeout: int | None = None )

无操作：trackio 同步记录工件，因此在 log_artifact 返回时，工件已经提交。

注册表

类 trackio.Registry

( name: strbucket_id: str | None = None )

参数

name (str) — 注册表名称，例如 "models"。必须匹配 ^[A-Za-z0-9_-]+$ （字母、数字、下划线、连字符）。
bucket_id (str, 可选) — 存放注册表的 Hugging Face 存储桶，例如 "my-org/models-registry"。如果使用本地注册表，则省略此项。如果设置了 TRACKIO_REGISTRY_BUCKET_ID，则默认使用该值。

一个工件注册表的句柄。

注册表是一个共享的制品版本目录，按集合进行组织。您使用 Run.link_artifact 向其中发布制品，并通过移动诸如 "staging" 或 "production" 之类的别名来提升版本。有关完整说明，请参阅注册表指南。

您无需自行构建 Registry。请使用 trackio.Api().create_registry(name) 创建注册表，或使用 trackio.Api().registry(name) 获取现有注册表；两者均返回此句柄。

示例：

import trackio

registry = trackio.Api().create_registry("models")
registry.create_collection(
    "my-model", artifact_type="model", description="My favorite model"
)

run = trackio.init(project="my-experiments")
artifact = trackio.log_artifact("model.pt", name="resnet", type="model")
run.link_artifact(artifact, "registry-models/my-model", aliases=["staging"])
trackio.finish()

registry.collection("my-model").links

集合

( name: str )

描述一个集合。

如果注册表或集合不存在，则返回 None。

集合

( )

列出注册表中的集合，包括链接。

如果注册表不存在，则返回一个空列表。

create_collection

( name: strartifact_type: strdescription: str | None = None )

参数

name (str) — 集合名称，在注册表中唯一。必须匹配 ^[A-Za-z0-9._-]+$。
artifact_type (str) — 该集合接受的工件类型，例如 "model" 或 "dataset"。类型在创建时固定；链接不同类型的工件会引发异常。
description (str, 可选) — 集合的人类可读描述。

在此注册表中创建一个集合。

集合也会在首次链接时自动创建，因此此功能主要用于预先设置描述。如果集合已存在，则会按原样返回，并应用非 None 的 description。

事件

( )

返回注册表的审计日志，最早的事件排在最前面。

每个事件都有一个 id、一个 ts 时间戳、一个 kind（"create"、"link"、"promote"、"update" 或 "unlink"）以及一个描述变更的 payload。没有 collection 键的 create payload 记录的是注册表本身的创建。

集合

类 trackio.Collection

( name: strtype: strdescription: str | Nonecreated_at: strnum_links: intlatest_version: int | Nonelinks: list[dict] )

某个注册表集合的只读快照。

由 Registry.create_collection、Registry.collection 和 Registry.collections 返回。

图像

类 trackio.TrackioImage

( value: str | pathlib.Path | numpy.ndarray | PIL.Image.Imagecaption: str | None = None )

参数

value (str、Path、numpy.ndarray 或 PIL.Image，可选) — 图像的路径、PIL Image 或形状为 (height, width, channels) 的 numpy 数组。如果是 numpy 数组，其类型应为 np.uint8，且 RGB 值范围在 [0, 255] 之间。
caption (str, 可选) — 图像的字符串说明。

初始化一个 Image 对象。

示例：

import trackio
import numpy as np
from PIL import Image

# Create an image from numpy array
image_data = np.random.randint(0, 255, (64, 64, 3), dtype=np.uint8)
image = trackio.Image(image_data, caption="Random image")
trackio.log({"my_image": image})

# Create an image from PIL Image
pil_image = Image.new('RGB', (100, 100), color='red')
image = trackio.Image(pil_image, caption="Red square")
trackio.log({"red_image": image})

# Create an image from file path
image = trackio.Image("path/to/image.jpg", caption="Photo from file")
trackio.log({"file_image": image})

视频

类 trackio.TrackioVideo

( value: str | pathlib.Path | numpy.ndarraycaption: str | None = Nonefps: int | None = Noneformat: typing.Optional[typing.Literal['gif', 'mp4', 'webm']] = None )

参数

value (str、Path 或 numpy.ndarray，可选) — 视频文件的路径，或一个 numpy 数组。如果是 numpy 数组，其类型应为 np.uint8，RGB 值范围为 [0, 255]。其形状应为 (frames, channels, height, width) 或 (batch, frames, channels, height, width)。对于后者，视频将被平铺成一个网格。
caption (str, 可选) — 视频的字符串说明。
fps (int, 可选) — 视频的每秒帧数。仅当值为 ndarray 时使用。默认值为 24。
format (Literal["gif", "mp4", "webm"], 可选) — 视频格式（“gif”、“mp4”或“webm”）。仅当值为 ndarray 时使用。默认为“gif”。

初始化一个 Video 对象。

示例：

import trackio
import numpy as np

# Create a simple video from numpy array
frames = np.random.randint(0, 255, (10, 3, 64, 64), dtype=np.uint8)
video = trackio.Video(frames, caption="Random video", fps=30)

# Create a batch of videos
batch_frames = np.random.randint(0, 255, (3, 10, 3, 64, 64), dtype=np.uint8)
batch_video = trackio.Video(batch_frames, caption="Batch of videos", fps=15)

# Create video from file path
video = trackio.Video("path/to/video.mp4", caption="Video from file")

write_video

( file_path: str | pathlib.Pathvideo: ndarrayfps: floatcodec: typing.Literal['h264', 'vp9', 'gif'] )

仅支持 RGB uint8，形状为 (F, H, W, 3)。

音频

类 trackio.TrackioAudio

( value: str | pathlib.Path | numpy.ndarraycaption: str | None = Nonesample_rate: int | None = Noneformat: typing.Optional[typing.Literal['wav', 'mp3']] = None )

参数

value (str、Path 或 numpy.ndarray，可选) — 音频文件的路径，或一个 numpy 数组。对于单声道，数组的形状应为 (samples,)；对于立体声，应为 (samples, 2)。浮点数组将进行峰值归一化并转换为 16 位 PCM；整型数组将在需要时转换为 16 位 PCM。
caption (str, 可选) — 音频的字符串说明。
sample_rate (int, 可选) — 采样率，单位为 Hz。当 value 为 numpy 数组时必填。
format (Literal["wav", "mp3"], 可选) — 当 value 为 numpy 数组时使用的音频格式。默认为 “wav”。

初始化一个 Audio 对象。

示例：

import trackio
import numpy as np

# Generate a 1-second 440 Hz sine wave (mono)
sr = 16000
t = np.linspace(0, 1, sr, endpoint=False)
wave = 0.2 * np.sin(2 * np.pi * 440 * t)
audio = trackio.Audio(wave, caption="A4 sine", sample_rate=sr, format="wav")
trackio.log({"tone": audio})

# Stereo from numpy array (shape: samples, 2)
stereo = np.stack([wave, wave], axis=1)
audio = trackio.Audio(stereo, caption="Stereo", sample_rate=sr, format="mp3")
trackio.log({"stereo": audio})

# From an existing file
audio = trackio.Audio("path/to/audio.wav", caption="From file")
trackio.log({"file_audio": audio})

ensure_int16_pcm

( data: ndarray )

将输入音频数组转换为连续的 int16 PCM。对浮点输入应用峰值归一化。

Object3D

类 trackio.TrackioObject3D

( path_or_array: str | pathlib.Path | numpy.ndarraycaption: str | None = None )

Html

类 trackio.TrackioHtml

( data: typing.Anyinject: bool = Truedata_is_not_path: bool = Falsecaption: str | None = None )

参数

data (str、Path、类文件对象、Plotly 图形或 Matplotlib 图形) — 原始 HTML、指向 .html 文件的路径、类文件对象，或 Plotly 或 Matplotlib 图形。
inject (bool, 可选) — 将 HTML 片段包裹在带样式的文档中。默认值为 True。
data_is_not_path (bool, 可选) — 为兼容 wandb.Html 而接受，但会被忽略。
caption (str, 可选) — 用于 HTML 的字符串标题。

初始化一个 Html 对象。

示例：

import trackio

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

# Raw HTML
trackio.log({"report": trackio.Html("<h1>Results</h1>")})

# Plotly figure
import plotly.express as px

fig = px.line(x=[1, 2, 3], y=[4, 5, 6])
trackio.log({"plot": trackio.Html(fig)})

# Matplotlib figure
import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4])
trackio.log({"chart": trackio.Html(plt)})

表格

类 trackio.Table

( columns: list[str] | None = Nonedata: list[list[typing.Any]] | None = Nonedataframe: typing.Optional[typing.Any] = Nonerows: list[list[typing.Any]] | None = Noneoptional: bool | list[bool] = Trueallow_mixed_types: bool = Falselog_mode: typing.Optional[typing.Literal['IMMUTABLE', 'MUTABLE', 'INCREMENTAL']] = 'IMMUTABLE' )

参数

columns (list[str]，可选) — 表格中列的名称。如果提供了 data，则此项可选。如果提供了 dataframe，则不应提供此项。目前被忽略。
data (list[list[Any]], 可选) — 二维行优先值数组。每个值可以是数字、字符串（按 Markdown 处理，过长时会被截断），或 Trackio.Image 或 Trackio.Image 对象列表。
dataframe (pandas.DataFrame，可选) — 用于创建表的 DataFrame。设置后，data 和 columns 参数将被忽略。
rows (list[list[Any]]，可选) — 目前被忽略。
optional (bool 或 list[bool]，可选，默认为 True) — 目前被忽略。
allow_mixed_types (bool，可选，默认为 False) — 目前被忽略。
log_mode — (Literal["IMMUTABLE", "MUTABLE", "INCREMENTAL"] 或 None，可选，默认为 "IMMUTABLE")：目前被忽略。

初始化一个 Table 对象。

表格可用于记录包括图像、数字和文本在内的表格数据。

to_display_format

( table_data: list[dict] ) → list[dict]

参数

table_data (list[dict]) — 表示表格行的字典列表（来自存储的 _value）。

返回值

list[dict]

包含图像（已转换为 Markdown 语法）的表格数据，长文本已截断。

将存储的表格数据转换为用于 UI 渲染的显示格式。

注意：此处不使用 self.data 属性，而是使用 table_data 参数，即 UI 接收到的数据。

跟踪

类 trackio.Trace

( messages: list[dict[str, Any]]metadata: dict | None = Nonespans: list[dict[str, Any]] | None = None )

参数

messages (list[dict[str, Any]]) — OpenAI 风格的 messages，例如 {"role": "user", "content": "..."}。 Assistant 消息可以包含 tool_calls，工具结果可以包含 tool_call_id；当未提供 spans 时，dashboard 会将它们配对为工具操作。
metadata (dict, 可选) — 跟踪级别的元数据，例如 session_id 或 environment。当 span 未提供这些值时，仪表板会使用键 status、duration_ms、latency_ms 和 cost_usd 作为跟踪级别的回退值。
spans (list[dict[str, Any]]，可选) — 描述生成响应的执行跨度。每个跨度都是一个字典，以 id、name 和 kind（"span"、"generation" 或 "tool"）为键，并包含可选的 parent_id、start_time、end_time、 duration_ms、status、error、input、output、model、usage、 cost_usd 和 metadata。

初始化一个 Trace 对象。

Traces 捕获对话式或智能体式请求：OpenAI 风格的消息、可选的元数据以及可选的执行 span。Span 是描述模型生成、工具调用或其他操作的字典。消息、元数据或 span 内部嵌套的 Trackio 媒体对象会随 trace 一起持久化并序列化。

直方图

类 trackio.Histogram

( sequence: typing.Union[numpy.ndarray, typing.Sequence[float], typing.Sequence[int], NoneType] = Nonenp_histogram: tuple | None = Nonenum_bins: int = 64 )

参数

sequence (np.ndarray 或 Sequence[float] 或 Sequence[int]，可选) — 用于创建直方图的数值序列。
np_histogram (tuple，可选) — 预计算的 NumPy 直方图，表示为 (hist, bins) 元组。
num_bins (int, 可选, 默认为 64) — 直方图的 bin 数量（最大为 512）。

Trackio 的直方图数据类型，与 wandb.Histogram 兼容。

示例：

import trackio
import numpy as np

# Create histogram from sequence
data = np.random.randn(1000)
trackio.log({"distribution": trackio.Histogram(data)})

# Create histogram from numpy histogram
hist, bins = np.histogram(data, bins=30)
trackio.log({"distribution": trackio.Histogram(np_histogram=(hist, bins))})

# Specify custom number of bins
trackio.log({"distribution": trackio.Histogram(data, num_bins=50)})

Update on GitHub

←使用 RapidFire AI 运行