torch.masked

Создано: 15 авг. 2022 г. | Последнее обновление: 13 апр. 2026 г.

Введение

Мотивация

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

API PyTorch для маскированных тензоров находится на стадии прототипа и в будущем может измениться, а может и не измениться.

MaskedTensor — это расширение torch.Tensor, которое предоставляет пользователю возможность:

использовать любую семантику масок (например, тензоры переменной длины, операторы nan* и т. д.)
различать градиенты со значением 0 и NaN
применять различные разреженные представления (см. учебное руководство ниже)

Понятия «заданный» и «не заданный» давно используются в PyTorch без формальной семантики и, конечно, без единообразия; MaskedTensor появился именно из-за накопившихся проблем, которые обычный класс torch.Tensor не мог должным образом решить. Поэтому одна из главных целей MaskedTensor — стать источником истины для таких «заданных» и «не заданных» значений в PyTorch, где они будут полноправными элементами, а не второстепенной деталью. В свою очередь, это должно раскрыть потенциал разреженности, обеспечить более безопасную и последовательную работу операторов, а также сделать взаимодействие пользователей и разработчиков с библиотекой более простым и интуитивно понятным.

Что такое MaskedTensor?

MaskedTensor — это подкласс тензора, состоящий из 1) входных данных и 2) маски. Маска указывает, какие элементы входных данных следует учитывать, а какие — игнорировать.

Например, допустим, мы хотим замаскировать все значения, равные 0 (показаны серым цветом), и найти максимум:

Сверху показан пример обычного тензора, а снизу — MaskedTensor, в котором все нули замаскированы. Очевидно, что результат будет разным в зависимости от наличия маски, однако такая гибкая структура позволяет пользователю систематически игнорировать при вычислениях любые выбранные элементы.

Мы подготовили несколько учебных руководств, которые помогут новым пользователям начать работу:

Поддерживаемые операторы

Унарные операторы

Унарные операторы принимают только один входной аргумент. Применять их к MaskedTensor довольно просто: если данные в заданном индексе замаскированы, мы применяем оператор; в противном случае данные остаются замаскированными.

Доступны следующие унарные операторы:

`abs`	Вычисляет абсолютное значение каждого элемента в `input`.
`absolute`	Псевдоним для `torch.abs()`
`acos`	Возвращает новый тензор с арккосинусом (в радианах) каждого элемента в `input`.
`arccos`	Псевдоним для `torch.acos()`.
`acosh`	Возвращает новый тензор с обратным гиперболическим косинусом элементов `input`.
`arccosh`	Псевдоним для `torch.acosh()`.
`angle`	Вычисляет угол (в радианах) каждого элемента заданного `input` тензора.
`asin`	Возвращает новый тензор с арксинусом элементов (в радианах) `input` тензора.
`arcsin`	Псевдоним для `torch.asin()`.
`asinh`	Возвращает новый тензор с обратным гиперболическим синусом элементов `input`.
`arcsinh`	Псевдоним для `torch.asinh()`.
`atan`	Возвращает новый тензор с арктангенсом элементов (в радианах) `input` тензора.
`arctan`	Псевдоним для `torch.atan()`.
`atanh`	Возвращает новый тензор с обратным гиперболическим тангенсом элементов `input`.
`arctanh`	Псевдоним для `torch.atanh()`.
`bitwise_not`	Вычисляет побитовое НЕ заданного входного тензора.
`ceil`	Возвращает новый тензор с округлёнными вверх значениями элементов `input` — наименьшими целыми числами, большими или равными соответствующим элементам.
`clamp`	Ограничивает все элементы `input` диапазоном от `[` `min` до `max` `]`.
`clip`	Псевдоним для `torch.clamp()`.
`conj_physical`	Вычисляет комплексно-сопряжённое значение каждого элемента заданного `input` тензора.
`cos`	Возвращает новый тензор с косинусами элементов `input`, заданных в радианах.
`cosh`	Возвращает новый тензор с гиперболическими косинусами элементов `input`.
`deg2rad`	Возвращает новый тензор, в котором каждый элемент `input` преобразован из градусов в радианы.
`digamma`	Псевдоним для `torch.special.digamma()`.
`erf`	Псевдоним для `torch.special.erf()`.
`erfc`	Псевдоним для `torch.special.erfc()`.
`erfinv`	Псевдоним для `torch.special.erfinv()`.
`exp`	Возвращает новый тензор с экспонентами элементов входного тензора `input`.
`exp2`	Псевдоним для `torch.special.exp2()`.
`expm1`	Псевдоним для `torch.special.expm1()`.
`fix`	Псевдоним для `torch.trunc()`
`floor`	Возвращает новый тензор с округлёнными вниз значениями элементов `input` — наибольшими целыми числами, меньшими или равными соответствующим элементам.
`frac`	Вычисляет дробную часть каждого элемента в `input`.
`lgamma`	Вычисляет натуральный логарифм абсолютного значения гамма-функции для `input`.
`log`	Возвращает новый тензор с натуральными логарифмами элементов `input`.
`log10`	Возвращает новый тензор с десятичными логарифмами элементов `input`.
`log1p`	Возвращает новый тензор с натуральными логарифмами выражения (1 + `input`).
`log2`	Возвращает новый тензор с логарифмами по основанию 2 элементов `input`.
`logit`	Псевдоним для `torch.special.logit()`.
`i0`	Псевдоним для `torch.special.i0()`.
`isnan`	Возвращает новый тензор с логическими значениями, указывающими, является ли каждый элемент `input` значением NaN.
`nan_to_num`	Заменяет значения `NaN`, положительной и отрицательной бесконечности в `input` значениями, заданными параметрами `nan`, `posinf` и `neginf` соответственно.
`neg`	Возвращает новый тензор с отрицательными значениями элементов `input`.
`negative`	Псевдоним для `torch.neg()`
`positive`	Возвращает `input`.
`pow`	Возводит каждый элемент `input` в степень `exponent` и возвращает тензор с результатом.
`rad2deg`	Возвращает новый тензор, в котором каждый элемент `input` преобразован из радиан в градусы.
`reciprocal`	Возвращает новый тензор с величинами, обратными элементам `input`
`round`	Округляет элементы `input` до ближайших целых чисел.
`rsqrt`	Возвращает новый тензор со значениями, обратными квадратным корням каждого элемента `input`.
`sigmoid`	Псевдоним для `torch.special.expit()`.
`sign`	Возвращает новый тензор со знаками элементов `input`.
`sgn`	Эта функция расширяет torch.sign() для комплексных тензоров.
`signbit`	Проверяет, установлен ли знаковый бит каждого элемента `input`.
`sin`	Возвращает новый тензор с синусами элементов `input` тензора, где каждое значение входного тензора задано в радианах.
`sinc`	Псевдоним для `torch.special.sinc()`.
`sinh`	Возвращает новый тензор с гиперболическими синусами элементов `input`.
`sqrt`	Возвращает новый тензор с квадратными корнями элементов `input`.
`square`	Возвращает новый тензор с квадратами элементов `input`.
`tan`	Возвращает новый тензор с тангенсами элементов `input` тензора, где каждое значение входного тензора задано в радианах.
`tanh`	Возвращает новый тензор с гиперболическими тангенсами элементов `input`.
`trunc`	Возвращает новый тензор с целыми частями элементов `input`, полученными усечением.

Доступны все перечисленные выше унарные операторы с изменением на месте, кроме:

`angle`	Вычисляет угол (в радианах) каждого элемента заданного `input` тензора.
`positive`	Возвращает `input`.
`signbit`	Проверяет, установлен ли знаковый бит каждого элемента `input`.
`isnan`	Возвращает новый тензор с логическими значениями, указывающими, является ли каждый элемент `input` значением NaN.

Бинарные операторы

Как вы могли видеть в руководстве, MaskedTensor также реализует бинарные операции с оговоркой: маски двух MaskedTensor должны совпадать, иначе будет вызвана ошибка. Как отмечено в сообщении об ошибке, если вам нужна поддержка определённого оператора или вы предлагаете семантику его поведения, создайте issue на GitHub. Пока мы решили использовать наиболее консервативную реализацию, чтобы пользователи точно понимали происходящее и осознанно принимали решения относительно семантики масок.

Доступны следующие бинарные операторы:

`add`	Прибавляет `other`, умноженное на `alpha`, к `input`.
`atan2`	Поэлементный арктангенс $\text{input}_{i} / \text{other}_{i}$ с учётом квадранта.
`arctan2`	Псевдоним для `torch.atan2()`.
`bitwise_and`	Вычисляет побитовое И для `input` и `other`.
`bitwise_or`	Вычисляет побитовое ИЛИ для `input` и `other`.
`bitwise_xor`	Вычисляет побитовое исключающее ИЛИ для `input` и `other`.
`bitwise_left_shift`	Вычисляет арифметический сдвиг `input` влево на `other` бит.
`bitwise_right_shift`	Вычисляет арифметический сдвиг `input` вправо на `other` бит.
`div`	Делит каждый элемент входного `input` на соответствующий элемент `other`.
`divide`	Псевдоним для `torch.div()`.
`floor_divide`
`fmod`	Поэлементно применяет std::fmod из C++.
`logaddexp`	Логарифм суммы экспонент входных данных.
`logaddexp2`	Логарифм суммы экспонент входных данных по основанию 2.
`mul`	Умножает `input` на `other`.
`multiply`	Псевдоним для `torch.mul()`.
`nextafter`	Поэлементно возвращает следующее значение с плавающей точкой после `input` в направлении `other`.
`remainder`	Поэлементно вычисляет операцию взятия остатка по модулю в Python.
`sub`	Вычитает `other`, умноженное на `alpha`, из `input`.
`subtract`	Псевдоним для `torch.sub()`.
`true_divide`	Псевдоним для `torch.div()` с `rounding_mode=None`.
`eq`	Вычисляет поэлементное равенство
`ne`	Поэлементно вычисляет $\text{input} \neq \text{other}$ .
`le`	Поэлементно вычисляет $\text{input} \leq \text{other}$ .
`ge`	Поэлементно вычисляет $\text{input} \geq \text{other}$ .
`greater`	Псевдоним для `torch.gt()`.
`greater_equal`	Псевдоним для `torch.ge()`.
`gt`	Поэлементно вычисляет $\text{input} > \text{other}$ .
`less_equal`	Псевдоним для `torch.le()`.
`lt`	Поэлементно вычисляет $\text{input} < \text{other}$ .
`less`	Псевдоним для `torch.lt()`.
`maximum`	Поэлементно вычисляет максимум `input` и `other`.
`minimum`	Поэлементно вычисляет минимум `input` и `other`.
`fmax`	Поэлементно вычисляет максимум `input` и `other`.
`fmin`	Поэлементно вычисляет минимум `input` и `other`.
`not_equal`	Псевдоним для `torch.ne()`.

Доступны все перечисленные выше операторы с изменением на месте, кроме:

`logaddexp`	Логарифм суммы экспонент входных данных.
`logaddexp2`	Логарифм суммы экспонент входных данных по основанию 2.
`equal`	`True`, если два тензора имеют одинаковый размер и элементы, иначе `False`.
`fmin`	Поэлементно вычисляет минимум `input` и `other`.
`minimum`	Поэлементно вычисляет минимум `input` и `other`.
`fmax`	Поэлементно вычисляет максимум `input` и `other`.

Операции редукции

Доступны следующие операции редукции (с поддержкой autograd). Дополнительную информацию и примеры операций редукции можно найти в руководстве Обзор, а в руководстве Расширенная семантика подробнее обсуждается, как были выбраны семантические правила для некоторых операций редукции.

`sum`	Возвращает сумму всех элементов тензора `input`.
`mean`
`amin`	Возвращает минимальное значение каждого среза тензора `input` по заданным измерениям `dim`.
`amax`	Возвращает максимальное значение каждого среза тензора `input` по заданным измерениям `dim`.
`argmin`	Возвращает индексы минимального значения (значений) в развёрнутом тензоре или вдоль заданного измерения
`argmax`	Возвращает индексы максимального значения среди всех элементов тензора `input`.
`prod`	Возвращает произведение всех элементов тензора `input`.
`all`	Проверяет, что все элементы `input` принимают значение `True`.
`norm`	Возвращает матричную или векторную норму заданного тензора.
`var`	Вычисляет дисперсию по измерениям, заданным параметром `dim`.
`std`	Вычисляет стандартное отклонение по измерениям, заданным параметром `dim`.

Функции представления и выбора

Мы также включили несколько функций представления и выбора; интуитивно эти операторы применяются и к данным, и к маске, после чего результат оборачивается в MaskedTensor. Для краткого примера рассмотрим select():

    >>> data = torch.arange(12, dtype=torch.float).reshape(3, 4)
    >>> data
    tensor([[ 0.,  1.,  2.,  3.],
            [ 4.,  5.,  6.,  7.],
            [ 8.,  9., 10., 11.]])
    >>> mask = torch.tensor([[True, False, False, True], [False, True, False, False], [True, True, True, True]])
    >>> mt = masked_tensor(data, mask)
    >>> data.select(0, 1)
    tensor([4., 5., 6., 7.])
    >>> mask.select(0, 1)
    tensor([False,  True, False, False])
    >>> mt.select(0, 1)
    MaskedTensor(
      [      --,   5.0000,       --,       --]
    )

В настоящее время поддерживаются следующие операции:

`atleast_1d`	Возвращает одномерное представление каждого входного тензора с нулём измерений.
`broadcast_tensors`	Выполняет широковещательное преобразование заданных тензоров в соответствии с семантикой широковещательного преобразования.
`broadcast_to`	Выполняет широковещательное преобразование `input` к форме `shape`.
`cat`	Объединяет заданную последовательность тензоров из `tensors` вдоль указанного измерения.
`chunk`	Пытается разделить тензор на заданное количество частей.
`column_stack`	Создаёт новый тензор, горизонтально объединяя тензоры из `tensors`.
`dsplit`	Разбивает `input` — тензор с тремя или более измерениями — на несколько тензоров по глубине в соответствии с `indices_or_sections`.
`flatten`	Преобразует `input` в одномерный тензор.
`hsplit`	Разбивает `input` — тензор с одним или более измерениями — на несколько тензоров по горизонтали в соответствии с `indices_or_sections`.
`hstack`	Объединяет тензоры последовательности по горизонтали (по столбцам).
`kron`	Вычисляет произведение Кронекера, обозначаемое символом $\otimes$ , для `input` и `other`.
`meshgrid`	Создаёт координатные сетки, заданные одномерными входными тензорами из `attr`.
`narrow`	Возвращает новый тензор, представляющий собой суженную версию тензора `input`.
`nn.functional.unfold`	Извлекает локальные блоки с перекрытием из пакетного входного тензора.
`ravel`	Возвращает непрерывный развёрнутый тензор.
`select`	Извлекает срез тензора `input` вдоль выбранного измерения по заданному индексу.
`split`	Разбивает тензор на части.
`stack`	Объединяет последовательность тензоров вдоль нового измерения.
`t`	Ожидает, что `input` будет тензором размерности <= 2, и транспонирует измерения 0 и 1.
`transpose`	Возвращает тензор, представляющий собой транспонированную версию `input`.
`vsplit`	Разбивает `input` — тензор с двумя или более измерениями — на несколько тензоров по вертикали в соответствии с `indices_or_sections`.
`vstack`	Объединяет тензоры последовательности по вертикали (по строкам).
`Tensor.expand`	Возвращает новое представление тензора `self`, в котором размерность единичных измерений увеличен.
`Tensor.expand_as`	Расширяет этот тензор до размера `other`.
`Tensor.reshape`	Возвращает тензор с теми же данными и количеством элементов, что и `self`, но с указанной формой.
`Tensor.reshape_as`	Возвращает этот тензор с той же формой, что и `other`.
`Tensor.unfold`	Возвращает представление исходного тензора, содержащее все срезы размера `size` из тензора `self` вдоль измерения `dimension`.
`Tensor.view`	Возвращает новый тензор с теми же данными, что и тензор `self`, но с другой `shape`.

torch.masked.maskedtensor.core

is_masked_tensor

Возвращает True, если входные данные являются MaskedTensor, иначе False

© 2026, PyTorch Contributors
PyTorch has a BSD-style license, as found in the LICENSE file.
https://docs.pytorch.org/docs/2.14/masked.html