MXNet Scala Symbolic API 实战指南:从计算图构建、属性作用域到序列化与执行
MXNet Scala Symbolic API 实战指南:从计算图构建、属性作用域到序列化与执行
本文围绕 MXNet 的 Scala Symbolic API(符号式 API)展开,系统讲解如何用 Scala 声明式地构建深度学习计算图、为符号附加元数据、将符号图序列化为 JSON 并在不同语言/存储之间流转,以及如何将符号图绑定(bind)为可执行的 Executor 完成前向推理。读完本文,你将能够在 Scala 中独立完成「定义网络 → 标注属性 → 保存/加载模型结构 → 绑定执行」的完整链路,并理解其背后与 C++ 引擎交互的调用机制。
Symbol 是什么:声明式的计算图描述
MXNet 的 Symbolic API 提供了一种配置计算图的方式。与命令式逐条执行不同,Symbol 是对「将要执行的计算」的一种描述(description):通过符号式构建 API 生成计算图,再交给引擎去求值。你可以在两个粒度上配置计算图:
- 神经网络层操作(layer-level):如卷积
Convolution、全连接、池化等大粒度算子; - 细粒度操作(fine-grained):如逐元素加减乘除等基础数学运算。
配套的图解教程 Symbolic Configuration and Execution in Pictures 用图示展示了如何组合符号来描述基础计算、如何配置神经网络、如何绑定并执行符号图。
从底层看,Symbol 对象最终映射到 C++ 侧的 nnvm::Symbol 图结构,Scala 绑定通过 C API(如 src/c_api/c_api_symbolic.cc 中的 MXSymbolCreateVariable、MXSymbolCreateGroup)与后端交互。理解了这一点,就能明白为什么符号图可以跨语言共享——因为它本质上是一份与语言无关的图描述。
如何组合符号(How to Compose Symbols)
符号的构建非常直观。Symbol.Variable 用于创建代表计算输入的参数节点(argument node),而符号对基础算术运算符(加、减、除、乘)做了重载,使其可以直接作用于符号,生成逐元素运算(element-wise operations)。
下面的例子创建了一个将两个输入相加的计算图:
import org.apache.mxnet._
val a = Symbol.Variable("a")
val b = Symbol.Variable("b")
val c = a + b
这里 c 并不是计算结果的值,而是一个描述「a 加 b」的图节点。除了算术运算符,符号还可以通过 Symbol.api.xxx 之类的生成式接口组合成神经网络,例如文档后续出现的 Symbol.api.Convolution(...) 就是在符号图上附加一个卷积层算子。多输入网络的组合方式可以参考图解教程中的 多输入网络示例 一节。
符号属性(Symbol Attributes)
创建时附加属性
你可以通过属性字典在创建符号时给它附加元信息,属性字典的键和值都必须是字符串,这样才能与 C++ 后端正常通信:
val data = Symbol.Variable("data", Map("mood" -> "angry"))
val op = Symbol.api.Convolution(Some(data), kernel = Shape(1, 1), num_filter = 1,
attr = Map("mood" -> "so so"))
使用 attr(key) 可以取回属性,返回值是 Option[String]:
data.attr("mood")
// Option[String] = Some(angry)
底层对应 C API 的 MXSymbolGetAttr(src/c_api/c_api_symbolic.cc):它先尝试读取普通属性键,若未命中且该键属于隐藏键(如 name 等 kHiddenKeys),还会尝试读取 __key__ 形式的内部属性;而 MXSymbolSetAttr(src/c_api/c_api_symbolic.cc)则会把字符串键值对放入 kwargs 并调用 nnvm::Symbol::SetAttrs 写入图。这解释了为什么属性必须使用字符串类型——C API 层的参数传递完全基于 C 字符串。
AttrScope:作用域式批量附加属性
当需要给一个作用域内创建的所有符号统一附加属性时,可以使用 AttrScope。AttrScope 会自动把指定属性附加到该作用域内创建的所有符号上;你也可以继承这个对象来改变命名行为。看下面的例子:
val (data, gdata) =
AttrScope(Map("group" -> "4", "data" -> "great")).withScope {
val data = Symbol.Variable("data", attr = Map("dtype" -> "data", "group" -> "1"))
val gdata = Symbol.Variable("data2")
(data, gdata)
}
assert(gdata.attr("group").get === "4")
assert(data.attr("group").get === "1")
val exceedScopeData = Symbol.Variable("data3")
assert(exceedScopeData.attr("group") === None, "No group attr in global attr scope")
这段代码体现了三条关键语义:
- 作用域属性自动注入:
gdata没有显式指定group,却从AttrScope中继承了"4"; - 显式属性优先:
data显式传入了"group" -> "1",因此覆盖了作用域的"4"; - 作用域是局部的:离开
withScope之后创建的data3不再携带group属性,返回None。
这一「作用域栈 + 合并覆盖」的机制在 python/mxnet/attribute.py 的 AttrScope 实现中有对应体现:__enter__ 时把当前作用域属性与新的属性合并(attr.update(self._attr)),__exit__ 时恢复旧作用域;get() 方法中同样遵循「符号自带属性覆盖作用域属性」的优先级(ret.update(attr))。Python 侧的 AttrScope 还要求所有属性值必须是字符串类型,否则抛出 ValueError,这与本文档强调的「key 和 value 都应为字符串」是一致的约定。
序列化(Serialization)
保存与加载
符号可以通过 mxnet.Symbol.save 与 mxnet.Symbol.load 进行序列化。相比 Python 的 pickle,save/load 的优势在于语言无关(language agnostic)且对云存储友好(cloud friendly):符号以 JSON 格式保存,你还可以通过 mxnet.Symbol.toJson 直接拿到 JSON 字符串。
下面的例子演示了把符号保存到 S3 桶、再加载回来,并通过 JSON 字符串比较两个符号是否等价:
import org.apache.mxnet._
val a = Symbol.Variable("a")
val b = Symbol.Variable("b")
val c = a + b
c.save("s3://my-bucket/symbol-c.json")
val c2 = Symbol.load("s3://my-bucket/symbol-c.json")
c.toJson == c2.toJson
// Boolean = true
注意路径既可以是本地文件(/path/to/symbol.json),也可以是 s3:// 或 hdfs:// 前缀的云存储路径——这正是「云友好」的体现。由于图结构是纯 JSON 描述,不包含任何特定语言的对象状态,因此一个用 Scala 保存的符号完全可以被 Python、R 等其他语言绑定加载。
底层实现
在 C API 层,MXSymbolSaveToFile(src/c_api/c_api_symbolic.cc)负责将 nnvm::Symbol 图写入文件,另有 MXSymbolSaveToJSON 生成 JSON 字符串。Python 侧的对应实现位于 python/mxnet/symbol/symbol.py:save(fname, remove_amp_cast=True) 与 tojson(remove_amp_cast=True) 默认会在保存前移除自动混合精度(AMP)相关算子(MXSymbolRemoveAmpCast),以保证导出的图是纯粹的推理图;load(fname)(python/mxnet/symbol/symbol.py)则从 JSON 文件恢复符号。这些语义在 Scala 绑定中是共享的,因为它们最终都落到同一套 C++ 图结构与 C API 上。
一个常见的完整流程是:训练阶段把「网络结构(符号 JSON)」与「权重参数(NDArray 参数文件)」分开保存,推理阶段用 Symbol.load 恢复结构、再加载权重绑定执行(下一节)。
执行符号(Executing Symbols)
训练与推理的分工
把一组符号组装成计算图之后,MXNet 引擎就可以对其求值:
- 训练场景:通常由高层 Model 类 与其
fit()函数代为处理,无需手动绑定; - 前向/预测/推理场景(三个词指同一件事:运行一个训练好的网络):输入参数就是输入数据和训练阶段学到的网络权重,需要手动把数据与权重绑定到图上。
使用 simpleBind 创建 Executor
要手动执行一组符号,你需要创建一个 Executor 对象,最典型的构造方式是调用符号上的 simpleBind(...) 方法:
// 示意:为符号指定输入 shape 并完成绑定
val inputShape = Shape(1, 3, 224, 224)
val executor = sym.simpleBind(ctx = Context.cpu(),
shapeDict = Map("data" -> inputShape))
simpleBind 的精髓在于只需指定输入数据的形状(shape),框架会自动为参数分配 NDArray 并完成绑定,免去手工逐个传入参数数组的繁琐——尤其当图很大、参数很多时,这一简化非常关键。图解教程 Symbolic Configuration and Execution in Pictures 中专门用图示对比了「手动 bind」与「simpleBind」:前者需要把每个参数 NDArray 显式传给 bind,后者只要 shape 即可。
从 C++ 侧看,Executor::SimpleBind 的完整签名在 include/mxnet/executor.h,它接受:
default_ctx/group2ctx:默认上下文及分组到上下文的映射;arg_shape_map、arg_dtype_map、arg_stype_map:参数的形状、数据类型与存储类型;grad_req_types:梯度需求类型(kNullOp/kAddTo/kWriteTo,不需要梯度的参数可设为kNullOp);param_names:参数名集合,框架据此区分输入数据与可学习参数;- 输出参数
in_args、arg_grads、aux_states:绑定后自动分配好的输入参数、梯度存储与辅助状态。
而更底层的 Executor::Bind(include/mxnet/executor.h)则要求调用方显式提供 in_args、arg_grad_store、grad_req_type、aux_states 等 NDArray 数组,灵活性更高但更繁琐。
前向、反向与辅助状态
绑定完成后:
- 调用
Executor.Forward得到前向输出结果; - 若在绑定/求值时指定了存放梯度的 NDArray,则在
Forward之后调用Executor.backward即可得到对应梯度(训练阶段使用); - 辅助状态(auxiliary states)与参数类似,只不过不能对其求梯度。它们虽然不是计算的一部分,但常用于跟踪内部状态(例如 BatchNorm 的滑动均值/方差),传递方式与参数一致。
simpleBind 会一并处理好这些辅助状态的分配。另外提醒:只绑定你需要的内容,让系统能做更多优化。
多输出(Multiple Outputs)
一个符号图可以配置多个输出。做法是把若干符号用 Group 组合起来,再绑定执行,从而同时拿到多个输出结果。
- C API 层由
MXSymbolCreateGroup(src/c_api/c_api_symbolic.cc)实现,它接收一组SymbolHandle并生成一个分组符号; - Python 侧的
mx.sym.Group(python/mxnet/symbol/symbol.py)封装了该调用:mx.sym.Group([a, b])会返回一个Grouped符号,且要求列表中全部是符号类型(混合经典符号与 numpy 符号会抛TypeError)。
在多输出场景中同样遵循「按需绑定」原则:分组后只绑定你实际需要的输出,便于引擎做更多优化。也可以对分组符号中的单个输出使用 GetOutput(对应 MXSymbolGetOutput)按索引取出。
从 Scala 到 C++ 引擎的调用链
理解 Scala Symbolic API 的运行机制,关键是把握这条调用链:
Scala Symbol API(org.apache.mxnet.Symbol)
│
▼
C API(MXSymbolCreateVariable / MXSymbolGetAttr / MXSymbolSaveToFile / ...)
│
▼
C++ nnvm::Symbol 计算图 + MXNet Engine(线程调度、依赖追踪、算子执行)
- 图构建:
Symbol.Variable、运算符重载、Symbol.api.xxx最终都会在 C++ 侧生成nnvm::Symbol节点与边; - 属性读写:
attr(key)/AttrScope落到MXSymbolGetAttr/MXSymbolSetAttr,属性以(key, value)字符串对存储在图中; - 序列化:
save/toJson落到MXSymbolSaveToFile/MXSymbolSaveToJSON,输出语言无关的 JSON; - 执行:
simpleBind走到Executor::SimpleBind,完成内存分配与图绑定后,由引擎调度Forward/Backward。
这条链路也是「Scala 保存的符号可以被 Python 加载」的根本原因:结构信息全部沉淀在 C++ 侧的语言无关表示里,各语言绑定只是不同的「前端」。
下一步学习
- 阅读 Symbolic Configuration and Execution in Pictures,以图示方式回顾符号构建、绑定、前向反向、辅助状态与多输出的完整流程;
- 需要解析和加载数据时,参见 IO Data Loading API;
- 进行向量/矩阵/张量运算时,参见 NDArray API;
- 进行多 GPU 与多主机分布式训练时,参见 KVStore API;
- 想直接跑通「加载模型 + 推理」的高层封装,可参考 Scala Infer API 教程,其中展示了用
ImageClassifier对单张图片与批量图片做分类的完整 Scala 示例。