Hub documentation

Tích hợp thư viện của bạn với Hub

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Tích hợp thư viện của bạn với Hub

Hugging Face Hub hướng đến việc tạo điều kiện thuận lợi cho việc chia sẻ các mô hình học máy, checkpoint và các sản phẩm (artifacts). Nỗ lực này bao gồm việc tích hợp Hub vào nhiều thư viện bên thứ ba tuyệt vời trong cộng đồng. Một số thư viện đã được tích hợp bao gồm spaCy, Sentence Transformers, OpenCLIP và timm, cùng nhiều thư viện khác. Việc tích hợp có nghĩa là người dùng có thể tải xuống và tải lên tệp lên Hub trực tiếp từ thư viện của bạn. Chúng tôi hy vọng bạn sẽ tích hợp thư viện của mình và cùng chúng tôi dân chủ hóa trí tuệ nhân tạo cho tất cả mọi người.

Việc tích hợp Hub với thư viện của bạn mang lại nhiều lợi ích, bao gồm:

Lưu trữ mô hình miễn phí cho bạn và người dùng của bạn.
Phiên bản hóa tệp tích hợp - ngay cả với các tệp lớn - được hỗ trợ bởi Git-Xet.
Các tính năng cộng đồng (thảo luận, yêu cầu kéo, lượt thích).
Chỉ số sử dụng cho tất cả các mô hình được chạy với thư viện của bạn.

Hướng dẫn này sẽ giúp bạn tích hợp Hub vào thư viện của mình để người dùng có thể tận dụng tất cả các tính năng mà Hub cung cấp.

Trước khi bắt đầu, chúng tôi khuyến nghị bạn tạo một tài khoản Hugging Face để quản lý các kho lưu trữ và tệp của mình.

Nếu bạn cần hỗ trợ trong quá trình tích hợp, hãy thoải mái mở một issue, và chúng tôi sẽ rất sẵn lòng giúp bạn.

Thực hiện

Việc triển khai tích hợp một thư viện với Hub thường bao gồm việc cung cấp các phương thức tích hợp sẵn để tải mô hình từ Hub và cho phép người dùng đẩy các mô hình mới lên Hub. Phần này sẽ giới thiệu các kiến thức cơ bản về cách thực hiện điều đó bằng cách sử dụng thư viện huggingface_hub. Để có hướng dẫn chi tiết hơn, hãy xem hướng dẫn này.

Cài đặt

Để tích hợp thư viện của bạn với Hub, bạn cần thêm thư viện huggingface_hub như một phụ thuộc:

pip install huggingface_hub

Để biết thêm chi tiết về việc cài đặt huggingface_hub, hãy xem hướng dẫn này.

Trong hướng dẫn này, chúng ta sẽ tập trung vào các thư viện Python. Nếu bạn đã triển khai thư viện của mình bằng JavaScript, bạn có thể sử dụng @huggingface/hub thay thế. Phần còn lại của logic (tức là lưu trữ tệp, các mẫu mã, v.v.) không phụ thuộc vào ngôn ngữ lập trình.
npm add @huggingface/hub

Người dùng sẽ cần xác thực sau khi cài đặt thành công thư viện huggingface_hub. Cách xác thực dễ nhất là lưu token trên máy. Người dùng có thể thực hiện điều đó từ terminal bằng lệnh login():

hf auth login

Lệnh này cho họ biết nếu họ đã đăng nhập và yêu cầu nhập token. Token sau đó được xác thực và lưu trong thư mục HF_HOME (mặc định là ~/.cache/huggingface/token). Bất kỳ script hoặc thư viện nào tương tác với Hub sẽ sử dụng token này khi gửi yêu cầu.

Ngoài ra, người dùng có thể đăng nhập bằng cách gọi login() trong notebook hoặc script:

from huggingface_hub import login
login()

Xác thực là tùy chọn khi tải xuống các tệp từ các kho công khai trên Hub.

Tải tệp từ Hub

Integrations cho phép người dùng tải xuống một model từ Hub và khởi tạo nó trực tiếp từ thư viện của bạn. Điều này thường được thực hiện bằng cách cung cấp một phương thức (thường được gọi là from_pretrained hoặc load_from_hf) phải đặc thù cho thư viện của bạn. Để khởi tạo một model từ Hub, thư viện của bạn phải:

tải tệp từ Hub. Đây là nội dung chúng ta sẽ thảo luận ngay bây giờ.
tạo mô hình Python từ các tệp này.

Sử dụng phương thức hf_hub_download để tải xuống các tệp từ một kho trên Hub. Các tệp đã tải xuống được lưu trong bộ nhớ đệm: ~/.cache/huggingface/hub. Người dùng sẽ không phải tải lại tệp vào lần sử dụng tiếp theo, giúp tiết kiệm đáng kể thời gian với các tệp lớn. Hơn nữa, nếu kho được cập nhật với phiên bản mới của tệp, huggingface_hub sẽ tự động tải xuống phiên bản mới nhất và lưu vào bộ nhớ đệm. Người dùng không cần lo lắng về việc cập nhật tệp thủ công.

Ví dụ, tải tệp config.json từ kho lysandre/arxiv-nlp:

>>> from huggingface_hub import hf_hub_download
>>> config_path = hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
>>> config_path
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

config_path hiện chứa đường dẫn đến tệp đã tải xuống. Bạn được đảm bảo rằng tệp tồn tại và luôn ở trạng thái cập nhật.

Nếu thư viện của bạn cần tải xuống toàn bộ một kho lưu trữ, hãy sử dụng snapshot_download. Hàm này sẽ tự động tải xuống tất cả các tệp song song. Giá trị trả về là đường dẫn đến thư mục chứa các tệp đã tải xuống.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

Có nhiều tùy chọn để tải tệp từ một phiên bản cụ thể, lọc các tệp cần tải, chỉ định thư mục cache tùy chỉnh, tải xuống thư mục cục bộ, v.v. Xem hướng dẫn tải xuống để biết thêm chi tiết.

Tải tệp lên Hub

Bạn cũng có thể muốn cung cấp một phương thức để người dùng có thể đẩy mô hình của họ lên Hub. Điều này cho phép cộng đồng xây dựng hệ sinh thái các mô hình tương thích với thư viện của bạn. Thư viện huggingface_hub cung cấp các phương thức để tạo kho lưu trữ và tải lên tệp:

create_repo tạo một kho trên Hub.
upload_file và upload_folder tải tệp lên một kho trên Hub.

Phương thức create_repo tạo một kho lưu trữ trên Hub. Sử dụng tham số repo_id để cung cấp tên cho kho lưu trữ của bạn:

>>> from huggingface_hub import create_repo
>>> create_repo(repo_id="test-model")
'https://huggingface.co/lysandre/test-model'

Khi bạn kiểm tra tài khoản Hugging Face của mình, bạn sẽ thấy kho test-model dưới namespace của mình.

Phương thức upload_file tải một tệp lên Hub. Phương thức này yêu cầu các điều kiện sau:

Đường dẫn đến tệp cần tải lên.
Đường dẫn cuối cùng trong kho lưu trữ.
Kho mà bạn muốn đẩy các tệp lên.

Ví dụ:

>>> from huggingface_hub import upload_file
>>> upload_file(
...    path_or_fileobj="/home/lysandre/dummy-test/README.md", 
...    path_in_repo="README.md", 
...    repo_id="lysandre/test-model"
... )
'https://huggingface.co/lysandre/test-model/blob/main/README.md'

Nếu bạn kiểm tra tài khoản Hugging Face của mình, bạn sẽ thấy tệp bên trong kho của bạn.

Thông thường, một thư viện sẽ serialize mô hình vào một thư mục cục bộ và sau đó tải lên Hub toàn bộ thư mục đó một lần. Điều này có thể thực hiện bằng cách sử dụng upload_folder:

>>> from huggingface_hub import upload_folder
>>> upload_folder(
...     folder_path="/home/lysandre/dummy-test",
...     repo_id="lysandre/test-model",
... )

Để biết thêm chi tiết về cách tải tệp lên, hãy xem hướng dẫn tải lên.

Thẻ mô hình

Model cards là các tệp đi kèm với mô hình và cung cấp thông tin hữu ích. Về bản chất, model cards là các tệp Markdown đơn giản với thêm phần metadata. Model cards rất quan trọng cho khả năng tìm kiếm, tái lập và chia sẻ! Bạn có thể tìm thấy model card dưới dạng tệp README.md trong bất kỳ kho mô hình nào. Xem hướng dẫn về model cards để biết thêm chi tiết về cách tạo một model card tốt.

Nếu thư viện của bạn cho phép đẩy mô hình lên Hub, bạn nên tạo một thẻ mô hình tối thiểu với các metadata đã được điền sẵn (thường là library_name, pipeline_tag hoặc tags) và thông tin về cách mô hình được huấn luyện. Điều này sẽ giúp có một mô tả chuẩn hóa cho tất cả các mô hình được xây dựng bằng thư viện của bạn.

Đăng ký thư viện của bạn

Tuyệt vời! Bây giờ bạn đã có một thư viện có khả năng tải mô hình từ Hub và cuối cùng là đẩy các mô hình mới lên. Bước tiếp theo là đảm bảo rằng các mô hình của bạn trên Hub được tài liệu hóa tốt và tích hợp với nền tảng. Để làm điều này, các thư viện có thể được đăng ký trên Hub, mang lại một số lợi ích cho người dùng:

một nhãn đẹp có thể được hiển thị trên trang mô hình (ví dụ: KerasNLP thay vì keras-nlp)
một liên kết đến kho lưu trữ thư viện và tài liệu của bạn được thêm vào mỗi trang mô hình
có thể xác định một quy tắc đếm lượt tải tùy chỉnh
các đoạn mã có thể được tạo ra để minh họa cách tải mô hình bằng thư viện của bạn

Để đăng ký một thư viện mới, vui lòng mở một Pull Request tại đây theo các hướng dẫn bên dưới:

ID của thư viện nên được viết chữ thường và phân tách bằng dấu gạch nối (ví dụ: "adapter-transformers"). Hãy đảm bảo duy trì thứ tự bảng chữ cái khi mở PR.
Đặt repoName và prettyLabel với kiểu viết thân thiện với người dùng (ví dụ: DeepForest).
Đặt repoUrl với một liên kết đến mã nguồn của thư viện (thường là một kho GitHub).
(tùy chọn) đặt docsUrl với một liên kết đến tài liệu của thư viện. Nếu tài liệu nằm trong kho GitHub được đề cập ở trên, không cần đặt nó hai lần.
Đặt filter thành false.
(tùy chọn) định nghĩa cách đếm lượt tải xuống bằng cách đặt countDownload. Lượt tải xuống có thể được theo dõi theo phần mở rộng tệp hoặc tên tệp. Hãy đảm bảo không đếm trùng. Ví dụ, nếu việc tải một mô hình yêu cầu 3 tệp, quy tắc đếm lượt tải xuống chỉ được phép đếm trên 1 trong 3 tệp đó. Nếu không, số lượt tải xuống sẽ bị đánh giá quá cao. Lưu ý: nếu thư viện sử dụng một trong các tệp cấu hình mặc định (config.json, config.yaml, hyperparams.yaml, params.json, và meta.yaml, xem ở đây), thì không cần phải định nghĩa thủ công quy tắc đếm lượt tải xuống.
(tùy chọn) định nghĩa snippets để người dùng biết cách khởi tạo nhanh một mô hình. Chi tiết hơn bên dưới.

Trước khi mở PR, hãy đảm bảo rằng ít nhất một model được tham chiếu tại https://huggingface.co/models?other=my-library-name. Nếu không, metadata của model card cho các model liên quan phải được cập nhật với library_name: my-library-name (xem ví dụ). Nếu bạn không phải là chủ sở hữu của các model trên Hub, vui lòng mở PR (xem ví dụ).

Dưới đây là một ví dụ tối giản thêm tích hợp cho VFIMamba.

Đoạn mã

Chúng tôi khuyến nghị thêm một đoạn mã để giải thích cách sử dụng một mô hình trong thư viện hạ nguồn của bạn.

Để thêm một đoạn mã, bạn cần cập nhật tệp model-libraries-snippets.ts với các hướng dẫn cho mô hình của bạn. Ví dụ, tích hợp Asteroid bao gồm một đoạn mã ngắn về cách tải và sử dụng một mô hình Asteroid:

const asteroid = (model: ModelData) =>
`from asteroid.models import BaseModel
  
model = BaseModel.from_pretrained("${model.id}")`;

Thực hiện điều này cũng sẽ thêm một thẻ vào mô hình của bạn để người dùng có thể nhanh chóng nhận diện các mô hình từ thư viện của bạn.

Sau khi đoạn mã của bạn được thêm vào model-libraries-snippets.ts, bạn có thể tham chiếu đến nó trong model-libraries.ts như đã mô tả ở trên.

Tài liệu hóa thư viện của bạn

Cuối cùng, bạn có thể thêm thư viện của mình vào tài liệu của Hub. Hãy xem ví dụ như Setfit PR đã thêm SetFit vào tài liệu.

Update on GitHub

←Chủ đề nâng cao Nhiệm vụ→