Оператор 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", включая прямую/dlhsgmm_v2и drhstgmm_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 ядра:
tokamax/ops/op_fusion.pyповторно экспортируетfuseв качестве общедоступной точки входа.tokamax._src.ops.fuser_adapterустанавливает флаг контекста пользователя JAX (in_op_fusion_context()) вокругjax.experimental.pallas.fuser.fuse.- Когда
Op.__call__выполняется в этом контексте, он проверяет, переопределяет ли подкласс_fusible_fwd(если нет, то вызываетNotImplementedError) и делегируетfuser_adapter.call_fusible_op. 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):
- Задайте для
fusible_argnamesназвания параметров, чьи листья массива должны оставаться замыканиямиfuser.Fusion. Все остальные аргументы массива (например, метаданные, индексы илиgroup_sizes) автоматически преобразуются в обычныеjax.Arrayс помощьюcall_fusible_opперед запуском_fusible_fwd. - Переопределить
_fusible_fwd. В отличие от_fwd(которая возвращает(out, residuals)),_fusible_fwdвозвращает выходные данныеTнапрямую и получаетout_fusionsи разрешенноеconfig. - Для составных операндов 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 xfuser.fusibleоборачивает каждый лист входного массива вFusion, даже если у этого операнда нет операций-производителей. Распаковка тривиальных замыканий позволяет сохранить нетронутые операнды на неизмененном неслитом путиBlockSpecбез дополнительных затрат времени на выполнение.Если базовое ядро декорировано с помощью
@jax.jit, вызовитеinspect.unwrap(base_kernel)на пути объединения.@jax.jitотклоняет аргументыfuser.Fusion.Если вызывающие объекты bare-kernel также должны иметь возможность вызывать вашу точку входа fusible непосредственно внутри
@fuser.fuse, обнаруживайте вызовы barejax.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
- Передайте полученные входные данные HBM вместе с извлеченными значениями
BlockSpec:- Вместо объединенного операнда (в паре с
lhs_val_specs) вставьте прологvalues. - Выходные дополнительные входные данные эпилога (
out_values, например смещение эпилога или остаток) передаются как входные данные ядра HBM, доступные только для чтения, в паре сout_fusion_input_specs, чтобыpltpu.emit_pipelineпредварительно загружал их тайлы в VMEM. Если слияние не выполнено, передайте пустой кортеж()для ссылок и спецификаций (0 листьев PyTree).
- Вместо объединенного операнда (в паре с
- Используйте разные типы 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).
Оцените обратные вызовы, полученные на тайлах 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сSequenceout_type:pl.kernelраспаковываетtupleилиlistout_typeв несколько позиционных аргументовout_ref. При использованииfuser_adapter.unpack_output_fusionодиночные выходные данныеout_initостаются в видеShapeDtypeStruct.- Дополнение на стороне хоста и объединенные формы. Поскольку в Pallas Fuser нет правила
lax.padили невыровненных правил push/pulllax.slice, проверяйте требования к выравниванию на раннем этапе в методеprepare()спецификации объединения и вызывайтеNotImplementedErrorдля неподдерживаемых форм, а не дополняйте объектыFusion. - Вспомогательные функции
Opвнутри_fusible_fwd.call_fusible_opприостанавливаетin_op_fusion_context()во время разрешенияdefault_configи внутри_fusible_fwd, поэтому вызов несвязанной вспомогательной функцииOpвнутри_fusible_fwdзапускает ее обычный путь_fwd, не вызывая ошибок вложенного связывания.
Контрольный список для тестирования
При добавлении поддержки слияния к оператору охватите:
- Объединение пролога (поточечное и полноосевое сокращение, например
RMSNorm), объединение эпилога (с внешними боковыми входами, такими как смещение или остаток, и без них) и комбинированное объединение пролога и эпилога. - Паритет без слияния. Убедитесь, что вызов точки входа слияния без окружающих операций (простой,
@op_fusion.fuseи@fuser.fuse) дает побитово идентичный вывод (chex.assert_trees_all_equal) для ядра без слияния. - Явные градиенты
@jax.custom_vjp. Проверьте, совпадают ли прямые значения и градиенты с несвязанными эталонными. - Неподдерживаемые комбинации. Проверьте сообщения clear
NotImplementedErrorна наличие невыровненных фигур или несовместимых параметров ядра.
Пример реализации
- Общедоступный фасад:
tokamax/ops/op_fusion.py Opдиспетчер и общие помощники:tokamax/_src/ops/fuser_adapter.py- Интеграция Kernel Fuser (
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py - Интеграция с
Op._fusible_fwd:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py - Тесты ядра и слияния
Op:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pyиtokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py