checkify 变换

The checkify transformation#

摘要：Checkify 允许您向 JAX 代码添加 jit 可运行时错误检查（例如，越界索引）。将 checkify.checkify 变换与类似断言的 checkify.check 函数一起使用，向 JAX 代码添加运行时检查。

from jax.experimental import checkify
import jax
import jax.numpy as jnp

def f(x, i):
  checkify.check(i >= 0, "index needs to be non-negative, got {i}", i=i)
  y = x[i]
  z = jnp.sin(y)
  return z

jittable_f = checkify.checkify(f)

err, z = jax.jit(jittable_f)(jnp.ones((5,)), -2)
print(err.get())
# >> index needs to be non-negative, got -2! (check failed at <...>:6 (f))

您还可以使用 checkify 自动添加常见检查

errors = checkify.user_checks | checkify.index_checks | checkify.float_checks
checked_f = checkify.checkify(f, errors=errors)

err, z = checked_f(jnp.ones((5,)), 100)
err.throw()
# ValueError: out-of-bounds indexing at <..>:7 (f)

err, z = checked_f(jnp.ones((5,)), -1)
err.throw()
# ValueError: index needs to be non-negative! (check failed at <…>:6 (f))

err, z = checked_f(jnp.array([jnp.inf, 1]), 0)
err.throw()
# ValueError: nan generated by primitive sin at <...>:8 (f)

err, z = checked_f(jnp.array([5, 1]), 0)
err.throw()  # if no error occurred, throw does nothing!

将检查功能化#

类似断言的检查 API 本身不是纯函数：它可能会像断言一样，作为副作用引发 Python 异常。因此，它不能与 jit、pmap、pjit 或 scan 一起分阶段进行。

jax.jit(f)(jnp.ones((5,)), -1)  # checkify transformation not used
# ValueError: Cannot abstractly evaluate a checkify.check which was not functionalized.

但是 checkify 变换将这些效果功能化（或释放）。checkify 变换后的函数会返回一个错误值作为新的输出，并保持纯函数。这种功能化意味着 checkify 变换后的函数可以与分阶段/变换以我们喜欢的任何方式组合。

err, z = jax.pmap(checked_f)(jnp.ones((3, 5)), jnp.array([-1, 2, 100]))
err.throw()
"""
ValueError:
..  at mapped index 0: index needs to be non-negative! (check failed at :6 (f))
..  at mapped index 2: out-of-bounds indexing at <..>:7 (f)
"""

为什么 JAX 需要 checkify？#

在某些 JAX 变换下，您可以使用普通的 Python 断言来表达运行时错误检查，例如，当仅使用 jax.grad 和 jax.numpy 时。

def f(x):
  assert x > 0., "must be positive!"
  return jnp.log(x)

jax.grad(f)(0.)
# ValueError: "must be positive!"

但是普通的断言在 jit、pmap、pjit 或 scan 内部不起作用。在这些情况下，数值计算会被分阶段执行，而不是在 Python 执行期间急切地求值，因此数值不可用

jax.jit(f)(0.)
# ConcretizationTypeError: "Abstract tracer value encountered ..."

JAX 变换语义依赖于函数式纯度，特别是在组合多个变换时，那么如何在不破坏所有这些的情况下提供错误机制呢？除了需要一个新的 API 外，情况更加复杂：XLA HLO 不支持断言或抛出错误，因此即使我们有一个能够分阶段执行断言的 JAX API，我们如何将这些断言降低到 XLA 呢？

您可以想象手动将运行时检查添加到您的函数中，并输出代表错误的值

def f_checked(x):
  error = x <= 0.
  result = jnp.log(x)
  return error, result

err, y = jax.jit(f_checked)(0.)
if err:
  raise ValueError("must be positive!")
# ValueError: "must be positive!"

错误是函数计算的常规值，错误是在 f_checked 之外抛出的。 f_checked 是函数式纯净的，因此我们知道它已经可以与 jit、pmap、pjit、scan 和所有 JAX 的变换一起使用。唯一的问题是这种管道可能很麻烦！

checkify 为您完成了这种重写：包括将错误值通过函数传递，将检查重写为布尔运算，并将结果与跟踪的错误值合并，并将最终错误值作为输出返回给已检查的函数

def f(x):
  checkify.check(x > 0., "{} must be positive!", x)  # convenient but effectful API
  return jnp.log(x)

f_checked = checkify(f)

err, x = jax.jit(f_checked)(-1.)
err.throw()
# ValueError: -1. must be positive! (check failed at <...>:2 (f))

我们称之为功能化或消除调用检查引入的效果。（在上面的“手动”示例中，错误值只是一个布尔值。checkify 的错误值在概念上类似，但也跟踪错误消息并公开 throw 和 get 方法；请参阅 jax.experimental.checkify）。 checkify.check 还允许您通过将它们作为格式参数提供给错误消息，将运行时值添加到错误消息中。

您现在可以手动用运行时检查来修改您的代码，但 checkify 也可以自动添加针对常见错误的检查！考虑以下错误情况

jnp.arange(3)[5]                # out of bounds
jnp.sin(jnp.inf)                # NaN generated
jnp.ones((5,)) / jnp.arange(5)  # division by zero

默认情况下， checkify 仅消除 checkify.check，并且不会采取任何措施来捕获上述错误。但是，如果您要求它， checkify 也会自动用检查来修改您的代码。

def f(x, i):
  y = x[i]        # i could be out of bounds.
  z = jnp.sin(y)  # z could become NaN
  return z

errors = checkify.user_checks | checkify.index_checks | checkify.float_checks
checked_f = checkify.checkify(f, errors=errors)

err, z = checked_f(jnp.ones((5,)), 100)
err.throw()
# ValueError: out-of-bounds indexing at <..>:7 (f)

err, z = checked_f(jnp.array([jnp.inf, 1]), 0)
err.throw()
# ValueError: nan generated by primitive sin at <...>:8 (f)

用于选择要启用哪些自动检查的 API 基于集合。有关更多详细信息，请参阅 jax.experimental.checkify。

checkify 在 JAX 变换下。 #

如上面的示例所示，已检查的函数可以轻松地进行 jit 处理。以下是 checkify 与其他 JAX 变换的几个更多示例。请注意，已检查的函数是函数式纯净的，应该可以与所有 JAX 变换轻松组合！

jit #

您可以安全地将 jax.jit 添加到已检查的函数中，或者 checkify 一个已 jit 处理的函数，两种方法都有效。

def f(x, i):
  return x[i]

checkify_of_jit = checkify.checkify(jax.jit(f))
jit_of_checkify = jax.jit(checkify.checkify(f))
err, _ =  checkify_of_jit(jnp.ones((5,)), 100)
err.get()
# out-of-bounds indexing at <..>:2 (f)
err, _ = jit_of_checkify(jnp.ones((5,)), 100)
# out-of-bounds indexing at <..>:2 (f)

vmap/pmap #

您可以对已检查的函数进行 vmap 和 pmap 处理（或对已映射的函数进行 checkify 处理）。映射已检查的函数将为您提供一个已映射的错误，该错误可以包含已映射维度的每个元素的不同错误。

def f(x, i):
  checkify.check(i >= 0, "index needs to be non-negative!")
  return x[i]

checked_f = checkify.checkify(f, errors=checkify.all_checks)
errs, out = jax.vmap(checked_f)(jnp.ones((3, 5)), jnp.array([-1, 2, 100]))
errs.throw()
"""
ValueError:
  at mapped index 0: index needs to be non-negative! (check failed at <...>:2 (f))
  at mapped index 2: out-of-bounds indexing at <...>:3 (f)
"""

但是，checkify-of-vmap 将产生一个单独的（未映射）错误！

@jax.vmap
def f(x, i):
  checkify.check(i >= 0, "index needs to be non-negative!")
  return x[i]

checked_f = checkify.checkify(f, errors=checkify.all_checks)
err, out = checked_f(jnp.ones((3, 5)), jnp.array([-1, 2, 100]))
err.throw()
# ValueError: index needs to be non-negative! (check failed at <...>:2 (f))

pjit #

已检查函数的 pjit 可以正常工作，您只需要为错误值输出指定一个额外的 out_axis_resources 为 None。

def f(x):
  return x / x

f = checkify.checkify(f, errors=checkify.float_checks)
f = pjit(
  f,
  in_shardings=PartitionSpec('x', None),
  out_shardings=(None, PartitionSpec('x', None)))

with jax.sharding.Mesh(mesh.devices, mesh.axis_names):
 err, data = f(input_data)
err.throw()
# ValueError: divided by zero at <...>:4 (f)

grad #

如果您对 grad 进行 checkify 处理，您的梯度计算也将被修改。

def f(x):
 return x / (1 + jnp.sqrt(x))

grad_f = jax.grad(f)

err, _ = checkify.checkify(grad_f, errors=checkify.nan_checks)(0.)
print(err.get())
>> nan generated by primitive mul at <...>:3 (f)

请注意，f 中没有乘法，但其梯度计算中存在乘法（这就是生成 NaN 的地方！）。因此，使用 checkify-of-grad 为正向和反向传递操作添加自动检查。

checkify.check 仅应用于函数的原始值。如果您想在梯度值上使用 check，请使用 custom_vjp。

@jax.custom_vjp
def assert_gradient_negative(x):
 return x

def fwd(x):
 return assert_gradient_negative(x), None

def bwd(_, grad):
 checkify.check(grad < 0, "gradient needs to be negative!")
 return (grad,)

assert_gradient_negative.defvjp(fwd, bwd)

jax.grad(assert_gradient_negative)(-1.)
# ValueError: gradient needs to be negative!

jax.experimental.checkify 的优缺点 #

优点 #

  • 您可以在任何地方使用它（错误是“仅仅是值”，并且在像其他值一样的变换下表现得直观）

  • 自动修改：您无需对代码进行本地修改。相反， checkify 可以修改所有代码！

局限性 #

  • 添加大量运行时检查可能会很昂贵（例如，为每个基本操作添加 NaN 检查将为您的计算添加大量操作）

  • 需要将错误值从函数中传递出去，并手动抛出错误。如果错误没有显式抛出，您可能会错过错误！

  • 抛出错误值将在主机上具体化该错误值，这意味着它是一个阻塞操作，这将破坏 JAX 的异步提前运行。

目录