Trả về mức hiện tại cho trình ghi log gốc của HuggingFace Hub.

HuggingFace Hub có các cấp độ ghi log sau:

• huggingface_hub.logging.CRITICAL, huggingface_hub.logging.FATAL
• huggingface_hub.logging.ERROR
• huggingface_hub.logging.WARNING, huggingface_hub.logging.WARN
• huggingface_hub.logging.INFO
• huggingface_hub.logging.DEBUG

Đặt cấp độ cho trình ghi log gốc của HuggingFace Hub.

Đặt mức độ chi tiết thành logging.INFO.

Đặt mức độ chi tiết thành logging.DEBUG.

Đặt mức độ chi tiết thành logging.WARNING.

Đặt mức độ chi tiết thành logging.ERROR.

Tắt việc lan truyền các đầu ra nhật ký của thư viện. Lưu ý rằng lan truyền nhật ký bị tắt theo mặc định.

Bật việc lan truyền các đầu ra nhật ký của thư viện. Vui lòng tắt trình xử lý mặc định của HuggingFace Hub để tránh ghi nhật ký trùng lặp nếu trình ghi nhật ký gốc đã được cấu hình.

Trả về một logger với tên được chỉ định. Hàm này không được thiết kế để người dùng thư viện truy cập trực tiếp.

>>> from huggingface_hub import logging

>>> logger = logging.get_logger(__name__)
>>> logging.set_verbosity_info()

Kiểm tra xem thanh tiến trình có bị vô hiệu hóa toàn cục hay cho một nhóm cụ thể không.

Hàm này trả về trạng thái thanh tiến trình có bị vô hiệu hóa cho một nhóm cụ thể hoặc toàn cục hay không. Nó kiểm tra biến môi trường HF_HUB_DISABLE_PROGRESS_BARS trước, sau đó là các cài đặt lập trình.

Tắt thanh tiến trình toàn cục hoặc cho một nhóm được chỉ định.

Hàm này cập nhật trạng thái của các thanh tiến trình dựa trên tên nhóm. Nếu không cung cấp tên nhóm, tất cả các thanh tiến trình sẽ bị vô hiệu hóa. Thao tác này tuân theo cài đặt của biến môi trường HF_HUB_DISABLE_PROGRESS_BARS.

Hoạt động như một lời gọi thông thường và như một trình quản lý ngữ cảnh: disable_progress_bars() # tắt cho đến khi gọi enable_progress_bars() with disable_progress_bars(): # tắt trong khối, bật lại khi thoát …

Bật thanh tiến trình toàn cục hoặc cho một nhóm được chỉ định.

Hàm này bật thanh tiến trình cho nhóm được chỉ định hoặc toàn cục nếu không có nhóm nào được chỉ định. Thao tác này phụ thuộc vào cài đặt biến môi trường HF_HUB_DISABLE_PROGRESS_BARS.

Đặt nhà máy client HTTP sẽ được sử dụng bởi huggingface_hub.

Client factory là một phương thức trả về một đối tượng httpx2.Client. Ở lần gọi đầu tiên của get_session(), client factory sẽ được sử dụng để tạo một đối tượng httpx2.Client mới, đối tượng này sẽ được chia sẻ giữa tất cả các cuộc gọi do huggingface_hub thực hiện.

Điều này có thể hữu ích nếu bạn đang chạy các script trong một môi trường cụ thể yêu cầu cấu hình tùy chỉnh (ví dụ: proxy hoặc chứng chỉ tùy chỉnh).

Sử dụng get_session() để lấy một httpx2.Client được cấu hình chính xác.

Lấy một đối tượng httpx2.Client, sử dụng nhà máy transport từ người dùng.

Client này được dùng chung cho tất cả các cuộc gọi do huggingface_hub thực hiện. Do đó, bạn không nên đóng nó thủ công.

Sử dụng set_client_factory() để tùy chỉnh httpx2.Client.

Đóng httpx2.Client toàn cục được sử dụng bởi huggingface_hub.

Nếu một Client bị đóng, nó sẽ được tạo lại vào lần gọi tiếp theo của get_session().

Có thể hữu ích nếu, ví dụ, chứng chỉ SSL đã được cập nhật.

Đặt nhà máy client HTTP async sẽ được sử dụng bởi huggingface_hub.

Nhà máy client bất đồng bộ là một phương thức trả về một đối tượng httpx2.AsyncClient. Điều này có thể hữu ích nếu bạn đang chạy các script trong một môi trường cụ thể yêu cầu cấu hình tùy chỉnh (ví dụ: proxy hoặc chứng chỉ tùy chỉnh). Sử dụng get_async_session() để lấy một httpx2.AsyncClient được cấu hình chính xác.

Ngược lại với httpx2.Client được dùng chung cho tất cả các cuộc gọi do huggingface_hub thực hiện, httpx2.AsyncClient không được dùng chung. Khuyến nghị sử dụng async context manager để đảm bảo client được đóng đúng cách khi thoát khỏi ngữ cảnh.

Trả về một đối tượng httpx2.AsyncClient, sử dụng nhà máy transport từ người dùng.

Sử dụng set_async_client_factory() để tùy chỉnh httpx2.AsyncClient.

Ngược lại với httpx2.Client được dùng chung cho tất cả các cuộc gọi do huggingface_hub thực hiện, httpx2.AsyncClient không được dùng chung. Khuyến nghị sử dụng async context manager để đảm bảo client được đóng đúng cách khi thoát khỏi ngữ cảnh.

Phiên bản nội bộ của response.raise_for_status() sẽ tinh chỉnh một HTTPError tiềm năng. Ngoại lệ được ném ra sẽ là một instance của HfHubHTTPError.

Trợ lý này được thiết kế để là phương thức duy nhất để gọi raise_for_status khi thực hiện một cuộc gọi đến Hugging Face Hub.

Gây ra khi yêu cầu thất bại:

• RepositoryNotFoundError Nếu không tìm thấy kho cần tải xuống. Điều này có thể do kho không tồn tại, do repo_type không được đặt đúng, hoặc do kho là private và bạn không có quyền truy cập.
• GatedRepoError Nếu kho dữ liệu tồn tại nhưng được bảo vệ và người dùng không có trong danh sách được cấp quyền.
• RevisionNotFoundError Nếu kho chứa tồn tại nhưng không tìm thấy phiên bản.
• EntryNotFoundError Nếu kho dữ liệu tồn tại nhưng mục (ví dụ: tệp được yêu cầu) không thể tìm thấy.
• BadRequestError Nếu yêu cầu thất bại với lỗi HTTP 400 BadRequest.
• HfHubHTTPError Nếu yêu cầu thất bại vì một lý do không được liệt kê ở trên.

Trả về trạng thái chúng ta có đang ở chế độ ngoại tuyến cho Hub hay không.

Khi chế độ ngoại tuyến được bật, tất cả các yêu cầu HTTP được thực hiện bằng get_session sẽ gây ra ngoại lệ OfflineModeIsEnabled.

from huggingface_hub import is_offline_mode

def list_files(repo_id: str):
    if is_offline_mode():
        ... # list files from local cache (degraded experience but still functional)
    else:
        ... # list files from Hub (complete experience)

HTTPError để kế thừa cho bất kỳ lỗi HTTP tùy chỉnh nào được ném ra trong HF Hub.

Mọi HTTPError đều được chuyển đổi thành ít nhất là HfHubHTTPError. Nếu máy chủ gửi lại một số thông tin, chúng sẽ được thêm vào thông báo lỗi.

Chi tiết đã thêm:

• Request ID được lấy từ các header theo thứ tự ưu tiên: “X-Request-Id”, “X-Amzn-Trace-Id”, “X-Amz-Cf-Id”.
• Thông báo lỗi máy chủ từ tiêu đề “X-Error-Message”.
• Thông báo lỗi máy chủ nếu chúng tôi tìm thấy một thông báo trong phần thân phản hồi.

    import httpx2
    from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError

    response = get_session().post(...)
    try:
        hf_raise_for_status(response)
    except HfHubHTTPError as e:
        print(str(e)) # formatted message
        e.request_id, e.server_message # details returned by server

        # Complete the error message with additional information once it's raised
        e.append_to_message("
ate_commit` expects the repository to exist.")
        raise

Được ném ra khi cố gắng truy cập một URL hf.co với tên kho không hợp lệ, hoặc với tên kho riêng tư mà người dùng không có quyền truy cập.

>>> from huggingface_hub import model_info
>>> model_info("<non_existent_repository>")
(...)
huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. (Request ID: PvMw_VjBMjVdMz53WKIzP)

Repository Not Found for url: https://huggingface.co/api/models/%3Cnon_existent_repository%3E.
Please make sure you specified the correct `repo_id` and `repo_type`.
If the repo is private, make sure you are authenticated and your token has the required permissions.
Invalid username or password.

Được ném ra khi cố gắng truy cập một kho lưu trữ có kiểm soát mà người dùng không có trong danh sách được ủy quyền.

Lưu ý: kế thừa từ RepositoryNotFoundError để đảm bảo tính tương thích ngược.

>>> from huggingface_hub import model_info
>>> model_info("<gated_repository>")
(...)
huggingface_hub.errors.GatedRepoError: 403 Client Error. (Request ID: ViT1Bf7O_026LGSQuVqfa)

Cannot access gated repo for url https://huggingface.co/api/models/ardent-figment/gated-model.
Access to model ardent-figment/gated-model is restricted and you are not in the authorized list.
Visit https://huggingface.co/ardent-figment/gated-model to ask for access.

Được ném ra khi cố gắng truy cập một URL hf.co có kho lưu trữ hợp lệ nhưng phiên bản không hợp lệ.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
(...)
huggingface_hub.errors.RevisionNotFoundError: 404 Client Error. (Request ID: Mwhe_c3Kt650GcdKEFomX)

Revision Not Found for url: https://huggingface.co/bert-base-cased/resolve/%3Cnon-existent-revision%3E/config.json.

Được HfApi.resolve_revision() ném ra khi một revision không thể được phân giải thành một commit hash: không thể kết nối đến Hub (chế độ ngoại tuyến, lỗi kết nối, hết thời gian chờ, Hub đang ngừng hoạt động, …) và không tìm thấy mục phù hợp nào trong bộ nhớ đệm cục bộ.

Được hf_raise_for_status ném ra khi máy chủ trả về lỗi HTTP 400.

>>> resp = httpx2.post("hf.co/api/check", ...)
>>> hf_raise_for_status(resp, endpoint_name="check")
huggingface_hub.errors.BadRequestError: Bad request for check endpoint: {details} (Request ID: XXX)

Được ném ra khi không tìm thấy mục, cả ở cục bộ lẫn từ xa.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.RemoteEntryNotFoundError (...)
>>> hf_hub_download('bert-base-cased', '<non-existent-file>', local_files_only=True)
(...)
huggingface_hub.utils.errors.LocalEntryNotFoundError (...)

Được ném ra khi cố gắng truy cập một URL hf.co có kho lưu trữ và phiên bản hợp lệ nhưng tên tệp không hợp lệ.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.EntryNotFoundError: 404 Client Error. (Request ID: 53pNl6M0MxsnG5Sw8JA6x)

Entry Not Found for url: https://huggingface.co/bert-base-cased/resolve/main/%3Cnon-existent-file%3E.

Được ném ra khi cố gắng truy cập một tệp hoặc snapshot không có trên đĩa khi mạng bị tắt hoặc không khả dụng (vấn đề kết nối). Mục có thể tồn tại trên Hub.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
(...)
huggingface_hub.errors.LocalEntryNotFoundError: Cannot find the requested files in the disk cache and outgoing traffic has been disabled. To enable hf.co look-ups and downloads online, set 'local_files_only' to False.

Được snapshot_download() ném ra khi không thể kết nối đến Hub (trạng thái ngoại tuyến, sự cố kết nối, hoặc local_files_only=True) và bản sao lưu (snapshot) được lưu trong bộ nhớ đệm (cache) được biết là không đầy đủ: một số tệp được liệt kê trong danh sách cây (tree listing) đã được lưu trong bộ nhớ đệm của kho (repository) bị thiếu trong bản sao lưu cục bộ.

Đây là một lớp con của LocalEntryNotFoundError để đảm bảo tính tương thích ngược.

Thuộc tính snapshot_path chứa đường dẫn đến bản snapshot cục bộ chưa hoàn chỉnh, nhờ đó thư viện phía sau có thể xác định vị trí các tệp được cache mới nhất mặc dù chúng được biết là chưa hoàn chỉnh.

Được get_cached_repo_tree() ném ra khi không có danh sách cây nào được lưu cache cho phiên bản được yêu cầu.

Danh sách cây được điền như một tác dụng phụ của snapshot_download().

Được ném ra khi một yêu cầu được thực hiện nhưng biến môi trường HF_HUB_OFFLINE=1 đã được đặt.

Gửi dữ liệu đo lường giúp theo dõi việc sử dụng các thư viện HF khác nhau.

Dữ liệu sử dụng này giúp chúng tôi gỡ lỗi và ưu tiên phát triển các tính năng mới. Tuy nhiên, chúng tôi hiểu rằng không phải ai cũng muốn chia sẻ thêm thông tin và chúng tôi tôn trọng quyền riêng tư của bạn. Bạn có thể tắt việc thu thập dữ liệu đo lường bằng cách đặt biến môi trường HF_HUB_DISABLE_TELEMETRY=1. Dữ liệu đo lường cũng bị tắt ở chế độ ngoại tuyến (tức là khi đặt HF_HUB_OFFLINE=1).

Việc thu thập dữ liệu đo lường được thực hiện trong một luồng riêng biệt để giảm thiểu tác động đến người dùng.

>>> from huggingface_hub.utils import send_telemetry

# Send telemetry without library information
>>> send_telemetry("ping")

# Send telemetry to subtopic with library information
>>> send_telemetry("gradio/local_link", library_name="gradio", library_version="3.22.1")

# Send telemetry with additional data
>>> send_telemetry(
...     topic="examples",
...     library_name="transformers",
...     library_version="4.26.0",
...     user_agent={"pipeline": "text_classification", "framework": "flax"},
... )

Xác thực các giá trị nhận được dưới dạng tham số cho bất kỳ phương thức công khai nào của huggingface_hub.

Mục tiêu của decorator này là thống nhất việc kiểm tra tính hợp lệ của các đối số được tái sử dụng ở mọi nơi. Mặc định, tất cả các bộ kiểm tra đã định nghĩa đều được chạy thử.

Trình xác thực:

• validate_repo_id(): repo_id phải là "repo_name" hoặc "namespace/repo_name". Namespace là tên người dùng hoặc một tổ chức.
• ~utils.smoothly_deprecate_legacy_arguments: Bỏ qua proxies khi tải tệp (nên được đặt ở phạm vi toàn cục).

>>> from huggingface_hub.utils import validate_hf_hub_args

>>> @validate_hf_hub_args
... def my_cool_method(repo_id: str):
...     print(repo_id)

>>> my_cool_method(repo_id="valid_repo_id")
valid_repo_id

>>> my_cool_method("other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

>>> my_cool_method(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Ngoại lệ chung được ném ra bởi các trình xác thực của huggingface_hub.

Kế thừa từ ValueError.

Kiểm tra xem repo_id có hợp lệ không.

Điều này không nhằm thay thế cho việc kiểm tra hợp lệ được thực hiện trên Hub mà thay vào đó là để tránh các mâu thuẫn cục bộ bất cứ khi nào có thể (ví dụ: truyền repo_type trong repo_id là bị cấm).

Quy tắc:

• Từ 1 đến 96 ký tự.
• “repo_name” hoặc “namespace/repo_name”
• [a-zA-Z0-9] hoặc ”-”, ”_”, ”.”
• “—” và “..” bị cấm

Hợp lệ: "foo", "foo/bar", "123", "Foo-BAR_foo.bar123"

Không hợp lệ: "datasets/foo/bar", ".repo_id", "foo--bar", "foo.git"

>>> from huggingface_hub.utils import validate_repo_id
>>> validate_repo_id(repo_id="valid_repo_id")
>>> validate_repo_id(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Được thảo luận tại https://github.com/huggingface/huggingface_hub/issues/1008. Trong moon-landing (kho nội bộ):

• https://github.com/huggingface/moon-landing/blob/main/server/lib/Names.ts#L27
• https://github.com/huggingface/moon-landing/blob/main/server/views/components/NewRepoForm/NewRepoForm.svelte#L138

Loại bỏ dần các đối số cũ trong mã nguồn huggingface_hub một cách suôn sẻ.

Hàm này bỏ qua một số đối số đã bị ngừng hỗ trợ trong kwargs và cảnh báo người dùng rằng chúng đã bị bỏ qua. Mục tiêu là tránh làm hỏng mã hiện có trong khi hướng dẫn người dùng sử dụng cách làm mới.

Danh sách các đối số đã bị ngừng hỗ trợ:

• proxies: Để thiết lập proxy, người dùng phải sử dụng biến môi trường HTTP_PROXY hoặc cấu hình httpx2.Client thủ công bằng cách sử dụng hàm set_client_factory().

  Trong huggingface_hub 0.x, proxies là một từ điển được truyền trực tiếp vào requests.request. Kể từ huggingface_hub 1.x, proxies cho từng yêu cầu không còn được hỗ trợ nữa. Cụ thể, không thể cấu hình proxy ở cấp độ từng yêu cầu. Giải pháp là cấu hình toàn cục bằng cách sử dụng hàm set_client_factory() hoặc biến môi trường HTTP_PROXY.

  Để biết thêm chi tiết, xem:

  • https://httpx2.pydantic.dev/advanced/proxies/

• resume_download: đã bị loại bỏ mà không có thay thế. huggingface_hub luôn tiếp tục tải xuống bất cứ khi nào có thể.

• force_filename: đã bị loại bỏ mà không có thay thế. Tên tệp luôn giống như trên Hub.

• local_dir_use_symlinks: đã bị loại bỏ mà không có thay thế. Việc tải xuống thư mục cục bộ không còn sử dụng liên kết mềm (symlinks) nữa.