🔐 NeMo Safe Synthesizer Tutorial: Differential Privacy¶
Learn how to apply differential privacy to achieve strong privacy with mathematical guarantees. This tutorial demonstrates how to configure differential privacy parameters for optimal results. The runtime of this notebook is about 1 hour on an A100.
If you have not yet completed the Safe Synthesizer 101 tutorial, consider starting there first.
🖥️ Prerequisites¶
This notebook requires a Linux machine with an NVIDIA GPU (H100 recommended, A100 minimum) and CUDA 12.9+. It will not run on macOS, Windows, or Apple Silicon.
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
import sys
# The override resolves a flashinfer-python pin conflict between vLLM and NeMo Safe Synthesizer.
!echo "flashinfer-python==0.7.0.post1" | uv pip install --python "{sys.executable}" \
"nemo-safe-synthesizer[engine,cu129]==0.2.0" \
-c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/v0.2.0/constraints.txt \
--overrides - \
--find-links https://flashinfer.ai/whl/cu129/flashinfer-jit-cache/ \
--find-links https://flashinfer.ai/whl/flashinfer-cubin/ \
--find-links https://wheels.vllm.ai/0.32.0/cu129/vllm/ \
--find-links https://download.pytorch.org/whl/cu129/torch/ \
--find-links https://download.pytorch.org/whl/cu129/torchaudio/ \
--find-links https://download.pytorch.org/whl/cu129/torchvision/ \
--find-links https://download.pytorch.org/whl/cu129/torchcodec/ \
--find-links https://download.pytorch.org/whl/cu129/torchao/ \
--find-links https://download.pytorch.org/whl/cu129/triton/
import sys
# Packages this tutorial uses besides NeMo Safe Synthesizer.
!uv pip install --python "{sys.executable}" kagglehub
🔑 Choose where PII planning runs¶
Before training, NeMo Safe Synthesizer replaces personally identifiable information (PII), and an LLM decides which columns contain it. By default, NeMo Safe Synthesizer runs that LLM in a temporary vLLM server on this machine's GPU, so no API key is needed and the data stays on this machine. The local model needs an 80 GB GPU and downloads about 66 GB the first time it runs.
To use a hosted service instead, such as the NVIDIA API at https://integrate.api.nvidia.com/v1, set NSS_INFERENCE_ENDPOINT, NSS_INFERENCE_MODEL, and NSS_INFERENCE_KEY in the next cell. You can obtain an API key from build.nvidia.com. Column samples are then sent to that service. See Where planning requests go for details.
import os
# Optional: plan with a hosted service instead of a local vLLM server.
# import getpass
# os.environ["NSS_INFERENCE_ENDPOINT"] = "https://integrate.api.nvidia.com/v1"
# os.environ["NSS_INFERENCE_MODEL"] = "nvidia/nemotron-3-ultra-550b-a55b"
# os.environ["NSS_INFERENCE_KEY"] = getpass.getpass("Paste inference API key: ")
if os.environ.get("NSS_INFERENCE_ENDPOINT"):
print(f"PII planning sends requests to {os.environ['NSS_INFERENCE_ENDPOINT']}")
else:
print("PII planning runs a local vLLM server on this machine's GPU")
📥 Load and preview sample dataset¶
Load a tabular dataset—in this example, the US Accidents dataset from Kaggle—and preview the first few rows. NeMo Safe Synthesizer will use a subset to keep runtime manageable.
This dataset includes text, categorical, and numeric fields, all of which are supported by Safe Synthesizer.
The code below also computes a recommended delta for differential privacy. Delta should reflect the full dataset size, not the subset, because it bounds the probability of a privacy breach across the entire population. See Differential Privacy for parameter guidance.
Dataset citations:
- Moosavi, Sobhan, Mohammad Hossein Samavatian, Srinivasan Parthasarathy, and Rajiv Ramnath. "A Countrywide Traffic Accident Dataset.", 2019.
- Moosavi, Sobhan, Mohammad Hossein Samavatian, Srinivasan Parthasarathy, Radu Teodorescu, and Rajiv Ramnath. "Accident Risk Prediction based on Heterogeneous Sparse Data: New Dataset and Insights." In proceedings of the 27th ACM SIGSPATIAL International Conference on Advances in Geographic Information Systems, ACM, 2019.
Each user is responsible for checking the content of the dataset and the applicable licenses and determining if it is suitable for the intended use.
import pandas as pd
import kagglehub
path = kagglehub.dataset_download("sobhanmoosavi/us-accidents")
print("Path to dataset files:", path)
df = pd.read_csv(f"{path}/US_Accidents_March23.csv", index_col=0)
full_data_size = len(df)
recommended_delta = 1 / (full_data_size ** 2) # delta should reflect the full dataset, even when a subset is used as Safe Synthesizer input
print(f"Full dataset size: {len(df)} records")
print(f"Recommended delta: {recommended_delta:.2e}")
# use a subset as Safe Synthesizer input for faster runtime
df = df.sample(n=26250, random_state=318)
print(f"Input dataset size: {len(df)} records")
df.head()
⚙️ Create and run Safe Synthesizer job¶
Create the Safe Synthesizer builder and attach your DataFrame. Enable differential privacy and configure the training and generation stages for optimal performance with DP.
Run the pipeline with run(), which performs data processing, PII replacement, training, generation, evaluation and saving of results in a single call. Results are available on builder.results.
from nemo_safe_synthesizer.sdk.library_builder import SafeSynthesizer
ARTIFACT_ROOT = "safe-synthesizer-artifacts/differential-privacy"
builder = (
SafeSynthesizer(save_path=ARTIFACT_ROOT)
.with_data_source(df) # .with_replace_pii(enable=False) to disable PII replacement
.with_differential_privacy(dp_enabled=True, delta=recommended_delta)
.with_train(batch_size=4, gradient_accumulation_steps=32) # Override the default batch size of 1, which is designed for non-DP training
.with_generate(structured_generation={'enabled': True}) # Improves the percentage of valid records when DP is enabled
)
builder.run()
results = builder.results
📤 Retrieve synthetic data¶
Inspect the generated synthetic data including row count and preview of the first rows.
synth = results.synthetic_data
print(f"Number of synthetic rows: {len(synth)}")
synth.head()
# Synthetic data and evaluation report are automatically saved to the artifacts directory
print(f"Artifacts automatically saved to: {builder._workdir.generate.path}")
🛡️ Review evaluation report¶
The pipeline computes both quality and privacy metrics. The summary includes timing information and overall scores, while the full evaluation report is rendered as an HTML document.
import json
print("Summary (timing and scores):")
print(json.dumps(results.summary.model_dump(), indent=2))
# View the evaluation report in a sandboxed iframe
import html
from IPython.display import display
report_html = results.evaluation_report_html
if report_html:
# srcdoc, not a data: URL: Chrome blanks data: URLs over 2 MB, and the base keeps the report's #section links in the frame.
report_doc = report_html.replace("<head>", '<head><base href="about:srcdoc">', 1)
frame = (
f'<iframe srcdoc="{html.escape(report_doc)}" sandbox="allow-scripts allow-popups" '
'width="100%" height="800"></iframe>'
)
# Raw display: HTML() warns about a bare <iframe>, and IFrame() cannot take srcdoc.
display({"text/html": frame}, raw=True)