tf.experimental.StructuredTensor

Многомерная коллекция структур с одной и той же схемой.

Наследует от: BatchableExtensionType, ExtensionType

tf.experimental.StructuredTensor(
    fields: Mapping[str, _FieldValue],
    ragged_shape: tf.experimental.DynamicRaggedShape
)

StructuredTensor — это многомерная коллекция структур с одной и той же схемой, где:

• Схема — это набор полей, каждое из которых имеет имя и тип.
• Структура сопоставляет каждому полю в схеме значение тензора (которое может быть вложенным StructuredTensor).

Важный частный случай: одномерный StructuredTensor кодирует двумерную таблицу, в которой столбцы представлены гетерогенными Tensor, а строки — соответствующими элементами каждого из этих Tensor.

Внутри StructuredTensor использует кодирование «сначала поля»: для каждого листового поля существует один тензор, в котором хранятся значения этого поля для всех структур в StructuredTensor.

Примеры

# A scalar StructuredTensor describing a single person.
s1 = tf.experimental.StructuredTensor.from_pyval(
    {"age": 82, "nicknames": ["Bob", "Bobby"]})
s1.shape
TensorShape([])
s1["age"]
<tf.Tensor: shape=(), dtype=int32, numpy=82>

# A vector StructuredTensor describing three people.
s2 = tf.experimental.StructuredTensor.from_pyval([
    {"age": 12, "nicknames": ["Josaphine"]},
    {"age": 82, "nicknames": ["Bob", "Bobby"]},
    {"age": 42, "nicknames": ["Elmo"]}])
s2.shape
TensorShape([3])
s2[0]["age"]
<tf.Tensor: shape=(), dtype=int32, numpy=12>

Пути полей

Путь поля — это кортеж имен полей, указывающий путь к вложенному полю.

x = {'a': 1, 'b': ['foo', 'bar', 'baz']}       # shape = [] (scalar)

s1 = [[x, x, x, x], [x, x, x, x]]              # shape = [2, 4]
tf.experimental.StructuredTensor.from_pyval(s1).row_partitions
(tf.RowPartition(row_splits=[0 4 8]),)

s2 = [[x, x], [x, x], [x, x], [x, x]]          # shape = [4, 2]
tf.experimental.StructuredTensor.from_pyval(s2).row_partitions
(tf.RowPartition(row_splits=[0 2 4 6 8]),)

s3 = [[x, x, x], [], [x, x, x, x], [x]]        # shape = [2, None]
tf.experimental.StructuredTensor.from_pyval(s3).row_partitions
(tf.RowPartition(row_splits=[0 3 3 7 8]),)

s4 = [[[x, x], [x, x]], [[x, x], [x, x]]]      # shape = [2, 2, 2]
tf.experimental.StructuredTensor.from_pyval(s4).row_partitions
(tf.RowPartition(row_splits=[0 2 4]),
 tf.RowPartition(row_splits=[0 2 4 6 8]))

s5 = [[[x, x], [x]], [[x, x]], [[x, x], [x]]]  # shape = [3, None, None]
tf.experimental.StructuredTensor.from_pyval(s5).row_partitions
(tf.RowPartition(row_splits=[0 2 3 5]),
 tf.RowPartition(row_splits=[0 2 3 5 7 8]))

Дочерние классы

class Spec

Методы

field_names

Просмотреть исходный код

field_names()

Возвращает строковые имена полей этого StructuredTensor.

field_value

Просмотреть исходный код

field_value(
    field_name
)

Возвращает значение тензора для указанного поля или пути.

Если field_name — это string, оно задает поле, непосредственно принадлежащее этому StructuredTensor. Если форма этого StructuredTensor равна [D1...DN], возвращаемый тензор будет иметь форму [D1...DN, V1...VM], где срез result[d1...dN] содержит значение поля для структуры в позиции self[d1...dN].

Если field_name — это tuple из string, он задает путь к полю, принадлежащему вложенному StructuredTensor. В частности, struct.field_value((f1, f2, ..., fN)) эквивалентно struct.field_value(f1).field_value(f2)....field_value(fN)

from_fields

Просмотреть исходный код

@classmethod
from_fields(
    fields, shape=(), nrows=None, row_partitions=None, validate=False
)

Создает StructuredTensor из словаря полей.

>>> tf.experimental.StructuredTensor.from_fields({'x': 1, 'y': [1, 2, 3]})
<StructuredTensor(
  fields={
    "x": tf.Tensor(1, shape=(), dtype=int32),
    "y": tf.Tensor([1 2 3], shape=(3,), dtype=int32)},
  shape=())>

tf.experimental.StructuredTensor.from_fields(
    {'foo': [1, 2], 'bar': [3, 4]}, shape=[2])
<StructuredTensor(
  fields={
    "bar": tf.Tensor([3 4], shape=(2,), dtype=int32),
    "foo": tf.Tensor([1 2], shape=(2,), dtype=int32)},
  shape=(2,))>

from_fields_and_rank

Просмотреть исходный код

@classmethod
from_fields_and_rank(
    fields: Mapping[str, _FieldValue],
    rank: int,
    validate: bool = False,
    dtype: Optional[tf.dtypes.DType] = None
) -> 'StructuredTensor'

Создает StructuredTensor из непустого словаря полей.

Обратите внимание: если тип данных формы не указан, он будет выведен по любым полям, для которых задан тип данных формы. Если типы данных полей различаются, будет предпочтителен int64, а не int32, поскольку преобразование int32 в int64 безопаснее, чем преобразование int64 в int32.

Если неровных полей нет, по умолчанию будет использоваться int64, однако в будущем это значение по умолчанию изменится на int32.

>>> tf.experimental.StructuredTensor.from_fields_and_rank(
...     {'x': 1, 'y': [1, 2, 3]}, 0)
<StructuredTensor(
  fields={
    "x": tf.Tensor(1, shape=(), dtype=int32),
    "y": tf.Tensor([1 2 3], shape=(3,), dtype=int32)},
  shape=())>
>>> StructuredTensor.from_fields_and_rank({'foo': [1, 2], 'bar': [3, 4]},
...                              1)
<StructuredTensor(
  fields={
    "bar": tf.Tensor([3 4], shape=(2,), dtype=int32),
    "foo": tf.Tensor([1 2], shape=(2,), dtype=int32)},
  shape=(2,))>

from_pyval

Просмотреть исходный код

@classmethod
from_pyval(
    pyval, typespec=None
)

Создает StructuredTensor из вложенной структуры Python.

tf.experimental.StructuredTensor.from_pyval(
    {'a': [1, 2, 3], 'b': [[4, 5], [6, 7]]})
<StructuredTensor(
    fields={
      "a": tf.Tensor([1 2 3], shape=(3,), dtype=int32),
      "b": <tf.RaggedTensor [[4, 5], [6, 7]]>},
    shape=())>

Обратите внимание: StructuredTensor.from_pyval(pyval).to_pyval() == pyval.

from_shape

Просмотреть исходный код

@classmethod
from_shape(
    ragged_shape: tf.experimental.DynamicRaggedShape
) -> 'StructuredTensor'

Создает StructuredTensor без полей и с ragged_shape.

merge_dims

Просмотреть исходный код

merge_dims(
    outer_axis, inner_axis
)

Объединяет outer_axis...inner_axis в одно измерение.

Возвращает копию этого RaggedTensor, в которой указанный диапазон измерений объединён в одно измерение, а элементы расположены в порядке обхода по строкам.

st = tf.experimental.StructuredTensor.from_pyval(
    [[{'foo': 12}, {'foo': 33}], [], [{'foo': 99}]])
st.merge_dims(0, 1)
<StructuredTensor(
  fields={
    "foo": tf.Tensor([12 33 99], shape=(3,), dtype=int32)},
  shape=(3,))>

nrows

Просмотреть исходный код

nrows()

Количество строк в этом StructuredTensor (если ранг > 0).

Это означает длину внешнего измерения StructuredTensor.

Обратите внимание: если self.rank > 1, это равно количеству строк первого разбиения строк. То есть self.nrows() == self.row_partitions[0].nrows().

В противном случае self.nrows() будет первым измерением значений поля.

partition_outer_dimension

Просмотреть исходный код

partition_outer_dimension(
    row_partition
)

Разбивает внешнее измерение этого StructuredTensor.

Возвращает новый StructuredTensor с теми же значениями, что и у self, где внешнее измерение разбито на два (возможно, ragged) измерения. Требуется, чтобы у этого StructuredTensor было внешнее измерение (то есть self.shape.rank > 0).

st = tf.experimental.StructuredTensor.from_pyval(
    [{'foo': 12}, {'foo': 33}, {'foo': 99}])
partition = RowPartition.from_row_lengths([2, 0, 1])
st.partition_outer_dimension(partition)
<StructuredTensor(
  fields={
    "foo": <tf.RaggedTensor [[12, 33], [], [99]]>},
  shape=(3, None))>

promote

Просмотреть исходный код

promote(
    source_path, new_name
)

Повышает поле, объединяя измерения между родителем и родителем второго уровня.

d = [
 {'docs': [{'tokens':[1, 2]}, {'tokens':[3]}]},
 {'docs': [{'tokens':[7]}]}]
st = tf.experimental.StructuredTensor.from_pyval(d)
st2 =st.promote(('docs','tokens'), 'docs_tokens')
st2[0]['docs_tokens']
<tf.Tensor: shape=(3,), dtype=int32, numpy=array([1, 2, 3], dtype=int32)>
st2[1]['docs_tokens']
<tf.Tensor: shape=(1,), dtype=int32, numpy=array([7], dtype=int32)>

to_pyval

Просмотреть исходный код

to_pyval()

Возвращает этот StructuredTensor в виде вложенного словаря Python или списка словарей.

Преобразует этот StructuredTensor во вложенное значение Python:

• StructTensors с rank=0 преобразуются в словарь с записью для каждого поля. Имена полей используются в качестве ключей, а значения полей преобразуются в значения Python. В частности:

  • Скалярные поля Tensor преобразуются в простые значения (например, int, float или string)
  • Нескалярные поля Tensor и поля RaggedTensor преобразуются во вложенные списки простых значений.
  • Поля StructuredTensor рекурсивно преобразуются с помощью to_pyval.

• StructTensors с rank>0 преобразуются во вложенные list Python, содержащие по одному словарю для каждой структуры (словарь каждой структуры определяется, как описано выше).

Требуется, чтобы все поля были тензорами Eager.

tf.experimental.StructuredTensor.from_fields(
    {'a': [1, 2, 3]}, [3]).to_pyval()
[{'a': 1}, {'a': 2}, {'a': 3}]

Обратите внимание, что StructuredTensor.from_pyval(pyval).to_pyval() == pyval.

with_shape_dtype

Просмотреть исходный код

with_shape_dtype(
    dtype: tf.dtypes.DType
) -> 'StructuredTensor'

with_updates

Просмотреть исходный код

with_updates(
    updates: Dict[FieldName, Union[_FieldValue, _FieldFn, None]],
    validate: bool = False
) -> 'StructuredTensor'

Создаёт новый StructuredTensor с обновлёнными полями.

Если этот StructuredTensor является скалярным, а k — это обновляемый FieldName, а v — новое значение, то:

result[k] = v              # If (k, v) is in updates and v is a FieldValue
result[k] = f(self[k])     # If (k, f) is in updates and f is a FieldFn
result[k] = self[k]        # If k is in self.field_names but not in updates

Если этот StructuredTensor имеет ранг N и форму [D1...DN], то каждое FieldValue v в updates должно иметь форму [D1...DN, ...], то есть начинаться с той же формы, что и StructuredTensor. Тогда результирующий StructuredTensor будет иметь:

result[i1...iN][k] = v[i1...iN]                        # (k, v) in updates
result[i1...iN][k] = f(self.field_value(k))[i1...iN]   # (k, f) in updates
result[i1...iN][k] = self[i1...iN][k]                  # k not in updates

Обратите внимание, что result.shape всегда равно self.shape (но формы вложенных StructuredTensor могут измениться при обновлении новыми значениями).

Примеры:

shoes_us = tf.experimental.StructuredTensor.from_pyval([
   {"age": 12, "nicknames": ["Josaphine"],
      "shoes": {"sizes": [8.0, 7.5, 7.5]} },
   {"age": 82, "nicknames": ["Bob", "Bobby"],
       "shoes": {"sizes": [11.0, 11.5, 12.0]} },
   {"age": 42, "nicknames": ["Elmo"],
       "shoes": {"sizes": [9.0, 9.5, 10.0]} }])
def us_to_europe(t):
  return tf.round(t * 2.54 + 17.0)  # Rough approximation.
shoe_sizes_key = ("shoes", "sizes")
shoes_eu = shoes_us.with_updates({shoe_sizes_key: us_to_europe})
shoes_eu.field_value(shoe_sizes_key)
<tf.RaggedTensor [[37.0, 36.0, 36.0], [45.0, 46.0, 47.0],
[40.0, 41.0, 42.0]]>

__eq__

Просмотреть исходный код

__eq__(
    other
)

Возвращает результат сравнения self==value.

__getitem__

Просмотреть исходный код

__getitem__(
    key
)

Возвращает указанную часть этого StructuredTensor.

• Если struct_tensor является скалярным (то есть представляет одну структуру), struct_tensor[f] возвращает значение поля f (где f должно быть строкой).

• Если struct_tensor не является скалярным (то есть представляет вектор или тензор структур более высокой размерности), struct_tensor[i] выбирает элемент или срез тензора, используя стандартные правила Python (например, отрицательные значения отсчитываются от конца). i может иметь один из следующих типов:

  • константа int
  • константа string
  • скалярное целое число Tensor
  • slice, содержащий целочисленные константы и/или скалярные целые числа Tensor

Многомерная индексация

StructuredTensor поддерживает многомерную индексацию. То есть key может быть tuple значений, индексирующим или срезающим несколько измерений одновременно. Например, если people — это вектор структур, каждая из которых имеет поле names со значениями-вектором, то people[3, 'names', 0] эквивалентно people[3]['names'][0]; а people[:, 'names', :] вернёт (возможно, ragged) матрицу имён с формой [num_people, num_names_per_person].

__ne__

Просмотреть исходный код

__ne__(
    other
)

Возвращает результат сравнения self!=value.