Variables de entorno

Trackio utiliza variables de entorno para configurar varios aspectos de su comportamiento, en particular para la implementación en Hugging Face Spaces y la persistencia de datos. Esta guía cubre las principales variables de entorno y su uso.

Variables de entorno principales

TRACKIO_DIR

Especifica un directorio personalizado para almacenar los datos de Trackio. De forma predeterminada, Trackio almacena los datos en ~/.cache/huggingface/trackio/.

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

Nota: Esta variable de entorno se aplica mientras Trackio no se esté ejecutando en un Space con almacenamiento persistente habilitado. Si Trackio se está ejecutando en un Space con almacenamiento persistente habilitado (lo cual se detecta con la variable de entorno PERSISTANT_STORAGE_ENABLED), los datos de Trackio se almacenarán en /data/trackio.

TRACKIO_SERVER_URL

URL base de un servidor de Trackio autoalojado (http:// o https://). Puede incluir write_token en la cadena de consulta (como en la full_url de trackio.show()) o mantener la URL sin parámetros y establecer TRACKIO_WRITE_TOKEN en su lugar. Cuando se establece, trackio.init() envía las métricas a ese servidor. Equivale a pasar server_url= a trackio.init().

Prioridad: Si TRACKIO_SPACE_ID también está definido (o se pasa space_id en el código), se utiliza el Space de Hugging Face y TRACKIO_SERVER_URL se ignora. La misma regla aplica cuando se pasan tanto space_id como server_url: space_id tiene prioridad.

Vea Alojar el servidor usted mismo.

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

TRACKIO_WRITE_TOKEN

El token de escritura del panel de control para un servidor de Trackio autoalojado (el mismo valor que el parámetro de consulta write_token en la URL de acceso de escritura). Cuando se establece en el servidor de Trackio, este valor se utiliza como token de escritura del servidor en lugar de generar un token aleatorio al inicio. Cuando se establece en el cliente de Trackio, úsalo cuando TRACKIO_SERVER_URL o server_url sea una URL base sin parámetros de consulta. El cliente envía este token en cada solicitud (por ejemplo, como la cabecera X-Trackio-Write-Token) para que la ingesta de métricas y las cargas estén autenticadas cuando no se ejecuta en Hugging Face Spaces.

TRACKIO_FRONTEND_DIR

Ruta a un directorio de frontend estático personalizado para Trackio. El directorio debe contener index.html.

Cuando se establece, Trackio utiliza ese frontend para trackio.show() y para los flujos de despliegue como trackio.sync() y trackio.freeze(), a menos que se pase un argumento explícito de frontend_dir / --frontend.

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

Si el directorio configurado no es válido, Trackio lo ignora y recurre a la lógica de selección de frontend integrada. El comportamiento automático de copia de la plantilla inicial solo se aplica cuando un argumento explícito frontend_dir / --frontend apunta a un directorio inexistente o vacío.

TRACKIO_LOGO_LIGHT_URL y TRACKIO_LOGO_DARK_URL

Personaliza los logotipos que se muestran en el panel de Trackio para los temas claro y oscuro. Puedes proporcionar URLs de logotipos personalizados. Ten en cuenta que se deben proporcionar ambas variables de entorno; de lo contrario, se utilizará el valor predeterminado de Trackio para cualquier variable que no se haya proporcionado.

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

Nota: Para los espacios remotos de Trackio, estas variables de entorno solo se aplican cuando el espacio se crea por primera vez mediante trackio.init(space_id=...). Para cambiar los logotipos en un espacio existente, actualice las variables del espacio directamente en la configuración del espacio de Hugging Face.

TRACKIO_PLOT_ORDER

Controla el orden de los gráficos y los grupos de métricas en el panel de Trackio. El valor debe ser una lista de patrones de métricas separados por comas que especifique el orden deseado. Los grupos se conservan: si train/loss se especifica primero, todas las demás métricas de train/* aparecerán juntas en el grupo train, con train/loss apareciendo primero dentro de ese grupo.

Si un patrón no coincide con ninguna métrica, simplemente se ignora sin provocar errores.

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"

Nota: Para los Trackio Spaces remotos, esta variable de entorno solo se aplica cuando el Space se crea por primera vez mediante trackio.init(space_id=...). Para cambiar el tema en un Space existente, actualice la variable de Space TRACKIO_THEME directamente en la configuración del Space de Hugging Face.

TRACKIO_COLOR_PALETTE

Personaliza la paleta de colores utilizada para las líneas de los gráficos en el panel de Trackio. El valor debe ser una lista de códigos de color en hexadecimal separados por comas. Estos colores se alternarán al graficar múltiples ejecuciones.

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

Paleta predeterminada: #A8769B, #E89957, #3B82F6, #10B981, #EF4444, #8B5CF6, #14B8A6, #F59E0B, #EC4899, #06B6D4

TRACKIO_TABLE_TRUNCATE_LENGTH

Controla la longitud máxima de los valores de cadena mostrados en las celdas de la tabla antes de que se trunquen. Cuando el valor de una celda supera esta longitud, se trunca con un elemento expandible que permite ver el texto completo. El valor predeterminado es de 250 caracteres.

export TRACKIO_TABLE_TRUNCATE_LENGTH="500"

TRACKIO_STORAGE_MODE

Controla cómo Trackio persiste los datos localmente. Valores permitidos: auto (predeterminado), sqlite, jsonl.

sqlite: los procesos de entrenamiento escriben directamente en la base de datos SQLite del proyecto (el comportamiento histórico).
jsonl: los procesos de entrenamiento escriben fragmentos JSONL de solo anexión en TRACKIO_DIR/inbox/, un archivo por proceso; el servidor del panel de control (trackio show) los importa en SQLite. Esto evita por completo los escritores concurrentes de SQLite, lo que hace que Trackio sea seguro en sistemas de archivos de red (NFS, Lustre, FSx, GPFS, WekaFS, CephFS, …) donde las semánticas de bloqueo y mmap de SQLite no son fiables.
auto: selecciona jsonl automáticamente cuando se detecta que TRACKIO_DIR está en un sistema de archivos de red (solo Linux), en caso contrario, sqlite.

export TRACKIO_STORAGE_MODE="jsonl"

TRACKIO_INBOX_POLL_INTERVAL

Con qué frecuencia (en segundos) el servidor del panel de control y Trackio Spaces comprueban si hay nuevos fragmentos JSONL para importar, tanto desde el directorio de bandeja de entrada local como desde la bandeja de entrada del Hugging Face Bucket. El valor predeterminado es 15; los valores inferiores a 5 se ajustan a 5.

export TRACKIO_INBOX_POLL_INTERVAL="30"

TRACKIO_SQLITE_* (avanzado)

Sobrescribir los PRAGMAs que Trackio establece en sus conexiones SQLite. Estos son principalmente útiles en sistemas de archivos inusuales; los valores no válidos se ignoran.

TRACKIO_SQLITE_JOURNAL_MODE: uno de wal, delete, truncate, persist, memory, off. El valor predeterminado es wal localmente y delete en Spaces.
TRACKIO_SQLITE_MMAP_SIZE: tamaño de la E/S mapeada en memoria, en bytes. El valor predeterminado es 0 (deshabilitado) en todos los entornos, ya que las lecturas mapeadas en memoria son el detonante directo de los errores SIGBUS en sistemas de archivos de red y aportan poco a la carga de trabajo de Trackio.
TRACKIO_SQLITE_SYNCHRONOUS: uno de off, normal, full, extra. El valor predeterminado es normal.
TRACKIO_SQLITE_LOCKING_MODE: uno de normal, exclusive. El valor predeterminado es exclusive en Spaces y normal en otros entornos.
TRACKIO_SQLITE_TEMP_STORE: uno de default, file, memory. El valor predeterminado es memory.

Configuración de clúster recomendada: si su directorio de inicio o de caché se encuentra en un sistema de archivos compartido (/fsx, Lustre, NFS, GPFS, WekaFS, …), apunte TRACKIO_DIR a un disco local al nodo (p. ej. /tmp o $SLURM_TMPDIR), o confíe en TRACKIO_STORAGE_MODE=auto, que detecta los sistemas de archivos de red y cambia al registro de fragmentos JSONL. Si debe escribir SQLite directamente en un sistema de archivos compartido, establezca:

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

TRACKIO_WEBHOOK_URL

Establece una URL global de webhook para las alertas. Cuando se establece, cada llamada a trackio.alert() enviará la carga de la alerta mediante POST a esta URL. Admite de forma nativa las URLs de webhook de Slack y Discord (las cargas se formatean automáticamente). Se puede sobrescribir por alerta o por ejecución mediante el parámetro webhook_url.

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

Consulte la Guía de alertas para obtener más detalles.

TRACKIO_WEBHOOK_MIN_LEVEL

Establece el nivel mínimo de alerta que debe enviarse a los webhooks. Las alertas por debajo de este nivel aún se imprimen en la terminal, se almacenan en la base de datos y se muestran en el panel de control, pero no se envían a los destinos de webhook.

Valores permitidos: info, warn, error.

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

Con warn, solo se envían alertas de WARN y ERROR a las URLs de webhook.

TRACKIO_CAPTURE_CONSOLE

Cuando se establece en 1 o true, Trackio captura todo lo que se escribe en stdout y stderr durante una ejecución y lo muestra en la página de la ejecución en el panel de control. Es equivalente a pasar capture_console=True a trackio.init(); un argumento explícito de capture_console tiene prioridad.

export TRACKIO_CAPTURE_CONSOLE=1

Consulte Captura de la salida de la consola y el comando de inicio para obtener más detalles.

TRACKIO_HANDLE_SIGTERM

Cuando se establece en 1 o true, trackio.init() instala un manejador de SIGTERM que convierte la señal en una salida normal, de modo que la ejecución se finaliza y sus últimas métricas y la salida de la consola se guardan cuando el proceso se detiene por un límite de tiempo de Slurm, docker stop o una expulsión de Kubernetes. El código de salida permanece en 143. El manejador solo se instala desde el hilo principal y solo cuando no se ha establecido otro manejador de SIGTERM. Está desactivado de forma predeterminada porque cambia cómo responde todo el proceso a SIGTERM: por ejemplo, el proceso espera a los hilos no daemon antes de salir, y los marcos de trabajo que encadenan manejadores existentes (como el auto-requeue de Slurm de PyTorch Lightning) saldrán en lugar de ignorar la señal.

export TRACKIO_HANDLE_SIGTERM=1

TRACKIO_BUCKET_ID

El ID del Bucket de Hugging Face (p. ej. username/bucketname) utilizado para persistir los datos de Trackio al ejecutarlo en un Hugging Face Space. Normalmente, se establece automáticamente en el Space cuando se crea mediante trackio.init(space_id=...) o trackio.sync(...); se genera automáticamente un bucket a partir del ID del Space, a menos que se proporcione un bucket_id explícito.

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

TRACKIO_DATASET_ID (obsoleto)

Obsoleto: Persistir los datos de Trackio en un Dataset de Hugging Face (dataset_id / TRACKIO_DATASET_ID) está obsoleto y se eliminará en una versión futura de Trackio. Utilice un Bucket de Hugging Face en su lugar (bucket_id / TRACKIO_BUCKET_ID).

El ID del Dataset de Hugging Face (p. ej. username/datasetname) al que un Space de Trackio sincroniza sus datos mediante un programador de commits en segundo plano. Cuando se establece en un Space, Trackio emite una advertencia de obsolescencia y, por ahora, continúa sincronizando con el Dataset.

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

HF_TOKEN

Su token de autenticación de Hugging Face. Es obligatorio para crear Spaces y Buckets en Hugging Face. Establezca este valor localmente al desplegar en Spaces desde su máquina. Debe tener permisos de write para el espacio de nombres en el que está desplegando el panel de Trackio.

export HF_TOKEN="hf_xxxxxxxxxxxxx"

Variables de entorno de Gradio

Dado que Trackio se construye sobre Gradio, puedes usar las variables de entorno que utiliza Gradio para controlar el comportamiento de Trackio. Aquí tienes algunos ejemplos:

GRADIO_SERVER_PORT

Especifica el puerto en el que se iniciará el panel de Tradio. El valor predeterminado es 7860

export GRADIO_SERVER_PORT=8000

GRADIO_SERVER_NAME

Define el nombre del host para el servidor del panel de Trackio. Para hacer que el panel sea accesible desde cualquier dirección IP, establezca este valor en "0.0.0.0"

export GRADIO_SERVER_NAME="0.0.0.0"

GRADIO_MCP_SERVER

Habilita la funcionalidad del servidor MCP (Model Context Protocol) en Trackio. Cuando está habilitado, el panel de Trackio se configurará como un servidor MCP y ciertas funciones se expondrán como herramientas MCP que pueden ser utilizadas por LLM (por ejemplo, para leer las métricas registradas).

export GRADIO_MCP_SERVER="True"

Vea esta lista más completa de variables de entorno utilizadas por Gradio.

Update on GitHub