API 兼容性

API 兼容性#

JAX 正在不断发展，我们希望能够改进其 API。也就是说，我们希望将 JAX 用户社区的波动降到最低，并且我们尽量减少重大更改的发生。

JAX 遵循 3 个月的弃用策略。当对 API 进行不兼容的更改时，我们将尽力遵守以下程序

  • 更改将在 CHANGELOG.md 和弃用 API 的文档字符串中宣布，旧 API 将发出 DeprecationWarning。

  • 在弃用 API 的 jax 版本发布后三个月，我们可以在任何时间移除弃用 API。请注意，三个月只是一个 *下限*，并且有意选择比许多更成熟的项目更快。实际上，弃用可能需要相当长的时间，尤其是在一个功能有很多用户的情况下。如果三个月的弃用时间段存在问题，请告知我们。

我们保留随时更改此策略的权利。

涵盖哪些内容？#

仅涵盖公共 JAX API，包括以下模块

  • jax

  • jax.dlpack

  • jax.image

  • jax.lax

  • jax.nn

  • jax.numpy

  • jax.ops

  • jax.profiler

  • jax.random (参见 以下详情)

  • jax.scipy

  • jax.tree

  • jax.tree_util

  • jax.test_util

这些模块中的并非所有内容都旨在公开，随着时间的推移，我们正在努力将公共 API 和私有 API 分开。公共 API 在 JAX 文档中有所记录。此外，我们的目标是所有非公共 API 的名称都应该以下划线为前缀，尽管我们还没有完全遵守这一点。

未涵盖的内容？#

  • 任何以下划线为前缀的内容。

  • jax._src

  • jax.core

  • jax.lib

  • jax.interpreters

  • jax.experimental

  • jax.example_libraries

  • jax.extend (参见 详情)

此列表并不详尽。

数值和随机性#

数值运算的精确值不能保证在 JAX 版本之间保持稳定。实际上，精确数值不一定在给定的 JAX 版本中、在加速器平台之间、在 jax.jit 内或之外保持稳定，等等。

对于固定的 PRNG 密钥输入，jax.random 中伪随机函数的输出可能在 JAX 版本之间有所不同。兼容性策略仅适用于输出分布。例如，表达式 jax.random.gumbel(jax.random.key(72)) 可能会在 JAX 版本之间返回不同的值，但 jax.random.gumbel 将继续是 Gumbel 分布的伪随机生成器。

我们尽量少地更改伪随机值。如果发生更改，将在变更日志中公布，但不会遵循弃用周期。在某些情况下，JAX 可能会公开一个暂时的配置标志，以恢复新的行为，帮助用户诊断和更新受影响的代码。此类标志将持续一个弃用窗口的时间。

目录