Diseño de la biblioteca
Tokamax está diseñado para estandarizar y simplificar los recorridos típicos de los desarrolladores en torno a la creación, la optimización, el mantenimiento y el uso en producción de kernels. Para ello, usa clases fundamentales y una infraestructura compartida de la que heredan todos los operadores de la biblioteca y que implementan dentro de un framework bien estructurado.
Capas de operadores
Clase base de Tokamax
tokamax.Op
es la clase fundamental de Tokamax, que sirve como base para cada operador de
la biblioteca. Cuando se invoca cualquier operador derivado, esta capa controla automáticamente
la siguiente funcionalidad:
- Vinculación de argumentos: Antes de que se ejecute cualquier cálculo, la clase base normaliza
y valida los argumentos del emisor en una sola representación canónica
para que el almacenamiento en caché, las heurísticas y la ejecución del kernel puedan razonar sobre la
carga de trabajo de manera uniforme (a través de un objeto
BoundArguments), independientemente de cómo se pasaron las entradas (consultaop.bind()). - Validación de dispositivos: Para detectar discrepancias de hardware de forma anticipada, el operador
verifica la compatibilidad del dispositivo con el acelerador de destino antes de la ejecución, a la vez que
permite omitir esta verificación cuando se compila de forma cruzada desde un host de
CPU (consulta
op.supported_on(),bypass_device_check=Trueyconfig.cross_compile(True)). - Captura de lotes: Debido a que la mejor configuración del kernel (
Config) suele depender del tamaño completo del problema por lotes, en lugar de una sola porción, la clase base captura las dimensiones de los lotes circundantes cuando se vectoriza un operador (jax.vmap) para que las heurísticas y las cachés de ajuste automático puedan optimizar la forma real de la carga de trabajo (consultaop._capture_batched_args()). - Resolución de configuración: Para proporcionar un rendimiento sólido de inmediato sin
requerir un ajuste manual, la clase base resuelve los hiperparámetros del kernel
automáticamente cada vez que el emisor no los proporciona, reutilizando la configuración
ajustada automáticamente con anterioridad en una caché de ajuste automático basada en disco, si está disponible, o recurriendo
a la heurística integrada (consulta
BoundArguments.default_config). - Serialización de metadatos de StableHLO: Para que los programas compilados sean introspectables para la generación de perfiles sin conexión y el ajuste automatizado, la clase base incorpora metadatos de operadores en el grafo reducido para que las herramientas downstream puedan reconstruir qué operadores se ejecutaron y con qué entradas (formas, tipos, etcétera) directamente desde un módulo compilado o un perfil de rendimiento (consulta
_tokamax_metadata()). - Ejecución hacia adelante y VJP personalizado: Debido a que los kernels de hardware especializados
a menudo no se pueden diferenciar de manera eficiente mediante la diferenciación automática
estándar, la clase base coordina la ejecución hacia adelante y hacia atrás
como un par, lo que permite que el pase hacia adelante pase valores intermedios directamente a
un kernel hacia atrás personalizado durante el cálculo del gradiente (consulta
op._fwd()) y las llamadas ajax.custom_vjp.
Clase base específica de la operación
Cada familia de operadores define su propia clase base que hereda de la
clase de operador fundamental y establece el contrato compartido en todos
los backends (por ejemplo, consulta
RaggedDot):
- Implementación de referencia: Cada clase base de operador proporciona una implementación de referencia portátil y pura de JAX de la especificación matemática completa, incluidos los gradientes cuando corresponda. Esto sirve como verdad fundamental para las pruebas de corrección numérica y garantiza un resguardo que funcione en cualquier hardware (consulta
RaggedDot._fwd()). - Vinculación canónica: Debido a que los usuarios pueden expresar la misma operación matemática de varias maneras, como pasar diferentes formas de máscaras, parámetros de configuración de precisión o especificaciones de dimensiones, la clase base del operador normaliza las entradas y verifica la compatibilidad de forma y tipo por adelantado para que los backends de hardware individuales solo tengan que controlar un único formato de entrada predecible (consulta
RaggedDot.bind()).
Clases de implementación de operaciones
Estas clases proporcionan las implementaciones de kernel específicas del hardware y los usuarios pueden crearlas y llamarlas directamente. Cada implementación hereda de
su clase base específica del operador y proporciona el comportamiento específico del backend (por
ejemplo, consulta
PallasMosaicTpuRaggedDot):
- Funcionalidad principal: Aquí es donde se define la ejecución real del kernel de hardware,
por lo general, con un lenguaje de kernel como Pallas. Cuando una operación requiere un pase hacia atrás especializado, el kernel de gradiente suele modelarse como su propia implementación de operador de primera clase para que se pueda configurar, ajustar y probar de forma independiente. Aunque el código de kernel de nivel más bajo suele dividirse en un archivo auxiliar independiente para la modularidad, esta clase sirve como la interfaz principal para invocar ese kernel (consulta
PallasMosaicTpuRaggedDot._fwd()). - Configuración: Debido a que los kernels de hardware suelen exponer perillas de rendimiento, como tamaños de mosaicos, etapas de canalización o estrategias de almacenamiento en búfer de memoria, cada backend define una estructura de configuración dedicada que permite a los usuarios o a las herramientas automatizadas controlar cómo se particiona, compila y ejecuta el kernel (consulta
Config). - Heurística: No todas las cargas de trabajo se ajustaron automáticamente con anticipación, por lo que cada
backend proporciona heurísticas integradas que eligen parámetros de ajuste predeterminados razonables
en función de las dimensiones del problema, los tipos de datos y las especificaciones del acelerador (consulta
_get_heuristics_config()). - Espacio de búsqueda de ajuste automático: Para las cargas de trabajo en las que el rendimiento máximo es importante,
cada backend define un espacio de búsqueda de ajuste automático de combinaciones de parámetros válidas
para una forma de problema determinada, lo que permite que el ajustador automático compare
los candidatos y descubra la configuración más rápida (consulta
_get_autotuning_configs()). - Validación específica de la implementación: Los kernels de hardware suelen tener
requisitos más estrictos que la operación matemática general, como
reglas de alineación de dimensiones o compatibilidad limitada con tipos de datos. Cada implementación
valida estas restricciones y señala cuando no se puede controlar una carga de trabajo,
lo que permite que los despachadores de nivel superior recurran de forma correcta a otro backend
(consulta
PallasMosaicTpuRaggedDot._fwd()).
API de alto nivel
La mayoría de los operadores tienen varios backends, como una implementación de referencia portátil junto con uno o más kernels específicos del hardware, y exponen un único punto de entrada familiar de alto nivel (p.ej., una función jax.lax estándar). Esta capa está diseñada para brindarles a los usuarios una interfaz simple y directa que selecciona automáticamente el mejor backend compatible para su hardware y formas de entrada, a la vez que les permite solicitar una implementación específica cuando lo deseen (consulta tokamax.ragged_dot()).
ArgSpecs
Mantener un catálogo compartido de formas de cargas de trabajo importantes es esencial para
probar y optimizar los kernels de manera coherente en todos los backends. Tokamax captura
estas formas representativas de producción y comparativas como especificaciones de carga de trabajo
que se comparten en todas las implementaciones de un operador. Esto proporciona a las pruebas de integración continua, las comparativas de regresión y las canalizaciones de ajuste automático una única fuente de información que se puede filtrar por etiquetas para diferentes flujos de trabajo (consulta las ArgSpecs de ragged_dot).
Estructura del repositorio
El código de implementación interno se encuentra en el árbol de fuentes privado (consulta
tokamax/_src),
mientras que los símbolos públicos para los operadores, el ajuste automático, la comparativa y la configuración
se vuelven a exportar a través de módulos de nivel superior (consulta
tokamax/__init__.py).
Dentro de cada directorio de operador (consulta
tokamax/_src/ops),
los archivos siguen una convención de nombres coherente, que se ilustra aquí con ragged dot:
- API de alto nivel: Define el punto de entrada funcional público y la lógica de envío del backend (consulta
api.py). - Clase base específica de la operación: Define la implementación de referencia portátil
(consulta
base.py). - Implementaciones de backend: Define clases de operadores, parámetros de configuración, heurística y espacios de ajuste automático específicos del hardware (consulta
pallas_mosaic_tpu.py). - Kernels de bajo nivel: Separa las implementaciones de kernel independientes y los ayudantes de bajo nivel compartidos en módulos complementarios (consulta
pallas_mosaic_tpu_kernel.py). - Especificaciones de la carga de trabajo: Cataloga las formas de entrada canónicas para las pruebas,
las comparativas y el ajuste automático (consulta
arg_specs.py). - Paquetes de pruebas: Define verificaciones de corrección parametrizadas compartidas junto con
paquetes de pruebas por backend (consulta
test_base.py).
Las operaciones dentro del directorio experimental siguen una estructura similar, pero es posible que no
se expongan en la API pública. Estas operaciones están diseñadas para la iteración y
la exploración rápidas, y pueden cambiar con frecuencia y de forma significativa, con expectativas generalmente más bajas
en torno al mantenimiento y la asistencia continuos.
¿A qué capa deben llamar los usuarios?
Elegir un punto de entrada es, fundamentalmente, un equilibrio entre la comodidad y el control. La mayoría de los usuarios deberían comenzar llamando a los operadores a través de la API funcional de alto nivel, que proporciona una interfaz de estilo familiar y selecciona automáticamente una implementación de backend adecuada. Cuando se necesita una selección de backend determinista, los usuarios pueden pasar una opción de implementación explícita a la función de alto nivel y, al mismo tiempo, mantener la misma firma de llamada. Para obtener el máximo control, los usuarios pueden crear una instancia de una clase de implementación de operador específica directamente para personalizar los hiperparámetros del kernel, como los tamaños de mosaico, y pasar argumentos específicos del backend.
No se recomienda llamar directamente a funciones de kernel de bajo nivel sin pasar por una clase de implementación de operador. Si lo haces, se omitirá la infraestructura esencial, incluidos el ajuste automático, la validación y canonicalización de entradas, y la serialización de metadatos, sin ofrecer ahorros significativos en la sobrecarga, ya que los wrappers de operadores son intencionalmente livianos. Por ejemplo, si no hay hiperparámetros ajustados automáticamente, es probable que los usuarios vean un rendimiento significativamente subóptimo.
Temas avanzados
Operator Fusion
Los operadores de TPU de Pallas fusionables admiten la fusión de prólogos y epílogos de JAX circundantes directamente en el kernel a través de @tokamax.ops.op_fusion.fuse. Consulta la
guía de Fusión de operadores para obtener ejemplos de uso
e instrucciones sobre cómo crear kernels compatibles con la fusión y subclases de
Op.
Serialización
Los kernels se pueden serializar en StableHLO. Las llamadas
al kernel son llamadas personalizadas de JAX, que están prohibidas de forma predeterminada en jax.export,
lo que requiere el uso de
tokamax.DISABLE_JAX_EXPORT_CHECKS para permitir que se exporten todos los kernels de Tokamax:
from jax import export
f_grad_exported = export.export(f_grad, disabled_checks=tokamax.DISABLE_JAX_EXPORT_CHECKS)(
jax.ShapeDtypeStruct(x.shape, x.dtype),
jax.ShapeDtypeStruct(scale.shape, scale.dtype),
)
Ten en cuenta que las funciones serializadas con kernels de Tokamax pierden la independencia del dispositivo de StableHLO estándar. Tokamax ofrece dos garantías de serialización:
- Se garantiza que una función deserializada que se serializó en un dispositivo específico se ejecutará en el dispositivo exacto para el que se serializó.
- Tokamax ofrece las mismas garantías de compatibilidad que JAX: retrocompatibilidad de 6 meses.
Compilación cruzada y exportación de CPU
Los kernels de Tokamax se pueden exportar o compilar de forma cruzada en un host de CPU:
- La selección de implementación explícita (p.ej.,
implementation="mosaic_tpu_v2") omite automáticamente la validación del dispositivo host. - Como alternativa, habilita la compilación cruzada de forma global con
tokamax.config.cross_compile(True):
with tokamax.config.cross_compile(True):
f_exported = export.export(
f, disabled_checks=tokamax.DISABLE_JAX_EXPORT_CHECKS
)(
jax.ShapeDtypeStruct(x.shape, x.dtype),
...,
)