MXNet Scala Symbolic API 实战指南:计算图配置、序列化与执行

原创2026-09-20 20:35:001,835 阅读
文章标签:深度学习机器学习人工智能

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))

内部流程为:

  1. 调用 inferShape(shapeDict) 推断参数、输出、辅助状态的形状;
  2. 调用 inferType(types) 推断数据类型(未指定时默认 MX_REAL_TYPE,即 float32);
  3. 形状或类型推断失败时抛出 require 异常并列出已知信息;
  4. 用 NDArray.zeros 在目标 ctx 上分配参数、梯度(gradReq != "null" 时)与辅助状态数组;
  5. 调用 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 语义的补充读物。

下一步

登录后查看全文
mxnet