Оператор Fusion

tokamax.ops.op_fusion позволяет объединять окружающие операции JAX (прологи и эпилоги) непосредственно в объединяемое ядро Tokamax Pallas TPU с помощью JAX Pallas Fuser. Вместо того чтобы материализовать промежуточные активации в HBM между нормализацией или активацией и пользовательским ядром, объединенные операции выполняются в VMEM на каждом фрагменте внутри цикла ядра.

Использование @op_fusion.fuse

Основные функции (пролог и эпилог)

Импортируйте op_fusion из tokamax.ops и оберните функцию, содержащую оператор Tokamax, который можно объединить, с помощью @op_fusion.fuse (обычно внутри @jax.jit):

import jax
import jax.numpy as jnp
import tokamax
from tokamax.ops import op_fusion


def rms_norm(x: jax.Array, weight: jax.Array, eps: float = 1e-6) -> jax.Array:
  ms = jnp.mean(jnp.square(x.astype(jnp.float32)), axis=-1, keepdims=True)
  return (x.astype(jnp.float32) * jax.lax.rsqrt(ms + eps)).astype(
      x.dtype
  ) * weight


@jax.jit
@op_fusion.fuse
def fused_ragged_dot(x, rms_weight, rhs, out_bias, group_sizes):
  # Prologue: fused into the kernel's LHS tile load.
  x_norm = rms_norm(x, rms_weight)
  out = tokamax.ragged_dot(
      x_norm,
      rhs,
      group_sizes=group_sizes,
      implementation="mosaic_tpu_v2",
  )
  # Epilogue: fused into the kernel's output store.
  return jax.nn.silu(out + out_bias)

Вы можете вызвать либо высокоуровневый функциональный API с явной реализацией объединения (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")), либо непосредственно экземпляр tokamax.Op (например, PallasMosaicTpuV2RaggedDot). Если оператор внутри @op_fusion.fuse не поддерживает объединение, Tokamax выдает ошибку NotImplementedError.

Параметры декоратора

op_fusion.fuse передает свои аргументы ключевых слов в jax.experimental.pallas.fuser.fuse:

@op_fusion.fuse(
    resolve_fusion_dtypes=True,
    debug=False,
    strict_mode=True,
    static_argnums=None,
    static_argnames=None,
)
  • static_argnums/static_argnames – помечает аргументы Python, не являющиеся массивами (например, скалярные значения конфигурации или логические флаги), как статические при вызове объединенной функции.
  • debug=True: выводит трассированные jaxpr-выражения, чтобы помочь диагностировать, почему операция не была объединена или не удалось распространить спецификацию блока.
  • strict_mode: управляет строгими проверками эквивалентности спецификаций блоков Pallas Fuser.

Квантованные входные данные и встроенные активации ядра

Объединенные прологи состоят из квантования активации на лету (AsQArray), предварительно квантованных весов (qwix.QArray) и встроенных объединенных активаций gate/up на PallasMosaicTpuV2RaggedDot:

import jax
import jax.numpy as jnp
import qwix
from tokamax._src import quantization
from tokamax._src.ops.ragged_dot import pallas_mosaic_tpu_v2
from tokamax.ops import op_fusion

gmm_op = pallas_mosaic_tpu_v2.PallasMosaicTpuV2RaggedDot()


@op_fusion.fuse
def fused_rms_norm_gate_up(x, rms_weight, w_q, w_scale, group_sizes):
  x_norm = rms_norm(x, rms_weight)
  return gmm_op(
      quantization.AsQArray(x_norm, jnp.float8_e4m3fn),
      qwix.QArray(w_q, w_scale),
      group_sizes=group_sizes,
      zero_initialize=False,
      fuse_gateup_activation="silu",
      preferred_element_type=jnp.bfloat16,
  )

Одна операция Fusible на блок @op_fusion.fuse

JAX Pallas Fuser поддерживает одно объединяемое ядро на область @op_fusion.fuse. При объединении нескольких ядер (например, gate_up, за которым следует down в блоке MoE) оберните каждый объединяемый этап в его собственную функцию @op_fusion.fuse внутри внешней функции @jax.jit:

@jax.jit
def moe_layer(x, rms_weight, w1_q, w1_scale, w2_q, w2_scale, group_sizes):
  mid = fused_rms_norm_gate_up(x, rms_weight, w1_q, w1_scale, group_sizes)
  return gmm_op(
      quantization.AsQArray(mid, jnp.float8_e4m3fn),
      qwix.QArray(w2_q, w2_scale),
      group_sizes=group_sizes,
      zero_initialize=False,
      preferred_element_type=jnp.bfloat16,
  )

Автоматическое дифференцирование с явным @jax.custom_vjp

@op_fusion.fuse объединяет блок прямого вычисления и не синтезирует автоматически объединенные обратные проходы через jax.grad. При дифференцировании объединенного блока оберните прямые и обратные вызовы в явный @jax.custom_vjp, чтобы вы могли объединять прологи/эпилоги в прямые и обратные (drhs / dlhs) ядра независимо друг от друга:

import jax
from tokamax._src.ops.ragged_dot import pallas_mosaic_tpu_v2
from tokamax.ops import op_fusion

op = pallas_mosaic_tpu_v2.PallasMosaicTpuV2RaggedDot()
drhs_op = pallas_mosaic_tpu_v2.PallasMosaicTpuV2RaggedDot(
    num_actual_groups=num_groups
)


@op_fusion.fuse
def fused_fwd_kernel(x, w, r, group_sizes):
  return op(rms_norm(x, w), r, group_sizes=group_sizes, zero_initialize=True)


@op_fusion.fuse
def fused_drhs_kernel(x, w, dy, group_sizes):
  return drhs_op(
      rms_norm(x, w),
      dy,
      group_sizes=group_sizes,
      ragged_dot_dimension_numbers=pallas_mosaic_tpu_v2.DRHS_RAGGED_DOT_DIM_NUMS,
      preferred_element_type=dy.dtype,
  )


@jax.custom_vjp
def fused_gmm(x, w, r, group_sizes):
  return fused_fwd_kernel(x, w, r, group_sizes)


def fused_gmm_fwd(x, w, r, group_sizes):
  return fused_fwd_kernel(x, w, r, group_sizes), (x, w, r, group_sizes)


def fused_gmm_bwd(residuals, dy):
  x, w, r, group_sizes = residuals
  dr = fused_drhs_kernel(x, w, dy, group_sizes)
  dx_norm = op(
      dy,
      r,
      group_sizes=group_sizes,
      ragged_dot_dimension_numbers=pallas_mosaic_tpu_v2.DLHS_RAGGED_DOT_DIM_NUMS,
      zero_initialize=True,
  )
  _, rms_vjp = jax.vjp(rms_norm, x, w)
  dx, dw = rms_vjp(dx_norm)
  return dx, dw, dr, None


fused_gmm.defvjp(fused_gmm_fwd, fused_gmm_bwd)

Использование ядер Bare Fusible

Используйте @op_fusion.fuse с оболочками операторов Tokamax (tokamax.ragged_dot или PallasMosaicTpuV2RaggedDot), а не простые ядра fusible и @jax.experimental.pallas.fuser.fuse, чтобы обеспечить обратную совместимость и сохранить канонизацию входных данных, автонастройку и сериализацию метаданных. Если вы вызываете низкоуровневые ядра gmm_v2/tgmm_v2 напрямую, используйте gmm_fuser.gmm_v2_fusible или gmm_fuser.tgmm_v2_fusible внутри @op_fusion.fuse или @jax.experimental.pallas.fuser.fuse:

from jax.experimental.pallas import fuser
from tokamax._src.ops.gmm_v2 import gmm_fuser


@jax.jit
@fuser.fuse
def fused_bare_gmm(x, w, rhs, out_bias, group_sizes):
  out = gmm_fuser.gmm_v2_fusible(rms_norm(x, w), rhs, group_sizes)
  return jax.nn.silu(out + out_bias)

Если gmm_v2_fusible/tgmm_v2_fusible не окружены операциями пролога или эпилога, тривиальные объединения с нулевым уравнением разворачиваются, чтобы скомпилированное ядро использовало точный путь без объединения.

Поддерживаемые операции и ограничения

  • Поддерживаемые операции Tokamax: PallasMosaicTpuV2RaggedDot (implementation="mosaic_tpu_v2", включая прямую/dlhs gmm_v2 и drhs tgmm_v2).
  • Поддерживаемые примитивы JAX для пролога и эпилога: управляются JAX Pallas Fuser. Обычно поддерживаются такие операции, как поэлементные унарные и бинарные математические операции, select/clamp, приведение типов данных, broadcast_in_dim, transpose, concatenate/stack/split и reduce_sum по всей оси блока (например, RMSNorm). Операции без правил спецификации блоков, такие как lax.pad, управление потоком (scan/while/cond) и reduce_max/reduce_min, не могут быть объединены.
  • Ограничения на объединение PallasMosaicTpuV2RaggedDot:
    • size_m должно быть выровнено по тайлингу подполосы TPU (size_lhs_sublane), когда lhs или out объединены в gmm_v2 (и когда lhs или rhs объединены в tgmm_v2).
    • Когда out объединен, out_size_n (и size_k для tgmm_v2) должны быть выровнены по num_lanes (128) или размеру фрагмента. Поддерживаются только эпилоги с одним выходом.
    • partial_sum не поддерживается при объединении.
    • Объединенный оператор rhs в gmm_v2 не поддерживается вместе с fuse_act или весами, упакованными в суббайты.

Создание совместимого с Fusion ядра и операции

Обзор архитектуры

Диспетчеризация Fusion разделена между общедоступным фасадом, внутренним адаптером, классом Op и сопутствующим модулем fuser ядра:

  1. tokamax/ops/op_fusion.py повторно экспортирует fuse в качестве общедоступной точки входа.
  2. tokamax._src.ops.fuser_adapter устанавливает флаг контекста пользователя JAX (in_op_fusion_context()) вокруг jax.experimental.pallas.fuser.fuse.
  3. Когда Op.__call__ выполняется в этом контексте, он проверяет, переопределяет ли подкласс _fusible_fwd (если нет, то вызывает NotImplementedError) и делегирует fuser_adapter.call_fusible_op.
  4. call_fusible_op приостанавливает контекст слияния при разрешении bound_args.default_config, связывает примитив fuser.fusible с листьями массива, материализует любой аргумент, не указанный в Op.fusible_argnames, и вызывает Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs) внутри bound_args._tokamax_metadata(config).

Шаг 1. Объявите fusible_argnames и переопределите _fusible_fwd в Op

В подклассе Op на сервере (полное описание приведено в разделе PallasMosaicTpuV2RaggedDot):

  1. Задайте для fusible_argnames названия параметров, чьи листья массива должны оставаться замыканиями fuser.Fusion. Все остальные аргументы массива (например, метаданные, индексы или group_sizes) автоматически преобразуются в обычные jax.Array с помощью call_fusible_op перед запуском _fusible_fwd.
  2. Переопределить _fusible_fwd. В отличие от _fwd (которая возвращает (out, residuals)), _fusible_fwd возвращает выходные данные T напрямую и получает out_fusions и разрешенное config.
  3. Для составных операндов PyTree, листья которых не должны быть объединены (например, предварительно квантованные веса QArray(qvalue, scale)), явно материализуйте их с помощью fuser_adapter.materialize(...).
from typing import ClassVar, override
import jax
from tokamax._src.ops import fuser_adapter


class MyPallasTpuOp(MyBaseOp[Config, None]):
  config_cls: ClassVar[type[Config]] = Config
  fusible_argnames: ClassVar[tuple[str, ...]] = ("lhs", "rhs")

  @override
  def _fusible_fwd(
      self,
      lhs: jax.Array | fuser_adapter.InputFusion,
      rhs: jax.Array | fuser_adapter.InputFusion,
      *,
      out_fusions: fuser_adapter.OutputFusion | None = None,
      config: Config,
      **kwargs,
  ) -> jax.Array:
    return my_kernel_fusible(
        lhs, rhs, config=config, out_fusions=out_fusions, **kwargs
    )

Шаг 2. Оставьте интеграцию Fuser в сопутствующем модуле *_fuser.py

Следуйте разделению Tokamax между основным ядром (gmm_v2.py, tgmm_v2.py) и его интеграцией с fuser (gmm_fuser.py):

  • Не добавляйте импорт jax.experimental.pallas.fuser в основной файл ядра, чтобы несплавленное ядро оставалось автономным и легко читаемым.
  • Распакуйте тривиальные замыкания fuser.Fusion с 0 уравнений, прежде чем создавать спецификацию слияния:

    def _unwrap_trivial_input_fusion(x):
      if isinstance(x, fuser.Fusion) and not jax.make_jaxpr(x)().jaxpr.eqns:
        return x()
      return x
    

    fuser.fusible оборачивает каждый лист входного массива в Fusion, даже если у этого операнда нет операций-производителей. Распаковка тривиальных замыканий позволяет сохранить нетронутые операнды на неизмененном неслитом пути BlockSpec без дополнительных затрат времени на выполнение.

  • Если базовое ядро декорировано с помощью @jax.jit, вызовите inspect.unwrap(base_kernel) на пути объединения. @jax.jit отклоняет аргументы fuser.Fusion.

  • Если вызывающие объекты bare-kernel также должны иметь возможность вызывать вашу точку входа fusible непосредственно внутри @fuser.fuse, обнаруживайте вызовы bare jax.Array и автоматически связывайте fuser.fusible (как это делает gmm_fuser.gmm_v2_fusible).

Шаг 3. Распакуйте слияния и преобразуйте BlockSpec с помощью fuser_adapter

Используйте общие вспомогательные функции в tokamax._src.ops.fuser_adapter, а не вызывайте низкоуровневые API fuser напрямую.

  • Распаковка пролога входных данных

    lhs_fn, lhs_values, lhs_values_type = fuser_adapter.unpack_input_fusion(lhs)
    

    Возвращает (fn, values, values_type), где values – кортеж массивов HBM, закрытых прологом, а values_type содержит их ShapeDtypeStruct.

  • Распаковка эпилога с одним выходом

    out_fn, out_values, out_values_type, out_init = (
        fuser_adapter.unpack_output_fusion(out_fusions, raw_out_type)
    )
    

    Распаковывает выходные данные Pallas Fuser в виде кортежа из одного элемента в один объект ShapeDtypeStruct (out_init) и вызывает ошибку NotImplementedError, если в эпилоге несколько выходных данных.

  • Перемещение входных данных BlockSpec назад через пролог

    pulled_lhs_fn, lhs_val_specs = fuser_adapter.pull_input_spec(
        lhs_fn,
        lhs_spec,
        lhs_values_type,
        grid_len=grid_len,
        num_scalar_prefetch=0,
    )
    
  • Передача выходных данных BlockSpec через эпилог

    pulled_out_fn, out_fusion_input_specs, final_out_spec = (
        fuser_adapter.push_pull_block_spec(
            out_fn,
            out_spec,
            out_values_type,
            raw_out_type,
            grid_len=grid_len,
            num_scalar_prefetch=0,
        )
    )
    

    fuser_adapter.push_pull_block_spec обрабатывает редукции с сохранением формы с трансляциями размера 1 (например, эпилоги RMSNorm, которые вызывают необработанный fuser.push_block_spec), проверяет, что извлеченная спецификация соответствует записанному ядром out_spec, разворачивает возвращаемое значение кортежа из 1 элемента и поддерживает совместимость между поддерживаемыми выпусками JAX.

Шаг 4. Подключите спецификации и обратные вызовы к ядру Pallas

  1. Передайте полученные входные данные HBM вместе с извлеченными значениями BlockSpec:
    • Вместо объединенного операнда (в паре с lhs_val_specs) вставьте пролог values.
    • Выходные дополнительные входные данные эпилога (out_values, например смещение эпилога или остаток) передаются как входные данные ядра HBM, доступные только для чтения, в паре с out_fusion_input_specs, чтобы pltpu.emit_pipeline предварительно загружал их тайлы в VMEM. Если слияние не выполнено, передайте пустой кортеж () для ссылок и спецификаций (0 листьев PyTree).
  2. Используйте разные типы PyTree для каждого режима слияния.
    • pltpu.emit_pipeline сопоставляет jax.tree.map(..., in_specs, in_refs), поэтому каждый входной контейнер ref и его контейнер in_spec должны иметь один и тот же тип PyTree @jax.tree_util.register_dataclass (например, LhsRef[T] для несвязанного lhs и FusedLhsRef[T] для связанного с прологом lhs).
  3. Оцените обратные вызовы, полученные на тайлах VMEM внутри тела ядра:

    • Каждая извлеченная функция имеет сигнатуру fn(program_ids, scalar_prefetch, *args).
    • Внутри pltpu.emit_pipeline(..., _explicit_indices=True) передайте pids = step.index (в противном случае tuple(pl.program_id(i) for i in range(grid_len))) и (), когда num_scalar_prefetch=0:
    # Prologue: compute the input tile from prefetched VMEM refs.
    tiled_lhs = lhs_fn(pids, (), tuple(r[...] for r in lhs_val_refs))
    
    # Epilogue: transform the accumulated output tile before storing.
    out_vals = tuple(r[...] for r in tiled_out_fusion_input_refs)
    out_tile = out_fn(pids, (), out_vals, acc_tile)
    

Наиболее распространенные ошибки

  • pl.BoundedSlice и reshape: правило извлечения изменения формы Pallas Fuser отклоняет pl.BoundedSlice. Если ваше неслитое ядро преобразует двумерные входные данные HBM в трехмерные ссылки с мозаичным разбиением на поддорожки перед emit_pipeline, преобразуйте спецификацию в двумерную BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...) перед извлечением или отправкой через слитые операнды (см. _to_2d_bounded_spec в gmm_fuser.py).
  • Порядок эпилога с маскированием строк. Если ваше ядро маскирует строки, не входящие в группу, или строки заполнения до нуля и объединяет частичные фрагменты подстрок на разных этапах, запустите out_fn перед применением нулевой маски, чтобы ненулевые эпилоги (например, + bias) не повредили маскированные строки.
  • pl.kernel с Sequence out_type: pl.kernel распаковывает tuple или list out_type в несколько позиционных аргументов out_ref. При использовании fuser_adapter.unpack_output_fusion одиночные выходные данные out_init остаются в виде ShapeDtypeStruct.
  • Дополнение на стороне хоста и объединенные формы. Поскольку в Pallas Fuser нет правила lax.pad или невыровненных правил push/pull lax.slice, проверяйте требования к выравниванию на раннем этапе в методе prepare() спецификации объединения и вызывайте NotImplementedError для неподдерживаемых форм, а не дополняйте объекты Fusion.
  • Вспомогательные функции Op внутри _fusible_fwd. call_fusible_op приостанавливает in_op_fusion_context() во время разрешения default_config и внутри _fusible_fwd, поэтому вызов несвязанной вспомогательной функции Op внутри _fusible_fwd запускает ее обычный путь _fwd, не вызывая ошибок вложенного связывания.

Контрольный список для тестирования

При добавлении поддержки слияния к оператору охватите:

  1. Объединение пролога (поточечное и полноосевое сокращение, например RMSNorm), объединение эпилога (с внешними боковыми входами, такими как смещение или остаток, и без них) и комбинированное объединение пролога и эпилога.
  2. Паритет без слияния. Убедитесь, что вызов точки входа слияния без окружающих операций (простой, @op_fusion.fuse и @fuser.fuse) дает побитово идентичный вывод (chex.assert_trees_all_equal) для ядра без слияния.
  3. Явные градиенты @jax.custom_vjp. Проверьте, совпадают ли прямые значения и градиенты с несвязанными эталонными.
  4. Неподдерживаемые комбинации. Проверьте сообщения clear NotImplementedError на наличие невыровненных фигур или несовместимых параметров ядра.

Пример реализации