# Tiếp nhận Datasets

Dữ liệu thường được lưu trữ trong các cơ sở dữ liệu hoặc kho lưu trữ đám mây dưới các định dạng không phù hợp cho các quy trình làm việc AI. Việc nạp dữ liệu vào [Hub](https://huggingface.co/datasets) là một cách tốt để công bố chúng dưới dạng các bộ dữ liệu sẵn sàng cho AI, cho phép nạp, xử lý dữ liệu cũng như huấn luyện và đánh giá mô hình một cách dễ dàng và hiệu quả.

## Sử dụng `huggingface_hub`

Cách đơn giản nhất để nạp dữ liệu là chỉ cần tải các tệp dữ liệu lên bằng `huggingface_hub`.

Thư viện Python `huggingface_hub` cung cấp một bộ tính năng phong phú cho phép bạn quản lý các kho lưu trữ, bao gồm việc tạo kho và tải bộ dữ liệu lên Hub. Xem [tài liệu của thư viện client](/docs/huggingface_hub/index) để biết thêm.

Điều này có liên quan nếu dữ liệu của bạn là tĩnh/đóng băng và bạn có thể dễ dàng lấy một bản dump cục bộ của dữ liệu ở định dạng được Hub hỗ trợ (ví dụ: Parquet hoặc JSON Lines) với cấu trúc có thể sử dụng được (ví dụ: các trường được định nghĩa rõ ràng cho huấn luyện và đánh giá).

## Sử dụng `dlt`

[dlt](http://github.com/dlt-hub/dlt) là một thư viện Python mã nguồn mở cho việc di chuyển dữ liệu (ETL), hữu ích cho các nhà phát triển (và các tác tử của họ) khi xây dựng các đường ống dữ liệu. Nó có thể nạp dữ liệu từ nhiều loại nguồn khác nhau:

* Lưu trữ đám mây hoặc tệp
* REST APIs
* Cơ sở dữ liệu SQL
* Trình tạo Python

Các ví dụ về kiểu nguồn:

* `filesystem` (bao gồm s3, gs, az, abff, v.v.)
* `sql_database`, `mongodb`, `google_sheets`
* `notion`, `hubspot`, `rest_api`

Tìm loại nguồn của bạn từ [danh sách các nguồn](https://dlthub.com/docs/dlt-ecosystem/verified-sources) và tạo dự án `dlt` của bạn:

```
dlt init <source-type> filesystem
```

Sau đó, bạn có thể tạo tệp cấu hình `.dlt/secrets.toml` ở thư mục gốc của dự án dlt để định nghĩa Hub là đích hệ thống tệp cho các bộ dữ liệu của bạn, dựa trên giao thức `hf://`:

```toml
[destination.filesystem]
bucket_url = "hf://datasets/<namespace>"

[destination.filesystem.credentials]
hf_token = "hf_..."  # Your Hugging Face Access Token
```

Namespace nên là tên người dùng của bạn hoặc tên tổ chức/đội nhóm mà bạn muốn nạp bộ dữ liệu của mình vào.

Sau đó, mỗi dataset dlt sẽ tạo hoặc cập nhật một kho dataset Hugging Face. Tên kho là /, trong đó  là tên bạn đã dùng trong bucket_url (tổ chức hoặc nhóm của bạn), và  là dataset_name của pipeline.

Dưới đây là một ví dụ về pipeline:

```python
import dlt

@dlt.resource
def my_data():
    # One of the functions auto-generated by `dlt init` that you can customize,
    # or you can define your own python generator function.

    # Here is an example from the `chess` source type:
    for player in ['magnuscarlsen', 'rpragchess']:
        response = requests.get(f'https://api.chess.com/pub/player/{player}')
        response.raise_for_status()
        yield response.json()

# Requires bucket_url = "hf://datasets/<namespace>" in .dlt/secrets.toml
pipeline = dlt.pipeline(
    pipeline_name="my_pipeline",
    destination="filesystem",
    dataset_name="dataset_name",
)

pipeline.run(my_data())
```

Tùy chỉnh tài nguyên `dlt` để tải dữ liệu bạn muốn và phân tích các trường bạn muốn xuất bản trong bộ dữ liệu của mình, ví dụ như văn bản bạn cần cho việc huấn luyện và đánh giá.

## Sử dụng các thư viện khác

Một số thư viện như [🤗 Datasets](/docs/datasets/index), [Pandas](./datasets-pandas), [Polars](./datasets-polars), [Dask](./datasets-dask), [DuckDB](./datasets-duckdb), [Spark](./datasets-spark) hoặc [Daft](./datasets-daft) có thể nạp dữ liệu từ nhiều nguồn khác nhau vào Hub. Xem danh sách [Các thư viện được Hub Datasets hỗ trợ](./datasets-libraries) để biết thêm thông tin.

## Tiếp nhận dữ liệu thô

Nếu bạn đang nạp dữ liệu thô cần được chỉnh sửa thêm trước khi được phát hành dưới dạng bộ dữ liệu sẵn sàng cho AI, hoặc nếu bạn cần trải nghiệm tương tự S3, hãy cân nhắc nạp chúng vào [Hugging Face Storage Buckets](./storage-buckets). Để di chuyển một bộ sưu tập hiện có lớn vào bucket từ ổ đĩa cục bộ hoặc một đám mây khác, hãy xem [Hướng dẫn di chuyển](./storage-buckets-migration).

Nếu dữ liệu của bạn đã nằm trong một kho dataset, model hoặc Space, bạn có thể sao chép nó vào một bucket **trên máy chủ** — không cần tải xuống hoặc tải lên lại — bằng `hf buckets cp`:

```bash
hf cp hf://datasets/username/my-dataset/ hf://buckets/username/my-bucket/
```

Chỉ các hash nội dung Xet được di chuyển, do đó ngay cả các tệp rất lớn cũng được sao chép tức thì. Xem [Sao chép tệp giữa các kho và bucket](./storage-buckets#copying-files-between-repos-and-buckets).

## Tiếp nhận theo lịch

Có một số hạn chế khi cập nhật cùng một tệp trên Hub hàng nghìn lần. Ví dụ, bạn có thể muốn nạp các thế hệ của một máy chủ suy luận LLM đang chạy, các vết theo dõi của các tác tử trực tiếp, hoặc nhật ký của một quá trình huấn luyện mô hình đang chạy. Trong những trường hợp như vậy, việc tải dữ liệu lên Hub dưới dạng một tập dữ liệu là hợp lý, nhưng có thể khó thực hiện đúng cách. Lý do chính là bạn không muốn tạo phiên bản cho mỗi lần cập nhật dữ liệu của mình, vì điều đó sẽ khiến kho git trở nên không thể sử dụng được.

Có ba tùy chọn khả dụng:

* **Dùng Storage Bucket thay vì kho Dataset:** [Storage Buckets](/docs/hub/storage-buckets) cung cấp trải nghiệm tương tự S3, cho phép cập nhật tệp rất thường xuyên vì chúng không dựa trên git. Storage Buckets đặc biệt hữu ích cho dữ liệu chưa sẵn sàng để công bố dưới dạng dataset, ví dụ như dữ liệu vẫn đang phát triển hoặc cần thêm công đoạn tuyển chọn.
* **Sử dụng CommitScheduler**: `CommitScheduler` trong `huggingface_hub` cung cấp khả năng nạp dữ liệu gần như thời gian thực để giữ cho lịch sử git của kho Dataset ở mức dễ quản lý. Nó có thể được cấu hình để thực hiện các lệnh git commit theo các khoảng thời gian được định nghĩa bằng phút.
* **Sử dụng Hugging Face Jobs để lên lịch chạy các script nạp dữ liệu**: Hugging Face Jobs cung cấp cách để chạy và lên lịch các script python trên hạ tầng của Hugging Face. Hãy lên lịch để các script nạp dữ liệu chạy theo các khoảng thời gian được định nghĩa bằng cú pháp Cron.

### Tần suất cao khi sử dụng Storage Buckets

Ngược lại với các kho Datasets dựa trên git, bạn có thể cập nhật các tệp trên Storage Buckets với tốc độ rất cao, cung cấp khả năng nạp dữ liệu gần như thời gian thực.

Sử dụng `batch_bucket_files()` trong `huggingface_hub` để cập nhật các tệp trong một bucket:

```python
from huggingface_hub import batch_bucket_files

def update_bucket(local_files):
    destinations = [os.path.basename(local_file) for local_file in local_file]
    batch_bucket_files(bucket_id="username/bucket_name", add=[(local_file, dst) for local_file, dst in zip(local_files, destinations)])
```

Ngoài ra, bạn có thể thêm vào các tệp trong một Bucket và `flush()` cho mỗi mục mới:

```python
from huggingface_hub import hffs

with hffs.open("buckets/username/bucket_name/texts.jsonl", "a") as f:
    for text in live_texts_stream:
        f.write(json.dumps({"text": text}) + "\n")
        f.flush()
```

`HfFileSystem` được xây dựng dựa trên `fsspec`, có blocksize mặc định là 5MiB, điều này có nghĩa là thao tác flush thực chất chỉ tải dữ liệu lên khi đã có đủ một khối 5MiB dữ liệu mới được thêm vào. Nếu bạn muốn tải lên thường xuyên hơn, hãy giảm `blocksize` trong `hffs.open()` (ví dụ `hffs.open(..., blocksize=100 * 2 ** 10)` cho 100 kiB) hoặc sử dụng `f.flush(force=True)`.

Bộ lưu trữ của Hugging Face dựa trên Xet, cho phép I/O hiệu quả khi thêm vào các tệp: các bản tải lên được khử trùng lặp và chỉ dữ liệu mới được tải lên. Tìm thêm thông tin về việc nạp dữ liệu động vào các bucket trong [tài liệu bucket về việc tải lên](/docs/hub/storage-buckets#uploading-files) và trong [tài liệu chỉnh sửa dataset](./datasets-editing#only-upload-the-new-data).

### Gần thời gian thực bằng cách sử dụng `CommitScheduler`

Ý tưởng là chạy một tác vụ nền thường xuyên đẩy một thư mục cục bộ lên Hub. Bạn muốn lưu trữ dữ liệu lên Hub (có thể là hàng triệu mục), nhưng không cần lưu trữ theo thời gian thực đầu vào của từng người dùng. Thay vào đó, bạn có thể lưu dữ liệu cục bộ trong một tệp JSON và tải lên mỗi 10 phút. Ví dụ:

```python
import json
from huggingface_hub import CommitScheduler

folder_path = "path/to/files/to/ingest"
every = 10  # ingest every 10min

with CommitScheduler(repo_id="username/dataset_name", repo_type="dataset", folder_path=folder_path, every=every) as scheduler:
    # Write to the folder to ingest every 10min
    # For example:
    with open(folder_path + "/texts.jsonl", "a") as f:
        f.write(json.dumps({"text": text}) + "\n")
    ...
```

Xem cách nạp dữ liệu động mà không cần tải lại toàn bộ mỗi lần trong tài liệu về [chỉnh sửa tập dữ liệu](./datasets-editing#only-upload-the-new-data).

Tìm thêm thông tin về các lần tải lên được lên lịch trong [tài liệu huggingface_hub](/docs/huggingface_hub/guides/upload#scheduled-uploads).

### Dựa trên Cron bằng Hugging Face Jobs

Lập lịch chạy các script python để nạp dữ liệu theo lịch

Ví dụ, để chạy một script `ingest.py` mỗi 5 phút:

```bash
hf jobs scheduled uv run "*/5 * * * *" ingest.py
```

Khai báo các phụ thuộc của script [trong phần đầu của script](https://docs.astral.sh/uv/guides/scripts/#declaring-script-dependencies) hoặc sử dụng `--with`. Ví dụ, để chạy một pipeline `dlt` mỗi ngày lúc nửa đêm:

```bash
hf jobs scheduled uv run --with "dlt[hf]" "0 0 * * *" pipeline.py
```

Bạn có thể kiểm tra nhật ký của mọi lần chạy bằng cách sử dụng `hf jobs logs` hoặc trực tiếp trên trang Jobs trong tài khoản của bạn trên Hugging Face.

Tìm hiểu thêm thông tin về Hugging Face Jobs trong [tài liệu Jobs](/docs/hub/jobs-overview).