# 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](https://github.com/huggingface/huggingface_hub/issues).

## 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`](https://www.python-httpx.org/) 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 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/utilities#huggingface_hub.set_client_factory) và [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/vi/package_reference/utilities#huggingface_hub.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](/docs/huggingface_hub/v2.4.0/vi/package_reference/utilities#huggingface_hub.errors.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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/utilities#huggingface_hub.set_async_client_factory).

Để biết thêm chi tiết, bạn có thể xem [PR #3328](https://github.com/huggingface/huggingface_hub/pull/3328) đã giới thiệu `httpx`.

### Tại sao `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`](../package_reference/environment_variables) 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.upload_file), [upload_folder()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.upload_folder), [create_commit()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/authentication#huggingface_hub.login) để lưu một token mới, [logout()](/docs/huggingface_hub/v2.4.0/vi/package_reference/authentication#huggingface_hub.logout) để xóa token và [whoami()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.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](/docs/huggingface_hub/v2.4.0/vi/package_reference/inference_client#huggingface_hub.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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.upload_file) và [upload_folder()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.create_commit), [delete_file()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.delete_file) và [delete_folder()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_api#huggingface_hub.HfApi.delete_folder).