命名张量¶

命名张量允许用户为其张量维度指定显式名称。在大多数情况下，接受维度参数的操作将接受维度名称，从而避免按位置跟踪维度。此外，命名张量在运行时使用名称自动检查 API 是否被正确使用，提供额外的安全性。名称还可用于重新排列维度，例如，支持“按名称广播”而不是“按位置广播”。

警告

命名张量 API 是一个原型功能，可能会有所更改。

创建命名张量¶

工厂函数现在接受一个新的 names 参数，该参数将名称与每个维度关联起来。

>>> torch.zeros(2, 3, names=('N', 'C'))
tensor([[0., 0., 0.],
        [0., 0., 0.]], names=('N', 'C'))

命名维度，像普通张量维度一样，是有序的。tensor.names[i] 是张量 tensor 的维度 i 的名称。

以下工厂函数支持命名张量

命名维度¶

有关张量名称的限制，请参阅 names。

使用 names 访问张量的维度名称，使用 rename() 重命名命名维度。

>>> imgs = torch.randn(1, 2, 2, 3 , names=('N', 'C', 'H', 'W'))
>>> imgs.names
('N', 'C', 'H', 'W')

>>> renamed_imgs = imgs.rename(H='height', W='width')
>>> renamed_imgs.names
('N', 'C', 'height', 'width)

命名张量可以与未命名张量共存；命名张量是 torch.Tensor 的实例。未命名张量的维度名称为 None。命名张量不要求所有维度都命名。

>>> imgs = torch.randn(1, 2, 2, 3 , names=(None, 'C', 'H', 'W'))
>>> imgs.names
(None, 'C', 'H', 'W')

名称传播语义¶

命名张量使用名称在运行时自动检查 API 是否被正确调用。这发生在一个称为 名称推断 的过程中。更正式地说，名称推断包括以下两个步骤

检查名称: 算子可能会在运行时执行自动检查，以检查某些维度名称是否必须匹配。
传播名称: 名称推断将名称传播到输出张量。

所有支持命名张量的操作都会传播名称。

>>> x = torch.randn(3, 3, names=('N', 'C'))
>>> x.abs().names
('N', 'C')

匹配语义¶

如果两个名称相等（字符串相等）或至少有一个为 None，则它们匹配。None 本质上是一个特殊的“通配符”名称。

unify(A, B) 确定将名称 A 和 B 中的哪一个传播到输出。如果它们匹配，它将返回两者中更具体的名称。如果名称不匹配，则会报错。

注意

在实践中，使用命名张量时应避免使用未命名维度，因为它们的处理可能很复杂。建议使用 refine_names() 将所有未命名维度提升为命名维度。

基本名称推断规则¶

让我们看看在添加两个没有广播的一维张量的情况下，如何在名称推断中使用 match 和 unify。

x = torch.randn(3, names=('X',))
y = torch.randn(3)
z = torch.randn(3, names=('Z',))

检查名称: 检查两个张量的名称是否匹配。

对于以下示例

>>> # x + y  # match('X', None) is True
>>> # x + z  # match('X', 'Z') is False
>>> # x + x  # match('X', 'X') is True

>>> x + z
Error when attempting to broadcast dims ['X'] and dims ['Z']: dim 'X' and dim 'Z' are at the same position from the right but do not match.

传播名称: 统一名称以选择传播哪一个。在 x + y 的情况下，unify('X', None) = 'X'，因为 'X' 比 None 更具体。

>>> (x + y).names
('X',)
>>> (x + x).names
('X',)

有关名称推断规则的完整列表，请参阅命名张量算子覆盖范围。这里有两个常见的可能有用的操作可以回顾一下

二元算术算子: 统一输入中的名称
矩阵乘法算子: 收缩掉维度

按名称显式对齐¶

使用 align_as() 或 align_to() 按名称将张量维度对齐到指定的顺序。这对于执行“按名称广播”很有用。

# This function is agnostic to the dimension ordering of `input`,
# as long as it has a `C` dimension somewhere.
def scale_channels(input, scale):
    scale = scale.refine_names('C')
    return input * scale.align_as(input)

>>> num_channels = 3
>>> scale = torch.randn(num_channels, names=('C',))
>>> imgs = torch.rand(3, 3, 3, num_channels, names=('N', 'H', 'W', 'C'))
>>> more_imgs = torch.rand(3, num_channels, 3, 3, names=('N', 'C', 'H', 'W'))
>>> videos = torch.randn(3, num_channels, 3, 3, 3, names=('N', 'C', 'H', 'W', 'D')

>>> scale_channels(imgs, scale)
>>> scale_channels(more_imgs, scale)
>>> scale_channels(videos, scale)

操作维度¶

使用 align_to() 对大量维度进行置换，而无需像 permute() 所要求的那样提及所有维度。

>>> tensor = torch.randn(2, 2, 2, 2, 2, 2)
>>> named_tensor = tensor.refine_names('A', 'B', 'C', 'D', 'E', 'F')

# Move the F (dim 5) and E dimension (dim 4) to the front while keeping
# the rest in the same order
>>> tensor.permute(5, 4, 0, 1, 2, 3)
>>> named_tensor.align_to('F', 'E', ...)

分别使用 flatten() 和 unflatten() 展平维度和反展平维度。这些方法比 view() 和 reshape() 更冗长，但对于阅读代码的人来说更具语义意义。

>>> imgs = torch.randn(32, 3, 128, 128)
>>> named_imgs = imgs.refine_names('N', 'C', 'H', 'W')

>>> flat_imgs = imgs.view(32, -1)
>>> named_flat_imgs = named_imgs.flatten(['C', 'H', 'W'], 'features')
>>> named_flat_imgs.names
('N', 'features')

>>> unflattened_named_imgs = named_flat_imgs.unflatten('features', [('C', 3), ('H', 128), ('W', 128)])
>>> unflattened_named_imgs.names
('N', 'C', 'H', 'W')

Autograd 支持¶

Autograd 当前对命名张量的支持有限：Autograd 忽略所有张量上的名称。梯度计算仍然正确，但我们失去了名称提供的安全性。

>>> x = torch.randn(3, names=('D',))
>>> weight = torch.randn(3, names=('D',), requires_grad=True)
>>> loss = (x - weight).abs()
>>> grad_loss = torch.randn(3)
>>> loss.backward(grad_loss)
>>> weight.grad  # Unnamed for now. Will be named in the future
tensor([-1.8107, -0.6357,  0.0783])

>>> weight.grad.zero_()
>>> grad_loss = grad_loss.refine_names('C')
>>> loss = (x - weight).abs()
# Ideally we'd check that the names of loss and grad_loss match but we don't yet.
>>> loss.backward(grad_loss)
>>> weight.grad
tensor([-1.8107, -0.6357,  0.0783])

当前支持的操作和子系统¶

算子¶

有关支持的 torch 和张量操作的完整列表，请参阅命名张量算子覆盖范围。我们尚不支持以下未在该链接中涵盖的内容

索引，高级索引。

对于 torch.nn.functional 算子，我们支持以下内容

子系统¶

支持 Autograd，参见 Autograd 支持。由于梯度当前未命名，优化器可能工作，但未经测试。

NN 模块当前不支持。当使用命名张量输入调用模块时，可能导致以下情况

NN 模块参数未命名，因此输出可能部分命名。
NN 模块前向传播的代码不支持命名张量，将适当地报错。

我们也不支持以下子系统，尽管其中一些可能开箱即用

distributions
serialization (torch.load(), torch.save())
multiprocessing
JIT
distributed
ONNX

如果其中任何一项对您的用例有帮助，请搜索是否已提交相关问题，如果没有，请提交一个问题。

命名张量 API 参考¶

在本节中，您可以找到命名张量特定 API 的文档。有关名称如何在其他 PyTorch 算子中传播的全面参考，请参阅命名张量算子覆盖范围。

class torch.Tensor

names¶

存储此张量每个维度的名称。

names[idx] 对应于张量维度 idx 的名称。如果维度已命名，则名称为字符串；如果维度未命名，则名称为 None。

维度名称可以包含字符或下划线。此外，维度名称必须是有效的 Python 变量名（即，不能以下划线开头）。

张量不能有两个具有相同名称的命名维度。

警告

命名张量 API 是实验性的，可能会有所更改。

rename(*names, **rename_map)[source][source]¶

重命名 self 的维度名称。

主要有两种用法

self.rename(**rename_map) 返回一个张量视图，该视图的维度已按照 rename_map 映射进行重命名。

self.rename(*names) 返回一个张量视图，使用 names 按位置重命名所有维度。使用 self.rename(None) 删除张量上的名称。

不能同时指定位置参数 names 和关键字参数 rename_map。

示例

>>> imgs = torch.rand(2, 3, 5, 7, names=('N', 'C', 'H', 'W'))
>>> renamed_imgs = imgs.rename(N='batch', C='channels')
>>> renamed_imgs.names
('batch', 'channels', 'H', 'W')

>>> renamed_imgs = imgs.rename(None)
>>> renamed_imgs.names
(None, None, None, None)

>>> renamed_imgs = imgs.rename('batch', 'channel', 'height', 'width')
>>> renamed_imgs.names
('batch', 'channel', 'height', 'width')

警告

命名张量 API 是实验性的，可能会有所更改。

rename_(*names, **rename_map)[source][source]¶: rename() 的就地版本。

refine_names(*names)[source][source]¶

根据 names 细化 self 的维度名称。

细化是重命名的一种特殊情况，它会“提升”未命名维度。None 维度可以细化为具有任何名称；已命名维度只能细化为具有相同的名称。

由于命名张量可以与未命名张量共存，细化名称提供了一种很好的方式来编写命名张量感知代码，该代码适用于命名张量和未命名张量。

names 最多可以包含一个省略号（...）。省略号会被贪婪地展开；它会就地展开，使用 self.names 中相应索引处的名称，将 names 填充到与 self.dim() 相同的长度。

Python 2 不支持省略号，但可以使用字符串字面量代替（'...'）。

参数: names (iterable of str) – 输出张量所需的名称。最多可以包含一个省略号。

示例

>>> imgs = torch.randn(32, 3, 128, 128)
>>> named_imgs = imgs.refine_names('N', 'C', 'H', 'W')
>>> named_imgs.names
('N', 'C', 'H', 'W')

>>> tensor = torch.randn(2, 3, 5, 7, 11)
>>> tensor = tensor.refine_names('A', ..., 'B', 'C')
>>> tensor.names
('A', None, None, 'B', 'C')

警告

命名张量 API 是实验性的，可能会有所更改。

align_as(other) → Tensor¶

根据 other 张量中的维度顺序，对 self 张量的维度进行置换，并为任何新名称添加大小为 1 的维度。

此操作对于按名称显式广播很有用（参见示例）。

为了使用此方法，self 的所有维度都必须命名。结果张量是原始张量的一个视图。

self 的所有维度名称都必须存在于 other.names 中。other 可能包含不在 self.names 中的命名维度；输出张量会为这些新名称中的每一个添加一个大小为 1 的维度。

要将张量对齐到特定顺序，请使用 align_to()。

示例

# Example 1: Applying a mask
>>> mask = torch.randint(2, [127, 128], dtype=torch.bool).refine_names('W', 'H')
>>> imgs = torch.randn(32, 128, 127, 3, names=('N', 'H', 'W', 'C'))
>>> imgs.masked_fill_(mask.align_as(imgs), 0)


# Example 2: Applying a per-channel-scale
>>> def scale_channels(input, scale):
>>>    scale = scale.refine_names('C')
>>>    return input * scale.align_as(input)

>>> num_channels = 3
>>> scale = torch.randn(num_channels, names=('C',))
>>> imgs = torch.rand(32, 128, 128, num_channels, names=('N', 'H', 'W', 'C'))
>>> more_imgs = torch.rand(32, num_channels, 128, 128, names=('N', 'C', 'H', 'W'))
>>> videos = torch.randn(3, num_channels, 128, 128, 128, names=('N', 'C', 'H', 'W', 'D'))

# scale_channels is agnostic to the dimension order of the input
>>> scale_channels(imgs, scale)
>>> scale_channels(more_imgs, scale)
>>> scale_channels(videos, scale)

警告

命名张量 API 是实验性的，可能会有所更改。

align_to(*names)[source][source]¶

根据 names 中指定的顺序，对 self 张量的维度进行置换，并为任何新名称添加大小为 1 的维度。

为了使用此方法，self 的所有维度都必须命名。结果张量是原始张量的一个视图。

self 的所有维度名称都必须存在于 names 中。names 可能包含不在 self.names 中的附加名称；输出张量会为这些新名称中的每一个添加一个大小为 1 的维度。

names 最多可以包含一个省略号（...）。省略号会被展开，等于 self 的所有未在 names 中提及的维度名称，按它们在 self 中出现的顺序排列。

Python 2 不支持省略号，但可以使用字符串字面量代替（'...'）。

参数: names (iterable of str) – 输出张量所需的维度顺序。最多可以包含一个省略号，它会展开为 self 中所有未提及的维度名称。

示例

>>> tensor = torch.randn(2, 2, 2, 2, 2, 2)
>>> named_tensor = tensor.refine_names('A', 'B', 'C', 'D', 'E', 'F')

# Move the F and E dims to the front while keeping the rest in order
>>> named_tensor.align_to('F', 'E', ...)

警告

命名张量 API 是实验性的，可能会有所更改。

flatten(dims, out_dim) → Tensor

将 dims 展平为一个具有名称 out_dim 的单维度。

张量 self 中，所有的 dims 在顺序上必须是连续的，但在内存中不一定是连续的。

示例

>>> imgs = torch.randn(32, 3, 128, 128, names=('N', 'C', 'H', 'W'))
>>> flat_imgs = imgs.flatten(['C', 'H', 'W'], 'features')
>>> flat_imgs.names, flat_imgs.shape
(('N', 'features'), torch.Size([32, 49152]))

警告

命名张量 API 是实验性的，可能会有所更改。

命名张量¶

创建命名张量¶

命名维度¶

名称传播语义¶

匹配语义¶

基本名称推断规则¶

按名称显式对齐¶

操作维度¶

Autograd 支持¶

当前支持的操作和子系统¶

算子¶

子系统¶

命名张量 API 参考¶

文档

教程

资源