Skip to content

style: apply /style-guide pass to models/sweeps #2722

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
johndmulhausen wants to merge 7 commits into
base: main
Choose a base branch
from
Open

style: apply /style-guide pass to models/sweeps #2722

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
15501f1
style: apply /style-guide pass to models/sweeps
johndmulhausen Jun 4, 2026
80c2295
docs: address mdlinville review feedback on models/sweeps
johndmulhausen Jun 5, 2026
5a3c96a
docs: fix correctness bugs in sweeps docs flagged in review
johndmulhausen Jun 5, 2026
0e12c65
docs: sweep remaining link/terminology patterns across sweeps docs
johndmulhausen Jun 5, 2026
fbe8298
docs: address Copilot review feedback on models/sweeps
johndmulhausen Jun 5, 2026
e291c81
Merge origin/main into style-guide/models-sweeps-20260604-104540
johndmulhausen Jun 10, 2026
52ce746
docs: back out keywords frontmatter from models/sweeps pages
johndmulhausen Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 46 additions & 45 deletions models/sweeps/add-w-and-b-to-your-code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,22 @@ description: Add W&B to your Python code script or Jupyter Notebook.
title: Add W&B (wandb) to your code
---

This guide provides recommendations on how to integrate W&B into your Python training script or notebook for hyperparameter search optimization.
This guide provides recommendations on how to integrate W&B into your Python training script or notebook for hyperparameter search optimization. By following these recommendations, you can use W&B Sweeps to explore hyperparameter values, log training and validation metrics, and identify the configuration that produces strong model performance.

This guide is for machine learning practitioners who already have a Python training script and want to add hyperparameter sweep support. The following sections walk through an example training script, then show how to update it to work with W&B Sweeps.

## Original training script

Suppose you have a Python script that trains a model (see below). Your goal is to find the hyperparameters that maxmimizes the validation accuracy(`val_acc`).
Suppose you have a Python script that trains a model (see the following code). Your goal is to find the hyperparameters that maximize the validation accuracy (`val_acc`).

In your Python script, you define two functions: `train_one_epoch` and `evaluate_one_epoch`. The `train_one_epoch` function simulates training for one epoch and returns the training accuracy and loss. The `evaluate_one_epoch` function simulates evaluating the model on the validation data set and returns the validation accuracy and loss.
In your Python script, you define two functions: `train_one_epoch` and `evaluate_one_epoch`. The `train_one_epoch` function simulates training for one epoch and returns the training accuracy and loss. The `evaluate_one_epoch` function simulates evaluation of the model on the validation data set and returns the validation accuracy and loss.

You define a configuration dictionary (`config`) that contains hyperparameter values such as the learning rate (`lr`), batch size (`batch_size`), and number of epochs (`epochs`). The values in the configuration dictionary control the training process.
You define a configuration dictionary (`config`) that contains hyperparameter values such as the learning rate (`lr`), batch size (`batch_size`), and number of epochs (`epochs`). The values in the configuration dictionary control the training process.

Next you define a function called `main` that mimics a typical training loop. For each epoch, the accuracy and loss is computed on the training and validation data sets.
Next, you define a function called `main` that mimics a typical training loop. For each epoch, the script computes the accuracy and loss on the training and validation data sets.

<Note>
This code is a mock training script. It does not train a model, but simulates the training process by generating random accuracy and loss values. The purpose of this code is to demonstrate how to integrate W&B into your training script.
This code is a mock training script. It doesn't train a model, but simulates the training process by generating random accuracy and loss values. The purpose of this code is to demonstrate how to integrate W&B into your training script.
</Note>

```python
Expand Down Expand Up @@ -53,21 +55,21 @@ if __name__ == "__main__":
main()
```

In the next section, you will add W&B to your Python script to track hyperparameters and metrics during training. You want to use W&B to find the best hyperparameters that maximize the validation accuracy (`val_acc`).
The following section shows how to add W&B to your Python script to track hyperparameters and metrics during training. You want to use W&B to find the best hyperparameters that maximize the validation accuracy (`val_acc`).


## Add W&B to your training script

Update you training script to include W&B. How you integrate W&B to your Python script or notebook depends on how you manage sweeps.
This section shows how to modify the original training script so that the sweep agent can pass hyperparameter values into each run and W&B can record the resulting metrics. How you integrate W&B into your Python script or notebook depends on how you manage sweeps.

To use the W&B Python SDK to start, stop, and manage sweeps, follow the instructions in the **Python script or notebook** tab. To use the W&B CLI instead, follow the instructions in the **CLI** tab.
To use the W&B Python SDK to start, stop, and manage sweeps, follow the instructions in the **Python script or notebook** tab. To use the W&B CLI instead, follow the instructions in the **CLI** tab.

<Tabs>
<Tab title="CLI">
Create a YAML configuration file with your sweep configuration. The
configuration file contains the hyperparameters you want the sweep to explore. In
the following example, the batch size (`batch_size`), epochs (`epochs`), and
the learning rate (`lr`) hyperparameters are varied during each sweep.
the following example, the sweep varies the batch size (`batch_size`), epochs
(`epochs`), and learning rate (`lr`) hyperparameters during each run.

```yaml
# config.yaml
Expand All @@ -87,18 +89,18 @@ parameters:
values: [5, 10, 15]
```

For more information on how to create a W&B Sweep configuration, see [Define sweep configuration](/models/sweeps/define-sweep-configuration/).
For more information, see [Define sweep configuration](/models/sweeps/define-sweep-configuration).

You must provide the name of your Python script for the `program` key
in your YAML file.

Next, add the following to the code example:

1. Import the W&B Python SDK (`wandb`) and PyYAML (`yaml`). PyYAML is used to read in our YAML configuration file.
1. Import the W&B Python SDK (`wandb`) and PyYAML (`yaml`). Use PyYAML to read in your YAML configuration file.
2. Read in the configuration file.
3. Use [`wandb.init()`](/models/ref/python/functions/init) to start a background process to sync and log data as a [W&B Run](/models/ref/python/experiments/run). Pass the config object to the config parameter.
4. Define hyperparameter values from `wandb.Run.config` instead of using hard coded values.
5. Log the metric you want to optimize with [`wandb.Run.log()`](/models/ref/python/experiments/run.md/#method-runlog). You must log the metric defined in your configuration. Within the configuration dictionary (`sweep_configuration` in this example) you define the sweep to maximize the `val_acc` value.
4. Define hyperparameter values from `wandb.Run.config` instead of using hardcoded values.
5. Log the metric you want to optimize with [`wandb.Run.log()`](/models/ref/python/experiments/run.md/#method-runlog). You must log the metric defined in your configuration. Within the configuration dictionary (`sweep_configuration` in this example), you define the sweep to maximize the `val_acc` value.

```python
import wandb
Expand Down Expand Up @@ -142,46 +144,43 @@ def main():
main()
```

In your CLI, set a maximum number of runs for the sweep
agent to try. This is optional. This example we set the
maximum number to 5.
After you update your training script, initialize and start the sweep from your CLI:

```bash
NUM=5
```
1. Optionally, set a maximum number of runs for the sweep agent to try. This example sets the maximum to five:

Next, initialize the sweep with the [`wandb sweep`](/models/ref/cli/wandb-sweep) command. Provide the name of the YAML file. Optionally provide the name of the project for the project flag (`--project`):
```bash
NUM=5
```

```bash
wandb sweep --project sweep-demo-cli config.yaml
```
2. Initialize the sweep with the [`wandb sweep`](/models/ref/cli/wandb-sweep) command. Provide the name of the YAML file. Optionally, provide the name of the project for the project flag (`--project`):

This returns a sweep ID. For more information on how to initialize sweeps, see
[Initialize sweeps](./initialize-sweeps).
```bash
wandb sweep --project sweep-demo-cli config.yaml
```

Copy the sweep ID and replace `sweepID` in the following code snippet to start
the sweep job with the [`wandb agent`](/models/ref/cli/wandb-agent)
command:
This returns a sweep ID. For more information, see [Initialize sweeps](/models/sweeps/initialize-sweeps).

```bash
wandb agent --count $NUM your-entity/sweep-demo-cli/sweepID
```
3. Copy the sweep ID and replace `[SWEEP-ID]` in the following command to start the sweep job with the [`wandb agent`](/models/ref/cli/wandb-agent) command. Replace `[YOUR-ENTITY]` with your W&B entity name:

```bash
wandb agent --count $NUM [YOUR-ENTITY]/sweep-demo-cli/[SWEEP-ID]
```

For more information, see [Start sweep jobs](./start-sweep-agents).
The sweep agent runs your training script repeatedly, each time with a different combination of hyperparameter values from your YAML configuration, and logs the results to W&B. For more information, see [Start sweep jobs](/models/sweeps/start-sweep-agents).
</Tab>
<Tab title="Python script or notebook">
Follow these steps to add W&B to your Python script:

1. Create a dictionary object where the key-value pairs define a [sweep configuration](/models/sweeps/define-sweep-configuration/). The sweep configuration defines the hyperparameters you want W&B to explore on your behalf along with the metric you want to optimize. Continuing from the previous example, the batch size (`batch_size`), epochs (`epochs`), and the learning rate (`lr`) are the hyperparameters to vary during each sweep. You want to maximize the accuracy of the validation score so you set `"goal": "maximize"` and the name of the variable you want to optimize for, in this case `val_acc` (`"name": "val_acc"`).
2. Pass the sweep configuration dictionary to [`wandb.sweep()`](/models/ref/python/functions/sweep). This initializes the sweep and returns a sweep ID (`sweep_id`). For more information, see [Initialize sweeps](./initialize-sweeps).
1. Create a dictionary object where the key-value pairs define a [sweep configuration](/models/sweeps/define-sweep-configuration). The sweep configuration defines the hyperparameters you want W&B to explore on your behalf along with the metric you want to optimize. Continuing from the previous example, the batch size (`batch_size`), epochs (`epochs`), and the learning rate (`lr`) are the hyperparameters to vary during each sweep. You want to maximize the accuracy of the validation score, so set `"goal": "maximize"` and the name of the variable you want to optimize for, in this case `val_acc` (`"name": "val_acc"`).
2. Pass the sweep configuration dictionary to [`wandb.sweep()`](/models/ref/python/functions/sweep). This initializes the sweep and returns a sweep ID (`sweep_id`). For more information, see [Initialize sweeps](/models/sweeps/initialize-sweeps).
3. At the top of your script, import the W&B Python SDK (`wandb`).
4. Within your `main` function, use [`wandb.init()`](/models/ref/python/functions/init) to generate a background process to sync and log data as a [W&B Run](/models/ref/python/experiments/run). Pass the project name as a parameter to the `wandb.init()` method. If you do not pass a project name, W&B uses the default project name.
5. Fetch the hyperparameter values from the `wandb.Run.config` object. This allows you to use the hyperparameter values defined in the sweep configuration dictionary instead of hard coded values.
6. Log the metric you are optimizing for to W&B using [`wandb.Run.log()`](/models/ref/python/experiments/run.md/#method-runlog). You must log the metric defined in your configuration. For example, if you define the metric to optimize as `val_acc`, you must log `val_acc`. If you do not log the metric, W&B does not know what to optimize for. Within the configuration dictionary (`sweep_configuration` in this example), you define the sweep to maximize the `val_acc` value.
7. Start the sweep with [`wandb.agent()`](/models/ref/python/functions/agent). Provide the sweep ID and the name of the function the sweep will execute (`function=main`), and specify the maximum number of runs to try to four (`count=4`).
4. Within your `main` function, use [`wandb.init()`](/models/ref/python/functions/init) to generate a background process to sync and log data as a [W&B Run](/models/ref/python/experiments/run). Pass the project name as a parameter to the `wandb.init()` method. If you don't pass a project name, W&B uses the default project name.
5. Fetch the hyperparameter values from the `wandb.Run.config` object. This lets you use the hyperparameter values defined in the sweep configuration dictionary instead of hardcoded values.
6. Log the metric you're optimizing for to W&B using [`wandb.Run.log()`](/models/ref/python/experiments/run.md/#method-runlog). You must log the metric defined in your configuration. For example, if you define the metric to optimize as `val_acc`, you must log `val_acc`. If you don't log the metric, W&B can't perform optimization. Within the configuration dictionary (`sweep_configuration` in this example), you define the sweep to maximize the `val_acc` value.
7. Start the sweep with [`wandb.agent()`](/models/ref/python/functions/agent). Provide the sweep ID and the name of the function the sweep executes (`function=main`), and set the maximum number of runs to four (`count=4`).


Putting this all together, your script might look similar to the following:
To put this together, your script might look similar to the following:

```python
import wandb # Import the W&B Python SDK
Expand All @@ -200,8 +199,8 @@ def evaluate_one_epoch(epoch):
return acc, loss

def main(args=None):
# When called by sweep agent, args will be None,
# so we use the project from sweep config
# When called by sweep agent, args is None,
# so use the project from sweep config
project = args.project if args else None

with wandb.init(project=project) as run:
Expand Down Expand Up @@ -254,14 +253,16 @@ if __name__ == "__main__":
# Start the sweep job
wandb.agent(sweep_id, function=main, count=4)
```

When you run this script, W&B starts the sweep, executes the `main` function up to four times with different hyperparameter combinations, and logs each run's metrics so you can compare results in the W&B App.
</Tab>
</Tabs>


<Note>
**Logging metrics to W&B in a sweep**

You must log the metric you define and are optimizing for in both your sweep configuration and with `wandb.Run.log()`. For example, if you define the metric to optimize as `val_acc` within your sweep configuration, you must also log `val_acc` to W&B. If you do not log the metric, W&B does not know what to optimize for.
You must log the metric you define and are optimizing for in both your sweep configuration and with `wandb.Run.log()`. For example, if you define the metric to optimize as `val_acc` within your sweep configuration, you must also log `val_acc` to W&B. If you don't log the metric, W&B can't perform optimization.

```python
with wandb.init() as run:
Expand All @@ -274,7 +275,7 @@ with wandb.init() as run:
)
```

The following is an incorrect example of logging the metric to W&B. The metric that is optimized for in the sweep configuration is `val_acc`, but the code logs `val_acc` within a nested dictionary under the key `validation`. You must log the metric directly, not within a nested dictionary.
The following is an incorrect example of logging the metric to W&B. The sweep configuration optimizes for `val_acc`, but the code logs `val_acc` within a nested dictionary under the key `validation`. You must log the metric directly, not within a nested dictionary.

```python
with wandb.init() as run:
Expand Down
Loading
Loading