Skip to content

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:

unknown_fields: ignore
training:
  batch_size: 4

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:

safe-synthesizer run --data-source data.csv --generation__num_records 2000

Use a YAML base for most settings, tune one field per run without editing the file:

safe-synthesizer run --config config.yaml --data-source data.csv \
  --training__learning_rate 0.001

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 generation or replace_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:

SafeSynthesizerParameters.from_params(
    **{"generation.structured_generation.enabled": True}
)

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:

synthesizer.with_generate({"temperature": 0.8}, num_records=2000)

Set an SDK-wide compatibility policy when constructing the builder so it applies before any raw section mapping is validated:

synthesizer = SafeSynthesizer(unknown_fields="ignore")

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:

training:
  quantize_model: true
  quantization_scheme: nvfp4   # or bnb-4bit / bnb-8bit / fp8 / mxfp4

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_example must be 1 (or "auto", which resolves to 1 when 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