Hugging Face's logo

Trackio documentation

Referencia de la API

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Referencia de la API

Ejecutar

clase 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 )

Parámetros

  • artifact (Artifact) — La versión del artifact a vincular. Debe ser un Artifact que haya sido registrado o recuperado. Para vincular una versión existente específica, recupérala primero con use_artifact("my-model:v3") y vincula el resultado. Un artifact que nunca haya sido registrado se registra primero en el proyecto de esta ejecución.
  • target_path (str) — La colección a la que se vinculará, en el formato "registry-<registry>/<collection>", por ejemplo, "registry-models/my-model". El registro debe existir previamente (consulte trackio.Api().create_registry). La colección se crea en el primer vínculo y adopta el tipo del artefacto; los vínculos posteriores deben coincidir con él.
  • aliases (list[str], opcional) — Alias a colocar en la versión vinculada, p. ej. ["staging"]. Un alias apunta a una versión por colección, por lo que asignar un alias que otra versión posee lo mueve. latest se gestiona automáticamente y siempre sigue a la versión vinculada más reciente; pasarla aquí no tiene efecto.
  • bucket_id (str, opcional) — Bucket de Hugging Face que contiene el registro, p. ej. "my-org/models-registry". Es obligatorio para vincular desde una ejecución que registra en un Space o en un servidor autoalojado. Omítelo para un registro local; por defecto es TRACKIO_REGISTRY_BUCKET_ID si este está establecido.

Vincular una versión de artefacto a una colección de registro.

Un enlace es un puntero a la versión de origen: no se copian archivos. El enlace recibe el siguiente número de versión en la colección (v0, v1, …), independientemente de los números de versión propios del artefacto de origen. Enlazar una versión que ya está en la colección no crea una nueva: se devuelve la versión existente y los aliases que pases siguen moviéndose.

Un registro local registra el enlace junto con los datos de la ejecución, por lo que solo está disponible para las ejecuciones en esta máquina. Pasa bucket_id para publicar en un registro basado en un bucket en su lugar; esa es también la forma en que una ejecución que registra en un Space o en un servidor autoalojado publica, ya que el bucket es accesible desde ambos lados.

use_artifact

< >

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

Resolver un artefacto y registrar esta ejecución como consumidor del mismo.

La especificación es un artefacto del proyecto ("name", "name:vN", "name:alias") o una ubicación del registro ("registry-<registry>/<collection>[:vN|:alias]"), que se resuelve a través de los enlaces de la colección hacia la versión de origen a la que apunta.

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

Parámetros

  • project (str) — El nombre del proyecto (puede ser un proyecto existente para continuar el seguimiento o un proyecto nuevo para comenzar el seguimiento desde cero).
  • name (str, opcional) — El nombre de la ejecución (si no se proporciona, se generará un nombre predeterminado).
  • group (str, opcional) — El nombre del grupo al que pertenece esta ejecución, para ayudar a organizar las ejecuciones relacionadas. Puede alternar la visibilidad de todo el grupo en el panel de control.
  • space_id (str, opcional) — Si se proporciona, el proyecto se registrará en un Hugging Face Space en lugar de en un directorio local. Debe ser un nombre completo de Space como “username/reponame” o “orgname/reponame”, o solo “reponame”, en cuyo caso el Space se creará en el espacio de nombres del usuario de Hugging Face actualmente conectado. Si el Space no existe, se creará. Si el Space ya existe, el proyecto se registrará en él. También se puede establecer mediante la variable de entorno TRACKIO_SPACE_ID. No se puede registrar en un Space que haya sido frozen (convertido al SDK estático); use trackio.sync(..., sdk="static") solo después de terminar de registrar. Tiene prioridad sobre server_url y TRACKIO_SERVER_URL cuando se establece más de uno.
  • server_url (str, opcional) — URL base de un servidor de Trackio autoalojado (http:// o https://), o la URL de acceso de escritura de trackio.show(), que puede incluir un parámetro de consulta write_token. El cliente envía ese token en cada solicitud (X-Trackio-Write-Token); también puede establecer TRACKIO_WRITE_TOKEN en lugar de incrustar el token en la URL. Cuando se establece, las métricas se envían a ese servidor a través de HTTP en lugar de crear o sincronizar con un Space de Hugging Face. También puede establecerse mediante la variable de entorno TRACKIO_SERVER_URL. Se ignora cuando se establece space_id o TRACKIO_SPACE_ID.
  • dataset_id (str, opcional) — Obsoleto: la persistencia de datos de trackio en un Dataset de Hugging Face se eliminará en una versión futura de trackio. Usa bucket_id (un Bucket de Hugging Face) en su lugar.
  • bucket_id (str, opcional) — El ID del Bucket de Hugging Face que se usará para la persistencia de métricas. De forma predeterminada, cuando se proporciona un space_id y bucket_id no se establece explícitamente, se genera automáticamente un bucket a partir del space_id. Los buckets proporcionan almacenamiento similar a S3 sin la sobrecarga de git: la base de datos SQLite se almacena directamente mediante hf-mount en el Space. Especifique un Bucket con un nombre como “username/bucketname” o simplemente “bucketname”.
  • config (dict, opcional) — Un diccionario de opciones de configuración. Se proporciona por compatibilidad con wandb.init().
  • resume (str, opcional, por defecto “never”) — Controla cómo se maneja la reanudación de una ejecución. Puede ser uno de los siguientes:
    • “must”: Debe reanudar la ejecución con el nombre indicado; se genera un error si la ejecución no existe
    • “allow”: Reanuda la ejecución si ya existe; de lo contrario, crea una nueva
    • “never”: No reanudar nunca una ejecución, siempre crear una nueva
  • private (bool, opcional) — Si se debe hacer el Space privado. Si es None (predeterminado), el repositorio será público a menos que el valor predeterminado de la organización sea privado. Este valor se ignora si el repositorio ya existe.
  • settings (cualquiera, opcional) — No se utiliza. Se proporciona para compatibilidad con wandb.init().
  • embed (bool, opcional, valor predeterminado True) — Si se ejecuta dentro de un cuaderno de Jupyter/Colab, si el panel de control debe incrustarse automáticamente en la celda cuando se llama a trackio.init(). Para ejecuciones locales, esto inicia un panel de control local de Trackio y lo incrusta. Para ejecuciones en Space, esto incrusta la URL del Space. En Colab, el panel de control local será accesible mediante una URL de compartición pública cuando share=True.
  • auto_log_gpu (bool o None, opcional, valor predeterminado None) — Controla el registro automático de métricas de GPU. Si es None (predeterminado), el registro de GPU se habilita automáticamente cuando nvidia-ml-py está instalado y se detecta una GPU de NVIDIA o una serie Apple M. Establezca True para forzar la habilitación o False para deshabilitarla.
  • gpu_log_interval (float, opcional, valor predeterminado 10.0) — El intervalo en segundos entre los registros automáticos de métricas de GPU. Solo se utiliza cuando auto_log_gpu=True.
  • auto_log_cpu (bool o None, opcional, valor predeterminado None) — Controla el registro automático de métricas de CPU y RAM (utilización, memoria, E/S de disco, E/S de red y sensores). Si es None (predeterminado), el registro de CPU se habilita automáticamente cuando psutil está instalado. Establezca True para forzar la habilitación o False para deshabilitarlo.
  • cpu_log_interval (float, opcional, valor predeterminado 10.0) — El intervalo en segundos entre los registros automáticos de métricas de CPU. Solo se utiliza cuando el registro automático de CPU está habilitado.
  • webhook_url (str, opcional) — Una URL de webhook a la que se enviarán las cargas de alertas mediante POST cuando se llame a trackio.alert(). Admite de forma nativa las URLs de webhook de Slack y Discord (las cargas se formatean automáticamente). También se puede configurar mediante la variable de entorno TRACKIO_WEBHOOK_URL. Las alertas individuales pueden invalidar esta URL pasando webhook_url a trackio.alert().
  • webhook_min_level (AlertLevel o str, opcional) — Nivel mínimo de alerta que debe activar la entrega del webhook. Por ejemplo, AlertLevel.WARN envía solo las alertas WARN y ERROR al destino del webhook. También se puede configurar mediante TRACKIO_WEBHOOK_MIN_LEVEL.
  • capture_console (bool o None, opcional, valor predeterminado None) — Si se captura todo lo que el script escribe en stdout y stderr (incluyendo la salida de print() y logging) y se almacena con la ejecución. La salida se muestra en la página de la ejecución del panel de control, donde también se puede descargar. Si es None (predeterminado), la captura de consola solo se habilita cuando la variable de entorno TRACKIO_CAPTURE_CONSOLE está establecida en 1 o true.

Devuelve

Ejecutar

Un objeto [Run] que se puede usar para registrar métricas y finalizar la ejecución.

Crea un nuevo proyecto de Trackio y devuelve un objeto [Run].

log

trackio.log

< >

( metrics: dictstep: int | None = None )

Parámetros

  • metrics (dict) — Un diccionario de métricas para registrar.
  • step (int, opcional) — El número de paso. Si no se proporciona, el paso se incrementará automáticamente.

Registra las métricas en la ejecución actual.

log_gpu

trackio.log_gpu

< >

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

Parámetros

  • run — Instancia de Run opcional. Si es None, usa la ejecución actual del contexto.
  • device — Índice del dispositivo CUDA del que se recopilarán las métricas (solo GPUs de NVIDIA). Si es None, se recopilan de todas las GPUs visibles para este proceso. Este parámetro se ignora para las GPUs de Apple.

Devuelve

dict

Las métricas de GPU que se registraron.

Registra las métricas de la GPU en la ejecución actual o especificada como métricas del sistema. Detecta automáticamente si hay disponible una GPU de NVIDIA o Apple y llama al método de registro apropiado.

Ejemplo:

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 )

Parámetros

  • metrics (dict) — Un diccionario de métricas del sistema para registrar.

Registra las métricas del sistema (GPU, etc.) en la ejecución actual usando marcas de tiempo en lugar de pasos.

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 )

Parámetros

  • artifact_or_path (Artifact, str o Path) — El artefacto que se registrará (debe tener al menos un archivo añadido mediante add_file o add_dir), o una ruta a un archivo o directorio para registrarlo como un nuevo artefacto.
  • name (str, opcional) — Nombre del artefacto al registrar una ruta. El valor predeterminado es run-<run_id>-<basename>. No debe pasarse junto con un Artifact.
  • type (str, opcional) — Tipo de artefacto al registrar una ruta (p. ej. "model", "dataset"). Por defecto es "unspecified". No debe pasarse junto con un Artifact.
  • aliases (list[str], opcional) — Alias que se rotarán a la versión resultante, junto con latest (asignado automáticamente cada vez que se crea una nueva versión). Tus alias se rotan a la versión incluso cuando el contenido idéntico se deduplica.
  • overwrite (bool, opcional) — Si es True, elimina todas las demás versiones de este artefacto después de que se registre el nuevo contenido. Los blobs que aún se utilizan en otros artefactos se conservan, y los números de versión siguen aumentando. El valor predeterminado es False.

Registra un artefacto como salida de la ejecución actual.

use_artifact

trackio.use_artifact

< >

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

Parámetros

  • artifact_or_name (Artifact o str) — Un Artifact ya registrado, o el nombre de un artifact. Un nombre simple ("my-model") se resuelve a :latest; también puedes fijar una versión ("my-model:v3") o resolver un alias ("my-model:prod").
  • type (str, opcional) — Si se especifica, se comprueba contra el tipo de artefacto almacenado y se lanza una excepción si no coincide.

Obtiene un artefacto y lo registra como una entrada para la ejecución actual.

terminar

trackio.finish

< >

( )

Finaliza la ejecución actual.

mostrar

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

Parámetros

  • project (str, opcional) — El nombre del proyecto cuyos ejecuciones se mostrarán. Si no se proporciona, se mostrarán todos los proyectos y el usuario podrá seleccionar uno.
  • dashboard (str, opcional) — Establezca "registry" para mostrar el panel de registro independiente. El valor predeterminado es el panel del proyecto.
  • theme (Any, opcional) — Se ignora. Se conserva por compatibilidad con versiones anteriores; Trackio ya no usa temas de Gradio.
  • mcp_server (bool, opcional) — Si es True, el panel expone un servidor MCP en /mcp cuando se instala la dependencia opcional trackio[mcp]. Si es None (valor predeterminado), se utiliza la variable de entorno GRADIO_MCP_SERVER (p. ej., en Spaces).
  • footer (bool, opcional, valor predeterminado True) — Si se debe incluir footer=false en la URL del token de escritura cuando es False. También se puede controlar mediante el parámetro de consulta footer en la URL.
  • color_palette (list[str], opcional) — Una lista de códigos de color en hexadecimal para usar en las líneas del gráfico. Si no se proporciona, se utilizará la variable de entorno TRACKIO_COLOR_PALETTE (códigos hexadecimales separados por comas), o si esta no está configurada, se utilizará la paleta de colores predeterminada. Ejemplo: ['#FF0000', '#00FF00', '#0000FF']
  • open_browser (bool, opcional, valor predeterminado True) — Si True y no se está en un notebook, se abrirá una nueva pestaña del navegador con el panel de control. Si False, no se abrirá el navegador.
  • block_thread (bool, opcional) — Si es True, el hilo principal se bloqueará hasta que se cierre el panel de control. Si es None (comportamiento predeterminado), el hilo principal no se bloqueará si el panel de control se inicia en un cuaderno; de lo contrario, el hilo principal se bloqueará.
  • host (str, opcional) — El host al que se vinculará el servidor. Si no se proporciona, el valor predeterminado es '127.0.0.1' (solo localhost). Establezca '0.0.0.0' para permitir el acceso remoto.
  • share (bool, opcional) — Si es True, crea una URL pública temporal (túnel compatible con Gradio). En Colab o notebooks alojados, el valor predeterminado es True a menos que se sobrescriba.
  • server_port (int, opcional) — Puerto al que se va a vincular. Si no se establece, se escanea desde GRADIO_SERVER_PORT (predeterminado 7860).
  • frontend_dir (str | Path, opcional) — Directorio que contiene un frontend estático personalizado. Debe contener index.html. Si no se proporciona, Trackio comprueba TRACKIO_FRONTEND_DIR, luego la configuración persistente de Trackio y, por último, el frontend incluido. Si un frontend_dir explícito apunta a un directorio inexistente o vacío, Trackio copia la plantilla inicial y sirve ese directorio.

Devuelve

app

El manejador del panel de control (.close() detiene el servidor). url: La URL local del panel de control. share_url: La URL pública de compartición, si la hay. full_url: La URL completa que incluye el token de escritura (URL de compartición al compartir, en caso contrario, local).

Inicia el panel de Trackio.

sync

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

Parámetros

  • project (str) — El nombre del proyecto que se va a subir.
  • space_id (str, opcional) — El ID del Space al que se subirá (p. ej., “username/space_id”). Si no se proporciona, primero comprueba los metadatos del proyecto y luego genera un space_id aleatorio.
  • private (bool, opcional) — Si se debe hacer el Space privado. Si es None (valor predeterminado), el repositorio será público a menos que el valor predeterminado de la organización sea privado. Este valor se ignora si el repositorio ya existe. No se admite con sdk="static" porque los paneles de Trackio estáticos leen los datos de la instantánea directamente desde el navegador.
  • force (bool, opcional, valor predeterminado False) — Si es True, sobrescribe la base de datos existente sin solicitar confirmación. Si es False, solicita al usuario confirmación antes de sobrescribir una base de datos existente.
  • run_in_background (bool, opcional, valor predeterminado False) — Si es True, la creación del Space y la carga en la base de datos se ejecutarán en un hilo en segundo plano. Si es False, todos los pasos se ejecutarán de forma síncrona.
  • sdk (str, opcional, valor predeterminado “gradio”) — El tipo de Space a desplegar. “gradio” despliega un Space de Gradio con un servidor en vivo. “static” congela el Space: despliega un Space estático que lee desde un HF Bucket (no se necesita servidor).
  • dataset_id (str, opcional) — Obsoleto: la persistencia de datos de trackio en un Dataset de Hugging Face se eliminará en una versión futura de trackio. Usa bucket_id (un Bucket de Hugging Face) en su lugar.
  • bucket_id (str, opcional) — El ID del HF Bucket al que se sincronizará. De forma predeterminada, se genera automáticamente un bucket a partir de space_id.

Devuelve

str

El ID del Space del proyecto sincronizado.

Sincroniza la base de datos de un proyecto local de Trackio con un Space de Hugging Face. Si el Space no existe, se creará. Los datos locales nunca se eliminan.

Congelar: Pasar sdk="static" despliega un Space estático respaldado por un HF Bucket (tablero de solo lectura, sin servidor Gradio). Puedes sincronizar el mismo proyecto más adelante para actualizar ese Space estático. Si quieres una instantánea única de un Space de Gradio existente, usa freeze() en su lugar.

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

Parámetros

  • space_id (str) — El ID del Gradio Space de origen (p. ej., "username/my-space" o un nombre de repositorio corto con el espacio de nombres del usuario conectado inferido, como init()). Debe ser un Gradio Space con un bucket montado en /data.
  • project (str) — El nombre del proyecto cuyos datos se incluirán en el Space congelado.
  • new_space_id (str, opcional) — El ID para el nuevo Space estático. Si no se proporciona, el valor predeterminado es "{space_id}_static".
  • private (bool, opcional) — No se admite. Los paneles estáticos congelados leen los datos de la instantánea directamente desde el navegador, por lo que la instantánea de destino debe ser pública.
  • bucket_id (str, opcional) — El ID del HF Bucket para el almacenamiento de datos del nuevo Space estático. Si no se proporciona, se genera automáticamente a partir del ID del nuevo Space.

Devuelve

str

El ID del Space estático recién creado.

Crea un nuevo Space estático de Hugging Face que contiene una copia de solo lectura de los datos del proyecto especificado desde el Space de Gradio de origen. Los datos se leen del bucket adjunto al Space de origen en el momento de la congelación. El Space original no se modifica y el nuevo Space estático no refleja automáticamente las métricas cargadas en el Space de Gradio original después de que se complete la congelación.

delete_project

trackio.delete_project

< >

( project: strforce: bool = False ) → bool

Parámetros

  • project (str) — El nombre del proyecto que se va a eliminar.
  • force (bool, opcional, valor predeterminado False) — Si es True, elimina el proyecto sin solicitar confirmación. Si es False, solicita al usuario que confirme antes de eliminar.

Devuelve

bool

True si el proyecto se eliminó, False en caso contrario.

Elimina un proyecto eliminando su base de datos SQLite local.

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 )

Parámetros

  • csv_path (str o Path) — La str o Path del archivo CSV a importar.
  • project (str) — El nombre del proyecto en el que se importará el archivo CSV. No debe ser un proyecto existente.
  • name (str, opcional) — El nombre de la Run en la que se importará el archivo CSV. Si no se proporciona, se generará un nombre predeterminado.
  • name (str, opcional) — El nombre de la ejecución (si no se proporciona, se generará un nombre predeterminado).
  • space_id (str, opcional) — Si se proporciona, el proyecto se registrará en un Hugging Face Space en lugar de en un directorio local. Debe ser un nombre completo de Space como "username/reponame" o "orgname/reponame", o simplemente "reponame", en cuyo caso el Space se creará en el espacio de nombres del usuario de Hugging Face actualmente conectado. Si el Space no existe, se creará. Si el Space ya existe, el proyecto se registrará en él.
  • dataset_id (str, opcional) — Obsoleto: la persistencia de datos de trackio en un Dataset de Hugging Face se eliminará en una versión futura de trackio. Utilice bucket_id (un Bucket de Hugging Face) en su lugar.
  • private (bool, opcional) — Si se debe hacer el Space privado. Si es None (predeterminado), el repositorio será público a menos que el valor predeterminado de la organización sea privado. Este valor se ignora si el repositorio ya existe.

Importa un archivo CSV en un proyecto de Trackio. El archivo CSV debe contener una columna "step", puede contener opcionalmente una columna "timestamp" y cualquier otra columna se tratará como métricas. También debe incluir una fila de encabezado con los nombres de las columnas.

TODO: llamar a init() y devolver un objeto Run para que el usuario pueda seguir registrando métricas en él.

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 )

Parámetros

  • log_dir (str o Path) — La str o Path al directorio que contiene los archivos de Eventos de TensorFlow.
  • project (str) — El nombre del proyecto en el que se importarán los archivos de eventos de TensorFlow. No debe ser un proyecto existente.
  • name (str, opcional) — El prefijo de nombre para las ejecuciones (si no se proporciona, se usarán los nombres de los directorios). Cada subdirectorio creará una ejecución separada.
  • space_id (str, opcional) — Si se proporciona, el proyecto se registrará en un Hugging Face Space en lugar de en un directorio local. Debe ser un nombre completo de Space como "username/reponame" o "orgname/reponame", o simplemente "reponame", en cuyo caso el Space se creará en el espacio de nombres del usuario de Hugging Face actualmente conectado. Si el Space no existe, se creará. Si el Space ya existe, el proyecto se registrará en él.
  • dataset_id (str, opcional) — Obsoleto: la persistencia de datos de trackio en un Dataset de Hugging Face se eliminará en una versión futura de trackio. Utilice bucket_id (un Bucket de Hugging Face) en su lugar.
  • private (bool, opcional) — Si se debe hacer el Space privado. Si es None (predeterminado), el repositorio será público a menos que el valor predeterminado de la organización sea privado. Este valor se ignora si el repositorio ya existe.

Importa archivos de TensorFlow Events desde un directorio a un proyecto de Trackio. Cada subdirectorio en el directorio de registro se importará como una ejecución independiente.

save

trackio.save

< >

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

Parámetros

  • glob_str (str o Path) — La ruta de archivo o el patrón glob a guardar. Puede ser un solo archivo o un patrón que coincida con varios archivos (p. ej., "*.py", "models/**/*.pth").
  • project (str, opcional) — El nombre del proyecto en el que se guardarán los archivos. Si no se proporciona, se utiliza el proyecto actual de trackio.init(). Si no hay ningún proyecto inicializado, se genera un error.

Devuelve

str

La ruta donde se guardó(aron) el/los archivo(s) (directorio de archivos del proyecto).

Guarda archivos en un proyecto (no vinculados a una ejecución específica). Si Trackio se está ejecutando localmente, el o los archivos se copiarán al directorio de archivos del proyecto. Si Trackio se está ejecutando en un Space, el o los archivos se subirán al directorio de archivos del Space.

Ejemplo:

import trackio

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

Artifact

clase trackio.Artifact

< >

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

Parámetros

  • name (str) — Nombre del artefacto, único dentro del proyecto. Debe coincidir con ^[A-Za-z0-9._-]+$ (letras, dígitos, punto, guion bajo, guion).
  • type (str) — Categoría libre como "model" o "dataset", utilizada para agrupar artefactos.
  • description (str, opcional) — Descripción legible por humanos del artefacto.
  • metadata (dict, opcional) — Metadatos arbitrarios serializables en JSON almacenados junto con la versión.

Un paquete de archivos y referencias con nombre y versión, adjunto a un proyecto.

Construya un Artifact, añada archivos con add_file / add_dir (los bytes se almacenan en un almacenamiento con dirección de contenido) o add_reference (un URI externo se registra sin copiar ningún byte) y, a continuación, persista el artefacto con trackio.log_artifact. El registro congela el artefacto y rellena sus atributos de solo lectura version, aliases, size y manifest.

add_dir

< >

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

Parámetros

  • local_dir (str o Path) — Ruta a un directorio existente cuyos archivos se añaden.
  • name (str, opcional) — Prefijo de ruta lógica para los archivos añadidos. Por defecto, no hay prefijo, de modo que los archivos conservan sus rutas relativas a local_dir.

Etiqueta todos los archivos regulares bajo un directorio, de forma recursiva.

Los enlaces simbólicos se omiten.

add_file

< >

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

Parámetros

  • local_path (str o Path) — Ruta a un archivo regular existente para agregar.
  • name (str, opcional) — Ruta lógica bajo la cual se almacena el archivo dentro del artefacto. Por defecto, es el nombre base del archivo.

Prepara un archivo individual para su inclusión en el artefacto.

add_reference

< >

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

Parámetros

  • uri (str) — Ubicación de los datos referenciados, codificada en porcentaje (construya URI locales con pathlib.Path.as_uri()). file://, http(s):// y hf:// se resuelven y obtienen de forma nativa; cualquier otro esquema (s3://, gs://, URLs de Azure blob, …) requiere un ReferenceHandler personalizado registrado mediante trackio.register_reference_handler — consulte la documentación de artefactos para ejemplos completos — y de lo contrario se lanza una excepción.
  • name (str, opcional) — Ruta lógica bajo la que se almacena la referencia. Por defecto, es el último segmento de uri; para un prefijo expandido (que termina con /), es el prefijo bajo el que se anida la ruta relativa de cada objeto.
  • checksum (bool, opcional, valor predeterminado True) — Cuando es True, sondea la fuente para derivar su tamaño y un checksum (y para expandir un directorio/prefijo): file:// se hashea en flujo a sha256, hf:// usa su sha256 de LFS o su id de blob de git, y http(s):// usa el ETag del servidor. Esto puede leer el sistema de archivos o realizar solicitudes de red. Cuando no se puede obtener un checksum para una fuente remota (p. ej., sin ETag), se utiliza el propio URI como digest y se emite una advertencia. Una ruta local file:// que no existe, en cambio, lanza una excepción. Pasa checksum=False para omitir por completo el sondeo remoto.
  • max_objects (int, opcional) — Límite de objetos en los que se expande un directorio/prefijo (valor predeterminado: 10.000); superarlo genera una excepción.

Estage una referencia a datos externos, sin copiar ningún byte.

A diferencia de add_file/add_dir, una referencia registra la URI de los datos (además, cuando está disponible, un tamaño y una suma de verificación) sin almacenar los bytes en el almacén de direcciones de contenido. Esta es la forma de versionar y hacer seguimiento del linaje sobre conjuntos de datos grandes o ya almacenados de forma duradera que no deben duplicarse.

Una URI que denota un directorio (file://, hf:// o un prefijo expandido por un controlador personalizado) se expande en una entrada por objeto, limitada por max_objects. Los bytes de referencia nunca se suben a un Space ni a un bucket.

La URI se almacena tal cual en el manifiesto del artefacto, y los manifiestos pueden sincronizarse con un Hugging Face Dataset compartido; por lo tanto, una URI firmada genera una advertencia por razones de seguridad; se recomienda utilizar la URI canónica sin firmar del objeto (p. ej. s3://bucket/key).

descargar

< >

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

Parámetros

  • root (str o Path, opcional) — Directorio donde se escribirán los archivos. El valor predeterminado es ./.trackio/artifact-downloads/<project>/<name>_v<version>/, indexado por proyecto para que los artefactos con el mismo nombre de proyectos diferentes nunca colisionen, y por la versión resuelta para que un alias cambiante como latest nunca deje atrás archivos obsoletos de una versión anterior.

Materialice los archivos del artefacto en un directorio local.

Los archivos se copian desde la caché de Trackio con dirección de contenido (y se obtienen del remoto cuando no están disponibles localmente), por lo que las llamadas repetidas son económicas e idempotentes.

Las entradas de referencia añadidas mediante add_reference también se obtienen aquí: el objeto en cada URI de referencia se descarga en el directorio (mediante httpx2 incluido para http(s)://, huggingface_hub para hf://, y el ReferenceHandler personalizado registrado para cualquier otro esquema). Cada objeto se escribe de forma atómica y las llamadas son idempotentes. Dado que los dígitos de referencia son opacos (un ETag del proveedor o el propio URI), se asume que un archivo presente está actualizado y no se vuelve a verificar contra la fuente, y una fuente cuyo sumatorio de comprobación reprobado ya no coincide con el registrado se descarga de todos modos con una advertencia. La descarga puede transferir una gran cantidad de datos; para trabajar con los URI sin descargarlos, léelos de la propiedad references o de get_entry_uri en su lugar. Una fuente ausente, un servidor inaccesible o un esquema sin un manejador registrado provocan una excepción.

get_entry_uri

< >

( name: str )

Devuelve la URI registrada para la entrada de referencia en la ruta lógica name, o None si no hay ninguna entrada de referencia con ese nombre.

enlace

< >

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

Parámetros

  • target_path (str) — La colección a la que se va a enlazar, como "registry-<registry>/<collection>". El registro debe existir ya.
  • aliases (list[str], opcional) — Alias a colocar en la versión vinculada. latest se gestiona automáticamente; pasarla no tiene efecto.
  • bucket_id (str, opcional) — Bucket que contiene el registro, p. ej. "my-org/models-registry". Omita para un registro local; por defecto es TRACKIO_REGISTRY_BUCKET_ID si este está definido.

Vincular esta versión del artefacto a una colección de registro.

Un enlace es un puntero a esta versión: no se copian archivos. Consulte Run.link_artifact para la semántica completa (versionado de colecciones, alias y el artefacto enlazado devuelto).

El artefacto ya debe estar registrado o descargado; a diferencia de Run.link_artifact, esto no registra un artefacto en borrador por ti, y el enlace no registra ninguna ejecución de publicación. Un artefacto descargado de un Space o de un servidor autoalojado solo puede enlazarse en un registro respaldado por un bucket, ya que un registro local no es accesible desde donde residen sus bytes.

unlink

< >

( )

Elimine este enlace del registro.

Llame a esto en el artefacto vinculado devuelto por link o Run.link_artifact, no en una versión de artefacto de origen. El artefacto de origen y sus archivos permanecen intactos; solo se elimina la pertenencia a la colección. Los alias que apuntan al vínculo se eliminan con él, y el número de versión de la colección nunca se reutiliza. Si la versión contenía latest, ese alias se mueve a la versión restante más alta.

esperar

< >

( timeout: int | None = None )

No-op: trackio registra los artefactos de forma síncrona, por lo que el artefacto ya está comprometido en el momento en que log_artifact devuelve el control.

Registro

clase trackio.Registry

< >

( name: strbucket_id: str | None = None )

Parámetros

  • name (str) — Nombre del registro, p. ej. "models". Debe coincidir con ^[A-Za-z0-9_-]+$ (letras, dígitos, guion bajo, guion).
  • bucket_id (str, opcional) — Bucket de Hugging Face que contiene el registro, p. ej. "my-org/models-registry". Omítelo para un registro local. El valor predeterminado es TRACKIO_REGISTRY_BUCKET_ID si está definido.

Un identificador de un registro de artefactos.

Un registro es un catálogo compartido de versiones de artefactos, organizado en colecciones. Publicas en él con Run.link_artifact y promueves versiones moviendo alias como "staging" o "production". Consulta la guía de Registro para obtener una visión completa.

No construyes un Registry por ti mismo. Crea un registro con trackio.Api().create_registry(name) o recupera uno existente con trackio.Api().registry(name); ambos devuelven este manejador.

Ejemplo:

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

colección

< >

( name: str )

Describe una colección.

Devuelve None si el registro o la colección no existen.

colecciones

< >

( )

Liste las colecciones del registro, incluidos los enlaces.

Devuelve una lista vacía si el registro no existe.

create_collection

< >

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

Parámetros

  • name (str) — Nombre de la colección, único dentro del registro. Debe coincidir con ^[A-Za-z0-9._-]+$.
  • artifact_type (str) — El tipo de artefacto que acepta la colección, p. ej. "model" o "dataset". El tipo se fija en la creación; vincular un artefacto de un tipo diferente provoca una excepción.
  • description (str, opcional) — Descripción legible por humanos de la colección.

Crea una colección en este registro.

Las colecciones también se crean automáticamente al enlazar por primera vez, por lo que esto es útil principalmente para establecer una descripción de antemano. Si la colección ya existe, se devuelve tal cual y se aplica una description que no sea None.

eventos

< >

( )

Devuelve el registro de auditoría del registro, con el evento más antiguo primero.

Cada evento tiene un id, una marca de tiempo ts, un kind ("create", "link", "promote", "update" o "unlink") y un payload que describe la mutación. Un create payload sin la clave collection registra la creación del propio registro.

Colección

clase trackio.Collection

< >

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

Una instantánea de solo lectura de una colección de registro.

Devuelto por Registry.create_collection, Registry.collection y Registry.collections.

Imagen

clase trackio.TrackioImage

< >

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

Parámetros

  • value (str, Path, numpy.ndarray o PIL.Image, opcional) — Una ruta a una imagen, una imagen PIL o un array numpy de forma (height, width, channels). Si es un array numpy, debe ser de tipo np.uint8 con valores RGB en el rango [0, 255].
  • caption (str, opcional) — Una cadena de texto que describe la imagen.

Inicializa un objeto Image.

Ejemplo:

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})

Video

clase trackio.TrackioVideo

< >

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

Parámetros

  • value (str, Path o numpy.ndarray, opcional) — Una ruta a un archivo de video o un array de numpy. Si es un array de numpy, debe ser de tipo np.uint8 con valores RGB en el rango [0, 255]. Se espera que tenga una forma de (frames, channels, height, width) o (batch, frames, channels, height, width). En el segundo caso, los videos se organizarán en una cuadrícula.
  • caption (str, opcional) — Una cadena de texto con la descripción del video.
  • fps (int, opcional) — Fotogramas por segundo del vídeo. Solo se utiliza cuando el valor es un ndarray. El valor predeterminado es 24.
  • format (Literal["gif", "mp4", "webm"], opcional) — Formato de vídeo (“gif”, “mp4” o “webm”). Solo se utiliza cuando el valor es un ndarray. El valor predeterminado es “gif”.

Inicializa un objeto Video.

Ejemplo:

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'] )

Solo RGB uint8, forma (F, H, W, 3).

Audio

clase trackio.TrackioAudio

< >

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

Parámetros

  • value (str, Path o numpy.ndarray, opcional) — Una ruta a un archivo de audio o un array de numpy. El array debe tener forma (samples,) para mono o (samples, 2) para estéreo. Los arrays de flotantes se normalizarán por pico y se convertirán a PCM de 16 bits; los arrays de enteros se convertirán a PCM de 16 bits según sea necesario.
  • caption (str, opcional) — Una cadena de texto con la descripción del audio.
  • sample_rate (int, opcional) — Tasa de muestreo en Hz. Obligatorio cuando value es un array de numpy.
  • format (Literal["wav", "mp3"], opcional) — Formato de audio utilizado cuando value es un array de numpy. El valor predeterminado es “wav”.

Inicializa un objeto Audio.

Ejemplo:

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 )

Convierte el array de audio de entrada a PCM int16 contiguo. Se aplica normalización de pico a las entradas de punto flotante.

Object3D

clase trackio.TrackioObject3D

< >

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

Html

clase trackio.TrackioHtml

< >

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

Parámetros

  • data (str, Path, file-like, Plotly figure, or Matplotlib figure) — HTML sin procesar, una ruta a un archivo .html, un objeto similar a un archivo, o una figura de Plotly o Matplotlib.
  • inject (bool, opcional) — Envuelve fragmentos de HTML en un documento con estilo. El valor predeterminado es True.
  • data_is_not_path (bool, opcional) — Aceptado por compatibilidad con wandb.Html pero ignorado.
  • caption (str, opcional) — Una cadena de texto como pie de imagen para el HTML.

Inicializa un objeto Html.

Ejemplo:

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)})

Tabla

clase 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' )

Parámetros

  • columns (list[str], opcional) — Nombres de las columnas de la tabla. Opcional si se proporciona data. No se espera si se proporciona dataframe. Actualmente se ignora.
  • data (list[list[Any]], opcional) — Matriz bidimensional orientada por filas de valores. Cada valor puede ser un número, una cadena de texto (tratada como Markdown y truncada si es demasiado larga) o un objeto Trackio.Image o una lista de objetos Trackio.Image.
  • dataframe (pandas.DataFrame, opcional) — DataFrame utilizado para crear la tabla. Cuando se establece, los argumentos data y columns se ignoran.
  • rows (list[list[Any]], opcional) — Actualmente se ignora.
  • optional (bool o list[bool], opcional, por defecto True) — Actualmente se ignora.
  • allow_mixed_types (bool, opcional, valor predeterminado False) — Actualmente se ignora.
  • log_mode — (Literal["IMMUTABLE", "MUTABLE", "INCREMENTAL"] o None, opcional, valor predeterminado "IMMUTABLE"): Actualmente se ignora.

Inicializa un objeto Table.

Las tablas se pueden utilizar para registrar datos tabulares, incluidos imágenes, números y texto.

to_display_format

< >

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

Parámetros

  • table_data (list[dict]) — Lista de diccionarios que representan filas de tabla (procedentes de _value almacenado).

Devuelve

list[dict]

Datos de la tabla con imágenes convertidas a sintaxis de markdown y texto largo truncado.

Convierte los datos de la tabla almacenados al formato de visualización para la renderización de la interfaz de usuario.

Nota: Esto no utiliza el atributo self.data, sino que utiliza el parámetro table_data, que es lo que recibe la interfaz de usuario.

Trace

clase trackio.Trace

< >

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

Parámetros

  • messages (list[dict[str, Any]]) — Mensajes en formato de OpenAI, p. ej. {"role": "user", "content": "..."}. Los mensajes del asistente pueden incluir tool_calls, y los resultados de las herramientas pueden incluir tool_call_id; cuando no se proporcionan spans, el panel asocia estos elementos en operaciones de herramientas.
  • metadata (dict, opcional) — Metadatos a nivel de trazas, p. ej. session_id o environment. Las claves status, duration_ms, latency_ms y cost_usd se utilizan en el panel de control como valores predeterminados a nivel de traza cuando los spans no los proporcionan.
  • spans (list[dict[str, Any]], opcional) — Spans de ejecución que describen qué produjo la respuesta. Cada span es un diccionario con claves id, name y kind ("span", "generation" o "tool"), además de las opcionales parent_id, start_time, end_time, duration_ms, status, error, input, output, model, usage, cost_usd y metadata.

Inicializa un objeto Trace.

Las trazas capturan una solicitud conversacional o de tipo agente: mensajes en el estilo de OpenAI, metadatos opcionales y spans de ejecución opcionales. Los spans son diccionarios que describen generaciones de modelos, llamadas a herramientas u otras operaciones. Los objetos multimedia de Trackio anidados dentro de mensajes, metadatos o spans se persisten y serializan junto con la traza.

Histograma

clase trackio.Histogram

< >

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

Parámetros

  • sequence (np.ndarray o Sequence[float] o Sequence[int], opcional) — Secuencia de valores para crear el histograma.
  • np_histogram (tuple, opcional) — Histograma de NumPy precalculado como una tupla (hist, bins).
  • num_bins (int, opcional, valor predeterminado 64) — Número de intervalos para el histograma (máximo 512).

Tipo de datos de histograma para Trackio, compatible con wandb.Histogram.

Ejemplo:

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

←Ejecución con RapidFire AI