Recursos do conjunto de dados

Features define a estrutura interna de um conjunto de dados. É usado para especificar o formato de serialização subjacente. O que é mais interessante para você, no entanto, é que Features contém informações de alto nível sobre tudo, desde os nomes e tipos de colunas até o ClassLabel. Você pode pensar em Features como a espinha dorsal de um conjunto de dados.

O formato Features é simples: dict[column_name, column_type]. Trata-se de um dicionário de pares de nome de coluna e tipo de coluna. O tipo de coluna oferece uma ampla gama de opções para descrever o tipo de dados que você possui.

Vamos dar uma olhada nos recursos do conjunto de dados MRPC do benchmark GLUE:

>>> from datasets import load_dataset
>>> dataset = load_dataset('nyu-mll/glue', 'mrpc', split='train')
>>> dataset.features
{'idx': Value('int32'),
 'label': ClassLabel(names=['not_equivalent', 'equivalent']),
 'sentence1': Value('string'),
 'sentence2': Value('string'),
}

O recurso Value informa ao 🤗 Datasets:

• O tipo de dados idx é int32.
• Os tipos de dados sentence1 e sentence2 são string.

🤗 O Datasets suporta muitos outros tipos de dados, como bool, float32 e binary, para citar apenas alguns.

Consulte Value para obter a lista completa de tipos de dados suportados.

O recurso ClassLabel informa ao 🤗 Datasets que a coluna label contém duas classes. As classes são rotuladas como not_equivalent e equivalent. Os rótulos são armazenados como inteiros no dataset. Ao recuperar os rótulos, ClassLabel.int2str() e ClassLabel.str2int() realizam a conversão do valor inteiro para o nome do rótulo, e vice-versa.

Se o tipo de dados de você contém uma lista de objetos, então você deve usar o recurso List. Lembra do conjunto de dados SQuAD?

>>> from datasets import load_dataset
>>> dataset = load_dataset('rajpurkar/squad', split='train')
>>> dataset.features
{'id': Value('string'),
 'title': Value('string'),
 'context': Value('string'),
 'question': Value('string'),
 'answers': {'text': List(Value('string')),
  'answer_start': List(Value('int32'))}}

O campo answers é construído usando o dicionário de recursos porque e contém dois subcampos, text e answer_start, que são listas de string e int32, respectivamente.

Veja a seção flatten para aprender como você pode extrair os subcampos aninhados como colunas independentes.

O tipo de recurso de array é útil para criar arrays de vários tamanhos. Você pode criar arrays com duas dimensões usando Array2D e até mesmo arrays com cinco dimensões usando Array5D.

>>> features = Features({'a': Array2D(shape=(1, 3), dtype='int32')})

O tipo de array também permite que a primeira dimensão do array seja dinâmica. Isso é útil para lidar com sequências de comprimentos variáveis, como frases, sem precisar preencher ou truncar a entrada para uma forma uniforme.

>>> features = Features({'a': Array3D(shape=(None, 5, 2), dtype='int32')})

Recurso de áudio

Os conjuntos de dados de áudio possuem uma coluna com o tipo Audio, que contém três campos importantes:

• array: os dados de áudio decodificados representados como um array unidimensional.
• path: o caminho para o arquivo de áudio baixado.
• sampling_rate: a taxa de amostragem dos dados de áudio.

Ao carregar um conjunto de dados de áudio e chamar a coluna de áudio, o recurso Audio decodifica e reamostra automaticamente o arquivo de áudio:

>>> from datasets import load_dataset, Audio

>>> dataset = load_dataset("PolyAI/minds14", "en-US", split="train")
>>> dataset[0]["audio"]
<datasets.features._torchcodec.AudioDecoder object at 0x11642b6a0>

Acesse um conjunto de dados de áudio usando primeiro o índice da linha e, em seguida, a coluna audio - dataset[0]["audio"] - para evitar a decodificação e a reamostragem de todos os arquivos de áudio no conjunto de dados. Caso contrário, isso pode ser um processo lento e demorado se você tiver um conjunto de dados grande.

Com decode=False, o tipo Audio simplesmente fornece o caminho ou os bytes do arquivo de áudio, sem decodificá-lo em um objeto AudioDecoder do torchcodec,

>>> dataset = load_dataset("PolyAI/minds14", "en-US", split="train").cast_column("audio", Audio(decode=False))
>>> dataset[0]
{'audio': {'bytes': None,
  'path': '/root/.cache/huggingface/datasets/downloads/extracted/f14948e0e84be638dd7943ac36518a4cf3324e8b7aa331c5ab11541518e9368c/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav'},
 'english_transcription': 'I would like to set up a joint account with my partner',
 'intent_class': 11,
 'lang_id': 4,
 'path': '/root/.cache/huggingface/datasets/downloads/extracted/f14948e0e84be638dd7943ac36518a4cf3324e8b7aa331c5ab11541518e9368c/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav',
 'transcription': 'I would like to set up a joint account with my partner'}

Recurso de imagem

Conjuntos de dados de imagem possuem uma coluna com o tipo Image, que carrega objetos PIL.Image a partir de imagens armazenadas como bytes:

Ao carregar um conjunto de dados de imagens e chamar a coluna de imagens, o recurso Image decodifica automaticamente o arquivo de imagem:

>>> from datasets import load_dataset, Image

>>> dataset = load_dataset("AI-Lab-Makerere/beans", split="train")
>>> dataset[0]["image"]
<PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=500x500 at 0x125506CF8>

Acesse um conjunto de dados de imagens usando primeiro o índice da linha e, em seguida, a coluna image - dataset[0]["image"] - para evitar a decodificação de todos os arquivos de imagem do conjunto de dados. Caso contrário, isso pode ser um processo lento e demorado se você tiver um conjunto de dados grande.

Com decode=False, o tipo Image simplesmente fornece o caminho ou os bytes do arquivo de imagem, sem decodificá-lo em um PIL.Image,

>>> dataset = load_dataset("AI-Lab-Makerere/beans", split="train").cast_column("image", Image(decode=False))
>>> dataset[0]["image"]
{'bytes': None,
 'path': '/Users/username/.cache/huggingface/datasets/downloads/extracted/772e7c1fba622cff102b85dd74bcce46e8168634df4eaade7bedd3b8d91d3cd7/train/healthy/healthy_train.265.jpg'}

Dependendo do conjunto de dados, você pode obter o caminho da imagem baixada localmente ou o conteúdo da imagem em bytes, caso o conjunto de dados não seja composto por arquivos individuais.

Você também pode definir um conjunto de dados de imagens a partir de arrays numpy:

>>> ds = Dataset.from_dict({"i": [np.zeros(shape=(16, 16, 3), dtype=np.uint8)]}, features=Features({"i": Image()}))

E, nesse caso, os arrays numpy são codificados em PNG (ou TIFF, se a precisão dos valores dos pixels for importante).

Para arrays multicanais, como RGB ou RGBA, apenas uint8 é suportado. Se você usar uma precisão maior, um aviso é exibido e o array é convertido para uint8. Para imagens em escala de cinza, você pode usar a precisão inteira ou de ponto flutuante que desejar, desde que seja compatível com Pillow. Um aviso é exibido se a precisão inteira ou de ponto flutuante da sua imagem for muito alta, e, nesse caso, o array é convertido: um array int64 é convertido para int32, e um array float64 é convertido para float32.

Recurso de malha

Os conjuntos de dados de malha possuem uma coluna com o tipo Mesh, que carrega arquivos de malha 3D como objetos trimesh.

Ao carregar um conjunto de dados de malha e chamar a coluna de malha, o recurso Mesh decodifica automaticamente o arquivo de malha:

>>> from datasets import load_dataset, Mesh

>>> dataset = load_dataset("VINAY-UMRETHE/My-Mesh-Dataset", split="train")
>>> dataset[0]["mesh"]
<trimesh.Scene(len(geometry)=33)>

Dependendo do conteúdo do arquivo, o trimesh pode retornar um objeto trimesh.Trimesh ou um objeto trimesh.Scene.

Acesse um conjunto de dados de malha usando primeiro o índice da linha e depois a coluna mesh - dataset[0]["mesh"] - para evitar a decodificação de todos os arquivos de malha no conjunto de dados. Caso contrário, isso pode ser um processo lento e demorado se você tiver um conjunto de dados grande.

Com decode=False, o tipo Mesh fornece o caminho ou os bytes do arquivo de malha sem decodificá-lo com trimesh:

>>> dataset = load_dataset("VINAY-UMRETHE/My-Mesh-Dataset", split="train").cast_column("mesh", Mesh(decode=False))
>>> dataset[0]["mesh"]
{'bytes': b'...',
 'path': '00001.glb'}

O recurso Mesh suporta arquivos .glb, .gltf, .ply e .stl. Para bytes incorporados, o path armazenado é usado para inferir o tipo de arquivo da malha.

Recurso Json

Os datasets são baseados no Arrow, que é um formato colunar, e, portanto, esperam que cada exemplo tenha o mesmo tipo e subtipos, e que os dicionários tenham as mesmas chaves e tipos de valores. Ao carregar um dataset, ocorre um erro quando os campos têm tipos incompatíveis, e os campos ausentes nos dicionários são preenchidos com None para que todos os dicionários tenham as mesmas chaves e tipos de valores.

Para evitar isso e permitir tipos mistos sem erros, você pode usar on_mixed_types="use_json" ou especificar features= com um tipo Json:

>>> ds = Dataset.from_dict({"a": [0, "foo", {"subfield": "bar"}]})
Traceback (most recent call last):
  ...
  File "pyarrow/error.pxi", line 92, in pyarrow.lib.check_status
pyarrow.lib.ArrowInvalid: Could not convert 'foo' with type str: tried to convert to int64

>>> features = Features({"a": Json()})
>>> ds = Dataset.from_dict({"a": [0, "foo", {"subfield": "bar"}]}, features=features)
>>> ds.features
{'a': Json()}
>>> list(ds["a"])
[0, "foo", {"subfield": "bar"}]

Isso também é útil para listas de dicionários com chaves e valores arbitrários, para evitar preencher campos ausentes com None:

>>> ds = Dataset.from_dict({"a": [[{"b": 0}, {"c": 0}]]})
>>> ds.features
{'a': List({'b': Value('int64'), 'c': Value('int64')})}
>>> list(ds["a"])
[[{'b': 0, 'c': None}, {'b': None, 'c': 0}]]  # missing fields are filled with None

>>> features = Features({"a": List(Json())})
>>> ds = Dataset.from_dict({"a": [[{"b": 0}, {"c": 0}]]}, features=features)
>>> ds.features
{'a': List(Json())}
>>> list(ds["a"])
[[{'b': 0}, {'c': 0}]]  # OK

Outro exemplo com dados de chamada de ferramentas e o argumento on_mixed_types="use_json" (útil para não precisar especificar features= manualmente):

>>> messages = [
...     {"role": "user", "content": "Turn on the living room lights and play my electronic music playlist."},
...     {"role": "assistant", "tool_calls": [
...         {"type": "function", "function": {
...             "name": "control_light",
...             "arguments": {"room": "living room", "state": "on"}
...         }},
...         {"type": "function", "function": {
...             "name": "play_music",
...             "arguments": {"playlist": "electronic"}  # mixed-type here since keys ["playlist"] and ["room", "state"] are different
...         }}]
...     },
...     {"role": "tool", "name": "control_light", "content": "The lights in the living room are now on."},
...     {"role": "tool", "name": "play_music", "content": "The music is now playing."},
...     {"role": "assistant", "content": "Done!"}
... ]
>>> ds = Dataset.from_dict({"messages": [messages]}, on_mixed_types="use_json")
>>> ds.features
{'messages': List({'role': Value('string'), 'content': Value('string'), 'tool_calls': List(Json()), 'name': Value('string')})}
>>> ds[0][1]["tool_calls"][0]["function"]["arguments"]
{"room": "living room", "state": "on"}