symbol_builder.py这个脚本主要包括import_module，get_symbol_train，get_symbol三个函数，后面两个函数类似，可以从get_symbol_train函数开始看，这里面调用了import_module函数。

    1. from __future__ import absolute_import
    2. import mxnet as mx
    3. # common.py脚本中的这两个函数主要是用到定义新层和anchor的。
    4. from .common import multi_layer_feature, multibox_layer  
    6. def import_module(module_name):
    7.     """Helper function to import module"""
    8.     import sys, os
    9.     import importlib
    10.     sys.path.append(os.path.dirname(__file__))
    11. # module_name只是一个str，这里调用importlib库的import_modole函数来导入指定名称的symbol脚本
    12.     return importlib.import_module(module_name)
    14. def get_symbol_train(network, num_classes, from_layers, num_filters, strides, pads,
    15.                      sizes, ratios, normalizations=-1, steps=[], min_filter=128,
    16.                      nms_thresh=0.5, force_suppress=False, nms_topk=400, **kwargs):
    17.     """Build network symbol for training SSD
    19.     Parameters
    20.     ----------
    21.     network : str
    22.         base network symbol name
    23.     num_classes : int
    24.         number of object classes not including background
    25.     from_layers : list of str
    26.         feature extraction layers, use '' for add extra layers
    27.         For example:
    28.         from_layers = ['relu4_3', 'fc7', '', '', '', '']
    29.         which means extract feature from relu4_3 and fc7, adding 4 extra layers
    30.         on top of fc7
    31.     num_filters : list of int
    32.         number of filters for extra layers, you can use -1 for extracted features,
    33.         however, if normalization and scale is applied, the number of filter for
    34.         that layer must be provided.
    35.         For example:
    36.         num_filters = [512, -1, 512, 256, 256, 256]
    37.     strides : list of int
    38.         strides for the 3x3 convolution appended, -1 can be used for extracted
    39.         feature layers
    40.     pads : list of int
    41.         paddings for the 3x3 convolution, -1 can be used for extracted layers
    42.     sizes : list or list of list
    43.         [min_size, max_size] for all layers or [[], [], []...] for specific layers
    44.     ratios : list or list of list
    45.         [ratio1, ratio2...] for all layers or [[], [], ...] for specific layers
    46.     normalizations : int or list of int
    47.         use normalizations value for all layers or [...] for specific layers,
    48.         -1 indicate no normalizations and scales
    49.     steps : list
    50.         specify steps for each MultiBoxPrior layer, leave empty, it will calculate
    51.         according to layer dimensions
    52.     min_filter : int
    53.         minimum number of filters used in 1x1 convolution
    54.     nms_thresh : float
    55.         non-maximum suppression threshold
    56.     force_suppress : boolean
    57.         whether suppress different class objects
    58.     nms_topk : int
    59.         apply NMS to top K detections
    61.     Returns
    62.     -------
    63.     mx.Symbol
    65.     """
    66.     label = mx.sym.Variable('label')
    67. # 调用前面的import_module函数，network是一个str，比如代码里面默认是‘vgg16_reduced’，
    68. # 因此后面的这个get_symbol就是调用的symbol文件夹下面的vgg16_reduced.py脚本中的get_symbol函数来得到symbol，
    69. # 因此body的数据类型是Symbol，是vgg16网络结构的定义。
    70.     body = import_module(network).get_symbol(num_classes, **kwargs)
    72. # 这里是调用symbol文件夹下的common.py脚本中的multi_layer_feature函数，生成的layers是一个列表，
    73. # 里面存放着包括relu4_3，relu7等6个symbol（这里是以输入图像大小为300*300的VGG16为例，所以是6个symbol）
    74.     layers = multi_layer_feature(body, from_layers, num_filters, strides, pads,
    75.         min_filter=min_filter)
    78. # 然后是调用commong.py脚本中的multibox_layer函数得到loc_preds，cls_preds，anchor_boxes三个symbol，
    79. # 这三个symbol分别表示回归层的计算，分类层的计算以及anchor是怎么生成和设计的。
    80. # 另外这个函数包含具体的取哪些层做特征融合以及怎么融合的过程。
    81.     loc_preds, cls_preds, anchor_boxes = multibox_layer(layers, \
    82.         num_classes, sizes=sizes, ratios=ratios, normalization=normalizations, \
    83.         num_channels=num_filters, clip=False, interm_layer=0, steps=steps)
    86. # mxnet.contrib.symbol.MultiBoxTarget的官方解释是用来Compute Multibox training targets，
    87. # 换句话说就是用来设定正负样本和处理模型预测值与真实值之间的关系。
    88. # 在输入中，anchor_boxes和cls_preds都是前面刚刚生成的symbol，维度都是3维，label也是一个symbol，
    89. # 是在该函数的第一行就定义的一个variable，在训练网络过程中这个label就是ground truth的信息。
    90. # overlap_threshold这个参数是用来判断哪些anchor是正样本的阈值，
    91. # 官方的介绍是：Anchor-GT overlap threshold to be regarded as a possitive match。
    92. # negative_mining_ratio表示max negative to positive samples ratio，也就是负样本和正样本的最大比例，
    93. # 之所以会有这个参数是因为一般数据中负样本的数量会远远大于正样本，通过限定负样本和正样本的比例可以使得模型更好收敛。
    94. # minimum_negative_samples表示负样本的最少数量。negative_mining_thresh表示threshold used for negative mining。
    95. # 最后得到的tmp也是一个symbol，包含3个部分，分别是loc_target，也就是回归的目标，简而言之是中心坐标和宽高的偏置；
    96. # loc_target_mask，这个mask的存在是因为框回归时候的损失函数回传只会回传和真实object框的IOU大于设定的overlap_threshold的anchors；
    97. # cls_target，表示每个anchor的真实标签。
    98.     tmp = mx.contrib.symbol.MultiBoxTarget(
    99.         *[anchor_boxes, label, cls_preds], overlap_threshold=.5, \
    100.         ignore_label=-1, negative_mining_ratio=3, minimum_negative_samples=0, \
    101.         negative_mining_thresh=.5, variances=(0.1, 0.1, 0.2, 0.2),
    102.         name="multibox_target")
    103.     loc_target = tmp[0]
    104.     loc_target_mask = tmp[1]
    105.     cls_target = tmp[2]
    108. # 针对分类，采用softmaxoutput来输出概率，其主要输入是网络生成的类别预测值：cls_preds和每个anchor的真实值：cls_target。
    109.     cls_prob = mx.symbol.SoftmaxOutput(data=cls_preds, label=cls_target, \
    110.         ignore_label=-1, use_ignore=True, grad_scale=1., multi_output=True, \
    111.         normalization='valid', name="cls_prob")
    113. # 针对边框回归，采用smooth L1损失函数。mxnet.symbol.smooth_l1是用来计算smooth L1损失，
    114. # 可以参看mxnet官网关于这个symbol的介绍：https://mxnet.incubator.apache.org/api/python/symbol.html#mxnet.symbol.smooth_l1。
    115. # 这里的输入用到了网络生成的框坐标预测值：loc_preds，真实框坐标：loc_target，回归框的mask：loc_target_mask。
    116. # loc_target_mask * (loc_preds - loc_target)表示只将有object的框的预测与实际值的差值作为损失函数的输入。
    117. # 另外这3个输入的维度都是一样的。
    118.     loc_loss_ = mx.symbol.smooth_l1(name="loc_loss_", \
    119.         data=loc_target_mask * (loc_preds - loc_target), scalar=1.0)
    121. # 这个mxnet.symbol.makeloss是用来生成你自己的loss函数的，其输入得是一个自定义的symbol，这里是用上面得到的smooth_l1损失作为输入。
    122. # 官方的一个例子：cross_entropy = label * log(out) + (1 - label) * log(1 - out)，loss = MakeLoss(cross_entropy)。
    123. # 这个normalization参数的含义如下：If this is set to null, the output gradient will not be normalized. 
    124. # If this is set to batch, the output gradient will be divided by the batch size. 
    125. # If this is set to valid, the output gradient will be divided by the number of valid input elements。
    126.     loc_loss = mx.symbol.MakeLoss(loc_loss_, grad_scale=1., \
    127.         normalization='valid', name="loc_loss")
    129.     # monitoring training status
    130. # 接下来这两个层并不参与梯度回传（因为grad_scale=0），只是用来提供后续计算某些值时的输入。
    131. # 因此即便后面用mx.symbol.Group()接口将这两层的输出也绑定在一起，但是对loss是没有贡献的。
    132. # nms操作是在mx.contrib.symbol.MultiBoxDetection()接口中实现的。
    133. # 现在在MXNet文档是调整为mx.symbol.contrib.MultiBoxDetection()接口。
    134. # 最后得到的det变量包含每个anchor的预测类别、置信度和4个坐标相关的值。
    135.     cls_label = mx.symbol.MakeLoss(data=cls_target, grad_scale=0, name="cls_label")
    136.     det = mx.contrib.symbol.MultiBoxDetection(*[cls_prob, loc_preds, anchor_boxes], \
    137.         name="detection", nms_threshold=nms_thresh, force_suppress=force_suppress,
    138.         variances=(0.1, 0.1, 0.2, 0.2), nms_topk=nms_topk)
    139.     det = mx.symbol.MakeLoss(data=det, grad_scale=0, name="det_out")
    142.     # group output
    143. # 最后输出分类的类别概率（每个anchor都有）：cls_prob；回归的损失：loc_loss；每个anchor的真实标签：cls_label。
    144.     out = mx.symbol.Group([cls_prob, loc_loss, cls_label, det])
    145.     return out
    147. def get_symbol(network, num_classes, from_layers, num_filters, sizes, ratios,
    148.                strides, pads, normalizations=-1, steps=[], min_filter=128,
    149.                nms_thresh=0.5, force_suppress=False, nms_topk=400, **kwargs):
    150.     """Build network for testing SSD
    152.     Parameters
    153.     ----------
    154.     network : str
    155.         base network symbol name
    156.     num_classes : int
    157.         number of object classes not including background
    158.     from_layers : list of str
    159.         feature extraction layers, use '' for add extra layers
    160.         For example:
    161.         from_layers = ['relu4_3', 'fc7', '', '', '', '']
    162.         which means extract feature from relu4_3 and fc7, adding 4 extra layers
    163.         on top of fc7
    164.     num_filters : list of int
    165.         number of filters for extra layers, you can use -1 for extracted features,
    166.         however, if normalization and scale is applied, the number of filter for
    167.         that layer must be provided.
    168.         For example:
    169.         num_filters = [512, -1, 512, 256, 256, 256]
    170.     strides : list of int
    171.         strides for the 3x3 convolution appended, -1 can be used for extracted
    172.         feature layers
    173.     pads : list of int
    174.         paddings for the 3x3 convolution, -1 can be used for extracted layers
    175.     sizes : list or list of list
    176.         [min_size, max_size] for all layers or [[], [], []...] for specific layers
    177.     ratios : list or list of list
    178.         [ratio1, ratio2...] for all layers or [[], [], ...] for specific layers
    179.     normalizations : int or list of int
    180.         use normalizations value for all layers or [...] for specific layers,
    181.         -1 indicate no normalizations and scales
    182.     steps : list
    183.         specify steps for each MultiBoxPrior layer, leave empty, it will calculate
    184.         according to layer dimensions
    185.     min_filter : int
    186.         minimum number of filters used in 1x1 convolution
    187.     nms_thresh : float
    188.         non-maximum suppression threshold
    189.     force_suppress : boolean
    190.         whether suppress different class objects
    191.     nms_topk : int
    192.         apply NMS to top K detections
    194.     Returns
    195.     -------
    196.     mx.Symbol
    198.     """
    199.     body = import_module(network).get_symbol(num_classes, **kwargs)
    200.     layers = multi_layer_feature(body, from_layers, num_filters, strides, pads,
    201.         min_filter=min_filter)
    203.     loc_preds, cls_preds, anchor_boxes = multibox_layer(layers, \
    204.         num_classes, sizes=sizes, ratios=ratios, normalization=normalizations, \
    205.         num_channels=num_filters, clip=False, interm_layer=0, steps=steps)
    207.     cls_prob = mx.symbol.SoftmaxActivation(data=cls_preds, mode='channel', \
    208.         name='cls_prob')
    209.     out = mx.contrib.symbol.MultiBoxDetection(*[cls_prob, loc_preds, anchor_boxes], \
    210.         name="detection", nms_threshold=nms_thresh, force_suppress=force_suppress,
    211.         variances=(0.1, 0.1, 0.2, 0.2), nms_topk=nms_topk)
    212.     return out