API 兼容性

API 兼容性#

JAX 在不断发展，我们希望能够对其API进行改进。尽管如此，我们希望尽量减少对JAX用户社区的变动，并且我们尽量少做破坏性的更改。

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

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

  • 在 jax 发布废弃某个 API 的三个月后，我们可能会随时移除该废弃的 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在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 可能会暴露一个临时的配置标志，以恢复新行为，帮助用户诊断和更新受影响的代码。此类标志将持续一个弃用窗口的时间。

目录