> This page is for version v1.5.1.
> For other versions, use one of these documentation indexes:
> - Latest (v1.5.1) (default): https://docs.nvidia.com/dynamo/latest/llms.txt
> - dev: https://docs.nvidia.com/dynamo/dev/llms.txt
> - v1.5.1: https://docs.nvidia.com/dynamo/v1.5.1/llms.txt
> - v1.5.0: https://docs.nvidia.com/dynamo/v1.5.0/llms.txt
> - v1.4.2: https://docs.nvidia.com/dynamo/v1.4.2/llms.txt
> - v1.4.1: https://docs.nvidia.com/dynamo/v1.4.1/llms.txt
> - v1.4.0: https://docs.nvidia.com/dynamo/v1.4.0/llms.txt
> - v1.3.0: https://docs.nvidia.com/dynamo/v1.3.0/llms.txt
> - v1.2.1: https://docs.nvidia.com/dynamo/v1.2.1/llms.txt
> - v1.2.0: https://docs.nvidia.com/dynamo/v1.2.0/llms.txt
> - v1.1.1: https://docs.nvidia.com/dynamo/v1.1.1/llms.txt
> - v1.1.0: https://docs.nvidia.com/dynamo/v1.1.0/llms.txt
> - v1.0.2: https://docs.nvidia.com/dynamo/v1.0.2/llms.txt
> - v1.0.1: https://docs.nvidia.com/dynamo/v1.0.1/llms.txt
> - v1.0.0: https://docs.nvidia.com/dynamo/v1.0.0/llms.txt
> - v0.9.1: https://docs.nvidia.com/dynamo/v-0-9-1/llms.txt
> - v0.9.0: https://docs.nvidia.com/dynamo/v-0-9-0/llms.txt
> - v0.8.1: https://docs.nvidia.com/dynamo/v-0-8-1/llms.txt
> - v0.8.0: https://docs.nvidia.com/dynamo/v-0-8-0/llms.txt
> - v0.7.1: https://docs.nvidia.com/dynamo/v-0-7-1/llms.txt
> - v0.7.0: https://docs.nvidia.com/dynamo/v-0-7-0/llms.txt

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.nvidia.com/dynamo/llms.txt. For full content including API reference and SDK examples, see https://docs.nvidia.com/dynamo/llms-full.txt.

# Sweeper Tutorial

<Warning>
**Experimental.** Sweeper's API and search behavior may change without a standard deprecation
period.
</Warning>

## 1. Define the Backend Search

Choose a model, hardware system, deployment modes, backends, and GPU budget:

```yaml
search_space:
  model_name: meta-llama/Meta-Llama-3.1-8B
  hardware_sku: gb200
  deployment_mode: [agg]
  backend: [trtllm]
  gpu_budget: 8
```

Sweeper enumerates legal parallel configurations, removes unsupported runner topologies, and adds
the active engine-role knobs to the optimizer study.

## 2. Define One Workload and Goal

```yaml
workload:
  isl: 1024
  osl: 128
  request_rate: 4
  num_request_ratio: 10

goal:
  target: throughput
```

Every candidate is evaluated against this workload. See [Traffic](/dynamo/knowledge-base/concepts/simulation/ai-simulate/sweeper/traffic) for trace and
closed-loop alternatives, and [Optimization Goals](/dynamo/knowledge-base/concepts/simulation/ai-simulate/sweeper/optimization-goals) for SLA and Pareto modes.

## 3. Control the Sweep

```yaml
sweep:
  max_rounds: 2
  candidates_per_round: 4
  parallel_evals: 2
  max_eval_seconds: 300
```

Each round is a barrier: the sampler asks for unique candidates, replay evaluates them, and then
the scores are reported back together. `parallel_evals` controls replay worker fan-out.

## 4. Add Optional Feature Search

An installed or injected provider owns the schema below its adapter name:

```yaml
adapters:
  example.policy:
    search_space:
      mode: [balanced, latency]
```

The provider receives the complete `search_space` mapping. It does not receive a preselected
concrete feature configuration.

## 5. Run and Inspect

```python
sweeper = Sweeper(
    runner_factory=my_runner_factory,
    providers={"example.policy": my_provider},
)
candidates = sweeper.run(config)

for candidate in candidates[:5]:
    print(candidate.score, candidate.used_gpus, candidate.config)
```

The same `Sweeper` instance can run multiple configurations. Studies, caches, and process pools are
new for every call.