Start a sweep agent

Start or stop a sweep agent on one or more machines.

This page explains how to start a sweep agent on one or more machines so that W&B can run your hyperparameter search. Sweep agents use the sweep configuration that you define when you initialize a sweep to explore different hyperparameter combinations. W&B creates a new run for each hyperparameter combination that the sweep agent runs.

See Manage sweeps to learn how to pause, resume, stop, or cancel a running sweep agent.

Before you continue:

• Configure your training script to create and track hyperparameter combinations with W&B. See Add W&B to your code for examples.
• Define a configuration file for your sweep.

These examples show how to start a sweep agent with the W&B CLI or from Python. You need the sweep ID that W&B returns when you initialize the sweep. You can use the short sweep ID on its own (for example, dtzl1o7u), or include the entity and project as a path:

entity/project/sweep_ID

Where:

• entity: Your W&B username or team name.
• project: The name of the project where you want W&B to store the output of the run. If you don’t specify the project, W&B puts the run in a project called “Uncategorized”.
• sweep_ID: The pseudo-random, unique ID that W&B generates.

CLI

Use the wandb agent command to start a sweep. Provide the sweep ID that W&B returns when you initialize the sweep.

Replace [SWEEP-ID] with your sweep ID in the following command:

wandb agent [SWEEP-ID]

For graceful shutdown when you interrupt the agent (for example, with Ctrl+C), use wandb agent --forward-signals [SWEEP-ID] so the current run receives the signal and can shut down cleanly. See Signal handling and sweep runs for details.

Python script or notebook

Use wandb.agent() to start a sweep. Provide the sweep ID that W&B returns when you initialize the sweep, along with the name of the function that serves as the entrypoint to your training script.

Replace [SWEEP-ID] with your sweep ID and [FUNCTION-NAME] with the name of your training function in the following code:

wandb.agent(sweep_id="[SWEEP-ID]", function="[FUNCTION-NAME]")

W&B only supports signal forwarding from the agent to the training run when you use the CLI (wandb agent --forward-signals). W&B doesn’t support signal forwarding for wandb.agent() in Python because the training function runs in a thread, not as a child process.

See the Python script or notebook tab in Add W&B to your code for an example of how to set up your training script if you use this method.

Multiprocessing

You must wrap your wandb.agent() and wandb.sweep() calls with if __name__ == '__main__': if you use the Python standard library’s multiprocessing or PyTorch’s pytorch.multiprocessing package. For example:

if __name__ == '__main__':
    wandb.agent(sweep_id="[SWEEP-ID]", function="[FUNCTION]", count="[COUNT]")

Wrapping your code with this convention ensures that Python only runs it when you run the script directly, and not when a worker process imports it as a module.

For more information about multiprocessing, see Python standard library multiprocessing or PyTorch multiprocessing. For more information about the if __name__ == '__main__': convention, see Defining main functions in Python.

Limit the number of runs a sweep agent tries

By default, random and Bayesian searches run indefinitely, so cap how many runs an agent attempts. Specify the number of runs a sweep agent should try to bound its work. The following code snippets demonstrate how to set a maximum number of runs with the CLI and within a Jupyter notebook or Python script.

Random and Bayesian searches run indefinitely. If you don’t set a run count, you must stop the process from the command line, from within your Python script, or from the Sweeps UI.

CLI

First, initialize your sweep with the wandb sweep command. For more information, see Initialize sweeps.

wandb sweep config.yaml

Next, pass an integer value to the count flag to set the maximum number of runs to try.

NUM=10
SWEEPID="dtzl1o7u"
wandb agent --count $NUM $SWEEPID

Python script or notebook

First, initialize your sweep. For more information, see Initialize sweeps.

sweep_id = wandb.sweep(sweep_config)

Next, start the sweep job. Provide the sweep ID that sweep initiation generates. Pass an integer value to the count parameter to set the maximum number of runs to try.

sweep_id, count = "dtzl1o7u", 10
wandb.agent(sweep_id, count=count)

If you start a new run after the sweep agent finishes, within the same script or notebook, call wandb.teardown() before you start the new run.