Introduction

Nucleus Edge es el componente on-premise que se instala para trabajar con los datos directamente dentro de tu propio entorno. Esta sección proporciona una guía práctica para su instalación y uso. Todas las opciones y parámetros disponibles se describen en el Manual de Referencias.

Descripción general

Nucleus Edge proporciona un conjunto reducido de funciones de Python:

El flujo habitual de generación de datos sintéticos es el siguiente: entrenar un sintetizador con synthesizer(...) → obtener el archivo del sintetizador → subirlo a la plataforma → generar datos sintéticos localmente con sample(...) o en la nube. También puedes anonimizar documentos, imágenes y archivos de audio directamente con anonymize(...). En todos los casos, los datos originales nunca salen de tu entorno.

Instalación

Nucleus Edge se distribuye como un paquete de Python y debe instalarse en un entorno con Python 3. Se recomienda utilizar Python 3.11, aunque también son compatibles las versiones 3.9 y 3.10.

# Crear y activar un entorno virtual aislado (recomendado)

python -m venv .venv

source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Instalar el paquete de Nucleus proporcionado por Dedomena.AI

pip install nucleus-4.10.2-DEV.tar.gz

GPU (opcional). El entrenamiento y la generación de datos se ejecutan por defecto en CPU. Para utilizar una GPU, instala Nucleus Edge en un equipo con una GPU NVIDIA compatible y pasa el parámetro cuda=True a las funciones correspondientes. El uso de GPU ofrece mayores beneficios cuando se trabaja con columnas de texto libre.

Conexión a IBM Db2 (opcional). Para leer datos desde Db2, descarga el controlador JDBC y colócalo en la carpeta DB2Driver dentro del directorio de instalación de Nucleus (consulta la sección Orígenes de datos compatibles).

Requisitos del sistema y del hardware

Software

• Sistema operativo: Se recomienda Linux (x86-64) y es obligatorio para las funcionalidades basadas en GPU. Las tareas tabulares (generación de datos sintéticos y anonimización de tablas) también pueden ejecutarse en CPU bajo Windows y macOS.

• Python: 3.9–3.11 (se recomienda 3.11).

• Controlador de GPU: para utilizar cualquier funcionalidad acelerada por GPU, se requiere un controlador NVIDIA actualizado compatible con CUDA 12.1 o superior.

Requisitos según la tarea

Especificaciones de la GPU — necesarias para anonimizar documentos, imágenes y archivos de audio (y para el procesamiento de texto libre)

Estas funcionalidades utilizan modelos de inteligencia artificial que se ejecutan en la GPU. Se requiere una GPU NVIDIA con las siguientes características:

• Arquitectura: Ampere o superior, con CUDA Compute Capability 8.0 o superior (por ejemplo, NVIDIA A100, L4, L40S, RTX A6000, RTX 6000 Ada o tarjetas más recientes basadas en Hopper o Blackwell).

• Memoria de vídeo (VRAM): 24 GB como mínimo; se recomiendan 48 GB o más, especialmente para documentos e imágenes de alta resolución, donde se ejecutan simultáneamente un modelo de visión y un modelo de lenguaje.

• CUDA: un controlador NVIDIA compatible con CUDA 12.1 o superior.

• Memoria RAM del sistema: 32 GB o más.

• Espacio en disco: mantener al menos 30 GB libres para almacenar los archivos de los modelos, que se descargan y almacenan en caché la primera vez que se utilizan estas funcionalidades (descarga única).

Para ejecutar las funciones de Nucleus Edge utilizando la GPU, pasa el parámetro `cuda=True a las funciones correspondientes.

> If no compatible GPU is available, you can still use Nucleus Edge for synthetic data and table anonymization on CPU. Anonymizing documents, images, and audio — and transforming free text — requires a GPU.

Autenticación

Todas las funciones de Nucleus Edge requieren un token proporcionado por Dedomena.AI. Este token autentica y autoriza el uso del componente, y debe pasarse como parámetro en cada llamada a las funciones:

from nucleus.synthesizer import synthesizer

TOKEN = "your-dedomena-token"

synthesizer(

    token=TOKEN,

    data_format="CSV",

    data_dir="data/customers.csv",

    # ...

)

Mantén el token fuera del control de versiones (por ejemplo, utilizando una variable de entorno o un gestor de secretos). El mismo token se utiliza para todas las funciones de Nucleus Edge.

Orígenes de datos compatibles

Nucleus Edge accede a los datos mediante los parámetros data_format y data_dir. Se admiten los siguientes formatos de entrada:

Bases de datos. Cuando data_format="DATABASE", asigna a data_dir la URL de conexión y usa query para indicar el nombre de una tabla o proporcionar una consulta SQL completa. Para IBM Db2, descarga el driver JDBC, colócalo en la carpeta DB2Driver dentro de la ruta de instalación de Nucleus y usa una URL con el siguiente formato:

jdbc:db2://\<host\>:\<port\>/\<database_name\>:sslConnection=true;user=\<userid\>;password=\<password\>;

Drivers JDBC de Db2: https://www.ibm.com/support/pages/db2-jdbc-driver-versions-and-downloads

Formatos de salida (sample): CSV, EXCEL, PARQUET o DATAFRAME (devuelve el resultado directamente en memoria como un DataFrame de pandas).

Anonimización

La anonimización y los datos sintéticos son operaciones independientes, con entradas y resultados distintos, por lo que se describen por separado.

Con Edge puedes anonimizar tablas y archivos no estructurados (documentos, imágenes y audio) directamente en tu máquina; en todos los casos la salida es un nuevo archivo anonimizado, listo para usar. También puedes proteger columnas sensibles de una tabla mientras entrenas un sintetizador.

Anonimizar tablas

Usa anonymize() para anonimizar también una tabla estructurada. Igual que al entrenar un sintetizador, la apuntas a una tabla (un archivo o una conexión a base de datos); la diferencia está en lo que se obtiene: el entrenamiento produce un modelo reutilizable, mientras que la anonimización produce un nuevo archivo con tus datos ya protegidos. Pasas una configuración que asigna a cada columna sensible el método que se debe aplicar; Edge transforma esas columnas y deja el resto intacto.

from nucleus.anonymize import anonymize

anonymize(

    token=TOKEN,

    data_format="CSV",

    data_dir="data/customers.csv",

    config=\{

        "full_name":   "simulation",  # columna de texto

        "email":       "mask",        # columna de texto

        "national_id": "hash",        # columna de texto

        "salary":      "perturb",     # columna numérica

        "birth_date":  "generalize",  # columna de fecha

    \},

    output_filename="customers_anonymized.csv",

    output_format="CSV",

)

La configuración funciona exactamente igual que para los archivos: la clave es el nombre de la columna y el valor es el método (forma corta) o \{"method": ..., "type": ...\} (forma extendida). El método debe ser válido para el tipo de dato de la columna: las columnas numéricas aceptan perturb, generalize, shuffle, mask, hash; las columnas de texto o categóricas aceptan mask, simulation, pseudonym, coding, hash, shuffle; y así sucesivamente (consulta Métodos de anonimización). Pasa config="auto" para aplicar el método por defecto a cada columna sensible detectada durante el análisis. Las tablas se pueden leer desde CSV, PARQUET o una conexión DATABASE, y escribirse de nuevo como CSV, EXCEL o PARQUET.

Anonimizar documentos, imágenes y audio

Usa anonymize() para proteger un archivo no estructurado. Pasas la ruta al archivo y una configuración que indica, para cada elemento sensible, qué método aplicar. Edge analiza el archivo, detecta los elementos sensibles que contiene y aplica el método que hayas elegido a todos los elementos de ese tipo, dejando el resto del archivo intacto. El archivo anonimizado se escribe en la ruta de salida que especifiques.

from nucleus.anonymize import anonymize

anonymize(

    token=TOKEN,

    data_dir="documents/id_card.png",

    config=\{

        "face":        "blur",       # elemento visual

        "signature":   "redact",     # elemento visual

        "person_name": "mask",       # elemento de texto

        "id_number":   "coding",     # elemento de texto

        "birth_date":  "generalize", # elemento de texto

    \},

    output_filename="id_card_anonymized.png",

    cuda=True,

)

El diccionario de configuración. Cada clave es el nombre de un elemento sensible y cada valor es el método que se le aplica. Usa la forma corta ("face": "blur") cuando el método no necesita opciones, o la forma extendida cuando quieras pasar opciones; por ejemplo, el tipo de variable para simulation:

config=\{

    "person_name": \{"method": "simulation", "type": "name"\},

    "email":       \{"method": "simulation", "type": "email"\},

    "id_number":   \{"method": "mask"\},

\}

El método que elijas debe ser válido para el canal del elemento: los elementos visuales aceptan blur, pixelate, redact; los elementos de texto aceptan mask, coding, simulation, pseudonym, hash; los elementos de audio aceptan beep, silence, remove (consulta Métodos de anonimización y Anonimización consistente entre activos relacionados). Para que Edge anonimice cada elemento detectado con su método por defecto, pasa config="auto".

Documentos (PDF):

anonymize(

    token=TOKEN,

    data_dir="documents/contract.pdf",

    config=\{

        "person_name": "pseudonym",

        "address":     "mask",

        "iban":        "hash",

    \},

    output_filename="contract_anonymized.pdf",

)

Audio:

anonymize(

    token=TOKEN,

    data_dir="calls/support_call.mp3",

    config=\{

        "person_name":  "beep",

        "phone_number": "beep",

        "address":      "silence",

    \},

    output_filename="support_call_anonymized.mp3",

)

Modo automático: detecta todo y aplica el método por defecto a cada elemento:

anonymize(

    token=TOKEN,

    data_dir="documents/id_card.png",

    config="auto",

    output_filename="id_card_anonymized.png",

)

Entradas admitidas:

Parámetros:

> Reversibilidad. Los métodos que conservan un mapeo (pseudonym, simulation, mask, generalize) también escriben un archivo de mapeo, de modo que un administrador autorizado pueda revertirlos más adelante. Los demás métodos son irreversibles. Consulta Métodos de anonimización.

Generación de datos sintéticos

Generar datos sintéticos con Edge es un proceso de dos pasos: entrenar un sintetizador y después generar filas a partir de él.

Paso 1 — Entrenar (synthesizer). Produce un archivo de sintetizador en output_dir.

from nucleus.synthesizer import synthesizer

synthesizer(

    token=TOKEN,

    data_format="CSV",

    data_dir="data/transactions.csv",

    algorithm="generic",

    epochs=200,

    batch_size=256,

    amplify="quality",              # mejora la fidelidad (requiere epochs \>= 150)

    categorical_columns=["category", "channel"],

    integer_columns=["age"],

    float_columns=["amount"],

    date_columns=\{"txn_date": "%Y-%m-%d"\},

    id_columns=\{"customer_id": r"ID_\d\{4\}"\},

    target="category",

    output_dir="results",

    synthesizer_name="tx_v1",

    synthesizer_description="Sintetizador de transacciones, modo calidad",

)

Paso 2 — Generar (sample). Carga el sintetizador y escribe filas sintéticas.

from nucleus.sample import sample

sample(

    token=TOKEN,

    model_dir="results/tx_v1.zip",

    n_rows=100_000,

    output_filename="synthetic_transactions.parquet",

    output_format="PARQUET",

)

Generación condicional. Pasa ratios para dar forma a la salida (consulta Datos sintéticos en la Guía de Cloud y Parámetros de generación):

sample(

    token=TOKEN,

    model_dir="results/tx_v1.zip",

    n_rows=50_000,

    ratios=\{"gender": \{"F": 1, "M": 0\}, "is_fraud": \{"1": 1, "0": 0\}\},  # solo mujeres Y fraude

    output_format="DATAFRAME",

)

Subida de sintetizadores

El archivo de sintetizador que produce synthesizer() (y retrain_synthesizer()) es lo que se envía a la plataforma. Como contiene todo lo necesario para generar datos —y está protegido—, puede transferirse y almacenarse de forma segura.

1. Entrena en local con synthesizer(...); localiza el archivo escrito en output_dir.

2. Sube el archivo a la plataforma (mediante la aplicación web o la API).

3. Una vez subido, el sintetizador queda disponible para generar datos sintéticos desde la aplicación web y la API, y ningún dato original ha salido de tu entorno.

4. Para mantener un sintetizador actualizado a medida que cambian tus datos de origen, reentrénalo (más abajo) y sube el nuevo archivo.

Reentrenamiento (retrain_synthesizer): continúa el entrenamiento de un sintetizador existente con nuevos datos. El parámetro forgetfulness_factor controla cuánto del entrenamiento anterior se conserva (0 = conservarlo todo, 1 = empezar de cero):

from nucleus.retrain_synthesizer import retrain_synthesizer

retrain_synthesizer(

    token=TOKEN,

    model_dir="results/tx_v1.zip",

    data_dir="data/transactions_new_month.csv",

    data_format="CSV",

    epochs=250,

    forgetfulness_factor=0.0,       # conserva todo lo aprendido hasta ahora

    output_dir="results",

)

Evaluación

El entrenamiento ya ejecuta la evaluación automática e incluye el informe junto con el sintetizador. Edge también te permite evaluar cualquier par de conjuntos de datos real y sintético cuando lo necesites y generar el informe tú mismo.

Tabla única (synthesizer_evaluations):

from nucleus.evaluations import synthesizer_evaluations

privacy, quality, utility = synthesizer_evaluations(

    token=TOKEN,

    real_data="data/real.parquet",

    synthetic_data="data/synth.parquet",

    data_format_real="PARQUET",

    data_format_synth="PARQUET",

    categorical_columns=["city", "category"],

    integer_columns=["age"],

    float_columns=["amount"],

    date_columns=["txn_date"],

    target="category",

    output_dir="report",            # escribe report/report.html

    synthesizer_name="tx_v1",

    verbose=True,

)

print(privacy, quality, utility)

La función devuelve las tres puntuaciones y escribe un informe HTML en output_dir. Las tablas con menos de tres columnas utilizables se omiten.

Múltiples tablas (synthesizer_evaluations_multitable): recibe una configuración por tabla y produce un único informe combinado; consulta Parámetros de evaluación.

Ejemplos en Python

A. Sintetizador transaccional con anonimización de descripciones

from nucleus.synthesizer import synthesizer

from nucleus.sample import sample

TOKEN = "your-dedomena-token"

synthesizer(

    token=TOKEN,

    data_format="PARQUET",

    data_dir="data/bank_tx.parquet",

    algorithm="transactional",

    epochs=250,

    batch_size=256,

    columns_mapping=\{

        "user_id": "client_id",

        "concept": "description",

        "amount": "amount_eur",

        "txn_date": "date",

        "balance": "balance_eur",

    \},

    balance_updated=True,

    transform_descriptions="level2",   # anonimiza nombres/direcciones/ciudades en el texto

    date_columns=\{"date": "%Y-%m-%d"\},

    float_columns=["amount_eur", "balance_eur"],

    categorical_columns=["category"],

    datasets_country="Spain",

    output_dir="results",

    synthesizer_name="bank_tx_v1",

)

sample(token=TOKEN, model_dir="results/bank_tx_v1.zip",

       n_rows=200_000, output_filename="synth_bank_tx.parquet")

B. Sintetizador de series temporales

from nucleus.synthesizer import synthesizer

synthesizer(

    token=TOKEN,

    data_format="CSV",

    data_dir="data/sensor_series.csv",

    algorithm="timeseries",

    epochs=300,

    time_step="D",                 # una observación por día

    series_length=365,             # 365 pasos diarios por serie

    static_columns=["device_type", "region"],

    float_columns=["temperature", "humidity"],

    date_columns=["timestamp"],

    columns_mapping=\{"user_id": "device_id", "txn_date": "timestamp"\},

    output_dir="results",

    synthesizer_name="sensors_v1",

)

C. Sintetizador relacional (multitabla)

from nucleus.synthesizer import synthesizer

datasets_config = \{

    "customers": \{

        "data_dir": "data/customers.csv", "data_format": "CSV",

        "algorithm": "generic",

        "categorical_columns": ["segment"], "integer_columns": ["age"],

        "primary_key": "customer_id", "foreign_key": \{\},

        "sensitive": \{"name": "name"\},

    \},

    "orders": \{

        "data_dir": "data/orders.parquet", "data_format": "PARQUET",

        "algorithm": "transactional",

        "columns_mapping": \{"user_id": "customer_id", "txn_date": "order_date",

                            "concept": "item", "amount": "total"\},

        "date_columns": ["order_date"], "float_columns": ["total"],

        "primary_key": "order_id", "foreign_key": \{"customer_id": "customers"\},

    \},

\}

synthesizer(

    token=TOKEN, algorithm="relational",

    datasets_config=datasets_config,

    epochs=200, datasets_country="Spain",

    output_dir="results", synthesizer_name="shop_v1",

)

D. Generar en un DataFrame en memoria

from nucleus.sample import sample

df = sample(token=TOKEN, model_dir="results/shop_v1.zip",

            n_rows=10_000, output_format="DATAFRAME")

print(df.head())

Manual de referencia

Este manual recoge las opciones disponibles en Nucleus Edge, agrupadas por finalidad. Las mismas opciones están disponibles cuando entrenas y generas en Cloud.

Parámetros comunes

Opciones compartidas por synthesizer(), sample(), retrain_synthesizer(), anonymize() y las funciones de evaluación.

Parámetros genéricos

Opciones principales de entrenamiento para generic (compartidas por transactional y timeseries cuando resultan aplicables).

Sintaxis de las restricciones (constraints):

Parámetros transaccionales

Opciones adicionales para algorithm="transactional".

Niveles de transform_descriptions:

• None: las descripciones se mantienen tal cual.

• level1: sustituye fechas, números de tarjeta, números de cuenta (IBAN) e importes en el texto.

• level2: todo lo de level1, más nombres de personas, direcciones y ciudades.

• level3: todo lo de level2, más nombres de comercios, sustituidos por alternativas verosímiles de un sector similar (p. ej., McDonald's → Burger King; Iberia → Air Europa).

Parámetros de series temporales

Opciones adicionales para algorithm="timeseries".

Parámetros relacionales

Para algorithm="relational", describe tus tablas con datasets_config: un diccionario con una entrada por tabla.

NUCLEUS mantiene coherentes los vínculos entre tablas para que las claves sigan coincidiendo en el resultado sintético. El entrenamiento relacional requiere 150 o más pasadas de entrenamiento.

Parámetros de generación

Opciones para sample() y retrain_synthesizer().

sample()

retrain_synthesizer() (además de los parámetros comunes)

Parámetros de evaluación

synthesizer_evaluations() (tabla única)

Devuelve las tres puntuaciones: (privacy, quality, utility).

synthesizer_evaluations_multitable() recibe una configuration con una entrada por tabla (cada una con sus datos reales y sintéticos, tipos de columna, columnas sensibles opcionales y target) y produce un único informe combinado con puntuaciones globales.

Parámetros de anonimización

Opciones para anonymize(), que anonimiza una tabla, un documento, una imagen o un archivo de audio. La salida es un nuevo archivo anonimizado (no un modelo). Consulta Anonimización en la sección de Nucleus Edge para ver ejemplos.

Entradas admitidas: tablas (CSV, Parquet, conexión a base de datos), imágenes (PNG, JPG/JPEG, TIFF, BMP), documentos (PDF, DOCX) y audio (WAV, MP3, M4A, FLAC).