SwanLab

Common errors

• Experiment is still shown as running on the SwanLab UI / Experiment status is Crashed

  cause The `swanlab.finish()` function was not explicitly called, or no logs (including system metrics) were uploaded for more than 30 minutes, leading SwanLab to assume the experiment crashed.
  fix Ensure `swanlab.finish()` is called at the end of your experiment script. For network issues, check your connection. For long-running idle periods without logs, consider setting a `mode` other than `cloud` or ensuring periodic logging.

• Cannot input API Key during login / Login fails with invalid API Key

  cause There might be an issue with how the API key is being provided to the CLI, or it's being used in a context where interactive input isn't possible.
  fix Use the command-line arguments: `swanlab login --api-key <YOUR_API_KEY>` or programmatically: `import swanlab; swanlab.login(api_key='Your API Key')`. If self-hosting, also include `--host <YOUR_HOST_ADDRESS>`.

• Subsequent swanlab.init() calls will be ignored (when running multiple experiments in one script)

  cause SwanLab expects `swanlab.finish()` to be called before initializing a new experiment in the same process. Without it, subsequent `init()` calls are ignored.
  fix Add `swanlab.finish()` between each `swanlab.init()` call to properly terminate the previous experiment before starting a new one in the same script.

• ValueError: Experiment ID must be a 1-64 character string. Invalid characters provided.

  cause The `id` parameter provided to `swanlab.init()` (often for resuming experiments) does not meet the specified format requirements.
  fix Ensure the experiment `id` is a string between 1 and 64 characters long and does not contain special characters such as `/ \ # ? % :`.

Warnings

• gotcha When running SwanLab experiments within subprocesses (e.g., in Jupyter notebooks or certain distributed training frameworks), `swanlab.finish()` must be explicitly called. Otherwise, the experiment may remain in a 'Running' state indefinitely on the UI or fail to upload all data.
  Fix: Always include `swanlab.finish()` at the end of your script or experiment execution block when not relying on automatic termination.
• gotcha The `resume` parameter in `swanlab.init()` has distinct behaviors (`must`, `allow`, `never`, `True`/`False`). Misunderstanding these modes can lead to unintended new experiments or errors when attempting to resume a specific run.
  Fix: Carefully choose the `resume` mode and provide the correct `id` for the experiment to be resumed. For example, `resume='allow'` will create a new run if the `id` is not found, while `resume='must'` will raise an error.
• gotcha By default, `swanlab.init()` operates in 'cloud' mode, attempting to synchronize data to swanlab.cn. Users expecting purely local or offline operation must explicitly set the `mode` parameter.
  Fix: To run locally without cloud synchronization, initialize SwanLab with `swanlab.init(mode='local')` or `swanlab.init(mode='offline')`. For debugging, `mode='disabled'` can prevent logging entirely.
• deprecated The `swanlab.OpenApi` module has been superseded by `swanlab.Api`, which provides a more powerful and object-oriented interface for programmatic interaction.
  Fix: Migrate your API interactions to use the `swanlab.Api` module for improved functionality and future compatibility.

Install

• pip install swanlab Install latest version

Imports

• swanlab

  import swanlab

• swanlab.init

  swanlab.init(...)

• swanlab.log

  swanlab.log({...})

• swanlab.finish

  swanlab.finish()

  Important to call explicitly in notebooks or long-running scripts to ensure data upload and proper run termination.

Quickstart

This quickstart initializes a SwanLab experiment, logs hyperparameters using `config`, and then simulates a training loop to log scalar metrics (`loss` and `accuracy`) using `swanlab.log()`. It concludes by explicitly calling `swanlab.finish()`.

import swanlab
import random

# Initialize a SwanLab experiment
run = swanlab.init(
    project="my-ml-project",
    experiment_name="basic_training_run",
    config={
        "learning_rate": 0.01,
        "epochs": 5,
        "batch_size": 32
    }
)

# Simulate a training loop
for epoch in range(run.config.epochs):
    loss = 1.0 / (epoch + 1) + random.uniform(-0.1, 0.1)
    accuracy = 0.5 + (epoch / run.config.epochs) * 0.4 + random.uniform(-0.05, 0.05)
    
    # Log metrics
    swanlab.log({"loss": loss, "accuracy": accuracy})
    print(f"Epoch {epoch+1}, Loss: {loss:.4f}, Accuracy: {accuracy:.4f}")

# Finish the experiment explicitly (optional in most scripts, but good practice)
swanlab.finish()