hijax を使った新しい Jax 型の定義
Defining new Jax types with hijax (docs.jax.dev)
要約
この記事は、JAXフレームワークにおけるカスタムデータ型定義のための「hijax」機能について解説しています。hijaxを使用すると、標準的な配列を超えた独自のデータ型を定義でき、データの不変性維持、複雑なデータ構造の管理、自動微分やvmap処理の改善に役立ちます。例として、量子化配列型の実装方法が紹介されています。
全文翻訳
hijax を使った新しい JAX 型の定義
JAX の組み込みの通貨は配列です。変換される関数は配列を入力として受け取り、配列を出力します。また、トレーシング機構が見るすべての中間値は f32[3,4] のような配列型を持ちます。集計データを扱いたい場合、通常のツールは pytree です。配列をコンテナにバンドルすると、JAX はバンドルを配列の葉(leaves)に透過的にフラット化します。
しかし、透過性が望ましくない場合もあります。一部のデータは、独自のアイデンティティを持つ新しい型としてモデル化するのが最善です。
- jaxprs では、配列の葉の散布ではなく、単一型の単一値として表示されるべきです。
- 内部不変条件を持つため、ユーザーはコンポーネントを自由に構築したりパターンマッチしたりするのではなく、固定された操作セットを通じてのみ生成および消費すべきです。
- その接線型(tangent type)は、それに対する微分が単に「接線用の同じ pytree」ではないように、その原始構造とは異なる場合があります。
vmapの下で独自のバッチ処理の概念を持つ場合があります。- 型にシャーディング情報を含めることができ、JAX の明示的なシャーディングモードに参加できます。
hijax 型(または「hi 型」)はこれを提供します。HiType をサブクラス化して型を定義し、その型の値を持つ Python クラスを登録し、新しい型を言及する入力および出力型を持つ hijax プリミティブを記述します。このドキュメントでは、量子化配列型という 1 つの実行例で、このストーリー全体を説明します。
hijax プリミティブにある程度の習熟があることを前提とします。カスタム微分ルールと hijax プリミティブ を参照してください。hijax の他のすべてと同様に、これは実験的なものです。jax.experimental.hijax からのインポートを想定し、API が進化することを想定してください。
TL;DR
HiTypeをサブクラス化し、lo_ty、lower_val、raise_valを実装して、型とその値が通常の(「lojax」)配列にどのように低レベル化されるかを定義し、register_hitypeを呼び出して値クラスを型に関連付けます。- 新しい型を言及する
HiPrimサブクラスを記述します。これらは、型の値が生成および消費される唯一の方法です。 - 自動微分の場合、型で
to_tangent_avalを実装し、プリミティブで VJP/JVP ルールを実装します。 vmapの場合、型でdec_rankとinc_rankを実装し、独自の設計のMappingSpecサブクラスとプリミティブのbatchルールを実装します。マップされた hi 型引数には、明示的なaxis_sizeと spec 値のin_axes/out_axesエントリが必要です。- 型でのシャーディング(明示モード)の場合、型にシャーディングデータを記録し、
lo_tyで消費し、プリミティブの型付けルールで伝播させます。
例:量子化配列
int8 に量子化された配列を扱いたいとします。量子化配列は実際には 2 つの配列のペアです。int8 値と、各行で共有される浮動小数点スケールです(つまり、一般的な行ごとの/チャネルごとの量子化スキームのように、最後の軸に沿って量子化し、行ごとに 1 つのスケールを使用します)。
import os
os.environ["XLA_FLAGS"] = '--xla_force_host_platform_device_count=8'
# (最後のシャーディングセクションのために 8 つの CPU デバイス)
from dataclasses import dataclass
import jax
import jax.numpy as jnp
@dataclass(frozen=True)
class QArray:
qvalue: jax.Array # int8[*leading, n]
scale: jax.Array # f32[*leading]
QArray を pytree として登録して完了することもできます。しかし、失うものを考えてみましょう。
- 不変条件。 2 つのコンポーネントは連動しています。
scaleはqvalueの最後の軸を除いた形状を持つ必要があり、qvalueはscaleと一緒にのみ意味があります。pytree として、コードがストリームを横断するのを妨げるものは何もありません。変換下では、JAX 自体は独立した葉しか認識しません。 - jaxprs での型。 pytree として、量子化配列はトレースされたコードでは 2 つの無関係な配列値として表示されます。1 つの型を持つ 1 つの値が表示されることを望みます。これにより、jaxprs は意味を伝えます。
- 接線。 量子化配列の値は離散グリッド上に存在するため、グリッドに沿って摂動することは意味がありません。しかし、pytree の接線型は、その葉の接線型の pytree に強制されます。そして、
qvalueのような整数配列の接線型はfloat0配列であり、取るに足らないペイロードしか運べません。したがって、pytree として、量子化配列はまったく有用な摂動を許容しません。私たちが望むのは、量子化配列全体に対して、量子化された値が近似する連続f32配列のような接線型を選択することです。
したがって、代わりに QArray を hijax 型にします。
型
hijax 型は HiType のサブクラスです。必須のコアは小さいです。
lo_tyは、その型を構成する lojax(配列)型が何であるかを示します。lower_valとraise_valは、値を配列のリストとの間で変換します。- 型はハッシュ可能で等価比較可能である必要があります(frozen dataclass は両方を提供します)。
これは pytree の flatten/unflatten インターフェースに似ていますが、型のレベルにあります。型のみを与えれば、値なしで JAX は低レベル化された型を計算できます。
また、型に sharding フィールドを追加し、値がデバイス間でどのようにパーティション化されるかを記録します。このドキュメントの最後のシャーディングセクションまで無視できます。qvalue コンポーネントのパーティショニングを記述するために JAX の NamedSharding を再利用し、最後の軸をドロップすることで scale のパーティショニングを導出します。フィールドの特別な点はありません。JAX はそれを解釈しません。私たちのメソッドのみがそれを消費します。主に lo_ty であり、コンポーネント型にシャーディングをスタンプします。代わりに独自の設計のオブジェクトでシャーディング情報を追跡することは自由です。ただし、同じ方法で消費する限りです。
from jax.experimental.hijax import HiType, ShapedArray, register_hitype
from jax.sharding import NamedSharding
@dataclass(frozen=True)
class QArrayTy(HiType):
shape: tuple[int, ...]
sharding: NamedSharding # qvalue のシャーディング。scale のシャーディングはそこから導出される
# 低レベル化:どの配列型がこの型を構成し、値がどのように変換されるか
def lo_ty(self):
scale_sharding = self.sharding.update(spec=jax.P(*self.sharding.spec[:-1]))
return [ShapedArray(self.shape, jnp.dtype('int8'),
sharding=self.sharding),
ShapedArray(self.shape[:-1], jnp.dtype('float32'),
sharding=scale_sharding)]
def lower_val(self, q):
return [q.qvalue, q.scale]
def raise_val(self, qvalue, scale):
return QArray(qvalue, scale)
# 自動微分:量子化配列の接線は通常の float 配列です(下記参照)
def to_tangent_aval(self):
return ShapedArray(self.shape, jnp.dtype('float32'),
sharding=self.sharding)
# 印刷、例:jaxprs で
def str_short(self, short_dtypes=False, mesh_axis_types=False):
dims = [str(d) if p is None else f'{d}@{p}'
for d, p in zip(self.shape, self.sharding.spec)]
return f'q8[{','.join(dims)}]'
__repr__ = str_short
register_hitype(QArray, lambda q: QArrayTy(q.qvalue.shape,
jax.typeof(q.qvalue).sharding))
register_hitype の呼び出しは、値クラスを型に関連付けます。その 2 番目の引数は、任意の与えられた値の型を計算します。これは、jax.typeof が配列をその ShapedArray 型にマッピングする方法に似ています。(私たちのものは、qvalue コンポーネントから形状とシャーディングの両方を読み取ります。すべての配列はシャーディングを運びます。メッシュが存在しない場合は自明です。)登録後、jax.typeof は QArray でも機能し、JAX の変換は値が期待される場所ならどこでもそれらを受け入れます。
プリミティブ
pytree を使用すると、ユーザーは値を自由に構築および分解できます。hijax 型を使用すると、値は、新しい型を宣言する hijax プリミティブによってのみ生成および消費されます。そこで不変条件が強制されます。すべてのプリミティブがそれを維持すれば、常に有効になります。
私たちの 2 つのプリミティブは quantize と dequantize で、HiPrim API を使用して記述されます。カスタム微分ルールと hijax プリミティブ を参照してください。それぞれが入力と出力の型を宣言し、expand での実装を提供し、(自動微分を見越して)ストレートスルー推定器 VJP ルールを持ちます。
from jax.experimental.hijax import HiPrim
class Quantize(HiPrim):
def __init__(self, x_aval):
if x_aval.dtype != jnp.dtype('float32'): raise TypeError(x_aval.dtype)
self.in_avals = (x_aval,)
self.out_aval = QArrayTy(x_aval.shape, x_aval.sharding)
self.params = {}
super().__init__()
def expand(self, x):
scale = jnp.max(jnp.abs(x), axis=-1) / 127.
qvalue = jnp.round(x / scale[..., None]).astype(jnp.int8)
return QArray(qvalue, scale)
# ストレートスルー推定器:恒等関数のように微分する
def vjp_fwd(self, nzs_in, x):
return self(x), None
def vjp_bwd_retval(self, _res, g):
return (g,)
class Dequantize(HiPrim):
def __init__(self, q_aval):
self.in_avals = (q_aval,)
self.out_aval = ShapedArray(q_aval.shape, jnp.dtype('float32'),
sharding=q_aval.sharding)
self.params = {}
super().__init__()
def expand(self, qx):
return qx.qvalue.astype('float32') * qx.scale[..., None]
def vjp_fwd(self, nzs_in, qx):
return self(qx), None
def vjp_bwd_retval(self, _res, g):
return (g,)
def quantize(x):
return Quantize(jax.typeof(x))(x)
def dequantize(qx):
return Dequantize(jax.typeof(qx))(qx)
Quantize の out_aval と Dequantize の in_avals が QArrayTy であることに注意してください。新しい型は、配列型と同様にプリミティブの型シグネチャに表示されます。また、expand が QArray 値クラスを自由に構築および検査することも注目してください。プリミティブの実装は抽象化境界の内側にあります。
すべて即時実行されます。
x = jnp.array([[1., 2., 3.],
[4., -5., 6.]])
qx = quantize(x)
print(qx)
print(jax.typeof(qx))
print(dequantize(qx))
QArray(qvalue=Array([[ 42, 85, 127],
[ 85, -106, 127]], dtype=int8), scale=Array([0.02362205, 0.04724409], dtype=float32))
q8[2,3]
[[ 0.992126 2.007874 3. ]
[ 4.015748 -5.007874 6. ]]
プリミティブの外側、コンテナの内側
上記の expand メソッドは QArray 値を構築し、その属性を直接読み取ります。この種の直接的なコンテナ操作は、expand(および型の独自のメソッド、lower_val や raise_val など)でのみ発生することが重要です。それ以外のすべての場所、特に jit、微分、または vmap する可能性のある関数では、hi 値はプリミティブを適用することによってのみ生成および消費されるべきです。
理由は、トレースされたコードが実際に何を見るかです。トレースの下では、量子化配列は QArray インスタンスではなく、q8[...] 型の Tracer です。したがって、トレースされたコードで属性を読み取ると失敗します。
try:
jax.jit(lambda qx: qx.qvalue)(qx)
except AttributeError as e:
print('AttributeError:', e)
AttributeError: DynamicJaxprTracer has no attribute qvalue
そして、さらに悪いことに、トレースされた配列にコンストラクタを呼び出してもすぐには失敗しません。JAX が 1 つの不透明な具体的な値として扱うコンテナ内に Tracer を密かに smuggles し、間違いは後で、その原因から離れた混乱を招くエラーとして現れます(ここでは定数ハンドラの欠落。grad の下ではリークしたトレーサーのエラーです)。
def bad_quantize(x):
scale = jnp.max(jnp.abs(x), axis=-1) / 127.
return QArray(jnp.round(x / scale[..., None]).astype('int8'), scale)
try:
jax.jit(bad_quantize)(x)
except TypeError as e:
print('TypeError:', e)
TypeError: Encountered an unexpected tracer. A function transformed by JAX had a side effect, allowing for a reference to an intermediate value with type int8[2,3] wrapped in a DynamicJaxprTracer to escape the scope of the transformation.
JAX transformations require that functions explicitly return their outputs, and disallow saving intermediate values to global state.
The function being traced when the value leaked was bad_quantize at /tmp/ipykernel_4310/1335604924.py:1 traced for jit.
------------------------------
The leaked intermediate value was created on line /tmp/ipykernel_4310/1335604924.py:3:16 (bad_quantize).
------------------------------
When the value was created, the final 5 stack frames (most recent last) excluding JAX-internal frames were:
------------------------------
/tmp/ipykernel_4310/1335604924.py:3:16 (bad_quantize)
------------------------------
To catch the leak earlier, try setting the environment variable JAX_CHECK_TRACER_LEAKS or using the `jax.checking_leaks` context manager.
Detail: The tracer reached lowering as a constant. One way that happens is a custom_vjp fwd rule or custom_gradient function that closes over a value traced by an enclosing jax.jit, when the jitted function is differentiated (as in grad(jit(f))). Pass such values as arguments instead.
See https://docs.jax.dev/en/latest/101/errors.html#jax.errors.UnexpectedTracerError
expand では話が異なります。expand が実行されるまでに、JAX はプリミティブをその lojax コンポーネントに基づいて実装することをコミットしており、その QArray 引数は実際の QArray インスタンス(lojax 値を含む。おそらくトレースされたもの)です。そこで、値を通常のコンテナとして操作することはまさに正しいことです。
(このドキュメントの他の場所にある属性へのトップレベルのピーク、qx.qvalue などは、同様の理由で問題ありません。即時実行 expand は即時実行と同じ理由で問題ありません。それらは具体的な値で即時実行されます。しかし、トレースされる可能性のある任意の関数内では、プリミティブに固執してください。)
より現実的なオペレーション:密行列 × 量子化行列乗算
変換オペレーションだけでは薄い API になります。実際には、量子化配列型は、型を直接消費するオペレーションでその価値を発揮します。古典的な例は、推論スタイルの行列乗算で、アクティベーション x は通常の密な f32 配列であり、重みは量子化されています。
class MatmulQ(HiPrim):
def __init__(self, x_aval, q_aval):
if not (isinstance(q_aval, QArrayTy) and len(x_aval.shape) == 2 and
len(q_aval.shape) == 2 and x_aval.shape[1] == q_aval.shape[0]):
raise TypeError(f'bad matmul_q operand types: {x_aval} @ {q_aval}')
self.in_avals = (x_aval, q_aval)
x_spec, q_spec = x_aval.sharding.spec, q_aval.sharding.spec
if x_spec[1] is not None or q_spec[0] is not None:
raise TypeError('matmul_q requires unsharded contraction axes, got '
f'{x_aval} @ {q_aval}')
out_sharding = x_aval.sharding.update(spec=jax.P(x_spec[0], q_spec[1]))
self.out_aval = ShapedArray((x_aval.shape[0], q_aval.shape[1]),
jnp.dtype('float32'), sharding=out_sharding)
self.params = {}
super().__init__()
def expand(self, x, qw):
# 各行のスケールを密なオペランドに折りたたみ、次に int8 ペイロードに対して直接 1 回の行列乗算を適用します
return (x * qw.scale) @ qw.qvalue.astype(jnp.float32)
def vjp_fwd(self, nzs_in, x, qw):
return self(x, qw), (x, qw)
def vjp_bwd_retval(self, res, g):
x, qw = res
w = dequantize(qw) # ルールはトレースされたコードです。ここでプリミティブを使用します
# 共接線は原始値と同じ場所に存在するため、原始オペランドのシャーディングを使用して(おそらくシャーディングされた)縮約を曖昧にします
return (jnp.matmul(g, w.T, out_sharding=jax.typeof(x).sharding),
jnp.matmul(x.T, g, out_sharding=jax.typeof(w).sharding))
def matmul_q(x, qw):
return MatmulQ(jax.typeof(x), jax.typeof(qw))(x, qw)
いくつか注目すべき点があります。型シグネチャは配列型と hi 型を自由に混在させます。in_avals は (ShapedArray, QArrayTy) のペアであり、構築時にチェックされるため、形状の不一致はすぐに失敗し、両方のオペランド型が pretty-printed されます。また、expand は表現を利用します。スケールは縮約軸に沿って行ごとに適用されるため、それらを密なオペランドに折りたたむことができます。したがって、重い行列乗算は、デ量子化されたコピーではなく、int8 ペイロードに対して直接実行されます。オペレーションを単一のプリミティブとして所有することで、それを一度、一箇所で記述できることを示します。
また、前のセクションの規律が機能していることに注意してください。expand はコンテナ属性として qw.scale と qw.qvalue を読み取りますが、VJP ルール(通常のトレースされたコード)は代わりに dequantize プリミティブを通過します。
(型付けルールは出力シャーディングも計算します。出力行は x の行のようにパーティション化され、出力列は qw の列のようにパーティション化されます。縮約軸は非シャーディングである必要があります。これは、明示的なシャーディングセクションで説明されています。明示モードの外では、これらのシャーディングはすべて自明であり、追加のコードは不活性です。)
w = jnp.arange(12., dtype='float32').reshape(3, 4) / 12.
qw = quantize(w)
print(matmul_q(x, qw))
print(x @ dequantize(qw)) # 参照
[[2.6627297 3.1706038 3.6587927 4.166667 ]
[2.3077428 2.7447505 3.1463253 3.5833333]]
[[2.6627297 3.1706038 3.6587927 4.166667 ]
[2.3077426 2.7447505 3.1463253 3.5833333]]
jaxprs での hi 型
トレースすると、量子化配列は単一の q8[2,3] 型の値として表示され、1 つの式によって生成され、別の式によって消費されます。
jax.jit(lambda x: dequantize(quantize(x))).trace(x).jaxpr
{ lambda ; a:f32[2,3]. let
b:q8[2,3] = Quantize a
c:f32[2,3] = Dequantize b
in (c,) }
同じ計算が、それらがペアになっているという兆候なしに、4 つの配列型の中間値として表示される pytree アプローチと比較してください。hi 型は低レベル化時にのみ消滅します。そのとき expand がトレースされ、各 q8[...] 型の値は lo_ty で与えられた配列コンポーネントに展開されます。
混合オペランド種を持つオペレーションも同様に直接読み取られます。f32[2,3] @ q8[3,4] -> f32[2,4] シグネチャを持つ 1 つの式です。
jax.jit(matmul_q).trace(x, qw).jaxpr
#
# `jit` は、量子化配列を引数、結果、および中間値として機能します。
{ lambda ; a:f32[2,3] b:q8[3,4]. let c:f32[2,4] = MatmulQ a b in (c,) }
print(jax.jit(lambda x: dequantize(quantize(x)))(x)) # QArray 内部
qx2 = jax.jit(quantize)(x) # QArray 結果
print(jax.typeof(qx2))
print(jax.jit(dequantize)(qx2)) # QArray 引数
[[ 0.992126 2.007874 3. ]
[ 4.015748 -5.007874 6. ]]
q8[2,3]
[[ 0.992126 2.007874 3. ]
[ 4.015748 -5.007874 6. ]]
自動微分と接線型
ここで hi 型がその価値を発揮します。型で、私たちは実装しました。
def to_tangent_aval(self):
return ShapedArray(self.shape, jnp.dtype('float32'))
これは次のように述べています。量子化配列の接線型は、通常の f32 配列です。pytree はこれを表現できません。pytree の接線型は常にその葉の接線型の pytree であり、qvalue の int8 葉の場合、それは自明な float0 接線型を意味します。
プリミティブ上のストレートスルー VJP ルールと組み合わせると、量子化を通過する勾配は、それが恒等関数であるかのように流れます。
def f(x):
return jnp.sum(dequantize(quantize(x)))
print(jax.grad(f)(x))
[[1. 1. 1.]
[1. 1. 1.]]
量子化配列入力に対する微分は、接線型が指示するように、通常の浮動小数点配列を生成します。
def g(qx):
return jnp.sum(dequantize(qx) ** 2)
print(jax.grad(g)(qx))
print(jax.typeof(jax.grad(g)(qx)))
[[ 1.984252 4.015748 6. ]
[ 8.031496 -10.015748 12. ]]
float32[2,3]
量子化行列乗算のような混合オペランド種を持つオペレーションも同様です。損失を両方のオペランドに対して微分すると、密なアクティベーションに対する f32 勾配と、量子化された重みに対する f32 勾配が得られます。
def loss(x, qw):
return jnp.sum(matmul_q(x, qw) ** 2)
grad_x, grad_qw = jax.grad(loss, argnums=(0, 1))(x, qw)
print(jax.typeof(grad_x), jax.typeof(grad_qw))
float32[2,3] float32[3,4]
接線型を f32 配列にすることは選択であり、実際の設計空間があることに注意してください。代わりに、QArrayTy の接線型を QArrayTy 自体にすることもできます。これにより、接線と共接線も量子化されます。これは異なるトレードオフであり、異なるアプリケーションに適しています。(その選択の場合、接線型は hi 型になるため、vspace_zero と vspace_add もそれに実装して、自動微分が共接線をインスタンス化および累積できるようにします。)この柔軟性により、hi 型はユーザー拡張ポイントとなります。JAX の各部分(トレーシング、低レベル化、自動微分、バッチ処理)について、状況に応じて型の参加方法を設定します。
vmap とマッピング仕様
量子化配列をマップするとはどういうことでしょうか?配列の場合、vmap の in_axes と out_axes は軸インデックスであり、JAX は引数の形状からマップされた軸サイズを推測できます。一般的な hi 型の場合、JAX は推測しません。あなたが値がどのようにマップされるかを示す「マッピング仕様」型を定義し、ユーザーはそれのインスタンスを in_axes/out_axes エントリとして渡し、推測できない場合は axis_size を明示的に渡します。
私たちの量子化配列の場合、行ごとのスケールのおかげで、QArray のバッチは単に大きな QArray です。q8[2,3] 型の n 個の量子化配列を新しい先頭軸にスタックすると、qvalue が形状 (n, 2, 3)、scale が形状 (n, 2) の q8[n,2,3] になります。したがって、必要なマッピングの概念は「先頭軸」だけであり、仕様型はデータを運ぶ必要はありません。
from jax.experimental.hijax import MappingSpec
@dataclass(frozen=True)
class QArraySpec(MappingSpec):
pass # QArray は先頭軸に沿ってのみマップされます
(仕様は、型が要求するほど豊かにすることができます。タプルライクな hi 型は、各コンポーネントに 1 つの軸を持つ仕様を使用する場合があります。このドキュメントの最後にあるタプル例を参照してください。)
型で、dec_rank と inc_rank を実装します。これらは、hi 型の「マップされた軸を削除」および「マップされた軸を追加」のアナログです。それらは軸サイズと仕様を受け取り、要素型とバッチ型を返します。
def qarray_dec_rank(self, size, spec):
assert isinstance(spec, QArraySpec) and self.shape[0] == size
return QArrayTy(self.shape[1:],
self.sharding.update(spec=jax.P(*self.sharding.spec[1:])))
def qarray_inc_rank(self, size, spec):
assert isinstance(spec, QArraySpec)
return QArrayTy((size, *self.shape),
self.sharding.update(spec=jax.P(None, *self.sharding.spec)))
QArrayTy.dec_rank = qarray_dec_rank
QArrayTy.inc_rank = qarray_inc_rank
(ノートブック形式でクラスにメソッドをアタッチしています。実際のコードでは、これらは class QArrayTy 定義内のさらに多くのメソッドになります。)
型で、batch ルールを実装します。batch ルールは、マッピング仕様を持つバッチ引数を受け取り(バッチされていない引数の場合は None、バッチされた配列引数の場合は整数軸、バッチされた hi 型引数の場合は仕様インスタンス)、バッチされた結果とそのマッピング仕様を返します。ルールは、バッチされた引数とバッチされていない引数の任意の組み合わせに対応できるように準備されている必要があります。
def quantize_batch(self, axis_data, args, in_dims):
x, = args
d, = in_dims
if d is None:
return quantize(x), None
x = jnp.moveaxis(x, d, 0)
return quantize(x), QArraySpec()
Quantize.batch = quantize_batch
def dequantize_batch(self, axis_data, args, in_dims):
qx, = args
d, = in_dims
if d is None:
return dequantize(qx), None
assert isinstance(d, QArraySpec)
return dequantize(qx), 0
Dequantize.batch = dequantize_batch
行ごとの量子化は任意のランクで適用されるため、両方のルールはスタックされた値に非バッチ操作を適用するだけで済みます。これは、その型のバッチが同じ型のファミリーの値であるという型の特徴です。
これで vmap が可能になります。量子化配列出力へのマッピングの場合、軸サイズは通常の配列引数から推測され、out_axes の仕様を渡します。
xs = jnp.arange(24., dtype='float32').reshape(4, 2, 3)
qxs = jax.vmap(quantize, out_axes=QArraySpec())(xs)
print(jax.typeof(qxs))
print(qxs.qvalue.shape, qxs.scale.shape)
q8[4,2,3]
(4, 2, 3) (4, 2)
量子化配列入力に対するマッピングの場合、in_axes の仕様を渡します。配列引数から軸サイズを推測できないため、axis_size を明示的に渡す必要があります。
xs_roundtrip = jax.vmap(dequantize, in_axes=QArraySpec(), axis_size=4)(qxs)
print(jax.typeof(xs_roundtrip))
float32[4,2,3]
通常のすべての合成が機能します。jit の vmap。
print(jax.typeof(jax.vmap(jax.jit(dequantize), in_axes=QArraySpec(),
axis_size=4)(qxs)))
float32[4,2,3]
grad の vmap など。
def norm_quantized(x):
return jnp.sum(dequantize(quantize(x)) ** 2)
print(jax.vmap(jax.grad(norm_quantized))(xs).shape)
(4, 2, 3)
scan と先頭軸
jax.lax.scan は、スタックされた hi 値をループ処理し、ステップごとに 1 つのスライスを消費できます。また、hi 値を運んだり生成したりすることもできます。vmap がユーザーにマッピング仕様を要求するのに対し、scan は常に先頭軸を歩くため、代わりに型に要求します。実装する必要がある追加のメソッドは leading_axis_spec であり、型の先頭軸を記述するマッピング仕様を返します。vmap セクションの dec_rank および inc_rank メソッドが残りの作業を行います。
def qarray_leading_axis_spec(self):
return QArraySpec()
QArrayTy.leading_axis_spec = qarray_leading_axis_spec
前のセクションの量子化配列のスタックをスキャンすると、ボディはステップごとに 1 つの q8[2,3] を表示します。vmap の axis_size と同様に、スキャンされたすべての値が hi 型の場合、推測する先頭軸サイズがないため、length を明示的に渡します(スキャンされた値のいずれかが配列の場合、scan はそれから長さを推測し、length は省略できます)。
def sum_dequantized(total, qx):
return total + jnp.sum(dequantize(qx)), ()
total, () = jax.lax.scan(sum_dequantized, 0., qxs, length=4)
print(total)
275.9685
hi 値は、スタックされた出力およびループキャリーとしても機能します。ここではキャリーは量子化配列で、各累積ステップ後に再量子化され、2 番目の出力は各ステップで 1 つの新しい QArray を q8[4,2,3] にスタックします。
def accum_quantized(qtotal, x):
return quantize(dequantize(qtotal) + x), quantize(2 * x)
qzero = quantize(jnp.zeros((2, 3), 'float32'))
qtotal, qys = jax.lax.scan(accum_quantized, qzero, xs)
print(jax.typeof(qtotal))
print(jax.typeof(qys))
q8[2,3]
q8[4,2,3]
型でのシャーディング:明示モード
最後に、シャーディング。JAX の明示シャーディングモードでは(並列処理ガイド を参照)、シャーディングは配列型の一部です。jax.typeof は値がメッシュ全体でどのようにパーティション化されているかを報告し、トレーシング中にシャーディング伝播が発生し、不一致は型エラーとして表面化します。QArrayTy の sharding フィールドと、それを伝播するプリミティブの型付けルールは、hi 型が参加できるようにするまさにそれです。量子化配列をデバイス全体にパーティション化するとはどういうことでしょうか?コンポーネントは一緒に移動します。行をシャーディングする場合、各デバイスは行の量子化値とそのスケールを保持します。いつものように、選択肢があり、lo_ty でそれを行いました。qvalue は型のシャーディングを運び、scale は最後の軸をドロップしてそれのようにシャーディングします。これにより、すべての行がスケールと一緒に移動します。
それが機能するのを見てみましょう。メッシュを作成し(ここでドキュメントの最初のセルで要求された 8 つの CPU デバイスを使用します)、いくつかの行をそれにシャーディングし、量子化します。シャーディングは型付けルールを通じて結果の型に伝播し、jax.typeof は @ マーカーで表示します。
mesh = jax.make_mesh((4,), ('i',))
jax.set_mesh(mesh)
rows = jax.device_put(jnp.arange(24., dtype='float32').reshape(8, 3),
jax.P('i'))
qrows = quantize(rows)
print(jax.typeof(qrows))
print(qrows.qvalue.sharding.spec, qrows.scale.sharding.spec)
print(jax.typeof(dequantize(qrows)))
q8[8@i,3]
P('i', None) P('i',)
float32[8@i,3]
トレース中も同様です。jaxprs の hi 型は、out_aval ルールによって計算されたシャーディングを表示するようになりました。
jax.jit(lambda x: dequantize(quantize(x))).trace(rows).jaxpr
{ lambda ; a:f32[8@i,3]. let
b:q8[8@i,3] = Quantize a
c:f32[8@i,3] = Dequantize b
in (c,) }
量子化行列乗算もシャーディングを伝播します。その型付けルールは、出力行を x の行のように、出力列を qw の列のようにパーティション化します(縮約軸は非シャーディングである必要があると要求します。どちらのオペランドも、シャーディングされた縮約がどのように着地するかを言うことができないためです)。
w2 = jnp.arange(12., dtype='float32').reshape(3, 4) / 12.
print(jax.typeof(matmul_q(rows, quantize(w2)))) # 行はシャーディングされている
qw2 = quantize(jax.device_put(w2, jax.P(None, 'i')))
print(jax.typeof(qw2)) # 列はシャーディングされている
print(jax.typeof(matmul_q(jnp.ones((2, 3), 'float32'), qw2)))
float32[8@i,4]
q8[3,4@i]
float32[2,4@i]
そして、縮約チェックは型エラーとしてトレース時に発生します。
xk = jax.device_put(jnp.ones((2, 8), 'float32'), jax.P(None, 'i'))
qk = quantize(jax.device_put(jnp.ones((8, 3), 'float32'), jax.P('i')))
try:
matmul_q(xk, qk)
except TypeError as e:
print('TypeError:', e)
TypeError: matmul_q requires unsharded contraction axes, got float32[2,8@i] @ q8[8@i,3]
自動微分はこれらすべてと合成されます。MatmulQ の後退ルールが out_sharding ヒントをその行列乗算に渡したことを思い出してください。それは、qw の共接線が行軸を縮約するためです。これはシャーディングされている場合があります(ここではそうであるように)、明示モードはすべてのシャーディングされた縮約がどのように着地するかを推測することを拒否します。正しい答えは原始オペランドのシャーディングです。共接線は、それらの原始値と同じ場所に存在します。
def qloss(x, qw):
return jnp.sum(matmul_q(x, qw) ** 2)
grad_rows, grad_qw2 = jax.grad(qloss, argnums=(0, 1))(rows, quantize(w2))
print(jax.typeof(grad_rows), jax.typeof(grad_qw2))
float32[8@i,3] float32[3,4]
1 つの注意点:JAX は、hi プリミティブの宣言された出力シャーディングと、その expand が実際に生成するものをクロスチェックしません。宣言された out_aval は、トレース中の下流コードが見るものであり、expand は実行時に何が起こるかを決定します。それらを一致させることは、型付けルールのジョブの一部です。
shard_map とパーティション仕様
明示モードは、プログラムのグローバルビューを維持しながら値をパーティション化します。その補完は shard_map であり、デバイスごとのビューを提供します。その境界を越えるには、量子化配列にはもう 1 つの要素が必要です。独自のパーティション仕様型で、shard_map の in_specs/out_specs がそれにどのように適用されるかを示します。ここでは、上記と同じ設計を維持します。量子化配列は先頭軸に沿ってのみシャーディングされます。
shard_map の場合、これを HiPspec サブクラスで表現します。これは、上記の MappingSpec のパーティション仕様アナログです。ユーザーはそれのインスタンスを in_specs/out_specs エントリとして渡し、その to_lo メソッドは、それが各低レベル化されたコンポーネント(lo_ty 順)に 1 つの jax.P パーティション仕様にどのように変換されるかを示します。
from jax.experimental.hijax import HiPspec
@dataclass(frozen=True)
class QArrayP(HiPspec):
spec: jax.P # 先頭軸のパーティショニング。最後の軸はそのままです。
def to_lo(self):
return (self.spec, self.spec) # qvalue と scale は一緒にシャーディングされます
(scale は qvalue より軸が 1 つ少ないため、両方のコンポーネントに同じパーティション仕様を渡すと、先頭軸が一緒にシャーディングされ、qvalue の末尾軸は変更されないことを正確に示します。)
型で、shard と unshard は、グローバル型からデバイスごとの型を計算し、コンポーネント型に委譲します。
def qarray_shard(self, mesh, manual_axes, check_vma, spec):
qvalue_ty, _ = self.lo_ty()
qspec, _ = spec.to_lo()
shard_ty = qvalue_ty.shard(mesh, manual_axes, check_vma, qspec)
return QArrayTy(shard_ty.shape, shard_ty.sharding)
def qarray_unshard(self, mesh, check_vma, spec):
qvalue_ty, _ = self.lo_ty()
qspec, _ = spec.to_lo()
full_ty = qvalue_ty.unshard(mesh, check_vma, qspec)
return QArrayTy(full_ty.shape, full_ty.sharding)
QArrayTy.shard = qarray_shard
QArrayTy.unshard = qarray_unshard
これで、量子化配列は shard_map 境界を双方向に越えることができ、前のセクションのメッシュと rows を使用して続行します。シャーディングされた量子化配列を生成します。
@jax.jit
@jax.shard_map(in_specs=jax.P('i'), out_specs=QArrayP(jax.P('i')))
def quantize_shards(x):
assert jax.typeof(x).shape == (2, 3) # 各デバイスは 2 行を表示します
return quantize(x)
qrows = quantize_shards(rows)
print(jax.typeof(qrows))
print(qrows.qvalue.sharding.spec, qrows.scale.sharding.spec)
q8[8@i,3]
P('i', None) P('i',)
そして、各デバイスが独自の行のパーティションごとの QArray を表示する 1 つを消費します。
@jax.jit
@jax.shard_map(in_specs=QArrayP(jax.P('i')), out_specs=jax.P('i'))
def dequantize_shards(qx):
assert jax.typeof(qx).shape == (2, 3) # デバイスごとの QArray シャード
return dequantize(qx)
print(jnp.max(jnp.abs(dequantize_shards(qrows) - rows)))
0.08661461
行ごとのスケールがあるため、シャードごとに量子化することは、グローバルに量子化することと正確に一致します。これは、バッチ処理を快適にしたのと同じプロパティです。
qrows_global = quantize(rows)
assert (qrows.qvalue == qrows_global.qvalue).all()
assert (qrows.scale == qrows_global.scale).all()
(shard_map を通過する自動微分の場合、さらに実装する必要があります。仕様型での to_tangent_spec と to_ct_spec、および hi 型での nospec。これは自動微分残差をシャーディングするために使用されます。)
追加例
レシピは常に同じです。値クラス、lo_ty/lower_val/raise_val 低レベル化トリプルを持つ HiType、および新しい型を言及する型シグネチャを持つプリミティブです。したがって、さらなる例は迅速に読むことができます。
ランク 1 配列
ランク 1 配列は、m × n 行列を 2 つのベクトルの外積として表現します。col : f32[m] と row : f32[n] です。表現のポイントは、m × n 積を具体化しないことです。オペレーションは直接因数を消費します。(因数 f32[m, r] と f32[r, n] を持つ一般的な低ランク型は、さらに同じです。)
@dataclass(frozen=True)
class Rank1:
col: jax.Array # f32[m]
row: jax.Array # f32[n]
@dataclass(frozen=True)
class Rank1Ty(HiType):
shape: tuple[int, int] # (m, n)、表現される密な形状
sharding: NamedSharding # 密な形状のシャーディング。因数の導出。
def lo_ty(self):
(m, n), spec = self.shape, self.sharding.spec
return [ShapedArray((m,), jnp.dtype('float32'),
sharding=self.sharding.update(spec=jax.P(spec[0]))),
ShapedArray((n,), jnp.dtype('float32'),
sharding=self.sharding.update(spec=jax.P(spec[1])))]
def lower_val(self, r1):
return [r1.col, r1.row]
def raise_val(self, col, row):
return Rank1(col, row)
# ランク 1 行列は加算で閉じないため、接線は密です
def to_tangent_aval(self):
return ShapedArray(self.shape, jnp.dtype('float32'),
sharding=self.sharding)
def str_short(self, short_dtypes=False, mesh_axis_types=False):
dims = [str(d) if p is None else f'{d}@{p}'
for d, p in zip(self.shape, self.sharding.spec)]
return f'r1[{','.join(dims)}]'
__repr__ = str_short
def typeof_rank1(r1):
col_s, row_s = jax.typeof(r1.col).sharding, jax.typeof(r1.row).sharding
sharding = col_s.update(spec=jax.P(col_s.spec[0], row_s.spec[0]))
return Rank1Ty((r1.col.shape[0], r1.row.shape[0]), sharding)
register_hitype(Rank1, typeof_rank1)
型は表現する密な形状を記録し、例えば r1[6,5] のように表示されます。接線型の選択に注意してください。これは QArrayTy とは異なる理由で異なります。2 つのランク 1 行列の合計は一般にランク 2 であるため、ランク 1 行列は加算で閉じず、それ自体の接線空間として機能できません。摂動は多様体を離れ、接線と共接線は密です。シャーディングの話は以前と同じで、フィールドは lo_ty で消費されます。密な行軸は col によって運ばれ、密な列軸は row によって運ばれます。
QArray とは異なり、その値は quantize の内部でしか作成されませんでしたが、ここでは因数からの構築自体がプリミティブです。また、アクセサプリミティブもあり、ルール(通常のトレースされたコード)は属性に触れることなく因数にアクセスできます。
class Outer(HiPrim):
def __init__(self, col_aval, row_aval):
if not (len(col_aval.shape) == 1 and len(row_aval.shape) == 1):
raise TypeError(f'bad outer factor types: {col_aval}, {row_aval}')
sharding = col_aval.sharding.update(
spec=jax.P(col_aval.sharding.spec[0], row_aval.sharding.spec[0]))
self.in_avals = (col_aval, row_aval)
self.out_aval = Rank1Ty((col_aval.shape[0], row_aval.shape[0]), sharding)
self.params = {}
super().__init__()
def expand(self, col, row):
return Rank1(col, row)
def vjp_fwd(self, nzs_in, col, row):
return self(col, row), (col, row)
def vjp_bwd_retval(self, res, g): # g は密な f32[m, n] です
col, row = res
return g @ row, col @ g
class Factors(HiPrim):
def __init__(self, r1_aval):
self.in_avals = (r1_aval,)
self.out_aval = tuple(r1_aval.lo_ty()) # 因数型は低レベル型です
self.params = {}
super().__init__()
def expand(self, r1):
return (r1.col, r1.row)
class MatmulR1(HiPrim):
def __init__(self, x_aval, r1_aval):
if not (isinstance(r1_aval, Rank1Ty) and len(x_aval.shape) == 2 and
x_aval.shape[1] == r1_aval.shape[0]):
raise TypeError(f'bad matmul_r1 operand types: {x_aval} @ {r1_aval}')
self.in_avals = (x_aval, r1_aval)
out_sharding = x_aval.sharding.update(
spec=jax.P(x_aval.sharding.spec[0], r1_aval.sharding.spec[1]))
self.out_aval = ShapedArray((x_aval.shape[0], r1_aval.shape[1]),
jnp.dtype('float32'), sharding=out_sharding)
self.params = {}
super().__init__()
def expand(self, x, r1):
return jnp.outer(x @ r1.col, r1.row) # col ⊗ row を具体化しない
def vjp_fwd(self, nzs_in, x, r1):
col, row = factors(r1) # ルールはトレースされたコードです。属性ではなくプリミティブを使用します
return self(x, r1), (x, col, row)
def vjp_bwd_retval(self, res, g):
x, col, row = res
return jnp.outer(g @ row, col), x.T @ g
def outer(col, row):
return Outer(jax.typeof(col), jax.typeof(row))(col, row)
def factors(r1):
return Factors(jax.typeof(r1))(r1)
def matmul_r1(x, r1):
return MatmulR1(jax.typeof(x), jax.typeof(r1))(x, r1)
(Factors は出力型をタプルの型として宣言します。in_avals エントリと out_aval は型の pytree にすることができます。また、実際に行う変換に必要なルールのみを必要とするため、自動微分ルールをまったく持ちません。また、MatmulR1 の後退ルールは、expand と同様に、表現を利用して密なオペランドの共接線を外積として計算します。)
col = jnp.arange(6., dtype='float32') / 6.
row = jnp.arange(5., dtype='float32') / 5.
r1 = outer(col, row)
print(jax.typeof(r1))
acts = jnp.ones((3, 6), 'float32')
print(jnp.max(jnp.abs(matmul_r1(acts, r1) - acts @ jnp.outer(col, row))))
r1[6,5]
1.1920929e-07
jaxprs、jit、および自動微分はすべて以前と同様に機能します。ランク 1 オペランドに対する勾配は、接線型が指示するように密ですが、コンストラクタを通過する勾配は因数に戻ります。
jax.jit(matmul_r1).trace(acts, r1).jaxpr
{ lambda ; a:f32[3,6] b:r1[6,5]. let c:f32[3,5] = MatmulR1 a b in (c,) }
def r1_loss(x, r1):
return jnp.sum(matmul_r1(x, r1) ** 2)
print(jax.typeof(jax.grad(r1_loss, argnums=1)(acts, r1)))
def factor_loss(col, row):
return jnp.sum(matmul_r1(acts, outer(col, row)) ** 2)
g_col, g_row = jax.grad(factor_loss, argnums=(0, 1))(col, row)
print(jax.typeof(g_col), jax.typeof(g_row))
float32[6,5]
float32[6] float32[5]
また、型付けルールは QArrayTy のようにシャーディングを伝播します。
print(jax.typeof(outer(jax.device_put(jnp.zeros(8, 'float32'), jax.P('i')),
row)))
r1[8@i,5]
ここで停止しましたが、vmap、scan、shard_map のサポートは、前のセクションと同様のレシピに従います。マッピング仕様を持つ dec_rank/inc_rank、leading_axis_spec、およびパーティション仕様型を持つ HiPspec を持つ shard/unshard です。
タプル
最後の例はジェネリックコンテナです。要素は任意の JAX 値であるタプルです。QArrayTy と Rank1Ty が固定されたコンポーネント構造を持っていたのに対し、TupTy はコンポーネント型によってパラメータ化されます。そして、すべてのメソッドがそれらに委譲します。
import itertools
@dataclass(frozen=True)
class HiTup:
elts: tuple
@dataclass(frozen=True)
class TupTy(HiType):
tys: tuple # コンポーネント型:配列型、または他の hi 型
# 低レベル化はコンポーネント型に委譲します
def lo_ty(self):
return [lo for ty in self.tys for lo in ty.lo_ty()]
def lower_val(self, tup):
return [lo for ty, elt in zip(self.tys, tup.elts)
for lo in ty.lower_val(elt)]
def raise_val(self, *los):
los = iter(los)
return HiTup(tuple(ty.raise_val(*itertools.islice(los, len(ty.lo_ty())))
for ty in self.tys))
# 接線型も同様です
def to_tangent_aval(self):
return TupTy(tuple(ty.to_tangent_aval() for ty in self.tys))
def str_short(self, short_dtypes=False, mesh_axis_types=False):
return ('Tup{' +
','.join(t.str_short(short_dtypes, mesh_axis_types))
for t in self.tys) + '}')
__repr__ = str_short
register_hitype(HiTup, lambda t: TupTy(tuple(map(jax.typeof, t.elts))))
委譲から無料で得られる 2 つのこと。第一に、要素自体が hi 型になる可能性があります。タプルのタプル、または QArray を保持するタプル。これは、lo_ty などが再帰するためです。第二に、ここには sharding フィールドはありません。格納されているコンポーネント型は、独自のシャーディングを運びます。これは、QArrayTy の単一フィールドと Rank1Ty の密な形状仕様に続く、型内シャーディングの 3 番目の方法です。
コンストラクタとアクセサプリミティブは、ランク 1 例からおなじみです。1 つの新しい要素:要素インデックスは静的パラメータであり、params 経由で渡され、self.idx として利用可能です。各要素は独自の軸(またはまったく)でバッチ処理できるため、マッピング仕様はコンポーネントごとに 1 つのエントリを運びます。
@dataclass(frozen=True)
class TupSpec(MappingSpec):
val: tuple # 各コンポーネントの 1 つの軸エントリ
def tup_dec_rank(self, size, spec):
return TupTy(tuple(ty.dec_rank(size, s)
for ty, s in zip(self.tys, spec.val)))
def tup_inc_rank(self, size, spec):
return TupTy(tuple(ty.inc_rank(size, s)
for ty, s in zip(self.tys, spec.val)))
TupTy.dec_rank = tup_dec_rank
TupTy.inc_rank = tup_inc_rank
class MakeTup(HiPrim):
def __init__(self, elt_avals):
self.in_avals = tuple(elt_avals)
self.out_aval = TupTy(tuple(elt_avals))
self.params = {}
super().__init__()
def expand(self, *elts):
return HiTup(elts)
def batch(self, axis_data, args, in_dims):
return make_tup(*args), TupSpec(tuple(in_dims))
class GetTupElt(HiPrim):
def __init__(self, tup_aval, idx):
self.in_avals = (tup_aval,)
self.out_aval = tup_aval.tys[idx]
self.params = dict(idx=idx)
super().__init__()
def expand(self, tup):
return tup.elts[self.idx]
def batch(self, axis_data, args, in_dims):
tup, = args
spec, = in_dims
if spec is None:
return get_tuple_element(tup, self.idx), None
return get_tuple_element(tup, self.idx), spec.val[self.idx]
def make_tup(*elts):
return MakeTup(map(jax.typeof, elts))(*elts)
def get_tuple_element(tup, idx):
return GetTupElt(jax.typeof(tup), idx)(tup)
(GetTupElt のバッチルールは、バッチされていない入力を処理します。hi プリミティブのバッチルールは、引数がバッチされていない場合でも呼び出されるため、in_dims エントリは None になる可能性があります。)
タプルは機能し、ネストし、他の hi 型を保持します。
tup = make_tup(jnp.arange(3.), 5.)
print(jax.typeof(tup))
print(get_tuple_element(tup, 1))
nested = make_tup(make_tup(1., 2.), jnp.arange(2.))
print(jax.typeof(nested))
print(jax.jit(lambda t: get_tuple_element(get_tuple_element(t, 0), 1))(nested))
print(jax.typeof(make_tup(qx, 3.))) # 量子化配列要素
Tup{float32[3],float32[]}
5.0
Tup{Tup{float32[],float32[]},float32[2]}
2.0
Tup{q8[2,3],float32[]}
コンポーネントごとのマッピング仕様は vmap の下での成果です。各要素は独自の in_axes/out_axes エントリを取得し、型で表示されます。ここでは、最初の要素は入力時にマップされ、2 番目の要素のみが出力時にマップされます。
def swap(t):
a, b = get_tuple_element(t, 0), get_tuple_element(t, 1)
return make_tup(b, a)
out = jax.vmap(swap, in_axes=TupSpec((0, None)), out_axes=TupSpec((None, 0)),
axis_size=3)(tup)
print(jax.typeof(tup), '->', jax.typeof(out))
Tup{float32[3],float32[]} -> Tup{float32[],float32[3]}
コンポーネント型が独自のシャーディングを運ぶため、型内シャーディングはまったく追加のものを必要としません。
print(jax.typeof(make_tup(rows, jnp.float32(1.))))
Tup{float32[8@i,3],float32[]}
これらのプリミティブの自動微分ルール、および scan と shard_map のサポート(コンポーネントごとの HiPspec を介して)については、tests/hijax_test.py の TupTy 例を参照してください。
カバーされていないもの
プリミティブ側では、リマテリアライゼーションとデッドコード削除をカスタマイズするためのフックもあります。
いつものように hijax では、tests/hijax_test.py はうまく機能する例の良いソースであり、カスタム微分ルールと hijax プリミティブ はプリミティブ側の API を、JVP ルール、シンボリックゼロ、カスタム線形化を含む、より詳細にカバーしています。