Introducción

Dedomena Edge es la versión on-premise de la plataforma Dedomena.AI: una librería de Python que instalas en tus propios servidores para validar la calidad de tus datasets, detectar datos sensibles, anonimizarlos y entrenar sintetizadores para generar datos sintéticos, sin que tus datos salgan nunca de tu infraestructura.

Esta guía explica cómo descargar e instalar Dedomena Edge, cómo se organiza, qué necesitas para ejecutarlo y cómo usar cada una de sus funciones. Al final encontrarás un manual de referencia con todos los comandos, variables y mensajes de error.

> Tus datos no salen de tu entorno. Edge solo se conecta con Dedomena.AI para descargar el paquete y los modelos. Detectar, anonimizar, entrenar y validar se hace siempre en tu máquina, y la licencia se comprueba en local, sin conexión.

Qué incluye Dedomena Edge

Edge reúne tres librerías bajo un mismo paquete de Python, dedomena:

Con ellas puedes trabajar con todos los tipos de activo:

Los nombres de los métodos de anonimización, los tipos de elementos sensibles y los algoritmos de síntesis son los mismos que en la plataforma Dedomena.AI en la nube. Una configuración escrita para la nube funciona igual en Edge.

Arquitectura y requisitos

Cómo se organiza una instalación

Una instalación de Edge tiene tres piezas, y las tres viven en tu infraestructura:

• La librería es el código que ejecutas desde Python. Se instala en un entorno virtual y procesa tus datos en local.

• Los modelos son los modelos de IA que usa la detección. Se descargan aparte del código y se guardan en una carpeta local. Puedes elegir su tamaño, o no usar ninguno (ver Tamaño de los modelos).

• La licencia es un token firmado que obtienes en la página Edge de la plataforma. La librería lo verifica en local, sin conectarse a nada.

La plataforma Dedomena.AI solo interviene para descargar el paquete, los modelos y el token desde la página Edge, y para darte los resultados cuando le subes los ficheros cifrados que producen tus flujos de trabajo: por ejemplo, los datos sintéticos generados a partir de un sintetizador que has entrenado con Edge (ver Generar datos).

Qué sale de tu máquina y qué no:

Módulos

El paquete se entrega por módulos: eliges los que necesitas y solo esos se instalan. Puedes elegir varios a la vez (por ejemplo, Texto + Imagen).

Algunas cosas a tener en cuenta:

• Axon va siempre incluido, elijas lo que elijas.

• Texto incluye Tablas: el modelo de lenguaje se usa también sobre las columnas de texto libre de las tablas.

• Si intentas usar algo que no está en tu paquete, la librería no falla con un error de Python: te dice que ese módulo no forma parte de tu instalación y qué módulos sí incluye.

Tamaño de los modelos: small, full o none

El paquete de código es el mismo para cualquier tamaño. El tamaño solo decide qué modelos se descargan:

Modelos que se descargan según el módulo y el tamaño:

• Con varios módulos se descarga la unión de sus modelos, sin repetir. Si va el modelo completo de un tipo, no se descarga además el ligero de ese mismo tipo.

• Imagen y audio necesitan siempre un modelo. Sin él no hay detección de imágenes ni transcripción, así que el tamaño none no se ofrece con esos módulos.

• Edición generativa de imágenes (opcional). Es un modelo adicional de unos 57,7 GB que sustituye los datos de una imagen por otros con un aspecto natural, en lugar de dibujarlos encima. Solo está disponible con el módulo Imagen y hardware GPU.

Requisitos del sistema

Sistema operativo y Python

CPU y memoria

GPU (solo para el hardware gpu)

Antes de cargar ningún modelo puedes comprobar si caben en tu tarjeta con models.report() (ver Qué motor se va a usar).

Disco

• Librería y dependencias: unos pocos GB (más en la variante GPU, que incluye las librerías de NVIDIA).

• Modelos: lo que indica la tabla de Tamaño de los modelos: small, full o none. Deja margen adicional para tus datos y resultados.

Red

• Instalación con pip: salida HTTPS a api.dedomena.ai y a los repositorios públicos de paquetes de Python durante la instalación.

• Descarga de modelos con dedomena-edge setup: salida HTTPS a api.dedomena.ai y a los servidores de descarga a los que redirige. Pide a Dedomena.AI la lista de dominios si tu cortafuegos trabaja con lista blanca.

• Instalación desde la descarga completa: la máquina de destino no necesita red.

• Uso: no hace falta red.

Qué combinación elegir

Descarga e instalación

Hay dos formas de instalar Edge. Las dos parten de la página Edge de la plataforma Dedomena.AI:

> Necesitas una cuenta de la plataforma con un plan que incluya Dedomena Edge. Si tu plan no lo incluye, la descarga responde que no tienes acceso a Edge: contacta con Dedomena.AI.

La página Edge

La página tiene tres bloques, de arriba abajo:

1. Las opciones del paquete: sistema operativo, módulos, hardware y tamaño de los modelos.

2. Tu token de licencia.

3. Las dos formas de instalar: Download e Install with pip.

Elegir las opciones

1. Sistema operativo: Linux.

2. Módulos: marca uno o varios. Los que van incluidos con otro se marcan solos y quedan bloqueados (por ejemplo, al marcar Texto se marca Tablas). Axon aparece siempre marcado. All instala todo.

3. Hardware:

   • CPU: para máquinas sin GPU. Instala las librerías de cálculo en su versión ligera para CPU.

   • GPU: para máquinas con GPU NVIDIA (CUDA 13, controlador 580 o superior).

4. Tamaño de los modelos: small, full o none (ver Tamaño de los modelos: small, full o none). La página desactiva las combinaciones que no son posibles:

   • full con hardware CPU, si eliges Texto, Imagen o All (esos modelos necesitan GPU);

   • none, si eliges Imagen, Audio o All (necesitan un modelo).

5. Edición generativa de imágenes (opcional): solo aparece con Imagen y hardware GPU.

Bajo el botón de descarga, la página indica qué lleva la descarga y cuánto pesan los modelos.

Tu token de licencia

El token es tu licencia de Edge. Lo necesitas para instalar y la librería lo usa cada vez que trabajas con ella. Es personal: no lo compartas ni lo subas a un repositorio de código.

• Show muestra el token y Copy lo copia.

• Generate new token genera uno nuevo. Úsalo cuando el actual caduque.

• Valid until indica la fecha de caducidad.

Los comandos de instalación de la página ya llevan tu token puesto. Más detalles en La licencia.

Opción A: descarga completa (sin internet en la máquina de destino)

1. Pulsa Download y elige una carpeta de tu ordenador.

   • En Chrome y Edge, el navegador va escribiendo los ficheros directamente en esa carpeta, comprueba cada uno y, si la descarga se corta, puedes retomarla donde se quedó.

   • En Firefox y Safari, la descarga se guarda como un único .zip. Si se corta, hay que empezarla de nuevo. Con modelos full (decenas de GB) te recomendamos Chrome o Edge.

2. Cuando termina tienes una carpeta dedomena-edge con este contenido:

   Elemento	Contenido
   install.sh	El instalador.
   wheels/	El paquete de Edge y todas sus dependencias, para Python 3.10, 3.11 y 3.12.
   models/	Los modelos elegidos. No existe con el tamaño none.

3. Copia la carpeta a la máquina donde vas a usar Edge, por el medio que uses habitualmente (SFTP, disco, repositorio interno…). Si descargaste un .zip, descomprímelo allí.

4. Instala:

   bash

   
   cd dedomena-edge
   
   bash install.sh \<TOKEN\>
   
   . ./env.sh          # cada vez que abras una sesión nueva, antes de usar la librería
   
   

Qué hace install.sh:

1. Elige dónde instalar (ver la tabla siguiente) y comprueba que la versión de Python es 3.10, 3.11 o 3.12.

2. Instala Edge desde ./wheels, sin conexión a internet.

3. Escribe env.sh, que activa el entorno virtual (si lo creó) y apunta la librería a la carpeta ./models (si hay modelos).

4. Guarda tu licencia en la máquina, para que la librería la encuentre sin que tengas que volver a pasarla.

5. Ejecuta dedomena-edge status, que muestra los módulos y modelos instalados.

Dónde instala:

Opciones adicionales:

• PYTHON=/ruta/a/python3.11 bash install.sh \<TOKEN\> usa un intérprete concreto.

• El token también puede ir en la variable DEDOMENA_TOKEN en lugar de como argumento.

• bash install.sh --help muestra la ayuda.

> Atención con conda. Si tu terminal activa automáticamente el entorno base de conda, el instalador lo considera «entorno activo» e instala ahí. Usa --venv si prefieres un entorno separado.

> No muevas la carpeta después de instalar. El entorno virtual y env.sh usan rutas absolutas, y los modelos se quedan en ./models. Si necesitas otra ubicación, copia la carpeta a su sitio definitivo antes de ejecutar install.sh.

Si algo falla durante la instalación:

Opción B: instalación con pip

1. Crea y activa un entorno virtual para Edge:

   bash

   
   python3.11 -m venv /opt/dedomena/venv
   
   . /opt/dedomena/venv/bin/activate
   
   

2. Instala el paquete con el comando que muestra la página. Ya lleva tus módulos, tu hardware y tu token:

   bash

   
   pip install --index-url "https://licence:\<TOKEN\>@api.dedomena.ai/edge/\<módulos\>/\<hardware\>/simple/" dedomena-edge
   
   

   • \<módulos\>: all, un módulo (tables, text, vision, audio, documents, axon) o varios unidos con + (por ejemplo text+vision). El orden no importa.

   • \<hardware\>: cpu o gpu.

   • El token va como contraseña del índice; el usuario (licence) es indiferente.

   Con hardware gpu y modelos full, instala además el motor de GPU que usan los modelos completos:

   bash

   
   pip install --index-url "https://licence:\<TOKEN\>@api.dedomena.ai/edge/\<módulos\>/gpu/simple/" "dedomena-edge[gpu]"
   
   

3. Descarga los modelos y guarda la licencia en la máquina:

   bash

   
   dedomena-edge setup --size small --token "\<TOKEN\>"     # o --size full / --size none
   
   

   setup lee qué módulos tiene tu instalación y descarga los modelos que necesitan para ese tamaño. Si una descarga se corta, vuelve a ejecutar el mismo comando: continúa donde se quedó. Cada fichero se verifica al terminar, y un modelo descargado a medias nunca se usa.

4. Comprueba la instalación:

   bash

   
   dedomena-edge status
   
   

Opciones de dedomena-edge setup:

Mensajes de setup que te pueden aparecer:

Errores de pip frecuentes:

Comprobar la instalación

dedomena-edge status

dedomena-edge 5.6.2

Modules    : axon, small, tables, text

Models dir : /home/usuario/.local/share/dedomena/models

GPU        : no

  small-text       1.0.0

• Modules muestra los módulos del paquete instalado. small es el código de los modelos ligeros, que acompaña a todo paquete con detección.

• Models dir es la carpeta donde la librería busca los modelos.

• Debajo aparece una línea por cada modelo instalado, con su versión.

Para ver la licencia:

python -c "import dedomena; print(dedomena.auth_status())"

Y para ver qué motor de detección usará cada modalidad y si los modelos caben en tu GPU:

python -c "from dedomena.detection import models; print(models.report())"

Actualizar, ampliar o cambiar la instalación

La licencia

La licencia es el token de la página Edge. Es un token firmado que lleva tu identificador, los permisos que tienes y su fecha de caducidad. La librería lo verifica en local, sin conectarse a nada, así que funciona en máquinas sin internet.

Guardar la licencia en la máquina

install.sh y dedomena-edge setup --token ya la guardan por ti. Si tienes que hacerlo a mano (por ejemplo, al renovarla):

import dedomena

dedomena.login("\<TOKEN\>", persist=True)   # la verifica y la guarda

dedomena.auth_status()

# Session(subject='...', scopes=('axon', 'detection', 'nucleus.anonymize', ...), expires=..., source=...)

A partir de ahí no tienes que pasar el token a ninguna función: todas lo encuentran solas.

• persist=True guarda el token en ~/.config/dedomena/token, con permisos solo para tu usuario. Sin persist=True, login() vale para la sesión de Python actual y no escribe nada en disco.

• dedomena.logout() cierra la sesión.

Dónde busca la librería el token

En este orden:

1. El argumento token= de la función que llamas.

2. La sesión abierta con dedomena.login(...).

3. La variable de entorno DEDOMENA_TOKEN.

4. El fichero de licencia guardado (~/.config/dedomena/token).

Contenedores, CI y gestores de secretos. Si tu política no permite guardar credenciales en disco, pasa el token por la variable DEDOMENA_TOKEN y define DEDOMENA_NO_PERSIST=1: la librería no escribirá nada en el directorio del usuario. Con DEDOMENA_CONFIG_DIR puedes cambiar la carpeta del fichero de licencia.

Permisos

El token indica qué puedes hacer:

Si intentas algo que tu licencia no cubre, la librería lo dice con el nombre de la actividad: Your Dedomena licence does not cover training a synthesizer. It covers: …. En ese caso, solicita a Dedomena.AI el permiso correspondiente.

Caducidad y renovación

• La fecha de caducidad aparece en la página (Valid until) y en dedomena.auth_status().

• 15 días antes de caducar, la librería avisa: Warning: Your Dedomena token expires on … (N day(s) left).

• Cuando caduca, las funciones dejan de ejecutarse con el mensaje Your Dedomena token expired on …. Genera un token nuevo en la página y guárdalo con dedomena.login("\<TOKEN_NUEVO\>", persist=True). No hace falta reinstalar nada.

• Atrasar el reloj del sistema no extiende la licencia.

Primeros pasos con la librería

Antes de empezar

Si instalaste con la descarga completa, carga el entorno en cada sesión nueva:

. /ruta/a/dedomena-edge/env.sh

Después:

import dedomena

print(dedomena.__version__)

from dedomena.nucleus import anonymize            # anonimización

from dedomena.nucleus import Auto, Generic        # sintetizadores

from dedomena.detection import detect             # detección

from dedomena.axon import Inspector, clean        # calidad de datos

import dedomena no carga nada pesado: cada librería se carga la primera vez que la usas.

Fuentes de datos

Todas las funciones que reciben datos aceptan las mismas fuentes:

Bases de datos. Se admiten PostgreSQL, MySQL/MariaDB, SQL Server, Oracle, SQLite e IBM Db2:

anonymize(

    "postgresql://usuario:contraseña@servidor:5432/crm",

    source_format="DATABASE",

    query="SELECT * FROM clientes WHERE alta \>= '2026-01-01'",

    config="auto",

    output="salida/clientes_anonimizados.parquet",

    output_format="PARQUET",

)

Si query es una sola palabra, se interpreta como nombre de tabla (SELECT * FROM "clientes").

IBM Db2. Descarga el controlador JDBC de IBM (db2jcc4.jar) y cópialo en la carpeta DB2Driver dentro del paquete instalado. Necesitas también un entorno de ejecución de Java en la máquina:

python -c "import dedomena, os; print(os.path.join(os.path.dirname(dedomena.__file__), 'DB2Driver'))"

La URL tiene esta forma:

jdbc:db2://\<host\>:\<puerto\>/\<base_de_datos\>:sslConnection=true;user=\<usuario\>;password=\<contraseña\>;

Controladores JDBC de Db2: <https://www.ibm.com/support/pages/db2-jdbc-driver-versions-and-downloads\>

El activo (Asset)

Casi todas las funciones devuelven un activo (dedomena.core.Asset): un objeto que lleva los datos y lo que se sabe de ellos.

Puedes pasar un activo de una función a otra: Axon prepara, la detección encuentra, Nucleus anonimiza o sintetiza, y el historial se conserva. Para guardarlo:

activo.save("salida/", data_format="CSV")   # salida/data.csv + salida/meta.json

Mensajes, registros y soporte

La librería no muestra trazas de error de Python. Cuando algo falla, verás una sola línea:

Dedomena error [3f9a1c02]: Failed to train the synthesizer.

Details were written to /ruta/logHistory.log

• DEDOMENA_LOG_FILE=/ruta/mi_log.log cambia la ubicación del registro. Es útil con varios trabajos en paralelo.

Si necesitas ayuda, envía a soporte el identificador del error ([3f9a1c02]), logHistory.log y, si existe, dedomena-support.enc.

Detección de elementos sensibles

La detección encuentra los datos sensibles de un activo y dice dónde están. La anonimización la ejecuta sola cuando hace falta, pero también puedes usarla directamente: para auditar qué datos tienes, revisar lo encontrado antes de anonimizar o alimentar tus propios procesos.

detect()

from dedomena.detection import detect

detect("documentos/dni.png")          # imagen

detect("documentos/contrato.pdf")     # PDF, DOCX o TXT

detect("llamadas/atencion.mp3")       # audio

detect(dataframe)                     # tabla: qué columna es de qué tipo

detect("Mi DNI es 12345678Z")         # texto libre

Devuelve una lista de elementos con la misma forma para todas las modalidades: el valor, su tipo y dónde está.

Requiere el permiso detection. Si tu paquete no incluye la modalidad del activo, la función te lo dice con el mensaje Detection for '…' is not part of this build.

Cómo se detecta

Edge combina varias capas, y siempre trabajan juntas:

• Patrones y validaciones (siempre activos): emails, teléfonos, DNI/NIE/CIF con su letra de control, IBAN con su dígito de control, tarjetas con su algoritmo de verificación, matrículas, direcciones IP… Ganan cualquier solapamiento: un número que supera su validación es un hecho.

• Modelos de IA (según el tamaño instalado): encuentran lo que ningún patrón alcanza, como nombres, empresas, direcciones escritas libremente, categorías especiales de datos (salud, religión, afiliación sindical…), rostros, firmas, logotipos y huellas.

• Lectura de texto en imágenes (en Imagen y en PDF escaneados): el texto de la imagen se lee y se analiza como cualquier otro texto, en español, inglés, euskera, catalán y gallego.

• Transcripción (en Audio): el audio se transcribe con marcas de tiempo por palabra, y la detección se aplica a la transcripción. Se recuperan también números dictados en palabras («seis, uno, dos…») cuando superan su validación.

La librería elige sola el mejor motor que tiene instalado para cada modalidad (ver Modelos: automáticos, registrados y propios). La forma del resultado no cambia con el motor, solo la cobertura.

> Sin modelo de imagen no hay detección de imágenes. Si tu paquete incluye Imagen y no has descargado ningún modelo, la primera imagen falla con un mensaje que indica el comando: dedomena-edge setup --size small. Así nunca se entrega una imagen revisada solo a medias.

Tipos de elementos sensibles

Cada elemento tiene un tipo: el código que usas en la configuración de la anonimización. Los tipos son los mismos que en la plataforma en la nube.

Para limitar la detección de texto a unos tipos concretos:

from dedomena.detection import detect_in_text

detect_in_text("Llama al 612 345 678 o escribe a ana@ejemplo.com", types=["phone_number"])

detect_in_text(texto, certain_only=True) devuelve solo los valores que han superado una validación (letra de control, dígito de control…).

Tablas: qué columna es de qué tipo

from dedomena.detection import detect_columns

detect_columns(dataframe)

# [\{'value': None, 'type': 'email', 'column': 'correo'\}, \{'value': None, 'type': 'dni', 'column': 'documento'\}, ...]

Necesita el módulo Tablas. Las columnas se clasifican por su nombre y por una muestra de sus valores.

Revisar y reutilizar una detección

Puedes detectar, revisar el resultado (o dárselo a revisar a una persona) y anonimizar después exactamente lo revisado, sin volver a detectar:

from dedomena.core import Asset

from dedomena.detection import detect

from dedomena.nucleus import anonymize

activo = Asset("documentos/dni.png")

activo.sensitive_elements = detect(activo)

activo.save_elements("revision/dni.elements.json")       # JSON para revisar o editar

# ... revisión ...

revisado = Asset.load_elements("revision/dni.elements.json")

anonymize(revisado, config="auto", output="salida/dni_anonimizado.png")

Un activo con sus elementos asignados se considera ya revisado: la anonimización no vuelve a detectar y no pisa la revisión.

Audio en lote

Para procesar muchos audios, usa las funciones de lote. Cada audio escribe su propio resultado, así que una tirada larga puede retomarse:

from dedomena.detection import audio

rutas = audio.discover("/datos/llamadas", recursive=True)

resultados = audio.detect_many(

    rutas,

    output_dir="/datos/salida/detecciones",   # un \<audio\>.detection.json por fichero

    types=\{"iban", "credit_card_number", "credit_card_security_code", "credit_card_expire"\},

    resume=True,                              # salta los ya procesados

    return_transcript=True,

    workers=1,

)

audio.write_summary(resultados, "/datos/salida/detecciones")

Para un solo fichero:

alineados, sin_alinear, transcripcion = audio.transcribe_and_detect(

    "llamada.mp3", language="es", return_transcript=True)

• alineados son los elementos con su intervalo de tiempo.

• sin_alinear son los valores detectados que no se pudieron situar en el tiempo. Se devuelven aparte para que nunca se pierdan en silencio.

• Si guardas la transcripción y sus marcas de tiempo, puedes repetir la detección con otros tipos sin volver a transcribir: audio.detect_in_transcript(transcripcion, palabras, types=…).

• device="auto" (por defecto) usa la GPU si está disponible para la transcripción ligera. device="cpu" la fuerza a CPU.

Anonimización

La anonimización modifica las partes sensibles de tus datos reales y deja todo lo demás exactamente como estaba. El resultado es un nuevo fichero anonimizado. Requiere el permiso nucleus.anonymize; la detección que hace por dentro no necesita el permiso detection.

Primer ejemplo

import dedomena

from dedomena.nucleus import anonymize

resultado = anonymize(

    "datos/clientes.csv",

    config="auto",                                   # detecta y aplica el método por defecto a cada elemento

    output="salida/clientes_anonimizados.csv",

    output_dir="resultados",                         # mapeo, registro e informe de conformidad

)

print(resultado.content)    # 'salida/clientes_anonimizados.csv'

anonymize() funciona igual con una tabla, una imagen, un documento o un audio: el tipo se deduce de la fuente.

Parámetros de anonymize():

Devuelve un Asset cuyo content es la ruta escrita (o el DataFrame, con output_format="DATAFRAME") y cuyo historial registra la anonimización.

La configuración

La configuración dice qué hacer con cada columna (en tablas) o con cada tipo de elemento (en imágenes, documentos y audio).

Modo automático. config="auto" detecta los elementos sensibles y aplica a cada uno el método por defecto de su tipo (ver Qué métodos admite cada tipo).

Forma corta. El nombre del método:

config = \{

    "email":   "mask",

    "salario": "perturb",

    "notas":   "drop",

\}

Forma extendida. Un diccionario con el método y, si lo admite, su parámetro (param):

config = \{

    "dni":        \{"method": "pseudonym", "param": r"CLI-\d\{6\}"\},

    "nombre":     \{"method": "simulation", "param": "name"\},

    "email":      \{"method": "simulation", "param": "email", "derive_from": "nombre"\},

    "cp":         \{"method": "mask", "param": 3\},

    "fecha_alta": \{"method": "date_shift", "param": "id_cliente"\},

    "codigo":     \{"method": "mask", "type": "string"\},

\}

• En tablas, las claves son los nombres de las columnas. Las columnas que no aparecen en la configuración no se tocan.

• En imágenes, documentos, audio y vídeo, las claves son los códigos de los tipos de elementos (ver Tipos de elementos sensibles). Se aceptan con mayúsculas, espacios o guiones bajos indistintamente.

• Los nombres de método admiten sinónimos: simulate es simulation, tokenize es coding, blackout es redact, mute es silence, etc. Los nombres que usa la plataforma en la nube también se aceptan.

Métodos de anonimización

Métodos que necesitan el modelo de lenguaje. text_regenerate necesita el módulo Texto con un modelo registrado (ver Registrar un modelo explícitamente). Sin él, la anonimización se detiene con un error en lugar de entregar la columna vacía o sin tocar. Tampoco se puede usar en columnas que no son texto libre: en una columna de URLs o de códigos, usa simulation o coding.

Qué métodos admite cada tipo

El método debe ser válido para el tipo de la columna o del elemento. El primero de cada lista es el que aplica config="auto".

date_shift se acepta también en columnas de texto porque las fechas leídas de un CSV suelen llegar como texto.

Tablas

from dedomena.nucleus import anonymize

anonymize(

    "datos/empleados.parquet",

    config=\{

        "dni":         \{"method": "pseudonym", "param": r"EMP-\d\{6\}"\},

        "nombre":      \{"method": "simulation", "param": "name"\},

        "email":       \{"method": "simulation", "param": "email", "derive_from": "nombre"\},

        "telefono":    "mask",

        "salario":     \{"method": "perturb", "param": 0.1\},

        "nacimiento":  \{"method": "generalize", "param": 10\},

        "observaciones": \{"method": "coding", "param": "tokens"\},

    \},

    output="salida/empleados_anonimizados.parquet",

    output_format="PARQUET",

    output_dir="resultados",

    country="Spain",

)

• Las tablas se anonimizan en CPU. Solo necesitan un modelo si usas text_regenerate, o si quieres que coding encuentre nombres y empresas dentro del texto libre (con el modelo ligero o el completo).

• Para recibir el resultado en memoria: output_format="DATAFRAME" y lo tienes en resultado.content.

• Si no indicas output, el fichero se escribe en la carpeta actual como \<nombre\>_anonymized.\<ext\>.

Imágenes

anonymize(

    "documentos/dni.png",

    config=\{

        "face":      "blur",

        "signature": "redact",

        "name":      \{"method": "simulation", "param": "name"\},

        "dni":       "mask",

        "birthdate": "mask",

    \},

    output="salida/dni_anonimizado.png",

)

• Elementos visuales (rostro, firma, logotipo, huella): se oculta toda la región, incluido el texto que haya encima.

• Texto dentro de la imagen: el valor original se borra y se dibuja el nuevo valor ajustado a su espacio, con colores tomados de la propia imagen.

• Zona MRZ de pasaportes y documentos de identidad: se sustituye por una MRZ sintética válida (con sus dígitos de control), coherente con los datos ya anonimizados del documento. Si no se puede reconstruir con seguridad, se pixela.

• Edición generativa (opcional, requiere su modelo y GPU): si está instalada, los textos se sustituyen con un aspecto natural en lugar de dibujados encima. Si no está instalada, se usa el método de dibujo, siempre predecible.

• Si un elemento configurado no tiene ubicación, la anonimización falla en lugar de entregar una imagen que parece anonimizada y no lo está.

Opciones de imagen (image_options):

Documentos

anonymize(

    "documentos/contrato.pdf",

    config=\{"name": "pseudonym", "address": "mask", "iban": "hash", "signature": "redact"\},

    output="salida/contrato_anonimizado.pdf",

)

• PDF: el texto sensible se elimina del documento, no solo se tapa (no se puede recuperar seleccionándolo ni copiándolo), y el reemplazo se escribe con la fuente, el tamaño y el color originales. Se anonimizan también los campos de formulario, las imágenes incrustadas y las regiones visuales (firmas, rostros, logotipos).

• DOCX: se recorren el cuerpo, las tablas, los encabezados y los pies de página. Un párrafo modificado puede perder el formato de caracteres que tuviera dentro.

• TXT: sustitución directa del texto.

Audio

anonymize(

    "llamadas/atencion_cliente.mp3",

    config=\{"name": "beep", "phone_number": "beep", "iban": "silence", "address": "beep"\},

    output="salida/atencion_cliente_anonimizada.mp3",

    audio_options=\{"language": "es"\},

)

Opciones de audio (audio_options):

• Si dos tramos se solapan, se aplica el método más destructivo (remove > silence > beep).

• El resultado conserva el formato de entrada.

Entregas de varios activos

Cuando anonimizas varios activos relacionados (varias tablas de un mismo sistema, o una tabla y los documentos de esos mismos clientes), usa la clase Anonymization. Garantiza que:

• la misma persona recibe el mismo reemplazo en todos los activos;

• las fechas de una misma entidad se desplazan igual en todas las tablas;

• las claves ajenas (references) siguen coincidiendo después de anonimizar.

from dedomena.nucleus import Anonymization

politica = \{

    "id_cliente": \{"method": "pseudonym", "param": r"C-\d\{6\}"\},

    "nombre":     \{"method": "simulation", "param": "name"\},

    "email":      \{"method": "simulation", "param": "email", "derive_from": "nombre"\},

    "fecha":      \{"method": "date_shift", "param": "id_cliente"\},

\}

tablas = [

    \{"name": "pedidos",  "data": "datos/pedidos.csv",

     "config": \{**politica, "id_cliente": \{"method": "pseudonym", "references": "clientes.id_cliente"\}\}\},

    \{"name": "clientes", "data": "datos/clientes.csv", "config": politica\},

]

anon = Anonymization(config=politica, output_dir="entrega_octubre", country="Spain")

for tabla in anon.ordered(tablas):          # primero las tablas referenciadas

    anon.run(tabla["data"], name=tabla["name"], config=tabla["config"],

             output=f"entrega_octubre/\{tabla['name']\}.csv")

anon.conformance()                          # informe de conformidad en PDF y JSON

print(anon.findings)                        # lo que haya quedado sin tratar

• ordered() ordena las tablas para que una tabla referenciada se anonimice antes que las que la referencian.

• run() acepta las mismas fuentes que anonymize(), más name (el nombre de la tabla en la entrega, al que apuntan las references) y config (para sobrescribir la política en ese activo).

Qué ficheros se generan

El informe de conformidad describe qué se detectó, qué se trató y con qué método, qué valores cambiaron, qué entidades se comparten entre activos y de qué protege (y de qué no) cada tratamiento. Si algo quedó sin tratar (una columna configurada que no existe, un valor de audio que no se pudo situar en el tiempo…), aparece en el informe y además se muestra en pantalla al terminar ese activo, aunque verbose=False.

Marca de contenido generado

Cuando un método escribe valores nuevos (simulation, text_regenerate o coding en modo invented) y ha tratado al menos un elemento, Edge marca el resultado como contenido generado por IA, tal como exige el artículo 50 del Reglamento Europeo de IA:

• el historial del activo lo indica (resultado.ai_generated es True);

• junto al fichero se escribe \<fichero\>-metadata.json con la información de procedencia.

Los métodos que ocultan, eliminan o transforman lo que había (mask, hash, pseudonym, blur, pixelate, redact, beep, drop, perturb, shuffle, generalize, date_shift) no marcan el resultado. Los datos sintéticos se marcan siempre.

Revertir y entregas incrementales

Los métodos reversibles (mask, pseudonym, simulation, generalize, coding, date_shift, text_regenerate) guardan su mapeo en output_dir. Con él, una persona autorizada puede revertir una tabla anonimizada:

from dedomena.nucleus import deanonymize

original = deanonymize("salida/clientes_anonimizados.csv",

                       mapping_dir="resultados",

                       output="revertido/clientes.csv")

hash, shuffle, perturb, drop y los métodos visuales y de audio no se pueden revertir. La reversión se aplica a tablas.

Entregas incrementales. Para anonimizar los datos del mes siguiente con exactamente los mismos reemplazos que la entrega anterior (la misma persona recibe el mismo seudónimo, sus fechas se desplazan igual), carga la entrega anterior:

from dedomena.nucleus import Anonymization

anon = Anonymization.load("entrega_octubre")

anon.run("datos/clientes_noviembre.csv", name="clientes",

         output="entrega_noviembre/clientes.csv")

Datos sintéticos

Un sintetizador aprende las propiedades estadísticas de tus datos reales, de modo que a partir de él se pueden generar datos sintéticos nuevos sin copiar los registros originales. El flujo es siempre el mismo:

1. Entrenar el sintetizador con tus datos, en tu máquina (train).

2. Evaluar su calidad, su privacidad y su utilidad (evaluate).

3. Guardarlo en un fichero (save).

4. Subir el sintetizador a la plataforma Dedomena.AI.

5. Generar los datos sintéticos desde la plataforma, o a través de la API.

Entrenar requiere el módulo Tablas y el permiso nucleus.synthesis. Los datos sintéticos se generan en la plataforma Dedomena.AI, a partir del sintetizador que subes (ver Generar datos).

Elegir el algoritmo

from dedomena.nucleus import Auto, choose_algorithm

choose_algorithm("datos/ventas.csv")          # ('transactional', 'motivo…'), sin entrenar nada

modelo = Auto(epochs=150)

modelo.train("datos/ventas.csv")

print(modelo.algorithm, modelo.reason)

Auto nunca elige TimeSeries: si tus datos son series temporales, usa esa clase directamente.

Ejemplo completo (Generic)

import dedomena

from dedomena.nucleus import Generic

# 1. Configurar

modelo = Generic(

    synthesizer_name="clientes_v1",

    synthesizer_description="Clientes particulares 2026",

    epochs=200,

    batch_size=256,

    configuration=\{

        "categorical_columns": ["provincia", "segmento"],

        "integer_columns": ["edad"],

        "float_columns": ["ingresos"],

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

        "id_columns": \{"id_cliente": r"CLI-\d\{6\}"\},

        "target": "segmento",

    \},

    sensitive=\{"nombre": "name", "email": "email", "dni": "dni"\},

    constraints=["edad\>=18", "ingresos\>=0"],

)

# 2. Entrenar

modelo.train("datos/clientes.csv")

# 3. Evaluar (escribe informe/report.pdf e informe/evaluation.json)

privacidad, calidad, utilidad = modelo.evaluate(output_dir="informe")

# 4. Guardar (escribe sintetizadores/synthesizer.zip, con el informe dentro)

modelo.save("sintetizadores")

# 5. Sube sintetizadores/synthesizer.zip a la plataforma Dedomena.AI y genera allí los datos

Opciones comunes

Estas opciones se pasan al crear Generic, Transactional, TimeSeries o Auto:

Tipos de columnas (dentro de configuration):

Las columnas que no declares se clasifican solas, y la librería indica cómo las ha clasificado. Ninguna columna se descarta: si no quieres que una columna entre en el modelo, elimínala de los datos antes de entrenar.

> Los tipos de columnas van dentro de configuration. Pasarlos como argumentos sueltos (categorical_columns=[…]), como en versiones anteriores, produce un error al crear el modelo.

Transaccional

Para movimientos de una entidad a lo largo del tiempo. Indica en columns_mapping qué columna de tus datos cumple cada papel:

from dedomena.nucleus import Transactional

modelo = Transactional(

    columns_mapping=\{"user_id": "cuenta", "txn_date": "fecha", "amount": "importe",

                     "concept": "concepto", "balance": "saldo", "cat_id": "categoria"\},

    balance_updated=True,

    transform_descriptions="level2",

    configuration=\{"categorical_columns": ["categoria"], "date_columns": \{"fecha": "%Y-%m-%d"\}\},

    datasets_country="Spain",

    epochs=250,

    synthesizer_name="movimientos_v1",

)

modelo.train("datos/movimientos.parquet")

modelo.save("sintetizadores/movimientos")

• balance_updated: True si el saldo de cada fila ya incluye el importe de esa fila; False si incluye el de la fila anterior. El saldo de los datos generados se recalcula a partir de los importes.

• Con una columna cat_id, se mantiene la coherencia entre descripción y categoría.

Descripciones de los movimientos (transform_descriptions, por defecto "level2"): las descripciones generadas se reescriben para que no repitan textos reales y sean coherentes con el importe y la fecha de su fila.

Los niveles 2 y 3 aprovechan los modelos de detección y de texto si están instalados. Sin ellos, se apoyan en patrones y en valores ficticios.

Series temporales

Para medidas periódicas de varias entidades. Indica en columns_mapping la entidad (user_id), la fecha (txn_date) y la medida (amount). Hacen falta al menos 5 entidades distintas.

from dedomena.nucleus import TimeSeries

modelo = TimeSeries(

    columns_mapping=\{"user_id": "contador", "txn_date": "fecha", "amount": "kwh"\},

    static_columns=["tarifa", "provincia"],     # constantes para cada entidad

    epochs=300,

    batch_size=64,

)

modelo.train("datos/lecturas.csv")

modelo.save("sintetizadores/lecturas")

• Las series se modelan con una observación por día. Otras columnas de fecha distintas de txn_date no se usan.

• Cuando generes datos a partir de un sintetizador de series temporales, la cantidad que pides es el número de series (entidades), no de filas.

Relacional

Para varias tablas relacionadas. Describe cada tabla en datasets_config y pasa los datos de todas a train():

from dedomena.nucleus import Relational

config = \{

    "clientes": \{

        "primary_key": "id_cliente",

        "categorical_columns": ["segmento", "provincia"],

        "integer_columns": ["edad"],

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

        "amplify": "default",

    \},

    "pedidos": \{

        "primary_key": "id_pedido",

        "foreign_key": \{"id_cliente": "clientes"\},

        "date_columns": ["fecha_pedido"],

        "float_columns": ["total"],

        "amplify": "default",

    \},

\}

modelo = Relational(datasets_config=config, epochs=200, datasets_country="Spain",

                    synthesizer_name="tienda_v1")

modelo.train(\{"clientes": "datos/clientes.csv", "pedidos": "datos/pedidos.parquet"\})

modelo.save("sintetizadores/tienda")

Claves por tabla en datasets_config:

• Las relaciones deben formar un grafo sin ciclos, y cada clave ajena debe apuntar a una clave primaria. Las filas con claves que no apuntan a nada se descartan al entrenar, con un aviso.

• El entrenamiento relacional requiere 150 o más pasadas.

• Cuando generes datos a partir de un sintetizador relacional, la cantidad que pides es el número de copias completas del esquema. Las claves siguen coincidiendo entre las tablas generadas.

• Un sintetizador relacional no se puede reentrenar: entrena uno nuevo con los datos actualizados.

Restricciones

Reglas que los datos generados cumplen siempre. Se escriben sin espacios:

Una restricción mal escrita produce un error al entrenar.

Generar datos

Los datos sintéticos se generan en la plataforma Dedomena.AI, a partir del sintetizador que entrenas con Edge:

1. Guarda el sintetizador con modelo.save(carpeta). Escribe synthesizer.zip en esa carpeta.

2. Sube synthesizer.zip a la plataforma Dedomena.AI, desde la aplicación web o a través de la API.

3. Genera los datos sintéticos desde la plataforma, o a través de la API.

Las opciones de generación (número de registros, generación condicional…) se describen en la documentación de la plataforma y de la API. Los datos sintéticos se marcan siempre como contenido generado por IA.

Guardar, cargar y reentrenar

modelo.save("sintetizadores/clientes")            # → sintetizadores/clientes/synthesizer.zip

modelo = load_synthesizer("sintetizadores/clientes/synthesizer.zip")

modelo.metadata                                    # nombre, algoritmo, columnas, puntuaciones…

• save() recibe una carpeta y escribe siempre synthesizer.zip dentro. Si has ejecutado evaluate() antes, el informe va incluido.

• load_synthesizer(ruta) carga un sintetizador guardado, por ejemplo para reentrenarlo.

• Protege synthesizer.zip como un dato sensible: contiene el modelo entrenado y puede contener muestras de los datos de entrenamiento.

Reentrenar con datos nuevos (solo Generic, Transactional y TimeSeries):

modelo = load_synthesizer("sintetizadores/clientes/synthesizer.zip")

modelo.retrain(data="datos/clientes_noviembre.csv", epochs=100)

modelo.save("sintetizadores/clientes_v2")

• Indica siempre epochs.

• Con amplify="quality", forgetfulness_factor (entre 0 y 1) decide qué parte de los datos anteriores se olvida: 0 conserva todo, 1 empieza de cero.

Evaluación e informe

privacidad, calidad, utilidad = modelo.evaluate(output_dir="informe")

Mide el sintetizador frente a los datos reales con los que se entrenó y devuelve tres puntuaciones de 0 a 100:

En output_dir se escriben:

• report.pdf: el informe, con las puntuaciones, cada métrica explicada y sus gráficos;

• evaluation.json: los mismos resultados en formato de datos, para integrarlos en tus procesos;

• logHistory.log.

Cada puntuación se acompaña de una valoración: crítica (hasta 40), mejorable (hasta 60), aceptable (hasta 80) o excelente.

• Datos de control. Para medir los riesgos de singularización y de vinculación, separa antes de entrenar una parte de los datos reales que el modelo no vea y pásala como control_data: modelo.evaluate(output_dir="informe", control_data="datos/control.csv").

• La evaluación necesita al menos 3 columnas tipadas que no sean sensibles ni identificadores.

• Ejecuta evaluate() antes de save() para que el informe vaya dentro del sintetizador.

• En relacional, evaluate(output_dir=…) devuelve las puntuaciones medias e incluye la integridad referencial.

Evaluar dos conjuntos de datos cualesquiera. Para comparar un conjunto real con datos sintéticos que hayas generado en la plataforma Dedomena.AI:

from dedomena.nucleus.evaluations import synthesizer_evaluations

privacidad, calidad, utilidad = synthesizer_evaluations(

    real_data="datos/real.parquet",

    synthetic_data="datos/sintetico.parquet",

    categorical_columns=["provincia", "segmento"],

    integer_columns=["edad"],

    float_columns=["ingresos"],

    date_columns=["fecha_alta"],

    target="segmento",

    output_dir="informe",

    synthesizer_name="clientes_v1",

)

Para varias tablas, synthesizer_evaluations_multitable(configuration=\{tabla: \{...\}\}, output_dir="informe") produce un único informe combinado.

Columnas de texto libre y privacidad

Las columnas de texto libre (text_columns) se modelan como categorías: los textos generados se toman de los textos reales del entrenamiento. Si esas columnas contienen datos personales, anonimízalas antes de entrenar, por ejemplo con coding o text_regenerate (ver Anonimización), o elimínalas de los datos.

La excepción son las descripciones de los movimientos en Transactional con transform_descriptions, que se reescriben al generar (ver Transaccional).

Partir de datos preparados con Axon

Si pasas a train() un activo preparado con Axon, el sintetizador aprovecha los tipos de columna que Axon ha detectado. Lo que declares tú en configuration tiene prioridad. Ver De Axon a Nucleus.

Axon: calidad y preparación de datasets

Axon comprueba y prepara un dataset antes de anonimizarlo o sintetizarlo: infiere los tipos de las columnas, detecta valores atípicos y patrones de valores ausentes, limpia el texto, aplica reglas de transformación y genera un informe de calidad en PDF. Va incluido en todos los paquetes y requiere el permiso axon.

Cada paso devuelve un nuevo activo y deja el original sin modificar; el historial se acumula.

Inspeccionar

from dedomena.axon import Inspector

activo = Inspector().run("datos/clientes.csv", name="clientes")

activo.schema["types"]       # categorical_columns, integer_columns, float_columns, boolean_columns, text_columns, date_columns

activo.schema["semantic"]    # columnas de identificadores, teléfonos, emails/URL, coordenadas…

activo.schema["outliers"]    # \{columna: [filas con valores atípicos]\}

activo.info["rows"], activo.info["columns"]

activo.info["axon"]["unavailable"]   # \{\} si se pudo ejecutar todo

La forma corta es inspect_dataset(fuente, **opciones).

Limpiar

from dedomena.axon import clean

limpio = clean("datos/clientes.csv", name="clientes")

limpio.info["axon"]["cleaning"]      # filas duplicadas, cabeceras repetidas, vacíos, espacios corregidos…

limpio.quality["cleaning_after"]     # indicador orientativo de 0 a 1

La limpieza:

• sustituye tabuladores y saltos de línea por espacios, junta espacios repetidos y recorta los extremos de cada celda;

• elimina comillas tipográficas o desparejadas;

• convierte a número las columnas con decimales escritos con coma ("1,5").

También cuenta las filas duplicadas y las cabeceras repetidas dentro de los datos, pero no las elimina. Elimínalas tú si lo necesitas, por ejemplo con df.drop_duplicates().

Después de limpiar, las columnas quedan como texto. Para devolverles su tipo, aplica reglas cast_type (siguiente apartado) y vuelve a inspeccionar.

Aplicar reglas

from dedomena.axon import ApplyRules, Inspector

reglas = \{

    "email":   \{"type": "normalize_nulls"\},

    "nombre":  \{"type": "normalize_text_casing", "params": \{"proposed_case": "title"\}\},

    "edad":    [\{"type": "cast_type", "params": \{"target_type": "integer", "mode": "force"\}\},

                \{"type": "nullify_out_of_range", "params": \{"min": 0, "max": 120\}\}],

    "importe": \{"type": "cast_type", "params": \{"target_type": "float", "mode": "force"\}\},

    "ciudad":  \{"type": "enforce_category", "params": \{"allowed": ["Madrid", "Barcelona", "Valencia"]\}\},

\}

preparado = ApplyRules(reglas).run(limpio, name="clientes")

preparado.lineage[-1].details["applied"]   # reglas aplicadas por columna

preparado.lineage[-1].details["failed"]    # reglas que no se pudieron aplicar (p. ej. columna inexistente)

preparado = Inspector().run(preparado, name="clientes")   # tipos finales

Cada columna recibe una regla o una lista de reglas, que se aplican en orden:

Para que la anonimización y la síntesis vean el tipo nuevo de una columna, usa cast_type con "mode": "force".

Informe de calidad en PDF

from dedomena.axon import report

ruta = report(preparado, "informes/calidad_clientes", lang="es", name="Clientes 2026")

# → 'informes/calidad_clientes.pdf'

• lang: "es" o "en".

• El informe se construye con lo que el activo ya sabe: inspecciona antes de generarlo.

• El informe incluye ejemplos de valores de cada columna. Trátalo con la misma confidencialidad que el dataset. Lo mismo aplica a meta.json cuando guardas un activo inspeccionado.

Riesgo e informe ejecutivo

Estas dos funciones necesitan el modelo de lenguaje: el módulo Texto con un modelo instalado.

from dedomena.detection import detect, llm

from dedomena.axon import risk, insight, report

llm.register()                                       # necesario para insight()

preparado.sensitive_elements = detect(preparado)     # detecta antes de calcular el riesgo

con_riesgo = risk(preparado, name="clientes")

resumen = con_riesgo.info["risk"]["summary"]

resumen["label"], resumen["level"], resumen["sensitivity_index"], resumen["avg_risk_level_sensitive"]

con_insight = insight(con_riesgo, language="spanish", context="Altas del canal online", rows=200)

print(con_insight.info["insight"]["text"])

report(con_insight, "informes/riesgo_clientes.pdf", lang="es")   # añade las secciones de riesgo e insights

• risk() calcula el nivel de riesgo de reidentificación a partir de las columnas sensibles detectadas: ejecuta detect() antes; sin detección, el resultado es «sin riesgo».

• insight() escribe un resumen ejecutivo de lo que dicen los datos, a partir de las primeras rows filas. language admite "spanish" o "english".

De Axon a Nucleus

El flujo recomendado:

1. Inspeccionar los datos originales con Inspector, para tener un diagnóstico.

2. Limpiar con clean.

3. Aplicar reglas con ApplyRules, usando cast_type con "mode": "force" para fijar los tipos.

4. Volver a inspeccionar con Inspector, para que el esquema describa los datos ya preparados.

5. Anonimizar o sintetizar con Nucleus.

from dedomena.nucleus import anonymize, Generic

anonimizado = anonymize(preparado, config="auto", output="salida/clientes_anon.csv")

modelo = Generic()

modelo.train(preparado)          # usa los tipos que ha detectado Axon

• Síntesis: usa los tipos de columna de Axon para todo lo que no hayas declarado en configuration.

• Anonimización: usa el contenido limpio y, si el activo ya tiene elementos detectados, los usa sin volver a detectar.

• Indica siempre output= al anonimizar un activo de Axon (o output_format="DATAFRAME").

Comprobar el motor de Axon

from dedomena.axon import engine_report

engine_report()      # \{'basic_cleaner': None, 'profiling': None, ...\}   None = funciona

Si una parte no puede ejecutarse en tu máquina (por ejemplo, por una dependencia), Inspector la omite, avisa y la anota en activo.info["axon"]["unavailable"] con el motivo. El resto del análisis continúa.

Modelos: automáticos, registrados y propios

Cómo elige la librería

No tienes que configurar nada: la librería usa el mejor motor que encuentra instalado para cada modalidad.

• Los patrones y las validaciones se aplican siempre, con cualquier motor.

• Al cargarse, cada motor deja una línea en el registro con lo elegido y el dispositivo (text detection engine selected: …, small-text device selected: cpu…).

• Si un motor no se puede cargar, la librería pasa al siguiente y lo avisa. Si lo que falta son los modelos, el aviso incluye el comando para descargarlos:

  code

  
  text detection engine selected: patterns (...).
  
  Download the models with your licence: `dedomena-edge setup --size small`.
  
  

• Los modelos ligeros se ejecutan en CPU aunque haya GPU, para no ocupar memoria de la tarjeta. Puedes moverlos a la GPU (ver Registrar un modelo explícitamente).

Qué motor se va a usar

from dedomena.detection import models

print(models.report())          # qué se usará en cada modalidad, y si cabe en la GPU

GPU: 96 GB

residency: shared

runs on:

  audio: small-audio on cpu

  images: …

  text: …

• models.runtime_report() devuelve lo mismo como diccionario.

• models.plan() indica, para los modelos completos, si caben en tu GPU: fits (caben), tight (caben reduciendo el contexto) o no (no caben).

• Nada de esto carga los modelos.

Por modalidad:

from dedomena.detection import llm, small, audio

llm.model_report()                     # (ruta, motor, problema): problema None = se puede cargar

small.report()                         # modelos ligeros disponibles, y qué falta

audio.transcriber_report(device="auto")

Registrar un modelo explícitamente

Registrar un modelo lo carga en memoria y lo conecta con la detección y la anonimización. La librería lo hace sola cuando lo necesita, pero registrarlo tú te permite elegir qué capacidades activar, en qué dispositivo y cuándo pagar el tiempo de carga.

Modelo de lenguaje (módulo Texto):

from dedomena.detection import llm

llm.register()        # con los modelos instalados

llm.unregister() vuelve a dejar la detección de texto en los patrones. llm.available() indica si se puede cargar.

> text_regenerate necesita registrar el modelo. La detección automática carga el modelo de lenguaje solo para detectar. Para usar text_regenerate, llama antes a llm.register().

Modelos ligeros:

from dedomena.detection import small

small.register(device="cuda")    # mueve a la GPU los modelos ligeros de texto e imagen

small.upgrade()                  # cambia los ligeros por los completos, si están instalados

Modelo de imagen completo:

from dedomena.detection.images import vlm

vlm.register(confirm=True)       # además, revisa cada región propuesta recortándola

Usar un modelo que ya tienes

Si tu organización ya tiene un modelo de lenguaje propio, Edge puede usarlo para la detección en texto libre, text_regenerate y los informes ejecutivos de Axon. Necesitas el módulo Texto.

Requisitos del modelo:

• Un modelo de lenguaje conversacional (instruido para seguir instrucciones), con un contexto de al menos 8.192 tokens.

• Multilingüe, si tus datos no están en inglés.

• Edge le envía sus propias instrucciones. La calidad de la detección depende del modelo: compruébala con tus datos antes de usarlo en producción.

Opción 1: tus pesos, en tu disco

Indica la ruta del modelo:

export DEDOMENA_LLM_MODEL=/modelos/mi-modelo

o al registrarlo:

from dedomena.detection import llm

llm.register(model="/modelos/mi-modelo")

Si la carpeta contiene a la vez una carpeta de modelo y un .gguf, gana la carpeta.

Opción 2: tu propio servidor de modelos

Si ya sirves un modelo en tu red interna con una API compatible con la de chat de OpenAI (/v1/chat/completions):

export DEDOMENA_LLM_ENDPOINT=http://modelos.interno:8000      # sin /v1

export DEDOMENA_LLM_ENDPOINT_MODEL=nombre-del-modelo-en-tu-servidor

from dedomena.detection import llm

llm.register()

• Edge llama a \<DEDOMENA_LLM_ENDPOINT\>/v1/chat/completions.

• El servidor debe estar en tu red: así los datos siguen sin salir de tu infraestructura.

• Edge no envía cabecera de autenticación. Si tu servidor la exige, publícalo detrás de un proxy interno que la añada.

• Con esta variable definida, Edge usa el servidor en lugar de un modelo local.

Modelo de imagen propio

Funciona igual con DEDOMENA_VISION_MODEL (una carpeta de modelo) o con DEDOMENA_VISION_ENDPOINT y DEDOMENA_VISION_ENDPOINT_MODEL (un servidor compatible). Edge le pide localizar regiones (rostros, firmas, logotipos, huellas) y valores dentro de la imagen, y devolver sus coordenadas, así que debe ser un modelo de visión y lenguaje capaz de hacerlo. Te recomendamos usar el modelo de imagen de Dedomena.AI, salvo que valides el tuyo con tus documentos.

Forzar un motor

La librería elige sola cómo ejecutar el modelo según su formato y tu hardware. Si necesitas forzar otra forma de ejecutarlo (por ejemplo, porque la GPU está ocupada con otro proceso), consulta con soporte de Dedomena.AI las variables DEDOMENA_LLM_BACKEND y DEDOMENA_VISION_BACKEND.

Registrar un detector propio

Si tienes tu propio detector (por ejemplo, un modelo interno para un tipo de documento propio), puedes conectarlo y todas las funciones de la librería lo usarán en lugar del motor incorporado:

from dedomena.detection import register_detector, detect

def mi_detector_de_texto(texto, types=None):

    """Recibe un texto y devuelve los elementos que encuentra."""

    resultados = []

    for numero in buscar_numeros_de_poliza(texto):          # tu lógica

        resultados.append(\{"value": numero, "type": "health_card"\})

    return resultados

register_detector("text", mi_detector_de_texto)

detect("La póliza AX-99812 está a nombre de…")

• Los patrones siguen aplicándose antes que tu detector y ganan los solapamientos.

• Un valor de texto que no aparece literalmente en el texto se descarta.

• Si tu detector falla, la librería vuelve a los patrones para ese lote y lo avisa en el registro.

• Para quitarlo: from dedomena.detection.registry import unregister_detector; unregister_detector("text").

Del mismo modo, register_generator("text_regenerate", funcion) permite conectar tu propio generador de texto. La función recibe (prompts, max_tokens=...) y devuelve una cadena por cada instrucción.

Dónde están los modelos

La librería busca cada modelo en este orden:

1. La ruta que indiques al registrarlo (model=).

2. Su variable de entorno: DEDOMENA_LLM_MODEL, DEDOMENA_VISION_MODEL, DEDOMENA_AUDIO_MODEL, DEDOMENA_SMALL_TEXT_MODEL, DEDOMENA_SMALL_VISION_MODEL, DEDOMENA_SMALL_AUDIO_MODEL…

3. La carpeta de modelos: DEDOMENA_MODELS_DIR, o ~/.local/share/dedomena/models si no está definida.

dedomena-edge setup descarga en la misma carpeta en la que la librería busca, así que no tienes que configurar nada. Con la descarga completa, env.sh define DEDOMENA_MODELS_DIR apuntando a ./models.

Integridad. Cada modelo lleva un manifiesto con el tamaño y la huella de cada fichero. La huella se comprueba al descargar, y el tamaño cada vez que se carga: un modelo copiado a medias no se usa.

GPU: memoria y uso compartido

Si tu paquete tiene los modelos completos de texto y de imagen, los dos comparten la GPU:

• si caben a la vez, se cargan los dos (shared);

• si no, se cargan por turnos (exclusive): cada uno dispone de la tarjeta entera y el otro se descarga al cambiar. Cada cambio cuesta una carga, así que ordena el trabajo por modalidad (primero las tablas, después las imágenes).

La librería lo decide midiendo la tarjeta. Puedes forzarlo con DEDOMENA_GPU_POLICY=shared|exclusive, y fijar la fracción de memoria de cada modelo con DEDOMENA_LLM_VRAM y DEDOMENA_VISION_VRAM (por ejemplo, 0.45).

Manual de referencia

Comandos

Variables de entorno

Todas son opcionales: sin ninguna, la librería decide sola.

Errores frecuentes