# Đặc điểm của bộ dữ liệu

[Features](/docs/datasets/main/vi/package_reference/main_classes#datasets.Features) định nghĩa cấu trúc bên trong của một tập dữ liệu. Nó được dùng để chỉ định định dạng chuỗi hóa (serialization) cơ bản. Tuy nhiên, điều thú vị hơn với bạn là [Features](/docs/datasets/main/vi/package_reference/main_classes#datasets.Features) chứa thông tin cấp cao về mọi thứ, từ tên và kiểu của các cột, cho đến [ClassLabel](/docs/datasets/main/vi/package_reference/main_classes#datasets.ClassLabel). Bạn có thể coi [Features](/docs/datasets/main/vi/package_reference/main_classes#datasets.Features) là xương sống của một tập dữ liệu.

Định dạng [Features](/docs/datasets/main/vi/package_reference/main_classes#datasets.Features) rất đơn giản: `dict[column_name, column_type]`. Đây là một từ điển gồm các cặp tên cột và kiểu cột. Kiểu cột cung cấp nhiều tùy chọn để mô tả loại dữ liệu bạn có.

Hãy cùng xem xét các đặc điểm của bộ dữ liệu MRPC từ bộ chuẩn 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'),
}
```

Tính năng [Value](/docs/datasets/main/vi/package_reference/main_classes#datasets.Value) cho 🤗 Datasets biết:

- Loại dữ liệu `idx` là `int32`.
- Các kiểu dữ liệu `sentence1` và `sentence2` là `string`.

🤗 Datasets hỗ trợ nhiều kiểu dữ liệu khác như `bool`, `float32` và `binary`, chỉ để nêu một vài ví dụ.

> [!TIP]
> Tham khảo [Value](/docs/datasets/main/vi/package_reference/main_classes#datasets.Value) để xem danh sách đầy đủ các kiểu dữ liệu được hỗ trợ.

Tính năng [ClassLabel](/docs/datasets/main/vi/package_reference/main_classes#datasets.ClassLabel) thông báo cho 🤗 Datasets rằng cột `label` chứa hai lớp. Các lớp được đặt tên là `not_equivalent` và `equivalent`. Nhãn được lưu dưới dạng số nguyên trong bộ dữ liệu. Khi bạn truy xuất các nhãn, [ClassLabel.int2str()](/docs/datasets/main/vi/package_reference/main_classes#datasets.ClassLabel.int2str) và [ClassLabel.str2int()](/docs/datasets/main/vi/package_reference/main_classes#datasets.ClassLabel.str2int) thực hiện việc chuyển đổi từ giá trị số nguyên sang tên nhãn, và ngược lại.

Nếu kiểu dữ liệu của bạn chứa một danh sách các đối tượng, thì bạn muốn sử dụng tính năng [List](/docs/datasets/main/vi/package_reference/main_classes#datasets.List). Bạn có nhớ bộ dữ liệu SQuAD không?

```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'))}}
```

Trường `answers` được xây dựng bằng cách sử dụng dict của các đặc trưng vì và chứa hai trường con, `text` và `answer_start`, lần lượt là các danh sách `string` và `int32`.

> [!TIP]
> Xem phần [flatten](./process#flatten) để tìm hiểu cách bạn có thể trích xuất các trường con lồng nhau thành các cột độc lập riêng biệt.

Loại đặc trưng mảng (array) hữu ích để tạo các mảng với nhiều kích thước khác nhau. Bạn có thể tạo mảng hai chiều bằng [Array2D](/docs/datasets/main/vi/package_reference/main_classes#datasets.Array2D), và thậm chí cả mảng năm chiều bằng [Array5D](/docs/datasets/main/vi/package_reference/main_classes#datasets.Array5D).

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

Loại mảng cũng cho phép chiều đầu tiên của mảng là động. Điều này hữu ích để xử lý các chuỗi có độ dài thay đổi như các câu, mà không cần phải đệm hoặc cắt ngắn đầu vào để có cùng một hình dạng.

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

## Đặc trưng âm thanh

Bộ dữ liệu âm thanh có một cột với kiểu [Audio](/docs/datasets/main/vi/package_reference/main_classes#datasets.Audio), chứa ba trường quan trọng:

- `array`: dữ liệu âm thanh đã giải mã, được biểu diễn dưới dạng mảng một chiều.
- `path`: đường dẫn đến tệp âm thanh đã tải xuống.
- `sampling_rate`: tần số lấy mẫu của dữ liệu âm thanh.

Khi bạn tải một tập dữ liệu âm thanh và gọi cột âm thanh, tính năng [Audio](/docs/datasets/main/vi/package_reference/main_classes#datasets.Audio) sẽ tự động giải mã và lấy lại mẫu (resample) tệp âm thanh:

```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]
> Truy cập vào một tập dữ liệu âm thanh bằng cách sử dụng chỉ số hàng trước, sau đó là cột `audio` - `dataset[0]["audio"]` - để tránh việc giải mã và lấy lại mẫu cho tất cả các tệp âm thanh trong tập dữ liệu. Nếu không, đây có thể là một quy trình chậm và tốn thời gian nếu bạn có một tập dữ liệu lớn.

Với `decode=False`, kiểu [Audio](/docs/datasets/main/vi/package_reference/main_classes#datasets.Audio) đơn giản chỉ trả về đường dẫn hoặc các byte của tệp âm thanh, mà không giải mã nó thành một đối tượng `AudioDecoder` của 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'}
```

## Đặc trưng hình ảnh

Bộ dữ liệu hình ảnh có một cột với kiểu [Image](/docs/datasets/main/vi/package_reference/main_classes#datasets.Image), tải các đối tượng `PIL.Image` từ các hình ảnh được lưu dưới dạng byte:

Khi bạn tải một tập dữ liệu ảnh và gọi cột ảnh, đặc trưng [Image](/docs/datasets/main/vi/package_reference/main_classes#datasets.Image) sẽ tự động giải mã tệp ảnh:

```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]
> Truy cập vào bộ dữ liệu ảnh bằng chỉ số hàng trước, sau đó là cột `image` - `dataset[0]["image"]` - để tránh việc giải mã tất cả các tệp ảnh trong bộ dữ liệu. Nếu không, đây có thể là một quy trình chậm và tốn thời gian nếu bạn có một bộ dữ liệu lớn.

Với `decode=False`, kiểu [Image](/docs/datasets/main/vi/package_reference/main_classes#datasets.Image) chỉ đơn giản là trả về đường dẫn hoặc các byte của tệp hình ảnh, mà không giải mã nó thành `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'}
```

Tùy thuộc vào bộ dữ liệu, bạn có thể nhận được đường dẫn đến hình ảnh đã tải xuống cục bộ, hoặc nội dung của hình ảnh dưới dạng bytes nếu bộ dữ liệu không được tạo từ các tệp riêng lẻ.

Bạn cũng có thể định nghĩa một tập dữ liệu hình ảnh từ các mảng numpy:

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

Và trong trường hợp này, các mảng numpy được mã hóa thành PNG (hoặc TIFF nếu độ chính xác của giá trị pixel là quan trọng).

Đối với các mảng đa kênh như RGB hoặc RGBA, chỉ hỗ trợ uint8. Nếu bạn sử dụng độ chính xác lớn hơn, một cảnh báo sẽ được hiển thị và mảng sẽ được chuyển xuống uint8. Đối với ảnh đen trắng, bạn có thể sử dụng độ chính xác nguyên hoặc số thực bất kỳ, miễn là tương thích với `Pillow`. Một cảnh báo sẽ được hiển thị nếu độ chính xác nguyên hoặc số thực của ảnh quá cao, và trong trường hợp này mảng sẽ được chuyển xuống: mảng int64 sẽ được chuyển xuống int32, và mảng float64 sẽ được chuyển xuống float32.

## Tính năng Mesh

Bộ dữ liệu Mesh có một cột với kiểu [Mesh](/docs/datasets/main/vi/package_reference/main_classes#datasets.Mesh), tải các tệp lưới 3D dưới dạng các đối tượng `trimesh`.

Khi bạn tải một bộ dữ liệu lưới và gọi cột lưới, tính năng [Mesh](/docs/datasets/main/vi/package_reference/main_classes#datasets.Mesh) sẽ tự động giải mã tệp lưới:

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

Tùy thuộc vào nội dung tệp, `trimesh` có thể trả về một đối tượng `trimesh.Trimesh` hoặc một đối tượng `trimesh.Scene`.

> [!WARNING]
> Truy cập vào bộ dữ liệu lưới bằng chỉ số hàng trước, sau đó là cột `mesh` - `dataset[0]["mesh"]` - để tránh việc giải mã tất cả các tệp lưới trong bộ dữ liệu. Nếu không, đây có thể là một quy trình chậm và tốn thời gian nếu bạn có một bộ dữ liệu lớn.

Với `decode=False`, kiểu [Mesh](/docs/datasets/main/vi/package_reference/main_classes#datasets.Mesh) cung cấp cho bạn đường dẫn hoặc các byte của tệp mesh mà không giải mã nó bằng `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'}
```

Tính năng [Mesh](/docs/datasets/main/vi/package_reference/main_classes#datasets.Mesh) hỗ trợ các tệp `.glb`, `.gltf`, `.ply` và `.stl`. Đối với các byte nhúng, `path` được lưu trữ sẽ được sử dụng để suy ra loại tệp mesh.

## Tính năng Json

Datasets được xây dựng dựa trên Arrow, một định dạng cột, do đó chúng yêu cầu mỗi ví dụ phải có cùng kiểu và các kiểu con, và các từ điển phải có cùng các khóa và kiểu giá trị. Việc tải một dataset sẽ gây ra lỗi khi các trường có kiểu không khớp, và sẽ điền các trường bị thiếu trong các từ điển bằng None để đảm bảo tất cả các từ điển đều có cùng các khóa và kiểu giá trị.

Để tránh điều này và cho phép các kiểu dữ liệu hỗn hợp mà không gặp lỗi, bạn có thể sử dụng `on_mixed_types="use_json"` hoặc chỉ định `features=` với kiểu [Json](/docs/datasets/main/vi/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"}]
```

Điều này cũng hữu ích cho các danh sách từ điển có các khóa và giá trị tùy ý, để tránh điền các trường thiếu bằng 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
```

Một ví dụ khác với dữ liệu gọi công cụ và đối số `on_mixed_types="use_json"` (có ích để không phải chỉ định `features=` thủ công):

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

