图书馆设计
Tokamax 旨在标准化和简化围绕内核编写、优化、维护和生产使用的典型开发者历程。它通过基础类和共享基础架构来实现这一点,库中的所有运算符都继承自这些基础类和共享基础架构,并在结构良好的框架中实现。
Operator 层
Tokamax 基类
tokamax.Op 是 Tokamax 的基础类,用作库中每个算子的基类。调用任何派生运算符时,此层会自动处理以下功能:
- 实参绑定:在运行任何计算之前,基类会将调用方的实参标准化并验证为单一规范表示法,以便缓存、启发法和内核执行都可以统一推理工作负载(通过
BoundArguments对象),而无需考虑输入是如何传递的(请参阅op.bind())。 - 设备验证:为了尽早发现硬件不匹配问题,算子会在运行前根据目标加速器验证设备支持情况,同时在从 CPU 主机进行交叉编译时仍允许绕过此检查(请参阅
op.supported_on()、bypass_device_check=True和config.cross_compile(True))。 - 批处理捕获:由于最佳内核配置 (
Config) 通常取决于完整的批处理问题大小,而不是单个切片,因此基类会在算子向量化 (jax.vmap) 时捕获周围的批处理维度,以便启发式算法和自动调优缓存可以针对真实工作负载形状进行优化(请参阅op._capture_batched_args())。 - 配置解析:为了提供开箱即用的强大性能,而无需手动调优,每当调用方未提供内核超参数时,基类都会自动解析这些超参数。如果可用,它会重复使用基于磁盘的自动调优缓存中先前自动调优的设置,或者回退到内置启发法(请参阅
BoundArguments.default_config)。 - StableHLO 元数据序列化:为了使编译后的程序可内省,以便进行离线性能分析和自动调优,基类会将算子元数据嵌入到降级后的计算图中,以便下游工具可以直接从编译后的模块或性能分析文件中重构哪些算子运行了以及使用了哪些输入(形状、类型等)(请参阅
_tokamax_metadata())。 - 前向执行和自定义 VJP:由于标准自动微分通常无法高效微分专用硬件内核,因此基类将前向和后向执行作为一个整体进行协调,从而允许前向传递在梯度计算期间将中间值直接传递给自定义后向内核(请参阅
op._fwd())并调用jax.custom_vjp。
特定于操作的基类
每个运算符系列都会定义自己的基类,该基类继承自基础运算符类,并建立在所有后端之间共享的协定(例如,请参阅 RaggedDot):
- 参考实现:每个算子基类都提供了一个可移植、纯 JAX 的参考实现,涵盖完整的数学规范,包括梯度(如适用)。这可作为数值正确性测试的标准答案,并保证在任何硬件上都能正常回退(请参阅
RaggedDot._fwd())。 - 规范绑定:由于用户可以通过多种方式表达相同的数学运算(例如传递不同形式的掩码、精度设置或维度规范),因此算子基类会预先对输入进行归一化并检查形状和类型兼容性,以便各个硬件后端只需处理单一、可预测的输入格式(请参阅
RaggedDot.bind())。
Op 实现类
这些类提供特定于硬件的内核实现,可由用户直接实例化和调用。每个实现都继承自其特定于算子的基类,并提供特定于后端的行为(例如,请参阅 PallasMosaicTpuRaggedDot):
- 核心功能:这是定义实际硬件内核执行的位置,通常使用 Pallas 等内核语言。当某个运算需要专门的反向传递时,梯度内核通常会建模为自己的一级算子实现,以便可以独立配置、调优和测试。虽然为了实现模块化,最低级别的内核代码通常会分解到单独的辅助文件中,但此类是调用该内核的主接口(请参阅
PallasMosaicTpuRaggedDot._fwd())。 - 配置:由于硬件内核通常会公开性能旋钮(例如图块大小、流水线阶段或内存缓冲策略),因此每个后端都会定义一个专用配置结构,让用户或自动化工具能够控制内核的分区、编译和执行方式(请参阅
Config)。 - 启发法:并非每个工作负载都已提前自动调优,因此每个后端都提供内置启发法,可根据问题维度、数据类型和加速器规范选择合理的默认调优参数(请参阅
_get_heuristics_config())。 - 自动调优搜索空间:对于注重峰值性能的工作负载,每个后端都会为给定的问题形状定义一个由有效参数组合组成的自动调优搜索空间,以便自动调优器对候选配置进行基准测试并发现最快的配置(请参阅
_get_autotuning_configs())。 - 实现专用验证:硬件内核的要求通常比一般数学运算更严格,例如维度对齐规则或有限的数据类型支持。每个实现都会验证这些限制,并在无法处理工作负载时发出信号,从而使更高级别的调度程序能够正常回退到另一个后端(请参阅
PallasMosaicTpuRaggedDot._fwd())。
高阶 API
大多数算子都有多个后端(例如,一个可移植的参考实现以及一个或多个特定于硬件的内核),并公开一个熟悉的单一高级入口点(例如,标准 jax.lax 函数)。此层旨在为用户提供一个简单的即插即用接口,该接口可自动为其硬件和输入形状选择最受支持的后端,同时仍允许用户在需要时请求特定实现(请参阅 tokamax.ragged_dot())。
ArgSpecs
维护重要工作负载形状的共享目录,对于在不同后端之间一致地测试和优化内核至关重要。Tokamax 会将这些具有代表性的生产和基准形状捕获为工作负载规范,并在算子的所有实现之间共享。这为持续集成测试、回归基准和自动调优流水线提供了单一事实来源,可按不同工作流的标记进行过滤(请参阅 ragged_dot 的 ArgSpecs)。
代码库结构
内部实现代码位于私有源代码树(请参阅 tokamax/_src)下,而运算符、自动调优、基准测试和配置的公共符号则通过顶级模块重新导出(请参阅 tokamax/__init__.py)。
在每个运营商目录(请参阅 tokamax/_src/ops)中,文件遵循一致的命名惯例,此处使用 ragged dot 进行了说明:
- 高级 API:定义公共功能入口点和后端调度逻辑(请参阅
api.py)。 - 特定于操作的基类:定义可移植的参考实现(请参阅
base.py)。 - 后端实现:定义特定于硬件的算子类、配置、启发式算法和自动调优空间(请参阅
pallas_mosaic_tpu.py)。 - 低级内核:将独立的内核实现和共享的低级辅助程序分离到配套模块中(请参阅
pallas_mosaic_tpu_kernel.py)。 - 工作负载规范:对规范输入形状进行分类,以便进行测试、基准测试和自动调优(请参阅
arg_specs.py)。 - 测试套件:定义共享的参数化正确性检查以及每个后端的测试套件(请参阅
test_base.py)。
experimental 目录中的操作遵循类似的结构,但可能不会在公共 API 中公开。这些操作旨在实现快速迭代和探索,可能会频繁且显著地发生变化,通常对持续维护和支持的期望较低。
用户应调用哪一层
选择入口点基本上是在便利性和控制力之间进行权衡。大多数用户应首先通过高级函数式 API 调用算子,该 API 提供熟悉的样式接口,并自动选择合适的后端实现。如果需要确定性后端选择,用户可以向高级函数传递显式实现选择,同时保持相同的调用签名。为了实现最大程度的控制,用户可以直接实例化特定的算子实现类,以自定义内核超参数(例如图块大小)并传递特定于后端的参数。
不建议直接调用低级内核函数,而不通过算子实现类。这样做会绕过重要的基础架构(包括自动调节、输入验证和规范化以及元数据序列化),而不会节省任何有意义的开销,因为算子封装容器有意设计得轻量。例如,如果没有适当的自动调优超参数,用户可能会看到明显不理想的性能。
高级主题
算子融合
可融合的 Pallas TPU 算子支持通过 @tokamax.ops.op_fusion.fuse 将周围的 JAX 前导和后继直接融合到内核中。如需查看用法示例以及有关编写融合兼容内核和 Op 子类的说明,请参阅算子融合指南。
序列化
内核可以序列化为 StableHLO。内核调用是 JAX 自定义调用,默认情况下在 jax.export 中被禁止,需要使用 tokamax.DISABLE_JAX_EXPORT_CHECKS 才能导出所有 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),
)
请注意,使用 Tokamax 内核序列化的函数会失去标准 StableHLO 的设备独立性。Tokamax 提供两项序列化保证:
- 在特定设备上序列化的反序列化函数可保证在序列化时所用的确切设备上运行。
- Tokamax 提供与 JAX 相同的兼容性保证:6 个月的向后兼容性。
交叉编译和 CPU 导出
Tokamax 内核可以在 CPU 主机上导出或交叉编译:
- 显式实现选择(例如
implementation="mosaic_tpu_v2")会自动绕过主机设备验证。 - 或者,使用
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),
...,
)