Datasets documentation

与 PyArrow 配合使用

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.2.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

与 PyArrow 配合使用

本文档简要介绍了如何使用 datasets 与 PyArrow 配合工作,重点说明如何使用 Arrow 计算函数处理数据集,以及如何在数据集与 PyArrow 之间进行转换。

这一点尤其有用,因为 datasets 底层使用 PyArrow,从而支持快速的零拷贝操作。

数据集格式

默认情况下,数据集返回的是普通的 Python 对象:整数、浮点数、字符串、列表等。

若要获取 PyArrow 表或数组,可以使用 Dataset.with_format() 将数据集的格式设置为 pyarrow:

>>> from datasets import Dataset
>>> data = {"col_0": ["a", "b", "c", "d"], "col_1": [0., 0., 1., 1.]}
>>> ds = Dataset.from_dict(data)
>>> ds = ds.with_format("arrow")
>>> ds[0]       # pa.Table
pyarrow.Table
col_0: string
col_1: double
----
col_0: [["a"]]
col_1: [[0]]
>>> ds[:2]      # pa.Table
pyarrow.Table
col_0: string
col_1: double
----
col_0: [["a","b"]]
col_1: [[0,0]]
>>> ds["data"]  # pa.array
<pyarrow.lib.ChunkedArray object at 0x1394312a0>
[
  [
    "a",
    "b",
    "c",
    "d"
  ]
]

对于例如使用 load_dataset(..., streaming=True) 获取的 IterableDataset 对象,此方法同样适用:

>>> ds = ds.with_format("arrow")
>>> for table in ds.iter(batch_size=2):
...     print(table)
...     break
pyarrow.Table
col_0: string
col_1: double
----
col_0: [["a","b"]]
col_1: [[0,0]]

处理数据

PyArrow 函数通常比常规手写 Python 函数更快,因此是优化数据处理的理想选择。您可以在 Dataset.map() 或 Dataset.filter() 中使用 Arrow 计算函数来处理数据集:

>>> import pyarrow.compute as pc
>>> from datasets import Dataset
>>> data = {"col_0": ["a", "b", "c", "d"], "col_1": [0., 0., 1., 1.]}
>>> ds = Dataset.from_dict(data)
>>> ds = ds.with_format("arrow")
>>> ds = ds.map(lambda t: t.append_column("col_2", pc.add(t["col_1"], 1)), batched=True)
>>> ds[:2]
pyarrow.Table
col_0: string
col_1: double
col_2: double
----
col_0: [["a","b"]]
col_1: [[0,0]]
col_2: [[1,1]]
>>> ds = ds.filter(lambda t: pc.equal(t["col_0"], "b"), batched=True)
>>> ds[0]
pyarrow.Table
col_0: string
col_1: double
col_2: double
----
col_0: [["b"]]
col_1: [[0]]
col_2: [[1]]

我们使用 batched=True,因为在 PyArrow 中按批次处理数据比逐行处理更快。也可以在 map() 中使用 batch_size= 来设置每个 table 的大小。

这对 IterableDataset.map() 和 IterableDataset.filter() 同样适用。

从 PyArrow 导入或导出

Dataset 是 PyArrow Table 的封装,您可以直接从 Table 实例化一个 Dataset:

ds = Dataset(table)

您可以通过 Dataset.data 访问数据集的 PyArrow Table,根据 Arrow 数据的来源以及所执行的操作,它会返回 MemoryMappedTable、InMemoryTable 或 ConcatenationTable。

这些对象封装了位于 Dataset.data.table 处的底层 PyArrow 表。该表包含数据集的所有数据,但可能还存在一个位于 Dataset._indices 的索引映射,它将数据集的行索引映射到 PyArrow 表的行索引。如果数据集已通过 Dataset.shuffle() 进行洗牌,或者仅使用了部分行(例如在 Dataset.select() 之后),就可能出现这种情况。

在一般情况下,您可以使用 table = ds.with_format("arrow")[:] 将数据集导出为 PyArrow Table。

Update on GitHub