Customizing PII Replacement¶
This guide shows how to review and edit the PII replacement plan, choose where synthetic values come from, tune free-text detection, and choose the model that builds the plan. For what PII replacement does and why, see PII Replacement. For a list of every setting, see Configuration Reference -- Replacing PII.
Turn Replacement Off¶
Set replace_pii: null in YAML, pass --no-replace-pii on the command line, or
call .with_replace_pii(enable=False) in the SDK.
The PII replay check in the evaluation still needs to know which values are
PII, so evaluation runs PII planning on the training data. Planning uses the
local planning model, or sends samples to NSS_INFERENCE_ENDPOINT when it is
set; see Where planning requests go.
Set evaluation.pii_replay_enabled: false to skip it.
Review and Reuse the Plan¶
The replacement plan lists the columns to replace, the kind of PII in each, an optional format pattern, and which columns each replacement must agree with. Create it without running anything else:
The command writes two files to a new timestamped run directory under
--artifact-path:
pii_replacement_plan.yaml: the plan. This is the file to review and edit.safe-synthesizer-config.yaml: a complete configuration that names the plan file and records the sampler used. Pass it to a later run with--config.
A full pipeline run writes the same two files to its run directory.
In the SDK, plan_pii_replacement() returns the resolved ReplacePiiConfig.
When you pass an output path, it writes the configuration there and
pii_replacement_plan.yaml beside it:
from nemo_safe_synthesizer.config import SafeSynthesizerParameters
from nemo_safe_synthesizer.sdk.library_builder import SafeSynthesizer
config = SafeSynthesizerParameters.from_yaml("config.yaml")
resolved_pii = (
SafeSynthesizer(config)
.with_data_source("data.csv")
.plan_pii_replacement("safe-synthesizer-config.yaml")
)
To reuse the reviewed plan, run the saved safe-synthesizer-config.yaml
again, since it already names the plan file. To point a different
configuration at the plan, set replace_pii.replacement_plan in its YAML, or
in the SDK call .with_replace_pii(replacement_plan="pii_replacement_plan.yaml");
its other replace_pii settings, such as locale, are kept.
The Review the PII Replacement Plan tutorial walks through this end to end.
Plan Sources¶
replace_pii.replacement_plan takes one of three forms.
Automatic discovery¶
auto_discovery, the default, builds the plan with an LLM (see
Planning LLM). Row counters, such as a saved Unnamed: 0
index column, are skipped, and so are the columns named in
data.order_training_examples_by and time_series.timestamp_column. The
grouping column can be replaced, so identifiers such as patient IDs are
anonymized.
Discovery matches values in your data to the sampler's values (see
Value mappings), so set replace_pii.sampler before
discovering the plan.
Inline plan¶
Write the plan directly in the configuration. An inline plan makes no LLM request, so this is how to replace PII without an LLM:
replace_pii:
replacement_plan:
columns_to_replace:
- column_name: full_name
entity_type: full_name
pattern: "{First} {Last}"
- column_name: email
entity_type: email
pattern: "{f}.{last}@{domain}"
depends_on:
- column_name: full_name
data_to_sampler_value_mapping: {}
Plan file¶
Give the path of a YAML file holding the same fields, such as the
pii_replacement_plan.yaml from a plan-only run:
A relative path in a configuration file is resolved against that file's
directory. A path given on the command line
(--replace_pii__replacement_plan) or through the SDK is resolved against the
working directory.
Plans you write are checked less strictly
Safe Synthesizer validates every plan against the data, but a plan you write is allowed to run where a discovered plan would not. For example, a pattern that fits fewer than 99% of a column's values is dropped from a discovered plan but kept, with a warning, in a plan you write. Value mapping problems stop every plan with an error: a mapping entry the sampler cannot use, or a dependency value with no mapping entry and no sampler match.
Entity Types¶
Each column in the plan has an entity_type. Types marked "kept" are never
replaced, so they cannot appear in columns_to_replace. Of those, gender,
ethnic_background, and organization can appear in depends_on; the rest
are only recognized by discovery so it does not mistake them for PII.
| Entity type | Replaced | Pattern syntax |
|---|---|---|
first_name, middle_name, last_name, full_name |
Yes | Name template |
email |
Yes | Name template |
phone_number |
Yes | Character mask |
credit_debit_card, api_key, unique_identifier |
Yes | Character mask |
date_of_birth |
Yes, shifted by days or weeks | Date format |
street_address, national_id, ipv4, ipv6 |
Yes | None |
free_text |
PII inside the text | None |
gender, ethnic_background, organization |
Kept | None |
date, city, state, zipcode, country |
Kept | None |
Patterns¶
A column's optional pattern sets the format of its replacement values. It
should match at least 99% of the column's non-null values. Values the pattern
does not fit still get replacements written in the pattern. If pattern is
left out, the entity's default format is used; an empty pattern is rejected.
Name templates, for names and email, combine literal text with placeholders,
such as {First} {Last} or {f}.{last}@{domain}:
{first},{middle},{last}: the name part in lowercase.{First}writes it in title case and{FIRST}in uppercase, and likewise for middle and last.{f},{m},{l}: the part's lowercase initial;{F},{M},{L}write it in uppercase.{domain},{organization}: email only. The original email's domain (a synthetic one when the original has none), and the value of an organization dependency written as a domain label. An email pattern must contain@, and#writes one random digit.
A full name without a pattern keeps the original's professional titles and
suffixes, such as Dr. and Jr., and drops forms of address such as Mr. and
Mrs.. A full name with a pattern is written exactly as the pattern says:
{First} {Last} writes no title, and Dr. {First} {Last} writes Dr. in
every value.
Character masks, for phone numbers, card numbers, API keys, and identifiers,
write one random character per token and copy everything else, so pmc-######
produces values like pmc-482913:
#is a digit,^an uppercase letter,@a lowercase letter,&a digit or uppercase letter,%a digit or lowercase letter, and*a digit or letter.[01]is one character from the brackets. Brackets list characters, not ranges, soCUST-10[01]###starts withCUST-100orCUST-101.\makes the next token or bracket literal, so\#writes#. A]without an opening[is rejected; write it as\].
A phone number keeps its country code and its area code, or a mobile number's
network prefix, and gets random digits for the rest, so (415) 555-2671
becomes a value like (415) 830-4417. Where the area code ends depends on the
country, and at most half of the national number is kept. A number written
without a country code is read as a number of the locale's country. Without a
pattern, the replacement is written like the original, including any extension.
With a character mask, the mask's fixed characters are written and the area
code fills the placeholders under it. A phone value without digits, such as
unknown or -, is left unchanged.
Date formats, for date_of_birth, use Python strftime codes such as
%m/%d/%Y or %B %d, %Y. Prose and ordinal forms such as December 10th are
not supported.
Dependencies¶
A column's depends_on lists other columns of the same record that its
replacement must agree with. A dependency works in one of two ways:
- A column that is not replaced, such as
sexorrace, steers what the sampler draws and keeps its original value. A first name that depends onsexcomes from a persona of that sex. Give such a column'sentity_type,genderorethnic_background, independs_on. - A column that is replaced passes on its new value. An email that depends on
first_nameandlast_nameis built from their replacements, and a first name that depends on a full-name column takes the first name of the replaced full name.
Only these dependencies are allowed:
- First and middle names: gender, ethnic background, or a full name.
- Last names: ethnic background or a full name.
- Full names: gender and ethnic background.
- Email addresses: first, middle, last, or full name, and organization.
A name that depends on a full name cannot also depend on gender or ethnic background, and an email depends on either name parts or a full name, not both.
Value Mappings¶
A dependency column's values must be ones the sampler understands. Matching
ignores case, and common gender spellings (F, Woman, Girl, M, Man,
Boy) are mapped automatically. Any other value needs an entry in
data_to_sampler_value_mapping. Automatic discovery fills it in for you; in a
plan you write, add entries keyed by the dependency column's name:
replace_pii:
replacement_plan:
columns_to_replace:
- column_name: first_name
entity_type: first_name
depends_on:
- column_name: sex
entity_type: gender
- column_name: race
entity_type: ethnic_background
data_to_sampler_value_mapping:
sex:
Non-binary:
- female
- male
race:
Asian:
- east asian
- south asian
- southeast asian
Black or African American:
- black
Each list allows any of the sampler values it names. Gender values are female
and male for every sampler; Nemotron-Personas also accepts its locale's own
words, such as femme in fr_FR. Ethnicity values exist only in
Nemotron-Personas, for locales whose dataset has them, such as en_US.
The mapping is checked against each run's sampler and locale. If you switch either, rerun automatic discovery or edit the entries.
Samplers¶
The sampler generates replacement values. Set it with
replace_pii.sampler.backend. When you leave it unset, Safe Synthesizer uses
Nemotron-Personas if the dataset for your locale is downloaded, and Faker
otherwise, with a warning. The exception is a discovered plan that matches on
ethnic background, which only Nemotron-Personas supports: it fails instead.
Nemotron-Personas¶
Nemotron-Personas are NVIDIA datasets of synthetic people, one per locale,
whose names, sex, ethnic background, and addresses follow that locale's census
distributions. The nemotron-personas sampler draws names and, for en_US,
street addresses from them, so names look like the locale's real population
and can match the record's gender and ethnic background. Emails come from
Faker.
Downloading a dataset requires an NGC API key and the NGC CLI. Data Designer's person-sampling setup explains how to get both and lists the available locales. Safe Synthesizer reads datasets from the same directory as Data Designer, so a dataset already downloaded for Data Designer needs no further setup.
Download a specific version of the resource for your locale. Safe Synthesizer
was tested with version 0.0.2 of the
en_US resource,
and a later version may rename columns:
ngc registry resource download-version \
nvidia/nemotron-personas/nemotron-personas-dataset-en_us:0.0.2
mkdir -p "${HOME}/.data-designer/managed-assets/datasets"
cp nemotron-personas-dataset-*/*.parquet \
"${HOME}/.data-designer/managed-assets/datasets/"
The sampler loads datasets/<locale>.parquet, so replace_pii.locale must
match the file name, such as en_US for en_US.parquet. To store the files
elsewhere, set NSS_NEMOTRON_PERSONAS_PATH or
replace_pii.sampler.nemotron_personas_path to the directory containing
datasets/.
If you set backend: nemotron-personas and the dataset is missing, the run
fails rather than switching to Faker.
Faker¶
Set backend: faker to generate every value with
Faker, without downloading a dataset. Faker
supports many more locales
than Nemotron-Personas and applies gender dependencies, but it cannot match
ethnic background.
Free-Text Detection¶
Columns planned as free_text are scanned with the GLiNER2 model
fastino/gliner2-privacy-filter-PII-multi plus regex checks for email
addresses, payment cards, and IP addresses. Only the detected PII is replaced.
GLiNER2 needs a CUDA GPU; see
GLiNER2 Device and Throughput
for memory and speed tuning.
The defaults favor precision: a word is replaced only when the model is very confident it is PII. The settings you are most likely to change are:
entity_thresholds: minimum confidence per entity type. Lower a value to catch more PII of that type, at the cost of replacing more words that are not PII.name_exclusion_thresholds: labels for terms often mistaken for names, such as medical conditions and family relationships. A detected name overlapping one of these is not replaced, unless it is a value already known in the record. Labels you set are added to the defaults or change their thresholds; set a label tonullto drop it. Dropping every default label turns exclusion off, for text where missed names matter more than false ones.find_and_replace: whentrue(the default,en_USonly), a value already known in the record, such as the original first name, is also replaced wherever it appears in free text, even if the model missed it. Short values and common English words, such asWillorJune, are skipped.batch_size: reduce it if GLiNER2 runs out of GPU memory.
replace_pii:
free_text_detection:
entity_thresholds:
first_name: 0.9
find_and_replace: true
batch_size: 8
Entity types you leave out of entity_thresholds keep their defaults. See
FreeTextDetectionConfig
for every field and default.
Locales Other Than en_US¶
replace_pii.locale sets the locale of generated values, but parts of
replacement were built and tuned for English text and US conventions:
- Free-text detection was tuned on English text. The default GLiNER2 checkpoint covers English, French, Spanish, German, Italian, Portuguese, and Dutch, and it needs spaces between words, so most PII in Chinese, Japanese, Korean, or Thai sentences is not detected.
- Name handling in free text knows mostly English titles and suffixes. It reads
French
M.as a first-name initial and a Spanish second surname, as inAna García López, as a middle name. - Email addresses built from generated names keep accented and non-Latin
letters, such as
françois.prévost42@example.com. - Full street addresses keep their city and postal code only when the street comes first; other address orders are replaced whole.
find_and_replaceruns only foren_US.
Planning LLM¶
Automatic discovery uses an LLM to classify columns, propose patterns, choose
dependencies, and map values. By default, Safe Synthesizer starts
nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16 in a temporary vLLM server on
this machine's GPU and stops it before replacement and training begin. No API
key is needed and the data stays on this machine. The first run downloads
about 66 GB of weights into the Hugging Face cache.
To use a hosted or self-hosted endpoint instead, set NSS_INFERENCE_ENDPOINT;
see Environment Variables -- Where planning requests go.
Local inference server¶
Safe Synthesizer can run two planning models locally. Each needs one GPU with at least 75 GiB of memory, such as an 80 GB A100 or H100. Without vLLM or a large enough GPU, planning fails with an error before downloading anything, rather than sending data elsewhere.
Choose a planning model with replace_pii.llm.model_id, --inference-model-id,
or NSS_INFERENCE_MODEL:
| Model ID | Request timeout | Notes |
|---|---|---|
nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16 (default) |
300 s | Performed well in our evaluation |
openai/gpt-oss-120b |
120 s | Performed well in our evaluation; fastest |
Override the request timeout for very large tables with NSS_INFERENCE_TIMEOUT
or --inference-timeout-seconds. Override request fields, such as the thinking
budget, with NSS_INFERENCE_REQUEST_OPTIONS or --inference-request-options,
for example {"thinking_token_budget": 500}.
To run another model locally, point NSS_INFERENCE_LOCAL_PROFILE or
--inference-local-profile at your own profile YAML. If you also set
replace_pii.llm.model_id or NSS_INFERENCE_MODEL, it must match the
profile's served model name, which defaults to its model_id. A profile has
model_id and revision, plus optional vLLM settings such as
gpu_memory_utilization, max_model_len, tensor_parallel_size,
min_gpu_memory_gib, extra_args, request_options, environment, and the
request, startup, and shutdown timeouts. The built-in profiles in
src/nemo_safe_synthesizer/pii_replacer/local_inference/profiles/ are good
starting points; if you set thinking_token_budget, copy their environment
settings too. Avoid extra_args that make vLLM compile kernels at startup, such as
--mamba-backend=flashinfer: a Safe Synthesizer install has no CUDA compiler.
replace_pii.llm.max_workers (default 8) sets how many planning requests run
at once.
Reuse one server across runs¶
Each run starts the planning model again, which takes about a minute and a half
even after the first download. When you plan or replace PII many times, for
example while refining a plan, start the server once yourself and point Safe
Synthesizer at it. This command starts the same server as the default profile,
nemotron-3.5-lightning-30b-a3b.yaml in
src/nemo_safe_synthesizer/pii_replacer/local_inference/profiles/; if the
two ever differ, follow the profile.
# The V1 model runner keeps the thinking budget working.
VLLM_USE_V2_MODEL_RUNNER=0 vllm serve nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16 \
--revision a9904d24bcc1d289a1950fa9d2b978c47cf903b9 \
--host 127.0.0.1 --port 8000 \
--gpu-memory-utilization 0.95 \
--max-model-len 32768 \
--max-num-seqs 8 \
--mamba-ssm-cache-dtype=float16 \
--reasoning-parser=nemotron_v3 \
--default-chat-template-kwargs='{"enable_thinking": true}'
Run it in the Python environment where Safe Synthesizer is installed, which
includes vLLM. The server is ready when
curl -s http://127.0.0.1:8000/v1/models lists the model. Then set these
variables where you run Safe Synthesizer:
export NSS_INFERENCE_ENDPOINT=http://127.0.0.1:8000/v1
export NSS_INFERENCE_MODEL=nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16
export NSS_INFERENCE_TIMEOUT=300
export NSS_INFERENCE_REQUEST_OPTIONS='{"temperature": 1.0, "top_p": 0.95, "thinking_token_budget": 4000}'
Keep the last two lines. With an endpoint, Safe Synthesizer applies none of the
profile's settings, so without them each request times out after 60 seconds
and the model reasons without a token budget. In a notebook, set the same
values in os.environ before planning starts.
- The server holds 95% of the GPU's memory until you stop it with Ctrl-C, so
use it for
plan_pii_replacement(),replace_pii(), andsafe-synthesizer run replace-pii. Stop it, and unsetNSS_INFERENCE_ENDPOINT, before training or generating on the same GPU. - Binding to
127.0.0.1keeps the data on this machine, but any user of the machine can call the server. To require a key, start the server withVLLM_API_KEYset and setNSS_INFERENCE_KEYto the same value.
Standalone Replacement¶
Replace PII in a complete dataset without holdout, training, generation, or evaluation:
Use standalone replacement to check the plan
Standalone replacement is for reviewing and refining PII replacement before a full run, not a privacy step on its own. It replaces only the kinds of PII it knows and can miss PII in free text, so its output can still identify people. Run the full pipeline to produce data you share.
safe-synthesizer run replace-pii \
--config config.yaml \
--data-source data.csv \
--output-file pii_replaced.csv
The output is Parquet when its path ends in .parquet, and CSV otherwise.
Without --output-file, the command writes <input name>_pii_replaced.csv to
the run directory, or .parquet for Parquet input, such as
data_pii_replaced.csv for data.csv. The plan and configuration files are
always written, as in Review and Reuse the Plan.
The SDK equivalent returns a TransformResult and writes only the files you
name:
result = (
SafeSynthesizer(config)
.with_data_source("data.csv")
.replace_pii(
"pii_replaced.csv",
config_output_path="safe-synthesizer-config.yaml",
)
)
How Replacement Works Internally¶
For the exact rules -- how replacements stay consistent and distinct, how
discovery batches and retries LLM requests, which detector owns which entity
type, and how the local server is isolated -- see
PII Replacement Internals
in design.md.