WorkloadTruth

WorkloadTruth

Instalación • Inicio rápido • Referencia de CLI • Comparación • Preguntas frecuentes

Clasifica una carga de trabajo de GPU como TRAINING, INFERENCE o IDLE solo con telemetría. Sin cambios de código en la carga de trabajo, sin etiquetas de trabajo autoinformadas.

Todos los planificadores de GPU de uso común hoy en día, incluidos run:ai, Slurm y los operadores de GPU de Kubernetes, te piden que declares si un trabajo es de entrenamiento o de inferencia al momento de enviarlo. Ninguno lo verifica. WorkloadTruth lee la telemetría de la GPU (utilización, patrón de memoria, consumo de energía) y responde la pregunta de forma independiente, de modo que un trabajo mal etiquetado o con comportamiento anómalo no pase desapercibido.

Instalación

# Real NVIDIA GPU telemetry (requires an NVIDIA driver on the host)
pip install "workloadtruth-cli[nvml]"

# Try it without a GPU, using the synthetic backend
pip install workloadtruth-cli

# npm launcher (thin wrapper around the PyPI package, see "Why two registries")
npx workloadtruth-cli --help

[!NOTE] El paquete npm es un lanzador, no una instalación independiente. npx workloadtruth-cli ejecuta el binario real de workloadtruth desde PATH, por lo que el paquete PyPI (pip install workloadtruth-cli) debe estar instalado primero.

Inicio rápido

# No GPU required. Classify a synthetic "training" telemetry trace.
$ workloadtruth classify --backend synthetic --profile training --samples 10 --interval 0
workload_type : TRAINING
confidence    : 1.00
gpu_index     : 0
samples       : 10 over 9.0s
reasons:
  - avg GPU utilization 87.8% >= training threshold 65.0%
  - low GPU utilization variance (std=3.4) <= training ceiling 15.0
  - memory growing 120.0 MiB/sample >= training threshold 5.0
  - low power-draw variance (std=9.4W) <= training ceiling 25.0W

# Real hardware
$ workloadtruth classify --backend nvml --samples 10 --interval 1 --json

--json en cada comando cambia a salida legible por máquina para scripts y agentes.

Resumen rápido

• Úsalo para: detectar trabajos de GPU con costos mal asignados (un trabajo facturado como "inferencia" de baja prioridad que en realidad está ejecutando entrenamiento completo) y cambios no autorizados en la carga de trabajo (un endpoint de inferencia que comienza a entrenar con tráfico en vivo sin aprobación)
• Lo que no es: una herramienta de cumplimiento o auditoría regulatoria. Ninguna regulación exige actualmente este tipo de monitoreo; ver Qué no es WorkloadTruth más abajo
• Trabajo previo: se basa en y cita arXiv:2606.19262 (ICML 2026); ver Relación con investigaciones previas

Cómo funciona la clasificación

WorkloadTruth incluye actualmente solo un clasificador basado en reglas: un conjunto de umbrales documentados e inspeccionables sobre cuatro características extraídas de una ventana de telemetría (promedio y varianza de la utilización de GPU, pendiente de crecimiento de memoria, promedio y varianza del consumo de energía). Cada umbral vive como una constante con nombre en src/workloadtruth/classifier/rules.py con un comentario que explica su intuición. Nada es una caja negra.

--experimental (un clasificador basado en ML) está presente como una bandera, pero falla de forma ruidosa con una explicación en lugar de enviar un resultado falso. El modelo entrenado y el conjunto de datos de arXiv:2606.19262 nunca se publicaron, y este proyecto no tiene una GPU NVIDIA en su entorno de compilación para recopilar datos reales de entrenamiento. Un clasificador de ML se incluye aquí solo cuando esté entrenado con un conjunto de datos real y divulgado, y se demuestre de forma independiente que supera la línea base basada en reglas, no antes.

Benchmark

workloadtruth benchmark mide la precisión del clasificador contra trazas de telemetría sintética de GPU documentadas (ver synthetic_backend.py para los parámetros exactos del perfil), tanto limpias como bajo una transformación de evasión deliberada que imita a un operador que disfraza un trabajo de entrenamiento como inferencia (limitando las oscilaciones de utilización, aplanando el crecimiento de memoria, inyectando brechas inactivas artificiales).

Esto se ejecuta con datos sintéticos, no con hardware NVIDIA real, por lo que no es directamente comparable con los números de hardware real de arXiv:2606.19262. Ambos se informan a continuación, lado a lado, nunca mezclados en una sola cifra.

	arXiv:2606.19262 (hardware real, NVML)	WorkloadTruth (trazas sintéticas, 300 pruebas/celda)
Precisión limpia	98.2%	100.0%
Precisión ante evasión	43-87%	66.7% en general

El número general de evasión oculta el hallazgo real. Desglosado por tipo de carga de trabajo, el clasificador basado en reglas de WorkloadTruth está actualmente completamente engañado en cargas de trabajo de entrenamiento evasivas (0% de precisión), mientras que sigue siendo preciso en trazas de inferencia e inactividad evasivas (100% cada una). Limitar la utilización de GPU por sí solo es suficiente para que un trabajo de entrenamiento se lea como inferencia para este clasificador hoy.

Perfil	Precisión limpia	Precisión ante evasión
Entrenamiento	100.0%	0.0%
Inferencia	100.0%	100.0%
Inactivo	100.0%	100.0%

Esta es la brecha concreta y divulgada que el conjunto de benchmarks existe para sacar a la luz y rastrear, no una nota al pie. Un clasificador basado en reglas que solo mira la varianza de utilización es trivialmente evadible. Cerrar esta brecha, mediante fusión de múltiples señales o un clasificador entrenado real una vez que existan datos, es la hoja de ruta, no un problema resuelto. Reprodúcelo tú mismo:

workloadtruth benchmark --trials 300 --window 30 --json

Referencia de CLI

$ workloadtruth --help
Usage: workloadtruth [OPTIONS] COMMAND [ARGS]...

  Classify a GPU workload as INFERENCE, TRAINING, or IDLE from telemetry
  alone.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  benchmark   Run the evasion-robustness benchmark against synthetic...
  classify    One-shot classification of the current GPU workload.
  mcp         Start an MCP server exposing classify/benchmark/verify-log...
  verify-log  Verify the hash chain of a local audit log has not been...
  watch       Continuously classify and append hash-chained entries to...

Comando	Propósito
classify	Clasificación de una sola vez. --backend synthetic|nvml, --json para salida legible por máquina.
watch	Clasificación continua; agrega una entrada encadenada por hash a un registro de auditoría local en cada ventana.
benchmark	Ejecuta el benchmark de robustez ante evasión (ver arriba).
verify-log	Recalcula el hash de cada entrada del registro de auditoría y confirma que la cadena no ha sido manipulada.
mcp	Inicia un servidor MCP (stdio) que expone classify_workload, run_benchmark, verify_audit_log como herramientas invocables por agentes. Requiere pip install "workloadtruth-cli[mcp]" en Python 3.10+ (ver abajo).

Cada comando admite --json. Referencia completa de banderas: workloadtruth <command> --help.

Servidor MCP

WorkloadTruth incluye un servidor Model Context Protocol para que un agente de IA (Claude, Cursor o cualquier cliente compatible con MCP) pueda clasificar cargas de trabajo de GPU, ejecutar el benchmark de robustez ante evasión y verificar el registro de auditoría directamente, sin que un humano invoque la CLI manualmente.

Instala el extra:

pip install "workloadtruth-cli[mcp]"

[!NOTE] El extra mcp requiere Python 3.10+, más estricto que el piso de 3.9 de WorkloadTruth. pip install "workloadtruth-cli[mcp]" fallará al resolverse en Python 3.9. Todas las demás funciones (classify, watch, benchmark, verify-log) funcionan en Python 3.9.

Agrégalo a la configuración de tu cliente MCP (para Claude Desktop, claude_desktop_config.json). El servidor se inicia mediante el subcomando workloadtruth mcp, no un script de consola separado:

{
  "mcpServers": {
    "workloadtruth": {
      "command": "uvx",
      "args": ["--from", "workloadtruth-cli", "workloadtruth", "mcp"]
    }
  }
}

El servidor expone tres herramientas a través de stdio:

• classify_workload(backend="nvml", profile="training", gpu_index=0, samples=10, interval_seconds=1.0, write_to_audit_log=False): muestrea la telemetría de la GPU y la clasifica como TRAINING, INFERENCE o IDLE. backend es "nvml" (hardware real) o "synthetic" (trazas sintéticas documentadas, sin necesidad de GPU). Opcionalmente agrega el resultado al registro de auditoría encadenado por hash.
• run_benchmark(trials=50, window=30): ejecuta el benchmark de robustez ante evasión contra telemetría sintética y devuelve la precisión por perfil en condiciones limpias y con ofuscación por evasión.
• verify_audit_log(log_file="workloadtruth.log.jsonl"): recalcula la cadena de hash de un registro de auditoría local e informa si ha sido manipulado.

Ejemplo de llamada, clasificando una traza de entrenamiento sintética sin necesidad de GPU:

classify_workload(backend="synthetic", profile="training", samples=10, interval_seconds=0)
-> {"workload_type": "TRAINING", "confidence": 1.0, "gpu_index": 0, ...}

El transporte es stdio, por lo que no hay nada que alojar: el cliente MCP lanza workloadtruth mcp como un subproceso local. También se incluye un manifiesto .well-known/agent.json en la raíz del repositorio para descubrimiento estilo A2A, que lista tanto las interfaces CLI y MCP como los paquetes que las proporcionan. Fuente: src/workloadtruth/mcp_server.py.

Registro de auditoría

workloadtruth watch agrega una entrada encadenada por hash a workloadtruth.log.jsonl en cada ventana de clasificación. El hash de cada entrada cubre su propio contenido más el hash de la entrada anterior, por lo que cualquier edición, reordenamiento o eliminación posterior rompe la cadena desde ese punto en adelante. workloadtruth verify-log recalcula cada hash e informa el primer enlace roto, si lo hay.

Esto demuestra qué se clasificó, cuándo, y que el registro local no ha sido alterado silenciosamente después. No demuestra que la clasificación en sí fuera correcta, y no es evidencia de cumplimiento regulatorio. Ver abajo.

Por qué dos registros

La implementación de WorkloadTruth es en Python. El acceso a NVML (pynvml/nvidia-ml-py) es la forma madura y oficial de leer la telemetría de GPU de NVIDIA, y también es lo que usa el trabajo previo más cercano (arXiv:2606.19262). El paquete npm (workloadtruth-cli) es un lanzador delgado, no una reimplementación. Localiza y ejecuta el binario real de workloadtruth instalado desde PyPI, de modo que npx workloadtruth-cli funcione para herramientas de agentes que priorizan npm sin duplicar el clasificador en dos lenguajes.

Comparación

	WorkloadTruth	NVIDIA DCGM / dcgm-exporter	run:ai	Weights & Biases
Lee telemetría de GPU	Sí (vía NVML)	Sí (fuente)	Sí	Sí
Clasifica el tipo de carga de trabajo automáticamente	Sí	No, expone solo métricas crudas	No, el tipo de carga de trabajo lo declara el usuario al enviar el trabajo	No, limitado a ejecuciones de entrenamiento por diseño, sin clasificación
Rastro de auditoría local encadenado por hash	Sí	No	No	No
Benchmark de robustez ante evasión	Sí (documentado, reproducible)	N/A	N/A	N/A
Requiere una GPU NVIDIA	Solo para el backend nvml; el backend synthetic funciona sin una	Sí	Sí	No (métricas generales del sistema)

Verificado directamente contra la documentación de cada proyecto: documentación del exportador DCGM, descripción general de inferencia de run:ai, documentación de métricas del sistema de W&B. Ninguno de estos clasifica el tipo de carga de trabajo solo con telemetría. Esa brecha es la que llena WorkloadTruth.

Qué es WorkloadTruth y por qué existe

WorkloadTruth es una herramienta de línea de comandos de código abierto y un servidor MCP que clasifica una carga de trabajo de GPU en ejecución como TRAINING, INFERENCE o IDLE usando solo telemetría a nivel de GPU (utilización, patrón de memoria, consumo de energía), sin cambios en el código de la carga de trabajo y sin depender de una etiqueta de trabajo autoinformada.

Existe porque todos los planificadores de GPU convencionales piden al propietario del trabajo que declare su tipo al momento del envío y nunca verifican esa declaración contra lo que el hardware está haciendo realmente. Esa brecha tiene dos consecuencias reales: mala asignación de costos (un trabajo programado con precios de "inferencia" de baja prioridad que en realidad está ejecutando entrenamiento completo) y cambios no autorizados en la carga de trabajo (un endpoint de inferencia que silenciosamente comienza a entrenar con tráfico en vivo). WorkloadTruth cierra esa brecha de verificación hoy, y además sirve como la primera implementación abierta e instalable de una línea de investigación académica real sobre verificación de ejecuciones de entrenamiento de IA a partir de telemetría de hardware (ver abajo).

Relación con investigaciones previas

La técnica central de WorkloadTruth, clasificar actividad de GPU de entrenamiento vs. no entrenamiento a partir de telemetría, no es novedosa. Es la aplicación directa de una línea de investigación real y activa:

1. Yonadav Shavit (Harvard), "What does it take to catch a Chinchilla?" (2023): propuso "transcripciones de entrenamiento" a nivel de hardware para verificar ejecuciones de entrenamiento a gran escala.
2. GovAI, "Computing Power and the Governance of AI" (2024): encuestó mecanismos de gobernanza de cómputo, explícitamente enmarcados como exploratorios, no como política respaldada.
3. "Hardware-Enabled Mechanisms for Verifying Responsible AI Development" (2025): investigadores de seguridad de hardware que proponen atestación en chip.
4. Rahman & Tajdari, "Detecting Hidden ML Training With Zero-Overhead Telemetry" (taller de Gobernanza Técnica de IA de ICML 2026): un clasificador funcional de telemetría NVML, con 98.2% de precisión en cargas de trabajo no ofuscadas, el trabajo previo directo para la técnica de clasificación central de este proyecto.

Lo que WorkloadTruth agrega: según la propia investigación de este proyecto (2026-07-19), no existía ninguna implementación de código abierto e instalable de esta línea de investigación, solo prototipos académicos. WorkloadTruth es ese empaquetado: una CLI real, un servidor MCP, un registro de auditoría encadenado por hash y un benchmark reproducible de robustez ante evasión, construido en abierto. No afirma mejorar la técnica de clasificación del artículo. Ver la sección de benchmark arriba: el clasificador basado en reglas actual es considerablemente más evadible que el enfoque de ML del artículo en el único eje que mide.

Qué no es WorkloadTruth

• No es una herramienta de cumplimiento o auditoría regulatoria. Ninguna ley exige actualmente la clasificación o el reporte de inferencia/entrenamiento. Cualquier afirmación futura en contrario nombrará la regulación específica promulgada; ninguna existe al momento de escribir esto.
• No es un inspector de contenido. WorkloadTruth solo lee señales a nivel de GPU (utilización, memoria, potencia). Nunca inspecciona pesos de modelos, datos de entrenamiento, prompts o completaciones.
• No es prueba de operación "cumplida" o "segura". El registro de auditoría prueba qué se clasificó y cuándo, y que el registro no fue alterado después, no que la clasificación fuera correcta o que se siguiera alguna política.

Preguntas frecuentes

¿Esto necesita una GPU NVIDIA? Solo para el backend nvml. --backend synthetic ejecuta el clasificador completo y la CLI contra trazas sintéticas documentadas, sin necesidad de GPU. Útil para probar la herramienta o para CI.

¿Puede clasificar cargas de trabajo de GPU AMD o Intel? Aún no. La capa de telemetría es una interfaz conectable (TelemetryBackend) específicamente para que se pueda agregar un nuevo backend de proveedor (AMD ROCm, Intel Level Zero) sin tocar el clasificador. Ver CONTRIBUTING.md.

¿Es el clasificador lo suficientemente preciso como para facturar o penalizar a alguien según su salida? Aún no, y la sección de benchmark anterior es la razón honesta: 0% de precisión en cargas de entrenamiento evasivas hoy. Trata workload_type como una señal para investigar, no como un veredicto.

¿Por qué no usar simplemente el clasificador ML del artículo? Sus pesos entrenados y su conjunto de datos nunca fueron publicados. Reimplementar un clasificador ML sin datos de entrenamiento reales produciría una afirmación de precisión no validada, no una medida. Ver Cómo funciona la clasificación.

¿En qué se diferencia esto de run:ai o NVIDIA DCGM? run:ai y DCGM ambos exponen o usan telemetría de GPU, pero ninguno clasifica el tipo de carga de trabajo a partir de esa telemetría. run:ai depende completamente de la etiqueta que el propietario del trabajo declara al enviarlo; DCGM solo expone métricas crudas de utilización y memoria para que otra cosa las interprete. WorkloadTruth es la capa que realmente observa la telemetría y responde la pregunta. Ver la tabla de comparación.

¿Funciona en Windows, macOS y Linux? El backend synthetic funciona en cualquier lugar donde se ejecute Python 3.9+, incluido el entorno de compilación macOS de este proyecto (que no tiene GPU NVIDIA). El backend nvml requiere una GPU NVIDIA y un controlador, lo que en la práctica significa Linux o Windows con hardware NVIDIA; NVML no está disponible en macOS.

¿Bajo qué licencia está esto y puedo usarlo comercialmente? Apache 2.0. El uso comercial, la modificación y la redistribución están permitidos bajo sus términos; ver LICENSE.

Contribuciones

Ver CONTRIBUTING.md. Problemas de seguridad: ver SECURITY.md.

Licencia

Apache 2.0