TensorNets

在 TensorFlow 中提供带有预训练权重的高级网络定义（经测试与 2.1.0 >= TF >= 1.4.0 兼容）。

指导原则

• 适用性。 许多人已经有自己的机器学习工作流，并希望在其工作流中加入新模型。TensorNets 可以轻松集成，因为它被设计为简单的函数式接口，而不使用自定义类。
• 可管理性。 模型使用 tf.contrib.layers 编写，其轻量级特性类似于 PyTorch 和 Keras，便于访问每个权重和输出端点。此外，部署和扩展预处理及预训练权重的集合也非常容易。
• 可读性。 借助最新的 TensorFlow API，可以实现更多的代码模块化和更少的缩进。例如，所有 Inception 变体在 TensorNets 中仅用约 500 行代码实现，而在 官方 TensorFlow 模型 中则需要 2000 多行。
• 可复现性。 您始终可以通过包括特征提取在内的简单 API 复现原始结果。此外，您无需担心 TensorFlow 的版本问题，因为与不同版本 TensorFlow 的兼容性已通过 Travis 进行了验证。

安装

您可以从 PyPI (pip install tensornets) 或直接从 GitHub (pip install git+https://github.com/taehoonlee/tensornets.git) 安装 TensorNets。

快速示例

每个网络（参见完整列表）都不是自定义类，而是一个以 tf.Tensor 作为输入和输出的函数。以下是 ResNet50 的示例：

import tensorflow as tf
# import tensorflow.compat.v1 as tf  # 适用于 TF 2
import tensornets as nets
# tf.disable_v2_behavior()  # 适用于 TF 2

inputs = tf.placeholder(tf.float32, [None, 224, 224, 3])
model = nets.ResNet50(inputs)

assert isinstance(model, tf.Tensor)

您可以使用 utils.load_img 加载示例图像，该函数返回一个 NHWC 格式的 np.ndarray：

img = nets.utils.load_img('cat.png', target_size=256, crop_size=224)
assert img.shape == (1, 224, 224, 3)

一旦创建了您的网络，就可以使用常规的 TensorFlow API 运行 😊，因为 TensorNets 中的所有网络始终返回 tf.Tensor。使用预训练权重和预处理非常简单，只需调用 pretrained() 和 preprocess()，即可复现原始结果：

with tf.Session() as sess:
    img = model.preprocess(img)  # 等同于 img = nets.preprocess(model, img)
    sess.run(model.pretrained())  # 等同于 nets.pretrained(model)
    preds = sess.run(model, {inputs: img})

您可以查看最可能的类别：

print(nets.utils.decode_predictions(preds, top=2)[0])
[(u'n02124075', u'Egyptian_cat', 0.28067636), (u'n02127052', u'lynx', 0.16826575)]

您还可以轻松获取中间层的值，使用 middles() 和 outputs()：

with tf.Session() as sess:
    img = model.preprocess(img)
    sess.run(model.pretrained())
    middles = sess.run(model.middles(), {inputs: img})
    outputs = sess.run(model.outputs(), {inputs: img})

model.print_middles()
assert middles[0].shape == (1, 56, 56, 256)
assert middles[-1].shape == (1, 7, 7, 2048)

model.print_outputs()
assert sum(sum((outputs[-1] - preds) ** 2)) < 1e-8

借助 load() 和 save()，您的权重值可以恢复：

with tf.Session() as sess:
    model.init()
    # ... 您的训练 ...
    model.save('test.npz')

with tf.Session() as sess:
    model.load('test.npz')
    # ... 您的部署 ...

TensorNets 使我们能够更快地部署知名架构并对其进行基准测试 ⚡️。有关更多信息，请查看 实用工具、示例 和 架构 列表。

目标检测示例

每个目标检测模型都可以与 TensorNets 中的任何网络结合使用（参见 性能），并接受两个参数：占位符和充当茎层的函数。以下是用于 PASCAL VOC 的 YOLOv2 示例：

import tensorflow as tf
import tensornets as nets

inputs = tf.placeholder(tf.float32, [None, 416, 416, 3])
model = nets.YOLOv2(inputs, nets.Darknet19)

img = nets.utils.load_img('cat.png')

with tf.Session() as sess:
    sess.run(model.pretrained())
    preds = sess.run(model, {inputs: model.preprocess(img)})
    boxes = model.get_boxes(preds, img.shape[1:3])

与其他模型一样，检测模型也会返回 tf.Tensor 作为输出。您可以使用 model.get_boxes(model_output, original_img_shape) 查看边界框预测 (x1, y1, x2, y2, score)，并可视化结果：

from tensornets.datasets import voc
print("%s: %s" % (voc.classnames[7], boxes[7][0]))  # 7 是猫

import numpy as np
import matplotlib.pyplot as plt
box = boxes[7][0]
plt.imshow(img[0].astype(np.uint8))
plt.gca().add_patch(plt.Rectangle(
    (box[0], box[1]), box[2] - box[0], box[3] - box[1],
    fill=False, edgecolor='r', linewidth=2))
plt.show()

更多检测示例，例如 VOC2007 上的 FasterRCNN，可在这里找到 😎。请注意：

• 检测模型的 API 略有不同：

  • YOLOv3: sess.run(model.preds, {inputs: img}),
  • YOLOv2: sess.run(model, {inputs: img}),
  • FasterRCNN: sess.run(model, {inputs: img, model.scales: scale})，

• FasterRCNN 需要 roi_pooling：

  • git clone https://github.com/deepsense-io/roi-pooling && cd roi-pooling && vi roi_pooling/Makefile 并根据此处进行编辑，
  • python setup.py install。

工具函数

除了 pretrained() 和 preprocess() 之外，输出的 tf.Tensor 还提供了以下有用的方法：

• logits：返回 tf.Tensor 形式的 logits（即 softmax 之前的值）；
• middles()（=get_middles()）：返回所有代表性端点的 tf.Tensor 列表；
• outputs()（=get_outputs()）：返回所有端点的 tf.Tensor 列表；
• weights()（=get_weights()）：返回所有权重矩阵的 tf.Tensor 列表；
• summary()（=print_summary()）：打印层数、权重矩阵数和参数量；
• print_middles()：打印所有代表性端点；
• print_outputs()：打印所有端点；
• print_weights()：打印所有权重矩阵。

>>> model.print_middles()
Scope: resnet50
conv2/block1/out:0 (?, 56, 56, 256)
conv2/block2/out:0 (?, 56, 56, 256)
conv2/block3/out:0 (?, 56, 56, 256)
conv3/block1/out:0 (?, 28, 28, 512)
conv3/block2/out:0 (?, 28, 28, 512)
conv3/block3/out:0 (?, 28, 28, 512)
conv3/block4/out:0 (?, 28, 28, 512)
conv4/block1/out:0 (?, 14, 14, 1024)
...

>>> model.print_outputs()
Scope: resnet50
conv1/pad:0 (?, 230, 230, 3)
conv1/conv/BiasAdd:0 (?, 112, 112, 64)
conv1/bn/batchnorm/add_1:0 (?, 112, 112, 64)
conv1/relu:0 (?, 112, 112, 64)
pool1/pad:0 (?, 114, 114, 64)
pool1/MaxPool:0 (?, 56, 56, 64)
conv2/block1/0/conv/BiasAdd:0 (?, 56, 56, 256)
conv2/block1/0/bn/batchnorm/add_1:0 (?, 56, 56, 256)
conv2/block1/1/conv/BiasAdd:0 (?, 56, 56, 64)
conv2/block1/1/bn/batchnorm/add_1:0 (?, 56, 56, 64)
conv2/block1/1/relu:0 (?, 56, 56, 64)
...

>>> model.print_weights()
Scope: resnet50
conv1/conv/weights:0 (7, 7, 3, 64)
conv1/conv/biases:0 (64,)
conv1/bn/beta:0 (64,)
conv1/bn/gamma:0 (64,)
conv1/bn/moving_mean:0 (64,)
conv1/bn/moving_variance:0 (64,)
conv2/block1/0/conv/weights:0 (1, 1, 64, 256)
conv2/block1/0/conv/biases:0 (256,)
conv2/block1/0/bn/beta:0 (256,)
conv2/block1/0/bn/gamma:0 (256,)
...

>>> model.summary()
Scope: resnet50
Total layers: 54
Total weights: 320
Total parameters: 25,636,712

示例

• 不同网络的比较：

inputs = tf.placeholder(tf.float32, [None, 224, 224, 3])
models = [
    nets.MobileNet75(inputs),
    nets.MobileNet100(inputs),
    nets.SqueezeNet(inputs),
]

img = utils.load_img('cat.png', target_size=256, crop_size=224)
imgs = nets.preprocess(models, img)

with tf.Session() as sess:
    nets.pretrained(models)
    for (model, img) in zip(models, imgs):
        preds = sess.run(model, {inputs: img})
        print(utils.decode_predictions(preds, top=2)[0])

• 迁移学习：

inputs = tf.placeholder(tf.float32, [None, 224, 224, 3])
outputs = tf.placeholder(tf.float32, [None, 50])
model = nets.DenseNet169(inputs, is_training=True, classes=50)

loss = tf.losses.softmax_cross_entropy(outputs, model.logits)
train = tf.train.AdamOptimizer(learning_rate=1e-5).minimize(loss)

with tf.Session() as sess:
    nets.pretrained(model)
    for (x, y) in your_NumPy_data:  # the NHWC and one-hot format
        sess.run(train, {inputs: x, outputs: y})

• 使用多 GPU：

inputs = tf.placeholder(tf.float32, [None, 224, 224, 3])
models = []

with tf.device('gpu:0'):
    models.append(nets.ResNeXt50(inputs))

with tf.device('gpu:1'):
    models.append(nets.DenseNet201(inputs))

from tensornets.preprocess import fb_preprocess
img = utils.load_img('cat.png', target_size=256, crop_size=224)
img = fb_preprocess(img)

with tf.Session() as sess:
    nets.pretrained(models)
    preds = sess.run(models, {inputs: img})
    for pred in preds:
        print(utils.decode_predictions(pred, top=2)[0])

性能

图像分类

• Top-k 准确率是在 ImageNet 验证集 上使用 TensorNets 测得的，可能与原始结果略有不同。
  • 输入：输入到模型中的图像尺寸
  • Top-1：单中心裁剪，Top-1 准确率
  • Top-5：单中心裁剪，Top-5 准确率
  • MAC：使用 tf.profiler 对浮点运算次数进行四舍五入
  • Size：对参数总数（包括全连接层）进行四舍五入
  • Stem：对参数总数（不包括全连接层）进行四舍五入
• 计算时间是在 NVIDIA Tesla P100（3584 核，16 GB 全局内存）上，使用 cuDNN 6.0 和 CUDA 8.0 测得的。
  • 速度：100 张图像推理所需的时间（毫秒）
• 摘要图由 此脚本 生成。

目标检测

• 目标检测模型可以与任何网络结合使用，但仅能对具有预训练权重的模型计算 mAP。请注意：
  • YOLOv3VOC 是由 taehoonlee 使用 此配置文件 训练的，该配置文件已修改为 max_batches=70000, steps=40000,60000。
  • YOLOv2VOC 等价于 YOLOv2(inputs, Darknet19)。
  • TinyYOLOv2VOC: TinyYOLOv2(inputs, TinyDarknet19)。
  • FasterRCNN_ZF_VOC: FasterRCNN(inputs, ZF)。
  • FasterRCNN_VGG16_VOC: FasterRCNN(inputs, VGG16, stem_out='conv5/3')。
• mAP 值是通过 TensorNets 获得的，可能与原始值略有不同。测试输入尺寸采用论文中报告的最佳数值：
  • YOLOv3、YOLOv2: 416x416
  • FasterRCNN: min_shorter_side=600, max_longer_side=1000
• 计算时间是在 NVIDIA Tesla P100（3584 核，16 GB 全局内存）上测量的，使用 cuDNN 6.0 和 CUDA 8.0。
  • 大小：四舍五入参数数量。
  • 速度：仅针对单张 416x416 或 608x608 图像的网络推理耗时（毫秒）。
  • FPS：1000 / 速度。

新闻 📰

• MobileNetv3 的六种变体发布，2020年3月12日。
• EfficientNet 的八种变体发布，2020年1月28日。
• TensorNets 现已支持 TF 2，2020年1月23日。
• MS COCO 工具发布，2018年7月9日。
• PNASNetlarge 发布，2018年5月12日。
• MobileNetv2 的六种变体发布，2018年5月5日。
• YOLOv3 用于 COCO 和 VOC 的版本发布，2018年4月4日。
• YOLOv2 和 FasterRCNN 的通用目标检测模型发布，2018年3月26日。

未来工作 🔥

• 添加训练代码。
• 添加图像分类模型。
  • PolyNet: 非常深的网络中结构多样性的探索，CVPR 2017，Top-5 4.25%。
  • 挤压与激励网络，CVPR 2018，Top-5 3.79%。
  • GPipe: 使用流水线并行高效训练巨型神经网络，arXiv 2018，Top-5 3.0%。
• 添加目标检测模型（MaskRCNN、SSD）。
• 添加图像分割模型（FCN、UNet）。
• 添加图像数据集（OpenImages）。
• 添加风格迁移示例，这些示例可以与 TensorNets 中的任何网络结合使用。
• 添加语音和语言模型，并配备代表性数据集（WaveNet、ByteNet）。

TensorNets 快速上手指南

TensorNets 是一个基于 TensorFlow 的高级网络定义库，提供带有预训练权重的常用模型。其核心设计理念是函数式接口（而非自定义类），所有模型均直接返回 tf.Tensor，便于无缝集成到现有的机器学习工作流中，同时保持代码的高可读性和可复现性。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.6+
• TensorFlow 版本：支持 1.4.0 至 2.1.0+
  • 若使用 TensorFlow 2.x，需兼容 v1 行为（见下方代码示例）。
• 前置依赖：
  • numpy
  • Pillow (用于图像加载)
  • matplotlib (可选，用于可视化)

安装步骤

你可以通过 PyPI 或 GitHub 直接安装。国内用户建议使用清华源或阿里源加速下载。

方式一：通过 PyPI 安装（推荐）

pip install tensornets -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从 GitHub 源码安装（获取最新版本）

pip install git+https://github.com/taehoonlee/tensornets.git -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

TensorNets 中的每个网络都是一个函数，接收 tf.Tensor 作为输入并返回 tf.Tensor 作为输出。以下以 ResNet50 为例展示最简使用流程。

1. 构建模型与加载图像

import tensorflow as tf
# 如果使用 TF 2.x，请取消下面两行的注释以兼容 v1 行为
# import tensorflow.compat.v1 as tf
# tf.disable_v2_behavior()

import tensornets as nets

# 定义输入占位符 [Batch, Height, Width, Channels]
inputs = tf.placeholder(tf.float32, [None, 224, 224, 3])

# 实例化模型 (直接返回 tf.Tensor)
model = nets.ResNet50(inputs)

# 加载并预处理图像 (返回 NHWC 格式的 numpy 数组)
img = nets.utils.load_img('cat.png', target_size=256, crop_size=224)

2. 运行推理与加载预训练权重

在 Session 中加载预训练权重并进行预测。preprocess() 和 pretrained() 方法确保了结果与原论文一致。

with tf.Session() as sess:
    # 预处理图像以匹配模型要求
    img_processed = model.preprocess(img)
    
    # 加载预训练权重
    sess.run(model.pretrained())
    
    # 执行推理
    preds = sess.run(model, {inputs: img_processed})

# 解码预测结果 (输出概率最高的类别)
print(nets.utils.decode_predictions(preds, top=2)[0])
# 示例输出：[(u'n02124075', u'Egyptian_cat', 0.28...), (u'n02127052', u'lynx', 0.16...)]

3. 提取中间层特征

你可以轻松获取中间层（middles）或所有输出端点（outputs）的张量值，便于迁移学习或特征分析。

with tf.Session() as sess:
    img_processed = model.preprocess(img)
    sess.run(model.pretrained())
    
    # 获取代表性中间层输出
    middles = sess.run(model.middles(), {inputs: img_processed})
    
    # 打印中间层结构信息
    model.print_middles()
    
    # 验证形状 (例如第一个中间层)
    print("First middle layer shape:", middles[0].shape)

4. 保存与加载权重

支持将训练后的权重保存为 .npz 文件以便后续部署。

# 保存权重
with tf.Session() as sess:
    model.init()
    # ... 执行训练过程 ...
    model.save('my_weights.npz')

# 加载权重
with tf.Session() as sess:
    model.load('my_weights.npz')
    # ... 执行部署或推理 ...