torch.utils.dlpack

Создано: 11 июл. 2018 г. | Последнее обновление: 01 июл. 2026 г.

torch.utils.dlpack.from_dlpack(ext_tensor) → Tensor [исходный код]

Преобразует тензор из внешней библиотеки в torch.Tensor.

Возвращаемый тензор PyTorch будет использовать ту же область памяти, что и входной тензор (который мог быть получен из другой библиотеки). Поэтому обратите внимание, что операции на месте также будут влиять на данные входного тензора. Это может привести к неожиданным проблемам (например, в других библиотеках могут быть флаги только для чтения или неизменяемые структуры данных), поэтому пользователю следует делать это, только если он точно уверен, что это допустимо.

Параметры:

• ext_tensor (объект с атрибутом __dlpack__ или капсула DLPack) –

  Тензор или капсула DLPack для преобразования.

  Если ext_tensor — объект тензора (или ndarray), он должен поддерживать протокол __dlpack__ (то есть иметь метод ext_tensor.__dlpack__). В противном случае ext_tensor может быть капсулой DLPack — непрозрачным экземпляром PyCapsule, обычно создаваемым функцией или методом to_dlpack.

• device (torch.device или str или None) – Необязательное устройство PyTorch, указывающее, где разместить новый тензор. Если значение равно None (по умолчанию), новый тензор будет находиться на том же устройстве, что и ext_tensor.
• copy (bool или None) – Необязательное логическое значение, указывающее, нужно ли копировать self. Если значение равно None, PyTorch выполнит копирование только при необходимости.

Тип возвращаемого значения:

Tensor

Примеры:

>>> import torch.utils.dlpack
>>> t = torch.arange(4)

# Convert a tensor directly (supported in PyTorch >= 1.10)
>>> t2 = torch.from_dlpack(t)
>>> t2[:2] = -1  # show that memory is shared
>>> t2
tensor([-1, -1,  2,  3])
>>> t
tensor([-1, -1,  2,  3])

# The old-style DLPack usage, with an intermediate capsule object
>>> capsule = torch.utils.dlpack.to_dlpack(t)
>>> capsule
<capsule object "dltensor" at ...>
>>> t3 = torch.from_dlpack(capsule)
>>> t3
tensor([-1, -1,  2,  3])
>>> t3[0] = -9  # now we're sharing memory between 3 tensors
>>> t3
tensor([-9, -1,  2,  3])
>>> t2
tensor([-9, -1,  2,  3])
>>> t
tensor([-9, -1,  2,  3])

torch.utils.dlpack.to_dlpack(tensor) → PyCapsule

Возвращает непрозрачный объект («капсулу DLPack»), представляющий тензор.

Примечание

to_dlpack — это устаревший интерфейс DLPack. Возвращаемую им капсулу нельзя использовать в Python ни для чего, кроме передачи в качестве входных данных в from_dlpack. Более идиоматичный способ работы с DLPack — напрямую вызвать from_dlpack для объекта тензора. Это работает, если у объекта есть метод __dlpack__, который теперь есть у PyTorch и большинства других библиотек.

Предупреждение

Вызывайте from_dlpack только один раз для каждой капсулы, созданной с помощью to_dlpack. Поведение при многократном использовании капсулы не определено.

Параметры:

tensor – тензор для экспорта

Капсула DLPack использует ту же область памяти, что и тензор.

class torch.utils.dlpack.ReadOnlyTensorWrapper(tensor) [исходный код]

Представление тензора без копирования и только для чтения, предназначенное исключительно для взаимодействия с DLPack.

Оборачивание тензора в ReadOnlyTensorWrapper указывает, что потребители не должны изменять его данные. Это меняет только поведение экспорта DLPack; обёртка использует то же хранилище, что и исходный тензор, и не выполняет копирование.

Оба пути экспорта DLPack направляются к вариантам только для чтения:

• быстрый протокол обмена C __dlpack_c_exchange_api__ (используемый tvm-ffi / CuteDSL) обращается к API обмена константами, который выполняет экспорт через const_data_ptr() и устанавливает DLPACK_FLAG_BITMASK_READ_ONLY;
• протокол капсул __dlpack__() принудительно устанавливает read_only=True.

Поскольку при экспорте используется const_data_ptr(), экспорт тензора с копированием при записи не приводит к его материализации.

Обёртка предназначена только для экспорта: любая операция torch, кроме методов протокола DLPack, вызывает RuntimeError. Чтобы работать с данными, снимите обёртку (например, используя исходный тензор).

Пример:

x = torch.randn(8)
ro = ReadOnlyTensorWrapper(x)
cute.runtime.from_dlpack(ro, enable_tvm_ffi=True)  # read-only export

Тип возвращаемого значения:

ReadOnlyTensorWrapper