TVTensors 常见问题解答¶
TVTensors 是与 torchvision.transforms.v2
一起引入的 Tensor 子类。此示例展示了这些 TVTensors 是什么以及它们的行为方式。
警告
**目标受众** 除非您正在编写自己的变换或自己的 TVTensors,否则您可能不需要阅读本指南。这是一个相当底层的主题,大多数用户无需担心:您无需了解 TVTensors 的内部机制即可有效地依赖 torchvision.transforms.v2
。但是,对于尝试实现自己的数据集、变换或直接使用 TVTensors 的高级用户来说,它可能很有用。
import PIL.Image
import torch
from torchvision import tv_tensors
什么是 TVTensors?¶
TVTensors 是零拷贝张量子类
tensor = torch.rand(3, 256, 256)
image = tv_tensors.Image(tensor)
assert isinstance(image, torch.Tensor)
assert image.data_ptr() == tensor.data_ptr()
在幕后,它们在 torchvision.transforms.v2
中是必需的,以便正确地分派到输入数据的相应函数。
torchvision.tv_tensors
支持四种类型的 TVTensors
我可以对 TVTensor 做什么?¶
TVTensors 看起来和感觉就像普通的张量 - 它们**是**张量。在普通 torch.Tensor
上支持的所有内容,如 .sum()
或任何 torch.*
运算符,也适用于 TVTensors。有关一些注意事项,请参阅我有一个 TVTensor,但现在我有一个 Tensor。请帮忙!。
如何构造 TVTensor?¶
使用构造函数¶
每个 TVTensor 类都采用任何可以转换为 Tensor
的类似张量数据
image = tv_tensors.Image([[[[0, 1], [1, 0]]]])
print(image)
Image([[[[0, 1],
[1, 0]]]], )
与其他 PyTorch 创建操作类似,构造函数还采用 dtype
、device
和 requires_grad
参数。
float_image = tv_tensors.Image([[[0, 1], [1, 0]]], dtype=torch.float32, requires_grad=True)
print(float_image)
Image([[[0., 1.],
[1., 0.]]], grad_fn=<AliasBackward0>, )
此外,Image
和 Mask
还可以直接采用 PIL.Image.Image
image = tv_tensors.Image(PIL.Image.open("../assets/astronaut.jpg"))
print(image.shape, image.dtype)
torch.Size([3, 512, 512]) torch.uint8
某些 TVTensors 需要传递额外的元数据才能进行构造。例如,BoundingBoxes
需要坐标格式以及相应的图像大小 (canvas_size
) 以及实际值。这些元数据是正确变换边界框所必需的。
bboxes = tv_tensors.BoundingBoxes(
[[17, 16, 344, 495], [0, 10, 0, 10]],
format=tv_tensors.BoundingBoxFormat.XYXY,
canvas_size=image.shape[-2:]
)
print(bboxes)
BoundingBoxes([[ 17, 16, 344, 495],
[ 0, 10, 0, 10]], format=BoundingBoxFormat.XYXY, canvas_size=torch.Size([512, 512]))
使用 tv_tensors.wrap()
¶
您还可以使用 wrap()
函数将张量对象包装到 TVTensor 中。当您已经拥有所需类型的对象时,这很有用,这通常发生在编写变换时:您只需像输入一样包装输出。
new_bboxes = torch.tensor([0, 20, 30, 40])
new_bboxes = tv_tensors.wrap(new_bboxes, like=bboxes)
assert isinstance(new_bboxes, tv_tensors.BoundingBoxes)
assert new_bboxes.canvas_size == bboxes.canvas_size
new_bboxes
的元数据与 bboxes
相同,但您可以将其作为参数传递以覆盖它。
我有一个 TVTensor,但现在我有一个 Tensor。请帮忙!¶
默认情况下,对 TVTensor
对象的操作将返回一个纯 Tensor
assert isinstance(bboxes, tv_tensors.BoundingBoxes)
# Shift bboxes by 3 pixels in both H and W
new_bboxes = bboxes + 3
assert isinstance(new_bboxes, torch.Tensor)
assert not isinstance(new_bboxes, tv_tensors.BoundingBoxes)
注意
此行为仅影响本机 torch
操作。如果您使用内置的 torchvision
变换或函数,您将始终获得与您作为输入传递的相同类型的输出(纯 Tensor
或 TVTensor
)。
但我想要一个 TVTensor 返回!¶
您可以通过调用 TVTensor 构造函数或使用 wrap()
函数(请参阅上面 如何构造 TVTensor? 中的更多详细信息)将纯张量重新包装到 TVTensor 中。
new_bboxes = bboxes + 3
new_bboxes = tv_tensors.wrap(new_bboxes, like=bboxes)
assert isinstance(new_bboxes, tv_tensors.BoundingBoxes)
或者,您可以使用 set_return_type()
作为整个程序的全局配置设置,或作为上下文管理器(阅读其文档以了解有关注意事项的更多信息)
with tv_tensors.set_return_type("TVTensor"):
new_bboxes = bboxes + 3
assert isinstance(new_bboxes, tv_tensors.BoundingBoxes)
为什么会发生这种情况?¶
**出于性能原因**。TVTensor
类是 Tensor 子类,因此任何涉及 TVTensor
对象的操作都将通过 __torch_function__ 协议。这会产生少量开销,我们希望尽可能避免这种情况。对于内置的 torchvision
变换,这并不重要,因为我们可以在那里避免开销,但它可能是您模型的 forward
中的一个问题。
无论如何,替代方案也没好到哪里去。 在每个保留TVTensor
类型的操作都有意义的情况下,也有同样多的操作更倾向于返回纯 Tensor:例如,img.sum()
仍然是 Image
吗?如果我们要一直保留TVTensor
类型,即使模型的 logits 或损失函数的输出最终也会成为 Image
类型,这肯定是不希望看到的。
注意
我们正在积极寻求对此行为的反馈。如果您发现此行为令人惊讶,或者您有任何关于如何更好地支持您的用例的建议,请通过此问题与我们联系:https://github.com/pytorch/vision/issues/7319
异常¶
此“解包”规则有一些例外:clone()
、to()
、torch.Tensor.detach()
和 requires_grad_()
会保留 TVTensor 类型。
TVTensor 上的原地操作,如 obj.add_()
,将保留 obj
的类型。但是,原地操作的**返回值**将是纯 Tensor。
image = tv_tensors.Image([[[0, 1], [1, 0]]])
new_image = image.add_(1).mul_(2)
# image got transformed in-place and is still a TVTensor Image, but new_image
# is a Tensor. They share the same underlying data and they're equal, just
# different classes.
assert isinstance(image, tv_tensors.Image)
print(image)
assert isinstance(new_image, torch.Tensor) and not isinstance(new_image, tv_tensors.Image)
assert (new_image == image).all()
assert new_image.data_ptr() == image.data_ptr()
Image([[[2, 4],
[4, 2]]], )
脚本的总运行时间:(0 分钟 0.008 秒)