Design da biblioteca

O Tokamax foi projetado para padronizar e simplificar as jornadas típicas dos desenvolvedores em relação à criação, otimização, manutenção e uso em produção de kernels. Isso é feito por meio de classes fundamentais e infraestrutura compartilhada que todos os operadores na biblioteca herdam e implementam em um framework bem estruturado.

Camadas de operador

Classe de base Tokamax

tokamax.Op é a classe fundamental do Tokamax, que serve como base para todos os operadores na biblioteca. Quando qualquer operador derivado é invocado, essa camada processa automaticamente as seguintes funcionalidades:

  • Vinculação de argumentos: antes de qualquer computação ser executada, a classe de base normaliza e valida os argumentos do autor da chamada em uma única representação canônica para que o armazenamento em cache, as heurísticas e a execução do kernel possam raciocinar sobre a carga de trabalho de maneira uniforme (por meio de um objeto BoundArguments), independentemente de como as entradas foram transmitidas (consulte op.bind()).
  • Validação do dispositivo: para detectar incompatibilidades de hardware com antecedência, o operador verifica o suporte do dispositivo em relação ao acelerador de destino antes da execução, mas ainda permite que essa verificação seja ignorada ao fazer compilação cruzada de um host de CPU (consulte op.supported_on(), bypass_device_check=True e config.cross_compile(True)).
  • Captura em lote: como a melhor configuração de kernel (Config) geralmente depende do tamanho total do problema em lote, e não de uma única fração, a classe de base captura as dimensões do lote ao redor quando um operador é vetorizado (jax.vmap) para que as heurísticas e os caches de ajuste automático possam otimizar o formato real da carga de trabalho (consulte op._capture_batched_args()).
  • Resolução de configuração: para oferecer um desempenho excelente sem ajustes manuais, a classe de base resolve os hiperparâmetros do kernel automaticamente sempre que o autor da chamada não os fornece, reutilizando as configurações ajustadas automaticamente em um cache de ajuste automático baseado em disco, se disponível, ou voltando para as heurísticas integradas (consulte BoundArguments.default_config).
  • Serialização de metadados do StableHLO: para tornar os programas compilados introspectáveis para criação de perfil off-line e ajuste automatizado, a classe de base incorporar metadados do operador ao gráfico reduzido para que as ferramentas downstream possam reconstruir quais operadores foram executados e com quais entradas (formas, tipos etc.) diretamente de um módulo compilado ou perfil de desempenho (consulte _tokamax_metadata()).
  • Execução direta e VJP personalizado: como os kernels de hardware especializados geralmente não podem ser diferenciados de maneira eficiente pela diferenciação automática padrão, a classe de base coordena a execução direta e reversa como um par, permitindo que a passagem direta transmita valores intermediários diretamente para um kernel reverso personalizado durante o cálculo de gradiente (consulte op._fwd()) e chamadas para jax.custom_vjp.

Classe de base específica da operação

Cada família de operadores define a própria classe de base que herda da classe de operador fundamental e estabelece o contrato compartilhado entre todos os back-ends (por exemplo, consulte RaggedDot):

  • Implementação de referência: cada classe de base de operador fornece uma implementação de referência portátil e pura do JAX da especificação matemática completa, incluindo gradientes quando aplicável. Isso serve como as informações empíricas para testes de correção numérica e garante um substituto funcional em qualquer hardware (consulte RaggedDot._fwd()).
  • Vinculação canônica: como os usuários podem expressar a mesma operação matemática de várias maneiras, como transmitir diferentes formas de máscaras, configurações de precisão ou especificações de dimensão, a classe de base do operador normaliza as entradas e verifica a compatibilidade de forma e tipo com antecedência para que os back-ends de hardware individuais só precisem lidar com um único formato de entrada previsível (consulte RaggedDot.bind()).

Classes de implementação de operações

Essas classes fornecem as implementações de kernel específicas do hardware e podem ser instanciadas e invocadas diretamente pelos usuários. Cada implementação herda da classe de base específica do operador e fornece o comportamento específico do back-end (por exemplo, consulte PallasMosaicTpuRaggedDot):

  • Funcionalidade principal: é onde a execução real do kernel de hardware é definida, normalmente usando uma linguagem de kernel, como Pallas. Quando uma operação requer uma passagem reversa especializada, o kernel de gradiente geralmente é modelado como uma implementação de operador de primeira classe própria para que possa ser configurado, ajustado e testado de forma independente. Embora o código do kernel de nível mais baixo seja frequentemente fatorado em um arquivo auxiliar separado para modularidade, essa classe serve como a interface principal para invocar esse kernel (consulte PallasMosaicTpuRaggedDot._fwd()).
  • Configuração: como os kernels de hardware geralmente expõem botões de desempenho, como tamanhos de blocos, estágios de pipeline ou estratégias de buffer de memória, cada back-end define uma estrutura de configuração dedicada que permite que usuários ou ferramentas automatizadas controlem como o kernel é particionado, compilado e executado (consulte Config).
  • Heurística: nem todas as cargas de trabalho foram ajustadas automaticamente com antecedência. Por isso, cada back-end oferece heurísticas integradas que escolhem parâmetros de ajuste padrão razoáveis com base nas dimensões do problema, nos tipos de dados e nas especificações do acelerador (consulte _get_heuristics_config()).
  • Espaço de pesquisa de ajuste automático: para cargas de trabalho em que o desempenho máximo é importante, cada back-end define um espaço de pesquisa de ajuste automático de combinações de parâmetros válidas para um determinado formato de problema, permitindo que o ajustador automático compare os candidatos e descubra a configuração mais rápida (consulte _get_autotuning_configs()).
  • Validação específica da implementação: os kernels de hardware geralmente têm requisitos mais rígidos do que a operação matemática geral, como regras de alinhamento de dimensões ou suporte limitado a tipos de dados. Cada implementação valida essas restrições e sinaliza quando uma carga de trabalho não pode ser processada, permitindo que os despachantes de nível superior usem outro back-end (consulte PallasMosaicTpuRaggedDot._fwd()).

API de alto nível

A maioria dos operadores tem vários back-ends, como uma implementação de referência portátil com um ou mais kernels específicos de hardware, e expõe um único ponto de entrada de alto nível familiar (por exemplo, uma função jax.lax padrão). Essa camada foi projetada para oferecer aos usuários uma interface simples e de fácil integração que seleciona automaticamente o melhor back-end compatível com o hardware e as formas de entrada, além de permitir que eles solicitem uma implementação específica quando desejado (consulte tokamax.ragged_dot()).

ArgSpecs

Manter um catálogo compartilhado de formas de carga de trabalho importantes é essencial para testar e otimizar kernels de maneira consistente em todos os back-ends. O Tokamax captura essas formas representativas de produção e comparativo de mercado como especificações de carga de trabalho que são compartilhadas entre todas as implementações de um operador. Isso fornece aos testes de integração contínua, aos comparativos de regressão e aos pipelines de ajuste automático uma única fonte de verdade que pode ser filtrada por tags para diferentes fluxos de trabalho (consulte os ArgSpecs para ragged_dot).

Estrutura do repositório

O código de implementação interna fica na árvore de origem particular (consulte tokamax/_src), enquanto os símbolos públicos para operadores, ajuste automático, comparativo de mercado e configuração são reexportados por módulos de nível superior (consulte tokamax/__init__.py).

Em cada diretório de operador (consulte tokamax/_src/ops), os arquivos seguem uma convenção de nomenclatura consistente, ilustrada aqui usando o ponto irregular:

  • API de alto nível: define o ponto de entrada funcional público e a lógica de envio do back-end (consulte api.py).
  • Classe de base específica da operação: define a implementação de referência portátil (consulte base.py).
  • Implementações de back-end: define classes de operador, configurações, heurísticas e espaços de ajuste automático específicos de hardware (consulte pallas_mosaic_tpu.py).
  • Kernels de baixo nível: separa implementações de kernel independentes e auxiliares de baixo nível compartilhados em módulos complementares (consulte pallas_mosaic_tpu_kernel.py).
  • Especificações de carga de trabalho: cataloga formas de entrada canônicas para testes, comparação de desempenho e ajuste automático (consulte arg_specs.py).
  • Pacotes de teste: define verificações de correção parametrizadas compartilhadas com pacotes de teste por back-end (consulte test_base.py).

As operações no diretório experimental seguem uma estrutura semelhante, mas podem não ser expostas na API pública. Essas operações são destinadas à iteração e exploração rápidas e podem mudar com frequência e de forma significativa, geralmente com expectativas mais baixas em relação à manutenção e ao suporte contínuos.

Qual camada os usuários devem chamar?

A escolha de um ponto de entrada é, fundamentalmente, uma compensação entre conveniência e controle. A maioria dos usuários deve começar chamando operadores pela API funcional de alto nível, que oferece uma interface de estilo familiar e seleciona automaticamente uma implementação de back-end adequada. Quando a seleção determinística de back-end é necessária, os usuários podem transmitir uma escolha de implementação explícita para a função de alto nível, mantendo a mesma assinatura de chamada. Para ter o máximo de controle, os usuários podem instanciar uma classe de implementação de operador específica diretamente para personalizar os hiperparâmetros do kernel, como tamanhos de blocos, e transmitir argumentos específicos do back-end.

Não é recomendável chamar funções de kernel de baixo nível diretamente sem passar por uma classe de implementação de operador. Isso ignora a infraestrutura essencial, incluindo ajuste automático, validação e canonização de entrada e serialização de metadados, sem oferecer economias significativas de sobrecarga, já que os wrappers de operador são intencionalmente leves. Na ausência de hiperparâmetros ajustados automaticamente, por exemplo, os usuários provavelmente vão notar um desempenho abaixo do ideal.

Tópicos avançados

Fusão de operadores

Os operadores de TPU do Pallas que podem ser combinados permitem a fusão de prólogos e epílogos do JAX diretamente no kernel usando @tokamax.ops.op_fusion.fuse. Consulte o guia Fusão de operadores para ver exemplos de uso e instruções sobre como criar kernels e subclasses Op compatíveis com fusão.

Serialização

Os kernels podem ser serializados para StableHLO. As chamadas de kernel são chamadas personalizadas do JAX, que são proibidas por padrão em jax.export, exigindo o uso de tokamax.DISABLE_JAX_EXPORT_CHECKS para permitir que todos os kernels do Tokamax sejam exportados:

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),
)

As funções serializadas com kernels Tokamax perdem a independência de dispositivo do StableHLO padrão. O Tokamax oferece duas garantias de serialização:

  1. Uma função desserializada em um dispositivo específico terá a garantia de ser executada no dispositivo exato para o qual foi serializada.
  2. O Tokamax oferece as mesmas garantias de compatibilidade do JAX: 6 meses de compatibilidade com versões anteriores.

Compilação cruzada e exportação de CPU

Os kernels do Tokamax podem ser exportados ou fazer compilação cruzada em um host de CPU:

  • A seleção de implementação explícita (por exemplo, implementation="mosaic_tpu_v2") ignora automaticamente a validação do dispositivo host.
  • Como alternativa, ative a compilação cruzada globalmente usando 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),
      ...,
  )