Configuration Reference¶
Parameter tables for all NeMo Safe Synthesizer configuration sections. For how to use each stage with examples, see Running Safe Synthesizer. For environment variables, see Environment Variables.
Configuration Precedence¶
Exactly what avenues of configuration are available, and thus how precedence is resolved, depends on how you run the pipeline. Settings are resolved in this order, from highest (first) to lowest priority (last):
- CLI:
CLI flags>dataset registry overrides>YAML config file>model defaults - SDK:
SDK builder calls>YAML config file>model defaults
Each layer only overrides what it explicitly sets -- everything else falls through to the next layer.
Unknown Configuration Keys¶
Safe Synthesizer rejects unknown configuration keys recursively by default.
This catches misspelled sections and parameters before a run starts, for
example evaluate instead of evaluation or training.epoch when no such
training parameter exists.
Set unknown_fields: ignore at the top level only when a configuration must
pass between mismatched client and service versions that may not recognize the
same fields:
The default is unknown_fields: reject. The setting applies to the same
configuration input in which it appears and is preserved in serialized
configurations. It controls unknown keys only; normal Pydantic value validation
and type coercion are unchanged. Undeclared fields cannot be retained because
Safe Synthesizer would not act on them.
Examples¶
Start from model defaults, override one field via CLI:
Use a YAML base for most settings, tune one field per run without editing the file:
Load a YAML base from Python, override a section with the builder:
from nemo_safe_synthesizer.sdk.library_builder import SafeSynthesizer
from nemo_safe_synthesizer.config import SafeSynthesizerParameters
config = SafeSynthesizerParameters.from_yaml("config.yaml")
synthesizer = (
SafeSynthesizer(config)
.with_data_source("data.csv")
.with_generate(num_records=2000, temperature=0.8) # overrides config.yaml values
)
synthesizer.run()
Note
Parameters that accept "auto" cannot be set to "auto" via CLI flags --
omit the flag to use the default, or set it in YAML.
See Using YAML Config Files with the CLI and SDK for more detail on combining config files with runtime overrides.
Python Parameter Construction¶
SafeSynthesizerParameters.from_params() accepts three forms of keyword name:
- top-level fields such as
generationorreplace_pii; - canonical dotted paths such as
generation.num_records; and - bare nested names such as
num_records, when that name is unique in the configuration schema.
Python syntax requires dotted names to be passed through ** expansion:
from nemo_safe_synthesizer.config import SafeSynthesizerParameters
config = SafeSynthesizerParameters.from_params(
generation={"temperature": 0.8}, # top-level section
num_records=2000, # unique bare leaf
**{"generation.structured_generation.enabled": True}, # dotted path
)
An ambiguous bare name raises an error and lists the accepted dotted paths. For
example, enabled appears in more than one section, so specify the intended
path:
Sparse Sources and Explicit Values¶
Absence, explicit None, and an explicit value equal to the model default are
different inputs. An absent field inherits the next lower-precedence source or
its model default. None is applied when the field accepts it, and an explicitly
supplied default value still counts as an override.
SDK section methods accept a sparse model or mapping as their source. Keyword arguments have higher precedence than that source, while omitted source fields retain the current lower-precedence configuration values:
Set an SDK-wide compatibility policy when constructing the builder so it applies before any raw section mapping is validated:
A mapping is a branch only when its schema field is another Pydantic model. Mapping-valued leaf fields, such as free-form dictionaries, are replaced as one atomic value rather than recursively merged.
Persistence with exclude_unset=True follows Pydantic's explicit-field
metadata. Sparse model sources also inspect nested explicit fields recursively,
so an in-place mutation such as
source.validation.group_by_fix_unordered_records = True is captured when that
model is used as a patch input. Unrelated defaults remain implicit.
Raw mapping sources follow the effective top-level unknown_fields setting.
They reject unknown extra keys by default and discard them when the policy is
ignore. After a name has been resolved to a canonical path,
however, that path remains strict: unknown paths and paths that descend through
an atomic leaf raise an error.
Resume-Time Overrides¶
When generation resumes from a saved training run, runtime configuration may
override only generation, evaluation, emit_telemetry, and
unknown_fields. Telemetry and the unknown-field policy are overridden only
when the runtime input explicitly sets them. An explicit
unknown_fields: ignore is applied while loading the saved configuration,
allowing unrecognized fields to be discarded when reading configuration files
from older versions. Fields that Safe Synthesizer has removed, such as
training.warmup_ratio, still raise an error under this policy.
Saved training, data, privacy, PII replacement, time-series, and preflight
settings remain unchanged.
Runs trained with a release before 0.2.0 saved the previous replace_pii
format (globals and steps), which is no longer supported, so generating
from them fails with an error about the v2 schema, even with
unknown_fields: ignore. See Replacing PII for the current
format and migrate the saved configuration, or train the run again.
Training¶
NeMo Safe Synthesizer fine-tunes a pretrained language model on your tabular data
using LoRA (Low-Rank Adaptation). See
TrainingHyperparams
for the full field list.
| Field | Default | Description | Guidance |
|---|---|---|---|
training.learning_rate |
"auto" |
Initial learning rate for the AdamW optimizer. "auto" selects a model-specific default (Mistral: 1e-4, others: 5e-4) |
Leave at "auto" for most cases; override with a float in (0, 1) to tune manually |
training.batch_size |
1 |
Per-device batch size | Leave at 1; increase gradient_accumulation_steps for a larger effective batch |
training.gradient_accumulation_steps |
8 |
Steps to accumulate before a backward pass; effective batch size = batch_size x this value |
8--32 typical |
training.num_input_records_to_sample |
"auto" |
Records the model sees during training -- proxy for training time ("auto" or int) |
First knob to increase if quality is low |
training.lora_r |
32 |
LoRA rank; lower values produce fewer trainable parameters | 16--64 typical; 32 is a reasonable default |
training.lora_alpha_over_r |
1.0 |
LoRA scaling ratio (alpha / rank) | Leave at 1.0 |
training.pretrained_model |
"HuggingFaceTB/SmolLM3-3B" |
HuggingFace model ID or local path | See supported families below; TinyLlama/TinyLlama-1.1B-Chat-v1.0 for fast CPU/low-VRAM iteration |
training.quantize_model |
false |
Enable quantization to reduce VRAM usage | Enable if VRAM is limited; 8-bit has lower quality impact than 4-bit |
training.quantization_scheme |
"bnb-8bit" |
Quantization scheme: bnb-4bit, bnb-8bit, fp8, nvfp4, mxfp4 |
See Quantization schemes below |
training.attn_implementation |
"sdpa" |
Attention backend for model loading | Leave at default |
training.rope_scaling_factor |
"auto" |
Scale the base model's context window via RoPE ("auto" or int) |
Leave at "auto" |
training.validation_ratio |
0.0 |
Fraction of training data held out for validation loss monitoring | Leave at 0.0 unless you specifically want to monitor validation loss |
training.max_vram_fraction |
0.8 |
Fraction of total GPU VRAM to allocate for training. Must be in [0, 1] | Lower if other GPU consumers are active on the same device |
validation_ratio vs holdout
training.validation_ratio splits the training data to monitor
validation loss during fine-tuning. data.holdout splits the full
dataset to create a test set used by the evaluation stage. They serve
different purposes and are applied at different stages.
Safe Synthesizer has explicit support (prompt templates, RoPE scaling,
tokenizer handling) for the model families listed below. Models outside this
list will raise a ValueError at startup.
We have extensively tested the following models for synthetic data use in NSS, and encourage you to start with SmolLM3-3B (the default).
| Family | HuggingFace ID |
|---|---|
| SmolLM3 (default) | HuggingFaceTB/SmolLM3-3B |
| TinyLlama | TinyLlama/TinyLlama-1.1B-Chat-v1.0 |
| Mistral | mistralai/Mistral-7B-Instruct-v0.3 |
Benchmarking data for additional models will be added as they are validated. To understand the trade-offs with model selection, see Training.
When training.pretrained_model is set to a Hugging Face Hub model ID, the model is downloaded from the Hub; if a local path or an offline cache is provided, no download is performed. See Pre-Caching Models for details.
Security Note: Pretrained models from Hugging Face Hub
Loading and using pretrained models from Hugging Face Hub (or any public source) can expose your environment to significant risks, including arbitrary code execution (ACE) or remote code execution (RCE) vulnerabilities. Only use models you have reviewed yourself or from organizations and authors you explicitly trust. Malicious or modified models may contain embedded code, backdoors, or privacy-leaking mechanisms.
Quantization schemes¶
When training.quantize_model: true, Safe Synthesizer applies one of the
following quantization schemes via transformers v5's
quantization_config= interface:
| Scheme | Backend | Bits/param | Hardware | Notes |
|---|---|---|---|---|
bnb-4bit |
bitsandbytes NF4 + bf16 compute | 4 | Ampere+ (sm_80+) | Lowest VRAM of the bitsandbytes schemes. LoftQ-compatible. |
bnb-8bit |
bitsandbytes int8 | 8 | Ampere+ (sm_80+) | Default. Higher quality than 4-bit; uses ~2x the VRAM. LoftQ-compatible. |
fp8 |
FineGrainedFP8Config |
8 | Hopper (sm_90+) / Blackwell | Float8 with block-wise scaling. Inference-leaning. |
nvfp4 |
TorchAoConfig(NVFP4WeightOnlyConfig()) |
4 | Blackwell (sm_100+) | Weight-only NVIDIA FP4. Requires recent torchao. |
mxfp4 |
Mxfp4Config |
4 | Varies by torch/torchao version | OCP Microscaling FP4. |
Select a scheme with training.quantization_scheme:
LoftQ + non-BNB schemes
peft_implementation: loftq is incompatible with fp8, nvfp4, and
mxfp4 — LoftQ requires the bitsandbytes runtime. Setting both will
raise a ParameterError at startup. Use qlora or lora with the
non-BNB schemes.
Generation¶
The generation stage controls how the fine-tuned model produces synthetic
records. See
GenerateParameters
for the full API reference.
| Field | Default | Description | Guidance |
|---|---|---|---|
generation.num_records |
1000 |
Number of synthetic records to generate | Match or exceed input dataset size for best quality |
generation.temperature |
0.9 |
Sampling temperature; lower values produce more predictable, less varied output | 0.7--1.1 typical; lower if output is noisy, higher if too repetitive |
generation.top_p |
1.0 |
Nucleus sampling probability | Leave at 1.0; lower (e.g. 0.9) to reduce tail tokens |
generation.repetition_penalty |
1.0 |
Penalty for repeated tokens; increase slightly if generation produces repetitive output | 1.0--1.15 typical; start at 1.05 if repetition is a problem |
generation.patience |
3 |
Consecutive bad batches before stopping | Leave at default |
generation.invalid_fraction_threshold |
0.8 |
Invalid record fraction that triggers the patience counter | Leave at default |
generation.structured_generation.enabled |
false |
Enable structured output to constrain record format (typically at the cost of reducing the quality of generated records and increasing generation time; use when the pipeline struggles to produce valid records) | Leave off unless the pipeline cannot produce valid records |
generation.structured_generation.backend |
"auto" |
vLLM guided-decoding backend | Leave at "auto" |
generation.structured_generation.schema_method |
"auto" |
Schema method ("auto", "structural_tag", "json_schema", or "regex") |
Leave at "auto"; it picks "structural_tag" on xgrammar-capable backends and "regex" otherwise |
generation.structured_generation.use_single_sequence |
false |
Match exactly one sequence when max_sequences_per_example is 1 |
Leave at default |
generation.enforce_timeseries_fidelity |
false |
Enforce time series order, intervals, and timestamps | Enable for time series data |
generation.attention_backend |
"auto" |
vLLM attention backend | Leave at "auto" |
Advanced group-by validation knobs live under generation.validation:
| Knob | Default | Effect |
|---|---|---|
group_by_accept_no_delineator |
false |
Treat raw JSONL without BOS/EOS markers as a single group instead of rejecting |
group_by_ignore_invalid_records |
false |
Drop invalid records from a group and keep the rest, rather than discarding the whole group |
group_by_fix_non_unique_value |
false |
Normalize the group-by column to the first record's value when records disagree |
group_by_fix_unordered_records |
false |
Re-sort records instead of rejecting out-of-order groups |
See Example Generation -- Validation
for guidance on when to enable each knob, and
GenerateParameters
for the full API reference.
Replacing PII¶
PII replacement runs before training and changes only the training split. It
is on by default; set replace_pii: null, pass --no-replace-pii, or call
.with_replace_pii(enable=False) to turn it off. For what it does, see
PII Replacement; for editing plans and
setting up samplers, see Customizing PII Replacement.
| Field | Default | Description | Guidance |
|---|---|---|---|
replace_pii.replacement_plan |
"auto_discovery" |
"auto_discovery", an inline plan, or the path of a plan YAML file (relative to the configuration file) |
Run --plan-only first, review the plan, then point this at the plan file |
replace_pii.locale |
"en_US" |
Locale of generated values and of the Nemotron-Personas dataset | Must match the downloaded datasets/<locale>.parquet |
replace_pii.seed |
null |
Seed for generated values, not for plan discovery, whose LLM can return a different plan on each run; when unset, each run draws a random seed and saves it in the run's safe-synthesizer-config.yaml |
Leave unset; to repeat a run's replacements, reuse its saved configuration, which also fixes the plan. Anyone who knows the seed can test guesses for original values in the replaced data, so keep that configuration as private as the input data |
replace_pii.sampler.backend |
unset | nemotron-personas or faker; unset uses Nemotron-Personas when downloaded, else Faker |
Set faker for locales without a Nemotron-Personas dataset |
replace_pii.sampler.nemotron_personas_path |
NSS_NEMOTRON_PERSONAS_PATH or ~/.data-designer/managed-assets |
Directory containing datasets/ |
Leave at default |
replace_pii.llm.model_id |
null |
Planning model; without an endpoint, selects a local planning model (default Nemotron 3.5 Lightning) | With NSS_INFERENCE_ENDPOINT, set this, NSS_INFERENCE_MODEL, or --inference-model-id |
replace_pii.llm.max_workers |
8 |
Concurrent planning requests | Leave at default; lower it if a hosted service rate-limits requests |
replace_pii.free_text_detection.entity_thresholds |
tuned per type | Minimum GLiNER2 confidence per entity type | Lower one type to catch more of it |
replace_pii.free_text_detection.name_exclusion_thresholds |
tuned labels | Labels for terms often mistaken for names; a name overlapping one is not replaced | Labels you set merge into the defaults; null drops a label |
replace_pii.free_text_detection.find_and_replace |
true |
Also replace known values the detector missed (en_US only) |
Leave on |
replace_pii.free_text_detection.batch_size |
8 |
GLiNER2 batch size | Reduce on GPU out-of-memory |
The planning endpoint and API key are set at runtime, never in YAML;
see Environment Variables -- PII Replacement.
See ReplacePiiConfig
for the full field list, including the free-text model, revision, and chunking
settings.
Differential Privacy¶
Differential privacy (DP) provides a formal bound on what an adversary can learn about any individual record. Safe Synthesizer implements DP-SGD (Differentially Private Stochastic Gradient Descent) via Opacus.
| Field | Default | Description | Guidance |
|---|---|---|---|
privacy.dp_enabled |
false |
Enable DP-SGD training | Enable for formal privacy guarantees |
privacy.epsilon |
8.0 |
Privacy budget -- lower values give stronger privacy | 4.0--12.0 typical; values below 4.0 may make convergence difficult |
privacy.delta |
"auto" |
Privacy failure probability ("auto" or float) |
Leave at "auto" |
privacy.per_sample_max_grad_norm |
1.0 |
Max L2 norm for per-sample gradients | Leave at 1.0 |
Compatibility constraints:
data.max_sequences_per_examplemust be1(or"auto", which resolves to1when DP is enabled) -- must be 1 to limit each example's contribution to the gradient, which DP requires- Safe Synthesizer disables gradient checkpointing automatically when DP is enabled -- no user action required (gradient checkpointing is incompatible with Opacus)
See DifferentialPrivacyHyperparams
for the full field list. For DP error diagnostics, see
Synthetic Data Quality.
Data¶
| Field | Default | Description | Guidance |
|---|---|---|---|
data.holdout |
0.05 |
Fraction (0--1) or absolute count (>1) for the holdout test set for evaluation | 0.05--0.15 typical |
data.max_holdout |
2000 |
Upper cap on holdout size | Leave at default for most datasets |
data.random_state |
null |
Random seed -- auto-generated if null; set an explicit integer for reproducible splits |
Set to a fixed integer for reproducibility |
data.group_training_examples_by |
null |
Column to group records by | Use for multi-row entities (e.g. patient ID, session ID) |
data.order_training_examples_by |
null |
Column to order within groups (requires data.group_training_examples_by) |
In time-series mode, prefer time_series.timestamp_column; if both are set they must match |
data.max_sequences_per_example |
"auto" |
Max sequences per example (1 for DP, null for time series, 10 otherwise). null lets each example fill the context window. DP and time-series mode cannot be enabled together. |
Leave at "auto" |
See DataParameters
for the full field list.
Time Series¶
Experimental
Time series synthesis is an experimental feature. APIs and behavior may change between releases.
| Field | Default | Description | Guidance |
|---|---|---|---|
time_series.is_timeseries |
false |
Enable time series mode | Enable for datasets with sequential time-ordered records |
time_series.timestamp_column |
null |
Timestamp field | Required unless an interval is provided |
time_series.timestamp_interval_seconds |
null |
Interval in seconds; must match the data when set | Required without a timestamp field; leave unset for irregular intervals |
time_series.timestamp_format |
null |
strftime or "elapsed_seconds" |
Leave null to infer |
time_series.start_timestamp |
null |
Override start timestamp for all groups (inferred from data if null) |
Leave null to infer from data |
time_series.stop_timestamp |
null |
Override stop timestamp for all groups (inferred from data if null) |
Leave null to infer from data |
Groups do not need equal lengths, common start and stop timestamps, or a consistent interval; Safe Synthesizer adapts to differently shaped groups automatically. Null, unparseable, or otherwise invalid timestamps remain data errors.
In time-series mode, time_series.timestamp_column and
data.order_training_examples_by play the same role: both name the column
that orders records within a group. You can set either one, or both if they
are identical; differing values are a configuration error. Prefer
timestamp_column, which also works for a single ungrouped series;
order_training_examples_by requires data.group_training_examples_by. When
only order_training_examples_by is set together with
timestamp_interval_seconds, that column is treated as the timestamp.
time_series.timestamp_interval_seconds is an assertion: if the spacing of
your timestamps does not match it, the run fails with
timestamp_interval_mismatch. Leave it unset to allow irregular intervals.
See TimeSeriesParameters
for the full schema. For detailed descriptions and constraints, see the
Time Series README.
Evaluation¶
| Field | Default | Description | Guidance |
|---|---|---|---|
evaluation.enabled |
true |
Master switch for evaluation | Leave enabled |
evaluation.mia_enabled |
true |
Membership Inference Attack (MIA) -- privacy risk assessment | Disable to speed up evaluation if privacy assessment is not needed |
evaluation.mia_excluded_columns |
null |
Columns to leave out of the MIA | Useful when identifiers were already replaced outside Safe Synthesizer, or are expected to repeat verbatim in the synthetic data |
evaluation.aia_enabled |
true |
Attribute Inference Attack (AIA) -- measures whether an attacker can infer a sensitive attribute from quasi-identifiers in the synthetic data | Disable to speed up evaluation if AIA is not needed |
evaluation.pii_replay_enabled |
true |
PII replay detection -- checks whether PII from training appears in synthetic data | With PII replacement off, evaluation still runs PII planning to find the PII, on the local planning model or at NSS_INFERENCE_ENDPOINT; set to false to skip it |
evaluation.sqs_report_columns |
250 |
Max columns in the Synthetic Quality Score (SQS) report | Increase if your dataset has more columns |
evaluation.sqs_report_rows |
5000 |
Max rows in the SQS report | Increase for larger datasets (impacts report generation time) |
evaluation.quasi_identifier_count |
3 |
Number of quasi-identifiers sampled for AIA (auto-reduced for small datasets) | Leave at default |
evaluation.mandatory_columns |
null |
Number of mandatory columns that must be used in evaluation | Leave at default |
evaluation.time_series.enabled |
null |
Add time-series metrics to evaluation and the HTML report. null follows time_series.is_timeseries |
Set false to skip in time-series mode; true requires time_series.is_timeseries: true |
evaluation.time_series.autocorrelation.value_columns |
null |
Numeric columns included in Autocorrelation Similarity | Leave null for inferred numeric columns or provide an explicit list |
evaluation.time_series.autocorrelation.max_lag |
20 |
Largest positive lag requested | Select a horizon relevant to the downstream use case |
evaluation.time_series.autocorrelation.min_points |
4 |
Minimum finite observations required per sequence | Leave at default unless short sequences must be excluded |
evaluation.time_series.autocorrelation.max_groups |
128 |
Maximum shared groups evaluated in a reproducible sample | Lower to reduce evaluation time for highly grouped data |
See EvaluationParameters
for the full API reference. See
Autocorrelation Similarity
for calculation and interpretation guidance.
Validate and Modify Configuration¶
config validate¶
Check your config for errors and display the merged parameters:
safe-synthesizer config validate --config config.yaml
safe-synthesizer config validate --config config.yaml --training__learning_rate 0.001
Fields set to "auto" remain as "auto" in the output -- auto-resolution
happens at runtime during process_data(), not at validation time. To see
resolved values, check safe-synthesizer-config.json in the run directory
after a pipeline run.
config modify¶
Modify a configuration and optionally save the result:
safe-synthesizer config modify --config config.yaml --training__learning_rate 0.001 --output modified.yaml
| Option | Description |
|---|---|
--config |
Path to YAML config file (optional -- omit to build from overrides only) |
--output |
Path to write modified YAML config (prints JSON to stdout if omitted) |
config create¶
Create a new configuration from defaults:
safe-synthesizer config create --output config.yaml
safe-synthesizer config create --training__pretrained_model "HuggingFaceTB/SmolLM3-3B" --output config.yaml
| Option | Description |
|---|---|
--output / -o |
Path to write YAML config (prints JSON to stdout if omitted) |
CLI Override Syntax¶
Use double underscores to address nested fields:
safe-synthesizer run --config config.yaml --data-source data.csv \
--training__learning_rate 0.001 \
--data__holdout 0.1 \
--generation__num_records 5000
Override precedence
CLI overrides > dataset registry overrides > YAML config file > model
defaults. See Configuration Precedence for
examples. Parameters that accept "auto" cannot be set to "auto" via
CLI flags -- omit the flag to use the default, or set it in YAML.
Configuration Sections¶
| YAML Key | SDK Method | API Reference |
|---|---|---|
data |
with_data() |
DataParameters |
training |
with_train() |
TrainingHyperparams |
generation |
with_generate() |
GenerateParameters |
evaluation |
with_evaluate() |
EvaluationParameters |
replace_pii (null to disable) |
with_replace_pii() |
ReplacePiiConfig |
privacy (null to disable) |
with_differential_privacy() |
DifferentialPrivacyHyperparams |
time_series |
with_time_series() |
TimeSeriesParameters |
- Running Safe Synthesizer -- pipeline execution and examples
- Environment Variables -- infrastructure and cache settings
- Program Runtime -- runtime errors and OOM fixes