注意

单击此处下载完整的示例代码

TorchScript 简介¶

创建于：2019 年 8 月 9 日 | 最后更新：2024 年 12 月 2 日 | 最后验证：2024 年 11 月 5 日

作者： James Reed (jamesreed@fb.com), Michael Suo (suo@fb.com), rev2

警告

TorchScript 不再处于积极开发阶段。

本教程是 TorchScript 的简介，TorchScript 是 PyTorch 模型（nn.Module 的子类）的中间表示，然后可以在 C++ 等高性能环境中运行。

在本教程中，我们将介绍

在 PyTorch 中编写模型的基础知识，包括

模块
定义 forward 函数
将模块组合成模块层次结构

将 PyTorch 模块转换为 TorchScript（我们的高性能部署运行时）的特定方法

跟踪现有模块
使用脚本直接编译模块
如何组合这两种方法
保存和加载 TorchScript 模块

我们希望您在完成本教程后，继续学习后续教程，该教程将引导您完成从 C++ 实际调用 TorchScript 模型的示例。

import torch  # This is all you need to use both PyTorch and TorchScript!
print(torch.__version__)
torch.manual_seed(191009)  # set the seed for reproducibility

2.6.0+cu124

<torch._C.Generator object at 0x7fd64938a3d0>

PyTorch 模型编写基础知识¶

让我们从定义一个简单的 Module 开始。Module 是 PyTorch 中组合的基本单元。它包含

构造函数，用于准备模块以进行调用
一组 Parameters 和子 Modules。这些由构造函数初始化，并且可以在模块调用期间使用。
forward 函数。这是在调用模块时运行的代码。

让我们来看一个小例子

class MyCell(torch.nn.Module):
    def __init__(self):
        super(MyCell, self).__init__()

    def forward(self, x, h):
        new_h = torch.tanh(x + h)
        return new_h, new_h

my_cell = MyCell()
x = torch.rand(3, 4)
h = torch.rand(3, 4)
print(my_cell(x, h))

(tensor([[0.8219, 0.8990, 0.6670, 0.8277],
        [0.5176, 0.4017, 0.8545, 0.7336],
        [0.6013, 0.6992, 0.2618, 0.6668]]), tensor([[0.8219, 0.8990, 0.6670, 0.8277],
        [0.5176, 0.4017, 0.8545, 0.7336],
        [0.6013, 0.6992, 0.2618, 0.6668]]))

所以我们已经

创建了一个继承 torch.nn.Module 的类。
定义了一个构造函数。构造函数没有做太多事情，只是调用了 super 的构造函数。
定义了一个 forward 函数，它接受两个输入并返回两个输出。forward 函数的实际内容并不是很重要，但它有点像一个假的 RNN 单元——也就是说——它是一个在循环中应用的函数。

我们实例化了模块，并创建了 x 和 h，它们只是 3x4 的随机值矩阵。然后我们使用 my_cell(x, h) 调用了单元。这反过来又调用了我们的 forward 函数。

让我们做一些更有趣的事情

class MyCell(torch.nn.Module):
    def __init__(self):
        super(MyCell, self).__init__()
        self.linear = torch.nn.Linear(4, 4)

    def forward(self, x, h):
        new_h = torch.tanh(self.linear(x) + h)
        return new_h, new_h

my_cell = MyCell()
print(my_cell)
print(my_cell(x, h))

MyCell(
  (linear): Linear(in_features=4, out_features=4, bias=True)
)
(tensor([[ 0.8573,  0.6190,  0.5774,  0.7869],
        [ 0.3326,  0.0530,  0.0702,  0.8114],
        [ 0.7818, -0.0506,  0.4039,  0.7967]], grad_fn=<TanhBackward0>), tensor([[ 0.8573,  0.6190,  0.5774,  0.7869],
        [ 0.3326,  0.0530,  0.0702,  0.8114],
        [ 0.7818, -0.0506,  0.4039,  0.7967]], grad_fn=<TanhBackward0>))

我们重新定义了我们的模块 MyCell，但这次我们添加了一个 self.linear 属性，并在 forward 函数中调用了 self.linear。

这里到底发生了什么？torch.nn.Linear 是 PyTorch 标准库中的一个 Module。就像 MyCell 一样，可以使用调用语法来调用它。我们正在构建 Module 的层次结构。

print 在 Module 上会给出 Module 的子类层次结构的可视化表示。在我们的示例中，我们可以看到我们的 Linear 子类及其参数。

通过以这种方式组合 Module，我们可以简洁明了地编写具有可重用组件的模型。

您可能已经注意到输出上的 grad_fn。这是 PyTorch 的自动微分方法（称为 autograd）的详细信息。简而言之，此系统允许我们计算通过可能复杂的程序的导数。该设计允许在模型编写方面具有极大的灵活性。

现在让我们检查一下这种灵活性

class MyDecisionGate(torch.nn.Module):
    def forward(self, x):
        if x.sum() > 0:
            return x
        else:
            return -x

class MyCell(torch.nn.Module):
    def __init__(self):
        super(MyCell, self).__init__()
        self.dg = MyDecisionGate()
        self.linear = torch.nn.Linear(4, 4)

    def forward(self, x, h):
        new_h = torch.tanh(self.dg(self.linear(x)) + h)
        return new_h, new_h

my_cell = MyCell()
print(my_cell)
print(my_cell(x, h))

MyCell(
  (dg): MyDecisionGate()
  (linear): Linear(in_features=4, out_features=4, bias=True)
)
(tensor([[ 0.8346,  0.5931,  0.2097,  0.8232],
        [ 0.2340, -0.1254,  0.2679,  0.8064],
        [ 0.6231,  0.1494, -0.3110,  0.7865]], grad_fn=<TanhBackward0>), tensor([[ 0.8346,  0.5931,  0.2097,  0.8232],
        [ 0.2340, -0.1254,  0.2679,  0.8064],
        [ 0.6231,  0.1494, -0.3110,  0.7865]], grad_fn=<TanhBackward0>))

我们再次重新定义了我们的 MyCell 类，但在这里我们定义了 MyDecisionGate。此模块利用控制流。控制流包括循环和 if 语句等内容。

许多框架采用的方法是给定完整的程序表示来计算符号导数。但是，在 PyTorch 中，我们使用梯度带。我们在操作发生时记录操作，并在计算导数时向后重放它们。通过这种方式，框架不必为语言中的所有构造显式定义导数。

autograd 的工作原理¶

TorchScript 基础知识¶

现在让我们以我们正在运行的示例为例，看看如何应用 TorchScript。

简而言之，即使在 PyTorch 的灵活和动态性质下，TorchScript 也提供了捕获模型定义的工具。让我们首先检查一下我们所说的跟踪。

跟踪 `Modules`¶

class MyCell(torch.nn.Module):
    def __init__(self):
        super(MyCell, self).__init__()
        self.linear = torch.nn.Linear(4, 4)

    def forward(self, x, h):
        new_h = torch.tanh(self.linear(x) + h)
        return new_h, new_h

my_cell = MyCell()
x, h = torch.rand(3, 4), torch.rand(3, 4)
traced_cell = torch.jit.trace(my_cell, (x, h))
print(traced_cell)
traced_cell(x, h)

MyCell(
  original_name=MyCell
  (linear): Linear(original_name=Linear)
)

(tensor([[-0.2541,  0.2460,  0.2297,  0.1014],
        [-0.2329, -0.2911,  0.5641,  0.5015],
        [ 0.1688,  0.2252,  0.7251,  0.2530]], grad_fn=<TanhBackward0>), tensor([[-0.2541,  0.2460,  0.2297,  0.1014],
        [-0.2329, -0.2911,  0.5641,  0.5015],
        [ 0.1688,  0.2252,  0.7251,  0.2530]], grad_fn=<TanhBackward0>))

我们稍微倒退了一下，采用了我们 MyCell 类的第二个版本。与之前一样，我们实例化了它，但这次，我们调用了 torch.jit.trace，传入了 Module，并传入了网络可能看到的示例输入。

这到底做了什么？它调用了 Module，记录了 Module 运行时发生的操作，并创建了 torch.jit.ScriptModule 的实例（其中 TracedModule 是一个实例）

TorchScript 将其定义记录在中间表示 (IR) 中，在深度学习中通常称为图。我们可以使用 .graph 属性检查图

print(traced_cell.graph)

graph(%self.1 : __torch__.MyCell,
      %x : Float(3, 4, strides=[4, 1], requires_grad=0, device=cpu),
      %h : Float(3, 4, strides=[4, 1], requires_grad=0, device=cpu)):
  %linear : __torch__.torch.nn.modules.linear.Linear = prim::GetAttr[name="linear"](%self.1)
  %20 : Tensor = prim::CallMethod[name="forward"](%linear, %x)
  %11 : int = prim::Constant[value=1]() # /var/lib/workspace/beginner_source/Intro_to_TorchScript_tutorial.py:191:0
  %12 : Float(3, 4, strides=[4, 1], requires_grad=1, device=cpu) = aten::add(%20, %h, %11) # /var/lib/workspace/beginner_source/Intro_to_TorchScript_tutorial.py:191:0
  %13 : Float(3, 4, strides=[4, 1], requires_grad=1, device=cpu) = aten::tanh(%12) # /var/lib/workspace/beginner_source/Intro_to_TorchScript_tutorial.py:191:0
  %14 : (Float(3, 4, strides=[4, 1], requires_grad=1, device=cpu), Float(3, 4, strides=[4, 1], requires_grad=1, device=cpu)) = prim::TupleConstruct(%13, %13)
  return (%14)

但是，这是一个非常低级的表示，并且图中包含的大部分信息对于最终用户来说没有用处。相反，我们可以使用 .code 属性来给出代码的 Python 语法解释

print(traced_cell.code)

def forward(self,
    x: Tensor,
    h: Tensor) -> Tuple[Tensor, Tensor]:
  linear = self.linear
  _0 = torch.tanh(torch.add((linear).forward(x, ), h))
  return (_0, _0)

那么，为什么我们要做这一切？有几个原因

TorchScript 代码可以在其自己的解释器中调用，该解释器基本上是一个受限的 Python 解释器。此解释器不获取全局解释器锁，因此可以在同一实例上同时处理多个请求。
这种格式允许我们将整个模型保存到磁盘并将其加载到另一个环境中，例如用 Python 以外的语言编写的服务器中
TorchScript 为我们提供了一种表示形式，我们可以在其中对代码进行编译器优化，以提供更高效的执行
TorchScript 允许我们与许多后端/设备运行时接口，这些运行时需要比单个运算符更广泛的程序视图。

我们可以看到，调用 traced_cell 产生的结果与 Python 模块相同

print(my_cell(x, h))
print(traced_cell(x, h))

(tensor([[-0.2541,  0.2460,  0.2297,  0.1014],
        [-0.2329, -0.2911,  0.5641,  0.5015],
        [ 0.1688,  0.2252,  0.7251,  0.2530]], grad_fn=<TanhBackward0>), tensor([[-0.2541,  0.2460,  0.2297,  0.1014],
        [-0.2329, -0.2911,  0.5641,  0.5015],
        [ 0.1688,  0.2252,  0.7251,  0.2530]], grad_fn=<TanhBackward0>))
(tensor([[-0.2541,  0.2460,  0.2297,  0.1014],
        [-0.2329, -0.2911,  0.5641,  0.5015],
        [ 0.1688,  0.2252,  0.7251,  0.2530]], grad_fn=<TanhBackward0>), tensor([[-0.2541,  0.2460,  0.2297,  0.1014],
        [-0.2329, -0.2911,  0.5641,  0.5015],
        [ 0.1688,  0.2252,  0.7251,  0.2530]], grad_fn=<TanhBackward0>))

使用脚本转换模块¶

我们使用模块的第二个版本而不是带有控制流子模块的版本是有原因的。现在让我们检查一下

class MyDecisionGate(torch.nn.Module):
    def forward(self, x):
        if x.sum() > 0:
            return x
        else:
            return -x

class MyCell(torch.nn.Module):
    def __init__(self, dg):
        super(MyCell, self).__init__()
        self.dg = dg
        self.linear = torch.nn.Linear(4, 4)

    def forward(self, x, h):
        new_h = torch.tanh(self.dg(self.linear(x)) + h)
        return new_h, new_h

my_cell = MyCell(MyDecisionGate())
traced_cell = torch.jit.trace(my_cell, (x, h))

print(traced_cell.dg.code)
print(traced_cell.code)

/var/lib/workspace/beginner_source/Intro_to_TorchScript_tutorial.py:263: TracerWarning:

Converting a tensor to a Python boolean might cause the trace to be incorrect. We can't record the data flow of Python values, so this value will be treated as a constant in the future. This means that the trace might not generalize to other inputs!

def forward(self,
    argument_1: Tensor) -> NoneType:
  return None

def forward(self,
    x: Tensor,
    h: Tensor) -> Tuple[Tensor, Tensor]:
  dg = self.dg
  linear = self.linear
  _0 = (linear).forward(x, )
  _1 = (dg).forward(_0, )
  _2 = torch.tanh(torch.add(_0, h))
  return (_2, _2)

查看 .code 输出，我们可以看到 if-else 分支无处可寻！为什么？跟踪完全按照我们所说的去做：运行代码，记录发生的操作，并构造一个 ScriptModule 来执行完全相同的操作。不幸的是，控制流之类的内容被擦除了。

我们如何才能在 TorchScript 中忠实地表示此模块？我们提供了一个脚本编译器，它直接分析您的 Python 源代码，将其转换为 TorchScript。让我们使用脚本编译器转换 MyDecisionGate

scripted_gate = torch.jit.script(MyDecisionGate())

my_cell = MyCell(scripted_gate)
scripted_cell = torch.jit.script(my_cell)

print(scripted_gate.code)
print(scripted_cell.code)

def forward(self,
    x: Tensor) -> Tensor:
  if bool(torch.gt(torch.sum(x), 0)):
    _0 = x
  else:
    _0 = torch.neg(x)
  return _0

def forward(self,
    x: Tensor,
    h: Tensor) -> Tuple[Tensor, Tensor]:
  dg = self.dg
  linear = self.linear
  _0 = torch.add((dg).forward((linear).forward(x, ), ), h)
  new_h = torch.tanh(_0)
  return (new_h, new_h)

万岁！我们现在已经在 TorchScript 中忠实地捕获了我们程序的行为。现在让我们尝试运行该程序

# New inputs
x, h = torch.rand(3, 4), torch.rand(3, 4)
print(scripted_cell(x, h))

(tensor([[ 0.5679,  0.5762,  0.2506, -0.0734],
        [ 0.5228,  0.7122,  0.6985, -0.0656],
        [ 0.6187,  0.4487,  0.7456, -0.0238]], grad_fn=<TanhBackward0>), tensor([[ 0.5679,  0.5762,  0.2506, -0.0734],
        [ 0.5228,  0.7122,  0.6985, -0.0656],
        [ 0.6187,  0.4487,  0.7456, -0.0238]], grad_fn=<TanhBackward0>))

混合脚本和跟踪¶

某些情况需要使用跟踪而不是脚本（例如，模块有许多架构决策是基于我们不希望出现在 TorchScript 中的常量 Python 值做出的）。在这种情况下，脚本可以与跟踪结合使用：torch.jit.script 将内联跟踪模块的代码，而跟踪将内联脚本模块的代码。

第一个案例的示例

class MyRNNLoop(torch.nn.Module):
    def __init__(self):
        super(MyRNNLoop, self).__init__()
        self.cell = torch.jit.trace(MyCell(scripted_gate), (x, h))

    def forward(self, xs):
        h, y = torch.zeros(3, 4), torch.zeros(3, 4)
        for i in range(xs.size(0)):
            y, h = self.cell(xs[i], h)
        return y, h

rnn_loop = torch.jit.script(MyRNNLoop())
print(rnn_loop.code)

def forward(self,
    xs: Tensor) -> Tuple[Tensor, Tensor]:
  h = torch.zeros([3, 4])
  y = torch.zeros([3, 4])
  y0 = y
  h0 = h
  for i in range(torch.size(xs, 0)):
    cell = self.cell
    _0 = (cell).forward(torch.select(xs, 0, i), h0, )
    y1, h1, = _0
    y0, h0 = y1, h1
  return (y0, h0)

第二个案例的示例

class WrapRNN(torch.nn.Module):
    def __init__(self):
        super(WrapRNN, self).__init__()
        self.loop = torch.jit.script(MyRNNLoop())

    def forward(self, xs):
        y, h = self.loop(xs)
        return torch.relu(y)

traced = torch.jit.trace(WrapRNN(), (torch.rand(10, 3, 4)))
print(traced.code)

def forward(self,
    xs: Tensor) -> Tensor:
  loop = self.loop
  _0, y, = (loop).forward(xs, )
  return torch.relu(y)

这样，脚本和跟踪可以在需要它们的情况中使用，也可以一起使用。

保存和加载模型¶

我们提供了 API，用于以存档格式将 TorchScript 模块保存到磁盘/从磁盘加载。此格式包括代码、参数、属性和调试信息，这意味着该存档是模型的独立表示，可以在完全独立的进程中加载。让我们保存并加载我们包装的 RNN 模块

traced.save('wrapped_rnn.pt')

loaded = torch.jit.load('wrapped_rnn.pt')

print(loaded)
print(loaded.code)

RecursiveScriptModule(
  original_name=WrapRNN
  (loop): RecursiveScriptModule(
    original_name=MyRNNLoop
    (cell): RecursiveScriptModule(
      original_name=MyCell
      (dg): RecursiveScriptModule(original_name=MyDecisionGate)
      (linear): RecursiveScriptModule(original_name=Linear)
    )
  )
)
def forward(self,
    xs: Tensor) -> Tensor:
  loop = self.loop
  _0, y, = (loop).forward(xs, )
  return torch.relu(y)

如您所见，序列化保留了模块层次结构和我们一直在检查的代码。例如，该模型也可以加载到 C++ 中以进行无 Python 执行。

进一步阅读¶

我们已经完成了我们的教程！有关更深入的演示，请查看 NeurIPS 演示，了解如何使用 TorchScript 转换机器翻译模型：https://colab.research.google.com/drive/1HiICg6jRkBnr5hvK2-VnMi88Vi9pUzEJ

脚本的总运行时间：（0 分 0.217 秒）

由 Sphinx-Gallery 生成的图库

TorchScript 简介¶

PyTorch 模型编写基础知识¶

TorchScript 基础知识¶

跟踪 `Modules`¶

使用脚本转换模块¶

混合脚本和跟踪¶

保存和加载模型¶

进一步阅读¶

文档

教程

资源

TorchScript 简介¶

PyTorch 模型编写基础知识¶

TorchScript 基础知识¶

跟踪 Modules¶

使用脚本转换模块¶

混合脚本和跟踪¶

保存和加载模型¶

进一步阅读¶

文档

教程

资源

跟踪 `Modules`¶