# Variáveis de Ambiente O Trackio usa variáveis de ambiente para configurar vários aspectos de seu comportamento, especialmente para o deploy em Hugging Face Spaces e a persistência de dados. Este guia aborda as principais variáveis de ambiente e seu uso. ## Variáveis de Ambiente Principais ### `TRACKIO_DIR` Especifica um diretório personalizado para armazenar os dados do Trackio. Por padrão, o Trackio armazena os dados em `~/.cache/huggingface/trackio/`. ```bash export TRACKIO_DIR="/path/to/trackio/data" ``` Nota: Esta variável de ambiente se aplica enquanto o Trackio não estiver sendo executado em um Space com armazenamento persistente habilitado. Se o Trackio estiver sendo executado em um Space com armazenamento persistente habilitado (o que é detectado pela variável de ambiente `PERSISTANT_STORAGE_ENABLED`), os dados do Trackio serão armazenados em `/data/trackio`. ### `TRACKIO_SERVER_URL` URL base de um servidor Trackio auto-hospedado (`http://` ou `https://`). Você pode incluir `write_token` na string de consulta (como no `full_url` de `trackio.show()`) ou manter a URL sem parâmetros e definir `TRACKIO_WRITE_TOKEN` em vez disso. Quando definido, `trackio.init()` envia as métricas para esse servidor. Equivalente a passar `server_url=` para `trackio.init()`. **Prioridade:** Se `TRACKIO_SPACE_ID` também estiver definido (ou `space_id` for passado no código), o Hugging Face Space é usado e `TRACKIO_SERVER_URL` é ignorado. A mesma regra se aplica quando ambos `space_id` e `server_url` são passados: `space_id` tem prioridade. Veja [Hospedar o Servidor](self_hosted_server). ```bash export TRACKIO_SERVER_URL="http://127.0.0.1:7860" export TRACKIO_WRITE_TOKEN="YOUR_TOKEN" ``` ### `TRACKIO_WRITE_TOKEN` O **write token** do dashboard para um servidor Trackio auto-hospedado (mesmo valor que o parâmetro de consulta `write_token` na URL de acesso de escrita). Quando definido no servidor Trackio, esse valor é usado como o write token do servidor em vez de gerar um token aleatório na inicialização. Quando definido no cliente Trackio, use isso quando `TRACKIO_SERVER_URL` ou `server_url` for uma URL base sem parâmetros de consulta. O cliente envia esse token em cada solicitação (por exemplo, como o cabeçalho `X-Trackio-Write-Token`) para que a ingestão de métricas e os uploads sejam autenticados quando não estiverem sendo executados nos Hugging Face Spaces. ### `TRACKIO_FRONTEND_DIR` Caminho para um diretório de frontend estático personalizado para o Trackio. O diretório deve conter `index.html`. Quando definido, o Trackio usa esse frontend para `trackio.show()` e para fluxos de implantação como `trackio.sync()` e `trackio.freeze()`, a menos que um argumento explícito de `frontend_dir` / `--frontend` seja passado. ```bash export TRACKIO_FRONTEND_DIR="/path/to/my-trackio-frontend" ``` Se o diretório configurado for inválido, o Trackio o ignora e recorre à lógica de seleção de frontend embutida. O comportamento automático de cópia do modelo inicial só se aplica quando um argumento explícito `frontend_dir` / `--frontend` aponta para um diretório ausente ou vazio. ### `TRACKIO_LOGO_LIGHT_URL` e `TRACKIO_LOGO_DARK_URL` Personalize os logotipos exibidos no dashboard do Trackio para os temas claro e escuro. Você pode fornecer URLs para logotipos personalizados. Observe que ambas as variáveis de ambiente devem ser fornecidas; caso contrário, o padrão do Trackio será usado para qualquer variável que não for fornecida. ```bash export TRACKIO_LOGO_LIGHT_URL="https://example.com/logo-light.png" export TRACKIO_LOGO_DARK_URL="https://example.com/logo-dark.png" ``` > **Observação:** Para Spaces remotos do Trackio, essas variáveis de ambiente são aplicadas apenas quando o Space é criado pela primeira vez via `trackio.init(space_id=...)`. Para alterar os logotipos em um Space existente, atualize as variáveis do Space diretamente nas configurações do Space no Hugging Face. ### `TRACKIO_PLOT_ORDER` Controla a ordem dos gráficos e dos grupos de métricas no dashboard do Trackio. O valor deve ser uma lista de padrões de métricas separados por vírgulas que especificam a ordem desejada. Os grupos são preservados - se `train/loss` for especificado primeiro, todas as outras métricas `train/*` aparecerão juntas no grupo train, com `train/loss` aparecendo primeiro dentro desse grupo. Se um padrão não corresponder a nenhuma métrica, ele é simplesmente ignorado sem causar erros. ```bash 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" ``` > **Observação:** Para Spaces remotos do Trackio, esta variável de ambiente é aplicada apenas quando o Space é criado pela primeira vez via `trackio.init(space_id=...)`. Para alterar o tema em um Space existente, atualize a variável `TRACKIO_THEME` do Space diretamente nas configurações do Space no Hugging Face. ### `TRACKIO_COLOR_PALETTE` Personaliza a paleta de cores usada para as linhas de gráfico no dashboard do Trackio. O valor deve ser uma lista de códigos de cor em hexadecimal separados por vírgulas. Essas cores serão alternadas ao plotar múltiplas execuções. ```bash export TRACKIO_COLOR_PALETTE="#FF0000,#00FF00,#0000FF,#FFFF00,#FF00FF,#00FFFF" ``` **Paleta padrão:** `#A8769B, #E89957, #3B82F6, #10B981, #EF4444, #8B5CF6, #14B8A6, #F59E0B, #EC4899, #06B6D4` ### `TRACKIO_TABLE_TRUNCATE_LENGTH` Controla o comprimento máximo dos valores de string exibidos nas células da tabela antes de serem truncados. Quando o valor de uma célula excede esse comprimento, ele será truncado com um elemento expansível que permite visualizar o texto completo. O valor padrão é `250` caracteres. ```bash export TRACKIO_TABLE_TRUNCATE_LENGTH="500" ``` ### `TRACKIO_STORAGE_MODE` Controla como o Trackio persiste dados localmente. Valores permitidos: `auto` (padrão), `sqlite`, `jsonl`. - `sqlite`: os processos de treinamento gravam diretamente no banco de dados SQLite do projeto (comportamento histórico). - `jsonl`: os processos de treinamento gravam fragmentos JSONL somente de adição em `TRACKIO_DIR/inbox/`, um arquivo por processo; o servidor do dashboard (`trackio show`) os importa para o SQLite. Isso evita completamente escritores simultâneos no SQLite, o que torna o Trackio seguro em sistemas de arquivos de rede (NFS, Lustre, FSx, GPFS, WekaFS, CephFS, ...) onde as semânticas de bloqueio e mmap do SQLite são pouco confiáveis. - `auto`: seleciona `jsonl` automaticamente quando `TRACKIO_DIR` é detectado em um sistema de arquivos de rede (somente Linux), caso contrário, `sqlite`. ```bash export TRACKIO_STORAGE_MODE="jsonl" ``` ### `TRACKIO_INBOX_POLL_INTERVAL` Com que frequência (em segundos) o servidor do dashboard e os Trackio Spaces verificam novos fragmentos JSONL para importar, tanto do diretório local de inbox quanto do inbox do Hugging Face Bucket. O valor padrão é `15`; valores abaixo de `5` são limitados a `5`. ```bash export TRACKIO_INBOX_POLL_INTERVAL="30" ``` ### `TRACKIO_SQLITE_*` (avançado) Substitua os PRAGMAs que o Trackio define em suas conexões SQLite. Eles são principalmente úteis em sistemas de arquivos incomuns; valores inválidos são ignorados. - `TRACKIO_SQLITE_JOURNAL_MODE`: um de `wal`, `delete`, `truncate`, `persist`, `memory`, `off`. O padrão é `wal` localmente e `delete` nos Spaces. - `TRACKIO_SQLITE_MMAP_SIZE`: tamanho da E/S mapeada em memória, em bytes. O valor padrão é `0` (desativado) em todos os casos, pois as leituras mapeadas em memória são o gatilho direto para falhas SIGBUS em sistemas de arquivos de rede e trazem poucos benefícios para a carga de trabalho do Trackio. - `TRACKIO_SQLITE_SYNCHRONOUS`: um dos valores `off`, `normal`, `full`, `extra`. O padrão é `normal`. - `TRACKIO_SQLITE_LOCKING_MODE`: um de `normal`, `exclusive`. O padrão é `exclusive` nos Spaces e `normal` em outros ambientes. - `TRACKIO_SQLITE_TEMP_STORE`: um de `default`, `file`, `memory`. O padrão é `memory`. **Configuração de cluster recomendada:** se o seu diretório home ou de cache estiver em um sistema de arquivos compartilhado (`/fsx`, Lustre, NFS, GPFS, WekaFS, ...), aponte `TRACKIO_DIR` para um disco local do nó (por exemplo, `/tmp` ou `$SLURM_TMPDIR`) ou dependa de `TRACKIO_STORAGE_MODE=auto`, que detecta sistemas de arquivos de rede e alterna para o registro de fragmentos JSONL. Se você precisar gravar SQLite diretamente em um sistema de arquivos compartilhado, defina: ```bash export TRACKIO_SQLITE_JOURNAL_MODE="delete" export TRACKIO_SQLITE_MMAP_SIZE="0" ``` ### `TRACKIO_WEBHOOK_URL` Define uma URL global de webhook para alertas. Quando definida, cada chamada para `trackio.alert()` enviará o payload do alerta via POST para esta URL. Suporta nativamente URLs de webhook do Slack e do Discord (os payloads são formatados automaticamente). Pode ser sobrescrita por alerta ou por execução por meio do parâmetro `webhook_url`. ```bash export TRACKIO_WEBHOOK_URL="https://hooks.slack.com/services/T.../B.../xxx" ``` Consulte o [Guia de alertas](alerts) para mais detalhes. ### `TRACKIO_WEBHOOK_MIN_LEVEL` Define o nível mínimo de alerta que deve ser enviado para webhooks. Alertas abaixo desse nível ainda são exibidos no terminal, armazenados no banco de dados e mostrados no painel, mas não são enviados para os destinos de webhook. Valores permitidos: `info`, `warn`, `error`. ```bash export TRACKIO_WEBHOOK_MIN_LEVEL="warn" ``` Com `warn`, apenas alertas `WARN` e `ERROR` são enviados para as URLs de webhook. ### `TRACKIO_CAPTURE_CONSOLE` Quando definido como `1` ou `true`, o Trackio captura tudo que é escrito no stdout e stderr durante uma execução e exibe isso na página da execução no dashboard. Equivale a passar `capture_console=True` para `trackio.init()`; um argumento explícito de `capture_console` tem precedência. ```bash export TRACKIO_CAPTURE_CONSOLE=1 ``` Veja [Capturando a saída do console e o comando de inicialização](track#capturing-console-output-and-the-launch-command) para mais detalhes. ### `TRACKIO_HANDLE_SIGTERM` Quando definido como `1` ou `true`, o `trackio.init()` instala um manipulador de `SIGTERM` que converte o sinal em uma saída normal, de modo que a execução é finalizada e suas últimas métricas e a saída do console são salvas quando o processo é interrompido por um limite de tempo do Slurm, `docker stop` ou uma evicção do Kubernetes. O código de saída permanece `143`. O manipulador é instalado apenas a partir da thread principal e somente quando nenhum outro manipulador de `SIGTERM` estiver definido. Ele está desativado por padrão porque altera como o processo inteiro responde a `SIGTERM`: por exemplo, o processo aguarda as threads não daemon antes de sair, e frameworks que encadeiam manipuladores existentes (como o requeue automático do Slurm no PyTorch Lightning) sairão em vez de ignorar o sinal. ```bash export TRACKIO_HANDLE_SIGTERM=1 ``` ### `TRACKIO_BUCKET_ID` O ID do Bucket do Hugging Face (por exemplo, `username/bucketname`) usado para persistir dados do Trackio ao executar em um Hugging Face Space. Normalmente, isso é definido automaticamente no Space quando ele é criado via `trackio.init(space_id=...)` ou `trackio.sync(...)`; um bucket é gerado automaticamente a partir do ID do Space, a menos que um `bucket_id` explícito seja fornecido. ```bash export TRACKIO_BUCKET_ID="username/my-trackio-bucket" ``` ### `TRACKIO_DATASET_ID` (obsoleto) > **Descontinuado:** A persistência de dados do Trackio em um Dataset do Hugging Face (`dataset_id` / `TRACKIO_DATASET_ID`) está descontinuada e será removida em uma versão futura do Trackio. Use um Bucket do Hugging Face em vez disso (`bucket_id` / `TRACKIO_BUCKET_ID`). O ID do Dataset do Hugging Face (por exemplo, `username/datasetname`) para o qual um Space do Trackio sincroniza seus dados por meio de um agendador de commits em segundo plano. Quando definido em um Space, o Trackio emite um aviso de depreciação e, por enquanto, continua sincronizando com o Dataset. ```bash export TRACKIO_DATASET_ID="username/my-trackio-dataset" ``` ### `HF_TOKEN` Seu token de autenticação do Hugging Face. Necessário para criar Spaces e Buckets no Hugging Face. Defina-o localmente ao implantar no Spaces a partir da sua máquina. Deve ter permissões de `write` para o namespace no qual você está implantando o dashboard do Trackio. ```bash export HF_TOKEN="hf_xxxxxxxxxxxxx" ``` ## Variáveis de Ambiente do Gradio Como o Trackio é construído sobre o Gradio, você pode usar variáveis de ambiente usadas pelo Gradio para controlar o comportamento do Trackio. Aqui estão alguns exemplos: ### `GRADIO_SERVER_PORT` Especifica a porta na qual o dashboard do Tradio será iniciado. O padrão é `7860` ```bash export GRADIO_SERVER_PORT=8000 ``` ### `GRADIO_SERVER_NAME` Define o nome do host para o servidor do painel do Trackio. Para tornar o painel acessível a partir de qualquer endereço IP, defina este valor como `"0.0.0.0"` ```bash export GRADIO_SERVER_NAME="0.0.0.0" ``` ### `GRADIO_MCP_SERVER` Ativa a funcionalidade de servidor MCP (Model Context Protocol) no Trackio. Quando ativado, o dashboard do Trackio será configurado como um servidor MCP e certas funções serão expostas como ferramentas MCP que podem ser usadas por LLMs (por exemplo, para ler as métricas registradas). ```bash export GRADIO_MCP_SERVER="True" ``` Veja [esta lista mais abrangente](https://www.gradio.app/guides/environment-variables) de variáveis de ambiente usadas pelo Gradio.