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
,以使这些预期更明确。
jaxlib#
jaxlib
包中的任何导入路径都被视为私有,并且可能在版本之间在不发出警告的情况下更改。jaxlib
中定义的一些API在 jax
包中有公共别名。
遗留的内部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,这些API旨在供下游项目使用,但没有与主JAX包相同的稳定性保证。如果您有使用 jax.extend
的代码,我们强烈建议针对JAX的每夜发布版进行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可能会公开一个临时配置标志来恢复新行为,以帮助用户诊断和更新受影响的代码。此类标志将持续一个弃用窗口的时间。