Bắt đầu với kho lưu trữ

Hướng dẫn thân thiện với người mới này sẽ giúp bạn có được các kỹ năng cơ bản cần thiết để tạo và quản lý kho lưu trữ của bạn trên Hub. Mỗi phần được xây dựng dựa trên phần trước đó, vì vậy bạn có thể thoải mái chọn nơi bắt đầu!

Yêu cầu

Tài liệu này cho thấy cách xử lý các kho lưu trữ thông qua giao diện web cũng như thông qua terminal. Không có yêu cầu nào khi làm việc với UI. Nếu bạn muốn làm việc với terminal, vui lòng làm theo các hướng dẫn cài đặt này.

Nếu bạn chưa có git khả dụng dưới dạng lệnh CLI, bạn sẽ cần cài đặt Git cho nền tảng của mình. Bạn cũng cần cài đặt Git-Xet, công cụ sẽ được sử dụng để xử lý các tệp lớn như hình ảnh và trọng số mô hình.

Để có thể tải xuống và tải lên các tệp lớn từ Git, bạn cần cài đặt tiện ích mở rộng Git Xet.

Để có thể đẩy mã nguồn của bạn lên Hub, bạn cần xác thực theo một cách nào đó. Cách dễ nhất là cài đặt hf CLI và chạy lệnh đăng nhập:

# Install hf:
#   brew install hf
#   or
#   pip install hf
hf auth login

Nội dung trong phần Getting Started của tài liệu này cũng có sẵn dưới dạng video!

Tạo một kho lưu trữ

Thông qua giao diện web của Hub, bạn có thể dễ dàng tạo kho lưu trữ, thêm tệp (kể cả tệp lớn!), khám phá các mô hình, trực quan hóa các khác biệt và nhiều hơn nữa. Trên Hub có ba loại kho lưu trữ, và trong hướng dẫn này bạn sẽ tạo một kho lưu trữ mô hình để minh họa. Để biết thông tin về việc tạo và quản lý mô hình, bộ dữ liệu và Spaces, hãy tham khảo tài liệu tương ứng của chúng.

1. Để tạo một kho lưu trữ mới, hãy truy cập huggingface.co/new:

2. Chỉ định chủ sở hữu của kho lưu trữ: đây có thể là bạn hoặc bất kỳ tổ chức nào mà bạn đang tham gia.

3. Nhập tên mô hình của bạn. Đây cũng sẽ là tên của kho lưu trữ.

4. Chỉ định xem bạn muốn mô hình của mình là công khai hay riêng tư.

5. Chỉ định giấy phép. Bạn có thể để trống trường License cho bây giờ. Để tìm hiểu về giấy phép, hãy truy cập tài liệu Licenses.

Sau khi tạo kho lưu trữ mô hình của bạn, bạn nên thấy một trang như sau:

Lưu ý rằng Hub sẽ yêu cầu bạn tạo một Model Card, bạn có thể tìm hiểu thêm trong tài liệu Model Cards. Việc bao gồm một Model Card trong kho lưu trữ model của bạn là một thực hành tốt, nhưng vì hiện tại chúng ta chỉ đang tạo một kho lưu trữ thử nghiệm nên có thể bỏ qua bước này.

Thêm tệp vào kho (Giao diện web)

Để thêm tệp vào kho của bạn qua giao diện web, hãy bắt đầu bằng cách chọn tab Files, điều hướng đến thư mục mong muốn, sau đó nhấp vào Add file. Bạn sẽ có tùy chọn để tạo tệp mới hoặc tải tệp lên trực tiếp từ máy tính của mình.

Tạo một tệp mới

Việc chọn tạo một tệp mới sẽ đưa bạn đến màn trình bày trình soạn thảo sau, nơi bạn có thể đặt tên cho tệp, thêm nội dung và lưu tệp với một thông báo tóm tắt các thay đổi của bạn. Thay vì trực tiếp cam kết tệp mới vào nhánh main của kho của bạn, bạn có thể chọn Open as a pull request để tạo một Pull Request.

Tải lên tệp

Nếu bạn chọn Tải tệp lên, bạn sẽ có thể chọn một tệp cục bộ để tải lên, kèm theo một thông báo tóm tắt các thay đổi của bạn đối với kho.

Tương tự như khi tạo tệp mới, bạn có thể chọn Open as a pull request để tạo một Pull Request thay vì thêm các thay đổi của bạn trực tiếp vào nhánh main của kho của bạn.

Thêm tệp vào kho (CLI)

Bạn có thể tải tệp lên kho của mình trực tiếp từ terminal bằng CLI hf. Sử dụng lệnh hf upload để đẩy các tệp cục bộ hoặc toàn bộ thư mục:

# Upload a single file to your model repo
hf upload your-username/your-model-name model.safetensors

# Upload an entire directory
hf upload your-username/your-model-name ./my-model-directory

# Upload to a dataset repo
hf upload your-username/your-dataset-name ./data --repo-type dataset

CLI hf xử lý các tệp lớn một cách tự động — không cần thiết lập thêm.

Thêm tệp vào kho (git)

Nhân bản các kho

Việc tải các kho xuống máy cục bộ được gọi là cloning. Bạn có thể sử dụng các lệnh sau để tải kho của bạn và điều hướng đến nó:

git clone https://huggingface.co/<your-username>/<your-model-name>
cd <your-model-name>

Hoặc đối với kho dữ liệu:

git clone https://huggingface.co/datasets/<your-username>/<your-dataset-name>
cd <your-dataset-name>

Bạn có thể clone qua SSH bằng lệnh sau:

git clone git@hf.co:<your-username>/<your-model-name>
cd <your-model-name>

Bạn cần thêm khóa SSH công khai của mình vào cài đặt người dùng để đẩy các thay đổi hoặc truy cập các kho lưu trữ riêng tư.

Cài đặt

Đã đến lúc, bạn có thể thêm bất kỳ tệp nào bạn muốn vào kho lưu trữ! 🔥

Bạn có các tệp lớn hơn 10MB không? Những tệp đó nên được theo dõi bằng git-xet, bạn có thể khởi tạo bằng:

git xet install

Khi bạn sử dụng Hugging Face để tạo một repository, Hugging Face tự động cung cấp một danh sách các phần mở rộng tệp phổ biến cho các tệp lớn phổ biến trong Machine Learning trong tệp .gitattributes, mà git-xet sử dụng để theo dõi các thay đổi đối với tệp lớn của bạn một cách hiệu quả. Tuy nhiên, bạn có thể cần thêm các phần mở rộng mới nếu các kiểu tệp của bạn chưa được xử lý. Bạn có thể thực hiện điều này bằng git xet track "*.your_extension".

Đẩy tệp

Bạn có thể sử dụng Git để lưu các tệp mới và mọi thay đổi đối với các tệp đã tồn tại dưới dạng một nhóm các thay đổi được gọi là commit, có thể được hiểu là một “phiên bản” của dự án. Để tạo một commit, bạn phải add các tệp để Git biết rằng chúng ta đang có kế hoạch lưu các thay đổi và sau đó commit những thay đổi đó. Để đồng bộ commit mới với Hugging Face Hub, bạn sau đó push commit đó lên Hub.

# Create any files you like! Then...
git add .
git commit -m "First model version"  # You can choose any descriptive message
git push

Và bạn đã hoàn tất! Bạn có thể kiểm tra kho lưu trữ của mình trên Hugging Face với tất cả các tệp vừa được thêm vào. Ví dụ, trong ảnh chụp màn hình bên dưới, người dùng đã thêm một số tệp. Lưu ý rằng một số tệp trong ví dụ này có kích thước 1.04 GB, do đó kho lưu trữ sử dụng Xet để theo dõi chúng.

Nếu bạn đã clone kho mã nguồn bằng HTTP, bạn có thể được yêu cầu nhập tên người dùng và mật khẩu ở mỗi thao tác push. Cách đơn giản nhất để tránh việc lặp lại là chuyển sang SSH thay vì HTTP. Ngoài ra, nếu bạn bắt buộc phải dùng HTTP, bạn có thể thấy hữu ích khi thiết lập một git credential helper để tự động điền tên người dùng và mật khẩu.

Xem lịch sử của một kho

Mỗi khi bạn thực hiện chu kỳ add-commit-push, kho sẽ theo dõi mọi thay đổi bạn đã thực hiện đối với các tệp của mình. Giao diện cho phép bạn khám phá các tệp mô hình và các commit, đồng thời xem sự khác biệt (còn được gọi là diff) do mỗi commit gây ra. Để xem lịch sử, bạn có thể nhấp vào liên kết History: X commits.

Bạn có thể nhấp vào một commit cụ thể để xem những thay đổi mà commit đó đã đưa vào: