Chuyển dữ liệu sang các kho lưu trữ

Hướng dẫn này cho thấy cách di chuyển các bộ dữ liệu lớn vào Storage Bucket từ bất kỳ vị trí nào mà chúng đang tồn tại: ổ đĩa cục bộ, một đám mây khác, hoặc Hub. Tìm nguồn của bạn trong bảng bên dưới và chuyển đến phần tương ứng.

Mọi nơi có thể, hãy để dữ liệu của bạn có thể đọc được như một hệ thống tệp và chạy hf sync. Công cụ này loại bỏ trùng lặp trên máy khách, nên bạn sẽ tải lên ít byte hơn so với việc sao chép thô.

Tổng quan

Lý do hf sync là mặc định:

• Bạn tải lên ít hơn. hf sync tải lên thông qua client Xet, công cụ này sẽ chia nhỏ và khử trùng lặp dữ liệu của bạn trước, nên chỉ các khối mà Hub chưa từng thấy mới được gửi đi. Việc sao chép thô (ví dụ, rclone qua cổng S3) sẽ truyền tải mọi byte.
• Nhanh hơn hoặc tương đương. Trong các lần di chuyển dữ liệu mà chúng tôi đã hỗ trợ cho đến nay, hf sync trên nguồn được gắn (mounted) đã đạt hoặc vượt rclone về thông lượng.

Trước khi bắt đầu

Tất cả các lệnh trong hướng dẫn này sử dụng hf, Hugging Face CLI. Đầu ra trợ giúp của nó có thể được đọc bởi agent, vì vậy một coding agent có thể tự lắp ráp và giám sát quá trình di chuyển cho bạn (xem CLI for AI Agents). Hãy xem xét các lệnh trước khi chạy chúng ở quy mô lớn.

1. Cài đặt CLI. Client Xet được cung cấp kèm theo.

   Đã sao chép

   curl -LsSf https://hf.co/cli/install.sh | bash
   hf version

2. Đăng nhập bằng token có quyền Write (tạo một token):

   Đã sao chép

   hf auth login
   hf auth whoami

3. Tạo bucket đích. <namespace> là tên người dùng hoặc tổ chức của bạn. Nếu không có --region, bucket sẽ được đặt trong khu vực lưu trữ mặc định của namespace, luôn là khu vực Mỹ đối với các gói ngoài Team & Enterprise. Với các gói đó, hãy truyền --region us hoặc --region eu để chọn.

   Đã sao chép

   hf buckets create <namespace>/<bucket> --private

Bắt đầu bằng một lần chạy thử. Dù bạn dùng phương án nào, hãy diễn tập trên một tập con nhỏ (một thư mục, hoặc một mẫu --include), kiểm tra kết quả bằng --dry-run và hf buckets ls, sau đó mới khởi chạy quá trình di chuyển toàn bộ. Mọi phương án trong hướng dẫn này đều có thể tiếp tục từ điểm dừng, nên một lần chạy thử không tốn thêm chi phí gì.

Từ ổ đĩa cục bộ hoặc hệ thống tệp cụm

Sử dụng phương pháp này khi dữ liệu của bạn nằm trên ổ đĩa cục bộ, một volume được gắn, hoặc khu vực scratch của cụm: bất kỳ thứ gì mà máy có thể đọc dưới dạng tệp. Đây cũng là bước cuối cùng của mọi đường dẫn cloud bên dưới, sau khi nguồn đã được gắn.

hf sync ./data hf://buckets/<namespace>/<bucket>/data

hf sync so sánh nguồn và đích, chỉ chuyển phần khác biệt, do đó việc chạy lại cùng một lệnh sẽ tiếp tục quá trình di chuyển bị gián đoạn: các tệp đã tải lên sẽ được bỏ qua. Các biến thể phổ biến:

# Mirror exactly: also delete destination files that are gone from the source
hf sync ./data hf://buckets/<namespace>/<bucket>/data --delete

# Preview what would transfer, without uploading
hf sync ./data hf://buckets/<namespace>/<bucket>/data --dry-run

# Only some files
hf sync ./data hf://buckets/<namespace>/<bucket>/data --include "*.parquet" --exclude "tmp/*"

Để xem xét một cuộc di chuyển quy mô lớn trước khi thực thi, hãy ghi kế hoạch ra tệp, kiểm tra nó, sau đó áp dụng. Cách này quét nguồn và đích chỉ một lần, thay vì quét một lần cho chạy thử và một lần nữa cho chạy thật.

hf sync ./data hf://buckets/<namespace>/<bucket>/data --plan plan.jsonl   # scan once, write the plan
hf sync --apply plan.jsonl                                                # run exactly that plan

Chạy --apply từ thư mục nơi bạn đã tạo kế hoạch, vì kế hoạch ghi lại đường dẫn nguồn đúng như bạn đã nhập. --apply không kiểm tra những gì đã được tải lên, vì vậy để tiếp tục một lần chạy bị gián đoạn, hãy chạy lại lệnh hf sync thông thường.

Để xác minh, hãy kiểm tra xem một lần chạy thử có còn gì cần chuyển không, và kiểm tra ngẫu nhiên nội dung:

hf sync ./data hf://buckets/<namespace>/<bucket>/data --dry-run
hf buckets ls hf://buckets/<namespace>/<bucket>/data

Tinh chỉnh

• Giữ cache trên ổ đĩa nhanh. Client Xet lưu cache các chunk và chỉ mục khử trùng lặp (shard cache) dưới HF_HOME. Chỉ định HF_HOME đến ổ NVMe cục bộ nếu thư mục home của bạn không nằm trên ổ NVMe.
• Bật chế độ hiệu năng cao cho các thao tác di chuyển hàng loạt trên máy có tài nguyên mạnh. HF_XET_HIGH_PERFORMANCE=1 tăng mức độ song song, kích thước bộ đệm và số lượng tệp được nạp cùng lúc, giúp client tận dụng mọi lõi CPU và bão hòa mạng. Chế độ này dành cho máy có băng thông cao và ổ đĩa nhanh; với các phiên bản hf_xet trước 1.7.0, chỉ nên dùng khi có ít nhất 64 GB RAM (kiểm tra bằng hf env). Xem Biến môi trường.
• Giới hạn bộ nhớ đệm shard. Giới hạn kích thước của nó là mềm: bộ nhớ đệm chỉ được dọn dẹp vào đầu mỗi lần chạy, nên trong một lần chạy dài, nó có thể tăng vượt xa giới hạn. Trong một lần di chuyển dữ liệu lớn, đặc biệt ở chế độ hiệu năng cao, nó có thể tăng lên hàng trăm GB và lấp đầy ổ đĩa, khiến lần chạy bị hủy. Đặt HF_XET_SHARD_CACHE_SIZE_LIMIT thấp hơn thoải mái so với dung lượng trống trên ổ đĩa, nhưng không thấp hơn mức bạn cần: bộ nhớ đệm kích thước X sẽ khử trùng lặp cho khoảng 1000 × X dữ liệu. Xem Bộ nhớ đệm Shard.

Đặt các giá trị này trước khi bắt đầu đồng bộ hóa. Kích thước chấp nhận các giá trị dễ đọc như 64gb:

export HF_HOME=/mnt/nvme/hf                 # chunk and shard caches on NVMe
export HF_XET_HIGH_PERFORMANCE=1            # use all cores and the full network
export HF_XET_SHARD_CACHE_SIZE_LIMIT=64gb   # keep the shard cache under free disk space

hf sync ./data hf://buckets/<namespace>/<bucket>/data

Tách theo đường dẫn con (thực nghiệm)

Với các bộ dữ liệu rất lớn, bạn có thể chia nguồn thành các đường dẫn con và chạy nhiều tiến trình hf sync cùng lúc. Kiểm tra ban đầu cho thấy thông lượng tăng gần như tuyến tính, nhưng điều này cần được xác thực thêm. Hai quy tắc:

• Tách theo dữ liệu liên quan để tệp của mỗi worker khử trùng lặp tốt với nhau.
• Gán cho mỗi worker một HF_HOME riêng để chúng không cạnh tranh bộ nhớ đệm. Mỗi bộ nhớ đệm chiếm dung lượng đĩa, vì vậy hãy chia HF_XET_SHARD_CACHE_SIZE_LIMIT giữa các worker.

HF_HOME=/mnt/nvme/hf-a hf sync ./data/groupA hf://buckets/<namespace>/<bucket>/groupA &
HF_HOME=/mnt/nvme/hf-b hf sync ./data/groupB hf://buckets/<namespace>/<bucket>/groupB &
wait

Một tiến trình duy nhất chia sẻ một bộ nhớ đệm và khử trùng lặp tốt nhất, vì vậy chỉ tách khi một tiến trình không thể bão hòa mạng của bạn.

Xử lý sự cố

Từ AWS S3 hoặc lưu trữ tương thích S3

hf sync không đọc các URL s3://, vì vậy hãy gắn (mount) bucket nguồn như một hệ thống tệp bằng Mountpoint for Amazon S3, sau đó đồng bộ từ điểm gắn. Dữ liệu của bạn vẫn đi qua client Xet, nên bạn sẽ nhận được tính năng khử trùng lặp phía client.

mount-s3 my-source-bucket /mnt/src
hf sync /mnt/src hf://buckets/<namespace>/<bucket>
umount /mnt/src

Đối với các kho lưu trữ tương thích S3 như Cloudflare R2 hoặc MinIO, hãy thêm --endpoint-url <url> vào mount-s3. Đối với bucket công khai cho phép đọc ẩn danh, chẳng hạn như các bucket trong đăng ký AWS Open Data, hãy thêm --no-sign-request. Việc xác minh, tinh chỉnh và khắc phục sự cố giống như đối với dữ liệu cục bộ.

Phương án thay thế: rclone thông qua cổng S3

Sử dụng phương pháp này nếu bạn đã đang chạy rclone và không muốn mount. Điểm đánh đổi: rclone gửi mọi byte qua cổng S3 mà không có loại bỏ trùng lặp phía client, do đó nó truyền tải nhiều hơn hf sync. Bạn cần thông tin xác thực S3 cho cổng.

Hãy sử dụng rclone 1.70 hoặc mới hơn (kiểm tra bằng rclone version, nâng cấp từ rclone downloads). Các phiên bản cũ có thể hết bộ nhớ khi liệt kê các bucket rất lớn. Lời khuyên cũ thường đề xuất --fast-list; với rclone mới, bạn không cần đến nó, và trên một danh sách liệt kê khổng lồ, nó sẽ giữ mọi thứ trong bộ nhớ và có thể gây ra cùng một sự cố.

Thêm gateway dưới dạng remote trong ~/.config/rclone/rclone.conf, bên cạnh remote cho nguồn của bạn (aws bên dưới):

[hf]
type = s3
provider = Other
endpoint = https://s3.hf.co/<namespace>
access_key_id = HFAK...
secret_access_key = ...
region = us-east-1
force_path_style = true
list_version = 2
upload_cutoff = 256M
chunk_size = 256M

Gateway chỉ hỗ trợ ListObjectsV2, do đó list_version = 2 là bắt buộc. Với 256M phần, các tệp lớn sẽ được chia thành ít phần hơn nhiều so với mặc định 5M của rclone. rclone giữ 4 phần cho mỗi thao tác truyền trong bộ nhớ, vì vậy --transfers 16 bên dưới cần khoảng 16 GB RAM; hãy giảm giá trị này trên máy có cấu hình nhỏ hơn. Sau đó, sao chép và kiểm tra:

rclone copy aws:my-source-bucket hf:<bucket> --transfers 16 --checkers 16 --progress
rclone check aws:my-source-bucket hf:<bucket>

rclone copy chỉ chuyển các đối tượng bị thiếu hoặc đã thay đổi, do đó việc chạy lại để tiếp tục là an toàn. Trước khi nhập một lượng lớn dữ liệu, hãy đọc giới hạn của gateway, đặc biệt là các quy tắc đặt tên khóa đối tượng.

Từ Google Cloud Storage hoặc Azure Blob Storage

Cách tiếp cận tương tự như S3: gắn (mount) nguồn bằng trình điều khiển (driver) riêng của đám mây đó, sau đó chạy hf sync.

Google Cloud Storage: gắn với gcsfuse.

gcsfuse my-gcs-bucket /mnt/src
hf sync /mnt/src hf://buckets/<namespace>/<bucket>

Azure Blob Storage: gắn với blobfuse2. Tệp cấu hình nêu tên tài khoản lưu trữ và container của bạn.

blobfuse2 mount /mnt/src --config-file=./blobfuse2.yaml
hf sync /mnt/src hf://buckets/<namespace>/<bucket>

Nếu không có mount, bạn có thể sử dụng rclone (công cụ này đọc GCS và Azure một cách bản địa; hãy tái sử dụng remote hf ở trên, với cùng mức đánh đổi là không khử trùng lặp), hoặc chạy quá trình di trú dưới dạng một Job.

Chạy quá trình di trú trong nền bằng Jobs

Jobs chạy một script trên hạ tầng tính toán của Hugging Face: bạn chọn phần cứng, khởi chạy từ CLI và trả phí theo phút. Hãy dùng nó khi bạn muốn một quy trình di chuyển dữ liệu dài, nhiều TB chạy tự động thay vì trên laptop hoặc một phiên mà bạn phải giữ mở.

1. Viết script di chuyển (migrate.py). Ví dụ này sao chép từng đối tượng trong một tiền tố S3 vào một bucket thông qua client Xet, nhờ đó các thao tác ghi được khử trùng lặp. Nó phù hợp cho việc sao chép một lần một tiền tố có kích thước vừa phải; đối với các tiền tố rất lớn, hãy xem hf-s3ream. Điều chỉnh các cài đặt ở đầu:

# /// script
# dependencies = ["huggingface_hub", "boto3", "tqdm"]
# ///
import boto3
from botocore import UNSIGNED
from botocore.config import Config
from huggingface_hub import HfFileSystem
from tqdm.contrib.concurrent import thread_map

# --- adapt these ---
SRC_BUCKET = "my-source-bucket"
SRC_PREFIX = "some/prefix/"
DST = "buckets/<namespace>/<bucket>"
WORKERS = 8   # files copied in parallel
# -------------------

s3 = boto3.client("s3")   # AWS credentials come from the Job's secrets
# For a public bucket (for example from the AWS Open Data registry), read anonymously
# instead, and drop the AWS secrets from the launch command:
# s3 = boto3.client("s3", config=Config(signature_version=UNSIGNED))
fs = HfFileSystem()       # HF token comes from the Job's HF_TOKEN secret

# List the destination once: {path: size} of the files already copied
done = {path: info["size"] for path, info in fs.find(DST, detail=True).items()}

# List the source and keep the objects not copied yet
todo = []
pages = s3.get_paginator("list_objects_v2").paginate(Bucket=SRC_BUCKET, Prefix=SRC_PREFIX)
for page in pages:
    for obj in page.get("Contents", []):
        key = obj["Key"]
        if key.endswith("/"):
            continue  # folder marker: bucket keys can't end with "/"
        if done.get(f"{DST}/{key}") != obj["Size"]:
            todo.append(key)

def copy(key):
    body = s3.get_object(Bucket=SRC_BUCKET, Key=key)["Body"]
    with fs.open(f"{DST}/{key}", "wb") as out:
        for chunk in iter(lambda: body.read(64 << 20), b""):
            out.write(chunk)

# Copy WORKERS files at a time, with a progress bar
thread_map(copy, todo, max_workers=WORKERS)

• Mỗi đối tượng được lưu tạm trên đĩa của Job và được tải lên khi nó được đóng, do đó đĩa phải chứa được WORKERS đối tượng lớn nhất của bạn cùng lúc. Tăng WORKERS để tăng tốc độ xử lý nhiều đối tượng nhỏ; giảm nó cho các đối tượng rất lớn.
• Các tệp đã có trong bucket với cùng kích thước sẽ bị bỏ qua, do đó việc chạy lại script sẽ tiếp tục quá trình sao chép bị gián đoạn. Script sẽ không sao chép lại tệp nguồn đã thay đổi nhưng giữ nguyên kích thước: để đồng bộ bucket với nguồn đang thay đổi, hãy gắn (mount) nguồn và chạy hf sync thay vào đó.

Đối với GCS hoặc Azure, hãy thay boto3 bằng SDK của đám mây tương ứng (google-cloud-storage, azure-storage-blob) và điều chỉnh các lệnh liệt kê và đọc. Phần đích vẫn giữ nguyên.

2. Chạy nó như một Job nền, truyền thông tin xác thực của bạn dưới dạng secrets:

hf jobs uv run --detach --flavor cpu-performance --timeout 24h \
  --secrets HF_TOKEN \
  --secrets AWS_ACCESS_KEY_ID \
  --secrets AWS_SECRET_ACCESS_KEY \
  migrate.py

Mỗi --secrets NAME truyền giá trị của biến đó từ môi trường của bạn (với HF_TOKEN, token của tài khoản đã đăng nhập sẽ được sử dụng nếu biến này chưa được đặt). Các Job dừng lại sau 30 phút theo mặc định, vì vậy hãy đặt --timeout đủ dài cho toàn bộ quá trình chuyển; nếu một Job dừng sớm, hãy khởi động lại nó và nó sẽ bỏ qua các tệp đã được sao chép.

--detach sẽ trả về ngay lập tức kèm theo Job ID. Theo dõi tiến độ bằng hf jobs logs -f <job_id>, liệt kê các lần chạy bằng hf jobs ls, và xem các tùy chọn phần cứng bằng hf jobs hardware.

Từ một kho Hub hoặc một bucket khác

Nếu dữ liệu đã có trên Hub, trong một kho lưu trữ mô hình hoặc bộ dữ liệu hoặc một bucket khác, hãy sao chép phía máy chủ. Đối với các tệp được theo dõi bởi Xet, chỉ các băm nội dung được di chuyển, do đó thao tác sao chép gần như tức thì và không có gì được tải lên lại.

# From a dataset repository into a bucket
hf buckets cp hf://datasets/<org>/<dataset>/<path> hf://buckets/<namespace>/<bucket>/<path>

# From one bucket to another
hf buckets cp hf://buckets/<namespace>/<bucket-a>/<path> hf://buckets/<namespace>/<bucket-b>/<path>

• Nguồn và đích phải nằm trong cùng một khu vực lưu trữ.
• Bạn cần quyền đọc đối với nguồn và quyền ghi đối với đích.
• Các tệp nhỏ không được Xet theo dõi (cấu hình, README) sẽ được tải xuống và tải lên lại tự động.
• Việc sao chép từ một bucket trở lại vào một repository hiện chưa khả dụng; tính năng này đang nằm trong lộ trình phát triển.

Xem Copy tệp giữa các repo và bucket cho tương đương trong Python.

Các tiền tố S3 rất lớn với hf-s3ream

hf-s3ream là một công cụ cộng đồng ở giai đoạn đầu (alpha), không phải là sản phẩm được Hugging Face hỗ trợ chính thức. Hãy thử nghiệm nó trên một tiền tố nhỏ trước khi sử dụng cho một cuộc di chuyển quy mô lớn.

hf-s3ream (mã nguồn trên GitHub, Apache-2.0) thực hiện sao chép từ S3 sang bucket với kích thước lớn từ giao diện web:

1. Đăng nhập bằng Hugging Face.
2. Nhập tiền tố nguồn S3, bucket đích và thông tin xác thực AWS của bạn. Đối với bucket công khai cho phép đọc ẩn danh, bật Public bucket: không cần thông tin xác thực AWS, và Jobs đọc S3 không ký.
3. Analyze chạy một lần thử nghiệm chi phí thấp để kiểm tra quyền truy cập, phát hiện khu vực nguồn và đề xuất cấu hình. Nó sẽ tạo bucket đích (riêng tư) nếu bucket đó chưa tồn tại.
4. Run khởi tạo một tác vụ planner. Planner xây dựng kế hoạch sao chép dựa trên khoảng, khởi động các tác vụ copier và hiển thị tiến độ trên đồ họa trực tiếp. Việc sao chép vẫn tiếp tục chạy nếu bạn đóng tab, nhưng trang sẽ không kết nối lại với nó. Để dừng việc sao chép, hãy nhấp vào Stop copy hoặc hủy tác vụ planner (hf jobs cancel <planner-job-id>): planner sẽ hủy các copier của nó.

hf-s3ream chạy trên Jobs dưới tài khoản của bạn, do đó các Jobs sẽ được tính phí cho bạn. Các bucket S3 chỉ cho phép truy cập từ mạng riêng (VPC) không thể được truy cập từ Jobs.

Chạy quy trình di chuyển quy mô lớn ở đâu

Đối với việc di chuyển dữ liệu nhiều TB, bạn thường sẽ chạy quá trình chuyển trên một VM trên cloud thay vì trên laptop. Nếu bạn không muốn quản lý VM, hãy chạy nó dưới dạng một Job.

• Chạy trên cùng một cloud và khu vực với nguồn của bạn. Việc đọc nguồn qua mạng nội bộ là nhanh nhất và rẻ nhất, và chi phí egress từ cloud nguồn thường là lớn nhất. Sau đó, quá trình tải lên sẽ diễn ra qua internet đến Hugging Face (khu vực Mỹ nằm trên AWS us-east-1).
• Sử dụng một tiến trình với nhiều luồng. Một lệnh hf sync duy nhất ở chế độ hiệu năng cao chia sẻ một bộ nhớ đệm khử trùng lặp. Chỉ chia theo đường dẫn con khi một tiến trình không thể bão hòa mạng của bạn.
• Giữ cho các phiên chạy dài được duy trì. Qua SSH, hãy bắt đầu quá trình di chuyển bên trong tmux (hoặc screen, hoặc nohup) để nó không bị gián đoạn khi phiên kết nối bị ngắt: tmux new -s migrate, tách ra bằng cách nhấn Ctrl-b rồi d, và kết nối lại sau đó bằng tmux attach -t migrate.

Điểm khởi đầu về kích thước, để xác thực trong một lần chạy thử:

Các bước tiếp theo

• Sử dụng dữ liệu tại chỗ. Gắn bucket như một hệ thống tệp cục bộ bằng hf-mount, hoặc như một volume trong Jobs và Spaces.
• Đọc trực tiếp từ các công cụ của bạn. pandas, Dask, PyArrow, Daft, DuckDB, 🤗 Datasets và Spark đọc các đường dẫn hf://buckets/... trực tiếp. Xem Tích hợp Bucket.

Đừng thực hiện nạp dữ liệu hàng loạt thông qua một mount. hf-mount lưu trữ các thao tác ghi vào một bộ đệm trên đĩa (/tmp/hf-mount-cache theo mặc định), và một cuộc di chuyển dữ liệu lớn qua nó có thể làm đầy đĩa đó. Hãy sử dụng một trong các phương thức ở trên để đưa dữ liệu vào bucket. Nếu bạn bắt buộc phải ghi một lượng lớn dữ liệu thông qua mount, hãy trỏ bộ đệm đến một đĩa có đủ dung lượng trống: hf-mount start --cache-dir /mnt/big bucket <namespace>/<bucket> /mnt/data (cờ này đặt trước bucket).