Sweeper Configuration | NVIDIA Dynamo Documentation

<!— Generated from aisimulate/docs/sweeper/configuration.md by docs/fern/scripts/sync_aisimulate_docs.py. Edit the canonical source instead of this Fern copy. —>

Experimental. Sweeper’s configuration schema may change without a standard deprecation period.

SmartSearchConfig.search_space contains backend and deployment fields. Optional feature-specific search spaces are mappings under SmartSearchConfig.adapters.

Top-Level Shape

1 search_space:
2   model_name: example/model
3   hardware_sku: h200_sxm
4   gpu_budget: 32
5   deployment_mode: [disagg, agg]
6   backend: [vllm, sglang]
7 
8 adapters:
9   example.policy:
10     search_space:
11       mode: [balanced, latency]
12 
13 workload:
14   isl: 1024
15   osl: 128
16   request_rate: 4
17   num_request_ratio: 10
18 
19 goal:
20   target: throughput_per_gpu
21 
22 sweep:
23   max_rounds: 10
24   candidates_per_round: 8
25   parallel_evals: 4

The adapter value is a search space, not one concrete runtime configuration. Its provider validates the whole mapping, contributes optimizer dimensions, and later materializes one concrete adapter configuration for each candidate.

Backend Fields

Field	Default	Purpose
`model_name`	required	model identifier
`hardware_sku`	required	AI Configurator system identifier
`deployment_mode`	`[disagg, agg]`	deployment branches to search
`backend`	`[vllm]`	engine backends to search
`gpu_budget`	`32`	maximum GPUs per candidate
`min_gpu_budget`	`None`	optional lower bound during enumeration
`context_length`	`None`	optional KV-feasibility sequence length
`parallel_configs`	`[]`	optional pinned parallel configurations
`startup_time`	`None`	optional simulated worker startup time
`aic_nextn`	`None`	optional speculative-decoding depth

Each engine role also has lists for max_num_batched_tokens and max_num_seqs, plus pinned block size, GPU-memory-utilization, and prefix-caching fields. A one-item list pins a searched field.

Pinned Parallel Configurations

Pinning parallel_configs requires exactly one deployment mode. An aggregated entry is one shape:

1 search_space:
2   deployment_mode: [agg]
3   parallel_configs:
4     - tp: 4
5       attention_dp: 2
6       replicas: 2

A disaggregated entry contains prefill and decode shapes. Every pinned shape must be legal, KV-feasible, and supported by at least one selected backend.

Provider Selection

Adapter names are provider entry-point names. A provider can be installed through the aisimulate.sweep_config_providers entry-point group or injected into the Sweeper constructor:

1 sweeper = Sweeper(
2     runner_factory=my_runner_factory,
3     providers={"example.policy": my_provider},
4 )

Sweeper loads only names present under adapters. See Sweep Configuration Providers for the complete ABI.

Sampler Algorithm Override

The experimental AISIMULATE_SWEEPER_VIZIER_ALGO environment variable overrides the Vizier algorithm. For example, set it to RANDOM_SEARCH to bypass the default GP-bandit designer. SPICA_VIZIER_ALGO remains a deprecated fallback during migration; when both are set, the AI Simulate variable takes precedence.

Removed KVBM Fields

Sweeper rejects the old KVBM block-count, transfer-bandwidth, offload-batch-size, and cache-hit fields. Native G2 replaces KVBM, so these fields have no adapter migration.