Hugging Face's logo

Trackio documentation

环境变量

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

环境变量

Trackio 使用环境变量来配置其行为的各个方面，尤其是针对部署到 Hugging Face Spaces 和数据持久化的场景。本指南涵盖了主要的环境变量及其用法。

核心环境变量

TRACKIO_DIR

指定用于存储 Trackio 数据的自定义目录。默认情况下，Trackio 会将数据存储在 ~/.cache/huggingface/trackio/ 中。

export TRACKIO_DIR="/path/to/trackio/data"

注意：只要 Trackio 未在启用持久化存储的 Space 中运行，此环境变量即生效。如果 Trackio 正在启用持久化存储的 Space 中运行（通过 PERSISTANT_STORAGE_ENABLED 环境变量检测），则 Trackio 数据将存储在 /data/trackio 中。

TRACKIO_SERVER_URL

自托管 Trackio 服务器的基础 URL（http:// 或 https://）。您可以在查询字符串中包含 write_token（如 trackio.show() 中的 full_url），或者保持 URL 不变，改为设置 TRACKIO_WRITE_TOKEN。设置后，trackio.init() 会将指标发送到该服务器。等效于向 trackio.init() 传递 server_url=。

优先级：如果同时设置了 TRACKIO_SPACE_ID（或在代码中传入了 space_id），则会使用 Hugging Face Space，并忽略 TRACKIO_SERVER_URL。当同时传入 space_id 和 server_url 时，规则相同：space_id 优先。

请参阅 自托管服务器。

export TRACKIO_SERVER_URL="http://127.0.0.1:7860"
export TRACKIO_WRITE_TOKEN="YOUR_TOKEN"

TRACKIO_WRITE_TOKEN

自托管 Trackio 服务器的仪表盘 write token（与写入访问 URL 中的 write_token 查询参数值相同）。在 Trackio 服务器上设置此值时，将使用该值作为服务器的写入令牌，而不是在启动时生成随机令牌。在 Trackio 客户端上设置此值时，当 TRACKIO_SERVER_URL 或 server_url 为不带查询参数的基础 URL 时，请使用此值。客户端会在每个请求中发送此令牌（例如作为 X-Trackio-Write-Token 请求头），以便在未运行于 Hugging Face Spaces 上时，对指标摄取和上传进行身份验证。

TRACKIO_FRONTEND_DIR

Trackio 自定义静态前端目录的路径。该目录必须包含 index.html。

设置后，Trackio 将使用该前端来运行 trackio.show() 以及 trackio.sync() 和 trackio.freeze() 等部署流程，除非显式传入了 frontend_dir / --frontend 参数。

export TRACKIO_FRONTEND_DIR="/path/to/my-trackio-frontend"

如果配置的目录无效，Trackio 将忽略该目录并回退到内置的前端选择逻辑。自动复制起始模板的行为仅在显式的 frontend_dir / --frontend 参数指向缺失或空目录时才会生效。

TRACKIO_LOGO_LIGHT_URL 和 TRACKIO_LOGO_DARK_URL

自定义在 Trackio 仪表板中为浅色和深色主题显示的徽标。您可以提供自定义徽标的 URL。请注意，应同时提供这两个环境变量；否则，对于未提供的任何变量，将使用 Trackio 的默认值。

export TRACKIO_LOGO_LIGHT_URL="https://example.com/logo-light.png"
export TRACKIO_LOGO_DARK_URL="https://example.com/logo-dark.png"

注意：对于远程 Trackio Spaces，这些环境变量仅在通过 trackio.init(space_id=...) 首次创建 Space 时生效。若要更改现有 Space 的徽标，请直接在 Hugging Face Space 设置中更新 Space 变量。

TRACKIO_PLOT_ORDER

控制 Trackio 仪表板中图表和指标组的排序。该值应为逗号分隔的指标模式列表，用于指定期望的顺序。分组会被保留——如果首先指定了 train/loss，则所有其他 train/* 指标将一起显示在 train 组中，且 train/loss 在该组内排在首位。

如果某个模式未匹配到任何指标，它将被直接忽略，而不会引发错误。

export TRACKIO_PLOT_ORDER="train/loss,val/loss"


**Pattern Matching:**
- **Exact matches**: `train/loss` matches exactly `train/loss`
- **Group wildcards**: `train/*` matches all metrics starting with `train/`
- **Partial wildcards**: `*gpu*` matches any metric containing "gpu"

**Behavior:**
- Metrics are grouped first (e.g., all `train/*` metrics stay together)
- Within each group, metrics are ordered according to the specified patterns
- Groups appear in the order of their first matching pattern
- Unspecified metrics appear in alphabetical order after specified ones

> **Note:** For remote Trackio Spaces, this environment variable is only applied when the Space is first created via `trackio.init(space_id=...)`. To change the plot order on an existing Space, update the `TRACKIO_PLOT_ORDER` Space variable directly in the Hugging Face Space settings.

### `TRACKIO_THEME`

Sets the theme for the Trackio dashboard. Can be a built-in Gradio theme name or a theme from the Hugging Face Hub.

```bash
# Built-in themes
export TRACKIO_THEME="soft"
export TRACKIO_THEME="citrus"
export TRACKIO_THEME="monochrome"

# Themes from the Hub
export TRACKIO_THEME="gstaff/xkcd"
export TRACKIO_THEME="ParityError/Anime"

注意：对于远程 Trackio Spaces，此环境变量仅在通过 trackio.init(space_id=...) 首次创建 Space 时生效。若要更改现有 Space 的主题，请直接在 Hugging Face Space 设置中更新 TRACKIO_THEME Space 变量。

TRACKIO_COLOR_PALETTE

自定义 Trackio 仪表盘中用于绘制折线的调色板。该值应为以逗号分隔的十六进制颜色代码列表。在绘制多个运行结果时，这些颜色将按顺序循环使用。

export TRACKIO_COLOR_PALETTE="#FF0000,#00FF00,#0000FF,#FFFF00,#FF00FF,#00FFFF"

默认调色板： #A8769B, #E89957, #3B82F6, #10B981, #EF4444, #8B5CF6, #14B8A6, #F59E0B, #EC4899, #06B6D4

TRACKIO_TABLE_TRUNCATE_LENGTH

控制表格单元格中字符串值在截断前显示的最大长度。当单元格值超过此长度时，将被截断并显示一个可展开的元素，以便查看完整文本。默认值为 250 个字符。

export TRACKIO_TABLE_TRUNCATE_LENGTH="500"

TRACKIO_STORAGE_MODE

控制 Trackio 如何在本地持久化数据。允许的值：auto（默认值）、sqlite、jsonl。

  • sqlite：训练进程直接写入项目的 SQLite 数据库（历史行为）。
  • jsonl：训练进程将仅追加的 JSONL 片段写入 TRACKIO_DIR/inbox/，每个进程对应一个文件；仪表盘服务器（trackio show）会将它们导入 SQLite。这完全避免了 SQLite 的并发写入问题，从而确保 Trackio 在 SQLite 的锁机制和 mmap 语义不可靠的网络文件系统（NFS、Lustre、FSx、GPFS、WekaFS、CephFS 等）上是安全的。
  • auto：当检测到 TRACKIO_DIR 位于网络文件系统上时（仅限 Linux），自动选择 jsonl，否则选择 sqlite。
export TRACKIO_STORAGE_MODE="jsonl"

TRACKIO_INBOX_POLL_INTERVAL

仪表盘服务器和 Trackio Spaces 检查新 JSONL 片段以进行导入的频率（以秒为单位），包括来自本地收件箱目录和 Hugging Face Bucket 收件箱的片段。默认值为 15；低于 5 的值将被限制为 5。

export TRACKIO_INBOX_POLL_INTERVAL="30"

TRACKIO_SQLITE_*（高级）

覆盖 Trackio 在其 SQLite 连接上设置的 PRAGMAs。这些设置主要在不寻常的文件系统上有用；无效的值将被忽略。

  • TRACKIO_SQLITE_JOURNAL_MODE：取值为 wal、delete、truncate、persist、memory 或 off 之一。本地默认值为 wal，在 Spaces 上默认值为 delete。
  • TRACKIO_SQLITE_MMAP_SIZE：内存映射 I/O 的大小（以字节为单位）。默认值为 0（禁用），因为在网络文件系统上，内存映射读取是触发 SIGBUS 崩溃的直接原因，且对 Trackio 的工作负载几乎没有收益。
  • TRACKIO_SQLITE_SYNCHRONOUS：取值为 off、normal、full 或 extra 之一。默认值为 normal。
  • TRACKIO_SQLITE_LOCKING_MODE：取值为 normal 或 exclusive。在 Spaces 上默认为 exclusive，在其他环境中默认为 normal。
  • TRACKIO_SQLITE_TEMP_STORE：取值为 default、file 或 memory 之一。默认值为 memory。

推荐的集群配置：如果您的主目录或缓存目录位于共享文件系统（/fsx、Lustre、NFS、GPFS、WekaFS 等）上，请将 TRACKIO_DIR 指向节点本地磁盘（例如 /tmp 或 $SLURM_TMPDIR），或者依赖 TRACKIO_STORAGE_MODE=auto，它会自动检测网络文件系统并切换到 JSONL 片段日志记录。如果必须在共享文件系统上直接写入 SQLite，请设置：

export TRACKIO_SQLITE_JOURNAL_MODE="delete"
export TRACKIO_SQLITE_MMAP_SIZE="0"

TRACKIO_WEBHOOK_URL

设置用于警报的全局 webhook URL。设置后，每次调用 trackio.alert() 都会将警报负载 POST 到该 URL。原生支持 Slack 和 Discord 的 webhook URL（负载会自动格式化）。可以通过 webhook_url 参数按警报或按运行进行覆盖。

export TRACKIO_WEBHOOK_URL="https://hooks.slack.com/services/T.../B.../xxx"

有关更多详细信息，请参阅警报指南。

TRACKIO_WEBHOOK_MIN_LEVEL

设置应发送到 Webhook 的最低告警级别。低于此级别的告警仍会打印到终端、存储在数据库中并显示在仪表板上，但不会发送到 Webhook 目标。

允许的值：info、warn、error。

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

使用 warn 时，仅 WARN 和 ERROR 级别的警报会发送到 webhook URL。

TRACKIO_CAPTURE_CONSOLE

当设置为 1 或 true 时，Trackio 会捕获运行期间写入 stdout 和 stderr 的所有内容，并在仪表板的运行页面上显示。这相当于向 trackio.init() 传递 capture_console=True；显式指定的 capture_console 参数具有更高优先级。

export TRACKIO_CAPTURE_CONSOLE=1

有关更多详细信息，请参阅 捕获控制台输出和启动命令。

TRACKIO_HANDLE_SIGTERM

当设置为 1 或 true 时，trackio.init() 会安装一个 SIGTERM 处理程序，将该信号转换为正常退出，从而在进程因 Slurm 时间限制、docker stop 或 Kubernetes 驱逐而停止时，完成运行并保存其最后的指标和控制台输出。退出代码保持为 143。该处理程序仅从主线程安装，且仅在未设置其他 SIGTERM 处理程序时生效。默认情况下此功能处于关闭状态，因为它会改变整个进程对 SIGTERM 的响应方式：例如，进程在退出前会等待非守护线程，并且那些链式调用现有处理程序的框架（例如 PyTorch Lightning 的 Slurm 自动重新排队）将选择退出，而不是忽略该信号。

export TRACKIO_HANDLE_SIGTERM=1

TRACKIO_BUCKET_ID

用于在 Hugging Face Space 上运行时持久化 Trackio 数据的 Hugging Face Bucket ID（例如 username/bucketname）。通常，在通过 trackio.init(space_id=...) 或 trackio.sync(...) 创建 Space 时，会自动在 Space 上设置此值；除非显式提供 bucket_id，否则会根据 Space ID 自动生成一个 bucket。

export TRACKIO_BUCKET_ID="username/my-trackio-bucket"

TRACKIO_DATASET_ID（已弃用）

已弃用：将 Trackio 数据持久化到 Hugging Face Dataset（dataset_id / TRACKIO_DATASET_ID）的功能已弃用，并将在 Trackio 的未来版本中移除。请改用 Hugging Face Bucket（bucket_id / TRACKIO_BUCKET_ID）。

Hugging Face 数据集的 ID（例如 username/datasetname），Trackio Space 会通过后台提交调度器将数据同步到该数据集。当在 Space 上设置此参数时，Trackio 会发出弃用警告，但目前仍会继续同步到该数据集。

export TRACKIO_DATASET_ID="username/my-trackio-dataset"

HF_TOKEN

您的 Hugging Face 身份验证令牌。在 Hugging Face 上创建 Spaces 和 Buckets 时必需。从本地机器部署到 Spaces 时，请在本地设置此项。必须对您部署 Trackio 仪表板的命名空间具有 write 权限。

export HF_TOKEN="hf_xxxxxxxxxxxxx"

Gradio 环境变量

由于 Trackio 基于 Gradio 构建，您可以使用 Gradio 的环境变量来控制 Trackio 的行为。以下是一些示例：

GRADIO_SERVER_PORT

指定 Tradio 仪表板启动时使用的端口。默认值为 7860

export GRADIO_SERVER_PORT=8000

GRADIO_SERVER_NAME

定义 Trackio 仪表板服务器的主机名。若要使仪表板可从任意 IP 地址访问，请将其设置为 "0.0.0.0"

export GRADIO_SERVER_NAME="0.0.0.0"

GRADIO_MCP_SERVER

在 Trackio 中启用 MCP（Model Context Protocol）服务器功能。启用后，Trackio 仪表盘将被配置为 MCP 服务器，并且某些功能将作为 MCP 工具暴露出来，供 LLM 使用（例如读取已记录的指标）。

export GRADIO_MCP_SERVER="True"

请参阅 Gradio 使用的更完整的环境变量列表。

Update on GitHub

←ML Agents 使用 Transformers 运行→