API 兼容性#
JAX 不断发展,我们希望能够改进其 API。尽管如此,我们希望最大限度地减少 JAX 用户社区的动荡,并尽量避免进行重大更改。
JAX 版本控制#
JAX 使用 基于努力的版本控制(参见 JEP 25516:JAX 的基于努力的版本控制),目前处于零版本阶段。这意味着对于版本 0.X.Y
,递增 Y
将引入小的破坏性更改,而递增 X
将引入主要的破坏性更改。
对于任何破坏性更改,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 在 JAX 文档中记录。此外,我们的目标是所有非公共 API 都应以划线为前缀命名,尽管我们尚未完全遵守这一点。
未涵盖内容?#
显式私有 API#
任何以划线为前缀的 API 或导入路径都是显式私有的,并且可能在 JAX 版本之间更改,恕不另行通知。我们正在努力将所有私有 API 移动到 jax._src
,以使这些预期更加明确。
遗留内部 API#
此外,还有几个遗留模块当前公开了一些没有划线的私有 API,包括
jax.core
jax.interpreters
jax.lib
jax.util
我们正在积极努力弃用这些模块及其包含的 API。在大多数情况下,此类弃用将遵循 3 个月的弃用期,但这并非总是可能。如果您使用任何此类 API,请预计它们很快将被弃用,并寻找替代方案。
实验性和示例库#
以下模块包含用于实验或演示目的的代码,API 可能会在版本之间更改,恕不另行通知
jax.experimental
jax.example_libraries
我们理解某些用户依赖于 jax.experimental
,因此在大多数情况下,我们对更改遵循 3 个月的弃用期,但这并非总是可能。
JAX extend#
jax.extend
模块包含半公开的 JAX 内部 API,旨在供下游项目使用,但不具有与主 JAX 包相同的稳定性保证。如果您有代码使用 jax.extend
,我们强烈建议针对 JAX 的 nightly 版本进行 CI 测试,以便在潜在更改发布之前捕获它们。
有关 jax.extend
的详细信息,请参阅 jax.extend
模块文档,或设计文档 jax.extend:扩展模块。
数值和随机性#
数值运算的确切值不能保证在 JAX 版本之间保持稳定。事实上,在给定的 JAX 版本中,跨加速器平台,在 jax.jit
内外等等,精确的数值不一定是稳定的。
对于固定的 PRNG 密钥输入,jax.random
中伪随机函数的输出可能因 JAX 版本而异。兼容性策略仅适用于输出分布。例如,表达式 jax.random.gumbel(jax.random.key(72))
可能在不同的 JAX 版本中返回不同的值,但 jax.random.gumbel
将仍然是 Gumbel 分布的伪随机生成器。
我们尽量不频繁地对此类伪随机值进行更改。当发生更改时,更改会在变更日志中宣布,但不遵循弃用周期。在某些情况下,JAX 可能会公开一个临时的配置标志,以恢复新行为,以帮助用户诊断和更新受影响的代码。此类标志将持续一个弃用窗口的时间长度。