# Recursos do conjunto de dados

[Features](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Features) contém informações de alto nível sobre tudo, desde os nomes e tipos de colunas até o [ClassLabel](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.ClassLabel). Você pode pensar em [Features](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Features) como a espinha dorsal de um conjunto de dados.

O formato [Features](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.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:

```py
>>> 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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.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.

> [!TIP]
> Consulte [Value](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Value) para obter a lista completa de tipos de dados suportados.

O recurso [ClassLabel](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.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()](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.ClassLabel.int2str) e [ClassLabel.str2int()](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.List). Lembra do conjunto de dados SQuAD?

```py
>>> 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.

> [!TIP]
> Veja a seção [flatten](./process#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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Array2D) e até mesmo arrays com cinco dimensões usando [Array5D](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Array5D).

```py
>>> 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.

```py
>>> 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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Audio) decodifica e reamostra automaticamente o arquivo de áudio:

```py
>>> 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>
```

> [!WARNING]
> 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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Audio) simplesmente fornece o caminho ou os bytes do arquivo de áudio, sem decodificá-lo em um objeto `AudioDecoder` do torchcodec,

```py
>>> 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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Image) decodifica automaticamente o arquivo de imagem:

```py
>>> 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>
```

> [!WARNING]
> 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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Image) simplesmente fornece o caminho ou os bytes do arquivo de imagem, sem decodificá-lo em um `PIL.Image`,

```py
>>> 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:

```python
>>> 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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Mesh) decodifica automaticamente o arquivo de malha:

```py
>>> 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`.

> [!WARNING]
> 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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.Mesh) fornece o caminho ou os bytes do arquivo de malha sem decodificá-lo com `trimesh`:

```py
>>> 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](/docs/datasets/v5.2.0/pt/package_reference/main_classes#datasets.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](/docs/datasets/v5.2.0/pt/package_reference/loading_methods#datasets.Json):

```python
>>> 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:

```python
>>> 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):

```python
>>> 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"}
```