# 自动差分包-Torch.Autograd

> 原文： [https://pytorch.org/docs/stable/autograd.html](https://pytorch.org/docs/stable/autograd.html)

`torch.autograd`提供了实现自动区分任意标量值函数的类和函数。 它需要对现有代码进行最小的更改-您只需要声明`Tensor`，应使用`requires_grad=True`关键字为其计算梯度。

* * *

```
torch.autograd.backward(tensors, grad_tensors=None, retain_graph=None, create_graph=False, grad_variables=None)¶
```

计算给定张量的梯度总和 w.r.t. 图叶。

该图使用链规则进行区分。 如果`tensors`中的任何一个都是非标量的(即，其数据具有多个元素）并且需要梯度，则将计算雅可比矢量积，在这种情况下，该函数还需要指定`grad_tensors`。 它应该是长度匹配的序列，其中包含雅可比向量积中的“向量”，通常是微分函数 w.r.t 的梯度。 相应的张量(对于不需要梯度张量的所有张量，`None`是可接受的值）。

此函数在树叶中累积渐变-调用它之前可能需要将它们归零。

参数

*   **张量**(张量的_序列）–将计算其导数的张量。_

*   **grad_tensors**  (_(_ [_tensor_](tensors.html#torch.Tensor "torch.Tensor") _或_ _无_的_序列 _）_）–雅可比向量积中的“向量”，通常是梯度 wrt 相应张量的每个元素。 无法为标量张量或不需要等级的张量指定任何值。 如果所有 grad_tensor 都可接受 None 值，则此参数是可选的。_

*   **keep_graph**  (_bool_ _，_ _可选_）–如果`False`，则用于计算等级的图形将被释放。 请注意，几乎在所有情况下都不需要将此选项设置为`True`，并且通常可以以更有效的方式解决它。 默认为`create_graph`的值。

*   **create_graph**  (_bool_ _，_ _可选_）–如果`True`，则将构造导数图，从而允许计算高阶导数 产品。 默认为`False`。

* * *

```
torch.autograd.grad(outputs, inputs, grad_outputs=None, retain_graph=None, create_graph=False, only_inputs=True, allow_unused=False)¶
```

计算并返回输出 w.r.t 的梯度总和。 输入。

`grad_outputs`应该是长度匹配的序列`output`，其中包含 Jacobian 向量积中的“向量”，通常是预先计算的梯度 w.r.t。 每个输出。 如果输出不是 require_grad，则渐变可以为`None`。

如果`only_inputs`为`True`，则该函数将仅返回指定输入的渐变列表。 如果是`False`，则渐变 w.r.t. 所有剩余的叶子仍将被计算，并将被累积到其`.grad`属性中。

Parameters

*   **输出**(张量的_序列）–微分功能的输出。_

*   **输入**(张量的_序列）–输入 w.r.t. 梯度将被返回(而不是累积到`.grad`中）。_

*   **grad_outputs** (张量的_序列）–雅可比向量积中的“向量”。 通常是渐变色 每个输出。 无法为标量张量或不需要等级的张量指定任何值。 如果所有 grad_tensor 都可接受 None 值，则此参数是可选的。 默认值：无。_

*   **retain_graph** (_bool__,_ _optional_) – If `False`, the graph used to compute the grad will be freed. Note that in nearly all cases setting this option to `True` is not needed and often can be worked around in a much more efficient way. Defaults to the value of `create_graph`.

*   **create_graph**  (_bool_ _，_ _可选_）–如果`True`，则将构造导数图，从而允许计算高阶导数 产品。 默认值：`False`。

*   **allow_unused**  (_bool_ _，_ _可选_）–如果为`False`，则指定在计算输出时未使用的输入(及其等级） 始终为零）是错误。 默认为`False`。

## 局部禁用梯度计算

* * *

```
class torch.autograd.no_grad¶
```

禁用梯度计算的上下文管理器。

当您确定不会调用`Tensor.backward()`时，禁用梯度计算对于推断很有用。 它将减少用于具有 &lt;cite&gt;require_grad = True&lt;/cite&gt; 的计算的内存消耗。

在这种模式下，即使输入具有 &lt;cite&gt;require_grad = True&lt;/cite&gt; ，每个计算的结果也将具有 &lt;cite&gt;require_grad = False&lt;/cite&gt; 。

使用 [`enable_grad`](#torch.autograd.enable_grad "torch.autograd.enable_grad") 上下文管理器时，此模式无效。

该上下文管理器是线程本地的； 它不会影响其他线程中的计算。

还用作装饰器。

例：

```
>>> x = torch.tensor([1], requires_grad=True)
>>> with torch.no_grad():
...   y = x * 2
>>> y.requires_grad
False
>>> @torch.no_grad()
... def doubler(x):
...     return x * 2
>>> z = doubler(x)
>>> z.requires_grad
False

```

* * *

```
class torch.autograd.enable_grad¶
```

启用梯度计算的上下文管理器。

如果已通过 [`no_grad`](#torch.autograd.no_grad "torch.autograd.no_grad") 或 [`set_grad_enabled`](#torch.autograd.set_grad_enabled "torch.autograd.set_grad_enabled") 禁用了梯度计算，则启用梯度计算。

This context manager is thread local; it will not affect computation in other threads.

Also functions as a decorator.

Example:

```
>>> x = torch.tensor([1], requires_grad=True)
>>> with torch.no_grad():
...   with torch.enable_grad():
...     y = x * 2
>>> y.requires_grad
True
>>> y.backward()
>>> x.grad
>>> @torch.enable_grad()
... def doubler(x):
...     return x * 2
>>> with torch.no_grad():
...     z = doubler(x)
>>> z.requires_grad
True

```

* * *

```
class torch.autograd.set_grad_enabled(mode)¶
```

将渐变计算设置为开或关的上下文管理器。

`set_grad_enabled`将根据其参数`mode`启用或禁用 grads。 它可以用作上下文管理器或功能。

使用 [`enable_grad`](#torch.autograd.enable_grad "torch.autograd.enable_grad") 上下文管理器时，`set_grad_enabled(False)`不起作用。

This context manager is thread local; it will not affect computation in other threads.

Parameters

**模式** (_bool_ )–标记是启用 Grad(`True`）还是禁用(`False`）。 这可用于有条件地启用渐变。

Example:

```
>>> x = torch.tensor([1], requires_grad=True)
>>> is_train = False
>>> with torch.set_grad_enabled(is_train):
...   y = x * 2
>>> y.requires_grad
False
>>> torch.set_grad_enabled(True)
>>> y = x * 2
>>> y.requires_grad
True
>>> torch.set_grad_enabled(False)
>>> y = x * 2
>>> y.requires_grad
False

```

## 张量的就地操作

在 autograd 中支持就地操作很困难，并且在大多数情况下，我们不鼓励使用它们。 Autograd 积极的缓冲区释放和重用使其非常高效，就地操作实际上很少显着降低内存使用量的情况很少。 除非您在高内存压力下进行操作，否则可能永远不需要使用它们。

### 就地正确性检查

所有`Tensor`都跟踪对其应用的就地操作，并且如果实现检测到在其中一个函数中保存了一个张量以用于后退，但此后对其进行了修改，则一旦向后进行修改，就会引发错误 通行证开始。 这样可以确保，如果您使用的是就地函数并且没有看到任何错误，则可以确保计算出的梯度是正确的。

## 变量(不建议使用）

警告

不推荐使用 Variable API：不再需要将变量用于带有张量的 autograd。 Autograd 自动将`requires_grad`设置为`True`的张量。 请在下面找到有关更改的快速指南：

*   `Variable(tensor)`和`Variable(tensor, requires_grad)`仍能按预期工作，但是它们返回张量而不是变量。

*   `var.data`与`tensor.data`相同。

*   现在，诸如`var.backward(), var.detach(), var.register_hook()`之类的方法可以在具有相同方法名称的张量上使用。

此外，现在可以使用 [`torch.randn()`](torch.html#torch.randn "torch.randn") ， [`torch.zeros()`](torch.html#torch.zeros "torch.zeros") ， [`torch.ones()`](torch.html#torch.ones "torch.ones") 等工厂方法使用`requires_grad=True`创建张量 下列：

`autograd_tensor = torch.randn((2, 3, 4), requires_grad=True)`

## 张量自动分级功能

* * *

```
class torch.Tensor
```

```
grad¶
```

此属性默认为`None`，并在首次调用 [`backward()`](#torch.Tensor.backward "torch.Tensor.backward") 计算`self`的梯度时成为张量。 然后，该属性将包含计算出的梯度，将来对 [`backward()`](#torch.Tensor.backward "torch.Tensor.backward") 的调用将在其中累积(添加）梯度。

```
requires_grad¶
```

如果需要为此张量计算梯度，则为`True`，否则为`False`。

注意

需要为张量计算梯度的事实并不意味着将填充 [`grad`](#torch.Tensor.grad "torch.Tensor.grad") 属性，有关更多详细信息，请参见 [`is_leaf`](#torch.Tensor.is_leaf "torch.Tensor.is_leaf") 。

```
is_leaf¶
```

按照惯例，所有具有 [`requires_grad`](#torch.Tensor.requires_grad "torch.Tensor.requires_grad") 即`False`的张量将是叶张量。

对于具有 [`requires_grad`](#torch.Tensor.requires_grad "torch.Tensor.requires_grad") (即`True`）的张量，如果它们是由用户创建的，则它们将是叶张量。 这意味着它们不是运算的结果，因此`grad_fn`为“无”。

在调用 [`backward()`](#torch.Tensor.backward "torch.Tensor.backward") 期间，仅叶子张量会填充其 [`grad`](#torch.Tensor.grad "torch.Tensor.grad") 。 要为非叶张量填充 [`grad`](#torch.Tensor.grad "torch.Tensor.grad") ，可以使用 [`retain_grad()`](#torch.Tensor.retain_grad "torch.Tensor.retain_grad") 。

Example:

```
>>> a = torch.rand(10, requires_grad=True)
>>> a.is_leaf
True
>>> b = torch.rand(10, requires_grad=True).cuda()
>>> b.is_leaf
False
# b was created by the operation that cast a cpu Tensor into a cuda Tensor
>>> c = torch.rand(10, requires_grad=True) + 2
>>> c.is_leaf
False
# c was created by the addition operation
>>> d = torch.rand(10).cuda()
>>> d.is_leaf
True
# d does not require gradients and so has no operation creating it (that is tracked by the autograd engine)
>>> e = torch.rand(10).cuda().requires_grad_()
>>> e.is_leaf
True
# e requires gradients and has no operations creating it
>>> f = torch.rand(10, requires_grad=True, device="cuda")
>>> f.is_leaf
True
# f requires grad, has no operation creating it

```

* * *

```
backward(gradient=None, retain_graph=None, create_graph=False)¶
```

计算电流张量 w.r.t. 图叶。

该图使用链规则进行区分。 如果张量是非标量的(即其数据具有多个元素）并且需要梯度，则该函数还需要指定`gradient`。 它应该是匹配类型和位置的张量，其中包含微分函数 w.r.t 的梯度。 `self`。

此函数在树叶中累积渐变-调用它之前可能需要将它们归零。

Parameters

*   **梯度** ([_tensor_](tensors.html#torch.Tensor "torch.Tensor") _或_ _无_）–梯度 w.r.t. 张量。 如果它是张量，除非`create_graph`为 True，否则它将自动转换为不需要 grad 的张量。 无法为标量张量或不需要等级的张量指定任何值。 如果 None 值可以接受，那么此参数是可选的。

*   **keep_graph**  (_bool_ _，_ _可选_）–如果`False`，则用于计算等级的图形将被释放。 请注意，几乎在所有情况下都不需要将此选项设置为 True，并且通常可以以更有效的方式解决它。 默认为`create_graph`的值。

*   **create_graph**  (_bool_ _，_ _可选_）–如果`True`，则将构造导数图，从而允许计算高阶导数 产品。 默认为`False`。

* * *

```
detach()¶
```

返回与当前图形分离的新 Tensor。

结果将永远不需要渐变。

Note

返回的 Tensor 与原始 Tensor 共享相同的存储。 可以看到对它们中的任何一个的就地修改，并且可能触发正确性检查中的错误。 重要说明：以前，就地大小/步幅/存储更改(例如 &lt;cite&gt;resize_&lt;/cite&gt; / &lt;cite&gt;resize_as_&lt;/cite&gt; / &lt;cite&gt;set_&lt;/cite&gt; / &lt;cite&gt;transpose_&lt;/cite&gt; ) 返回的张量也会更新原始张量。 现在，这些就地更改将不再更新原始张量，而将触发错误。 对于稀疏张量：原位索引/值更改(例如 &lt;cite&gt;zero_&lt;/cite&gt; / &lt;cite&gt;copy_&lt;/cite&gt; / &lt;cite&gt;add_&lt;/cite&gt; )将不会再更新原始张量， 而是触发错误。

* * *

```
detach_()¶
```

从创建它的图形中分离张量，使其成为一片叶子。 视图不能就地分离。

* * *

```
register_hook(hook)¶
```

注册一个倒钩。

每当计算相对于张量的梯度时，都会调用该挂钩。 挂钩应具有以下签名：

```
hook(grad) -> Tensor or None

```

挂钩不应修改其自变量，但可以选择返回一个新的渐变，该渐变将代替 [`grad`](#torch.Tensor.grad "torch.Tensor.grad") 使用。

此函数返回带有方法`handle.remove()`的句柄，该方法可将钩子从模块中移除。

Example:

```
>>> v = torch.tensor([0., 0., 0.], requires_grad=True)
>>> h = v.register_hook(lambda grad: grad * 2)  # double the gradient
>>> v.backward(torch.tensor([1., 2., 3.]))
>>> v.grad

 2
 4
 6
[torch.FloatTensor of size (3,)]

>>> h.remove()  # removes the hook

```

* * *

```
retain_grad()¶
```

为非叶张量启用.grad 属性。

## 功能

* * *

```
class torch.autograd.Function¶
```

记录操作历史并定义用于区分操作的公式。

在`Tensor`上执行的每个操作都会创建一个新的函数对象，该对象执行计算并记录其发生。 历史记录以 DAG 函数的形式保留，其边缘表示数据依赖性(`input &lt;- output`）。 然后，当调用向后时，通过调用每个 [`Function`](#torch.autograd.Function "torch.autograd.Function") 对象的 [`backward()`](#torch.autograd.backward "torch.autograd.backward") 方法，并将返回的梯度传递到下一个[，以拓扑顺序处理图形 ] `Function`](#torch.autograd.Function "torch.autograd.Function") s。

通常，用户与函数交互的唯一方法是创建子类并定义新操作。 这是扩展 torch.autograd 的推荐方法。

每个功能对象只能使用一次(在向前传递中）。

例子：

```
>>> class Exp(Function):
>>>
>>>     @staticmethod
>>>     def forward(ctx, i):
>>>         result = i.exp()
>>>         ctx.save_for_backward(result)
>>>         return result
>>>
>>>     @staticmethod
>>>     def backward(ctx, grad_output):
>>>         result, = ctx.saved_tensors
>>>         return grad_output * result

```

* * *

```
static backward(ctx, *grad_outputs)¶
```

定义用于区分操作的公式。

该功能将被所有子类覆盖。

它必须接受上下文`ctx`作为第一个参数，然后返回 [`forward()`](#torch.autograd.Function.forward "torch.autograd.Function.forward") 返回的输出数量，并且它应该返回与 [`forward()`的输入一样多的张量[](#torch.autograd.Function.forward "torch.autograd.Function.forward") 。 每个参数都是给定输出的梯度 w.r.t，每个返回值都应该是梯度 w.r.t。 相应的输入。

上下文可用于检索在前向传递过程中保存的张量。 它还具有属性`ctx.needs_input_grad`，它是一个布尔元组，表示每个输入是否需要渐变。 例如，如果 [`forward()`](#torch.autograd.Function.forward "torch.autograd.Function.forward") 的第一个输入需要进行 w.r.t.的梯度计算，则 [`backward()`](#torch.autograd.backward "torch.autograd.backward") 将具有`ctx.needs_input_grad[0] = True`。 输出。

* * *

```
static forward(ctx, *args, **kwargs)¶
```

执行操作。

This function is to be overridden by all subclasses.

它必须接受上下文 ctx 作为第一个参数，后跟任意数量的参数(张量或其他类型）。

上下文可用于存储张量，然后可以在向后传递过程中检索这些张量。

## 上下文方法混合

创建新的 [`Function`](#torch.autograd.Function "torch.autograd.Function") 时， &lt;cite&gt;ctx&lt;/cite&gt; 可使用以下方法。

* * *

```
class torch.autograd.function._ContextMethodMixin¶
```

* * *

```
mark_dirty(*args)¶
```

将给定张量标记为在就地操作中已修改。

**仅应从** `forward()` **方法内部调用一次，并且所有自变量均应为输入。**

在调用`forward()`时在原位修改的每个张量都应提供给此函数，以确保检查的正确性。 在修改之前或之后调用该函数都没有关系。

* * *

```
mark_non_differentiable(*args)¶
```

将输出标记为不可微分。

**仅应从** `forward()` **方法内部调用一次，并且所有自变量均应为输出。**

这会将输出标记为不需要梯度，从而提高了向后计算的效率。 您仍然需要为`backward()`中的每个输出接受一个渐变，但是它始终将是零张量，其形状与相应输出的形状相同。

例如使用 用于从最大值`Function`返回的索引。

* * *

```
save_for_backward(*tensors)¶
```

保存给定的张量以供将来调用`backward()`。

**最多只能调用一次，并且只能从** `forward()` **方法内部调用。**

以后，可以通过`saved_tensors`属性访问已保存的张量。 在将它们退还给用户之前，应进行检查以确保未在修改其内容的任何就地操作中使用它们。

参数也可以是`None`。

## 数值梯度检查

* * *

```
torch.autograd.gradcheck(func, inputs, eps=1e-06, atol=1e-05, rtol=0.001, raise_exception=True, check_sparse_nnz=False, nondet_tol=0.0)¶
```

检查相对于分析梯度 w.r.t 的小有限差分计算出的梯度。 `inputs`中的浮点类型为`requires_grad=True`的张量。

在数值梯度和解析梯度之间的检查使用 [`allclose()`](torch.html#torch.allclose "torch.allclose") 。

Note

默认值是为双精度的`input`设计的。 如果`input`的精度较低，例如`FloatTensor`，则此检查可能会失败。

Warning

如果`input`中的任何已检查张量具有重叠的内存，即，不同的索引指向相同的内存地址(例如，来自`torch.expand()`的索引），则此检查可能会失败，因为在这些索引处通过点扰动计算出的数值梯度将改变值 共享相同内存地址的所有其他索引。

Parameters

*   **函数**(_函数_）–一个 Python 函数，接受 Tensor 输入并返回 Tensor 或 Tensors 元组

*   **输入**(张量 _或_ [_tensor_](tensors.html#torch.Tensor "torch.Tensor") 的元组）–该功能的输入

*   **eps**  (_python：float_ _，_ _可选_）–有限差分摄动

*   **atol**  (_python：float_ _，_ _可选_）–绝对公差

*   **rtol**  (_python：float_ _，_ _可选_）–相对公差

*   **raise_exception**  (_bool_ _，_ _可选_）–指示如果检查失败，是否引发异常。 该异常提供有关故障确切性质的更多信息。 这在调试 gradchecks 时很有用。

*   **check_sparse_nnz**  (_bool_ _，_ _可选_）–如果为 True，则 gradcheck 允许输入 SparseTensor，对于输入的任何 SparseTensor，gradcheck 将执行 仅在 nnz 位置检查。

*   **nondet_tol**  (_python：float_ _，_ _可选_）–对不确定性的容忍度。 通过微分运行相同的输入时，结果必须完全匹配(默认值为 0.0）或在此公差范围内。

退货

如果所有差异均满足全封闭条件，则为真

* * *

```
torch.autograd.gradgradcheck(func, inputs, grad_outputs=None, eps=1e-06, atol=1e-05, rtol=0.001, gen_non_contig_grad_outputs=False, raise_exception=True, nondet_tol=0.0)¶
```

检查相对于分析梯度 w.r.t 的，通过小的有限差分计算出的梯度的梯度。 `inputs`和`grad_outputs`中的张量是浮点型且带有`requires_grad=True`的张量。

此函数检查通过向给定`grad_outputs`计算的梯度进行反向传播是否正确。

The check between numerical and analytical gradients uses [`allclose()`](torch.html#torch.allclose "torch.allclose").

Note

默认值是为双精度的`input`和`grad_outputs`设计的。 如果它们的精度较低，例如`FloatTensor`，则此检查可能会失败。

Warning

如果`input`和`grad_outputs`中的任何已检查张量具有重叠的内存，即指向同一内存地址的不同索引(例如，来自`torch.expand()`的索引），则此检查可能会失败，因为在这种情况下通过点摄动计算出的数值梯度 索引将更改共享同一内存地址的所有其他索引的值。

Parameters

*   **func** (_function_) – a Python function that takes Tensor inputs and returns a Tensor or a tuple of Tensors

*   **inputs** (_tuple of Tensor_ _or_ [_Tensor_](tensors.html#torch.Tensor "torch.Tensor")) – inputs to the function

*   **grad_outputs** (_张量元组_ _或_ [_tensor_](tensors.html#torch.Tensor "torch.Tensor") _，_ _可选_）–相对于函数输出的渐变。

*   **eps** (_python:float__,_ _optional_) – perturbation for finite differences

*   **atol** (_python:float__,_ _optional_) – absolute tolerance

*   **rtol** (_python:float__,_ _optional_) – relative tolerance

*   **gen_non_contig_grad_outputs**  (_bool_ _，_ _可选_））–如果`grad_outputs`为`None`，`gen_non_contig_grad_outputs`为`True`，则随机 使生成的梯度输出不连续

*   **raise_exception** (_bool__,_ _optional_) – indicating whether to raise an exception if the check fails. The exception gives more information about the exact nature of the failure. This is helpful when debugging gradchecks.

*   **nondet_tol**  (_python：float_ _，_ _可选_）–对不确定性的容忍度。 通过微分运行相同的输入时，结果必须完全匹配(默认值为 0.0）或在此公差范围内。 注意，梯度中的少量不确定性将导致二阶导数的较大误差。

Returns

True if all differences satisfy allclose condition

## 探查器

Autograd 包括一个探查器，可让您检查模型中不同运算符的成本-包括 CPU 和 GPU。 目前有两种模式-仅使用 [`profile`](#torch.autograd.profiler.profile "torch.autograd.profiler.profile") 的 CPU。 并使用 [`emit_nvtx`](#torch.autograd.profiler.emit_nvtx "torch.autograd.profiler.emit_nvtx") 基于 nvprof(注册 CPU 和 GPU 活动）。

* * *

```
class torch.autograd.profiler.profile(enabled=True, use_cuda=False, record_shapes=False)¶
```

上下文管理器，用于管理 autograd profiler 状态并保存结果摘要。 在后台，它仅记录正在 C ++中执行的函数的事件，并将这些事件公开给 Python。 您可以将任何代码包装到其中，并且它只会报告 PyTorch 函数的运行时。

Parameters

*   启用**的** (_bool_ _，_ _可选_）–将其设置为 False 会使此上下文管理器变为无操作。 默认值：`True`。

*   **use_cuda**  (_bool_ _，_ _可选_）–以及使用 cudaEvent API 启用 CUDA 事件的计时。 每个张量操作会增加大约 4us 的开销。 默认值：`False`

*   **record_shapes**  (_bool_ _，_ _可选_）–如果设置了形状记录，将收集有关输入尺寸的信息。 这样一来，您可以查看引擎盖下使用了哪些尺寸，并使用 prof.key_averages(group_by_input_shape = True）将它们进一步分组。 请注意，形状记录可能会歪曲您的轮廓数据。 建议使用带有和不带有形状记录的单独运行来验证计时。 对于最底层的事件(在嵌套函数调用的情况下），偏斜很可能会忽略不计。 但是对于较高级别的功能，由于形状收集，可能会人为地增加总的自体 cpu 时间。

例

```
>>> x = torch.randn((1, 1), requires_grad=True)
>>> with torch.autograd.profiler.profile() as prof:
>>>     for _ in range(100):  # any normal python code, really!
>>>         y = x ** 2
>>          y.backward()
>>> # NOTE: some columns were removed for brevity
>>> print(prof.key_averages().table(sort_by="self_cpu_time_total"))
-----------------------------------  ---------------  ---------------  ---------------
Name                                 Self CPU total   CPU time avg     Number of Calls
-----------------------------------  ---------------  ---------------  ---------------
mul                                  32.048ms         32.048ms         200
pow                                  27.041ms         27.041ms         200
PowBackward0                         9.727ms          55.483ms         100
torch::autograd::AccumulateGrad      9.148ms          9.148ms          100
torch::autograd::GraphRoot           691.816us        691.816us        100
-----------------------------------  ---------------  ---------------  ---------------

```

* * *

```
export_chrome_trace(path)¶
```

将 EventList 导出为 Chrome 跟踪工具文件。

稍后可以在`chrome://tracing` URL 下加载和检查检查点。

Parameters

**路径** (_str_ )–将写入跟踪的路径。

* * *

```
key_averages(group_by_input_shape=False)¶
```

平均所有功能事件的键。

@param group_by_input_shapes 该键将变为(事件名称，输入维度），而不仅仅是事件名称。 这对于查看哪个维度对运行时间的贡献最大是很有用的，并且可以帮助进行特定于维度的优化或选择最佳的量化候选对象(也就是拟合屋顶线）

Returns

一个包含 FunctionEventAvg 对象的 EventList。

* * *

```
property self_cpu_time_total¶
```

返回花费在 CPU 上的总时间，作为所有事件中所有自身时间的总和。

* * *

```
table(sort_by=None, row_limit=100, header=None)¶
```

将 EventList 打印为格式正确的表。

Parameters

**sort_by**  (_str_ _，_ _可选_）–用于对条目进行排序的属性。 默认情况下，它们以与注册时相同的顺序打印。 有效密钥包括：`cpu_time`，`cuda_time`，`cpu_time_total`，`cuda_time_total`，`count`。

Returns

包含表的字符串。

* * *

```
total_average()¶
```

平均所有事件。

Returns

FunctionEventAvg 对象。

* * *

```
class torch.autograd.profiler.record_function(name)¶
```

上下文管理器，在运行 autograd profiler 时将标签添加到 Python 代码块中。 在跟踪代码配置文件时很有用。

Parameters

**名称** (_str_ )–分配给代码块的标签。

Example

```
>>> x = torch.randn((1, 1), requires_grad=True)
>>> with torch.autograd.profiler.profile() as prof:
...     y = x ** 2
...     with torch.autograd.profiler.record_function("label-z"): # label the block
...         z = y ** 3
...     y.backward()
...
>>> # NOTE: some columns were removed for brevity
>>> print(prof.key_averages().table(sort_by="self_cpu_time_total"))
-----------------------------------  ---------------  ---------------  ---------------
Name                                 Self CPU total %  CPU time avg     Number of Calls
-----------------------------------  ---------------  ---------------  ---------------
pow                                  60.77%           47.470us         3
mul                                  21.73%           25.465us         2
PowBackward0                         12.03%           121.891us        1
torch::autograd::AccumulateGrad      2.70%            6.324us          1
label-z                              2.13%            12.421us         1
torch::autograd::GraphRoot           0.64%            1.503us          1
-----------------------------------  ---------------  ---------------  ---------------
Self CPU time total: 234.344us
CUDA time total: 0.000us

```

* * *

```
class torch.autograd.profiler.emit_nvtx(enabled=True, record_shapes=False)¶
```

使每个自动分级操作发出 NXTX 范围的上下文管理器。

在 nvprof 下运行程序时，它很有用：

```
nvprof --profile-from-start off -o trace_name.prof -- <regular command here>

```

不幸的是，无法强制 nvprof 将收集到的数据刷新到磁盘，因此对于 CUDA 分析，必须使用此上下文管理器注释 nvprof 跟踪并等待进程退出后再检查它们。 然后，可以使用 NVIDIA Visual Profiler(nvvp）可视化时间轴，或者 [`torch.autograd.profiler.load_nvprof()`](#torch.autograd.profiler.load_nvprof "torch.autograd.profiler.load_nvprof") 可以加载结果以进行检查，例如 在 Python REPL 中。

Parameters

*   启用 (_bool_ _，_ _可选_ _，_ _默认= True_ )–设置`enabled=False`使此上下文管理器成为禁止操作。 默认值：`True`。

*   **record_shapes**  (_bool_ _，_ _可选_ _，_ _默认=假_）–如果`record_shapes=True`，包装每个 autograd 操作的 nvtx 范围将以以下格式附加有关该操作接收的 Tensor 参数的大小的信息：`[[arg0.size(0), arg0.size(1), ...], [arg1.size(0), arg1.size(1), ...], ...]`非张量参数将由`[]`表示。 参数将按照后端操作接收到的顺序列出。 请注意，此顺序可能与在 Python 端传递这些参数的顺序不匹配。 还要注意，形状记录可能会增加 nvtx 范围创建的开销。

Example

```
>>> with torch.cuda.profiler.profile():
...     model(x) # Warmup CUDA memory allocator and profiler
...     with torch.autograd.profiler.emit_nvtx():
...         model(x)

```

**前向后相关**

当在 Nvidia Visual Profiler 中查看使用 [`emit_nvtx`](#torch.autograd.profiler.emit_nvtx "torch.autograd.profiler.emit_nvtx") 创建的配置文件时，将每个后向操作与相应的前向操作相关联可能很困难。 为了简化此任务， [`emit_nvtx`](#torch.autograd.profiler.emit_nvtx "torch.autograd.profiler.emit_nvtx") 将序列号信息附加到它生成的范围。

在前进过程中，每个功能范围均以`seq=&lt;N&gt;`装饰。 `seq`是一个运行计数器，每次创建一个新的向后功能对象时都将递增并存放以用于向后。 因此，与每个前向功能范围相关联的`seq=&lt;N&gt;`注释告诉您，如果通过此前向功能创建后向功能对象，则后向对象将接收序列号 N。在后向传递过程中，包装每个 C ++的顶级范围 向后函数的`apply()`调用装饰有`stashed seq=&lt;M&gt;`。 `M`是创建反向对象的序列号。 通过比较后向的`stashed seq`数字和正向的`seq`数字，您可以跟踪哪个正向运算符创建了每个向后功能。

向后传递过程中执行的所有功能也都用`seq=&lt;N&gt;`装饰。 在默认向后(使用`create_graph=False`）期间，此信息无关紧要，实际上，对于所有此类功能，`N`可能只是 0。 只有与向后功能对象的`apply()`方法关联的顶级范围才有用，可以将这些功能对象与更早的向前传递相关联。

**双向**

另一方面，如果正在进行`create_graph=True`的向后传递(换句话说，如果您要进行双向后退），则向后执行过程中每个函数的执行都将被赋予非零且有用的`seq=&lt;N&gt;`。 这些函数本身可以创建 Function 对象，以便稍后在双向后执行时，就像向前传递中的原始函数一样。 向后和双向后之间的关系在概念上与向前和向后之间的关系相同：这些函数仍会发出带有当前序列号标记的范围，它们创建的 Function 对象仍会存储这些序列号，并且在最终 double- 向后，功能对象的`apply()`范围仍标记有`stashed seq`数字，可以将其与从后向传递的 &lt;cite&gt;seq&lt;/cite&gt; 数字进行比较。

* * *

```
torch.autograd.profiler.load_nvprof(path)¶
```

打开 nvprof 跟踪文件并解析 autograd 批注。

Parameters

**路径** (_str_ )– nvprof 跟踪的路径

## 异常检测

* * *

```
class torch.autograd.detect_anomaly¶
```

上下文管理器，可为 autograd 引擎启用异常检测。

这有两件事：-在启用检测的情况下运行正向传递，将允许反向传递打印创建失败的反向函数的正向操作的回溯。 -任何产生“ nan”值的向后计算都会引发错误。

Warning

仅在调试时才应启用此模式，因为不同的测试会减慢程序的执行速度。

Example

```
>>> import torch
>>> from torch import autograd
>>> class MyFunc(autograd.Function):
...     @staticmethod
...     def forward(ctx, inp):
...         return inp.clone()
...     @staticmethod
...     def backward(ctx, gO):
...         # Error during the backward pass
...         raise RuntimeError("Some error in backward")
...         return gO.clone()
>>> def run_fn(a):
...     out = MyFunc.apply(a)
...     return out.sum()
>>> inp = torch.rand(10, 10, requires_grad=True)
>>> out = run_fn(inp)
>>> out.backward()
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "/your/pytorch/install/torch/tensor.py", line 93, in backward
        torch.autograd.backward(self, gradient, retain_graph, create_graph)
      File "/your/pytorch/install/torch/autograd/__init__.py", line 90, in backward
        allow_unreachable=True)  # allow_unreachable flag
      File "/your/pytorch/install/torch/autograd/function.py", line 76, in apply
        return self._forward_cls.backward(self, *args)
      File "<stdin>", line 8, in backward
    RuntimeError: Some error in backward
>>> with autograd.detect_anomaly():
...     inp = torch.rand(10, 10, requires_grad=True)
...     out = run_fn(inp)
...     out.backward()
    Traceback of forward call that caused the error:
      File "tmp.py", line 53, in <module>
        out = run_fn(inp)
      File "tmp.py", line 44, in run_fn
        out = MyFunc.apply(a)
    Traceback (most recent call last):
      File "<stdin>", line 4, in <module>
      File "/your/pytorch/install/torch/tensor.py", line 93, in backward
        torch.autograd.backward(self, gradient, retain_graph, create_graph)
      File "/your/pytorch/install/torch/autograd/__init__.py", line 90, in backward
        allow_unreachable=True)  # allow_unreachable flag
      File "/your/pytorch/install/torch/autograd/function.py", line 76, in apply
        return self._forward_cls.backward(self, *args)
      File "<stdin>", line 8, in backward
    RuntimeError: Some error in backward

```

* * *

```
class torch.autograd.set_detect_anomaly(mode)¶
```

上下文管理器，用于打开或关闭 autograd 引擎的异常检测。

`set_detect_anomaly`将基于其参数`mode`启用或禁用自动求导异常检测。 它可以用作上下文管理器或功能。

有关异常检测行为的详细信息，请参见上面的`detect_anomaly`。

Parameters

**模式** (_bool_ )–标记是启用异常检测(`True`）还是禁用(`False`）。