深入理解 Ivy 的函数类型体系:Primary、Compositional、Mixed 与 Standalone 函数
深入理解 Ivy 的函数类型体系:Primary、Compositional、Mixed 与 Standalone 函数
Ivy 是一个统一机器学习框架接口、支持多框架(NumPy、JAX、TensorFlow、PyTorch、PaddlePaddle 等)之间代码转换的库。要驾驭 Ivy,首先必须理解它的函数是如何被组织与分类的。本指南以 function_types.rst 为核心,系统讲解 Ivy 中四类核心函数类型(Primary、Compositional、Mixed、Standalone)的定义、源码实现与协作关系,并进一步解释 Nestable 与 Convenience 两个正交维度。读完本文,你将能准确判断任意 Ivy 函数的实现归属、理解装饰器包装机制,并具备阅读与扩展 Ivy 后端代码的能力。
总览:四种函数类型的关系
Ivy 将全部函数划分为四种类型:Primary(主函数)、Compositional(组合函数)、Mixed(混合函数)与 Standalone(独立函数)。这四种分类是互斥(mutually exclusive)的,即任何一个 Ivy 函数只能属于其中一种;同时这四类函数合起来构成了 Ivy 中全部函数(即集合完备)。四类函数的关系可以用一个简单的韦恩图表示:四个互不重叠的区域,拼成整个 Ivy 函数全集。
理解这一分类体系的关键在于 Ivy 的两级代码结构:
- 前端(函数声明与组合实现所在层):
ivy/functional/ivy/,例如 elementwise.py、losses.py 等分类模块; - 后端(框架特定实现所在层):
ivy/functional/backends/<backend_name>/,例如 torch/elementwise.py、jax/layers.py 等。
Primary 与 Compositional 的差异,本质上就是"该函数在后端是否有专属实现"的差异。下面逐一展开。
Primary Functions(主函数):最底层的构建块
Primary 函数是 Ivy 中最底层的构建块。每个 Primary 函数在 ivy/functional/backends/<backend_name>/<category_name>.py 中都有唯一对应的后端专属实现。这些实现通常只是对后端框架中功能几乎相同的既有函数做一层轻量包装——例如 torch 后端直接调用 torch.tan、torch.nn.functional.linear 等。由于直接复用了框架原生实现(底层多为 C/C++ 代码),Primary 函数的运行效率最高。
Primary 函数必须同时满足两个"双写"要求:
- 在
ivy/functional/ivy/<category_name>.py中声明:包含类型注解、docstring 与 docstring 示例,但不包含真正的实现; - 在每个后端文件
ivy/functional/backends/<backend_name>/<category_name>.py中提供框架专属实现。
以前端 elementwise.py 中的 ivy.tan 为例(去掉装饰器与 docstring 后),其核心只有一行,直接委托给当前后端:
def tan(
x: Union[ivy.Array, ivy.NativeArray],
/,
*,
out: Optional[ivy.Array] = None,
) -> ivy.Array:
return ivy.current_backend(x).tan(x, out=out)
而 PyTorch 后端在 torch/elementwise.py 中的实现同样轻量:
def tan(
x: torch.Tensor,
/,
*,
out: Optional[torch.Tensor] = None
) -> torch.Tensor:
x = _cast_for_unary_op(x)
return torch.tan(x, out=out)
注意两个实现中类型注解的差异:Ivy 层使用 Union<a href="https://link.gitcode.com/i/8b5a2d0712de09d9ba4e6dad04f325ec" target="_blank">ivy.Array, ivy.NativeArray],而 torch 层使用 torch.Tensor。这是由 Ivy 的数组体系决定的——ivy.Array 是 Ivy 对原生数组的封装,ivy.NativeArray 指各框架的原生张量;后端函数只处理原生张量。同样地,out 参数在 Ivy 层注解为 ivy.Array,而 x 注解为 Union[ivy.Array, ivy.NativeArray],这也与 Ivy 的数组类型转换规则相关,详见 [arrays.rst。
Compositional Functions(组合函数):由 Ivy 函数拼装而成
与 Primary 相反,Compositional 函数没有后端专属实现,它们由其他 Ivy 函数组合而成——被组合的成员既可以是 Primary、也可以是 Compositional、还可以是 Mixed 函数。因此 Compositional 函数只存在于 ivy/functional/ivy/<category_name>.py,后端目录中不存在其对应实现。
以 losses.py 中的 ivy.cross_entropy 为例(去掉 docstring 与装饰器后),可以看到它是纯粹的"组合式"实现:
def cross_entropy(
true: Union[ivy.Array, ivy.NativeArray],
pred: Union[ivy.Array, ivy.NativeArray],
/,
*,
axis: int = -1,
epsilon: float = 1e-7,
reduction: str = "mean",
out: Optional[ivy.Array] = None
) -> ivy.Array:
ivy.utils.assertions.check_elem_in_list(reduction, ["none", "sum", "mean"])
pred = ivy.clip(pred, epsilon, 1 - epsilon)
log_pred = ivy.log(pred)
return _reduce_loss(reduction, log_pred * true, axis, out)
这段代码依次调用了 ivy.clip、ivy.log、ivy.negative、ivy.sum、ivy.mean 等 Ivy 函数,并借助 _reduce_loss 私有辅助函数(losses.py#L19-L25)实现 sum/mean/none 三种 reduction 策略。其中 ivy.clip 等底层函数又会分别委托给各自的后端实现,从而形成"前端组合、后端分工"的调用链。这种设计让新函数可以完全在框架无关的层实现,代价是相比直接调用后端原生函数有一定性能开销。
Mixed Functions(混合函数):后端实现与组合实现并存
有些函数只被部分后端原生提供(例如某些后端根本没有对应算子,或算子行为不完全一致)。此时 Ivy 采取混合策略(mixed approach):
- 只要某个后端提供了功能近似的原生函数,就必须为其编写后端专属实现,以最大化运行时效率(原生实现通常是 C/C++);
- 对于没有原生函数可包装的后端,则提供组合式实现兜底。
由于这类函数同时拥有"组合式实现 + 至少一个后端专属实现",故得名 Mixed。从文件布局看,Mixed 函数在 ivy/functional/ivy/<category_name>.py 中有组合实现,同时在部分(而非全部)ivy/functional/backends/<backend_name>/<category_name>.py 中有专属实现。
一个需要特别注意的行为细节:未显式设置后端时,Mixed 函数永远走组合式实现。原因在于:Primary 函数会通过 ivy.current_backend(array_arg).func_name(...) 直接调度到后端专属实现;而 Mixed 函数在 ivy/functional/ivy/ 层提供的是组合实现而非委托代码,因此即使某个后端明明有更高效的专属实现,只要没有调用 ivy.set_backend(...) 显式设置后端,就仍会使用组合实现。实践中的最佳做法是:始终显式设置后端(例如 ivy.set_backend("torch")),这样只要存在后端专属实现,就一定会被优先调用。
Mixed 函数还有两个附加机制:partial_mixed_handler 与 mixed_backend_wrappers,见下文。
Partial Mixed Functions(部分混合函数):最大化利用原生能力
现实场景中,某些后端原生函数并不能覆盖 Ivy 想要支持的全部输入情形,但能覆盖其中一部分。Ivy 的原则是:在保证跨后端超集行为(superset behaviour)的前提下,尽可能多地复用框架原生功能——即使原生函数只提供部分超集行为,也先用它处理能覆盖的部分,再对剩余情形补充逻辑。这与 superset_behaviour.rst 中"Maximizing Usage of Native Functionality"一节的思路一致。
Ivy 通过为后端实现附加 partial_mixed_handler 属性来支持这种部分混合机制:该属性是一个布尔函数,以函数输入为参数,用于决定当前输入应当走 Primary(原生)实现还是 Compositional(组合)实现。
最经典的例子是 ivy.linear:torch 的原生 torch.nn.functional.linear 只支持 2 维的 weight 张量,而 Ivy 还允许 3 维 weight。torch 后端实现见 torch/layers.py:
def linear(
x: torch.Tensor,
weight: torch.Tensor,
/,
*,
bias: Optional[torch.Tensor] = None,
out: Optional[torch.Tensor] = None,
) -> torch.Tensor:
return torch.nn.functional.linear(x, weight, bias)
linear.partial_mixed_handler = lambda x, weight, **kwargs: weight.ndim == 2
这里的布尔函数表达得非常直观:当 weight 是 2 维时走 torch 原生实现(高效),否则走组合实现(完整支持 3 维场景)。
相应地,组合实现侧需要加上 handle_partial_mixed_function 装饰器。在 func_wrapper.py#L955-L970 中,该装饰器的执行逻辑是:
- 检查被包装函数是否带有
partial_mixed_handler属性——若没有,则直接在后端处理(handle_mixed_in_backend = True); - 若有,则取出
compos(组合实现)与condition(布尔条件); - 若条件为真,调用后端专属实现
fn(*args, **kwargs);否则回退到组合实现compos(*args, **kwargs)。
当后端被显式设置后,_wrap_function 会按照 FN_DECORATORS 列表(func_wrapper.py#L17-L39)中的顺序把 handle_partial_mixed_function 装饰器挂到 Primary 实现上(相关逻辑见 func_wrapper.py#L1076-L1097)。
partial_mixed_handler 在仓库中大量使用,例如:
- torch/experimental/layers.py 中的
dropout:根据输入类型/概率条件切换实现; - torch/experimental/manipulation.py 中的
pad; - numpy/experimental/manipulation.py 中的
put_along_axis:按mode参数切换; - paddle/general.py 与 torch/general.py 中的
get_item等。
mixed_backend_wrappers:为 Primary 实现配置包装器
对于所有 Mixed 函数,还需要在组合实现上附加 mixed_backend_wrappers 属性,用于声明:Primary(后端)实现需要额外追加哪些包装器,以及组合实现中哪些包装器应被跳过。该属性是一个包含两个键的字典:
to_add:需要追加到 Primary 实现的包装器元组。一般来说handle_out_argument、inputs_to_native_arrays、outputs_to_ivy_arrays应当总是被追加到 Primary 实现;to_skip:组合实现中需要跳过的包装器元组。一般来说inputs_to_ivy_arrays应当被跳过。
仍以 linear 为例,其 mixed_backend_wrappers 定义如下(见 functional/ivy/layers.py 附近的组合实现):
linear.mixed_backend_wrappers = {
"to_add": (
"handle_out_argument",
"inputs_to_native_arrays",
"outputs_to_ivy_arrays",
),
"to_skip": ("inputs_to_ivy_arrays", "handle_partial_mixed_function"),
}
当后端被设置时,_wrap_function 会在 func_wrapper.py#L1064-L1097 中根据 mixed_backend_wrappers 处理这些包装器:先判断是否为 Mixed 函数(hasattr(original, "mixed_backend_wrappers") and original != to_wrap),再读取 to_add/to_skip,随后遍历 FN_DECORATORS 应用装饰器。此外,若函数是 partial mixed,还需把 handle_partial_mixed_function 之后的那些装饰器从组合实现 compos 上逐层剥离(to_wrap.compos = to_wrap.compos.__wrapped__),因为这些工作将由 Primary 实现统一完成,避免重复包装。
关于装饰器机制的完整讲解,请参阅 function_wrapping.rst。
Standalone Functions(独立函数):不引用任何其他函数
Standalone 函数是完全不引用任何 Primary、Compositional 或 Mixed 函数的函数。按定义,它们只能引用自身(递归)或其他 Standalone 函数。最常见的 Standalone 函数就是便利函数(Convenience functions)。
最典型的例子是 ivy/functional/ivy/nest.py 中的全部函数——它们要么不引用任何函数,要么只递归地引用自己,要么只引用其他 Standalone 函数。例如:
- ivy.default:若
x存在则返回x,否则返回默认值; - ivy.cache_fn:包装一个函数,当传入
cache=True时返回之前缓存过的输出; - ivy.stable_divide:在除法分母上加上一个小常数,实现数值稳定除法。
由于这类函数不参与张量运算主流程,它们不属于计算图的一部分,不直接修改数组,但常被其他函数用来组织与优化代码。
Nestable Functions(可嵌套函数):以 Container 为输入
Nestable 是另一个正交维度(与上述四类互斥分类不互斥,如韦恩图所示):Primary、Compositional、Mixed、Standalone 函数都可以同时是 Nestable 的。
Nestable 函数允许在任意参数位置接受 ivy.Container 实例。多个参数可以同时传入 Container,前提是这些 Container 共享相同的嵌套结构。当传入 Container 时,函数会对容器的所有叶子逐一应用,叶子值作为对应位置的参数传入函数,输出同样是一个 ivy.Container。
这一特性让同一份代码既能处理单个参数,也能处理任意批次的嵌套参数——在机器学习中尤为实用:例如同时处理一批不同的训练数据,或对网络中的每个权重执行同一操作,都不需要修改函数本身。
Nestable 的包装逻辑在 func_wrapper.py#L871-L913 的 handle_nestable 装饰器中实现:运行时若检测到 ivy.nestable_mode 开启且参数/关键字参数中存在 Container,则调用 ivy.Container 的静态方法(或 cont_multi_map_in_function)将函数映射到容器叶子;否则直接调用原函数。在**后端设置(backend setting)**过程中,_wrap_function 会对 ivy 模块中的每个函数应用包装;凡带有 @handle_nestable 装饰器的函数都会获得这一能力(见 func_wrapper.py#L1076-L1084 中按 FN_DECORATORS 顺序应用装饰器的逻辑)。
关于 Nestable 与 Container 的更多细节,请参阅 containers.rst。
Convenience Functions(便利函数):组织代码而非计算
Convenience 函数同样是与前四类不互斥的正交分类:它们不直接形成计算图,也不直接修改数组,而是用于组织与改进其他会修改数组的函数的代码。Convenience 函数可以是 Primary、Compositional、Mixed 或 Standalone 函数,其中许多同时也是 Nestable 的。
仓库中各类 Convenience 函数示例:
- Primary 便利函数:
- ivy.can_cast:依据类型提升规则判断一种数据类型能否转换为另一种;
- ivy.dtype:获取输入数组的数据类型;
- ivy.dev:获取输入数组所在的设备;
- Compositional 便利函数:
- ivy.set_default_dtype:设置全局默认数据类型;
- ivy.default_dtype:综合考虑输入与全局默认类型,返回应使用的数据类型;
- ivy.get_all_arrays_on_dev:获取当前位于指定设备上的所有数组;
- Standalone 便利函数:
- ivy.get_backend:返回绑定了指定后端框架的本地 Ivy 模块;
- ivy.nested_map:将任意函数映射到任意嵌套结构的叶子;
- ivy.index_nest:对任意嵌套结构进行递归索引。
Convenience 函数不按文件或目录分组,它们散布在各个子模块中。浏览 ivy/functional/ivy/ 下的全部子模块(目录列表),你会发现更多同类函数。
总结:如何判断一个 Ivy 函数属于哪种类型
读完本文,你可以用如下方法快速判断任意 Ivy 函数的类型:
- 在
ivy/functional/backends/<backend>/目录中查找是否存在同名实现:- 所有后端都有 → Primary;
- 部分后端有、且前端层提供组合实现 → Mixed;
- 全部后端都没有 → 继续看第 2 步;
- 在前端
ivy/functional/ivy/<category>.py中查看其实现:- 函数体只是
ivy.current_backend(...)委托调用 → Primary; - 函数体由若干其他 Ivy 函数组合而成 → Compositional;
- 函数体不引用任何 Ivy 函数(只引用自身或同类函数)→ Standalone;
- 函数体只是
- 进一步检查:
- 后端实现上是否有
partial_mixed_handler属性 → Partial Mixed(属于 Mixed 的特殊形态); - 前端实现上是否带
@handle_nestable装饰器 → Nestable; - 是否属于查询数据类型、设备、默认值等工具函数 → Convenience。
- 后端实现上是否有
理解这四种函数类型,是阅读 Ivy 源码、编写新算子、以及为自定义后端贡献实现的起点。若要继续深入装饰器与函数包装的完整机制,请阅读 function_wrapping.rst;若想了解后端如何被设置与调度,请阅读 backend_setting.rst 与 navigating_the_code.rst。