Chuyển sang huggingface_hub v1.0

Phiên bản v1.0 là một cột mốc quan trọng đối với thư viện huggingface_hub. Nó đánh dấu cam kết của chúng tôi về sự ổn định của API và mức độ trưởng thành của thư viện. Chúng tôi đã thực hiện một số cải tiến và thay đổi gây mất tương thích để thư viện trở nên vững chắc và dễ sử dụng hơn.

Hướng dẫn này nhằm giúp bạn chuyển đổi mã hiện có sang phiên bản mới. Nếu bạn có bất kỳ câu hỏi hoặc phản hồi nào, vui lòng cho chúng tôi biết bằng cách mở một issue trên GitHub.

Python 3.9+

huggingface_hub hiện yêu cầu Python 3.9 trở lên. Python 3.8 không còn được hỗ trợ.

Chuyển đổi sang HTTPX

Thư viện huggingface_hub hiện sử dụng httpx thay vì requests cho các yêu cầu HTTP. Thay đổi này được thực hiện để cải thiện hiệu suất và hỗ trợ cả yêu cầu đồng bộ lẫn bất đồng bộ theo cùng một cách. Do đó, chúng tôi đã loại bỏ cả hai phụ thuộc requests và aiohttp.

Thay đổi gây mất tương thích

Đây là một thay đổi lớn ảnh hưởng đến toàn bộ thư viện. Mặc dù chúng tôi đã cố gắng thực hiện thay đổi này một cách minh bạch nhất có thể, bạn có thể cần cập nhật mã của mình trong một số trường hợp. Dưới đây là danh sách các thay đổi gây lỗi tương thích được đưa ra trong quá trình này:

• Cấu hình proxy: proxy “theo từng phương thức” không còn được hỗ trợ nữa. Proxy phải được cấu hình toàn cục bằng cách sử dụng các biến môi trường HTTP_PROXY và HTTPS_PROXY.
• Backend HTTP tùy chỉnh: Hàm configure_http_backend đã bị loại bỏ. Bạn nên sử dụng set_client_factory() và set_async_client_factory() để cấu hình các client HTTP.
• Xử lý lỗi: Các lỗi HTTP không còn kế thừa từ requests.HTTPError nữa, mà từ httpx.HTTPError. Chúng tôi khuyến nghị bắt HfHubHTTPError (nhập bằng from huggingface_hub.utils import HfHubHTTPError), đây là lớp con của requests.HTTPError trong v0.x và của httpx.HTTPError trong v1.x. Việc bắt lỗi từ huggingface_hub đảm bảo mã của bạn tương thích với cả phiên bản cũ và mới của thư viện.
• SSLError: httpx không có khái niệm SSLError. Nó giờ là httpx.ConnectError chung chung.
• LocalEntryNotFoundError: Lỗi này không còn kế thừa từ HTTPError nữa. Chúng tôi hiện định nghĩa EntryNotFoundError (mới) được kế thừa bởi cả LocalEntryNotFoundError (nếu không tìm thấy tệp trong bộ nhớ đệm cục bộ) và RemoteEntryNotFoundError (nếu không tìm thấy tệp trong kho trên Hub). Chỉ lỗi từ xa mới kế thừa từ HTTPError.
• InferenceClient: InferenceClient giờ có thể được sử dụng như một context manager. Điều này đặc biệt hữu ích khi streaming token từ một mô hình ngôn ngữ để đảm bảo kết nối được đóng đúng cách.
• AsyncInferenceClient: Tham số trust_env đã bị loại bỏ khỏi bộ khởi tạo của AsyncInferenceClient. Các biến môi trường được tin cậy mặc định bởi httpx. Nếu bạn không muốn tin cậy môi trường, bạn phải cấu hình bằng set_async_client_factory().

Để biết thêm chi tiết, bạn có thể xem PR #3328 đã giới thiệu httpx.

Tại sao là httpx?

Việc chuyển đổi từ requests sang httpx mang lại một số cải tiến chính, nâng cao hiệu suất, độ tin cậy và khả năng bảo trì của thư viện:

An toàn luồng và tái sử dụng kết nối: httpx được thiết kế an toàn về mặt luồng, cho phép chúng ta tái sử dụng an toàn cùng một client trên nhiều luồng. Việc tái sử dụng kết nối này giảm thiểu chi phí thiết lập các kết nối mới cho mỗi yêu cầu HTTP, cải thiện hiệu suất, đặc biệt khi thực hiện các yêu cầu thường xuyên đến Hub.

Hỗ trợ HTTP/2: httpx cung cấp hỗ trợ HTTP/2 bản địa, mang lại hiệu quả cao hơn khi thực hiện nhiều yêu cầu đến cùng một máy chủ (đúng với trường hợp sử dụng của chúng ta). Điều này giúp giảm độ trễ và tiết kiệm tài nguyên hơn so với HTTP/1.1.

API đồng bộ/phi đồng bộ thống nhất: Khác với cấu hình trước đây của chúng ta sử dụng các phụ thuộc riêng biệt requests (đồng bộ) và aiohttp (phi đồng bộ), httpx cung cấp cả client đồng bộ và phi đồng bộ với hành vi giống hệt nhau. Điều này đảm bảo rằng InferenceClient và AsyncInferenceClient có chức năng nhất quán và loại bỏ các khác biệt hành vi tinh vi từng tồn tại giữa hai triển khai.

Cải thiện xử lý lỗi SSL: httpx xử lý các lỗi SSL một cách tinh tế hơn, giúp việc gỡ lỗi các vấn đề kết nối trở nên dễ dàng và đáng tin cậy hơn.

Kiến trúc bền vững: httpx được bảo trì tích cực và được thiết kế cho các ứng dụng Python hiện đại. Ngược lại, requests đang ở chế độ bảo trì và sẽ không nhận được các bản cập nhật lớn như cải thiện an toàn luồng (thread-safety) hoặc hỗ trợ HTTP/2.

Xử lý biến môi trường tốt hơn: httpx cung cấp cách xử lý biến môi trường nhất quán hơn trong cả ngữ cảnh đồng bộ và bất đồng bộ, loại bỏ các điểm không nhất quán trước đó khi requests mặc định đọc biến môi trường cục bộ trong khi aiohttp thì không.

Việc chuyển sang httpx giúp huggingface_hub sở hữu một backend HTTP hiện đại, hiệu quả và dễ bảo trì. Trong khi hầu hết người dùng sẽ trải nghiệm hoạt động liền mạch, những cải tiến ở tầng sâu hơn mang lại hiệu suất và độ tin cậy tốt hơn cho mọi tương tác với Hub.

hf_transfer

Bây giờ tất cả các kho trên Hub đều được bật Xet và hf_xet là cách mặc định để tải xuống/tải lên tệp, chúng tôi đã loại bỏ hỗ trợ cho gói tùy chọn hf_transfer. Do đó, biến môi trường HF_HUB_ENABLE_HF_TRANSFER sẽ bị bỏ qua. Hãy sử dụng HF_XET_HIGH_PERFORMANCE thay thế.

Lớp Repository

Lớp Repository đã bị loại bỏ trong v1.0. Đây là một lớp bọc mỏng quanh CLI git để quản lý các kho lưu trữ. Bạn vẫn có thể sử dụng git trực tiếp trong terminal, nhưng cách tiếp cận được khuyến nghị là sử dụng API dựa trên HTTP trong thư viện huggingface_hub để có trải nghiệm mượt mà hơn, đặc biệt khi làm việc với các tệp lớn.

Dưới đây là sự ánh xạ từ lớp Repository cũ sang lớp HfApi mới:

phương thức Repository	phương thức HfApi
repo.clone_from	snapshot_download
repo.git_add + git_commit + git_push	upload_file(), upload_folder(), create_commit()
repo.git_tag	create_tag
repo.git_branch	create_branch

Lớp HfFolder

HfFolder được dùng để quản lý token truy cập của người dùng. Sử dụng login() để lưu một token mới, logout() để xóa token và whoami() để kiểm tra người dùng liên kết với token hiện tại. Cuối cùng, sử dụng get_token() để lấy token của người dùng trong một script.

Lớp InferenceApi

InferenceApi là một class để tương tác với Inference API. Hiện tại, bạn nên sử dụng class InferenceClient thay thế.

Các tính năng đã bị ngừng hỗ trợ khác

Một số phương thức và tham số đã bị loại bỏ trong v1.0. Các mục được liệt kê bên dưới đã bị ngừng hỗ trợ kèm theo thông báo cảnh báo trong v0.x.

• constants.hf_cache_home đã bị loại bỏ. Vui lòng sử dụng HF_HOME thay thế.
• Các tham số use_auth_token đã được loại bỏ khỏi tất cả các phương thức. Vui lòng sử dụng token thay thế.
• Phương thức get_token_permission đã bị loại bỏ.
• Phương thức update_repo_visibility đã bị loại bỏ. Vui lòng sử dụng update_repo_settings thay thế.
• Tham số is_write_action đã được loại bỏ khỏi build_hf_headers, cũng như write_permission khỏi login. Khái niệm “quyền ghi” đã bị loại bỏ và không còn liên quan nữa, vì token chi tiết (fine-grained tokens) hiện là cách tiếp cận được khuyến nghị.
• Tham số new_session trong login đã được đổi tên thành skip_if_logged_in để rõ ràng hơn.
• Các tham số resume_download, force_filename và local_dir_use_symlinks đã bị loại bỏ khỏi hf_hub_download và snapshot_download.
• Các tham số library, language, tags và task đã được loại bỏ khỏi list_models.

Lệnh cache CLI

Quản lý bộ nhớ đệm từ CLI đã được thiết kế lại để tuân theo quy trình làm việc lấy cảm hứng từ Docker. Lệnh huggingface-cli đã bị loại bỏ, hf (được giới thiệu trong v0.34) thay thế nó bằng một CLI tài nguyên-hành động rõ ràng hơn. Các lệnh hf cache scan và hf cache delete cũ cũng bị loại bỏ trong v1.0 và được thay thế bằng bộ ba lệnh mới bên dưới:

• hf cache ls liệt kê các mục cache dưới dạng bảng ngắn gọn, JSON hoặc CSV. Sử dụng --revisions để xem các phiên bản riêng lẻ, thêm các biểu thức --filter như size>1GB hoặc accessed>30d, và kết hợp chúng với --quiet khi bạn chỉ cần các định danh.
• hf cache rm xóa các mục cache được chọn. Truyền một hoặc nhiều repo ID (ví dụ model/bert-base-uncased) hoặc revision hashes, và tùy chọn thêm --dry-run để xem trước hoặc --yes để bỏ qua lời nhắc xác nhận. Lệnh này thay thế cả quy trình TUI tương tác và --disable-tui từ lệnh trước đó.
• hf cache prune thực hiện tác vụ dọn dẹp phổ biến là xóa các phiên bản không được tham chiếu trong một lần. Thêm --dry-run hoặc --yes theo cách tương tự như với hf cache rm.

Cuối cùng, phần mở rộng [cli] đã bị loại bỏ - CLI giờ được phát hành cùng với gói lõi huggingface_hub.

Hỗ trợ TensorFlow và Keras 2.x

Tất cả mã và các phụ thuộc liên quan đến TensorFlow đã được loại bỏ trong v1.0. Điều này bao gồm các thay đổi gây mất tương thích sau:

• huggingface_hub[tensorflow] không còn là một phụ thuộc bổ sung được hỗ trợ
• Các hàm tiện ích split_tf_state_dict_into_shards và get_tf_storage_size đã bị loại bỏ.
• Các phiên bản tensorflow, fastai và fastcore không còn được bao gồm trong các tiêu đề tích hợp sẵn.

Tích hợp Keras 2.x cũng đã bị loại bỏ. Điều này bao gồm lớp KerasModelHubMixin và các tiện ích save_pretrained_keras, from_pretrained_keras, và push_to_hub_keras. Keras 2.x là một thư viện cũ và không còn được bảo trì. Cách tiếp cận được khuyến nghị là sử dụng Keras 3.x, vốn được tích hợp chặt chẽ với Hub (tức là nó chứa các phương thức tích hợp để tải/đẩy lên Hub). Nếu bạn vẫn muốn làm việc với Keras 2.x, bạn nên hạ cấp huggingface_hub xuống phiên bản v0.x.

Giá trị trả về của upload_file và upload_folder

Các hàm upload_file() và upload_folder() giờ đây sẽ trả về URL của commit được tạo trên Hub. Trước đó, chúng trả về URL của tệp hoặc thư mục. Điều này nhằm thống nhất với giá trị trả về của create_commit(), delete_file() và delete_folder().

Update on GitHub