MXNet Scala Symbolic API 实战指南:计算图配置、序列化与执行
MXNet Scala Symbolic API 实战指南:计算图配置、序列化与执行
本教程面向使用 Scala 语言在 Apache MXNet 中构建、保存与执行深度学习计算图的开发者,系统讲解 org.apache.mxnet.Symbol 这一符号式(symbolic)编程接口:如何通过算子重载与神经网络层算子组合计算图、如何为符号附加属性、如何以语言无关的 JSON 格式序列化符号,以及如何绑定 Executor 完成前向推理与梯度计算。读完本文,你将能够用 Scala 编写可复用的网络定义代码,并掌握多输出图、属性作用域等进阶用法,为后续衔接 模型训练、数据加载 与 分布式 KVStore 打下基础。
本文对应的原始教程位于 symbol.md,配套的图文版教程见 Symbolic Configuration and Execution in Pictures。所有示例均可在本仓库的 Scala 包 scala-package/core/src/main/scala/org/apache/mxnet/ 下找到对应实现。
如何组合(Compose)符号
符号式 API 的核心思想是:先用描述性的符号(Symbol)搭建一张"计算图",再在需要时把数据真正"喂"进图中求值。计算图可以在两种粒度上配置:一是神经网络层级别的算子(如全连接、卷积、激活),二是更细粒度的逐元素数学运算。
两层神经网络的符号式定义
下面这段代码定义一个包含两个全连接层、ReLU 激活与 Softmax 输出的两层网络。注意每个算子的第一个参数是输入符号,num_hidden 指定隐藏单元数,name 为该节点命名:
import org.apache.mxnet._
val data = Symbol.Variable("data")
val fc1 = Symbol.api.FullyConnected(Some(data), num_hidden = 128, name = "fc1")
val act1 = Symbol.api.Activation(Some(fc1), "relu", "relu1")
val fc2 = Symbol.api.FullyConnected(Some(act1), num_hidden = 64, name = "fc2")
val net = Symbol.api.SoftmaxOutput(Some(fc2), name = "out")
:type net
// org.apache.mxnet.Symbol
Symbol.Variable("data")创建计算图的输入占位节点(argument node),data是它的名字;Symbol.api是SymbolAPI的入口(见 Symbol.scala),暴露了FullyConnected、Activation、Convolution、SoftmaxOutput等全部算子;- 整个过程中没有发生任何数值计算,
net只是一个记录节点拓扑关系的句柄(handle),其类型为org.apache.mxnet.Symbol。
算子重载:用运算符表达逐元素运算
基本算术运算符(加、减、除、乘)对 Symbol 做了逐元素运算的重载,可以直接写出直觉化的表达式。下面的代码构建了一个把两个输入相加的计算图:
import org.apache.mxnet._
val a = Symbol.Variable("a")
val b = Symbol.Variable("b")
val c = a + b
从源码看,+、-、*、/ 等运算符分别被映射到底层原子算子(atomic operator):_Plus、_Minus、_Mul、_Div,并且为标量运算生成了对应的 _PlusScalar、_MinusScalar 等变体(见 Symbol.scala)。此外还支持 **(幂)、>、>=、<、<=、% 以及 max、min、equal 等比较与聚合运算;当标量出现在运算符左侧时,会通过 SymbolConversions 隐式转换并生成 _RMinusScalar、_RDivScalar 这类反向标量算子(见 Symbol.scala)。例如 1.0 - a 也能写出合法的符号表达式。
每个符号在底层通过 createFromListedSymbols 调用 C 接口 mxSymbolCreateAtomicSymbol 创建原子符号,随后用 compose 把输入子符号连接到该节点上(见 Symbol.scala)。算子名称取自底层引擎通过 mxListAllOpNames 枚举出的全部算子表,因此 Scala 层可以覆盖与 Python/C++ 相同的算子集合。
符号属性(Symbol Attributes)
属性(attribute)用于给符号附加键值对形式的元信息,常用于标注数据来源、分组信息、dtype 等。
创建时附加属性
可以在创建符号时传入属性字典。属性同时支持变量节点与算子节点:
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"))
为了与 C++ 后端正确通信,属性字典的键和值都必须是字符串。取回属性使用 attr(key) 方法,返回 Option[String]:
data.attr("mood")
// Option[String] = Some(angry)
从实现上看,attr(key) 调用 C 接口 mxSymbolGetAttr,通过 success 标志区分"属性不存在"与"属性存在但值为空",不存在时返回 None(见 Symbol.scala)。若需要一次取出全部属性,可使用 listAttr()(浅层,仅当前节点)与 attrMap()(递归,含子节点,键格式为 childName -> Map[key -> value])。
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 -> "4"; - 显式属性优先:
data显式传入了group -> "1",覆盖了作用域中的同名键(见 AttrScope.scala,合并逻辑是scopeAttr ++ userDefinedAttr,后者覆盖前者); - 作用域不泄漏:
exceedScopeData在withScope之外创建,取不到group属性。
从实现看,AttrScope 采用全局 current 单例保存当前作用域状态,withScope 在进入时保存旧作用域、叠加属性并设为当前,在 finally 中恢复(见 AttrScope.scala)。符号创建时(如 Symbol.Variable、createFromListedSymbols)都会调用 AttrScope.current.get(...) 合并作用域属性再写入底层句柄。
Variable 的内置特殊属性
Symbol.Variable 还支持几个通过构造参数写入的特殊属性(见 Symbol.scala):
| 参数 | 写入的属性键 | 作用 |
|---|---|---|
shape |
__shape__ |
指定变量的形状,供形状推断使用 |
lrMult |
__lr_mult__ |
该输入变量的学习率倍率 |
wdMult |
__wd_mult__ |
该输入变量的权重衰减倍率 |
dType |
__dtype__ |
变量数据类型 |
kwargs |
自定义键 | 必须以 __ 开头和结尾,否则抛 require 异常 |
序列化:保存与加载符号
符号的序列化有两种途径:mxnet.Symbol.save / mxnet.Symbol.load 文件读写,以及 mxnet.Symbol.toJson / loadJson 的 JSON 字符串直取。前者的优势是语言无关且云友好——用 Scala 保存的符号文件可以被 Python、R、C++ 等其他语言绑定加载,并且可以直接读写 S3、HDFS 等云存储。
保存到 S3 并加载回来
下面的例子把符号保存到 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
save底层调用mxSymbolSaveToFile(见 Symbol.scala),支持s3://、hdfs://以及本地绝对路径三种文件名形式;load底层调用mxSymbolCreateFromFile(见 Symbol.scala);toJson底层调用mxSymbolSaveToJSON,返回可直接存储、传输或做哈希/比较的 JSON 字符串(见 Symbol.scala);Symbol.loadJson(json)则从字符串反序列化。
符号文件本身只描述计算图结构,不包含权重数值;模型参数(weight/bias 等 NDArray)需要配合 NDArray.save 单独存储,训练后的完整模型一般通过高层 Model 类 统一管理。
执行符号:绑定 Executor
符号搭建好之后,由 MXNet 引擎负责求值。对训练场景,这一过程通常由高层 Model 类 和 fit() 函数自动完成;而对"前向推理 / 预测"(feed-forward、prediction、inference 指同一件事:运行一个已训练好的网络)场景,输入参数就是输入数据和训练中学到的网络权重。
要手动执行一组符号,需要创建 Executor 对象,通常通过符号上的 simpleBind(<parameters>) 方法构造。
simpleBind:只给数据形状,自动分配
simpleBind 会基于已知的输入形状自动推断全部参数的形状与类型,并自动为参数和辅助状态分配 NDArray(见 Symbol.scala):
val executor = net.simpleBind(
ctx = Context.cpu(),
gradReq = "write",
shapeDict = Map("data" -> Shape(128, 784)),
typeDict = Map("data" -> DType.Float32))
内部流程为:
- 调用
inferShape(shapeDict)推断参数、输出、辅助状态的形状; - 调用
inferType(types)推断数据类型(未指定时默认MX_REAL_TYPE,即 float32); - 形状或类型推断失败时抛出
require异常并列出已知信息; - 用
NDArray.zeros在目标ctx上分配参数、梯度(gradReq != "null"时)与辅助状态数组; - 调用
bind(...)真正创建执行器。
gradReq(梯度需求)可取三种值,控制梯度如何写入 args_grad:
| 取值 | 语义 |
|---|---|
write |
每次梯度直接覆写到指定的 args_grad NDArray(默认) |
add |
每次梯度累加到指定 NDArray |
null |
不执行任何操作,梯度可能不被计算 |
inferShape 在信息不足时还会回退调用 mxSymbolInferShapePartial 做部分推断,并给出警告日志提示无法确定的参数(见 Symbol.scala)。
bind:显式绑定 NDArray
如果希望完全掌控参数的存放位置(例如把训练好的权重直接塞进执行器),可以改用 bind。bind 提供大量重载,参数既可以按 listArguments() 的顺序传 Seq<a href="https://link.gitcode.com/i/09bf0b172f799170196641578c8857c4" target="_blank">NDArray],也可以按名字传 Map[String, NDArray];argsGrad、auxStates 同理(见 [Symbol.scala)。所有重载最终汇总到 bindHelper,统一调用 C 接口 mxExecutorBindEX 创建执行器,并按 gradReq 映射表("null" -> 0、"write" -> 1、"add" -> 3)转换请求值。
绑定后通过 Executor 对象求值:
forward():前向计算。forward(isTrain: Boolean, kwargs: (String, NDArray)*)可先按参数名把输入 NDArray 拷入执行器(调用mxExecutorForward,见 Executor.scala);outputs:执行器头部的输出 NDArray 数组(由mxExecutorOutputs取得);backward(outGrads: Array<a href="https://link.gitcode.com/i/a7d83461aa931e52cbbd74f3baacc19c" target="_blank">NDArray]):反向传播,计算参数的梯度(见 [Executor.scala);argDict/gradDict/auxDict:分别按参数名取参数、梯度、辅助状态的 NDArray 字典;copyParamsFrom(argParams, auxParams):把已训练参数批量拷入执行器,适合推理部署;reshape(...):共享内存的动态形状调整,适用于变长序列等场景(见 Executor.scala)。
注意:Executor 与 Symbol 都是持有底层原生句柄的资源对象,使用完毕后应调用 dispose() 释放,参见 Executor.scala 中的释放逻辑。
多个输出:Symbol.Group
用 mxnet.symbol.Group 可以把多个符号打包成一个组合符号,绑定后执行器将同时产出多个输出。示例中我们把 fc1 的中间结果与 net 的最终结果一起输出:
import org.apache.mxnet._
val data = Symbol.Variable("data")
val fc1 = Symbol.api.FullyConnected(Some(data), num_hidden = 128, name = "fc1")
val act1 = Symbol.api.Activation(Some(fc1), "relu", "relu1")
val fc2 = Symbol.api.FullyConnected(Some(act1), num_hidden = 64, name = "fc2")
val net = Symbol.api.SoftmaxOutput(Some(fc2), name = "out")
val group = Symbol.Group(fc1, net)
group.listOutputs()
// IndexedSeq[String] = ArrayBuffer(fc1_output, out_output)
得到 group 后,直接对它绑定即可。生成的执行器将有两个输出:fc1_output 与 out_output(Softmax 输出)。Group 底层调用 mxSymbolCreateGroup 把多个符号句柄聚合成一个新符号(见 Symbol.scala),listOutputs() 则调用 mxSymbolListOutputs 枚举输出名。
实践中可以借助 listOutputs() 确认每个输出的命名规则(默认格式为 <节点名>_output),再通过 get(index) 或 get(name) 取回单个输出符号。需要说明的是,若只想拿到计算图中某个中间节点,还可以用 getInternals() 获取包含全部内部输出的组合符号,再按名字取出,例如 net.getInternals().get("fc1_output")——这一点在 SymbolSuite.scala 的 symbol internal 测试中有直接验证。
另外,一个值得记住的建议(同样出现在图文教程 symbol_in_pictures.md 中):只绑定你需要的输出,这样引擎可以做更多优化。
配套源码与测试验证
- 符号核心实现:Symbol.scala——运算符重载、
Variable、Group、save/load/toJson、simpleBind/bind全部在此; - 属性作用域:AttrScope.scala;
- 执行器实现:Executor.scala;
- 算子入口:SymbolAPI.scala 与编译期生成机制 SymbolMacro.scala;
- 单元测试:SymbolSuite.scala 覆盖了符号组合(
symbol compose)、内部输出提取、类型推断(inferType)、符号复制等场景,可作为理解 API 语义的补充读物。
下一步
- 解析与加载数据:阅读 IO Data Loading API;
- 向量/矩阵/张量运算:阅读 NDArray API;
- 多 GPU 与多机分布式训练:阅读 KVStore API;
- 用高层接口直接训练模型:阅读 Model API 教程;
- 图形化的符号构建与执行概念讲解:阅读 Symbolic Configuration and Execution in Pictures。