Hugging Face's logo

Hub Python Library documentation

HfApi Client

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

HfApi Client

Dưới đây là tài liệu cho lớp HfApi, đóng vai trò là lớp bọc Python cho API của Hugging Face Hub.

Tất cả các phương thức từ HfApi cũng có thể được truy cập trực tiếp từ gốc của gói. Cả hai cách tiếp cận đều được mô tả chi tiết bên dưới.

Việc sử dụng phương pháp root đơn giản hơn nhưng lớp HfApi mang lại cho bạn nhiều sự linh hoạt hơn. Cụ thể, bạn có thể truyền một token sẽ được tái sử dụng trong tất cả các cuộc gọi HTTP. Điều này khác so với hf auth login hoặc login() vì token không được lưu trữ trên máy. Bạn cũng có thể cung cấp một endpoint khác hoặc cấu hình user-agent tùy chỉnh.

from huggingface_hub import HfApi, list_models

# Use root method
models = list_models()

# Or configure a HfApi client
hf_api = HfApi(
    endpoint="https://huggingface.co", # Can be a Private Hub endpoint.
    token="hf_xxx", # Token is not persisted on the machine.
)
models = hf_api.list_models()

HfApi

lớp huggingface_hub.HfApi

< >

( endpoint: str | None = Nonetoken: str | bool | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneheaders: dict[str, str] | None = None )

Tham số

  • endpoint (str, tùy chọn) — Endpoint của Hub. Mặc định là https://huggingface.co.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • library_name (str, tùy chọn) — Tên của thư viện đang thực hiện yêu cầu HTTP. Giá trị này sẽ được thêm vào tiêu đề user-agent. Ví dụ: "transformers".
  • library_version (str, tùy chọn) — Phiên bản của thư viện đang thực hiện yêu cầu HTTP. Giá trị này sẽ được thêm vào tiêu đề user-agent. Ví dụ: "4.24.0".
  • user_agent (str, dict, tùy chọn) — Thông tin user agent dưới dạng một từ điển hoặc một chuỗi duy nhất. Nó sẽ được bổ sung thông tin về các gói đã cài đặt.
  • headers (dict, tùy chọn) — Các header bổ sung được gửi kèm theo mỗi yêu cầu. Ví dụ: {"X-My-Header": "value"}. Các header được truyền ở đây có độ ưu tiên cao hơn các header mặc định.

Client để tương tác với Hugging Face Hub qua HTTP.

Client được khởi tạo với một số cài đặt cấp cao được sử dụng trong tất cả các yêu cầu gửi đến Hub (điểm cuối HF, xác thực, user agents…). Việc sử dụng client HfApi được khuyến khích nhưng không bắt buộc, vì tất cả các phương thức công khai của nó đều được phơi bày trực tiếp ở gốc của huggingface_hub.

accept_access_request

< >

( repo_id: struser: str | None = Nonerequest_id: str | None = Nonerepo_type: str | None = Nonetoken: bool | str | None = None )

Tham số

  • repo_id (str) — ID của kho cần chấp nhận yêu cầu truy cập.
  • user (str, tùy chọn) — Tên người dùng của người dùng mà yêu cầu truy cập nên được chấp nhận. Phải cung cấp đúng một trong user hoặc request_id.
  • request_id (str, tùy chọn) — ID của yêu cầu truy cập cần chấp nhận (xem AccessRequest). Bắt buộc khi repo được cấu hình để không chia sẻ tên người dùng của người yêu cầu. Phải cung cấp đúng một trong user hoặc request_id.
  • repo_type (str, tùy chọn) — Loại repo để chấp nhận yêu cầu truy cập. Phải là một trong model, dataset hoặc space. Mặc định là model.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 nếu kho không được bảo vệ.
  • HfHubHTTPError — HTTP 403 nếu bạn chỉ có quyền truy cập chỉ đọc vào kho. Điều này có thể xảy ra nếu bạn không có vai trò write hoặc admin trong tổ chức mà kho đó thuộc về, hoặc nếu bạn đã truyền một token read.
  • HfHubHTTPError — HTTP 404 nếu người dùng không tồn tại trên Hub.
  • HfHubHTTPError — HTTP 404 nếu không tìm thấy yêu cầu truy cập của người dùng.
  • HfHubHTTPError — HTTP 404 nếu yêu cầu truy cập của người dùng đã có trong danh sách được chấp nhận.

Chấp nhận yêu cầu truy cập từ một người dùng cho một kho có kiểm soát (gated repo) cụ thể.

Khi yêu cầu được chấp nhận, người dùng sẽ có thể tải xuống bất kỳ tệp nào trong kho và truy cập tab cộng đồng. Nếu chế độ phê duyệt là tự động, bạn không cần phải chấp nhận yêu cầu thủ công. Một yêu cầu đã được chấp nhận có thể bị hủy hoặc từ chối vào bất kỳ lúc nào bằng cách sử dụng cancel_access_request() và reject_access_request().

Để biết thêm thông tin về các kho có kiểm soát, hãy xem https://huggingface.co/docs/hub/models-gated.

add_collection_item

< >

( collection_slug: stritem_id: stritem_type: CollectionItemType_Tnote: str | None = Noneexists_ok: bool = Falsetoken: bool | str | None = None )

Tham số

  • collection_slug (str) — Slug của bộ sưu tập cần cập nhật. Ví dụ: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • item_id (str) — Id của mục cần thêm vào bộ sưu tập. Sử dụng repo_id cho repos/spaces/datasets, paper id cho các bài báo, slug của một bộ sưu tập khác (ví dụ: "moonshotai/kimi-k2") hoặc bucket id (ví dụ: "namespace/bucket-name").
  • item_type (str) — Loại của mục cần thêm. Có thể là một trong "model", "dataset", "space", "paper", "collection" hoặc "bucket".
  • note (str, tùy chọn) — Ghi chú đính kèm cho mục trong bộ sưu tập. Kích thước tối đa của một ghi chú là 500 ký tự.
  • exists_ok (bool, tùy chọn) — Nếu True, không gây ra lỗi nếu mục đã tồn tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 403 nếu bạn chỉ có quyền truy cập chỉ đọc vào kho. Điều này có thể xảy ra nếu bạn không có vai trò write hoặc admin trong tổ chức mà kho đó thuộc về, hoặc nếu bạn đã truyền một token read.
  • HfHubHTTPError — HTTP 404 nếu mục bạn cố thêm vào bộ sưu tập không tồn tại trên Hub.
  • HfHubHTTPError — HTTP 409 nếu mục bạn cố thêm vào bộ sưu tập đã có trong bộ sưu tập (và exists_ok=False)

Thêm một mục vào bộ sưu tập trên Hub.

Trả về: Collection

Ví dụ:

>>> from huggingface_hub import add_collection_item
>>> collection = add_collection_item(
...     collection_slug="davanstrien/climate-64f99dc2a5067f6b65531bab",
...     item_id="pierre-loic/climate-news-articles",
...     item_type="dataset"
... )
>>> collection.items[-1].item_id
"pierre-loic/climate-news-articles"
# ^item got added to the collection on last position

# Add item with a note
>>> add_collection_item(
...     collection_slug="davanstrien/climate-64f99dc2a5067f6b65531bab",
...     item_id="datasets/climate_fever",
...     item_type="dataset",
...     note="This dataset adopts the FEVER methodology that consists of 1,535 real-world claims regarding climate-change collected on the internet."
... )
(...)

add_space_secret

< >

( repo_id: strkey: strvalue: strdescription: str | None = Nonetoken: bool | str | None = None )

Tham số

  • repo_id (str) — ID của kho cần cập nhật. Ví dụ: "bigcode/in-the-stack".
  • key (str) — Khóa bí mật. Ví dụ: "GITHUB_API_KEY"
  • value (str) — Giá trị bí mật. Ví dụ: "your_github_api_key".
  • description (str, tùy chọn) — Mô tả bí mật. Ví dụ: "Github API key to access the Github API".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Thêm hoặc cập nhật một bí mật trong một Space.

Secrets cho phép thiết lập các khóa hoặc token bí mật cho một Space mà không cần hardcode chúng. Để biết thêm chi tiết, xem https://huggingface.co/docs/hub/spaces-overview#managing-secrets.

add_space_variable

< >

( repo_id: strkey: strvalue: strdescription: str | None = Nonetoken: bool | str | None = None )

Tham số

  • repo_id (str) — ID của kho cần cập nhật. Ví dụ: "bigcode/in-the-stack".
  • key (str) — Khóa biến. Ví dụ: "MODEL_REPO_ID"
  • value (str) — Giá trị của biến. Ví dụ: "the_model_repo_id".
  • description (str) — Mô tả của biến. Ví dụ: "Model Repo ID of the implemented model".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Thêm hoặc cập nhật một biến trong một Space.

Biến cho phép thiết lập các biến môi trường cho một Space mà không cần hardcode chúng. Để biết thêm chi tiết, xem https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

auth_check

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = Nonewrite: bool = False )

Tham số

  • repo_id (str) — Kho cần kiểm tra quyền truy cập. Định dạng nên là "user/repo_name". Ví dụ: "user/my-cool-model".
  • repo_type (str, tùy chọn) — Loại của kho. Phải là một trong "model", "dataset" hoặc "space". Nếu không được chỉ định, giá trị mặc định là "model".
  • token (Union[bool, str, None], tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.
  • write (bool, tuỳ chọn) — Nếu True, kiểm tra xem người dùng có quyền ghi nội dung trên kho lưu trữ hay không. Nếu False (mặc định), chỉ kiểm tra quyền truy cập đọc.

Gây ra

RepositoryNotFoundError hoặc GatedRepoError

  • RepositoryNotFoundError — Được ném ra nếu kho không tồn tại, là riêng tư, hoặc người dùng không có quyền truy cập. Điều này có thể xảy ra nếu repo_id hoặc repo_type không chính xác, hoặc nếu kho là riêng tư nhưng người dùng chưa xác thực.

  • GatedRepoError — Được ném ra nếu kho dữ liệu tồn tại nhưng được bảo vệ và người dùng không được cấp quyền truy cập.

Kiểm tra xem token người dùng được cung cấp có quyền truy cập vào một kho lưu trữ cụ thể trên Hugging Face Hub hay không.

Phương thức này xác minh xem người dùng, đã xác thực thông qua token được cung cấp, có quyền truy cập vào kho lưu trữ được chỉ định hay không. Nếu kho lưu trữ không được tìm thấy hoặc người dùng không có quyền hạn cần thiết để truy cập, phương thức sẽ ném ra một ngoại lệ phù hợp.

Ví dụ:

Kiểm tra xem người dùng có quyền truy cập vào kho lưu trữ hay không:

>>> from huggingface_hub import auth_check
>>> from huggingface_hub.utils import GatedRepoError, RepositoryNotFoundError

try:
    auth_check("user/my-cool-model")
except GatedRepoError:
    # Handle gated repository error
    print("You do not have permission to access this gated repository.")
except RepositoryNotFoundError:
    # Handle repository not found error
    print("The repository was not found or you do not have access.")

Trong ví dụ này:

  • Nếu người dùng có quyền truy cập, phương thức sẽ hoàn tất thành công.
  • Nếu kho lưu trữ bị hạn chế truy cập hoặc không tồn tại, các ngoại lệ phù hợp sẽ được ném ra, cho phép người dùng xử lý chúng theo cách tương ứng.

batch_bucket_files

< >

( bucket_id: stradd: list[tuple[str | Path | bytes, str]] | None = Nonecopy: list[tuple[str, str, str, str]] | None = Nonedelete: list[str] | None = Nonetoken: str | bool | None = None )

Tham số

  • bucket_id (str) — ID của bucket (ví dụ: "username/my-bucket").
  • add (list of tuple, optional) — Các tệp cần tải lên. Mỗi phần tử là một tuple (source, destination) trong đó source là đường dẫn đến một tệp cục bộ (str hoặc Path) hoặc nội dung bytes thô, và destination là đường dẫn trong bucket.
  • copy (list của tuple, tuỳ chọn) — Các tệp cần sao chép theo xet hash. Mỗi phần tử là một (source_repo_type, source_repo_id, xet_hash, destination) tuple với các trường sau:
    • source_repo_type là kiểu của kho lưu trữ nguồn: "model", "dataset", "space" hoặc "bucket".
    • source_repo_id là ID của kho lưu trữ hoặc bucket nguồn (ví dụ: "username/my-model").
    • xet_hash là xet hash của tệp cần sao chép.
    • destination là đường dẫn đích trong bucket. Đây là thao tác phía máy chủ — không có dữ liệu nào được tải xuống hoặc tải lên lại.
  • delete (list of str, optional) — Đường dẫn của các tệp cần xóa khỏi bucket.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

BucketBatchError

  • BucketBatchError — Nếu máy chủ báo rằng một số thao tác đã thất bại. Lỗi này được ném ra sau khi mọi thao tác đã được gửi đi, do đó các thao tác khác trong lô đã được áp dụng.

Thêm, sao chép và/hoặc xóa các tệp trong một bucket.

Đây là một thao tác phi giao dịch. Nếu xảy ra lỗi trong quá trình, một số tệp có thể đã được tải lên, sao chép hoặc xóa trong khi các tệp khác thì chưa.

Ví dụ:

>>> from huggingface_hub import batch_bucket_files

# Upload files
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[
...         ("./model.safetensors", "models/model.safetensors"),
...         (b'{{"key": "value"}}', "config.json"),
...     ],
... )

# Copy xet files from another bucket or repo (server-side, no data transfer)
>>> batch_bucket_files(
...     "username/my-bucket",
...     copy=[
...         ("bucket", "username/source-bucket", "<xethash_1>", "models/model.safetensors"),
...         ("model", "username/my-model", "<xethash_2>", "models/config.safetensors"),
...     ],
... )

# Delete files
>>> batch_bucket_files("username/my-bucket", delete=["old-model.bin"])

# Upload and delete in one batch
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[("./new.txt", "new.txt")],
...     delete=["old.txt"],
... )

bucket_info

< >

( bucket_id: strtoken: bool | str | None = None ) → BucketInfo

Tham số

  • bucket_id (str) — ID của bucket (ví dụ: "username/my-bucket").
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

BucketInfo

Thông tin về bucket.

Gây ra

BucketNotFoundError hoặc or

  • BucketNotFoundError — Nếu không tìm thấy bucket. Điều này có thể do bucket không tồn tại,
  • or — vì nó được đặt ở chế độ private và bạn không có quyền truy cập.

Lấy thông tin về một bucket cụ thể trên Hub.

Ví dụ:

>>> from huggingface_hub import bucket_info
>>> info = bucket_info(bucket_id="Wauplin/first-bucket")
>>> info.id
'Wauplin/first-bucket'
>>> info.private
False
>>> info.created_at
datetime.datetime(2026, 2, 6, 17, 37, 57, tzinfo=datetime.timezone.utc)
>>> info.size
551879671
>>> info.total_files
12

cancel_access_request

< >

( repo_id: struser: str | None = Nonerequest_id: str | None = Nonerepo_type: str | None = Nonetoken: bool | str | None = None )

Tham số

  • repo_id (str) — ID của kho cần hủy yêu cầu cấp quyền truy cập.
  • user (str, tùy chọn) — Tên người dùng của người dùng mà yêu cầu truy cập cần được hủy bỏ. Phải cung cấp đúng một trong user hoặc request_id.
  • request_id (str, tuỳ chọn) — ID của yêu cầu truy cập cần hủy (xem AccessRequest). Bắt buộc khi repo được cấu hình để không chia sẻ tên người dùng của người yêu cầu. Phải cung cấp đúng một trong user hoặc request_id.
  • repo_type (str, tùy chọn) — Loại repo để hủy yêu cầu truy cập. Phải là một trong model, dataset hoặc space. Mặc định là model.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 nếu kho không được bảo vệ.
  • HfHubHTTPError — HTTP 403 nếu bạn chỉ có quyền truy cập chỉ đọc vào kho. Điều này có thể xảy ra nếu bạn không có vai trò write hoặc admin trong tổ chức mà kho đó thuộc về, hoặc nếu bạn đã truyền một token read.
  • HfHubHTTPError — HTTP 404 nếu người dùng không tồn tại trên Hub.
  • HfHubHTTPError — HTTP 404 nếu không tìm thấy yêu cầu truy cập của người dùng.
  • HfHubHTTPError — HTTP 404 nếu yêu cầu truy cập của người dùng đã có trong danh sách chờ.

Hủy yêu cầu truy cập từ một người dùng đối với một kho có kiểm soát (gated repo) cụ thể.

Một yêu cầu đã bị hủy sẽ quay lại danh sách chờ và người dùng sẽ mất quyền truy cập vào kho.

Để biết thêm thông tin về các kho có kiểm soát, hãy xem https://huggingface.co/docs/hub/models-gated.

cancel_job

< >

( job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • job_id (str) — ID của Job.
  • namespace (str, optional) — Namespace nơi Job đang chạy. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Hủy một Job tính toán trên hạ tầng của Hugging Face.

change_discussion_status

< >

( repo_id: strdiscussion_num: intnew_status: Literal['open', 'closed']token: bool | str | None = Nonecomment: str | None = Nonerepo_type: str | None = None ) → DiscussionStatusChange

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • discussion_num (int) — Số thứ tự của Discussion hoặc Pull Request. Phải là một số nguyên dương.
  • new_status (str) — Trạng thái mới cho cuộc thảo luận, là "open" hoặc "closed".
  • comment (str, tùy chọn) — Một chú thích tùy chọn để đăng kèm theo thay đổi trạng thái.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

DiscussionStatusChange

sự kiện thay đổi trạng thái

Đóng hoặc mở lại một Discussion hoặc Pull Request.

Ví dụ:

>>> HfApi().change_discussion_status(
...     repo_id="username/repo_name",
...     discussion_num=34,
...     new_status="closed"
... )
# DiscussionStatusChange(id='deadbeef0000000', type='status-change', ...)

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

comment_discussion

< >

( repo_id: strdiscussion_num: intcomment: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionComment

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • discussion_num (int) — Số thứ tự của Discussion hoặc Pull Request. Phải là một số nguyên dương.
  • comment (str) — Nội dung của bình luận cần tạo. Bình luận hỗ trợ định dạng markdown.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

DiscussionComment

bình luận vừa được tạo

Tạo một bình luận mới trên Discussion được chỉ định.

Ví dụ:


>>> comment = """
... Hello @otheruser!
...
... # This is a title
...
... **This is bold**, *this is italic* and ~this is strikethrough~
... And [this](http://url) is a link
... """

>>> HfApi().comment_discussion(
...     repo_id="username/repo_name",
...     discussion_num=34,
...     comment=comment
... )
# DiscussionComment(id='deadbeef0000000', type='comment', ...)

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

copy_files

< >

( source: strdestination: strtoken: str | bool | None = None )

Tham số

  • source (str) — Vị trí nguồn dưới dạng URI hf://. Có thể là đường dẫn bucket (ví dụ: "hf://buckets/my-bucket/path/to/file") hoặc đường dẫn repo (ví dụ: "hf://username/my-model/weights.bin", "hf://datasets/username/my-dataset/data/").
  • destination (str) — Vị trí đích dưới dạng URI hf:// trỏ đến một bucket (ví dụ: "hf://buckets/my-bucket/target/path") hoặc một repository (ví dụ: "hf://username/my-model/target/path").
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

ValueError

  • ValueError — Nếu URI nguồn/đích không hợp lệ hoặc nếu sao chép từ một bucket sang một repo.

Sao chép tệp giữa các vị trí trên Hub.

Sao chép tệp từ một bucket hoặc kho (mô hình, tập dữ liệu, space) sang một bucket hoặc kho khác. Hỗ trợ cả tệp riêng lẻ và toàn bộ thư mục.

Khi sao chép thư mục, việc thêm / ở cuối đường dẫn nguồn sử dụng ngữ nghĩa kiểu rsync: sao chép nội dung của thư mục vào đích, không lồng chính thư mục nguồn bên trong. Nếu không có / ở cuối, thư mục nguồn sẽ được lồng bên trong thư mục đích (giống như cp -r).

Khi sao chép từ một kho lưu trữ sang một bucket, các tệp .gitattributes sẽ được tự động loại trừ vì chúng là metadata đặc thù của git và không liên quan trong ngữ cảnh bucket.

Sao chép từ repo sang repo sử dụng CommitOperationCopy bên trong và tạo một commit trên kho đích. Sao chép từ bucket sang repo không được hỗ trợ.

Các bản sao phía máy chủ chỉ hoạt động trong cùng một khu vực lưu trữ.

Ví dụ:

>>> from huggingface_hub import copy_files

# Copy a single file between buckets
>>> copy_files("hf://buckets/my-bucket/data.bin", "hf://buckets/other-bucket/data.bin")

# Copy a folder into another bucket (nests: backup/models/...)
>>> copy_files("hf://buckets/my-bucket/models", "hf://buckets/other-bucket/backup/")

# Copy folder contents (trailing /): files go directly into backup/
>>> copy_files("hf://buckets/my-bucket/models/", "hf://buckets/other-bucket/backup/")

# Copy a file from a model repo to a bucket
>>> copy_files("hf://username/my-model/model.safetensors", "hf://buckets/my-bucket/")

# Copy an entire dataset to a bucket
>>> copy_files("hf://datasets/username/my-dataset/", "hf://buckets/my-bucket/datasets/")

# Copy files between repositories
>>> copy_files("hf://username/source-model/", "hf://username/dest-model/")

# Copy a file from one repo to another
>>> copy_files("hf://username/source-model/config.json", "hf://username/dest-model/config.json")

create_branch

< >

( repo_id: strbranch: strrevision: str | None = Nonetoken: bool | str | None = Nonerepo_type: str | None = Noneexist_ok: bool = False )

Tham số

  • repo_id (str) — Kho lưu trữ mà nhánh sẽ được tạo trong đó. Ví dụ: "user/my-cool-model".
  • branch (str) — Tên của nhánh cần tạo.
  • revision (str, tùy chọn) — Phiên bản git để tạo nhánh từ đó. Nó có thể là tên nhánh hoặc OID/SHA của một commit, dưới dạng chuỗi hex. Mặc định là đầu của nhánh "main".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tạo nhánh trên một dataset hoặc space, None hoặc "model" nếu gắn thẻ cho một model. Mặc định là None.
  • exist_ok (bool, tùy chọn, mặc định là False) — Nếu True, không gây ra lỗi nếu nhánh đã tồn tại.

Gây ra

RepositoryNotFoundError hoặc BadRequestError hoặc HfHubHTTPError

  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho riêng tư nhưng chưa xác thực hoặc kho không tồn tại.
  • BadRequestError — Nếu tham chiếu cho một branch không hợp lệ. Ví dụ: refs/pr/5 hoặc ‘refs/foo/bar’.
  • HfHubHTTPError — Nếu nhánh đã tồn tại trên kho (lỗi 409) và exist_ok được đặt thành False.

Tạo một nhánh mới cho một kho trên Hub, bắt đầu từ bản sửa đổi được chỉ định (mặc định là main). Để tìm một bản sửa đổi phù hợp với nhu cầu của bạn, bạn có thể sử dụng list_repo_refs() hoặc list_repo_commits().

create_bucket

< >

( bucket_id: strprivate: bool | None = Nonevisibility: Literal['public', 'private'] | None = Noneresource_group_id: str | None = Noneregion: REPO_REGIONS | None = Noneexist_ok: bool = Falsetoken: bool | str | None = None ) → BucketUrl

Tham số

  • bucket_id (str) — Một namespace (người dùng hoặc tổ chức) và tên bucket được phân tách bằng /. Nếu không cung cấp namespace, bucket sẽ được tạo trong namespace của người dùng hiện tại.
  • private (bool, tuỳ chọn) — Xác định việc có làm cho bucket ở chế độ riêng tư hay không. Nếu là None (mặc định), bucket sẽ ở chế độ công khai trừ khi mặc định của tổ chức là riêng tư. Không thể truyền cùng với visibility.
  • visibility (Literal["public", "private"], tùy chọn) — Độ hiển thị của bucket. Có thể là "public" hoặc "private". Nếu là None (mặc định), bucket sẽ là công khai trừ khi mặc định của tổ chức là riêng tư.
  • resource_group_id (str, tùy chọn) — Nhóm tài nguyên để tạo bucket. Nhóm tài nguyên chỉ khả dụng cho các tổ chức Enterprise Hub và cho phép xác định thành viên nào trong tổ chức có thể truy cập tài nguyên. ID của một nhóm tài nguyên có thể tìm thấy trong URL của trang tài nguyên trên Hub (ví dụ: "66670e5163145ca562cb1988"). Để tìm hiểu thêm về nhóm tài nguyên, xem https://huggingface.co/docs/hub/en/security-resource-groups.
  • region (Literal["us", "eu"], tùy chọn) — Khu vực cloud để tạo bucket. Có thể là "us" hoặc "eu". Nếu không được chỉ định, bucket sẽ được tạo trong khu vực mặc định. Yêu cầu gói Team hoặc cao hơn.
  • exist_ok (bool, tùy chọn, mặc định là False) — Nếu True, sẽ không gây ra lỗi nếu bucket đã tồn tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

BucketUrl

URL của bucket mới được tạo, chứa các thuộc tính như endpoint, namespace và bucket_id.

Tạo một bucket trên Hub.

Ví dụ:

>>> from huggingface_hub import create_bucket

>>> url = create_bucket(bucket_id="my-bucket")
>>> url.bucket_id
'user/my-bucket'
>>> url.url
'https://huggingface.co/buckets/user/my-bucket'
>>> url.uri.to_uri()
'hf://buckets/user/my-bucket'

>>> create_bucket(bucket_id="my-bucket", private=True, exist_ok=True)
BucketUrl(...)

>>> create_bucket(bucket_id="my-bucket", region="us")
BucketUrl(...)

create_collection

< >

( title: strnamespace: str | None = Nonedescription: str | None = Noneprivate: bool = Falseresource_group_id: str | None = Noneexists_ok: bool = Falsetoken: bool | str | None = None )

Tham số

  • title (str) — Tiêu đề của bộ sưu tập cần tạo. Ví dụ: "Recent models".
  • namespace (str, không bắt buộc) — Namespace của bộ sưu tập cần tạo (tên người dùng hoặc tổ chức). Mặc định sẽ là tên chủ sở hữu.
  • description (str, tùy chọn) — Mô tả của bộ sưu tập cần tạo. Kích thước tối đa cho một mô tả là 150 ký tự.
  • private (bool, tuỳ chọn) — Xác định xem bộ sưu tập có nên là riêng tư hay không. Mặc định là False (tức là bộ sưu tập công khai).
  • resource_group_id (str, tùy chọn) — Gán bộ sưu tập cho một nhóm tài nguyên của tổ chức sở hữu. Chỉ hợp lệ đối với các bộ sưu tập thuộc sở hữu của tổ chức. ID nhóm tài nguyên là một chuỗi thập lục phân 24 ký tự.
  • exists_ok (bool, tùy chọn) — Nếu True, không gây ra lỗi nếu bộ sưu tập đã tồn tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Tạo một Collection mới trên Hub.

Trả về: Collection

Ví dụ:

>>> from huggingface_hub import create_collection
>>> collection = create_collection(
...     title="ICCV 2023",
...     description="Portfolio of models, papers and demos I presented at ICCV 2023",
... )
>>> collection.slug
"username/iccv-2023-64f9a55bb3115b4f513ec026"

create_commit

< >

( repo_id: stroperations: Iterable[CommitOperation]commit_message: strcommit_description: str | None = Nonetoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecreate_pr: bool | None = Nonenum_threads: int = 5parent_commit: str | None = Nonerun_as_future: bool = False_hot_reload: bool | None = None ) → CommitInfo or Future

Tham số

  • repo_id (str) — Kho lưu trữ mà commit sẽ được tạo, ví dụ: "username/custom_transformers"
  • operations (Iterable của ~hf_api.CommitOperation) — Một iterable chứa các thao tác cần đưa vào commit, bao gồm:
    • ~hf_api.CommitOperationAdd để tải lên một tệp
    • ~hf_api.CommitOperationDelete để xóa một tệp
    • ~hf_api.CommitOperationCopy để sao chép một tệp

    Các đối tượng Operation sẽ bị thay đổi để bao gồm thông tin liên quan đến việc tải lên. Không tái sử dụng cùng các đối tượng đó cho nhiều lần commit.

  • commit_message (str) — Tóm tắt (dòng đầu tiên) của commit sẽ được tạo.
  • commit_description (str, tùy chọn) — Mô tả của commit sẽ được tạo
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset", "space" hoặc "kernel" nếu tải lên kho dataset, space hoặc kernel, None hoặc "model" nếu tải lên model. Mặc định là None.
  • revision (str, tùy chọn) — Phiên bản git để commit từ. Mặc định là đầu của nhánh "main".
  • create_pr (boolean, tùy chọn) — Có tạo Pull Request với commit đó hay không. Mặc định là False. Nếu revision không được đặt, PR sẽ được mở đối với nhánh "main". Nếu revision được đặt và là một nhánh, PR sẽ được mở đối với nhánh này. Nếu revision được đặt và không phải là tên nhánh (ví dụ: một commit oid), RevisionNotFoundError sẽ được trả về bởi máy chủ.
  • num_threads (int, tùy chọn) — Số lượng luồng đồng thời để tải tệp lên. Mặc định là 5. Đặt thành 2 nghĩa là tối đa 2 tệp sẽ được tải lên đồng thời.
  • parent_commit (str, tùy chọn) — OID / SHA của commit cha, dưới dạng chuỗi hex. Các dạng viết tắt (7 ký tự đầu tiên) cũng được hỗ trợ. Nếu được chỉ định và create_pr là False, commit sẽ thất bại nếu revision không trỏ đến parent_commit. Nếu được chỉ định và create_pr là True, pull request sẽ được tạo từ parent_commit. Việc chỉ định parent_commit đảm bảo rằng repo không bị thay đổi trước khi commit các thay đổi, và đặc biệt hữu ích nếu repo được cập nhật / commit đồng thời.
  • run_as_future (bool, tùy chọn) — Có chạy phương thức này ở nền hay không. Các tác vụ nền được chạy tuần tự mà không chặn luồng chính. Truyền run_as_future=True sẽ trả về một đối tượng Future. Mặc định là False.

Trả về

CommitInfo hoặc Future

Thư mục CommitInfo chứa thông tin về commit mới được tạo (commit hash, commit url, pr url, commit message,…). Nếu run_as_future=True được truyền vào, sẽ trả về một đối tượng Future chứa kết quả khi được thực thi.

Gây ra

ValueError hoặc RepositoryNotFoundError

  • ValueError — Nếu thông báo commit trống.
  • ValueError — Nếu commit cha không phải là OID commit hợp lệ.
  • ValueError — Nếu một tệp README.md có phần metadata không hợp lệ được commit. Trong trường hợp này, commit sẽ thất bại sớm, trước khi cố gắng tải lên bất kỳ tệp nào.
  • ValueError — Nếu create_pr là True và revision không phải là None hay "main".
  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho riêng tư nhưng chưa xác thực hoặc kho không tồn tại.

Tạo một commit trong kho đã cho, xóa & tải lên các tệp khi cần.

Danh sách đầu vào CommitOperation sẽ bị thay đổi trong quá trình commit. Không tái sử dụng cùng các đối tượng cho nhiều lần commit.

create_commit giả định rằng kho đã tồn tại trên Hub. Nếu bạn gặp lỗi Client 404, hãy đảm bảo rằng bạn đã xác thực, token của bạn có các quyền cần thiết, và repo_id cùng repo_type được đặt đúng. Nếu kho chưa tồn tại, hãy tạo nó trước bằng create_repo().

create_commit bị giới hạn ở 25k tệp LFS và 1GB payload cho các tệp thông thường.

tạo thảo luận

< >

( repo_id: strtitle: strtoken: bool | str | None = Nonedescription: str | None = Nonerepo_type: str | None = Nonepull_request: bool = False )

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • title (str) — Tiêu đề của cuộc thảo luận. Độ dài tối đa là 200 ký tự, và phải có ít nhất 3 ký tự. Khoảng trắng ở đầu và cuối sẽ bị loại bỏ.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • description (str, tùy chọn) — Mô tả tùy chọn cho Pull Request. Mặc định là "Discussion opened with the huggingface_hub Python library"
  • pull_request (bool, tùy chọn) — Có tạo Pull Request hay thảo luận hay không. Nếu True, sẽ tạo Pull Request. Nếu False, sẽ tạo thảo luận. Mặc định là False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.

Tạo một Discussion hoặc Pull Request.

Các Pull Request được tạo bằng chương trình sẽ ở trạng thái "draft".

Việc tạo một Pull Request kèm theo các thay đổi cũng có thể được thực hiện ngay lập tức bằng HfApi.create_commit().

Trả về: DiscussionWithDetails

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

create_inference_endpoint

< >

( name: strrepository: strframework: straccelerator: strinstance_size: strinstance_type: strregion: strvendor: straccount_id: str | None = Noneprivate_link_account_id: str | None = Noneprivate_link_region: str | None = Nonemin_replica: int = 1max_replica: int = 1scaling_metric: InferenceEndpointScalingMetric | None = Nonescaling_threshold: float | None = Nonescale_to_zero_timeout: int | None = Nonerevision: str | None = Nonetask: str | None = Nonecustom_image: dict | None = Nonecontainer_registry_username: str | None = Nonecontainer_registry_password: str | None = Nonecontainer_command: list[str] | None = Nonecontainer_args: list[str] | None = Noneenv: dict[str, str] | None = Nonesecrets: dict[str, str] | None = Nonetype: InferenceEndpointType | str = <InferenceEndpointType.AUTHENTICATED: 'authenticated'>domain: str | None = Nonepath: str | None = Nonecache_http_responses: bool | None = Nonetags: list[str] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint

Tham số

  • name (str) — Tên duy nhất cho Inference Endpoint mới.
  • repository (str) — Tên của kho mô hình liên quan đến Inference Endpoint (ví dụ: "gpt2").
  • framework (str) — Khung machine learning được sử dụng cho mô hình (ví dụ: "custom").
  • accelerator (str) — Bộ tăng tốc phần cứng được sử dụng cho suy luận (ví dụ: "cpu").
  • instance_size (str) — Kích thước hoặc loại instance được sử dụng để lưu trữ model (ví dụ: "x4").
  • instance_type (str) — Loại instance trên cloud nơi Inference Endpoint sẽ được triển khai (ví dụ: "intel-icl").
  • region (str) — Khu vực đám mây nơi Inference Endpoint sẽ được tạo (ví dụ: "us-east-1").
  • vendor (str) — Nhà cung cấp đám mây hoặc nhà cung cấp nơi Inference Endpoint sẽ được triển khai (ví dụ: "aws").
  • account_id (str, tùy chọn) — Đã bị hủy bỏ và bị bỏ qua. Hãy sử dụng private_link_account_id và private_link_region để cấu hình AWS PrivateLink.
  • private_link_account_id (str, tùy chọn) — ID tài khoản AWS được phép truy cập Inference Endpoint thông qua AWS PrivateLink. Yêu cầu private_link_region.
  • private_link_region (str, tùy chọn) — Khu vực AWS của điểm vào PrivateLink ("us-east-1" hoặc "eu-west-1"), nơi endpoint VPC của private_link_account_id sẽ kết nối. Độc lập với region và vendor của compute.
  • min_replica (int, tùy chọn) — Số lượng tối thiểu các bản sao (instance) cần duy trì hoạt động cho Inference Endpoint. Để bật tính năng scale về 0, hãy đặt giá trị này thành 0 và điều chỉnh scale_to_zero_timeout cho phù hợp. Mặc định là 1.
  • max_replica (int, tùy chọn) — Số lượng bản sao (instance) tối đa để mở rộng cho Inference Endpoint. Mặc định là 1.
  • scaling_metric (str hoặc InferenceEndpointScalingMetric , tùy chọn) — Tham chiếu chỉ số cho việc mở rộng. Là “pendingRequests” hoặc “hardwareUsage” khi được cung cấp. Mặc định là None (nghĩa là: để dịch vụ HF Endpoints chỉ định chỉ số).
  • scaling_threshold (float, tùy chọn) — Ngưỡng của chỉ số đo lường mở rộng (scaling metric) được dùng để kích hoạt việc mở rộng lên (scale up). Bỏ qua khi không cung cấp chỉ số đo lường mở rộng. Mặc định là None (nghĩa là: để dịch vụ HF Endpoints xác định ngưỡng).
  • scale_to_zero_timeout (int, tùy chọn) — Thời lượng tính bằng phút trước khi một endpoint không hoạt động bị thu về mức không, hoặc không thu về mức không nếu được đặt là None và min_replica không phải 0. Mặc định là None.
  • revision (str, tùy chọn) — Phiên bản cụ thể của mô hình cần triển khai trên Inference Endpoint (ví dụ: "6c0e6080953db56375760c0471a8c5f2929baf11").
  • task (str, tùy chọn) — Nhiệm vụ để triển khai mô hình (ví dụ: "text-classification").
  • custom_image (dict, tùy chọn) — Ảnh container để chạy. Có thể là một dict có khóa theo biến thể ảnh (ví dụ {"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}‌}, cũng như sGLang, tgi, tei, llamacpp, hfServe, …), được chuyển tiếp nguyên vẹn, hoặc một dict phẳng mô tả một container tùy chỉnh (ví dụ {"url": ..., "port": ...}), được gửi dưới dạng {"custom": ...} (xem các ví dụ). Mặc định là ảnh do Hugging Face quản lý.
  • container_registry_username (str, tùy chọn) — Tên người dùng được sử dụng để xác thực với registry lưu trữ hình ảnh container tùy chỉnh.
  • container_registry_password (str, tùy chọn) — Mật khẩu được sử dụng để xác thực với registry lưu trữ hình ảnh container tùy chỉnh. Yêu cầu container_registry_username. Bỏ qua khỏi API payload khi không được cung cấp.
  • container_command (list[str], tùy chọn) — Ghi đè lệnh entrypoint của container (tương ứng với model.command trong API payload). Hoạt động với cả các image engine được quản lý (ví dụ: vLLM, SGLang) và các image tùy chỉnh.
  • container_args (list[str], tùy chọn) — Các đối số được thêm vào entrypoint của container (tương ứng với model.args trong API payload). Hoạt động với cả các image engine được quản lý (ví dụ: vLLM, SGLang) và các image tùy chỉnh.
  • env (dict[str, str], tùy chọn) — Các biến môi trường không bí mật để tiêm vào môi trường của container.
  • secrets (dict[str, str], tùy chọn) — Các giá trị bí mật để tiêm vào môi trường của container.
  • type ([`InferenceEndpointType], *optional*) -- The type of the Inference Endpoint, which can be “authenticated”(default),“public”or“private”`.
  • domain (str, tùy chọn) — Domain tùy chỉnh cho việc triển khai Inference Endpoint; nếu được cấu hình, inference endpoint sẽ khả dụng tại domain này (ví dụ: "my-new-domain.cool-website.woof").
  • path (str, tùy chọn) — Đường dẫn tùy chỉnh đến mô hình đã triển khai, phải bắt đầu bằng / (ví dụ: "/models/google-bert/bert-base-uncased").
  • cache_http_responses (bool, tùy chọn) — Có nên lưu bộ nhớ đệm các phản hồi HTTP từ Inference Endpoint hay không. Mặc định là False.
  • tags (list[str], tùy chọn) — Danh sách các thẻ để liên kết với Inference Endpoint.
  • namespace (str, optional) — Namespace nơi Inference Endpoint sẽ được tạo. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

InferenceEndpoint

thông tin về Inference Endpoint đã được cập nhật.

Tạo một Inference Endpoint mới.

Các giá trị accelerator, instance_size, instance_type, region và vendor có mối quan hệ phụ thuộc lẫn nhau; hãy sử dụng list_inference_endpoints_hardware() để liệt kê các tổ hợp hợp lệ.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
...     "my-endpoint-name",
...     repository="gpt2",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="cpu",
...     vendor="aws",
...     region="us-east-1",
...     type="authenticated",
...     instance_size="x2",
...     instance_type="intel-icl",
... )
>>> endpoint
InferenceEndpoint(name='my-endpoint-name', status="pending",...)

# Run inference on the endpoint
>>> endpoint.client.text_generation(...)
"..."
# Start an Inference Endpoint running Zephyr-7b-beta on TGI
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
...     "aws-zephyr-7b-beta-0486",
...     repository="HuggingFaceH4/zephyr-7b-beta",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="gpu",
...     vendor="aws",
...     region="us-east-1",
...     type="authenticated",
...     instance_size="x1",
...     instance_type="nvidia-a10g",
...     env={
...           "MAX_BATCH_PREFILL_TOKENS": "2048",
...           "MAX_INPUT_LENGTH": "1024",
...           "MAX_TOTAL_TOKENS": "1512",
...           "MODEL_ID": "/repository"
...         },
...     custom_image={
...         "healthRoute": "/health",
...         "url": "ghcr.io/huggingface/text-generation-inference:1.1.0",
...     },
...    secrets={"MY_SECRET_KEY": "secret_value"},
...    tags=["dev", "text-generation"],
... )
# Start an Inference Endpoint running ProsusAI/finbert while scaling to zero in 15 minutes
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
...     "finbert-classifier",
...     repository="ProsusAI/finbert",
...     framework="pytorch",
...     task="text-classification",
...     min_replica=0,
...     scale_to_zero_timeout=15,
...     accelerator="cpu",
...     vendor="aws",
...     region="us-east-1",
...     type="authenticated",
...     instance_size="x2",
...     instance_type="intel-icl",
... )
>>> endpoint.wait(timeout=300)
# Run inference on the endpoint
>>> endpoint.client.text_generation(...)
TextClassificationOutputElement(label='positive', score=0.8983615040779114)

create_inference_endpoint_from_catalog

< >

( repo_id: str | None = Nonerecipe_id: str | None = Nonename: str | None = Noneaccelerator: Literal['cpu', 'gpu', 'neuron'] | str | None = Nonegguf_file: str | None = Nonetoken: bool | str | None = Nonenamespace: str | None = None ) → InferenceEndpoint

Tham số

  • repo_id (str, tùy chọn) — ID của model trong catalog để triển khai dưới dạng Inference Endpoint. Loại trừ lẫn nhau với recipe_id.
  • recipe_id (str, tùy chọn) — ID của công thức trong catalog cần triển khai (xem InferenceCatalogRecipe). Loại trừ lẫn nhau với repo_id.
  • name (str, tùy chọn) — Tên duy nhất cho Inference Endpoint mới. Nếu không được cung cấp, một tên ngẫu nhiên sẽ được tạo ra.
  • accelerator (str, tùy chọn) — Bộ tăng tốc phần cứng được sử dụng cho suy luận. Các giá trị có thể bao gồm "cpu", "gpu" và "neuron". Nếu không được cung cấp, máy chủ sẽ sử dụng giá trị mặc định phù hợp với mô hình. Chỉ hợp lệ khi dùng với repo_id.
  • gguf_file (str, tùy chọn) — Tệp GGUF cần triển khai, dành cho các mô hình có một công thức cho mỗi mức lượng tử hóa (ví dụ: "Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf"). Chỉ hợp lệ khi dùng với repo_id.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication).
  • namespace (str, optional) — Namespace nơi Inference Endpoint sẽ được tạo. Mặc định là namespace của người dùng hiện tại.

Trả về

InferenceEndpoint

thông tin về Inference Endpoint mới.

Tạo một Inference Endpoint mới từ Hugging Face Inference Catalog.

Mục tiêu của Inference Catalog là cung cấp một danh sách các mô hình được tuyển chọn, tối ưu cho suy luận và đã được kiểm tra với các cấu hình mặc định. Xem https://huggingface.co/proxy/endpoints.huggingface.co/catalog để xem danh sách các mô hình có sẵn trong catalog.

Mỗi model trong catalog được triển khai thông qua một recipe: một tổ hợp phần cứng và engine đã được kiểm tra cho model đó. Truyền repo_id để triển khai recipe mặc định của một model, có thể thu hẹp phạm vi bằng accelerator và gguf_file, hoặc truyền recipe_id để triển khai một recipe cụ thể được liệt kê bởi list_inference_catalog().

create_inference_endpoint_from_catalog là thử nghiệm. API của nó có thể thay đổi trong tương lai. Vui lòng cung cấp phản hồi nếu bạn có bất kỳ đề xuất hoặc yêu cầu nào.

create_pull_request

< >

( repo_id: strtitle: strtoken: bool | str | None = Nonedescription: str | None = Nonerepo_type: str | None = None )

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • title (str) — Tiêu đề của cuộc thảo luận. Độ dài tối đa là 200 ký tự, và phải có ít nhất 3 ký tự. Khoảng trắng ở đầu và cuối sẽ bị loại bỏ.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • description (str, tùy chọn) — Mô tả tùy chọn cho Pull Request. Mặc định là "Discussion opened with the huggingface_hub Python library"
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.

Tạo một Pull Request. Các Pull Request được tạo bằng chương trình sẽ ở trạng thái "draft".

Việc tạo một Pull Request kèm theo các thay đổi cũng có thể được thực hiện ngay lập tức bằng HfApi.create_commit();

Đây là một lớp bọc quanh HfApi.create_discussion().

Trả về: DiscussionWithDetails

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

create_repo

< >

( repo_id: strtoken: str | bool | None = Noneprivate: bool | None = Nonevisibility: RepoVisibility_T | None = Nonerepo_type: str | None = Noneexist_ok: bool = Falseresource_group_id: str | None = Noneregion: REPO_REGIONS | None = Nonespace_sdk: str | None = Nonespace_hardware: SpaceHardware | None = Nonespace_sleep_time: int | None = Nonespace_secrets: list[dict[str, str]] | None = Nonespace_variables: list[dict[str, str]] | None = Nonespace_volumes: list[Volume] | None = Nonespace_template: str | None = None ) → RepoUrl

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • private (bool, optional) — Có nên đặt kho thành riêng tư hay không. Nếu là None (mặc định), kho sẽ là công khai trừ khi mặc định của tổ chức là riêng tư. Giá trị này bị bỏ qua nếu kho đã tồn tại. Không thể truyền cùng với visibility.
  • visibility (Literal["public", "private", "protected"], optional) — Mức độ hiển thị của kho. Có thể là "public" hoặc "private", hoặc "protected" đối với Spaces. Nếu là None (mặc định), kho sẽ là công khai trừ khi mặc định của tổ chức là riêng tư. Giá trị này bị bỏ qua nếu kho đã tồn tại.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.
  • exist_ok (bool, tùy chọn, mặc định là False) — Nếu True, không gây ra lỗi nếu kho đã tồn tại.
  • resource_group_id (str, tùy chọn) — Nhóm tài nguyên để tạo kho. Nhóm tài nguyên chỉ khả dụng cho các tổ chức Enterprise Hub và cho phép xác định thành viên nào trong tổ chức có thể truy cập tài nguyên. ID của một nhóm tài nguyên có thể tìm thấy trong URL của trang tài nguyên trên Hub (ví dụ: "66670e5163145ca562cb1988"). Để tìm hiểu thêm về nhóm tài nguyên, xem https://huggingface.co/docs/hub/en/security-resource-groups.
  • region (Literal["us", "eu"], tùy chọn) — Khu vực cloud để tạo kho. Có thể là "us" hoặc "eu". Nếu không được chỉ định, kho sẽ được tạo trong khu vực mặc định. Yêu cầu gói Team hoặc cao hơn.
  • space_sdk (str, tuỳ chọn) — Lựa chọn SDK để sử dụng nếu repo_type là “space”. Có thể là “streamlit”, “gradio”, “docker” hoặc “static”. Các Space "static" miễn phí cho tất cả mọi người. Các SDK khác chạy trên phần cứng tính toán: trên phần cứng cpu-basic miễn phí, chúng yêu cầu một gói đăng ký (PRO cho người dùng, Team hoặc Enterprise cho tổ chức), trong khi phần cứng trả phí chỉ yêu cầu thanh toán (phương thức thanh toán và tín dụng trả trước).
  • space_hardware (SpaceHardware hoặc str, tùy chọn) — Lựa chọn phần cứng nếu repo_type là “space”. Xem SpaceHardware để biết danh sách đầy đủ.
  • space_sleep_time (int, tùy chọn) — Số giây không hoạt động cần chờ trước khi một Space được đưa vào trạng thái ngủ. Đặt thành -1 nếu bạn không muốn Space của bạn ngủ (hành vi mặc định cho phần cứng đã nâng cấp). Đối với phần cứng miễn phí, bạn không thể cấu hình thời gian ngủ (giá trị được cố định ở mức 48 giờ không hoạt động). Xem https://huggingface.co/docs/hub/spaces-gpus#sleep-time để biết thêm chi tiết.
  • space_secrets (list[dict[str, str]], tùy chọn) — Một danh sách các khóa bí mật cần thiết lập trong Space của bạn. Mỗi mục có dạng {"key": ..., "value": ..., "description": ...} trong đó description là tùy chọn. Để biết thêm chi tiết, xem https://huggingface.co/docs/hub/spaces-overview#managing-secrets.
  • space_variables (list[dict[str, str]], tùy chọn) — Một danh sách các biến môi trường công khai để thiết lập trong Space của bạn. Mỗi mục có dạng {"key": ..., "value": ..., "description": ...} trong đó description là tùy chọn. Để biết thêm chi tiết, xem https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables.
  • space_volumes (list[Volume], tùy chọn) — Một danh sách các đối tượng Volume để gắn (mount) vào Space khi tạo. Mỗi volume có một type ("bucket", "model", "dataset", hoặc "space"), một source (ID của repo hoặc bucket), một mount_path (đường dẫn bên trong container), và các trường tùy chọn revision, read_only, và path. Chỉ áp dụng nếu repo_type là “space”.
  • space_template (str, tùy chọn) — Khởi tạo Space mới từ một mẫu chính thức. Có thể là id của kho mẫu (ví dụ "SpacesExamples/jupyterlab") hoặc tên ngắn của nó (ví dụ "JupyterLab"). Sử dụng HfApi.list_space_templates() để liệt kê các mẫu khả dụng. Chỉ áp dụng nếu repo_type là “space”. Nếu mẫu được khuyến nghị là riêng tư và visibility không được đặt rõ ràng, Space sẽ được tạo ở chế độ riêng tư.

Trả về

RepoUrl

URL của kho vừa được tạo. Giá trị là một lớp con của str chứa các thuộc tính như endpoint, repo_type và repo_id.

Tạo một kho trống trên HuggingFace Hub.

create_scheduled_job

< >

( image: strcommand: list[str]schedule: strsuspend: bool | None = Noneconcurrency: bool | None = Noneenv: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • image (str) — Ảnh Docker cần sử dụng. Ví dụ: "ubuntu", "python:3.12", "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel". Ví dụ với một ảnh từ một Space: "hf.co/spaces/lhoestq/duckdb".
  • command (list[str]) — Lệnh cần thực thi. Ví dụ: ["echo", "hello"].
  • schedule (str) — Một trong các giá trị “@annually”, “@yearly”, “@monthly”, “@weekly”, “@daily”, “@hourly”, hoặc một biểu thức lịch CRON (ví dụ: ‘0 9 * * 1’ cho 9 giờ sáng mỗi thứ Hai).
  • suspend (bool, tùy chọn) — Nếu là True, Job được lên lịch sẽ bị tạm dừng. Mặc định là False.
  • concurrency (bool, tùy chọn) — Nếu là True, nhiều phiên bản của Job này có thể chạy đồng thời. Mặc định là False.
  • env (dict[str, Any], tùy chọn) — Định nghĩa các biến môi trường cho Job.
  • secrets (dict[str, Any], tùy chọn) — Định nghĩa các biến môi trường bí mật cho Job.
  • flavor (str, tùy chọn) — Flavor cho phần cứng. Xem JobHardware để biết các giá trị có thể. Mặc định là "cpu-basic".
  • timeout (Union[int, float, str], tùy chọn) — Thời lượng tối đa cho Job: int với s (giây, mặc định), m (phút), h (giờ) hoặc d (ngày). Ví dụ: 300 hoặc "5m" cho 5 phút.
  • attempts (int, tùy chọn) — Số lần thử tối đa cho mỗi lần chạy, bao gồm cả lần thử ban đầu. Mặc định là 1.
  • name (str, tùy chọn) — Tên cho Job được lên lịch. Được lưu dưới dạng nhãn name. Không thể truyền cùng với khóa name trong labels. Tên không nhất thiết phải duy nhất. Mặc định là tên được suy ra từ image và command (kèm hậu tố hash ngắn).
  • labels (dict[str, str], tùy chọn) — Nhãn cần gắn cho tác vụ (các cặp khóa-giá trị).
  • volumes (list[Volume], tùy chọn) — Các Hugging Face Buckets hoặc Repos để gắn làm volumes trong container của job. Mỗi volume là một Volume có type ("bucket", "model", "dataset" hoặc "space"), source (ví dụ "username/my-bucket") và mount_path (ví dụ "/data").
  • expose (list[int], tuỳ chọn) — Các cổng container cần mở qua jobs proxy. Mỗi cổng được liệt kê sẽ có thể truy cập trên tên miền jobs công khai (ví dụ: https://<job_id>--8000.hf.jobs). Việc truy cập luôn yêu cầu một HF token có quyền đọc vào namespace của job. Sử dụng expose_public để cho phép truy cập không cần xác thực.
  • expose_public (list[int], tuỳ chọn) — Các cổng cần mở qua proxy của Jobs mà không cần xác thực. Chúng không cần được liệt kê trong expose.
  • resource_group_id (str, tuỳ chọn) — ID của nhóm tài nguyên để tạo Job được lên lịch. Được sử dụng để kiểm soát quyền truy cập vào các tài nguyên trong tổ chức và cho các tính năng gán chi phí/giới hạn chi tiêu. Nếu không được cung cấp, Job được lên lịch sẽ được tạo bên ngoài bất kỳ nhóm tài nguyên nào.
  • namespace (str, optional) — Namespace nơi Job sẽ được tạo. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Tạo các Job tính toán được lên lịch trên hạ tầng của Hugging Face.

Ví dụ:

Tạo Job được lên lịch đầu tiên của bạn:

>>> from huggingface_hub import create_scheduled_job
>>> create_scheduled_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"], schedule="@hourly")

Sử dụng biểu thức lịch CRON:

>>> from huggingface_hub import create_scheduled_job
>>> create_scheduled_job(image="python:3.12", command=["python", "-c" ,"print('this runs every 5min')"], schedule="*/5 * * * *")

Tạo một GPU Job được lên lịch:

>>> from huggingface_hub import create_scheduled_job
>>> image = "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel"
>>> command = ["python", "-c", "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"]
>>> create_scheduled_job(image=image, command=command, flavor="a10g-small", schedule="@hourly")

create_scheduled_uv_job

< >

( script: strscript_args: list[str] | None = Noneschedule: strsuspend: bool | None = Noneconcurrency: bool | None = Nonedependencies: list[str] | None = Nonepython: str | None = Noneimage: str | None = Noneenv: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • script (str) — Đường dẫn hoặc URL của script UV, hoặc một lệnh.
  • script_args (list[str], tùy chọn) — Các đối số để truyền cho script hoặc lệnh.
  • schedule (str) — Một trong các giá trị “@annually”, “@yearly”, “@monthly”, “@weekly”, “@daily”, “@hourly”, hoặc một biểu thức lịch CRON (ví dụ: ‘0 9 * * 1’ cho 9 giờ sáng mỗi thứ Hai).
  • suspend (bool, tùy chọn) — Nếu là True, Job được lên lịch sẽ bị tạm dừng. Mặc định là False.
  • concurrency (bool, tùy chọn) — Nếu là True, nhiều phiên bản của Job này có thể chạy đồng thời. Mặc định là False.
  • dependencies (list[str], tùy chọn) — Các phụ thuộc cần dùng để chạy script UV.
  • python (str, tùy chọn) — Sử dụng một phiên bản Python cụ thể. Mặc định là 3.12.
  • image (str, tùy chọn, mặc định là “ghcr.io/astral-sh/uv —python3.12-bookworm”): Sử dụng hình ảnh Docker tùy chỉnh có cài đặt uv.
  • env (dict[str, Any], tùy chọn) — Định nghĩa các biến môi trường cho Job.
  • secrets (dict[str, Any], tùy chọn) — Định nghĩa các biến môi trường bí mật cho Job.
  • flavor (str, tùy chọn) — Flavor cho phần cứng. Xem JobHardware để biết các giá trị có thể. Mặc định là "cpu-basic".
  • timeout (Union[int, float, str], tùy chọn) — Thời lượng tối đa cho Job: int với s (giây, mặc định), m (phút), h (giờ) hoặc d (ngày). Ví dụ: 300 hoặc "5m" cho 5 phút.
  • attempts (int, tùy chọn) — Số lần thử tối đa cho mỗi lần chạy, bao gồm cả lần thử ban đầu. Mặc định là 1.
  • name (str, tùy chọn) — Tên cho Job được lên lịch. Được lưu dưới dạng nhãn name. Không thể truyền cùng với khóa name trong labels. Tên không nhất thiết phải duy nhất. Mặc định là tên được suy ra từ script và các đối số của nó (kèm hậu tố hash ngắn).
  • labels (dict[str, str], tùy chọn) — Nhãn cần gắn cho tác vụ (các cặp khóa-giá trị).
  • volumes (list[Volume], tùy chọn) — Các Hugging Face Buckets hoặc Repos để gắn làm volumes trong container của job. Mỗi volume là một Volume có type ("bucket", "model", "dataset" hoặc "space"), source (ví dụ "username/my-bucket") và mount_path (ví dụ "/data").
  • expose (list[int], tuỳ chọn) — Các cổng container cần mở qua jobs proxy. Mỗi cổng được liệt kê sẽ có thể truy cập trên tên miền jobs công khai (ví dụ: https://<job_id>--8000.hf.jobs). Việc truy cập luôn yêu cầu một HF token có quyền đọc vào namespace của job. Sử dụng expose_public để cho phép truy cập không cần xác thực.
  • expose_public (list[int], tuỳ chọn) — Các cổng cần mở qua proxy của Jobs mà không cần xác thực. Chúng không cần được liệt kê trong expose.
  • resource_group_id (str, tuỳ chọn) — ID của nhóm tài nguyên để tạo Job được lên lịch. Được sử dụng để kiểm soát quyền truy cập vào các tài nguyên trong tổ chức và cho các tính năng gán chi phí/giới hạn chi tiêu. Nếu không được cung cấp, Job được lên lịch sẽ được tạo bên ngoài bất kỳ nhóm tài nguyên nào.
  • namespace (str, optional) — Namespace nơi Job sẽ được tạo. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Chạy một Job script UV trên hạ tầng của Hugging Face.

Khác với hf jobs uv run, phương pháp này bỏ qua bảng tùy chọn [tool.hf-jobs] mà một kịch bản UV có thể chứa trong phần tiêu đề PEP 723 của nó (xem hướng dẫn về Jobs): cấu hình khởi chạy phải được truyền vào một cách tường minh tại đây.

Ví dụ:

Lịch chạy một script từ URL:

>>> from huggingface_hub import create_scheduled_uv_job
>>> script = "https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> create_scheduled_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small", schedule="@weekly")

Lịch một script cục bộ:

>>> from huggingface_hub import create_scheduled_uv_job
>>> script = "my_sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> create_scheduled_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small", schedule="@weekly")

Lên lịch một lệnh:

>>> from huggingface_hub import create_scheduled_uv_job
>>> script = "lighteval"
>>> script_args= ["endpoint", "inference-providers", "model_name=openai/gpt-oss-20b,provider=auto", "lighteval|gsm8k|0|0"]
>>> create_scheduled_uv_job(script, script_args=script_args, dependencies=["lighteval"], flavor="a10g-small", schedule="@weekly")

create_tag

< >

( repo_id: strtag: strtag_message: str | None = Nonerevision: str | None = Nonetoken: bool | str | None = Nonerepo_type: str | None = Noneexist_ok: bool = False )

Tham số

  • repo_id (str) — Kho lưu trữ mà một commit sẽ được gắn thẻ. Ví dụ: "user/my-cool-model".
  • tag (str) — Tên của tag cần tạo.
  • tag_message (str, tùy chọn) — Mô tả của thẻ cần tạo.
  • revision (str, tùy chọn) — Phiên bản git cần gắn thẻ. Có thể là tên nhánh hoặc OID/SHA của một commit, dưới dạng chuỗi hex. Các dạng viết tắt (7 ký tự đầu tiên) cũng được hỗ trợ. Mặc định là đầu của nhánh "main".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu gắn thẻ cho một dataset hoặc space, None hoặc "model" nếu gắn thẻ cho một model. Mặc định là None.
  • exist_ok (bool, tùy chọn, mặc định là False) — Nếu True, không gây ra lỗi nếu tag đã tồn tại.

Gây ra

RepositoryNotFoundError hoặc RevisionNotFoundError hoặc HfHubHTTPError

  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho riêng tư nhưng chưa xác thực hoặc kho không tồn tại.
  • RevisionNotFoundError — Nếu không tìm thấy revision (lỗi 404) trên repo.
  • HfHubHTTPError — Nếu nhánh đã tồn tại trên kho (lỗi 409) và exist_ok được đặt thành False.

Đánh dấu một commit cụ thể của một kho trên Hub.

create_webhook

< >

( url: str | None = Nonejob_id: str | None = Nonewatched: list[dict | WebhookWatchedItem]domains: list[constants.WEBHOOK_DOMAIN_T] | None = Nonesecret: str | None = Nonesecrets: dict[str, str] | None = Nonetoken: bool | str | None = None ) → WebhookInfo

Tham số

  • url (str) — URL để gửi payload tới.
  • job_id (str) — ID của Job nguồn để kích hoạt bằng webhook payload trong biến môi trường WEBHOOK_PAYLOAD. Các biến môi trường bổ sung có sẵn để tiện lợi: WEBHOOK_REPO_ID, WEBHOOK_REPO_TYPE và WEBHOOK_SECRET.
  • watched (list[WebhookWatchedItem]) — Danh sách các WebhookWatchedItem để webhook theo dõi. Các mục này có thể là users, orgs, models, datasets, spaces hoặc buckets. Các mục được theo dõi cũng có thể được cung cấp dưới dạng các từ điển thông thường.
  • domains (list[Literal["repo", "discussion"]], optional) — Danh sách các domain cần theo dõi. Có thể là “repo”, “discussion” hoặc cả hai. Mặc định là cả hai.
  • secret (str, optional) — Một bí mật để ký cho payload.
  • secrets (dict[str, str], optional) — Các biến môi trường bí mật cho Job được kích hoạt bởi webhook (ví dụ: {"HF_TOKEN": "hf_***"}). Chỉ hợp lệ với job_id. Các secrets của Job nguồn không được sao chép sang webhook, vì vậy hãy truyền chúng tại đây.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

WebhookInfo

Thông tin về webhook mới được tạo.

Tạo một webhook mới.

Webhook có thể gửi payload đến một URL, hoặc kích hoạt một Job để chạy trên hạ tầng của Hugging Face. Hàm này nên được gọi với một trong url hoặc job_id, nhưng không được dùng cả hai.

Ví dụ:

Tạo một webhook gửi payload đến một URL

>>> from huggingface_hub import create_webhook
>>> payload = create_webhook(
...     watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
...     url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
...     domains=["repo", "discussion"],
...     secret="my-secret",
... )
>>> print(payload)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    job=None,
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=False,
)

Chạy một Job sau đó tạo một webhook kích hoạt Job này

>>> from huggingface_hub import create_webhook, run_job
>>> job = run_job(
...     image="ubuntu",
...     command=["bash", "-c", r"echo An event occurred in $WEBHOOK_REPO_ID: $WEBHOOK_PAYLOAD"],
... )
>>> payload = create_webhook(
...     watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
...     job_id=job.id,
...     domains=["repo", "discussion"],
...     secret="my-secret",
... )
>>> print(payload)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    url=None,
    job=JobSpec(
        docker_image='ubuntu',
        space_id=None,
        command=['bash', '-c', 'echo An event occurred in $WEBHOOK_REPO_ID: $WEBHOOK_PAYLOAD'],
        arguments=[],
        environment={},
        secrets=[],
        flavor='cpu-basic',
        timeout=None,
        tags=None,
        arch=None
    ),
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=False,
)

dataset_info

< >

( repo_id: strrevision: str | None = Nonetimeout: float | None = Nonefiles_metadata: bool = Falseexpand: list[ExpandDatasetProperty_T] | None = Nonetoken: bool | str | None = None ) → hf_api.DatasetInfo

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • revision (str, tùy chọn) — Phiên bản của kho dữ liệu để lấy thông tin.
  • timeout (float, tùy chọn) — Có nên đặt thời gian chờ cho yêu cầu đến Hub hay không.
  • files_metadata (bool, tùy chọn) — Có lấy hay không lấy metadata cho các tệp trong kho (kích thước, metadata LFS, v.v.). Mặc định là False.
  • expand (list[ExpandDatasetProperty_T], tuỳ chọn) — Danh sách các thuộc tính cần trả về trong phản hồi. Khi được sử dụng, chỉ các thuộc tính trong danh sách sẽ được trả về. Tham số này không thể được sử dụng nếu files_metadata được truyền vào. Các giá trị có thể là "author", "cardData", "citation", "createdAt", "disabled", "description", "downloads", "downloadsAllTime", "gated", "lastModified", "likes", "mainSize", "paperswithcode_id", "private", "siblings", "sha", "tags", "trendingScore", "usedStorage" và "resourceGroup".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

hf_api.DatasetInfo

Thông tin về kho dữ liệu.

Lấy thông tin về một tập dữ liệu cụ thể trên huggingface.co.

Dataset có thể là private nếu bạn truyền vào một token hợp lệ.

Gây ra các lỗi sau:

  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.
  • RevisionNotFoundError Nếu không tìm thấy revision cần tải xuống.

delete_branch

< >

( repo_id: strbranch: strtoken: bool | str | None = Nonerepo_type: str | None = None )

Tham số

  • repo_id (str) — Kho lưu trữ mà một nhánh sẽ bị xóa. Ví dụ: "user/my-cool-model".
  • branch (str) — Tên của nhánh cần xóa.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tạo nhánh trên một dataset hoặc space, None hoặc "model" nếu gắn thẻ cho một model. Mặc định là None.

Gây ra

RepositoryNotFoundError hoặc HfHubHTTPError

  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho riêng tư nhưng chưa xác thực hoặc kho không tồn tại.
  • HfHubHTTPError — Nếu cố gắng xóa một nhánh được bảo vệ. Ví dụ: main không thể bị xóa.
  • HfHubHTTPError — Nếu cố gắng xóa một nhánh không tồn tại.

Xóa một nhánh khỏi kho trên Hub.

delete_bucket

< >

( bucket_id: strmissing_ok: bool = Falsetoken: bool | str | None = None )

Tham số

  • bucket_id (str) — ID của bucket (ví dụ: "username/my-bucket").
  • missing_ok (bool, tùy chọn, mặc định là False) — Nếu True, sẽ không gây ra lỗi nếu bucket không tồn tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

BucketNotFoundError

  • BucketNotFoundError — Nếu không tìm thấy bucket và missing_ok được đặt thành False (mặc định).

Xóa một bucket khỏi Hub.

Ví dụ:

>>> from huggingface_hub import delete_bucket
>>> delete_bucket(bucket_id="Wauplin/first-bucket")
>>> delete_bucket(bucket_id="Wauplin/first-bucket", missing_ok=True)

delete_collection

< >

( collection_slug: strmissing_ok: bool = Falsetoken: bool | str | None = None )

Tham số

  • collection_slug (str) — Slug của bộ sưu tập cần xóa. Ví dụ: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • missing_ok (bool, tùy chọn) — Nếu True, không gây ra lỗi nếu bộ sưu tập không tồn tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Xóa một bộ sưu tập trên Hub.

Ví dụ:

>>> from huggingface_hub import delete_collection
>>> collection = delete_collection("username/useless-collection-64f9a55bb3115b4f513ec026", missing_ok=True)

Đây là một thao tác không thể hoàn tác. Một bộ sưu tập đã bị xóa không thể được khôi phục.

delete_collection_item

< >

( collection_slug: stritem_object_id: strmissing_ok: bool = Falsetoken: bool | str | None = None )

Tham số

  • collection_slug (str) — Slug của bộ sưu tập cần cập nhật. Ví dụ: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • item_object_id (str) — ID của mục trong bộ sưu tập. Đây không phải là id của mục trên Hub (repo_id hoặc paper id). Nó phải được lấy từ một đối tượng CollectionItem. Ví dụ: collection.items[0].item_object_id.
  • missing_ok (bool, tùy chọn) — Nếu True, không gây ra lỗi nếu mục không tồn tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Xóa một mục khỏi bộ sưu tập.

Ví dụ:

>>> from huggingface_hub import get_collection, delete_collection_item

# Get collection first
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")

# Delete item based on its ID
>>> delete_collection_item(
...     collection_slug="TheBloke/recent-models-64f9a55bb3115b4f513ec026",
...     item_object_id=collection.items[-1].item_object_id,
... )

delete_file

< >

( path_in_repo: strrepo_id: strtoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = None )

Tham số

  • path_in_repo (str) — Đường dẫn tệp tương đối trong kho, ví dụ: "checkpoints/1fec34a/weights.bin"
  • repo_id (str) — Kho lưu trữ mà tệp sẽ bị xóa, ví dụ: "username/custom_transformers"
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tệp nằm trong một dataset hoặc space, None hoặc "model" nếu nằm trong một model. Mặc định là None.
  • revision (str, tùy chọn) — Phiên bản git để commit từ. Mặc định là đầu của nhánh "main".
  • commit_message (str, tùy chọn) — Tóm tắt / tiêu đề / dòng đầu tiên của commit được tạo. Mặc định là f"Delete {path_in_repo} with huggingface_hub".
  • commit_description (str, tùy chọn) — Mô tả của commit được tạo
  • create_pr (boolean, tùy chọn) — Có tạo Pull Request với commit đó hay không. Mặc định là False. Nếu revision không được đặt, PR sẽ được mở đối với nhánh "main". Nếu revision được đặt và là một nhánh, PR sẽ được mở đối với nhánh này. Nếu revision được đặt và không phải là tên nhánh (ví dụ: một commit oid), RevisionNotFoundError sẽ được trả về bởi máy chủ.
  • parent_commit (str, tùy chọn) — OID / SHA của commit cha, dưới dạng chuỗi hex. Các dạng viết tắt (7 ký tự đầu tiên) cũng được hỗ trợ. Nếu được chỉ định và create_pr là False, commit sẽ thất bại nếu revision không trỏ đến parent_commit. Nếu được chỉ định và create_pr là True, pull request sẽ được tạo từ parent_commit. Việc chỉ định parent_commit đảm bảo rằng repo không bị thay đổi trước khi commit các thay đổi, và đặc biệt hữu ích nếu repo được cập nhật / commit đồng thời.

Xóa một tệp trong kho đã cho.

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.
  • RevisionNotFoundError Nếu không tìm thấy revision cần tải xuống.
  • EntryNotFoundError Nếu tệp cần tải xuống không được tìm thấy.

delete_files

< >

( repo_id: strdelete_patterns: list[str]token: bool | str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = None )

Tham số

  • repo_id (str) — Kho lưu trữ mà thư mục sẽ bị xóa, ví dụ: "username/custom_transformers"
  • delete_patterns (list[str]) — Danh sách các tệp hoặc thư mục cần xóa. Mỗi chuỗi có thể là đường dẫn tệp, đường dẫn thư mục, hoặc một mẫu wildcard. Các mẫu là Standard Wildcards (mẫu globbing) như được tài liệu hóa tại đây. Việc khớp mẫu dựa trên fnmatch. Lưu ý rằng fnmatch khớp * qua các ranh giới đường dẫn, khác với globbing shell Unix truyền thống. Ví dụ: ["file.txt", "folder/", "data/*.parquet"]
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False. vào token đã lưu.
  • repo_type (str, tùy chọn) — Loại kho cần xóa tệp. Có thể là "model", "dataset" hoặc "space". Mặc định là "model".
  • revision (str, tùy chọn) — Phiên bản git để commit từ. Mặc định là đầu của nhánh "main".
  • commit_message (str, tùy chọn) — Tóm tắt (dòng đầu tiên) của commit được tạo. Mặc định là f"Delete files using huggingface_hub".
  • commit_description (str, tùy chọn) — Mô tả của commit được tạo.
  • create_pr (boolean, tùy chọn) — Có tạo Pull Request với commit đó hay không. Mặc định là False. Nếu revision không được đặt, PR sẽ được mở đối với nhánh "main". Nếu revision được đặt và là một nhánh, PR sẽ được mở đối với nhánh này. Nếu revision được đặt và không phải là tên nhánh (ví dụ: một commit oid), RevisionNotFoundError sẽ được trả về bởi máy chủ.
  • parent_commit (str, tùy chọn) — OID / SHA của commit cha, dưới dạng chuỗi hex. Các dạng viết tắt (7 ký tự đầu tiên) cũng được hỗ trợ. Nếu được chỉ định và create_pr là False, commit sẽ thất bại nếu revision không trỏ đến parent_commit. Nếu được chỉ định và create_pr là True, pull request sẽ được tạo từ parent_commit. Việc chỉ định parent_commit đảm bảo rằng repo không bị thay đổi trước khi commit các thay đổi, và đặc biệt hữu ích nếu repo được cập nhật / commit đồng thời.

Xóa tệp khỏi một kho trên Hub.

Nếu một đường dẫn thư mục được cung cấp, toàn bộ thư mục cũng như tất cả các tệp chứa trong đó sẽ bị xóa.

delete_folder

< >

( path_in_repo: strrepo_id: strtoken: bool | str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = None )

Tham số

  • path_in_repo (str) — Đường dẫn thư mục tương đối trong repo, ví dụ: "checkpoints/1fec34a".
  • repo_id (str) — Kho lưu trữ mà thư mục sẽ bị xóa, ví dụ: "username/custom_transformers"
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False. vào token đã lưu.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu thư mục nằm trong một dataset hoặc space, None hoặc "model" nếu nằm trong một model. Mặc định là None.
  • revision (str, tùy chọn) — Phiên bản git để commit từ. Mặc định là đầu của nhánh "main".
  • commit_message (str, tùy chọn) — Tóm tắt / tiêu đề / dòng đầu tiên của commit được tạo. Mặc định là f"Delete folder {path_in_repo} with huggingface_hub".
  • commit_description (str, tùy chọn) — Mô tả của commit được tạo.
  • create_pr (boolean, tùy chọn) — Có tạo Pull Request với commit đó hay không. Mặc định là False. Nếu revision không được đặt, PR sẽ được mở đối với nhánh "main". Nếu revision được đặt và là một nhánh, PR sẽ được mở đối với nhánh này. Nếu revision được đặt và không phải là tên nhánh (ví dụ: một commit oid), RevisionNotFoundError sẽ được trả về bởi máy chủ.
  • parent_commit (str, tùy chọn) — OID / SHA của commit cha, dưới dạng chuỗi hex. Các dạng viết tắt (7 ký tự đầu tiên) cũng được hỗ trợ. Nếu được chỉ định và create_pr là False, commit sẽ thất bại nếu revision không trỏ đến parent_commit. Nếu được chỉ định và create_pr là True, pull request sẽ được tạo từ parent_commit. Việc chỉ định parent_commit đảm bảo rằng repo không bị thay đổi trước khi commit các thay đổi, và đặc biệt hữu ích nếu repo được cập nhật / commit đồng thời.

Xóa một thư mục trong kho đã cho.

Bọc đơn giản quanh phương thức create_commit().

delete_inference_endpoint

< >

( name: strnamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • name (str) — Tên của Inference Endpoint cần xóa.
  • namespace (str, optional) — Namespace chứa Inference Endpoint. Mặc định là người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Xóa một Inference Endpoint.

Thao tác này không thể đảo ngược. Nếu bạn không muốn bị tính phí cho một Inference Endpoint, cách tốt hơn là tạm dừng nó bằng pause_inference_endpoint() hoặc thu nhỏ nó về không bằng scale_to_zero_inference_endpoint().

Để tiện lợi, bạn cũng có thể xóa một Inference Endpoint bằng cách sử dụng InferenceEndpoint.delete().

delete_repo

< >

( repo_id: strtoken: str | bool | None = Nonerepo_type: str | None = Nonemissing_ok: bool = False )

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model.
  • missing_ok (bool, tùy chọn, mặc định là False) — Nếu True, không gây ra lỗi nếu kho không tồn tại.

Gây ra

RepositoryNotFoundError

  • RepositoryNotFoundError — Nếu không tìm thấy kho cần xóa và missing_ok được đặt thành False (mặc định).

Xóa một kho (repo) khỏi HuggingFace Hub. LƯU Ý: thao tác này không thể hoàn tác.

delete_scheduled_job

< >

( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • scheduled_job_id (str) — ID của Job được lên lịch.
  • namespace (str, optional) — Namespace chứa Job được lên lịch. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Xóa một Job tính toán đã lên lịch trên hạ tầng Hugging Face.

delete_space_secret

< >

( repo_id: strkey: strtoken: bool | str | None = None )

Tham số

  • repo_id (str) — ID của kho cần cập nhật. Ví dụ: "bigcode/in-the-stack".
  • key (str) — Khóa bí mật. Ví dụ: "GITHUB_API_KEY".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Xóa một bí mật khỏi một Space.

Secrets cho phép thiết lập các khóa hoặc token bí mật cho một Space mà không cần hardcode chúng. Để biết thêm chi tiết, xem https://huggingface.co/docs/hub/spaces-overview#managing-secrets.

delete_space_variable

< >

( repo_id: strkey: strtoken: bool | str | None = None )

Tham số

  • repo_id (str) — ID của kho cần cập nhật. Ví dụ: "bigcode/in-the-stack".
  • key (str) — Khóa biến. Ví dụ: "MODEL_REPO_ID"
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Xóa một biến khỏi một Space.

Biến cho phép thiết lập các biến môi trường cho một Space mà không cần hardcode chúng. Để biết thêm chi tiết, xem https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

delete_space_volumes

< >

( repo_id: strtoken: bool | str | None = None )

Tham số

  • repo_id (str) — ID của Space cần cập nhật. Ví dụ: "username/my-space".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

BadRequestError

  • BadRequestError — Nếu Space không có volume nào được gắn.

Xóa tất cả các volume khỏi một Space.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.delete_space_volumes("username/my-space")

delete_tag

< >

( repo_id: strtag: strtoken: bool | str | None = Nonerepo_type: str | None = None )

Tham số

  • repo_id (str) — Kho lưu trữ mà một thẻ sẽ bị xóa. Ví dụ: "user/my-cool-model".
  • tag (str) — Tên của tag cần xóa.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu gắn thẻ cho dataset hoặc space, None hoặc "model" nếu gắn thẻ cho model. Mặc định là None.

Gây ra

RepositoryNotFoundError hoặc RevisionNotFoundError

  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho riêng tư nhưng chưa xác thực hoặc kho không tồn tại.
  • RevisionNotFoundError — Nếu không tìm thấy tag.

Xóa một thẻ khỏi kho trên Hub.

delete_webhook

< >

( webhook_id: strtoken: bool | str | None = None ) → None

Tham số

  • webhook_id (str) — Định danh duy nhất của webhook cần xóa.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

None

Xóa một webhook.

Ví dụ:

>>> from huggingface_hub import delete_webhook
>>> delete_webhook("654bbbc16f2ec14d77f109cc")

disable_space_dev_mode

< >

( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime

Tham số

  • repo_id (str) — ID của Space cần tắt chế độ dev. Ví dụ: "Salesforce/BLIP2".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

SpaceRuntime

Thông tin thời gian chạy về Space của bạn.

Gây ra

RepositoryNotFoundError hoặc HfHubHTTPError hoặc BadRequestError

  • RepositoryNotFoundError — Nếu Space của bạn không được tìm thấy (lỗi 404). Khả năng cao là repo_id sai hoặc Space của bạn là riêng tư nhưng bạn chưa xác thực.
  • HfHubHTTPError — 403 Forbidden: chỉ chủ sở hữu của một Space mới có thể đặt chế độ dev. Nếu bạn muốn xử lý một Space mà bạn không sở hữu, hãy yêu cầu chủ sở hữu bằng cách mở một Discussion hoặc nhân bản Space đó.
  • BadRequestError — Nếu Space của bạn là một Space tĩnh. Các Space tĩnh luôn chạy và không bao giờ bị tính phí. Nếu bạn muốn ẩn một Space tĩnh, bạn có thể đặt nó ở chế độ riêng tư.

Tắt chế độ dev trên một Space.

Spaces Dev Mode giúp việc gỡ lỗi ứng dụng của bạn trở nên dễ dàng hơn và rút ngắn thời gian lặp lại trên Spaces bằng cách cho phép bạn khởi động lại ứng dụng mà không cần dừng container của Space. Việc bật dev mode yêu cầu gói PRO hoặc Team & Enterprise, nhưng việc tắt nó luôn được cho phép (ví dụ: sau khi đăng ký hết hạn). Xem https://huggingface.co/docs/hub/spaces-dev-mode để biết thêm chi tiết.

disable_webhook

< >

( webhook_id: strtoken: bool | str | None = None ) → WebhookInfo

Tham số

  • webhook_id (str) — Định danh duy nhất của webhook cần vô hiệu hóa.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

WebhookInfo

Thông tin về webhook đã bị vô hiệu hóa.

Tắt một webhook (đặt nó ở trạng thái “tắt”).

Ví dụ:

>>> from huggingface_hub import disable_webhook
>>> disabled_webhook = disable_webhook("654bbbc16f2ec14d77f109cc")
>>> disabled_webhook
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    jon=None,
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=True,
)

download_bucket_files

< >

( bucket_id: strfiles: list[tuple[str | BucketFile, str | Path]]raise_on_missing_files: bool = Falsetoken: str | bool | None = None )

Tham số

  • bucket_id (str) — ID của bucket (ví dụ: "username/my-bucket").
  • files (list[tuple[Union[str, BucketFile], Union[str, Path]]]) — Các tệp cần tải xuống dưới dạng danh sách các bộ (source, destination). Xem mô tả ở trên để biết chi tiết về định dạng.
  • raise_on_missing_files (bool, tùy chọn) — Nếu True, sẽ gây ra EntryNotFoundError khi tệp được yêu cầu không tồn tại trong bucket. Nếu False (mặc định), các tệp thiếu sẽ bị bỏ qua kèm theo cảnh báo.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Tải tệp từ một bucket.

Files input là một danh sách các tuple (remote file, local file) trong đó remote file là đường dẫn của tệp trong bucket hoặc một đối tượng BucketFile, và local file là đường dẫn đích trên hệ thống tệp cục bộ. Khi truyền một đối tượng BucketFile (lấy từ list_bucket_tree()), phương thức sẽ bỏ qua bước lấy metadata và tải trực tiếp các tệp xuống.

Ví dụ:

>>> from huggingface_hub import download_bucket_files

>>> download_bucket_files(
...     bucket_id="username/my-bucket",
...     files=[
...         ("models/model.safetensors", "./local/model.safetensors"),
...         ("config.json", "./local/config.json"),
...     ],
... )
>>> from huggingface_hub import download_bucket_files

>>> parquet_files = [file for file in list_bucket_tree(bucket_id="username/my-bucket") if file.path.endswith(".parquet")]
>>> download_bucket_files(
...     bucket_id="username/my-bucket",
...     files=[(file, f"./local/{file.path}") for file in parquet_files],
... )

duplicate_repo

< >

( from_id: strto_id: str | None = Nonerepo_type: str | None = Noneprivate: bool | None = Nonevisibility: RepoVisibility_T | None = Nonetoken: bool | str | None = Noneexist_ok: bool = Falseresource_group_id: str | None = Nonespace_hardware: SpaceHardware | None = Nonespace_sleep_time: int | None = Nonespace_secrets: list[dict[str, str]] | None = Nonespace_variables: list[dict[str, str]] | None = Nonespace_volumes: list[Volume] | None = None ) → DuplicatedRepoUrl

Tham số

  • from_id (str) — ID của repo cần nhân bản. Ví dụ: "openai/gdpval".
  • to_id (str, tùy chọn) — ID của repo mới. Ví dụ: "myorg/my-gdpval". Nếu không được cung cấp, repo mới sẽ có cùng tên với repo gốc, nhưng trong tài khoản của bạn.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu nhân bản một dataset hoặc Space, None hoặc "model" nếu nhân bản một model. Mặc định là None.
  • private (bool, optional) — Xác định xem repo mới có nên là private hay không. Mặc định là cùng mức độ riêng tư với repo gốc. Không thể truyền cùng với visibility.
  • visibility (Literal["public", "private", "protected"], optional) — Độ hiển thị của kho mới. Có thể là "public" hoặc "private", hoặc "protected" đối với Spaces. Mặc định là cùng độ hiển thị với kho gốc.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • exist_ok (bool, tùy chọn, mặc định là False) — Nếu True, không gây ra lỗi nếu kho đã tồn tại.
  • resource_group_id (str, tùy chọn) — Nhóm tài nguyên để tạo kho mới. Nhóm tài nguyên chỉ khả dụng cho các tổ chức Enterprise Hub và cho phép xác định thành viên nào trong tổ chức có thể truy cập tài nguyên. ID của một nhóm tài nguyên có thể tìm thấy trong URL của trang tài nguyên trên Hub (ví dụ: "66670e5163145ca562cb1988"). Để tìm hiểu thêm về nhóm tài nguyên, xem https://huggingface.co/docs/hub/en/security-resource-groups.
  • space_hardware (SpaceHardware hoặc str, tùy chọn) — Lựa chọn phần cứng nếu repo_type là “space”. Ví dụ: "t4-medium". Xem SpaceHardware để biết danh sách đầy đủ.
  • space_sleep_time (int, tùy chọn) — Số giây không hoạt động cần chờ trước khi một Space được đưa vào trạng thái ngủ. Đặt thành -1 nếu bạn không muốn Space của mình ngủ (hành vi mặc định cho phần cứng đã nâng cấp). Đối với phần cứng miễn phí, bạn không thể cấu hình thời gian ngủ (giá trị được cố định ở mức 48 giờ không hoạt động). Chỉ áp dụng nếu repo_type là “space”. Xem https://huggingface.co/docs/hub/spaces-gpus#sleep-time để biết thêm chi tiết.
  • space_secrets (list[dict[str, str]], tùy chọn) — Một danh sách các khóa bí mật cần thiết lập trong Space của bạn. Mỗi mục có dạng {"key": ..., "value": ..., "description": ...} trong đó description là tùy chọn. Chỉ áp dụng nếu repo_type là “space”. Để biết thêm chi tiết, xem https://huggingface.co/docs/hub/spaces-overview#managing-secrets.
  • space_variables (list[dict[str, str]], tùy chọn) — Một danh sách các biến môi trường công khai để thiết lập trong Space của bạn. Mỗi mục có dạng {"key": ..., "value": ..., "description": ...} trong đó description là tùy chọn. Chỉ áp dụng nếu repo_type là “space”. Để biết thêm chi tiết, xem https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables.
  • space_volumes (list[Volume], tùy chọn) — Một danh sách các đối tượng Volume để gắn (mount) vào Space tại thời điểm nhân bản. Mỗi volume có một type ("bucket", "model", "dataset", hoặc "space"), một source (ID của repo hoặc bucket), một mount_path (đường dẫn bên trong container), và các trường tùy chọn revision, read_only, và path. Chỉ áp dụng nếu repo_type là “space”.

Trả về

DuplicatedRepoUrl

URL của kho vừa được tạo. Giá trị là một lớp con của RepoUrl (và của str) chứa các thuộc tính như endpoint, repo_type, repo_id và files_copy_pending.

Gây ra

RepositoryNotFoundError hoặc HfHubHTTPError

  • RepositoryNotFoundError — Nếu from_id hoặc to_id không được tìm thấy. Điều này có thể do kho không tồn tại, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.
  • HfHubHTTPError — Nếu API HuggingFace trả về một lỗi

Nhân bản một kho trên Hub (mô hình, bộ dữ liệu hoặc Space).

Thao tác này thực hiện sao chép phía máy chủ, giữ nguyên toàn bộ lịch sử git và các đối tượng LFS mà không cần tải xuống/tải lên cục bộ.

Lịch sử git được sao chép ngay lập tức, nhưng các tệp LFS/Xet có thể vẫn đang được sao chép ở chế độ nền sau khi phương thức này trả về. Trong trường hợp đó, files_copy_pending có giá trị True trong giá trị trả về và việc tải các tệp này từ kho mới có thể thất bại cho đến khi quá trình sao chép hoàn tất.

Ví dụ:

>>> from huggingface_hub import duplicate_repo

# Duplicate a model to your account
>>> repo_url = duplicate_repo("google/gemma-7b")
>>> repo_url
RepoUrl('https://huggingface.co/nateraw/gemma-7b',...)
>>> repo_url.files_copy_pending
True

# Duplicate a dataset with a custom name
>>> duplicate_repo("openai/gdpval", to_id="myorg/my-gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/myorg/my-gdpval',...)

# Duplicate a Space with custom hardware
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", space_hardware="t4-medium")
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

edit_discussion_comment

< >

( repo_id: strdiscussion_num: intcomment_id: strnew_content: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionComment

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • discussion_num (int) — Số thứ tự của Discussion hoặc Pull Request. Phải là một số nguyên dương.
  • comment_id (str) — ID của bình luận cần chỉnh sửa.
  • new_content (str) — Nội dung mới của bình luận. Bình luận hỗ trợ định dạng markdown.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

DiscussionComment

bình luận đã chỉnh sửa

Chỉnh sửa một bình luận trên Discussion / Pull Request.

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

enable_space_dev_mode

< >

( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime

Tham số

  • repo_id (str) — ID của Space cần bật chế độ dev. Ví dụ: "Salesforce/BLIP2".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

SpaceRuntime

Thông tin thời gian chạy về Space của bạn.

Gây ra

RepositoryNotFoundError hoặc HfHubHTTPError hoặc BadRequestError

  • RepositoryNotFoundError — Nếu Space của bạn không được tìm thấy (lỗi 404). Khả năng cao là repo_id sai hoặc Space của bạn là riêng tư nhưng bạn chưa xác thực.
  • HfHubHTTPError — 403 Forbidden: chỉ chủ sở hữu của một Space mới có thể đặt chế độ dev. Nếu bạn muốn xử lý một Space mà bạn không sở hữu, hãy yêu cầu chủ sở hữu bằng cách mở một Discussion hoặc nhân bản Space đó.
  • BadRequestError — Nếu Space của bạn là một Space tĩnh. Các Space tĩnh luôn chạy và không bao giờ bị tính phí. Nếu bạn muốn ẩn một Space tĩnh, bạn có thể đặt nó ở chế độ riêng tư.

Bật chế độ dev trên một Space.

Spaces Dev Mode giúp việc gỡ lỗi ứng dụng của bạn trở nên dễ dàng hơn và rút ngắn thời gian lặp lại trên Spaces bằng cách cho phép bạn khởi động lại ứng dụng mà không cần dừng container của Space. Tính năng này có sẵn như một phần của gói PRO hoặc Team & Enterprise. Xem https://huggingface.co/docs/hub/spaces-dev-mode để biết thêm chi tiết.

enable_webhook

< >

( webhook_id: strtoken: bool | str | None = None ) → WebhookInfo

Tham số

  • webhook_id (str) — Định danh duy nhất của webhook cần bật.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

WebhookInfo

Thông tin về webhook được bật.

Bật webhook (khiến nó “hoạt động”).

Ví dụ:

>>> from huggingface_hub import enable_webhook
>>> enabled_webhook = enable_webhook("654bbbc16f2ec14d77f109cc")
>>> enabled_webhook
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    job=None,
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=False,
)

fetch_job_logs

< >

( job_id: strnamespace: str | None = Nonefollow: bool = Falsetail: int | None = Nonetoken: bool | str | None = None )

Tham số

  • job_id (str) — ID của Job.
  • namespace (str, optional) — Namespace nơi Job đang chạy. Mặc định là namespace của người dùng hiện tại.
  • follow (bool, tùy chọn) — Nếu True, phát trực tiếp nhật ký theo thời gian thực cho đến khi việc hoàn thành (chặn). Nếu False (mặc định), chỉ lấy các nhật ký hiện có và trả về ngay lập tức (không chặn).
  • tail (int, tùy chọn) — Số dòng tối đa cần trả về từ nhật ký. Khi kết hợp với follow=True, bắt đầu từ N dòng cuối và tiếp tục phát trực tiếp các nhật ký mới. Khi follow=False, chỉ trả về N dòng cuối từ các nhật ký hiện có.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Lấy tất cả các nhật ký từ một Job tính toán trên hạ tầng của Hugging Face.

Ví dụ:

>>> from huggingface_hub import fetch_job_logs, run_job
>>> job = run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"])
>>> for log in fetch_job_logs(job_id=job.id):
...     print(log)
Hello from HF compute!

>>> # Non-blocking: fetch only currently available logs
>>> for log in fetch_job_logs(job_id=job.id, follow=False):
...     print(log)

>>> # Stream logs starting from the last 100 lines
>>> for log in fetch_job_logs(job_id=job.id, follow=True, tail=100):
...     print(log)

fetch_job_metrics

< >

( job_id: strnamespace: str | None = Nonefollow: bool = Falsetoken: bool | str | None = None )

Tham số

  • job_id (str) — ID của Job.
  • namespace (str, optional) — Namespace nơi Job đang chạy. Mặc định là namespace của người dùng hiện tại.
  • follow (bool, tùy chọn) — Nếu True, phát trực tiếp các chỉ số theo thời gian thực cho đến khi công việc hoàn tất (chặn). Nếu False (mặc định), chỉ lấy các chỉ số hiện tại và trả về (không chặn).
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Lấy các chỉ số trực tiếp từ một Job tính toán trên hạ tầng của Hugging Face.

Ví dụ:

>>> from huggingface_hub import fetch_job_metrics, run_job
>>> job = run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"], flavor="a10g-small")
>>> for metrics in fetch_job_metrics(job_id=job.id):
...     print(metrics)
{
    "cpu_usage_pct": 0,
    "cpu_millicores": 3500,
    "memory_used_bytes": 1306624,
    "memory_total_bytes": 15032385536,
    "rx_bps": 0,
    "tx_bps": 0,
    "gpus": {
        "882fa930": {
            "utilization": 0,
            "memory_used_bytes": 0,
            "memory_total_bytes": 22836000000
        }
    },
    "replica": "57vr7"
}

>>> # Stream metrics until the job completes
>>> for metrics in fetch_job_metrics(job_id=job.id, follow=True):
...     print(metrics)

fetch_space_logs

< >

( repo_id: strbuild: bool = Falsefollow: bool = Falsetoken: bool | str | None = None ) → Iterable[str]

Tham số

  • repo_id (str) — ID của Space. Ví dụ: "bigcode/in-the-stack".
  • build (bool, tùy chọn, mặc định là False) — Nếu True, lấy nhật ký build của container (hữu ích khi một Space bị kẹt ở trạng thái BUILD_ERROR). Nếu False (mặc định), lấy nhật ký chạy, tức là stdout/stderr của ứng dụng đang chạy.
  • follow (bool, tùy chọn, mặc định là False) — Nếu True, luồng nhật ký theo thời gian thực (khóa) cho đến khi máy chủ đóng luồng hoặc KeyboardInterrupt được ném ra. Nếu False (mặc định), chỉ lấy nhật ký đang được đệm hiện tại và trả về ngay lập tức (không khóa, giống như docker logs).
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Mặc định là token được lưu cục bộ, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Trả về

Iterable[str]

Một trình tạo (generator) trả về các dòng nhật ký khi chúng có sẵn.

Lấy nhật ký chạy hoặc nhật ký build của một Space trên Hub.

Hữu ích để gỡ lỗi một Space đang gặp lỗi khi build hoặc bị crash khi chạy, đặc biệt là từ một script hoặc quy trình làm việc dạng agentic, nơi việc đọc log trong trình duyệt không khả thi.

Ví dụ:

>>> from huggingface_hub import fetch_space_logs
>>> # Non-blocking: print currently available run logs and exit.
>>> for line in fetch_space_logs("username/my-space"):
...     print(line, end="")

>>> # Debug a build failure:
>>> for line in fetch_space_logs("username/my-space", build=True):
...     print(line, end="")

>>> # Stream run logs until the server closes the stream.
>>> for line in fetch_space_logs("username/my-space", follow=True):
...     print(line, end="")

file_exists

< >

( repo_id: strfilename: strrepo_type: str | None = Nonerevision: str | None = Nonetoken: str | bool | None = None )

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • filename (str) — Tên của tệp cần kiểm tra, ví dụ: "config.json"
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu lấy thông tin kho từ một dataset hoặc một space, None hoặc "model" nếu lấy thông tin kho từ một model. Mặc định là None.
  • revision (str, tùy chọn) — Phiên bản của kho chứa mà bạn muốn lấy thông tin. Mặc định là nhánh "main".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Kiểm tra xem một tệp có tồn tại trong một kho trên Hugging Face Hub hay không.

Ví dụ:

>>> from huggingface_hub import file_exists
>>> file_exists("bigcode/starcoder", "config.json")
True
>>> file_exists("bigcode/starcoder", "not-a-file")
False
>>> file_exists("bigcode/not-a-repo", "config.json")
False

get_bucket_file_metadata

< >

( bucket_id: strremote_path: strtoken: str | bool | None = None ) → BucketFileMetadata

Tham số

  • bucket_id (str) — ID của bucket (ví dụ: "username/my-bucket").
  • remote_path (str) — Đường dẫn của tệp trong bucket.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

BucketFileMetadata

Tệp metadata chứa thông tin về kích thước và xet.

Lấy metadata của một tệp trong bucket.

Ví dụ:

>>> from huggingface_hub import get_bucket_file_metadata
>>> metadata = get_bucket_file_metadata(
...     bucket_id="username/my-bucket",
...     remote_path="models/model.safetensors",
... )
>>> metadata.size
42000

get_bucket_paths_info

< >

( bucket_id: strpaths: Iterable[str]token: str | bool | None = None ) → Iterable[BucketFile]

Tham số

  • bucket_id (str) — ID của bucket (ví dụ: "username/my-bucket").
  • paths (Iterable[str]) — Các đường dẫn để lấy thông tin. Nếu một đường dẫn không tồn tại, nó sẽ bị bỏ qua mà không gây ra ngoại lệ. Chỉ hỗ trợ đường dẫn tệp.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[BucketFile]

Thông tin về các đường dẫn, dưới dạng một đối tượng lặp được của các đối tượng BucketFile.

Lấy thông tin về các đường dẫn của một bucket.

Các cuộc gọi được thực hiện theo các lô gồm 1000 đường dẫn. Kết quả được trả về ngay khi nhận được.

Ví dụ:

>>> from huggingface_hub import get_bucket_paths_info
>>> paths_info = get_bucket_paths_info("username/my-bucket", ["file.txt", "checkpoints/model.safetensors"])
>>> for info in paths_info:
...     print(info)
BucketFile(type='file', path='file.txt', size=2379, xet_hash='96e637d9665bd35477b1908a23f2e254edfba0618dbd2d62f90a6baee7d139cf', mtime=datetime.datetime(2024, 9, 25, 15, 31, 2, 346000, tzinfo=datetime.timezone.utc))
BucketFile(type='file', path='checkpoints/model.safetensors', size=2408828, xet_hash='3ed0e9fefe788ddd61d1e26eba67057e9740a064b009256fbafadf6bb95785ca', mtime=datetime.datetime(2024, 9, 25, 15, 31, 2, 346000, tzinfo=datetime.timezone.utc))

get_collection

< >

( collection_slug: strtoken: bool | str | None = None )

Tham số

  • collection_slug (str) — Slug của bộ sưu tập trên Hub. Ví dụ: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Lấy thông tin về một Collection trên Hub.

Trả về: Collection

Ví dụ:

>>> from huggingface_hub import get_collection
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")
>>> collection.title
'Recent models'
>>> len(collection.items)
37
>>> collection.items[0]
CollectionItem(
    item_object_id='651446103cd773a050bf64c2',
    item_id='TheBloke/U-Amethyst-20B-AWQ',
    item_type='model',
    position=88,
    note=None
)

get_dataset_leaderboard

< >

( repo_id: strbase_model_only: bool | None = Nonetoken: bool | str | None = Nonetimeout: float | None = None ) → list[DatasetLeaderboardEntry]

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /. Ví dụ: "allenai/olmOCR-bench".
  • base_model_only (bool hoặc None, tùy chọn) — Mặc định, bảng xếp hạng chỉ bao gồm các model không có quan hệ base_model được khai báo (tức là các repo gốc/canonical), khớp với chế độ xem bảng xếp hạng mặc định của Hub. Các repo fine-tuned hoặc dẫn xuất khai báo model cha sẽ bị loại. Truyền base_model_only=False để tắt bộ lọc này và bao gồm mọi kết quả đã gửi, bất kể model có khai báo quan hệ base model hay không.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • timeout (float, tùy chọn) — Có nên đặt thời gian chờ cho yêu cầu đến Hub hay không.

Trả về

list[DatasetLeaderboardEntry]

Danh sách các đối tượng DatasetLeaderboardEntry đại diện cho các mục trên bảng xếp hạng, được sắp xếp theo thứ hạng.

Lấy bảng xếp hạng cho một bộ dữ liệu trên Hub.

Bảng xếp hạng sắp xếp các mô hình dựa trên điểm đánh giá của chúng trên bộ dữ liệu chuẩn được cung cấp. Không phải bộ dữ liệu nào cũng có bảng xếp hạng — chỉ những bộ dữ liệu chuẩn có kết quả đánh giá được gửi đến mới có. Điều này mang lại góc nhìn tập trung vào bộ dữ liệu về các điểm số; để có góc nhìn tập trung vào mô hình, hãy sử dụng model_info() với expand=["evalResults"].

Gây ra các lỗi sau:

  • RepositoryNotFoundError Nếu không tìm thấy kho lưu trữ. Điều này có thể do kho không tồn tại, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.
  • HfHubHTTPError Nếu bộ dữ liệu không có bảng xếp hạng.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> leaderboard = api.get_dataset_leaderboard("allenai/olmOCR-bench")
>>> leaderboard[0].model_id
'datalab-to/chandra-ocr-2'
>>> leaderboard[0].rank
1

# Include fine-tuned / derivative models too
>>> full_leaderboard = api.get_dataset_leaderboard("allenai/olmOCR-bench", base_model_only=False)

get_dataset_tags

< >

( )

Liệt kê tất cả các thẻ (tags) hợp lệ của bộ dữ liệu dưới dạng một đối tượng namespace lồng nhau.

get_discussion_details

< >

( repo_id: strdiscussion_num: intrepo_type: str | None = Nonetoken: bool | str | None = None )

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • discussion_num (int) — Số thứ tự của Discussion hoặc Pull Request. Phải là một số nguyên dương.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Lấy chi tiết của một Discussion / Pull Request từ Hub.

Trả về: DiscussionWithDetails

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

get_full_repo_name

< >

( model_id: strorganization: str | None = Nonetoken: bool | str | None = None ) → str

Tham số

  • model_id (str) — Tên của mô hình.
  • organization (str, tùy chọn) — Nếu được truyền vào, tên kho sẽ nằm trong không gian tên của tổ chức thay vì không gian tên của người dùng.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

str

Tên kho trong không gian tên của người dùng ({username}/{model_id}) nếu không truyền tổ chức, và trong không gian tên của tổ chức ({organization}/{model_id}) nếu không.

Trả về tên kho cho một ID model và tổ chức tùy chọn.

get_hf_file_metadata

< >

( url: strtoken: bool | str | None = Nonetimeout: float | None = 10 )

Tham số

  • url (str) — URL của tệp, ví dụ được trả về bởi hf_hub_url().
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • timeout (float, tùy chọn, mặc định là 10) — Số giây chờ máy chủ gửi metadata trước khi từ bỏ.

Lấy metadata của một tệp được phiên bản hóa trên Hub cho một url nhất định.

get_inference_endpoint

< >

( name: strnamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint

Tham số

  • name (str) — Tên của Inference Endpoint cần lấy thông tin.
  • namespace (str, optional) — Namespace chứa Inference Endpoint. Mặc định là người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

InferenceEndpoint

thông tin về Inference Endpoint được yêu cầu.

Lấy thông tin về một Inference Endpoint.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.get_inference_endpoint("my-text-to-image")
>>> endpoint
InferenceEndpoint(name='my-text-to-image', ...)

# Get status
>>> endpoint.status
'running'
>>> endpoint.url
'https://my-text-to-image.region.vendor.endpoints.huggingface.cloud'

# Run inference
>>> endpoint.client.text_to_image(...)

get_model_tags

< >

( )

Liệt kê tất cả các thẻ mô hình hợp lệ dưới dạng một đối tượng namespace lồng nhau

get_organization_overview

< >

( organization: strtoken: bool | str | None = None ) → Organization

Tham số

  • organization (str) — Tên của tổ chức cần xem tổng quan.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Organization

Một đối tượng Organization chứa phần giới thiệu về tổ chức.

Gây ra

HTTPError

  • HTTPError — HTTP 404 Nếu tổ chức không tồn tại trên Hub.

Xem tổng quan về một tổ chức trên Hub.

get_paths_info

< >

( repo_id: strpaths: list[str] | strexpand: bool = Falserevision: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None ) → list[Union[RepoFile, RepoFolder]]

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • paths (Union[list[str], str], tùy chọn) — Các đường dẫn để lấy thông tin. Nếu một đường dẫn không tồn tại, nó sẽ bị bỏ qua mà không gây ra ngoại lệ.
  • expand (bool, tùy chọn, mặc định là False) — Có nên lấy thêm thông tin về các đường dẫn (ví dụ: commit gần nhất và kết quả quét bảo mật của các tệp) hay không. Thao tác này tốn kém hơn cho máy chủ nên chỉ trả về 50 kết quả mỗi trang (thay vì 1000). Vì phân trang được triển khai trong huggingface_hub, điều này là minh bạch với bạn ngoại trừ thời gian cần thiết để nhận được kết quả.
  • revision (str, tùy chọn) — Phiên bản của kho chứa mà bạn muốn lấy thông tin. Mặc định là nhánh "main".
  • repo_type (str, tùy chọn) — Loại kho chứa mà bạn muốn lấy thông tin từ đó ("model", "dataset" hoặc "space". Mặc định là "model".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

list[Union[RepoFile, RepoFolder]]

Thông tin về các đường dẫn, dưới dạng danh sách các đối tượng RepoFile và RepoFolder.

Gây ra

RepositoryNotFoundError hoặc RevisionNotFoundError

  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho là riêng tư nhưng chưa xác thực hoặc kho không tồn tại.
  • RevisionNotFoundError — Nếu không tìm thấy revision (lỗi 404) trên repo.

Lấy thông tin về các đường dẫn của một kho.

Ví dụ:

>>> from huggingface_hub import get_paths_info
>>> paths_info = get_paths_info("allenai/c4", ["README.md", "en"], repo_type="dataset")
>>> paths_info
[
    RepoFile(path='README.md', size=2379, blob_id='f84cb4c97182890fc1dbdeaf1a6a468fd27b4fff', lfs=None, last_commit=None, security=None),
    RepoFolder(path='en', tree_id='dc943c4c40f53d02b31ced1defa7e5f438d5862e', last_commit=None)
]

get_repo_discussions

< >

( repo_id: strauthor: str | None = Nonediscussion_type: constants.DiscussionTypeFilter | None = Nonediscussion_status: constants.DiscussionStatusFilter | None = Nonerepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterator[Discussion]

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • author (str, tùy chọn) — Truyền một giá trị để lọc theo tác giả của cuộc thảo luận. None có nghĩa là không lọc. Mặc định là None.
  • discussion_type (str, tùy chọn) — Đặt thành "pull_request" để chỉ lấy các pull request, "discussion" để chỉ lấy các thảo luận. Đặt thành "all" hoặc None để lấy cả hai. Mặc định là None.
  • discussion_status (str, tùy chọn) — Đặt thành "open" (tương ứng "closed") để chỉ lấy các thảo luận đang mở (tương ứng đã đóng). Đặt thành "all" hoặc None để lấy cả hai. Mặc định là None.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu lấy từ một dataset hoặc space, None hoặc "model" nếu lấy từ một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterator[Discussion]

Một trình lặp các đối tượng Discussion.

Lấy các Thảo luận và Yêu cầu Gộp (Pull Requests) cho kho (repo) được chỉ định.

Ví dụ:

Thu thập tất cả các cuộc thảo luận của một kho lưu trữ trong một danh sách:

>>> from huggingface_hub import get_repo_discussions
>>> discussions_list = list(get_repo_discussions(repo_id="bert-base-uncased"))

Lặp qua các cuộc thảo luận của một kho:

>>> from huggingface_hub import get_repo_discussions
>>> for discussion in get_repo_discussions(repo_id="bert-base-uncased"):
...     print(discussion.num, discussion.title)

get_safetensors_metadata

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonetoken: bool | str | None = Nonetimeout: float | None = 10 ) → SafetensorsRepoMetadata

Tham số

  • repo_id (str) — Tên người dùng hoặc tên tổ chức và tên kho, phân tách bằng /.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tệp nằm trong một dataset hoặc space, None hoặc "model" nếu nằm trong một model. Mặc định là None.
  • revision (str, tùy chọn) — Phiên bản git để lấy tệp. Có thể là tên nhánh, thẻ hoặc mã băm commit. Mặc định là đầu của nhánh "main".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • timeout (float, tùy chọn, mặc định là 10) — Số giây chờ máy chủ gửi dữ liệu trước khi từ bỏ, được truyền cho mỗi yêu cầu lấy tiêu đề tệp safetensors. Đặt thành None để tắt thời gian chờ (không khuyến nghị, vì kết nối bị treo có thể khiến cuộc gọi treo vĩnh viễn).

Trả về

SafetensorsRepoMetadata

thông tin liên quan đến kho safetensors.

Gây ra

NotASafetensorsRepoError hoặc SafetensorsParsingError

  • NotASafetensorsRepoError — Nếu repo không phải là repo safetensors, tức là không có file model.safetensors hoặc model.safetensors.index.json.
  • SafetensorsParsingError — Nếu không thể phân tích đúng phần đầu (header) của tệp safetensors.

Phân tích metadata cho một kho safetensors trên Hub.

Đầu tiên, chúng ta kiểm tra xem repo có một tệp safetensors đơn lẻ hay là một repo safetensors dạng phân mảnh (sharded). Nếu là một tệp safetensors đơn lẻ, chúng ta sẽ phân tích metadata từ tệp này. Nếu là một repo safetensors dạng phân mảnh, chúng ta sẽ phân tích metadata từ tệp index và sau đó phân tích metadata từ từng shard.

Để phân tích metadata từ một tệp safetensors đơn lẻ, hãy sử dụng parse_safetensors_file_metadata(). Để lấy mọi header shard của một model dạng shard trên main trong một yêu cầu duy nhất, hãy sử dụng get_sharded_safetensors_metadata().

Để biết thêm chi tiết về định dạng safetensors, hãy xem https://huggingface.co/docs/safetensors/index#format.

Ví dụ:

# Parse repo with single weights file
>>> metadata = get_safetensors_metadata("bigscience/bloomz-560m")
>>> metadata
SafetensorsRepoMetadata(
    metadata=None,
    sharded=False,
    weight_map={'h.0.input_layernorm.bias': 'model.safetensors', ...},
    files_metadata={'model.safetensors': SafetensorsFileMetadata(...)}
)
>>> metadata.files_metadata["model.safetensors"].metadata
{'format': 'pt'}

# Parse repo with sharded model
>>> metadata = get_safetensors_metadata("bigscience/bloom")
Parse safetensors files: 100%|██████████████████████████████████████████| 72/72 [00:12<00:00,  5.78it/s]
>>> metadata
SafetensorsRepoMetadata(metadata={'total_size': 352494542848}, sharded=True, weight_map={...}, files_metadata={...})
>>> len(metadata.files_metadata)
72  # All safetensors files have been fetched

# Parse repo with sharded model
>>> get_safetensors_metadata("runwayml/stable-diffusion-v1-5")
NotASafetensorsRepoError: 'runwayml/stable-diffusion-v1-5' is not a safetensors repo. Couldn't find 'model.safetensors.index.json' or 'model.safetensors' files.

get_sharded_safetensors_metadata

< >

( repo_id: strfilename: str = 'model.safetensors.index.json'token: bool | str | None = Nonetimeout: float | None = 10 ) → SafetensorsRepoMetadata

Tham số

  • repo_id (str) — Tên người dùng hoặc tên tổ chức và tên kho, phân tách bằng /.
  • filename (str, tùy chọn) — Đường dẫn của tệp chỉ mục safetensors trong kho. Mặc định là "model.safetensors.index.json".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • timeout (float, tùy chọn, mặc định là 10) — Số giây chờ máy chủ gửi dữ liệu trước khi từ bỏ. Đặt thành None để tắt timeout (không khuyến nghị, vì một kết nối bị treo có thể khiến cuộc gọi bị treo vô thời hạn).

Trả về

SafetensorsRepoMetadata

cùng metadata với get_safetensors_metadata().

Lấy metadata của mọi shard của một mô hình safetensors dạng sharded trên main từ Hub trong một yêu cầu duy nhất, thay vì get_safetensors_metadata() phân tích header của từng shard. Chỉ dành cho Hugging Face Hub.

Ví dụ:

>>> metadata = get_sharded_safetensors_metadata("HuggingFaceH4/zephyr-7b-beta")
>>> len(metadata.files_metadata)
8

get_space_runtime

< >

( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime

Tham số

  • repo_id (str) — ID của kho cần cập nhật. Ví dụ: "bigcode/in-the-stack".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

SpaceRuntime

Thông tin thời gian chạy về một Space, bao gồm giai đoạn và phần cứng của Space.

Lấy thông tin thời gian chạy về một Space.

get_space_secrets

< >

( repo_id: strtoken: bool | str | None = None ) → dict[str, SpaceSecret]

Tham số

  • repo_id (str) — ID của kho cần truy vấn. Ví dụ: "bigcode/in-the-stack".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

dict[str, SpaceSecret]

Từ điển các đối tượng SpaceSecret được đánh chỉ mục theo tên bí mật.

Lấy tất cả các bí mật từ một Space.

Giá trị bí mật chỉ có thể ghi và không thể đọc lại. Chỉ có khóa, mô tả và thời gian cập nhật cuối cùng được trả về.

Secrets cho phép thiết lập các khóa hoặc token bí mật cho một Space mà không cần hardcode chúng. Để biết thêm chi tiết, xem https://huggingface.co/docs/hub/spaces-overview#managing-secrets.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.get_space_secrets("username/my-space")
{'HF_TOKEN': SpaceSecret(key='HF_TOKEN', description='...', updated_at=datetime.datetime(...))}

get_space_variables

< >

( repo_id: strtoken: bool | str | None = None )

Tham số

  • repo_id (str) — ID của kho cần truy vấn. Ví dụ: "bigcode/in-the-stack".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Lấy tất cả các biến từ một Space.

Biến cho phép thiết lập các biến môi trường cho một Space mà không cần hardcode chúng. Để biết thêm chi tiết, xem https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

get_user_overview

< >

( username: strtoken: bool | str | None = None ) → User

Tham số

  • username (str) — Tên người dùng của người dùng cần xem tổng quan.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

User

Một đối tượng User chứa thông tin tổng quan về người dùng.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Nếu người dùng không tồn tại trên Hub.

Xem tổng quan về một người dùng trên Hub.

get_webhook

< >

( webhook_id: strtoken: bool | str | None = None ) → WebhookInfo

Tham số

  • webhook_id (str) — Định danh duy nhất của webhook cần lấy.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

WebhookInfo

Thông tin về webhook.

Lấy webhook theo id của nó.

Ví dụ:

>>> from huggingface_hub import get_webhook
>>> webhook = get_webhook("654bbbc16f2ec14d77f109cc")
>>> print(webhook)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    job=None,
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    secret="my-secret",
    domains=["repo", "discussion"],
    disabled=False,
)

get_zero_gpu_quota

< >

( token: bool | str | None = None ) → ZeroGpuQuota

Tham số

  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Một token chi tiết (fine-grained) phải có quyền “Billing > Read billing usage and payment method status” và một token OAuth phải có phạm vi read-billing.

Trả về

ZeroGpuQuota

Hạn mức ZeroGPU của người dùng đã xác thực.

Lấy hạn mức ZeroGPU của người dùng đã xác thực.

Có ích để theo dõi việc sử dụng ZeroGPU khi gọi các ZeroGPU Spaces theo chương trình (ví dụ: từ một ứng dụng, một agent hoặc một máy chủ MCP). Xem https://huggingface.co/docs/hub/spaces-zerogpu để biết thêm chi tiết.

Ví dụ:

>>> from huggingface_hub import get_zero_gpu_quota
>>> quota = get_zero_gpu_quota()
>>> quota
ZeroGpuQuota(base=2400, remaining=1810, resets_at=datetime.datetime(2026, 9, 30, 9, 12, 3, tzinfo=datetime.timezone.utc), overquota_used=0)
>>> print(f"{quota.remaining / 60:.1f} minutes left")
30.2 minutes left

grant_access

< >

( repo_id: struser: strrepo_type: str | None = Nonetoken: bool | str | None = None )

Tham số

  • repo_id (str) — ID của kho cần cấp quyền truy cập.
  • user (str) — Tên người dùng của người dùng được cấp quyền truy cập.
  • repo_type (str, tùy chọn) — Loại repo được cấp quyền truy cập. Phải là một trong model, dataset hoặc space. Mặc định là model.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 nếu kho không được bảo vệ.
  • HfHubHTTPError — HTTP 400 nếu người dùng đã có quyền truy cập vào kho.
  • HfHubHTTPError — HTTP 403 nếu bạn chỉ có quyền truy cập chỉ đọc vào kho. Điều này có thể xảy ra nếu bạn không có vai trò write hoặc admin trong tổ chức mà kho đó thuộc về, hoặc nếu bạn đã truyền một token read.
  • HfHubHTTPError — HTTP 404 nếu người dùng không tồn tại trên Hub.

Cấp quyền truy cập cho một người dùng đối với một kho có kiểm soát nhất định.

Việc cấp quyền truy cập không yêu cầu người dùng phải tự gửi yêu cầu truy cập. Người dùng sẽ được tự động thêm vào danh sách chấp nhận, cho phép họ tải xuống các tệp. Bạn có thể thu hồi quyền truy cập đã cấp vào bất kỳ lúc nào bằng cách sử dụng cancel_access_request() hoặc reject_access_request().

Để biết thêm thông tin về các kho có kiểm soát, hãy xem https://huggingface.co/docs/hub/models-gated.

hf_hub_download

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | Path | None = Nonelocal_dir: str | Path | None = Noneforce_download: bool = Falseetag_timeout: float = 10token: bool | str | None = Nonelocal_files_only: bool = Falsetqdm_class: type[base_tqdm] | None = Nonedry_run: bool = False ) → str or DryRunFileInfo

Tham số

  • repo_id (str) — Tên người dùng hoặc tên tổ chức và tên kho, phân tách bằng /.
  • filename (str) — Tên của tệp trong kho.
  • subfolder (str, tùy chọn) — Một giá trị tùy chọn tương ứng với một thư mục bên trong kho.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải xuống từ một dataset hoặc space, None hoặc "model" nếu tải xuống từ một model. Mặc định là None.
  • revision (str, tùy chọn) — Một id phiên bản Git tùy chọn, có thể là tên nhánh, một tag, hoặc một commit hash.
  • cache_dir (str, Path, tùy chọn) — Đường dẫn đến thư mục lưu trữ các tệp được lưu trong bộ nhớ đệm.
  • local_dir (str hoặc Path, tùy chọn) — Nếu được cung cấp, tệp đã tải xuống sẽ được đặt trong thư mục này.
  • force_download (bool, tùy chọn, mặc định là False) — Liệu tệp có nên được tải xuống ngay cả khi nó đã tồn tại trong bộ nhớ đệm cục bộ hay không.
  • etag_timeout (float, tùy chọn, mặc định là 10) — Khi lấy ETag, số giây chờ máy chủ gửi dữ liệu trước khi từ bỏ, được truyền vào httpx2.request.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • local_files_only (bool, tùy chọn, mặc định là False) — Nếu True, tránh tải xuống tệp và trả về đường dẫn đến tệp được lưu cục bộ nếu tệp đó tồn tại.
  • tqdm_class (tqdm, tùy chọn) — Nếu được cung cấp, sẽ ghi đè lên hành vi mặc định của thanh tiến trình. Đối số được truyền phải kế thừa từ tqdm.auto.tqdm hoặc ít nhất phải mô phỏng hành vi của nó. Mặc định là thanh tiến trình tùy chỉnh của HF, có thể bị vô hiệu hóa bằng cách đặt biến môi trường HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool, tùy chọn, mặc định là False) — Nếu True, thực hiện chạy thử mà không thực sự tải xuống tệp. Trả về một đối tượng DryRunFileInfo chứa thông tin về những gì sẽ được tải xuống.

Trả về

str hoặc DryRunFileInfo

  • Nếu dry_run=False: Đường dẫn cục bộ của tệp hoặc, nếu mạng bị tắt, phiên bản tệp được lưu trong bộ nhớ đệm trên đĩa gần nhất.
  • Nếu dry_run=True: Một đối tượng DryRunFileInfo chứa thông tin tải xuống.

Gây ra

RepositoryNotFoundError hoặc RevisionNotFoundError hoặc ~utils.RemoteEntryNotFoundError hoặc LocalEntryNotFoundError hoặc EnvironmentError hoặc OSError hoặc ValueError

  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.
  • RevisionNotFoundError — Nếu không tìm thấy revision để tải xuống.
  • ~utils.RemoteEntryNotFoundError — Nếu tệp cần tải xuống không được tìm thấy.
  • LocalEntryNotFoundError — Nếu mạng bị vô hiệu hóa hoặc không khả dụng và tệp không được tìm thấy trong bộ nhớ đệm.
  • EnvironmentError — Nếu token=True nhưng không tìm thấy token.
  • OSError — Nếu không thể xác định được ETag.
  • ValueError — Nếu giá trị của một số tham số không hợp lệ.

Tải xuống một tệp nhất định nếu tệp đó chưa có trong bộ nhớ đệm cục bộ.

Bố cục tệp cache mới trông như sau:

  • Thư mục cache chứa một thư mục con cho mỗi repo_id (được đặt tên theo loại repo)
  • bên trong mỗi thư mục repo:
    • refs là danh sách các cặp revision => commit_hash mới nhất được biết đến
    • blobs chứa các blob tệp thực tế (được xác định bằng git-sha hoặc sha256, tùy thuộc vào việc chúng có phải là tệp LFS hay không)
    • snapshots chứa một thư mục con cho mỗi commit, mỗi “commit” chứa tập con các tệp đã được giải quyết tại commit đó. Mỗi tên tệp là một symlink trỏ đến blob tại commit đó.
[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

Nếu local_dir được cung cấp, cấu trúc tệp từ kho sẽ được nhân bản tại vị trí này. Khi sử dụng tùy chọn này, cache_dir sẽ không được dùng và một thư mục .cache/huggingface/ sẽ được tạo tại gốc của local_dir để lưu trữ một số siêu dữ liệu liên quan đến các tệp đã tải xuống. Mặc dù cơ chế này không mạnh mẽ bằng hệ thống cache chính, nó được tối ưu hóa cho việc thường xuyên kéo phiên bản mới nhất của một kho.

Ẩn bình luận thảo luận

< >

( repo_id: strdiscussion_num: intcomment_id: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionComment

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • discussion_num (int) — Số thứ tự của Discussion hoặc Pull Request. Phải là một số nguyên dương.
  • comment_id (str) — ID của bình luận cần chỉnh sửa.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

DiscussionComment

bình luận ẩn

Ẩn một bình luận trên Discussion / Pull Request.

Nội dung của các bình luận ẩn không thể được truy xuất lại. Việc ẩn một bình luận là không thể đảo ngược.

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

inspect_job

< >

( job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • job_id (str) — ID của Job.
  • namespace (str, optional) — Namespace nơi Job đang chạy. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Kiểm tra một Job tính toán trên hạ tầng của Hugging Face.

Ví dụ:

>>> from huggingface_hub import inspect_job, run_job
>>> job = run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"])
>>> inspect_job(job_id=job.id)
JobInfo(
    id='68780d00bbe36d38803f645f',
    created_at=datetime.datetime(2025, 7, 16, 20, 35, 12, 808000, tzinfo=datetime.timezone.utc),
    docker_image='python:3.12',
    space_id=None,
    command=['python', '-c', "print('Hello from HF compute!')"],
    arguments=[],
    environment={},
    secrets={},
    flavor='cpu-basic',
    status=JobStatus(stage='RUNNING', message=None)
)

inspect_scheduled_job

< >

( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • scheduled_job_id (str) — ID của Job được lên lịch.
  • namespace (str, optional) — Namespace chứa Job được lên lịch. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Kiểm tra một Job tính toán đã lên lịch trên hạ tầng Hugging Face.

Ví dụ:

>>> from huggingface_hub import inspect_scheduled_job, create_scheduled_job
>>> scheduled_job = create_scheduled_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"], schedule="@hourly")
>>> inspect_scheduled_job(scheduled_job_id=scheduled_job.id)

kernel_info

< >

( repo_id: strrevision: str | None = Nonetimeout: float | None = Nonetoken: bool | str | None = None ) → ModelInfo

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • revision (str, tùy chọn) — Phiên bản của kho kernel để lấy thông tin.
  • timeout (float, tùy chọn) — Có nên đặt thời gian chờ cho yêu cầu đến Hub hay không.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

ModelInfo

Thông tin về kho lưu trữ kernel.

Lấy thông tin về một kernel cụ thể trên huggingface.co.

list_accepted_access_requests

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[AccessRequest]

Tham số

  • repo_id (str) — ID của kho cần lấy các yêu cầu truy cập.
  • repo_type (str, tùy chọn) — Loại repo để lấy các yêu cầu truy cập. Phải là một trong model, dataset hoặc space. Mặc định là model.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[AccessRequest]

Một iterable các đối tượng AccessRequest. Mỗi mục chứa thuộc tính username, request_id, email, status và timestamp. Nếu kho có cổng có biểu mẫu tùy chỉnh, thuộc tính fields sẽ được điền với câu trả lời của người dùng.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 nếu kho không được bảo vệ.
  • HfHubHTTPError — HTTP 403 nếu bạn chỉ có quyền truy cập chỉ đọc vào kho. Điều này có thể xảy ra nếu bạn không có vai trò write hoặc admin trong tổ chức mà kho đó thuộc về, hoặc nếu bạn đã truyền một token read.

Lấy các yêu cầu truy cập đã được chấp nhận cho một kho có kiểm soát nhất định.

Một yêu cầu được chấp nhận có nghĩa là người dùng đã yêu cầu quyền truy cập vào repo và yêu cầu đó đã được chấp thuận. Người dùng có thể tải xuống bất kỳ tệp nào của repo. Nếu chế độ phê duyệt là tự động, danh sách này mặc định phải chứa tất cả các yêu cầu. Các yêu cầu đã được chấp nhận có thể bị hủy hoặc từ chối vào bất kỳ lúc nào bằng cách sử dụng cancel_access_request() và reject_access_request(). Một yêu cầu bị hủy sẽ quay lại danh sách chờ trong khi một yêu cầu bị từ chối sẽ chuyển sang danh sách đã từ chối. Trong cả hai trường hợp, người dùng sẽ mất quyền truy cập vào repo.

Để biết thêm thông tin về các kho có kiểm soát, hãy xem https://huggingface.co/docs/hub/models-gated.

Ví dụ:

>>> from huggingface_hub import list_accepted_access_requests

>>> requests = list(list_accepted_access_requests("meta-llama/Llama-2-7b"))
>>> len(requests)
411
>>> requests[0]
[
    AccessRequest(
        username='clem',
        request_id='655f3a1c9e6b2d4f8a7c1e05',
        fullname='Clem 🤗',
        email='***',
        timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
        status='accepted',
        fields=None,
    ),
    ...
]

list_bucket_tree

< >

( bucket_id: strprefix: str | None = Nonerecursive: bool | None = Nonetoken: str | bool | None = None ) → Iterable[Union[BucketFile, BucketFolder]]

Tham số

  • bucket_id (str) — ID của bucket (ví dụ: "username/my-bucket").
  • prefix (str, tuỳ chọn) — Lọc kết quả thành các tệp có đường dẫn bắt đầu bằng tiền tố này.
  • recursive (bool, tùy chọn) — Nếu True, liệt kê các tệp đệ quy. Nếu False (mặc định), chỉ liệt kê các tệp và thư mục ở thư mục gốc.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[Union[BucketFile, BucketFolder]]

Một iterable gồm các đối tượng BucketFile và BucketFolder chứa thông tin về tệp và thư mục (đường dẫn, v.v.).

Liệt kê các tệp trong một bucket.

Ví dụ:

>>> from huggingface_hub import list_bucket_tree
>>> for file_info in list_bucket_tree(bucket_id="username/my-bucket"):
...     print(file_info.path)

>>> # Filter by prefix
>>> for file_info in list_bucket_tree(bucket_id="username/my-bucket", prefix="models/"):
...     print(file_info.path)

list_buckets

< >

( namespace: str | None = Nonesearch: str | None = Nonetoken: bool | str | None = None ) → Iterable[BucketInfo]

Tham số

  • namespace (str, optional) — Liệt kê các bucket dưới namespace này (người dùng hoặc tổ chức). Mặc định là liệt kê các bucket của người dùng.
  • search (str, tuỳ chọn) — Chuỗi tìm kiếm để lọc tên bucket.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[BucketInfo]

Một iterable gồm các đối tượng BucketInfo.

Liệt kê các bucket trên Hub thuộc một namespace nhất định.

Ví dụ:

>>> from huggingface_hub import list_buckets
>>> for bucket in list_buckets(): # lists buckets in the user's namespace
...     print(bucket)

>>> for bucket in list_buckets(namespace="huggingface"): # lists buckets in the "huggingface" organization
...     print(bucket)

>>> for bucket in list_buckets(search="my-prefix"): # filter buckets by name
...     print(bucket)

list_collections

< >

( owner: list[str] | str | None = Noneitem: list[str] | str | None = Nonesort: CollectionSort_T | None = Nonelimit: int | None = Nonetoken: bool | str | None = None ) → Iterable[Collection]

Tham số

  • owner (list[str] hoặc str, tùy chọn) — Lọc theo tên người dùng của chủ sở hữu.
  • item (list[str] hoặc str, tùy chọn) — Lọc các bộ sưu tập chứa một mục cụ thể. Ví dụ: "models/teknium/OpenHermes-2.5-Mistral-7B", "datasets/squad" hoặc "papers/2311.12983".
  • sort (Literal["lastModified", "trending", "upvotes"], tuỳ chọn) — Sắp xếp các bộ sưu tập theo thời gian sửa đổi gần nhất, xu hướng hoặc số lượt bình chọn.
  • limit (int, tùy chọn) — Số lượng tối đa các bộ sưu tập được trả về.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[Collection]

một đối tượng có thể lặp lại của các đối tượng Collection.

Liệt kê các bộ sưu tập trên Huggingface Hub, dựa trên một số bộ lọc.

Khi liệt kê các bộ sưu tập, danh sách mục trong mỗi bộ sưu tập bị cắt ngắn tối đa 4 mục. Để lấy tất cả các mục từ một bộ sưu tập, bạn phải sử dụng get_collection().

list_daily_papers

< >

( date: str | None = Nonetoken: bool | str | None = Noneweek: str | None = Nonemonth: str | None = Nonesubmitter: str | None = Nonesort: DailyPapersSort_T | None = Nonep: int | None = Nonelimit: int | None = None ) → Iterable[PaperInfo]

Tham số

  • date (str, tùy chọn) — Ngày theo định dạng ISO (YYYY-MM-DD) để lấy các bài báo hàng ngày. Mặc định là các bài báo mới nhất.
  • token (Union[bool, str, None], tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ. Để tắt xác thực, truyền False.
  • week (str, tùy chọn) — Tuần theo định dạng ISO (YYYY-Www) để lấy các bài báo hàng ngày. Ví dụ, 2025-W09.
  • month (str, tùy chọn) — Tháng theo định dạng ISO (YYYY-MM) để lấy các bài báo hàng ngày. Ví dụ, 2025-02.
  • submitter (str, tùy chọn) — Tên người dùng của người gửi để lọc các bài báo hàng ngày.
  • sort (Literal["publishedAt", "trending"], optional) — Thứ tự sắp xếp cho các bài báo hàng ngày. Có thể sắp xếp theo publishedAt hoặc theo trending. Mặc định là "publishedAt"
  • p (int, tùy chọn) — Số trang cho phân trang. Mặc định là 0.
  • limit (int, tùy chọn) — Giới hạn số lượng bài báo cần lấy. Mặc định là 50.

Trả về

Iterable[PaperInfo]

một iterable các đối tượng huggingface_hub.hf_api.PaperInfo.

Liệt kê các bài báo hàng ngày được xuất bản vào một ngày cụ thể trên Hugging Face Hub.

Ví dụ:

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> list(api.list_daily_papers(date="2025-10-29"))

list_dataset_parquet_files

< >

( repo_id: strconfig: str | None = Nonetoken: bool | str | None = None ) → list[DatasetParquetEntry]

Tham số

  • repo_id (str) — ID của kho dữ liệu (ví dụ: "username/dataset-name").
  • config (str, tùy chọn) — Lọc theo tên config/subset cụ thể. Khi được cung cấp, chỉ các tệp parquet cho config đó sẽ được trả về.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

list[DatasetParquetEntry]

một danh sách các đối tượng DatasetParquetEntry chứa config, split, url và size cho từng tệp parquet.

Liệt kê các tệp parquet có sẵn cho một tập dữ liệu trên Hub.

Tất cả các dataset được lưu trữ trên Hub sẽ được tự động chuyển đổi sang Parquet bởi Dataset Viewer. Phương thức này trả về danh sách các tệp parquet kèm theo URL, configs, splits và kích thước của chúng.

Ví dụ:

>>> from huggingface_hub import list_dataset_parquet_files
>>> list_dataset_parquet_files("lhoestq/demo1")
>>> entries[0]
DatasetParquetEntry(config='default', split='train', url='https://huggingface.co/...', size=5038)

list_datasets

< >

( filter: str | Iterable[str] | None = Noneauthor: str | None = Nonebenchmark: Literal[True] | Literal['official'] | str | None = Nonedataset_name: str | None = Nonegated: bool | None = Nonelanguage_creators: str | list[str] | None = Nonelanguage: str | list[str] | None = Nonemultilinguality: str | list[str] | None = Nonesize_categories: str | list[str] | None = Nonetask_categories: str | list[str] | None = Nonetask_ids: str | list[str] | None = Nonesearch: str | None = Nonesort: DatasetSort_T | None = Nonelimit: int | None = Noneexpand: list[ExpandDatasetProperty_T] | None = Nonefull: bool | None = Nonetoken: bool | str | None = None ) → Iterable[DatasetInfo]

Tham số

  • filter (str hoặc Iterable[str], tùy chọn) — Một chuỗi hoặc danh sách các chuỗi để lọc các bộ dữ liệu trên hub.
  • author (str, tùy chọn) — Chuỗi nhận diện tác giả của các bộ dữ liệu được trả về.
  • benchmark (True, "official", str, tùy chọn) — Lọc bộ dữ liệu theo benchmark. Có thể là True hoặc "official" để trả về các bộ dữ liệu benchmark chính thức. Vì tính tương thích trong tương lai, cũng có thể là một chuỗi đại diện cho tên benchmark (hiện tại chỉ hỗ trợ “official”).
  • dataset_name (str, tùy chọn) — Một chuỗi hoặc danh sách các chuỗi có thể được sử dụng để xác định các bộ dữ liệu trên Hub theo tên của chúng, chẳng hạn như SQAC hoặc wikineural
  • gated (bool, tùy chọn) — Một giá trị boolean để lọc các dataset trên Hub có bị hạn chế truy cập (gated) hay không. Mặc định, tất cả các dataset đều được trả về. Nếu truyền gated=True, chỉ các dataset bị hạn chế truy cập mới được trả về. Nếu truyền gated=False, chỉ các dataset không bị hạn chế truy cập mới được trả về.
  • language_creators (str hoặc List, tùy chọn) — Một chuỗi hoặc danh sách các chuỗi có thể được sử dụng để xác định các bộ dữ liệu trên Hub dựa trên cách dữ liệu được tuyển chọn, chẳng hạn như crowdsourced hoặc machine_generated.
  • language (str hoặc List, tùy chọn) — Một chuỗi hoặc danh sách các chuỗi đại diện cho mã ngôn ngữ hai ký tự để lọc bộ dữ liệu trên Hub.
  • multilinguality (str hoặc List, tùy chọn) — Một chuỗi hoặc danh sách các chuỗi đại diện cho bộ lọc cho các bộ dữ liệu chứa nhiều ngôn ngữ.
  • size_categories (str hoặc List, tùy chọn) — Một chuỗi hoặc danh sách các chuỗi có thể được sử dụng để xác định các bộ dữ liệu trên Hub theo kích thước của bộ dữ liệu, chẳng hạn như 100K<n<1M hoặc 1M<n<10M.
  • task_categories (str hoặc List, tùy chọn) — Một chuỗi hoặc danh sách các chuỗi có thể được sử dụng để xác định các bộ dữ liệu trên Hub theo nhiệm vụ được thiết kế, chẳng hạn như audio_classification hoặc named_entity_recognition.
  • task_ids (str hoặc List, tùy chọn) — Một chuỗi hoặc danh sách các chuỗi có thể được sử dụng để xác định các bộ dữ liệu trên Hub theo nhiệm vụ cụ thể như speech_emotion_recognition hoặc paraphrase.
  • search (str, tuỳ chọn) — Chuỗi sẽ được chứa trong các bộ dữ liệu được trả về.
  • sort (DatasetSort_T, optional) — Khóa để sắp xếp các dataset kết quả. Các giá trị có thể là “created_at”, “downloads”, “last_modified”, “likes” và “trending_score”.
  • limit (int, tùy chọn) — Giới hạn số lượng bộ dữ liệu được lấy. Để tùy chọn này là None sẽ lấy tất cả các bộ dữ liệu.
  • expand (list[ExpandDatasetProperty_T], tuỳ chọn) — Danh sách các thuộc tính cần trả về trong phản hồi. Khi được sử dụng, chỉ các thuộc tính trong danh sách sẽ được trả về. Tham số này không thể được sử dụng nếu full được truyền vào. Các giá trị có thể là "author", "cardData", "citation", "createdAt", "disabled", "description", "downloads", "downloadsAllTime", "gated", "lastModified", "likes", "mainSize", "paperswithcode_id", "private", "siblings", "sha", "tags", "trendingScore", "usedStorage" và "resourceGroup".
  • full (bool, tùy chọn) — Có lấy toàn bộ dữ liệu của bộ dữ liệu, bao gồm last_modified, card_data và các tệp hay không. Có thể chứa thông tin hữu ích như ID PapersWithCode.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[DatasetInfo]

một iterable các đối tượng huggingface_hub.hf_api.DatasetInfo.

Liệt kê các bộ dữ liệu được lưu trữ trên Huggingface Hub, dựa trên một số bộ lọc.

Ví dụ sử dụng với đối số filter:

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all datasets
>>> api.list_datasets()


# List only the text classification datasets
>>> api.list_datasets(filter="task_categories:text-classification")


# List only the datasets in russian for language modeling
>>> api.list_datasets(
...     filter=("language:ru", "task_ids:language-modeling")
... )

# List FiftyOne datasets (identified by the tag "fiftyone" in dataset card)
>>> api.list_datasets(filter="fiftyone")

Ví dụ sử dụng với đối số search:

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all datasets with "text" in their name
>>> api.list_datasets(search="text")

# List all datasets with "text" in their name made by google
>>> api.list_datasets(search="text", author="google")

list_inference_catalog

< >

( accelerator: Literal['cpu', 'gpu', 'neuron'] | str | None = Noneengine: Literal['llamacpp', 'sglang', 'tei', 'vllm'] | str | None = Nonelicense: str | None = Nonetask: str | None = Nonesearch: str | None = Nonelimit: int | None = Nonetoken: bool | str | None = None ) → list[InferenceCatalogModel]

Tham số

  • accelerator (str, tùy chọn) — Chỉ trả về các mô hình có công thức (recipe) cho bộ tăng tốc này ("cpu", "gpu" hoặc "neuron").
  • engine (str, tùy chọn) — Chỉ trả về các mô hình có công thức (recipe) cho engine suy luận này (ví dụ: "vllm", "llamacpp", "tei", "sglang").
  • license (str, tùy chọn) — Chỉ trả về các mô hình dưới giấy phép này (ví dụ: "Apache 2.0").
  • task (str, tùy chọn) — Chỉ trả về các mô hình cho tác vụ này (ví dụ: "text-generation").
  • search (str, tuỳ chọn) — Chỉ trả về các mô hình khớp với truy vấn tìm kiếm này.
  • limit (int, tùy chọn) — Số lượng tối đa các mô hình cần trả về.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication).

Trả về

list[InferenceCatalogModel]

Các mô hình có sẵn trong danh mục, mỗi mô hình kèm theo các công thức đã được kiểm chứng.

Liệt kê các model có sẵn trong Hugging Face Inference Catalog.

Mục tiêu của Inference Catalog là cung cấp một danh sách các mô hình được tuyển chọn, tối ưu cho suy luận và đã được kiểm tra với các cấu hình mặc định. Xem https://huggingface.co/proxy/endpoints.huggingface.co/catalog để xem danh sách các mô hình có sẵn trong catalog.

Sử dụng create_inference_endpoint_from_catalog() để triển khai một mô hình hoặc một công thức từ danh mục.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> catalog = api.list_inference_catalog(task="text-generation", accelerator="neuron")
>>> [(model.repo_id, [recipe.id for recipe in model.recipes]) for model in catalog]
[('meta-llama/Llama-3.1-8B-Instruct', ['sizzling-biryani-g4xsi1ac', 'artisanal-quinoa-yz9ynamx']), ...]

list_inference_catalog là thử nghiệm. API của nó có thể thay đổi trong tương lai. Vui lòng cung cấp phản hồi nếu bạn có bất kỳ đề xuất hoặc yêu cầu nào.

list_inference_endpoints

< >

( namespace: str | None = Nonetoken: bool | str | None = None ) → listInferenceEndpoint

Tham số

  • namespace (str, optional) — Namespace để liệt kê các endpoint. Mặc định là người dùng hiện tại. Đặt thành "*" để liệt kê tất cả các endpoint từ tất cả các namespace (tức là namespace cá nhân và tất cả các tổ chức mà người dùng thuộc về).
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

listĐiểm cuối suy luận

Danh sách tất cả các điểm cuối suy luận cho namespace được chỉ định.

Liệt kê tất cả các điểm cuối suy luận cho namespace được chỉ định.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.list_inference_endpoints()
[InferenceEndpoint(name='my-endpoint', ...), ...]

list_inference_endpoints_hardware

< >

( namespace: str | None = Nonetoken: bool | str | None = None ) → list[InferenceEndpointHardware]

Tham số

  • namespace (str, không bắt buộc) — Namespace mà bạn muốn liệt kê phần cứng và hạn mức accelerator khả dụng. Mặc định là người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication).

Trả về

list[InferenceEndpointHardware]

Phần cứng có sẵn ở mọi nhà cung cấp và khu vực, bao gồm cả phần cứng hiện không khả dụng hoặc đã bị ngừng hỗ trợ.

Liệt kê phần cứng có sẵn để triển khai một Inference Endpoint.

Mỗi mục chứa các giá trị chính xác của vendor, region, accelerator, instance_type và instance_size được kỳ vọng bởi create_inference_endpoint(), cùng với giá và hạn mức accelerator của namespace.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> hardware = api.list_inference_endpoints_hardware()
>>> [hw.id for hw in hardware if hw.accelerator == "gpu" and hw.status == "available"]
['aws-us-east-1-nvidia-l4-x1', 'aws-us-east-1-nvidia-l4-x4', ...]

list_jobs

< >

( status: list[JobStage | str] | JobStage | str | None = Nonelabels: dict[str, str] | None = Nonetimeout: int | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → Iterable[JobInfo]

Tham số

  • status (JobStage, str hoặc list, tùy chọn) — Chỉ trả về các Job có trạng thái được chỉ định, ví dụ "RUNNING" hoặc [JobStage.RUNNING, JobStage.SCHEDULING]. Xem JobStage để biết các giá trị có thể.
  • labels (dict[str, str], tùy chọn) — Chỉ trả về các Job có tất cả các nhãn key=value đã cho, ví dụ {"env": "prod", "team": "ml"}.
  • timeout (float, tùy chọn) — Có nên đặt thời gian chờ cho yêu cầu đến Hub hay không.
  • namespace (str, optional) — Namespace mà từ đó nó liệt kê các job. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Trả về

Iterable[JobInfo]

một iterable của các đối tượng JobInfo.

Liệt kê các Job tính toán trên hạ tầng của Hugging Face.

list_jobs_hardware

< >

( token: bool | str | None = None ) → list[JobHardwareInfo]

Trả về

list[JobHardwareInfo]

Danh sách các cấu hình phần cứng khả dụng.

Liệt kê các tùy chọn phần cứng khả dụng cho Jobs trên hạ tầng của Hugging Face.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> hardware_list = api.list_jobs_hardware()
>>> hardware_list[0]
JobHardwareInfo(name='cpu-basic', pretty_name='CPU Basic', cpu='2 vCPU', ram='16 GB', ephemeral_storage='20 GB', accelerator=None, unit_cost_micro_usd=167, unit_cost_usd=0.000167, unit_label='minute')
>>> hardware_list[0].name
'cpu-basic'

# Filter GPU options
>>> gpu_hardware = [hw for hw in hardware_list if hw.accelerator is not None]
>>> gpu_hardware[0].accelerator.model
'T4'

list_lfs_files

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[LFSFileInfo]

Tham số

  • repo_id (str) — Kho lưu trữ mà bạn đang liệt kê các tệp LFS.
  • repo_type (str, tùy chọn) — Loại kho. Đặt thành "dataset" hoặc "space" nếu liệt kê từ một dataset hoặc space, None hoặc "model" nếu liệt kê từ một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[LFSFileInfo]

Một trình lặp các đối tượng LFSFileInfo.

Liệt kê tất cả các tệp LFS trong một kho trên Hub.

Điều này chủ yếu hữu ích để đếm lượng dung lượng lưu trữ mà một repo đang sử dụng và cuối cùng là dọn dẹp các tệp lớn bằng permanently_delete_lfs_files(). Lưu ý rằng đây sẽ là một hành động vĩnh viễn, ảnh hưởng đến tất cả các commit tham chiếu đến các tệp đã bị xóa này và không thể hoàn tác.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")

# Filter files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))

# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)

list_liked_repos

< >

( user: str | None = Nonetoken: bool | str | None = None ) → UserLikes

Tham số

  • user (str, tùy chọn) — Tên của người dùng mà bạn muốn lấy các lượt thích.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

UserLikes

đối tượng chứa tên người dùng và 3 danh sách id kho (1 cho models, 1 cho datasets và 1 cho Spaces).

Gây ra

ValueError

  • ValueError — Nếu user không được truyền và không tìm thấy token (từ đối số hoặc từ máy).

Liệt kê tất cả các kho lưu trữ công khai được một người dùng thích trên huggingface.co.

Danh sách này là công khai nên token là tùy chọn. Nếu user không được truyền vào, mặc định sẽ là người dùng đã đăng nhập.

Xem thêm unlike().

Ví dụ:

>>> from huggingface_hub import list_liked_repos

>>> likes = list_liked_repos("julien-c")

>>> likes.user
"julien-c"

>>> likes.models
["osanseviero/streamlit_1.15", "Xhaheen/ChatGPT_HF", ...]

list_models

< >

( filter: str | Iterable[str] | None = Noneauthor: str | None = Noneapps: str | list[str] | None = Nonegated: bool | None = Noneinference: Literal['warm'] | None = Noneinference_provider: Literal['all'] | PROVIDER_T | list[PROVIDER_T] | None = Nonetrained_dataset: str | list[str] | None = Nonesearch: str | None = Nonepipeline_tag: str | None = Nonenum_parameters: str | None = Noneemissions_thresholds: tuple[float, float] | None = Nonesort: ModelSort_T | None = Nonelimit: int | None = Noneexpand: list[ExpandModelProperty_T] | None = Nonefull: bool | None = NonecardData: bool = Falsefetch_config: bool = Falsetoken: bool | str | None = None ) → Iterable[ModelInfo]

Tham số

  • filter (str hoặc Iterable[str], tùy chọn) — Một chuỗi hoặc danh sách các chuỗi để lọc các model trên Hub. Các model có thể được lọc theo thư viện, ngôn ngữ, tác vụ, thẻ, và nhiều tiêu chí khác.
  • author (str, tùy chọn) — Chuỗi nhận diện tác giả (người dùng hoặc tổ chức) của các model được trả về.
  • apps (str hoặc List, tùy chọn) — Một chuỗi hoặc danh sách các chuỗi để lọc các model trên Hub hỗ trợ các ứng dụng được chỉ định. Các giá trị ví dụ bao gồm "ollama" hoặc ["ollama", "vllm"].
  • gated (bool, tùy chọn) — Một giá trị boolean để lọc các model trên Hub có bị hạn chế truy cập (gated) hay không. Mặc định, tất cả các model đều được trả về. Nếu truyền gated=True, chỉ các model bị hạn chế truy cập mới được trả về. Nếu truyền gated=False, chỉ các model không bị hạn chế truy cập mới được trả về.
  • inference (Literal["warm"], tùy chọn) — Nếu là “warm”, lọc các model trên Hub hiện đang được phục vụ bởi ít nhất một nhà cung cấp.
  • inference_provider (Literal["all"] hoặc str, tùy chọn) — Chuỗi để lọc các model trên Hub được cung cấp bởi một provider cụ thể. Truyền "all" để lấy tất cả các model được cung cấp bởi ít nhất một provider.
  • trained_dataset (str hoặc List, tùy chọn) — Một thẻ chuỗi hoặc danh sách các thẻ chuỗi của bộ dữ liệu đã được huấn luyện cho một mô hình trên Hub.
  • search (str, tuỳ chọn) — Chuỗi sẽ được chứa trong các model id được trả về.
  • pipeline_tag (str, tùy chọn) — Chuỗi thẻ pipeline để lọc các model trên Hub, chẳng hạn như summarization.
  • num_parameters (str, tùy chọn) — Lọc mô hình theo số lượng tham số. Chấp nhận cùng cú pháp khoảng giá trị như giao diện và API của Hub, ví dụ "min:6B,max:128B", "min:6B" hoặc "max:128B".
  • emissions_thresholds (Tuple, tùy chọn) — Một tuple gồm hai số nguyên hoặc số thực, đại diện cho mức carbon tối thiểu và tối đa (tính bằng gam) để lọc các mô hình kết quả.
  • sort (ModelSort_T, tuỳ chọn) — Khóa để sắp xếp các mô hình kết quả. Các giá trị có thể là “created_at”, “downloads”, “last_modified”, “likes” và “trending_score”.
  • limit (int, tùy chọn) — Giới hạn số lượng model được lấy về. Để tùy chọn này là None để lấy tất cả các model.
  • expand (list[ExpandModelProperty_T], tuỳ chọn) — Danh sách các thuộc tính cần trả về trong phản hồi. Khi được sử dụng, chỉ các thuộc tính trong danh sách sẽ được trả về. Tham số này không thể được sử dụng nếu full, cardData hoặc fetch_config được truyền vào. Các giá trị có thể là "author", "cardData", "config", "createdAt", "disabled", "downloads", "downloadsAllTime", "evalResults", "gated", "gguf", "inference", "inferenceProviderMapping", "lastModified", "library_name", "likes", "mask_token", "model-index", "pipeline_tag", "private", "safetensors", "sha", "siblings", "spaces", "tags", "transformersInfo", "trendingScore", "widgetData", và "resourceGroup".
  • full (bool, tùy chọn) — Có lấy toàn bộ dữ liệu của model hay không, bao gồm last_modified, sha, các tệp và tags. Mặc định được đặt thành True khi sử dụng bộ lọc.
  • cardData (bool, tùy chọn) — Có lấy thêm metadata của model hay không. Có thể chứa thông tin hữu ích như lượng khí thải carbon, các chỉ số (metrics) và các dataset được dùng để huấn luyện.
  • fetch_config (bool, tùy chọn) — Có lấy các cấu hình mô hình hay không. Mục này không được bao gồm trong full do kích thước lớn.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[ModelInfo]

một iterable các đối tượng huggingface_hub.hf_api.ModelInfo.

Liệt kê các mô hình được lưu trữ trên Huggingface Hub, dựa trên một số bộ lọc.

Ví dụ:

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all models
>>> api.list_models()

# List text classification models
>>> api.list_models(filter="text-classification")

# List models from the KerasHub library
>>> api.list_models(filter="keras-hub")

# List models served by Cohere
>>> api.list_models(inference_provider="cohere")

# List models with "bert" in their name
>>> api.list_models(search="bert")

# List models with "bert" in their name and pushed by google
>>> api.list_models(search="bert", author="google")

# List models with 6B to 128B parameters
>>> api.list_models(num_parameters="min:6B,max:128B", sort="likes")

list_organization_followers

< >

( organization: strtoken: bool | str | None = None ) → Iterable[User]

Tham số

  • organization (str) — Tên của tổ chức cần lấy danh sách người theo dõi.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[User]

Danh sách các đối tượng User là người theo dõi của tổ chức.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Nếu tổ chức không tồn tại trên Hub.

Liệt kê người theo dõi của một tổ chức trên Hub.

list_organization_members

< >

( organization: strtoken: bool | str | None = None ) → Iterable[User]

Tham số

  • organization (str) — Tên của tổ chức cần lấy danh sách thành viên.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[User]

Danh sách các đối tượng User với các thành viên của tổ chức.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Nếu tổ chức không tồn tại trên Hub.

Danh sách các thành viên của một tổ chức trên Hub.

list_papers

< >

( query: str | None = Nonelimit: int | None = Nonetoken: bool | str | None = None ) → Iterable[PaperInfo]

Tham số

  • query (str, tùy chọn) — Chuỗi truy vấn tìm kiếm để tìm các bài báo. Nếu được cung cấp, sẽ trả về các bài báo khớp với truy vấn.
  • limit (int, tùy chọn) — Số lượng tối đa các bài báo cần trả về.
  • token (Union[bool, str, None], tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[PaperInfo]

một iterable các đối tượng huggingface_hub.hf_api.PaperInfo.

Liệt kê các bài báo hàng ngày trên Hugging Face Hub dựa trên truy vấn tìm kiếm.

Ví dụ:

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all papers with "attention" in their title
>>> api.list_papers(query="attention")

danh_yêu_cầu_truy_cập_đang_chờ

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[AccessRequest]

Tham số

  • repo_id (str) — ID của kho cần lấy các yêu cầu truy cập.
  • repo_type (str, tùy chọn) — Loại repo để lấy các yêu cầu truy cập. Phải là một trong model, dataset hoặc space. Mặc định là model.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[AccessRequest]

Một iterable các đối tượng AccessRequest. Mỗi mục chứa thuộc tính username, request_id, email, status và timestamp. Nếu kho có cổng có biểu mẫu tùy chỉnh, thuộc tính fields sẽ được điền với câu trả lời của người dùng.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 nếu kho không được bảo vệ.
  • HfHubHTTPError — HTTP 403 nếu bạn chỉ có quyền truy cập chỉ đọc vào kho. Điều này có thể xảy ra nếu bạn không có vai trò write hoặc admin trong tổ chức mà kho đó thuộc về, hoặc nếu bạn đã truyền một token read.

Lấy các yêu cầu truy cập đang chờ cho một kho có kiểm soát được chỉ định.

Một yêu cầu đang chờ có nghĩa là người dùng đã yêu cầu quyền truy cập vào kho nhưng yêu cầu đó chưa được xử lý. Nếu chế độ phê duyệt là tự động, danh sách này nên trống. Các yêu cầu đang chờ có thể được chấp nhận hoặc từ chối bằng cách sử dụng accept_access_request() và reject_access_request().

Để biết thêm thông tin về các kho có kiểm soát, hãy xem https://huggingface.co/docs/hub/models-gated.

Ví dụ:

>>> from huggingface_hub import list_pending_access_requests, accept_access_request

# List pending requests
>>> requests = list(list_pending_access_requests("meta-llama/Llama-2-7b"))
>>> len(requests)
411
>>> requests[0]
[
    AccessRequest(
        username='clem',
        request_id='655f3a1c9e6b2d4f8a7c1e05',
        fullname='Clem 🤗',
        email='***',
        timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
        status='pending',
        fields=None,
    ),
    ...
]

# Accept Clem's request
>>> accept_access_request("meta-llama/Llama-2-7b", "clem")

list_rejected_access_requests

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[AccessRequest]

Tham số

  • repo_id (str) — ID của kho cần lấy các yêu cầu truy cập.
  • repo_type (str, tùy chọn) — Loại repo để lấy các yêu cầu truy cập. Phải là một trong model, dataset hoặc space. Mặc định là model.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[AccessRequest]

Một iterable các đối tượng AccessRequest. Mỗi mục chứa thuộc tính username, request_id, email, status và timestamp. Nếu kho có cổng có biểu mẫu tùy chỉnh, thuộc tính fields sẽ được điền với câu trả lời của người dùng.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 nếu kho không được bảo vệ.
  • HfHubHTTPError — HTTP 403 nếu bạn chỉ có quyền truy cập chỉ đọc vào kho. Điều này có thể xảy ra nếu bạn không có vai trò write hoặc admin trong tổ chức mà kho đó thuộc về, hoặc nếu bạn đã truyền một token read.

Lấy các yêu cầu truy cập bị từ chối cho một kho có kiểm soát nhất định.

Yêu cầu bị từ chối có nghĩa là người dùng đã yêu cầu quyền truy cập vào repo và yêu cầu đó đã bị chủ sở hữu repo (có thể là bạn hoặc một người dùng khác trong tổ chức của bạn) từ chối một cách rõ ràng. Người dùng không thể tải xuống bất kỳ tệp nào của repo. Các yêu cầu bị từ chối có thể được chấp nhận hoặc hủy vào bất kỳ lúc nào bằng cách sử dụng accept_access_request() và cancel_access_request(). Một yêu cầu bị hủy sẽ quay lại danh sách đang chờ, trong khi một yêu cầu được chấp nhận sẽ chuyển sang danh sách đã chấp nhận.

Để biết thêm thông tin về các kho có kiểm soát, hãy xem https://huggingface.co/docs/hub/models-gated.

Ví dụ:

>>> from huggingface_hub import list_rejected_access_requests

>>> requests = list(list_rejected_access_requests("meta-llama/Llama-2-7b"))
>>> len(requests)
411
>>> requests[0]
[
    AccessRequest(
        username='clem',
        request_id='655f3a1c9e6b2d4f8a7c1e05',
        fullname='Clem 🤗',
        email='***',
        timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
        status='rejected',
        fields=None,
    ),
    ...
]

list_repo_commits

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = Nonerevision: str | None = Noneformatted: bool = False ) → list[GitCommitInfo]

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu liệt kê các commit từ một dataset hoặc một Space, None hoặc "model" nếu liệt kê từ một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • revision (str, tùy chọn) — Phiên bản git để commit từ. Mặc định là đầu của nhánh "main".
  • formatted (bool) — Có nên trả về tiêu đề và mô tả của các commit được định dạng HTML hay không. Mặc định là False.

Trả về

list[GitCommitInfo]

danh sách các đối tượng chứa thông tin về các commit cho một kho trên Hub.

Gây ra

RepositoryNotFoundError hoặc RevisionNotFoundError

  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho là riêng tư nhưng chưa xác thực hoặc kho không tồn tại.
  • RevisionNotFoundError — Nếu không tìm thấy revision (lỗi 404) trên repo.

Lấy danh sách các commit của một phiên bản nhất định cho một kho trên Hub.

Các commit được sắp xếp theo ngày (commit gần nhất ở đầu).

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Commits are sorted by date (last commit first)
>>> initial_commit = api.list_repo_commits("gpt2")[-1]

# Initial commit is always a system commit containing the `.gitattributes` file.
>>> initial_commit
GitCommitInfo(
    commit_id='9b865efde13a30c13e0a33e536cf3e4a5a9d71d8',
    authors=['system'],
    created_at=datetime.datetime(2019, 2, 18, 10, 36, 15, tzinfo=datetime.timezone.utc),
    title='initial commit',
    message='',
    formatted_title=None,
    formatted_message=None
)

# Create an empty branch by deriving from initial commit
>>> api.create_branch("gpt2", branch="new_empty_branch", revision=initial_commit.commit_id)

list_repo_files

< >

( repo_id: strrevision: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None ) → list[str]

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • revision (str, tùy chọn) — Phiên bản của kho chứa mà bạn muốn lấy thông tin từ đó.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

list[str]

danh sách các tệp trong một kho lưu trữ nhất định.

Lấy danh sách các tệp trong một kho lưu trữ được chỉ định.

list_repo_likers

< >

( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[User]

Tham số

  • repo_id (str) — Kho lưu trữ cần truy xuất. Ví dụ: "user/my-cool-model".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.

Trả về

Iterable[User]

một iterable các đối tượng huggingface_hub.hf_api.User.

Liệt kê tất cả người dùng đã thích một kho lưu trữ (repo) cụ thể trên hugging Face Hub.

Xem thêm list_liked_repos().

list_repo_refs

< >

( repo_id: strrepo_type: str | None = Noneinclude_pull_requests: bool = Falsetoken: str | bool | None = None ) → GitRefs

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • repo_type (str, tùy chọn) — Đặt thành "dataset", "space" hoặc "kernel" nếu liệt kê refs từ một dataset, một Space hoặc một Kernel, None hoặc "model" nếu liệt kê từ một model. Mặc định là None.
  • include_pull_requests (bool, tùy chọn) — Có bao gồm các refs từ pull request trong danh sách hay không. Mặc định là False.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

GitRefs

đối tượng chứa tất cả thông tin về các nhánh và thẻ cho một kho trên Hub.

Lấy danh sách các refs của một kho (repo) cho trước (cả tags và branches).

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.list_repo_refs("gpt2")
GitRefs(branches=[GitRefInfo(name='main', ref='refs/heads/main', target_commit='e7da7f221d5bf496a48136c0cd264e630fe9fcc8')], converts=[], tags=[])

>>> api.list_repo_refs("bigcode/the-stack", repo_type='dataset')
GitRefs(
    branches=[
        GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
        GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
    ],
    converts=[],
    tags=[
        GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
    ]
)

list_repo_tree

< >

( repo_id: strpath_in_repo: str | None = Nonerecursive: bool = Falseexpand: bool = Falserevision: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None ) → Iterable[Union[RepoFile, RepoFolder]]

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • path_in_repo (str, tùy chọn) — Đường dẫn tương đối của cây (thư mục) trong kho, ví dụ: "checkpoints/1fec34a/results". Mặc định sẽ là cây (thư mục) gốc của kho.
  • recursive (bool, tùy chọn, mặc định là False) — Liệt kê các tệp và thư mục của cây một cách đệ quy hay không.
  • expand (bool, tùy chọn, mặc định là False) — Có nên lấy thêm thông tin về các tệp và thư mục của cây (ví dụ: commit gần nhất và kết quả quét bảo mật của các tệp) hay không. Thao tác này tốn kém hơn cho máy chủ nên chỉ trả về 50 kết quả mỗi trang (thay vì 1000). Vì phân trang được triển khai trong huggingface_hub, điều này là minh bạch với bạn ngoại trừ thời gian cần thiết để nhận được kết quả.
  • revision (str, tùy chọn) — Phiên bản của kho chứa mà bạn muốn lấy cây. Mặc định là nhánh "main".
  • repo_type (str, tùy chọn) — Loại kho cần lấy cây ("model", "dataset", "space" hoặc "kernel"). Mặc định là "model".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[Union[RepoFile, RepoFolder]]

Thông tin về các tệp và thư mục của cây, dưới dạng một đối tượng lặp được của các đối tượng RepoFile và RepoFolder. Thứ tự của các tệp và thư mục không được đảm bảo.

Gây ra

RepositoryNotFoundError hoặc RevisionNotFoundError hoặc ~utils.RemoteEntryNotFoundError

  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho là riêng tư nhưng chưa xác thực hoặc kho không tồn tại.
  • RevisionNotFoundError — Nếu không tìm thấy revision (lỗi 404) trên repo.
  • ~utils.RemoteEntryNotFoundError — Nếu cây (thư mục) không tồn tại (lỗi 404) trên kho.

Liệt kê các tệp và thư mục trong cây kho và lấy thông tin về chúng.

Ví dụ:

Lấy thông tin về cây của một kho.

>>> from huggingface_hub import list_repo_tree
>>> repo_tree = list_repo_tree("lysandre/arxiv-nlp")
>>> repo_tree
<generator object HfApi.list_repo_tree at 0x7fa4088e1ac0>
>>> list(repo_tree)
[
    RepoFile(path='.gitattributes', size=391, blob_id='ae8c63daedbd4206d7d40126955d4e6ab1c80f8f', lfs=None, last_commit=None, security=None),
    RepoFile(path='README.md', size=391, blob_id='43bd404b159de6fba7c2f4d3264347668d43af25', lfs=None, last_commit=None, security=None),
    RepoFile(path='config.json', size=554, blob_id='2f9618c3a19b9a61add74f70bfb121335aeef666', lfs=None, last_commit=None, security=None),
    RepoFile(
        path='flax_model.msgpack', size=497764107, blob_id='8095a62ccb4d806da7666fcda07467e2d150218e',
        lfs={'size': 497764107, 'sha256': 'd88b0d6a6ff9c3f8151f9d3228f57092aaea997f09af009eefd7373a77b5abb9', 'pointer_size': 134}, last_commit=None, security=None
    ),
    RepoFile(path='merges.txt', size=456318, blob_id='226b0752cac7789c48f0cb3ec53eda48b7be36cc', lfs=None, last_commit=None, security=None),
    RepoFile(
        path='pytorch_model.bin', size=548123560, blob_id='64eaa9c526867e404b68f2c5d66fd78e27026523',
        lfs={'size': 548123560, 'sha256': '9be78edb5b928eba33aa88f431551348f7466ba9f5ef3daf1d552398722a5436', 'pointer_size': 134}, last_commit=None, security=None
    ),
    RepoFile(path='vocab.json', size=898669, blob_id='b00361fece0387ca34b4b8b8539ed830d644dbeb', lfs=None, last_commit=None, security=None)]
]

Lấy thêm thông tin về cây của kho (cam kết cuối cùng và kết quả quét bảo mật của các tệp)

>>> from huggingface_hub import list_repo_tree
>>> repo_tree = list_repo_tree("prompthero/openjourney-v4", expand=True)
>>> list(repo_tree)
[
    RepoFolder(
        path='feature_extractor',
        tree_id='aa536c4ea18073388b5b0bc791057a7296a00398',
        last_commit={
            'oid': '47b62b20b20e06b9de610e840282b7e6c3d51190',
            'title': 'Upload diffusers weights (#48)',
            'date': datetime.datetime(2023, 3, 21, 9, 5, 27, tzinfo=datetime.timezone.utc)
        }
    ),
    RepoFolder(
        path='safety_checker',
        tree_id='65aef9d787e5557373fdf714d6c34d4fcdd70440',
        last_commit={
            'oid': '47b62b20b20e06b9de610e840282b7e6c3d51190',
            'title': 'Upload diffusers weights (#48)',
            'date': datetime.datetime(2023, 3, 21, 9, 5, 27, tzinfo=datetime.timezone.utc)
        }
    ),
    RepoFile(
        path='model_index.json',
        size=582,
        blob_id='d3d7c1e8c3e78eeb1640b8e2041ee256e24c9ee1',
        lfs=None,
        last_commit={
            'oid': 'b195ed2d503f3eb29637050a886d77bd81d35f0e',
            'title': 'Fix deprecation warning by changing `CLIPFeatureExtractor` to `CLIPImageProcessor`. (#54)',
            'date': datetime.datetime(2023, 5, 15, 21, 41, 59, tzinfo=datetime.timezone.utc)
        },
        security={
            'safe': True,
            'av_scan': {'virusFound': False, 'virusNames': None},
            'pickle_import_scan': None
        }
    )
    ...
]

list_scheduled_jobs

< >

( labels: dict[str, str] | None = Nonetimeout: int | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → list[ScheduledJobInfo]

Tham số

  • labels (dict[str, str], tùy chọn) — Chỉ trả về các Job đã được lên lịch có tất cả các nhãn key=value được cho, ví dụ {"env": "prod", "team": "ml"}.
  • timeout (float, tùy chọn) — Có nên đặt thời gian chờ cho yêu cầu đến Hub hay không.
  • namespace (str, optional) — Namespace mà từ đó nó liệt kê các job. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Trả về

list[ScheduledJobInfo]

một danh sách các đối tượng ScheduledJobInfo.

Liệt kê các Job tính toán đã lên lịch trên hạ tầng Hugging Face.

list_space_templates

< >

( token: str | bool | None = None ) → list[SpaceTemplate]

Tham số

Trả về

list[SpaceTemplate]

Danh sách các mẫu Space có sẵn.

Liệt kê các mẫu Space chính thức có sẵn trên Hub.

repo_id của một template được trả về (hoặc name ngắn của nó) có thể được truyền dưới dạng space_template cho HfApi.create_repo() để khởi tạo một Space mới từ template đó.

Ví dụ:

>>> from huggingface_hub import list_space_templates
>>> templates = list_space_templates()
>>> templates[0]
SpaceTemplate(name='Streamlit', repo_id='streamlit/streamlit-template-space', sdk='docker', preferred_private=False)

list_spaces

< >

( filter: str | Iterable[str] | None = Noneauthor: str | None = Nonesearch: str | None = Nonedatasets: str | Iterable[str] | None = Nonemodels: str | Iterable[str] | None = Nonelinked: bool = Falsesort: SpaceSort_T | None = Nonelimit: int | None = Noneexpand: list[ExpandSpaceProperty_T] | None = Nonefull: bool | None = Nonetoken: bool | str | None = None ) → Iterable[SpaceInfo]

Tham số

  • filter (str hoặc Iterable, tùy chọn) — Một thẻ dạng chuỗi hoặc danh sách các thẻ có thể được sử dụng để xác định các Spaces trên Hub.
  • author (str, tùy chọn) — Chuỗi nhận diện tác giả của các Spaces được trả về.
  • search (str, tuỳ chọn) — Chuỗi sẽ được chứa trong các Spaces được trả về.
  • datasets (str hoặc Iterable, tùy chọn) — Có nên trả về các Spaces sử dụng một dataset hay không. Tên của một dataset cụ thể có thể được truyền dưới dạng chuỗi.
  • models (str hoặc Iterable, tùy chọn) — Có nên trả về các Spaces sử dụng một model hay không. Tên của một model cụ thể có thể được truyền dưới dạng chuỗi.
  • linked (bool, tùy chọn) — Có nên trả về các Spaces sử dụng mô hình hoặc bộ dữ liệu hay không.
  • sort (SpaceSort_T, tuỳ chọn) — Khóa để sắp xếp các space kết quả. Các giá trị có thể là “created_at”, “last_modified”, “likes” và “trending_score”.
  • limit (int, tùy chọn) — Giới hạn số lượng Spaces được lấy. Để tùy chọn này là None để lấy tất cả các Spaces.
  • expand (list[ExpandSpaceProperty_T], tùy chọn) — Danh sách các thuộc tính cần trả về trong phản hồi. Khi được sử dụng, chỉ các thuộc tính trong danh sách sẽ được trả về. Tham số này không thể được sử dụng nếu full được truyền vào. Các giá trị có thể là "author", "cardData", "datasets", "disabled", "lastModified", "createdAt", "likes", "models", "private", "region", "runtime", "sdk", "siblings", "sha", "subdomain", "tags", "trendingScore", "usedStorage", và "resourceGroup".
  • full (bool, tùy chọn) — Có nên lấy toàn bộ dữ liệu Spaces, bao gồm các trường last_modified, siblings và card_data hay không.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[SpaceInfo]

một iterable các đối tượng huggingface_hub.hf_api.SpaceInfo.

Liệt kê các space được lưu trữ trên Huggingface Hub, dựa trên một số bộ lọc.

list_spaces_hardware

< >

( token: bool | str | None = None ) → list[JobHardwareInfo]

Trả về

list[JobHardwareInfo]

Danh sách các cấu hình phần cứng khả dụng.

Liệt kê các tùy chọn phần cứng khả dụng cho Spaces.

Ví dụ:

>>> from huggingface_hub import list_spaces_hardware
>>> hardware_list = list_spaces_hardware()
>>> hardware_list[0]
JobHardwareInfo(name='cpu-basic', pretty_name='CPU Basic', cpu='2 vCPU', ram='16 GB', ...)
>>> hardware_list[0].name
'cpu-basic'

list_user_followers

< >

( username: strtoken: bool | str | None = None ) → Iterable[User]

Tham số

  • username (str) — Tên người dùng của người dùng cần lấy danh sách người theo dõi.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[User]

Danh sách các đối tượng User là người theo dõi của người dùng.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Nếu người dùng không tồn tại trên Hub.

Lấy danh sách người theo dõi của một người dùng trên Hub.

list_user_following

< >

( username: strtoken: bool | str | None = None ) → Iterable[User]

Tham số

  • username (str) — Tên người dùng của người dùng cần lấy danh sách người dùng mà họ đang theo dõi.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[User]

Danh sách các đối tượng User với các người dùng được người dùng đó theo dõi.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Nếu người dùng không tồn tại trên Hub.

Lấy danh sách người dùng được theo dõi bởi một người dùng trên Hub.

list_user_repos

< >

( namespace: str | None = Nonetoken: bool | str | None = None ) → Iterable[RepoStorageInfo]

Tham số

  • namespace (str, tùy chọn) — Tên tổ chức. Nếu không được cung cấp, sẽ liệt kê các kho của người dùng đã xác thực.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Mặc định là token được lưu cục bộ.

Trả về

Iterable[RepoStorageInfo]

Một iterable gồm các đối tượng RepoStorageInfo.

Liệt kê tất cả các kho (mô hình, bộ dữ liệu, spaces, buckets) của một người dùng hoặc tổ chức kèm thông tin lưu trữ.

Sử dụng endpoint /api/settings/repositories cho người dùng đã xác thực hoặc /api/organizations/{namespace}/settings/repositories cho một tổ chức.

Ví dụ:

>>> from huggingface_hub import list_user_repos

>>> repos = list(list_user_repos())
>>> repos[0]
RepoStorageInfo(id='username/my-model', type='model', ...)

>>> # List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))

list_webhooks

< >

( token: bool | str | None = None ) → list[WebhookInfo]

Tham số

Trả về

list[WebhookInfo]

Danh sách các đối tượng thông tin webhook.

Liệt kê tất cả các webhook đã cấu hình.

Ví dụ:

>>> from huggingface_hub import list_webhooks
>>> webhooks = list_webhooks()
>>> len(webhooks)
2
>>> webhooks[0]
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    secret="my-secret",
    domains=["repo", "discussion"],
    disabled=False,
)

merge_pull_request

< >

( repo_id: strdiscussion_num: inttoken: bool | str | None = Nonecomment: str | None = Nonerepo_type: str | None = None ) → DiscussionStatusChange

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • discussion_num (int) — Số thứ tự của Discussion hoặc Pull Request. Phải là một số nguyên dương.
  • comment (str, tùy chọn) — Một chú thích tùy chọn để đăng kèm theo thay đổi trạng thái.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

DiscussionStatusChange

sự kiện thay đổi trạng thái

Gộp một Pull Request.

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

model_info

< >

( repo_id: strrevision: str | None = Nonetimeout: float | None = NonesecurityStatus: bool | None = Nonefiles_metadata: bool = Falseexpand: list[ExpandModelProperty_T] | None = Nonetoken: bool | str | None = None ) → huggingface_hub.hf_api.ModelInfo

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • revision (str, tùy chọn) — Phiên bản của kho lưu trữ mô hình để lấy thông tin.
  • timeout (float, tùy chọn) — Có nên đặt thời gian chờ cho yêu cầu đến Hub hay không.
  • securityStatus (bool, tùy chọn) — Có nên lấy trạng thái bảo mật từ kho lưu trữ mô hình hay không. Trạng thái bảo mật sẽ được trả về trong trường security_repo_status.
  • files_metadata (bool, tùy chọn) — Có lấy hay không lấy metadata cho các tệp trong kho (kích thước, metadata LFS, v.v.). Mặc định là False.
  • expand (list[ExpandModelProperty_T], tuỳ chọn) — Danh sách các thuộc tính cần trả về trong phản hồi. Khi được sử dụng, chỉ các thuộc tính trong danh sách sẽ được trả về. Tham số này không thể được sử dụng nếu securityStatus hoặc files_metadata được truyền vào. Các giá trị có thể là "author", "baseModels", "cardData", "childrenModelCount", "config", "createdAt", "disabled", "downloads", "downloadsAllTime", "evalResults", "gated", "gguf", "inference", "inferenceProviderMapping", "lastModified", "library_name", "likes", "mask_token", "model-index", "pipeline_tag", "private", "safetensors", "sha", "siblings", "spaces", "tags", "transformersInfo", "trendingScore", "widgetData", "usedStorage", và "resourceGroup".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

huggingface_hub.hf_api.ModelInfo

Thông tin kho lưu trữ mô hình.

Lấy thông tin về một mô hình cụ thể trên huggingface.co

Model có thể là private nếu bạn truyền vào một token hợp lệ hoặc đã đăng nhập.

Gây ra các lỗi sau:

  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.
  • RevisionNotFoundError Nếu không tìm thấy revision cần tải xuống.

move_bucket

< >

( from_id: strto_id: strtoken: bool | str | None = None )

Tham số

  • from_id (str) — Một namespace (người dùng hoặc tổ chức) và tên bucket được phân tách bởi /. Định danh bucket gốc (ví dụ: "username/my-bucket").
  • to_id (str) — Một namespace (người dùng hoặc tổ chức) và tên bucket được phân tách bởi /. Định danh bucket cuối cùng (ví dụ: "username/new-bucket-name" hoặc "organization/my-bucket").
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

BucketNotFoundError

  • BucketNotFoundError — Nếu không tìm thấy bucket nguồn. Điều này có thể do bucket không tồn tại, hoặc do bucket được đặt ở chế độ private và bạn không có quyền truy cập.

Di chuyển một bucket từ “namespace1/repo_name1” sang “namespace2/repo_name2”

Lưu ý rằng có một số hạn chế nhất định. Để biết thêm thông tin về việc di chuyển kho lưu trữ, hãy xem https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo.

Ví dụ:

>>> from huggingface_hub import move_bucket

>>> # Rename a bucket within the same namespace
>>> move_bucket(from_id="username/old-name", to_id="username/new-name")

>>> # Transfer a bucket to an organization
>>> move_bucket(from_id="username/my-bucket", to_id="my-org/my-bucket")

move_repo

< >

( from_id: strto_id: strrepo_type: str | None = Nonetoken: str | bool | None = None )

Tham số

  • from_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /. Định danh kho gốc.
  • to_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /. Định danh kho cuối cùng.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Chuyển một kho từ namespace1/repo_name1 sang namespace2/repo_name2

Lưu ý rằng có một số hạn chế nhất định. Để biết thêm thông tin về việc di chuyển kho lưu trữ, hãy xem https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo.

Gây ra các lỗi sau:

  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

paper_info

< >

( id: str ) → PaperInfo

Tham số

  • id (str, tùy chọn) — ArXiv id của bài báo.

Trả về

PaperInfo

Một đối tượng PaperInfo.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Nếu bài báo không tồn tại trên Hub.

Lấy thông tin về một bài báo trên Hub.

parse_safetensors_file_metadata

< >

( repo_id: strfilename: strrepo_type: str | None = Nonerevision: str | None = Nonetoken: bool | str | None = Nonetimeout: float | None = 10 ) → SafetensorsFileMetadata

Tham số

  • repo_id (str) — Tên người dùng hoặc tên tổ chức và tên kho, phân tách bằng /.
  • filename (str) — Tên của tệp trong kho.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tệp nằm trong một dataset hoặc space, None hoặc "model" nếu nằm trong một model. Mặc định là None.
  • revision (str, tùy chọn) — Phiên bản git để lấy tệp. Có thể là tên nhánh, thẻ hoặc mã băm commit. Mặc định là đầu của nhánh "main".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • timeout (float, tùy chọn, mặc định là 10) — Số giây chờ máy chủ gửi dữ liệu trước khi từ bỏ. Đặt thành None để tắt timeout (không khuyến nghị, vì một kết nối bị treo có thể khiến cuộc gọi bị treo vô thời hạn).

Trả về

SafetensorsFileMetadata

thông tin liên quan đến tệp safetensors.

Gây ra

NotASafetensorsRepoError hoặc SafetensorsParsingError

  • NotASafetensorsRepoError — Nếu repo không phải là repo safetensors, tức là không có file model.safetensors hoặc model.safetensors.index.json.
  • SafetensorsParsingError — Nếu không thể phân tích đúng phần đầu (header) của tệp safetensors.

Phân tích metadata từ một tệp safetensors trên Hub.

Để phân tích metadata từ tất cả các tệp safetensors trong một repo cùng lúc, hãy sử dụng get_safetensors_metadata().

Để biết thêm chi tiết về định dạng safetensors, hãy xem https://huggingface.co/docs/safetensors/index#format.

pause_inference_endpoint

< >

( name: strnamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint

Tham số

  • name (str) — Tên của Inference Endpoint cần tạm dừng.
  • namespace (str, optional) — Namespace chứa Inference Endpoint. Mặc định là người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

InferenceEndpoint

thông tin về Inference Endpoint đang tạm dừng.

Tạm dừng một Inference Endpoint.

Inference Endpoint ở trạng thái tạm dừng sẽ không bị tính phí. Bạn có thể tiếp tục sử dụng nó bất cứ lúc nào bằng resume_inference_endpoint(). Điều này khác với việc thu nhỏ Inference Endpoint về không bằng scale_to_zero_inference_endpoint(), khi đó nó sẽ được khởi động lại tự động khi có yêu cầu được gửi đến.

Để tiện lợi, bạn cũng có thể tạm dừng một Inference Endpoint bằng cách sử dụng pause_inference_endpoint().

pause_space

< >

( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime

Tham số

  • repo_id (str) — ID của Space cần tạm dừng. Ví dụ: "Salesforce/BLIP2".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

SpaceRuntime

Thông tin thời gian chạy về Space của bạn, bao gồm stage=PAUSED và phần cứng được yêu cầu.

Gây ra

RepositoryNotFoundError hoặc HfHubHTTPError hoặc BadRequestError

  • RepositoryNotFoundError — Nếu Space của bạn không được tìm thấy (lỗi 404). Khả năng cao là repo_id sai hoặc Space của bạn là riêng tư nhưng bạn chưa xác thực.
  • HfHubHTTPError — 403 Forbidden: chỉ chủ sở hữu của một Space mới có thể tạm dừng nó. Nếu bạn muốn quản lý một Space mà bạn không sở hữu, hãy yêu cầu chủ sở hữu bằng cách mở một Discussion hoặc sao chép Space đó.
  • BadRequestError — Nếu Space của bạn là một Space tĩnh. Các Space tĩnh luôn chạy và không bao giờ bị tính phí. Nếu bạn muốn ẩn một Space tĩnh, bạn có thể đặt nó ở chế độ riêng tư.

Tạm dừng Space của bạn.

Space ở trạng thái tạm dừng sẽ ngừng thực thi cho đến khi chủ sở hữu khởi động lại thủ công. Điều này khác với trạng thái ngủ mà các Space miễn phí chuyển sang sau 48 giờ không hoạt động. Thời gian tạm dừng không bị tính phí vào tài khoản của bạn, bất kể phần cứng bạn đã chọn. Để khởi động lại Space của bạn, hãy sử dụng restart_space() và truy cập trang cài đặt Space của bạn.

Để biết thêm chi tiết, vui lòng truy cập tài liệu.

permanently_delete_lfs_files

< >

( repo_id: strlfs_files: Iterable[LFSFileInfo]rewrite_history: bool = Truerepo_type: str | None = Nonetoken: bool | str | None = None )

Tham số

  • repo_id (str) — Kho lưu trữ mà bạn đang liệt kê các tệp LFS.
  • lfs_files (Iterable[LFSFileInfo]) — Một iterable gồm các mục LFSFileInfo để xóa vĩnh viễn khỏi kho. Sử dụng list_lfs_files() để liệt kê tất cả các tệp LFS từ một kho.
  • rewrite_history (bool, tùy chọn, mặc định là True) — Có nên viết lại lịch sử của kho lưu trữ để xóa các con trỏ tệp tham chiếu đến các tệp LFS đã bị xóa hay không (được khuyến nghị).
  • repo_type (str, tùy chọn) — Loại kho. Đặt thành "dataset" hoặc "space" nếu liệt kê từ một dataset hoặc space, None hoặc "model" nếu liệt kê từ một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Xóa vĩnh viễn các tệp LFS khỏi một kho trên Hub.

Đây là một thao tác vĩnh viễn sẽ ảnh hưởng đến tất cả các commit tham chiếu đến các tệp đã bị xóa và có thể làm hỏng kho lưu trữ của bạn. Đây là một thao tác không thể hoàn tác. Chỉ sử dụng khi bạn thực sự hiểu rõ những gì mình đang làm.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")

# Filter files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))

# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)

preupload_lfs_files

< >

( repo_id: stradditions: Iterable[CommitOperationAdd]token: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecreate_pr: bool | None = Nonenum_threads: int = 5free_memory: bool = Truegitignore_content: str | None = None )

Tham số

  • repo_id (str) — Kho lưu trữ mà bạn sẽ commit các tệp vào, ví dụ: "username/custom_transformers".
  • additions (Iterable của CommitOperationAdd) — Danh sách các tệp cần tải lên. Cảnh báo: các đối tượng trong danh sách này sẽ bị thay đổi để bao gồm thông tin liên quan đến việc tải lên. Không tái sử dụng cùng các đối tượng cho nhiều lần commit.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Loại kho cần tải lên (ví dụ: "model" -mặc định-, "dataset", "space" hoặc "kernel").
  • revision (str, tùy chọn) — Phiên bản git để commit từ. Mặc định là đầu của nhánh "main".
  • create_pr (boolean, tùy chọn) — Liệu bạn có dự định tạo một Pull Request với commit đó hay không. Mặc định là False.
  • num_threads (int, tùy chọn) — Số lượng luồng đồng thời để tải tệp lên. Mặc định là 5. Đặt thành 2 nghĩa là tối đa 2 tệp sẽ được tải lên đồng thời.
  • free_memory (bool, tùy chọn, mặc định là True) — Nếu True, thuộc tính path_or_fileobj của mỗi CommitOperationAdd sẽ được thay thế bằng một đối tượng bytes rỗng sau khi tải lên để tiết kiệm bộ nhớ. Đặt thành False nếu bạn cần tái sử dụng các đối tượng thao tác bên ngoài một cuộc gọi create_commit() tiếp theo.
  • gitignore_content (str, tùy chọn) — Nội dung của tệp .gitignore để biết tệp nào nên được bỏ qua. Thứ tự ưu tiên là trước tiên kiểm tra xem gitignore_content có được truyền vào không, sau đó kiểm tra xem tệp .gitignore có hiện diện trong danh sách các tệp cần commit hay không, và cuối cùng mặc định dùng tệp .gitignore đã được lưu trên Hub (nếu có).

Tải trước các tệp LFS lên S3 để chuẩn bị cho một commit trong tương lai.

Phương pháp này hữu ích nếu bạn đang tạo các tệp để tải lên theo thời gian thực và không muốn lưu trữ chúng trong bộ nhớ trước khi tải lên tất cả cùng lúc.

Đây là phương pháp dành cho người dùng nâng cao. Bạn không cần gọi trực tiếp phương pháp này để thực hiện một commit thông thường. Hãy dùng create_commit() trực tiếp thay vào đó.

Các thao tác commit sẽ bị thay đổi trong quá trình xử lý. Cụ thể, path_or_fileobj được đính kèm sẽ bị xóa sau khi tải lên để tiết kiệm bộ nhớ (và được thay thế bằng một đối tượng bytes rỗng). Không tái sử dụng các đối tượng này, ngoại trừ việc truyền chúng vào create_commit(). Nếu bạn không muốn xóa nội dung đính kèm khỏi đối tượng thao tác commit, hãy truyền free_memory=False.

Ví dụ:

>>> from huggingface_hub import CommitOperationAdd, preupload_lfs_files, create_commit, create_repo

>>> repo_id = create_repo("test_preupload").repo_id

# Generate and preupload LFS files one by one
>>> operations = [] # List of all `CommitOperationAdd` objects that will be generated
>>> for i in range(5):
...     content = ... # generate binary content
...     addition = CommitOperationAdd(path_in_repo=f"shard_{i}_of_5.bin", path_or_fileobj=content)
...     preupload_lfs_files(repo_id, additions=[addition]) # upload + free memory
...     operations.append(addition)

# Create commit
>>> create_commit(repo_id, operations=operations, commit_message="Commit all shards")

read_paper

< >

( id: str ) → str

Tham số

  • id (str) — ArXiv id của bài báo.

Trả về

str

Nội dung trang bài báo dưới dạng markdown.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Nếu bài báo không tồn tại trên Hub.

Lấy nội dung markdown của một trang bài báo trên Hub.

reject_access_request

< >

( repo_id: struser: str | None = Nonerequest_id: str | None = Nonerepo_type: str | None = Nonerejection_reason: str | Nonetoken: bool | str | None = None )

Tham số

  • repo_id (str) — ID của kho cần từ chối yêu cầu truy cập.
  • user (str, tùy chọn) — Tên người dùng của người dùng mà yêu cầu truy cập cần bị từ chối. Phải cung cấp đúng một trong user hoặc request_id.
  • request_id (str, tùy chọn) — ID của yêu cầu truy cập cần từ chối (xem AccessRequest). Bắt buộc khi repo được cấu hình không chia sẻ tên người dùng của người yêu cầu. Phải cung cấp đúng một trong user hoặc request_id.
  • repo_type (str, tùy chọn) — Loại repo để từ chối yêu cầu truy cập. Phải là một trong model, dataset hoặc space. Mặc định là model.
  • rejection_reason (str, tùy chọn) — Lý do từ chối tùy chọn sẽ hiển thị cho người dùng (tối đa 200 ký tự).
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 nếu kho không được bảo vệ.
  • HfHubHTTPError — HTTP 403 nếu bạn chỉ có quyền truy cập chỉ đọc vào kho. Điều này có thể xảy ra nếu bạn không có vai trò write hoặc admin trong tổ chức mà kho đó thuộc về, hoặc nếu bạn đã truyền một token read.
  • HfHubHTTPError — HTTP 404 nếu người dùng không tồn tại trên Hub.
  • HfHubHTTPError — HTTP 404 nếu không tìm thấy yêu cầu truy cập của người dùng.
  • HfHubHTTPError — HTTP 404 nếu yêu cầu truy cập của người dùng đã nằm trong danh sách bị từ chối.

Từ chối yêu cầu truy cập từ một người dùng đối với một kho có kiểm soát (gated repo) cụ thể.

Yêu cầu bị từ chối sẽ được đưa vào danh sách bị từ chối. Người dùng không thể tải xuống bất kỳ tệp nào của kho. Các yêu cầu bị từ chối có thể được chấp nhận hoặc hủy vào bất kỳ lúc nào bằng accept_access_request() và cancel_access_request(). Yêu cầu bị hủy sẽ quay lại danh sách chờ trong khi yêu cầu được chấp nhận sẽ được đưa vào danh sách đã chấp nhận.

Để biết thêm thông tin về các kho có kiểm soát, hãy xem https://huggingface.co/docs/hub/models-gated.

rename_discussion

< >

( repo_id: strdiscussion_num: intnew_title: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionTitleChange

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • discussion_num (int) — Số thứ tự của Discussion hoặc Pull Request. Phải là một số nguyên dương.
  • new_title (str) — Tiêu đề mới cho cuộc thảo luận
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải lên một dataset hoặc space, None hoặc "model" nếu tải lên một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

DiscussionTitleChange

sự kiện thay đổi tiêu đề

Đổi tên một Thảo luận.

Ví dụ:

>>> new_title = "New title, fixing a typo"
>>> HfApi().rename_discussion(
...     repo_id="username/repo_name",
...     discussion_num=34,
...     new_title=new_title
... )
# DiscussionTitleChange(id='deadbeef0000000', type='title-change', ...)

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

repo_exists

< >

( repo_id: strrepo_type: str | None = Nonetoken: str | bool | None = None )

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu lấy thông tin kho từ một dataset hoặc một space, None hoặc "model" nếu lấy thông tin kho từ một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Kiểm tra xem một kho lưu trữ có tồn tại trên Hugging Face Hub hay không.

Ví dụ:

>>> from huggingface_hub import repo_exists
>>> repo_exists("google/gemma-7b")
True
>>> repo_exists("google/not-a-repo")
False

repo_info

< >

( repo_id: strrevision: str | None = Nonerepo_type: str | None = Nonetimeout: float | None = Nonefiles_metadata: bool = Falseexpand: ExpandModelProperty_T | ExpandDatasetProperty_T | ExpandSpaceProperty_T | None = Nonetoken: bool | str | None = None ) → Union[SpaceInfo, DatasetInfo, ModelInfo]

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • revision (str, tùy chọn) — Phiên bản của kho chứa mà từ đó lấy thông tin.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu lấy thông tin kho từ một dataset hoặc một space, None hoặc "model" nếu lấy thông tin kho từ một model. Mặc định là None.
  • timeout (float, tùy chọn) — Có nên đặt thời gian chờ cho yêu cầu đến Hub hay không.
  • expand (ExpandModelProperty_T hoặc ExpandDatasetProperty_T hoặc ExpandSpaceProperty_T, tuỳ chọn) — Danh sách các thuộc tính cần trả về trong phản hồi. Khi được sử dụng, chỉ các thuộc tính trong danh sách sẽ được trả về. Tham số này không thể được sử dụng nếu files_metadata được truyền vào. Để xem danh sách đầy đủ các thuộc tính khả dụng, hãy xem model_info(), dataset_info() hoặc space_info().
  • files_metadata (bool, tùy chọn) — Có lấy hay không lấy metadata cho các tệp trong kho (kích thước, metadata LFS, v.v.). Mặc định là False.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Union[SpaceInfo, DatasetInfo, ModelInfo]

Thông tin kho lưu trữ, dưới dạng đối tượng huggingface_hub.hf_api.DatasetInfo, huggingface_hub.hf_api.ModelInfo hoặc huggingface_hub.hf_api.SpaceInfo.

Lấy đối tượng thông tin cho một kho có loại đã cho.

Gây ra các lỗi sau:

  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.
  • RevisionNotFoundError Nếu không tìm thấy revision cần tải xuống.

request_space_hardware

< >

( repo_id: strhardware: SpaceHardwaretoken: bool | str | None = Nonesleep_time: int | None = None ) → SpaceRuntime

Tham số

  • repo_id (str) — ID của kho cần cập nhật. Ví dụ: "bigcode/in-the-stack".
  • hardware (str hoặc SpaceHardware) — Phần cứng để chạy Space. Ví dụ: "t4-medium".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • sleep_time (int, tùy chọn) — Số giây không hoạt động cần chờ trước khi một Space được đưa vào trạng thái ngủ. Đặt thành -1 nếu bạn không muốn Space của bạn ngủ (hành vi mặc định cho phần cứng đã nâng cấp). Đối với phần cứng miễn phí, bạn không thể cấu hình thời gian ngủ (giá trị được cố định ở mức 48 giờ không hoạt động). Xem https://huggingface.co/docs/hub/spaces-gpus#sleep-time để biết thêm chi tiết.

Trả về

SpaceRuntime

Thông tin thời gian chạy về một Space, bao gồm giai đoạn và phần cứng của Space.

Yêu cầu phần cứng mới cho một Space.

Bạn cũng có thể yêu cầu phần cứng trực tiếp khi tạo kho Space! Xem create_repo() để biết thêm chi tiết.

rerun_job

< >

( job_id: strnamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo

Tham số

  • job_id (str) — ID của Job cần chạy lại.
  • namespace (str, không bắt buộc) — Namespace của Job. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Token truy cập của người dùng. Mặc định là token được lưu cục bộ.

Trả về

JobInfo

Job vừa được khởi động.

Chạy một Job mới bằng cách sử dụng spec của Job hiện có, bao gồm các cài đặt retry và resource của nó.

resolve_revision

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | Path | None = Nonelocal_files_only: bool = Falsetoken: bool | str | None = None ) → ResolvedRevision

Tham số

  • repo_id (str) — Tên người dùng hoặc tên tổ chức và tên kho, phân tách bằng /.
  • repo_type (str, tùy chọn) — Đặt thành "dataset", "space" hoặc "kernel" nếu repo là dataset, space hoặc kernel repo, None hoặc "model" nếu là model. Mặc định là None.
  • revision (str, tùy chọn) — Phiên bản cần phân giải. Có thể là tên nhánh, một tag, một PR ref hoặc một commit hash. Mặc định là nhánh mặc định. Nếu một ResolvedRevision được truyền vào, nó sẽ được trả về nguyên vẹn - trừ khi nó được phân giải đối với một repo khác, trong trường hợp đó phiên bản ban đầu được yêu cầu sẽ được phân giải lại.
  • cache_dir (str, Path, tùy chọn) — Đường dẫn đến thư mục lưu trữ các tệp được lưu đệm. Mặc định là giá trị của HF_HUB_CACHE.
  • local_files_only (bool, tùy chọn, mặc định là False) — Nếu True, chỉ giải quyết revision từ bộ nhớ đệm cục bộ, không liên hệ với Hub.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

ResolvedRevision

Một lớp con của str lưu trữ cả phiên bản được yêu cầu và mã băm của commit mà nó trỏ đến.

Gây ra

RevisionResolutionError hoặc RevisionNotFoundError hoặc RepositoryNotFoundError

  • RevisionResolutionError — Nếu không thể xác định revision: không thể kết nối với Hub và không có gì được lưu cục bộ.
  • RevisionNotFoundError — Nếu revision không tồn tại trên Hub.
  • RepositoryNotFoundError — Nếu không tìm thấy kho lưu trữ. Điều này có thể do kho không tồn tại, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

Giải quyết một phiên bản (nhánh, thẻ, tham chiếu PR) thành một băm commit.

Điều này dành cho các thư viện tải xuống và nạp nhiều thành phần của một repo riêng biệt (config, weights, tokenizer, …). Việc giải quyết revision một lần và truyền ResolvedRevision được trả về xung quanh đảm bảo rằng mọi cuộc gọi tiếp theo đều nhắm đến đúng commit đó, ngay cả khi repo được cập nhật trong thời gian đó. Nó cũng tiết kiệm các cuộc gọi HTTP, vì các lượt tải xuống được thực hiện bằng commit hash có thể được phục vụ từ bộ nhớ đệm cục bộ mà không cần liên hệ với Hub.

Bản ánh xạ revision -> commit hash được lưu đệm trên đĩa (trong thư mục refs/ của bộ đệm) theo cơ chế cố gắng hết sức. Nếu không thể kết nối đến Hub sau đó (chế độ ngoại tuyến, lỗi kết nối, hết thời gian chờ, Hub ngừng hoạt động, …), giá trị được lưu đệm sẽ được sử dụng làm phương án dự phòng.

Nếu bạn chỉ cần tải xuống một bản snapshot hoàn chỉnh của repo, một lệnh gọi duy nhất snapshot_download() là đủ và đã thực hiện đúng cách. resolve_revision chỉ hữu ích khi tải xuống các tệp riêng biệt.

Ví dụ:

>>> from huggingface_hub import hf_hub_download, resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')

# Pass it around: every download is pinned to the same commit
>>> config = hf_hub_download("openai-community/gpt2", "config.json", revision=revision)
>>> weights = hf_hub_download("openai-community/gpt2", "model.safetensors", revision=revision)

restart_space

< >

( repo_id: strtoken: bool | str | None = Nonefactory_reboot: bool = False ) → SpaceRuntime

Tham số

  • repo_id (str) — ID của Space cần khởi động lại. Ví dụ: "Salesforce/BLIP2".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • factory_reboot (bool, tùy chọn) — Nếu True, Space sẽ được xây dựng lại từ đầu mà không lưu trữ bộ nhớ đệm cho bất kỳ yêu cầu nào.

Trả về

SpaceRuntime

Thông tin thời gian chạy về Space của bạn.

Gây ra

RepositoryNotFoundError hoặc HfHubHTTPError hoặc BadRequestError

  • RepositoryNotFoundError — Nếu Space của bạn không được tìm thấy (lỗi 404). Khả năng cao là repo_id sai hoặc Space của bạn là riêng tư nhưng bạn chưa xác thực.
  • HfHubHTTPError — 403 Forbidden: chỉ chủ sở hữu của một Space mới có thể khởi động lại nó. Nếu bạn muốn khởi động lại một Space mà bạn không sở hữu, hãy yêu cầu chủ sở hữu bằng cách mở một Discussion hoặc sao chép Space đó.
  • BadRequestError — Nếu Space của bạn là một Space tĩnh. Các Space tĩnh luôn chạy và không bao giờ bị tính phí. Nếu bạn muốn ẩn một Space tĩnh, bạn có thể đặt nó ở chế độ riêng tư.

Khởi động lại Space của bạn.

Đây là cách duy nhất để khởi động lại một Space bằng lập trình nếu bạn đã đặt nó ở chế độ Tạm dừng (xem pause_space()). Bạn phải là chủ sở hữu của Space để khởi động lại nó. Nếu bạn đang sử dụng phần cứng nâng cấp, tài khoản của bạn sẽ bị tính phí ngay khi Space được khởi động lại. Bạn có thể kích hoạt việc khởi động lại bất kể trạng thái hiện tại của Space.

Để biết thêm chi tiết, vui lòng truy cập tài liệu.

resume_inference_endpoint

< >

( name: strnamespace: str | None = Nonerunning_ok: bool = Truetoken: bool | str | None = None ) → InferenceEndpoint

Tham số

  • name (str) — Tên của Inference Endpoint cần tiếp tục.
  • namespace (str, optional) — Namespace chứa Inference Endpoint. Mặc định là người dùng hiện tại.
  • running_ok (bool, tùy chọn) — Nếu True, phương thức sẽ không gây ra lỗi nếu Inference Endpoint đã đang chạy. Mặc định là True.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

InferenceEndpoint

thông tin về Inference Endpoint đã được khởi động lại.

Tiếp tục một Inference Endpoint.

Để tiện lợi, bạn cũng có thể khôi phục một Inference Endpoint bằng cách sử dụng InferenceEndpoint.resume().

resume_scheduled_job

< >

( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • scheduled_job_id (str) — ID của Job được lên lịch.
  • namespace (str, optional) — Namespace chứa Job được lên lịch. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Tiếp tục (hủy tạm dừng) một Job tính toán đã lên lịch trên hạ tầng của Hugging Face.

revision_exists

< >

( repo_id: strrevision: strrepo_type: str | None = Nonetoken: str | bool | None = None )

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • revision (str) — Phiên bản của kho cần kiểm tra.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu lấy thông tin kho từ một dataset hoặc một space, None hoặc "model" nếu lấy thông tin kho từ một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Kiểm tra xem một bản sửa đổi cụ thể có tồn tại trên một kho trên Hugging Face Hub hay không.

Ví dụ:

>>> from huggingface_hub import revision_exists
>>> revision_exists("google/gemma-7b", "float16")
True
>>> revision_exists("google/gemma-7b", "not-a-revision")
False

run_as_future

< >

( fn: Callable[..., R]*args**kwargs ) → Future

Tham số

  • fn (Callable) — Phương thức cần chạy ở nền.
  • *args, **kwargs — Các đối số mà phương thức sẽ được gọi với chúng.

Trả về

Future

một instance Future để lấy kết quả của tác vụ.

Chạy một phương thức ở nền và trả về một instance của Future.

Mục tiêu chính là chạy các phương thức mà không chặn luồng chính (ví dụ: đẩy dữ liệu trong quá trình huấn luyện). Các tác vụ nền được xếp hàng để duy trì thứ tự nhưng không được chạy song song. Nếu bạn cần tăng tốc các script của mình bằng cách song song hóa nhiều lời gọi tới API, bạn phải thiết lập và sử dụng riêng ThreadPoolExecutor của mình.

Lưu ý: Các phương thức được sử dụng nhiều nhất như upload_file(), upload_folder() và create_commit() có tham số run_as_future: bool để gọi chúng trực tiếp ở chế độ nền. Điều này tương đương với việc gọi api.run_as_future(...) trên chúng nhưng ngắn gọn hơn.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> future = api.run_as_future(api.whoami) # instant
>>> future.done()
False
>>> future.result() # wait until complete and return result
(...)
>>> future.done()
True

run_job

< >

( image: strcommand: list[str]env: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Nonessh: bool = Falsenetwork_group: str | None = Nonenetwork_aliases: list[str] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • image (str) — Ảnh Docker cần sử dụng. Ví dụ: "ubuntu", "python:3.12", "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel". Ví dụ với một ảnh từ một Space: "hf.co/spaces/lhoestq/duckdb".
  • command (list[str]) — Lệnh cần thực thi. Ví dụ: ["echo", "hello"].
  • env (dict[str, Any], tùy chọn) — Định nghĩa các biến môi trường cho Job.
  • secrets (dict[str, Any], tùy chọn) — Định nghĩa các biến môi trường bí mật cho Job.
  • flavor (str, tùy chọn) — Flavor cho phần cứng. Xem JobHardware để biết các giá trị có thể. Mặc định là "cpu-basic".
  • timeout (Union[int, float, str], tùy chọn) — Thời lượng tối đa cho Job: int với s (giây, mặc định), m (phút), h (giờ) hoặc d (ngày). Ví dụ: 300 hoặc "5m" cho 5 phút.
  • attempts (int, tùy chọn) — Số lần thử tối đa, bao gồm lần chạy ban đầu. Mặc định là 1. Ví dụ, 3 sẽ thử lại một Job thất bại tối đa 2 lần.
  • name (str, tùy chọn) — Tên cho Job. Được lưu dưới dạng nhãn name. Không thể truyền cùng với khóa name trong labels. Tên không nhất thiết phải duy nhất. Mặc định là tên được suy ra từ image và command (kèm hậu tố hash ngắn).
  • labels (dict[str, str], tùy chọn) — Nhãn cần gắn cho tác vụ (các cặp khóa-giá trị).
  • volumes (list[Volume], tùy chọn) — Các Hugging Face Buckets hoặc Repos để gắn làm volumes trong container của job. Mỗi volume là một Volume có type ("bucket", "model", "dataset" hoặc "space"), source (ví dụ "username/my-bucket") và mount_path (ví dụ "/data").
  • expose (list[int], tuỳ chọn) — Các cổng container cần mở qua jobs proxy. Mỗi cổng được liệt kê sẽ có thể truy cập trên tên miền jobs công khai (ví dụ: https://<job_id>--8000.hf.jobs). Việc truy cập luôn yêu cầu một HF token có quyền đọc vào namespace của job. Sử dụng expose_public để cho phép truy cập không cần xác thực.
  • expose_public (list[int], tuỳ chọn) — Các cổng cần mở qua proxy của Jobs mà không cần xác thực. Chúng không cần được liệt kê trong expose.
  • ssh (bool, tùy chọn) — Nếu là True, container của job có thể được truy cập qua SSH tại URL do job.status.ssh_url cung cấp (ví dụ ssh <job_id>@ssh.hf.jobs, hoặc hf jobs ssh <job_id> từ CLI). Việc kết nối yêu cầu quyền ghi vào namespace của job và một khóa công khai SSH đã được đăng ký trên Hub (https://huggingface.co/settings/keys). Mặc định là False.
  • network_group (str, tùy chọn) — Tên của nhóm mạng cần tham gia. Các tác vụ trong cùng namespace và resource group chia sẻ một nhóm sẽ được đặt cùng nhau và có thể liên lạc với nhau trên mọi cổng. Bên trong mỗi thành viên, HF_NETWORK_GROUP_HOSTNAME sẽ phân giải thành mọi thành viên của nhóm. Chỉ gồm chữ cái thường, chữ số và dấu gạch nối, tối đa 46 ký tự.
  • network_aliases (list[str], tùy chọn) — Các alias mà job này khai báo trong nhóm mạng của nó. Các thành viên sẽ truy cập các job khai báo một alias tại ${HF_NETWORK_GROUP_PREFIX}<alias>. Nhiều job có thể khai báo cùng một alias. Chỉ gồm chữ cái in thường, chữ số và dấu gạch nối, tối đa 34 ký tự, duy nhất trong job. Yêu cầu network_group.
  • resource_group_id (str, tùy chọn) — ID của nhóm tài nguyên để tạo Job. Được sử dụng để kiểm soát quyền truy cập vào các tài nguyên trong một tổ chức và cho các tính năng gán chi phí/giới hạn chi tiêu. Nếu không được cung cấp, Job sẽ được tạo bên ngoài bất kỳ nhóm tài nguyên nào.
  • namespace (str, optional) — Namespace nơi Job sẽ được tạo. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Chạy các tác vụ tính toán trên hạ tầng của Hugging Face.

Ví dụ:

Chạy Job đầu tiên của bạn:

>>> from huggingface_hub import run_job
>>> run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"])

Chạy một tác vụ GPU:

>>> from huggingface_hub import run_job
>>> image = "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel"
>>> command = ["python", "-c", "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"]
>>> run_job(image=image, command=command, flavor="a10g-small")

Chạy một Job với volumes:

>>> from huggingface_hub import Volume, run_job
>>> dataset_volume = Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")
>>> output_bucket_volume = Volume(type="bucket", source="username/my-bucket", mount_path="/output")
>>> image = "duckdb/duckdb"
>>> command = ["duckdb", "-c", "COPY (SELECT * FROM '/data/**/*.parquet' LIMIT 5) TO '/output/first-rows.parquet'"]
>>> run_job(image=image, command=command, volumes=[dataset_volume, output_bucket_volume])

run_uv_job

< >

( script: strscript_args: list[str] | None = Nonedependencies: list[str] | None = Nonepython: str | None = Noneimage: str | None = Noneenv: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Nonessh: bool = Falsenetwork_group: str | None = Nonenetwork_aliases: list[str] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • script (str) — Đường dẫn hoặc URL của script UV, hoặc một lệnh.
  • script_args (list[str], tùy chọn) — Các đối số để truyền cho script hoặc lệnh.
  • dependencies (list[str], tùy chọn) — Các phụ thuộc cần dùng để chạy script UV.
  • python (str, tùy chọn) — Sử dụng một phiên bản Python cụ thể. Mặc định là 3.12.
  • image (str, tùy chọn, mặc định là “ghcr.io/astral-sh/uv —python3.12-bookworm”): Sử dụng hình ảnh Docker tùy chỉnh có cài đặt uv.
  • env (dict[str, Any], tùy chọn) — Định nghĩa các biến môi trường cho Job.
  • secrets (dict[str, Any], tùy chọn) — Định nghĩa các biến môi trường bí mật cho Job.
  • flavor (str, tùy chọn) — Flavor cho phần cứng. Xem JobHardware để biết các giá trị có thể. Mặc định là "cpu-basic".
  • timeout (Union[int, float, str], tùy chọn) — Thời lượng tối đa cho Job: int với s (giây, mặc định), m (phút), h (giờ) hoặc d (ngày). Ví dụ: 300 hoặc "5m" cho 5 phút.
  • attempts (int, tùy chọn) — Số lần thử tối đa, bao gồm lần chạy ban đầu. Mặc định là 1.
  • name (str, tùy chọn) — Tên cho Job. Được lưu dưới dạng nhãn name. Không thể truyền cùng với khóa name trong labels. Tên không nhất thiết phải duy nhất. Mặc định là tên được suy ra từ script và các đối số của nó (kèm hậu tố hash ngắn).
  • labels (dict[str, str], tùy chọn) — Nhãn cần gắn cho tác vụ (các cặp khóa-giá trị).
  • volumes (list[Volume], tùy chọn) — Các Hugging Face Buckets hoặc Repos để gắn làm volumes trong container của job. Mỗi volume là một Volume có type ("bucket", "model", "dataset" hoặc "space"), source (ví dụ "username/my-bucket") và mount_path (ví dụ "/data").
  • expose (list[int], tuỳ chọn) — Các cổng container cần mở qua jobs proxy. Mỗi cổng được liệt kê sẽ có thể truy cập trên tên miền jobs công khai (ví dụ: https://<job_id>--8000.hf.jobs). Việc truy cập luôn yêu cầu một HF token có quyền đọc vào namespace của job. Sử dụng expose_public để cho phép truy cập không cần xác thực.
  • expose_public (list[int], tuỳ chọn) — Các cổng cần mở qua proxy của Jobs mà không cần xác thực. Chúng không cần được liệt kê trong expose.
  • ssh (bool, tùy chọn) — Nếu là True, container của job có thể được truy cập qua SSH tại URL do job.status.ssh_url cung cấp (ví dụ ssh <job_id>@ssh.hf.jobs, hoặc hf jobs ssh <job_id> từ CLI). Việc kết nối yêu cầu quyền ghi vào namespace của job và một khóa công khai SSH đã được đăng ký trên Hub (https://huggingface.co/settings/keys). Mặc định là False.
  • network_group (str, tùy chọn) — Tên của nhóm mạng cần tham gia. Các tác vụ trong cùng namespace và resource group chia sẻ một nhóm sẽ được đặt cùng nhau và có thể liên lạc với nhau trên mọi cổng. Bên trong mỗi thành viên, HF_NETWORK_GROUP_HOSTNAME sẽ phân giải thành mọi thành viên của nhóm. Chỉ gồm chữ cái thường, chữ số và dấu gạch nối, tối đa 46 ký tự.
  • network_aliases (list[str], tùy chọn) — Các alias mà job này khai báo trong nhóm mạng của nó. Các thành viên sẽ truy cập các job khai báo một alias tại ${HF_NETWORK_GROUP_PREFIX}<alias>. Nhiều job có thể khai báo cùng một alias. Chỉ gồm chữ cái in thường, chữ số và dấu gạch nối, tối đa 34 ký tự, duy nhất trong job. Yêu cầu network_group.
  • resource_group_id (str, tùy chọn) — ID của nhóm tài nguyên để tạo Job. Được sử dụng để kiểm soát quyền truy cập vào các tài nguyên trong một tổ chức và cho các tính năng gán chi phí/giới hạn chi tiêu. Nếu không được cung cấp, Job sẽ được tạo bên ngoài bất kỳ nhóm tài nguyên nào.
  • namespace (str, optional) — Namespace nơi Job sẽ được tạo. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Chạy một Job script UV trên hạ tầng của Hugging Face.

Khác với hf jobs uv run, phương pháp này bỏ qua bảng tùy chọn [tool.hf-jobs] mà một kịch bản UV có thể chứa trong phần tiêu đề PEP 723 của nó (xem hướng dẫn về Jobs): cấu hình khởi chạy phải được truyền vào một cách tường minh tại đây.

Ví dụ:

Chạy một script từ một URL:

>>> from huggingface_hub import run_uv_job
>>> script = "https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> run_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small")

Chạy một script cục bộ:

>>> from huggingface_hub import run_uv_job
>>> script = "my_sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> run_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small")

Chạy một lệnh:

>>> from huggingface_hub import run_uv_job
>>> script = "lighteval"
>>> script_args= ["endpoint", "inference-providers", "model_name=openai/gpt-oss-20b,provider=auto", "lighteval|gsm8k|0|0"]
>>> run_uv_job(script, script_args=script_args, dependencies=["lighteval"], flavor="a10g-small")

Gắn các volume, ví dụ để lưu các checkpoint của mô hình trong quá trình huấn luyện:

>>> from huggingface_hub import Volume, run_uv_job
>>> script = "my_sft.py"
>>> script_args = ["--output_dir", "/training-outputs/training-v3-final", ...]
>>> checkpoints_bucket = Volume(type="bucket", source="username/my-bucket", mount_path="/training-outputs")
>>> run_uv_job(script, script_args=script_args, volumes=[checkpoints_bucket])

scale_to_zero_inference_endpoint

< >

( name: strnamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint

Tham số

  • name (str) — Tên của Inference Endpoint cần scale về zero.
  • namespace (str, optional) — Namespace chứa Inference Endpoint. Mặc định là người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

InferenceEndpoint

thông tin về Inference Endpoint đã được scale về 0.

Thang đo điểm cuối suy luận về không.

Inference Endpoint được scale về 0 sẽ không bị tính phí. Nó sẽ được khởi động lại ở lần yêu cầu tiếp theo, kèm theo độ trễ khởi động lạnh. Điều này khác với việc tạm dừng Inference Endpoint bằng pause_inference_endpoint(), khi đó sẽ cần khởi động lại thủ công bằng resume_inference_endpoint().

Để tiện lợi, bạn cũng có thể thu nhỏ một Inference Endpoint về không bằng cách sử dụng InferenceEndpoint.scale_to_zero().

search_spaces

< >

( query: strfilter: str | Iterable[str] | None = Nonesdk: str | list[str] | None = Noneinclude_non_running: bool = Falsetoken: bool | str | None = None ) → Iterable[SpaceSearchResult]

Tham số

  • query (str) — Chuỗi truy vấn tìm kiếm.
  • filter (str hoặc Iterable[str], tùy chọn) — Một thẻ chuỗi hoặc danh sách các thẻ để lọc.
  • sdk (str hoặc list[str], tùy chọn) — Lọc theo SDK (ví dụ: "gradio", "docker", "static").
  • include_non_running (bool, tuỳ chọn) — Có bao gồm các Spaces không đang chạy trong kết quả hay không. Mặc định là False.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

Iterable[SpaceSearchResult]

một iterable gồm các đối tượng SpaceSearchResult.

Tìm kiếm Spaces trên Hub bằng tìm kiếm ngữ nghĩa.

Endpoint này sử dụng tìm kiếm ngữ nghĩa (dựa trên embedding) cho các truy vấn nhiều từ và tìm kiếm toàn văn cho các truy vấn một từ.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> results = list(api.search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'
>>> results[0].ai_category
'Image Generation'

set_space_sleep_time

< >

( repo_id: strsleep_time: inttoken: bool | str | None = None ) → SpaceRuntime

Tham số

  • repo_id (str) — ID của kho cần cập nhật. Ví dụ: "bigcode/in-the-stack".
  • sleep_time (int, tùy chọn) — Số giây không hoạt động cần chờ trước khi một Space được đưa vào trạng thái ngủ. Đặt thành -1 nếu bạn không muốn Space của mình bị tạm dừng (hành vi mặc định cho phần cứng đã nâng cấp). Đối với phần cứng miễn phí, bạn không thể cấu hình thời gian ngủ (giá trị được cố định ở mức 48 giờ không hoạt động). Xem https://huggingface.co/docs/hub/spaces-gpus#sleep-time để biết thêm chi tiết.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

SpaceRuntime

Thông tin thời gian chạy về một Space, bao gồm giai đoạn và phần cứng của Space.

Đặt thời gian ngủ tùy chỉnh cho một Space chạy trên phần cứng nâng cấp.

Space của bạn sẽ chuyển sang trạng thái ngủ sau X giây không hoạt động. Bạn không bị tính phí khi Space ở chế độ “sleep”. Nếu một khách truy cập mới đến Space của bạn, nó sẽ được “thức dậy”. Chỉ phần cứng nâng cấp mới có thể cấu hình thời gian ngủ. Để biết thêm về giai đoạn ngủ, vui lòng tham khảo https://huggingface.co/docs/hub/spaces-gpus#sleep-time.

Bạn cũng có thể đặt thời gian ngủ tùy chỉnh khi yêu cầu phần cứng bằng request_space_hardware().

set_space_volumes

< >

( repo_id: strvolumes: list[Volume]token: bool | str | None = None )

Tham số

  • repo_id (str) — ID của Space cần cập nhật. Ví dụ: "username/my-space".
  • volumes (list[Volume]) — Danh sách các đối tượng Volume cần gắn (mount). Mỗi volume có một type ("bucket", "model", "dataset" hoặc "space"), một source (ID của repo hoặc bucket), một mount_path (đường dẫn bên trong container), và các trường tùy chọn revision, read_only và path.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

BadRequestError

  • BadRequestError — Nếu Space là một Space tĩnh (không hỗ trợ volumes trên các Space tĩnh).

Đặt các volume cho một Space.

Đặt (hoặc thay thế) danh sách các volume được gắn vào Space. Mỗi volume cho phép container của Space truy cập vào một tài nguyên Hub (mô hình, tập dữ liệu, hoặc bucket lưu trữ).

Ví dụ:

>>> from huggingface_hub import HfApi, Volume
>>> api = HfApi()
>>> api.set_space_volumes(
...     "username/my-space",
...     volumes=[
...         Volume(type="model", source="username/my-model", mount_path="/models", read_only=True),
...         Volume(type="bucket", source="username/my-bucket", mount_path="/data"),
...     ],
... )

snapshot_download

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | Path | None = Nonelocal_dir: str | Path | None = Noneetag_timeout: float = 10force_download: bool = Falsetoken: bool | str | None = Nonelocal_files_only: bool = Falseallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonemax_workers: int = 8tqdm_class: type[base_tqdm] | None = Nonedry_run: bool = False ) → str or list of DryRunFileInfo

Tham số

  • repo_id (str) — Tên người dùng hoặc tên tổ chức và tên kho, phân tách bằng /.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu tải xuống từ một dataset hoặc space, None hoặc "model" nếu tải xuống từ một model. Mặc định là None.
  • revision (str, tùy chọn) — Một id phiên bản Git tùy chọn, có thể là tên nhánh, một tag, hoặc một commit hash.
  • cache_dir (str, Path, tùy chọn) — Đường dẫn đến thư mục lưu trữ các tệp được lưu trong bộ nhớ đệm.
  • local_dir (str hoặc Path, tùy chọn) — Nếu được cung cấp, các tệp đã tải xuống sẽ được đặt trong thư mục này.
  • etag_timeout (float, tùy chọn, mặc định là 10) — Khi lấy ETag, số giây chờ máy chủ gửi dữ liệu trước khi từ bỏ, được truyền vào httpx2.request.
  • force_download (bool, tùy chọn, mặc định là False) — Liệu tệp có nên được tải xuống ngay cả khi nó đã tồn tại trong bộ nhớ đệm cục bộ hay không.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • local_files_only (bool, tùy chọn, mặc định là False) — Nếu True, tránh tải xuống tệp và trả về đường dẫn đến tệp được lưu cục bộ nếu tệp đó tồn tại.
  • allow_patterns (list[str] hoặc str, tùy chọn) — Nếu được cung cấp, chỉ các tệp khớp với ít nhất một mẫu sẽ được tải xuống.
  • ignore_patterns (list[str] hoặc str, tùy chọn) — Nếu được cung cấp, các tệp khớp với bất kỳ mẫu nào trong danh sách sẽ không được tải xuống.
  • max_workers (int, tùy chọn) — Số lượng luồng đồng thời để tải xuống các tệp (1 luồng = 1 tệp tải xuống). Mặc định là 8.
  • tqdm_class (tqdm, tùy chọn) — Nếu được cung cấp, sẽ ghi đè lên hành vi mặc định của thanh tiến trình. Đối số được truyền phải kế thừa từ tqdm.auto.tqdm hoặc ít nhất phải mô phỏng hành vi của nó. Lưu ý rằng tqdm_class không được truyền cho từng thao tác tải xuống riêng lẻ. Mặc định là thanh tiến trình tùy chỉnh của HF, có thể bị vô hiệu hóa bằng cách đặt biến môi trường HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool, tùy chọn, mặc định là False) — Nếu True, thực hiện chạy thử mà không thực sự tải xuống các tệp. Trả về một danh sách các đối tượng DryRunFileInfo chứa thông tin về những gì sẽ được tải xuống.

Trả về

str hoặc danh sách DryRunFileInfo

  • Nếu dry_run=False: Đường dẫn thư mục của bản sao lưu kho.
  • Nếu dry_run=True: Một danh sách các đối tượng DryRunFileInfo chứa thông tin tải xuống.

Gây ra

RepositoryNotFoundError hoặc RevisionNotFoundError hoặc EnvironmentError hoặc OSError hoặc ValueError

  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.
  • RevisionNotFoundError — Nếu không tìm thấy revision để tải xuống.
  • EnvironmentError — Nếu token=True và không tìm thấy token.
  • OSError — nếu không thể xác định được ETag.
  • ValueError — nếu giá trị của một số tham số không hợp lệ.

Tải xuống các tệp của kho.

Tải xuống toàn bộ snapshot các tệp của một repo tại revision được chỉ định. Điều này hữu ích khi bạn muốn tất cả các tệp từ một repo, vì bạn không biết trước mình sẽ cần những tệp nào. Tất cả các tệp được đặt lồng trong một thư mục để giữ nguyên tên tệp thực tế của chúng tương đối so với thư mục đó. Bạn cũng có thể lọc các tệp cần tải xuống bằng cách sử dụng allow_patterns và ignore_patterns.

Nếu local_dir được cung cấp, cấu trúc tệp từ kho sẽ được nhân bản tại vị trí này. Khi sử dụng tùy chọn này, cache_dir sẽ không được sử dụng và một thư mục .cache/huggingface/ sẽ được tạo tại gốc của local_dir để lưu trữ một số siêu dữ liệu liên quan đến các tệp đã tải xuống. Mặc dù cơ chế này không mạnh mẽ bằng hệ thống cache chính, nó được tối ưu hóa để thường xuyên kéo phiên bản mới nhất của một kho.

Một phương án thay thế là clone kho mã nguồn, nhưng điều này yêu cầu git và git-lfs phải được cài đặt và cấu hình đúng cách. Ngoài ra, khi clone một kho mã nguồn bằng git, bạn không thể lọc các tệp cần tải xuống.

space_info

< >

( repo_id: strrevision: str | None = Nonetimeout: float | None = Nonefiles_metadata: bool = Falseexpand: list[ExpandSpaceProperty_T] | None = Nonetoken: bool | str | None = None ) → SpaceInfo

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • revision (str, tùy chọn) — Phiên bản của kho space để lấy thông tin.
  • timeout (float, tùy chọn) — Có nên đặt thời gian chờ cho yêu cầu đến Hub hay không.
  • files_metadata (bool, tùy chọn) — Có lấy hay không lấy metadata cho các tệp trong kho (kích thước, metadata LFS, v.v.). Mặc định là False.
  • expand (list[ExpandSpaceProperty_T], tùy chọn) — Danh sách các thuộc tính cần trả về trong phản hồi. Khi được sử dụng, chỉ các thuộc tính trong danh sách sẽ được trả về. Tham số này không thể được sử dụng nếu full được truyền vào. Các giá trị có thể là "author", "cardData", "createdAt", "datasets", "disabled", "lastModified", "likes", "models", "private", "region", "runtime", "sdk", "siblings", "sha", "subdomain", "tags", "trendingScore", "usedStorage" và "resourceGroup".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

SpaceInfo

Thông tin kho lưu trữ Space.

Lấy thông tin về một Space cụ thể trên huggingface.co.

Space có thể là riêng tư nếu bạn truyền vào một token hợp lệ.

Gây ra các lỗi sau:

  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.
  • RevisionNotFoundError Nếu không tìm thấy revision cần tải xuống.

super_squash_history

< >

( repo_id: strbranch: str | None = Nonecommit_message: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None )

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • branch (str, tùy chọn) — Nhánh cần squash. Mặc định là đầu của nhánh "main".
  • commit_message (str, tùy chọn) — Thông báo commit được sử dụng cho commit đã được nén.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu liệt kê các commit từ một dataset hoặc một Space, None hoặc "model" nếu liệt kê từ một model. Mặc định là None.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

RepositoryNotFoundError hoặc RevisionNotFoundError hoặc BadRequestError

  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho là riêng tư nhưng chưa xác thực hoặc kho không tồn tại.
  • RevisionNotFoundError — Nếu không tìm thấy nhánh cần squash.
  • BadRequestError — Nếu tham chiếu không hợp lệ cho một nhánh. Bạn không thể nén lịch sử trên các thẻ.

Nén lịch sử commit trên một nhánh của kho trên Hub.

Việc nén lịch sử repo hữu ích khi bạn biết mình sẽ tạo hàng trăm commit và không muốn làm lộn xộn lịch sử. Việc nén commit chỉ có thể được thực hiện từ đầu của một nhánh.

Một khi đã được nén, lịch sử commit không thể được khôi phục. Đây là một thao tác không thể hoàn tác.

Một khi lịch sử của một nhánh đã được nén lại, sẽ không thể hợp nhất nó trở lại vào một nhánh khác vì lịch sử của chúng đã phân kỳ.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Create repo
>>> repo_id = api.create_repo("test-squash").repo_id

# Make a lot of commits.
>>> api.upload_file(repo_id=repo_id, path_in_repo="file.txt", path_or_fileobj=b"content")
>>> api.upload_file(repo_id=repo_id, path_in_repo="lfs.bin", path_or_fileobj=b"content")
>>> api.upload_file(repo_id=repo_id, path_in_repo="file.txt", path_or_fileobj=b"another_content")

# Squash history
>>> api.super_squash_history(repo_id=repo_id)

suspend_scheduled_job

< >

( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )

Tham số

  • scheduled_job_id (str) — ID của Job được lên lịch.
  • namespace (str, optional) — Namespace chứa Job được lên lịch. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Tạm dừng (đóng băng) một Job tính toán đã lên lịch trên hạ tầng của Hugging Face.

sync_bucket

< >

( source: str | None = Nonedest: str | None = Nonedelete: bool = Falseignore_times: bool = Falseignore_sizes: bool = Falseexisting: bool = Falseignore_existing: bool = Falseinclude: list[str] | None = Noneexclude: list[str] | None = Nonefilter_from: str | None = Noneplan: str | None = Noneapply: str | None = Nonedry_run: bool = Falseverbose: bool = Falsequiet: bool = Falsetoken: bool | str | None = None ) → [SyncPlan]

Tham số

  • source (str, tuỳ chọn) — Đường dẫn nguồn: thư mục cục bộ hoặc hf://buckets/namespace/bucket_name(/prefix). Bắt buộc trừ khi sử dụng apply.
  • dest (str, tuỳ chọn) — Đường dẫn đích: thư mục cục bộ hoặc hf://buckets/namespace/bucket_name(/prefix). Bắt buộc trừ khi sử dụng apply.
  • delete (bool, optional, mặc định là False) — Xóa các tệp đích không có trong nguồn.
  • ignore_times (bool, tuỳ chọn, mặc định là False) — Bỏ qua các tệp chỉ dựa trên kích thước, bỏ qua thời gian sửa đổi.
  • ignore_sizes (bool, tuỳ chọn, mặc định là False) — Bỏ qua các tệp chỉ dựa trên thời gian sửa đổi, bỏ qua kích thước.
  • existing (bool, tuỳ chọn, mặc định là False) — Bỏ qua việc tạo các tệp mới trên máy nhận (chỉ cập nhật các tệp hiện có).
  • ignore_existing (bool, tuỳ chọn, mặc định là False) — Bỏ qua việc cập nhật các tệp đã tồn tại trên máy nhận (chỉ tạo các tệp mới).
  • include (list[str], optional) — Bao gồm các tệp khớp với các mẫu (theo kiểu fnmatch).
  • exclude (list[str], tuỳ chọn) — Loại trừ các tệp khớp với các mẫu (theo kiểu fnmatch).
  • filter_from (str, optional) — Đường dẫn đến tệp filter chứa các quy tắc include/exclude.
  • plan (str, optional) — Lưu kế hoạch đồng bộ vào tệp JSONL này thay vì thực thi.
  • apply (str, optional) — Áp dụng một tệp kế hoạch đã lưu trước đó. Khi được đặt, source và dest không cần thiết.
  • dry_run (bool, tùy chọn, mặc định là False) — In kế hoạch đồng bộ ra stdout dưới dạng JSONL mà không thực thi.
  • verbose (bool, tùy chọn, mặc định là False) — Hiển thị các thao tác chi tiết cho từng tệp.
  • quiet (bool, tuỳ chọn, mặc định là False) — Ẩn tất cả đầu ra và thanh tiến trình.
  • token (Union[bool, str, None], optional) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng.

Trả về

[SyncPlan]

Kế hoạch đồng bộ đã được tính toán (hoặc tải vào).

Đồng bộ hóa các tệp giữa một thư mục cục bộ và một bucket.

Điều này tương đương với lệnh CLI hf buckets sync. Một trong source hoặc dest phải là đường dẫn bucket (hf://buckets/...) và cái còn lại phải là đường dẫn thư mục cục bộ.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Upload local directory to bucket
>>> api.sync_bucket("./data", "hf://buckets/username/my-bucket")

# Download bucket to local directory
>>> api.sync_bucket("hf://buckets/username/my-bucket", "./data")

# Sync with delete and filtering
>>> api.sync_bucket(
...     "./data",
...     "hf://buckets/username/my-bucket",
...     delete=True,
...     include=["*.safetensors"],
... )

# Dry run: preview what would be synced
>>> plan = api.sync_bucket("./data", "hf://buckets/username/my-bucket", dry_run=True)
>>> plan.summary()
{'uploads': 3, 'downloads': 0, 'deletes': 0, 'skips': 1, 'total_size': 4096}

# Save plan for review, then apply
>>> api.sync_bucket("./data", "hf://buckets/username/my-bucket", plan="sync-plan.jsonl")
>>> api.sync_bucket(apply="sync-plan.jsonl")

sync_job_volume

< >

( source: str | Pathmount_path: strremote_name: str | None = Noneread_only: bool = Truenamespace: str | None = Nonetoken: bool | str | None = None ) → Volume

Tham số

  • source (str hoặc Path) — Đường dẫn đến thư mục cục bộ để đồng bộ hóa.
  • mount_path (str) — Đường dẫn gắn (mount path) bên trong container của Job, ví dụ "/inputs". Phải bắt đầu bằng /.
  • remote_name (str, tùy chọn) — Tên của thư mục con trong bucket để đồng bộ hóa. Mặc định là tên {dirname}-{hash} được suy ra từ đường dẫn nguồn và tên máy chủ của máy.
  • read_only (bool, tùy chọn, mặc định là True) — Gắn volume chỉ đọc trong Job. Truyền False để cho phép Job ghi ngược lại vào thư mục bucket (ví dụ để lấy các kết quả đầu ra bằng sync_bucket() sau đó).
  • namespace (str, optional) — Namespace sở hữu bucket jobs-artifacts. Mặc định là namespace của người dùng hiện tại. Hãy sử dụng cùng namespace với Job sẽ gắn (mount) volume.
  • token (Union[bool, str, None], tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Trả về

Khối lượng

Dung lượng bucket được giới hạn phạm vi theo thư mục con đã đồng bộ, để truyền vào danh sách volumes của run_job(), run_uv_job(), create_scheduled_job() hoặc create_scheduled_uv_job().

Đồng bộ một thư mục cục bộ với một bucket và trả về một Volume sẵn sàng để gắn vào một Job.

Các tệp được tải lên một thư mục con của bucket {namespace}/jobs-artifacts (được tạo tự động ở chế độ riêng tư; một cảnh báo sẽ được phát ra nếu bucket đã tồn tại và ở chế độ công khai) bằng cách sử dụng cùng logic đồng bộ như sync_bucket(): việc đồng bộ lại cùng một thư mục chỉ tải lên các tệp mới hoặc đã bị sửa đổi. Mặc định, tên thư mục con được suy ra từ đường dẫn thư mục và tên máy chủ của máy, do đó các lần gọi lặp lại từ cùng một thư mục sẽ tái sử dụng cùng một thư mục từ xa. Truyền remote_name để sử dụng một tên cố định thay thế.

Lưu ý rằng dữ liệu được sao chép vào bucket, không được gắn trực tiếp: các thay đổi được thực hiện cục bộ sau lúc đồng bộ sẽ không hiển thị cho Job (chạy lại sync_job_volume để cập nhật), và volume được gắn ở chế độ chỉ đọc theo mặc định. Để lấy dữ liệu do Job ghi vào một volume đọc-ghi, hãy đồng bộ thư mục bucket trở lại bằng sync_bucket(). Nếu thư mục nguồn trống (ví dụ: một thư mục đầu ra), một tệp .keep giữ chỗ sẽ được tải lên để volume vẫn có thể được gắn.

Ví dụ:

>>> from huggingface_hub import run_uv_job, sync_job_volume

# Upload ./training-data once, then run multiple jobs against it
>>> volume = sync_job_volume("./training-data", "/data")
>>> run_uv_job("train.py", script_args=["--learning-rate", "0.01"], volumes=[volume])
>>> run_uv_job("train.py", script_args=["--learning-rate", "0.05"], volumes=[volume])

# Read-write volume to retrieve outputs after the job completes
>>> volume = sync_job_volume("./outputs", "/outputs", read_only=False)
>>> job = run_uv_job("process.py", volumes=[volume])

trigger_scheduled_job

< >

( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo

Tham số

  • scheduled_job_id (str) — ID của Job được lên lịch.
  • namespace (str, optional) — Namespace chứa Job được lên lịch. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Trả về

JobInfo

Thông tin về lần chạy được kích hoạt.

Gây ra

HfHubHTTPError

  • HfHubHTTPError — HTTP 409 nếu một instance khác đã đang chạy và concurrency bị tắt trên job được lên lịch.

Kích hoạt một Job được lên lịch để chạy ngay lập tức.

Điều này kích hoạt một lần chạy ngay lập tức của spec công việc được lên lịch. Nó không thay đổi lịch trình và không ảnh hưởng đến lần chạy được lên lịch tiếp theo. Nếu một instance đang chạy và công việc được lên lịch không cho phép chạy đồng thời, yêu cầu sẽ bị từ chối (HTTP 409).

không giống

< >

( repo_id: strtoken: bool | str | None = Nonerepo_type: str | None = None )

Tham số

  • repo_id (str) — Kho lưu trữ để bỏ thích. Ví dụ: "user/my-cool-model".
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset" hoặc "space" nếu bỏ thích một dataset hoặc space, None hoặc "model" nếu bỏ thích một model. Mặc định là None.

Gây ra

RepositoryNotFoundError

  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho riêng tư nhưng chưa xác thực hoặc kho không tồn tại.

Khác với một kho lưu trữ cụ thể trên Hub (ví dụ: xóa khỏi danh sách yêu thích).

Để ngăn chặn việc sử dụng spam, không thể like một kho lưu trữ từ một script.

Xem thêm list_liked_repos().

Ví dụ:

>>> from huggingface_hub import list_liked_repos, unlike
>>> "gpt2" in list_liked_repos().models # we assume you have already liked gpt2
True
>>> unlike("gpt2")
>>> "gpt2" in list_liked_repos().models
False

update_bucket_settings

< >

( bucket_id: strprivate: booltoken: bool | str | None = None )

Tham số

  • bucket_id (str) — ID của bucket (ví dụ: "username/my-bucket").
  • private (bool) — Xác định có làm cho bucket riêng tư hay không.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gây ra

BucketNotFoundError hoặc or

  • BucketNotFoundError — Nếu không tìm thấy bucket. Điều này có thể do bucket không tồn tại,
  • or — vì nó được đặt ở chế độ private và bạn không có quyền truy cập.

Cập nhật cài đặt của một bucket trên Hub.

Hiện tại, cài đặt duy nhất được hỗ trợ là mức độ hiển thị của bucket.

Ví dụ:

>>> from huggingface_hub import update_bucket_settings

>>> # Make a bucket public
>>> update_bucket_settings(bucket_id="Wauplin/first-bucket", private=False)

>>> # Make it private again
>>> update_bucket_settings(bucket_id="Wauplin/first-bucket", private=True)

update_collection_item

< >

( collection_slug: stritem_object_id: strnote: str | None = Noneposition: int | None = Nonetoken: bool | str | None = None )

Tham số

  • collection_slug (str) — Slug của bộ sưu tập cần cập nhật. Ví dụ: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • item_object_id (str) — ID của mục trong bộ sưu tập. Đây không phải là id của mục trên Hub (repo_id hoặc paper id). Nó phải được lấy từ một đối tượng CollectionItem. Ví dụ: collection.items[0].item_object_id.
  • note (str, tùy chọn) — Ghi chú đính kèm cho mục trong bộ sưu tập. Kích thước tối đa của một ghi chú là 500 ký tự.
  • position (int, tùy chọn) — Vị trí mới của mục trong bộ sưu tập.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Cập nhật một mục trong bộ sưu tập.

Ví dụ:

>>> from huggingface_hub import get_collection, update_collection_item

# Get collection first
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")

# Update item based on its ID (add note + update position)
>>> update_collection_item(
...     collection_slug="TheBloke/recent-models-64f9a55bb3115b4f513ec026",
...     item_object_id=collection.items[-1].item_object_id,
...     note="Newly updated model!",
...     position=0,
... )

update_collection_metadata

< >

( collection_slug: strtitle: str | None = Nonedescription: str | None = Noneposition: int | None = Noneprivate: bool | None = Nonetheme: str | None = Nonetoken: bool | str | None = None )

Tham số

  • collection_slug (str) — Slug của bộ sưu tập cần cập nhật. Ví dụ: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • title (str) — Tiêu đề của bộ sưu tập cần cập nhật.
  • description (str, tùy chọn) — Mô tả của bộ sưu tập cần cập nhật. Kích thước tối đa cho một mô tả là 150 ký tự.
  • position (int, tùy chọn) — Vị trí mới của bộ sưu tập trong danh sách các bộ sưu tập của người dùng.
  • private (bool, optional) — Xác định xem bộ sưu tập có nên được đặt ở chế độ riêng tư hay không.
  • theme (str, tùy chọn) — Chủ đề của bộ sưu tập trên Hub.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Cập nhật metadata của một collection trên Hub.

Tất cả các đối số đều là tùy chọn. Chỉ các metadata được cung cấp sẽ được cập nhật.

Trả về: Collection

Ví dụ:

>>> from huggingface_hub import update_collection_metadata
>>> collection = update_collection_metadata(
...     collection_slug="username/iccv-2023-64f9a55bb3115b4f513ec026",
...     title="ICCV Oct. 2023",
...     description="Portfolio of models, datasets, papers and demos I presented at ICCV Oct. 2023",
...     private=False,
...     theme="pink",
... )
>>> collection.slug
"username/iccv-oct-2023-64f9a55bb3115b4f513ec026"
# ^collection slug got updated but not the trailing ID

update_collection_resource_group

< >

( collection_slug: strresource_group_id: str | Nonetoken: bool | str | None = None )

Tham số

  • collection_slug (str) — Slug của bộ sưu tập cần cập nhật. Ví dụ: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • resource_group_id (str hoặc None) — Nhóm tài nguyên để gán cho bộ sưu tập, dưới dạng chuỗi thập lục phân 24 ký tự. Nếu là None, bộ sưu tập sẽ được gỡ khỏi mọi nhóm tài nguyên.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Gán một bộ sưu tập cho nhóm tài nguyên, hoặc gỡ bỏ nó khỏi mọi nhóm tài nguyên.

Chỉ có hiệu lực với các bộ sưu tập thuộc sở hữu của tổ chức.

Ví dụ:

>>> from huggingface_hub import update_collection_resource_group
>>> update_collection_resource_group(
...     collection_slug="my-org/iccv-2023-64f9a55bb3115b4f513ec026",
...     resource_group_id="66980ecfc1e12a49c8f0e42d",
... )

update_inference_endpoint

< >

( name: straccelerator: str | None = Noneinstance_size: str | None = Noneinstance_type: str | None = Nonemin_replica: int | None = Nonemax_replica: int | None = Nonescale_to_zero_timeout: int | None = Nonescaling_metric: InferenceEndpointScalingMetric | None = Nonescaling_threshold: float | None = Nonerepository: str | None = Noneframework: str | None = Nonerevision: str | None = Nonetask: str | None = Nonecustom_image: dict | None = Nonecontainer_command: list[str] | None = Nonecontainer_args: list[str] | None = Nonetensor_parallel_size: int | None = Nonedata_parallel_size: int | None = Noneenv: dict[str, str] | None = Nonesecrets: dict[str, str] | None = Nonedomain: str | None = Nonepath: str | None = Nonecache_http_responses: bool | None = Nonetags: list[str] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint

Tham số

  • name (str) — Tên của Inference Endpoint cần cập nhật.
  • accelerator (str, tùy chọn) — Bộ tăng tốc phần cứng được sử dụng cho suy luận (ví dụ: "cpu").
  • instance_size (str, tùy chọn) — Kích thước hoặc loại instance được sử dụng để lưu trữ model (ví dụ: "x4").
  • instance_type (str, tùy chọn) — Loại instance trên cloud nơi Inference Endpoint sẽ được triển khai (ví dụ: "intel-icl").
  • min_replica (int, tùy chọn) — Số lượng tối thiểu các bản sao (instance) cần duy trì hoạt động cho Inference Endpoint.
  • max_replica (int, tùy chọn) — Số lượng bản sao (instance) tối đa để mở rộng cho Inference Endpoint.
  • scale_to_zero_timeout (int, tùy chọn) — Thời lượng tính bằng phút trước khi một endpoint không hoạt động bị thu về mức không.
  • scaling_metric (str hoặc InferenceEndpointScalingMetric , tùy chọn) — Tham chiếu chỉ số để mở rộng. Là “pendingRequests” hoặc “hardwareUsage” khi được cung cấp. Mặc định là None.
  • scaling_threshold (float, tùy chọn) — Ngưỡng của chỉ số đo lường mở rộng được sử dụng để kích hoạt việc mở rộng lên. Bỏ qua khi không cung cấp chỉ số đo lường mở rộng. Mặc định là None.
  • repository (str, tùy chọn) — Tên của kho mô hình liên quan đến Inference Endpoint (ví dụ: "gpt2").
  • framework (str, tùy chọn) — Khung machine learning được sử dụng cho mô hình (ví dụ: "custom").
  • revision (str, tùy chọn) — Phiên bản cụ thể của mô hình cần triển khai trên Inference Endpoint (ví dụ: "6c0e6080953db56375760c0471a8c5f2929baf11").
  • task (str, tùy chọn) — Nhiệm vụ để triển khai mô hình (ví dụ: "text-classification").
  • custom_image (dict, tùy chọn) — Ảnh container để chạy. Có thể là một dict có khóa là biến thể của ảnh (ví dụ {"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}‌}, cũng như sGLang, tgi, tei, llamacpp, hfServe, …), được chuyển tiếp nguyên vẹn, hoặc một dict phẳng mô tả một container tùy chỉnh (ví dụ {"url": ..., "port": ...}), được gửi dưới dạng {"custom": ...}.
  • container_command (list[str], tùy chọn) — Ghi đè lệnh entrypoint của container (tương ứng với model.command trong API payload). Hoạt động với cả các image engine được quản lý (ví dụ: vLLM, SGLang) và các image tùy chỉnh.
  • container_args (list[str], tùy chọn) — Các đối số được thêm vào entrypoint của container (tương ứng với model.args trong API payload). Hoạt động với cả các image engine được quản lý (ví dụ: vLLM, SGLang) và các image tùy chỉnh.
  • tensor_parallel_size (int, tùy chọn) — Số lượng bộ tăng tốc để chia nhỏ một bản sao mô hình duy nhất (ảnh vLLM và SGLang). Được ghi bên trong cấu hình ảnh engine. API yêu cầu model.image như một tổng thể, do đó khi custom_image không được cung cấp, ảnh hiện đang được cấu hình trên endpoint sẽ được lấy về và cập nhật tại chỗ.
  • data_parallel_size (int, tùy chọn) — Số lượng bản sao mô hình cần chạy, mỗi bản sao trên một bộ tăng tốc (ảnh vLLM). Cách xử lý giống như tensor_parallel_size.
  • env (dict[str, str], tùy chọn) — Các biến môi trường không bí mật để tiêm vào môi trường của container
  • secrets (dict[str, str], tùy chọn) — Các giá trị bí mật để tiêm vào môi trường của container.
  • domain (str, tùy chọn) — Domain tùy chỉnh cho việc triển khai Inference Endpoint; nếu được cấu hình, inference endpoint sẽ khả dụng tại domain này (ví dụ: "my-new-domain.cool-website.woof").
  • path (str, tùy chọn) — Đường dẫn tùy chỉnh đến mô hình đã triển khai, phải bắt đầu bằng / (ví dụ: "/models/google-bert/bert-base-uncased").
  • cache_http_responses (bool, tùy chọn) — Có nên lưu bộ nhớ đệm các phản hồi HTTP từ Inference Endpoint hay không.
  • tags (list[str], tùy chọn) — Danh sách các thẻ để liên kết với Inference Endpoint.
  • namespace (str, optional) — Namespace nơi Inference Endpoint sẽ được cập nhật. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

InferenceEndpoint

thông tin về Inference Endpoint đã được cập nhật.

Cập nhật một Inference Endpoint.

Phương pháp này cho phép cập nhật cấu hình tính toán, mô hình đã triển khai, tuyến đường, hoặc bất kỳ sự kết hợp nào của chúng. Tất cả các đối số đều là tùy chọn nhưng ít nhất một đối số phải được cung cấp.

Để tiện lợi, bạn cũng có thể cập nhật một Inference Endpoint bằng cách sử dụng InferenceEndpoint.update().

update_job_expose

< >

( job_id: strexpose: list[int] | None = Noneexpose_public: list[int] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo

Tham số

  • job_id (str) — ID của Job đang chạy.
  • expose (list[int], tuỳ chọn) — Các cổng cần mở qua Jobs proxy. Việc truy cập yêu cầu một HF token có quyền đọc vào namespace của Job.
  • expose_public (list[int], tuỳ chọn) — Các cổng cần mở qua proxy của Jobs mà không cần xác thực. Chúng không cần được liệt kê trong expose.
  • namespace (str, không bắt buộc) — Namespace của Job. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Token truy cập của người dùng. Mặc định là token được lưu cục bộ.

Trả về

JobInfo

Công việc đã được cập nhật.

Thay đổi các cổng được phơi bày của một Job đang chạy mà không cần chạy lại nó.

expose và expose_public cùng nhau tạo thành cấu hình cổng hoàn chỉnh: các cổng không có trong danh sách nào sẽ bị đóng. Không truyền tham số nào để đóng tất cả các cổng đã mở.

update_job_labels

< >

( job_id: strlabels: dict[str, str]namespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo

Tham số

  • job_id (str) — ID của Job.
  • labels (dict[str, str]) — Các nhãn mới cần đặt cho tác vụ. Thay thế tất cả các nhãn hiện có. Cả khóa và giá trị phải có tối đa 100 ký tự và chỉ chứa ký tự chữ số, dấu gạch ngang và dấu gạch dưới.
  • namespace (str, optional) — Namespace nơi Job đang chạy. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Trả về

JobInfo

Thông tin Job đã được cập nhật.

Cập nhật nhãn của một Job hiện có.

Thay thế tất cả các nhãn do người dùng cung cấp hiện có bằng các nhãn mới.

update_repo_settings

< >

( repo_id: strgated: Literal['auto', 'manual', False] | None = Noneprivate: bool | None = Nonevisibility: RepoVisibility_T | None = Nonetoken: str | bool | None = Nonerepo_type: str | None = None )

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • gated (Literal["auto", "manual", False], tuỳ chọn) — Trạng thái gated của kho. Nếu đặt thành None (mặc định), cài đặt gated của kho sẽ không được cập nhật.
    • “auto”: Kho lưu trữ được bảo vệ, và các yêu cầu truy cập sẽ được tự động phê duyệt hoặc từ chối dựa trên các tiêu chí được định nghĩa trước.
    • “manual”: Kho lưu trữ được bảo vệ, và các yêu cầu truy cập cần được phê duyệt thủ công.
    • False : Kho lưu trữ không được bảo vệ, và bất kỳ ai cũng có thể truy cập.
  • private (bool, tuỳ chọn) — Xác định xem kho có nên là kho riêng tư hay không. Không thể truyền cùng với visibility.
  • visibility (Literal["public", "private", "protected"], optional) — Tính khả kiến của kho. Có thể là "public" hoặc "private", hoặc "protected" đối với Spaces.
  • token (Union[str, bool, None], tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Loại kho cần cập nhật cài đặt ("model", "dataset" hoặc "space"). Mặc định là "model".

Gây ra

ValueError hoặc HfHubHTTPError hoặc RepositoryNotFoundError

  • ValueError — Nếu gated không phải là “auto”, “manual” hoặc False.
  • ValueError — Nếu repo_type không phải là một trong các giá trị trong constants.REPO_TYPES.
  • HfHubHTTPError — Nếu yêu cầu đến API của Hugging Face Hub 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.

Cập nhật cài đặt của một kho lưu trữ, bao gồm quyền truy cập có kiểm soát và mức độ hiển thị.

Để cung cấp nhiều quyền kiểm soát hơn về cách các kho được sử dụng, Hub cho phép tác giả kho bật yêu cầu truy cập cho kho của họ, đồng thời thay đổi mức độ hiển thị của kho.

update_scheduled_job_labels

< >

( scheduled_job_id: strlabels: dict[str, str]namespace: str | None = Nonetoken: bool | str | None = None ) → ScheduledJobInfo

Tham số

  • scheduled_job_id (str) — ID của Job được lên lịch.
  • labels (dict[str, str]) — Các nhãn mới để đặt cho công việc đã lên lịch. Thay thế tất cả các nhãn hiện có. Cả khóa và giá trị phải tối đa 100 ký tự và chỉ chứa ký tự chữ số, dấu gạch ngang và dấu gạch dưới.
  • namespace (str, optional) — Namespace chứa Job được lên lịch. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Trả về

ScheduledJobInfo

Thông tin về Job được lên lịch đã cập nhật.

Cập nhật nhãn của một Job được lên lịch hiện có.

Thay thế tất cả các nhãn do người dùng cung cấp hiện có bằng các nhãn mới.

update_scheduled_job_schedule

< >

( scheduled_job_id: strschedule: strnamespace: str | None = Nonetoken: bool | str | None = None ) → ScheduledJobInfo

Tham số

  • scheduled_job_id (str) — ID của Job được lên lịch.
  • schedule (str) — Một trong các giá trị “@annually”, “@yearly”, “@monthly”, “@weekly”, “@daily”, “@hourly”, hoặc một biểu thức lịch CRON (ví dụ: ‘0 9 * * 1’ cho 9 giờ sáng mỗi thứ Hai).
  • namespace (str, optional) — Namespace chứa Job được lên lịch. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Trả về

ScheduledJobInfo

Thông tin về Job được lên lịch đã cập nhật.

Thay đổi thời điểm chạy của một Job đã lên lịch có sẵn.

Chỉ lịch được cập nhật: spec của Job, các nhãn và trạng thái suspended được giữ nguyên. Để chạy Job được lên lịch một lần ngay bây giờ mà không thay đổi lịch của nó, hãy dùng trigger_scheduled_job() thay vào đó.

Ví dụ:

>>> from huggingface_hub import update_scheduled_job_schedule
>>> scheduled_job = update_scheduled_job_schedule(scheduled_job_id="6abb8dc9c617607c354d45f4", schedule="@daily")
>>> scheduled_job.schedule
'@daily'

update_webhook

< >

( webhook_id: strurl: str | None = Nonejob_id: str | None = Nonewatched: list[dict | WebhookWatchedItem] | None = Nonedomains: list[constants.WEBHOOK_DOMAIN_T] | None = Nonesecret: str | None = Nonesecrets: dict[str, str] | None = Nonetoken: bool | str | None = None ) → WebhookInfo

Tham số

  • webhook_id (str) — Định danh duy nhất của webhook cần được cập nhật.
  • url (str, tùy chọn) — URL mà payload sẽ được gửi đến.
  • job_id (str, tùy chọn) — ID của Job nguồn để kích hoạt bằng webhook payload. Bắt buộc khi thiết lập secrets.
  • watched (list[WebhookWatchedItem], optional) — Danh sách các mục cần theo dõi. Các mục này có thể là người dùng, tổ chức, mô hình, bộ dữ liệu hoặc không gian. Xem WebhookWatchedItem để biết thêm chi tiết. Các mục được theo dõi cũng có thể được cung cấp dưới dạng từ điển thông thường.
  • domains (list[Literal["repo", "discussion"]], optional) — Các domain cần theo dõi. Có thể bao gồm “repo”, “discussion”, hoặc cả hai.
  • secret (str, optional) — Một bí mật để ký cho payload, cung cấp một lớp bảo mật bổ sung.
  • secrets (dict[str, str], optional) — Các biến môi trường bí mật cho Job được kích hoạt bởi webhook. Các khóa được liệt kê sẽ thay thế giá trị đã lưu, chuỗi rỗng sẽ xóa bí mật đó, và các khóa bị bỏ qua sẽ giữ nguyên giá trị đã lưu. Yêu cầu job_id.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

WebhookInfo

Thông tin về webhook đã được cập nhật.

Cập nhật webhook hiện có.

Ví dụ:

>>> from huggingface_hub import update_webhook
>>> updated_payload = update_webhook(
...     webhook_id="654bbbc16f2ec14d77f109cc",
...     url="https://new.webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
...     watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
...     domains=["repo"],
...     secret="my-secret",
... )
>>> print(updated_payload)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    job=None,
    url="https://new.webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo"],
    secret="my-secret",
    disabled=False,

upload_attachment

< >

( path: str | Pathtoken: bool | str | None = None ) → str

Tham số

  • path (str hoặc Path) — Đường dẫn đến tệp cần tải lên. Các định dạng được hỗ trợ là PNG, JPEG, GIF, WebP, MP4, MOV, WebM, MP3 và WAV. Tệp phải nhỏ hơn 10MB (50MB đối với video).
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Token cần có quyền discussion.write. Để tải lên ẩn danh, hãy truyền False.

Trả về

str

đường dẫn URL của tệp đã tải lên.

Gây ra

ValueError

  • ValueError — Nếu định dạng tệp không được hỗ trợ.

Tải lên Hub một tệp hình ảnh, video hoặc âm thanh và trả về URL của nó.

Đây là những gì trình soạn thảo web của Hub thực hiện khi bạn kéo một tệp vào hộp bình luận của Discussion hoặc Pull Request. Nhúng URL được trả về vào mô tả hoặc bình luận: ![alt text](url) cho hình ảnh, URL trần cho video và <audio controls src="url"></audio> cho tệp âm thanh.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> url = api.upload_attachment("screenshot.png")
>>> api.create_discussion("username/my-model", title="Rendering bug", description=f"![screenshot]({url})")

upload_file

< >

( path_or_fileobj: str | Path | bytes | BinaryIOpath_in_repo: strrepo_id: strtoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = Nonerun_as_future: bool = False_hot_reload: bool | None = None ) → CommitInfo or Future

Tham số

  • path_or_fileobj (str, Path, bytes, hoặc IO) — Đường dẫn đến tệp trên máy cục bộ hoặc luồng dữ liệu nhị phân / fileobj / buffer.
  • path_in_repo (str) — Đường dẫn tệp tương đối trong kho, ví dụ: "checkpoints/1fec34a/weights.bin"
  • repo_id (str) — Kho lưu trữ mà tệp sẽ được tải lên, ví dụ: "username/custom_transformers"
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset", "space" hoặc "kernel" nếu tải lên kho dataset, space hoặc kernel, None hoặc "model" nếu tải lên model. Mặc định là None.
  • revision (str, tùy chọn) — Phiên bản git để commit từ. Mặc định là đầu của nhánh "main".
  • commit_message (str, tùy chọn) — Tóm tắt / tiêu đề / dòng đầu tiên của commit được tạo
  • commit_description (str, tùy chọn) — Mô tả của commit được tạo
  • create_pr (boolean, tùy chọn) — Có tạo Pull Request với commit đó hay không. Mặc định là False. Nếu revision không được đặt, PR sẽ được mở đối với nhánh "main". Nếu revision được đặt và là một nhánh, PR sẽ được mở đối với nhánh này. Nếu revision được đặt và không phải là tên nhánh (ví dụ: một commit oid), RevisionNotFoundError sẽ được trả về bởi máy chủ.
  • parent_commit (str, tùy chọn) — OID / SHA của commit cha, dưới dạng chuỗi hex. Các dạng viết tắt (7 ký tự đầu tiên) cũng được hỗ trợ. Nếu được chỉ định và create_pr là False, commit sẽ thất bại nếu revision không trỏ đến parent_commit. Nếu được chỉ định và create_pr là True, pull request sẽ được tạo từ parent_commit. Việc chỉ định parent_commit đảm bảo rằng repo không bị thay đổi trước khi commit các thay đổi, và đặc biệt hữu ích nếu repo được cập nhật / commit đồng thời.
  • run_as_future (bool, tùy chọn) — Có chạy phương thức này ở nền hay không. Các tác vụ nền được chạy tuần tự mà không chặn luồng chính. Truyền run_as_future=True sẽ trả về một đối tượng Future. Mặc định là False.

Trả về

CommitInfo hoặc Future

Thư mục CommitInfo chứa thông tin về commit mới được tạo (commit hash, commit url, pr url, commit message,…). Nếu run_as_future=True được truyền vào, sẽ trả về một đối tượng Future chứa kết quả khi được thực thi.

Tải lên một tệp cục bộ (tối đa 50 GB) vào kho đã cho. Việc tải lên được thực hiện thông qua yêu cầu HTTP post và không yêu cầu cài đặt git hoặc git-lfs.

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ
  • 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, hoặc do kho được đặt ở chế độ private và bạn không có quyền truy cập.
  • RevisionNotFoundError Nếu không tìm thấy revision cần tải xuống.

upload_file giả định rằng repo đã tồn tại trên Hub. Nếu bạn gặp lỗi Client 404, hãy đảm bảo rằng bạn đã xác thực, token của bạn có các quyền cần thiết, và repo_id cùng repo_type được đặt đúng. Nếu repo chưa tồn tại, hãy tạo nó trước bằng create_repo().

Ví dụ:

>>> from huggingface_hub import upload_file

>>> with open("./local/filepath", "rb") as fobj:
...     upload_file(
...         path_or_fileobj=fileobj,
...         path_in_repo="remote/file/path.h5",
...         repo_id="username/my-dataset",
...         repo_type="dataset",
...         token="my_token",
...     )

>>> upload_file(
...     path_or_fileobj=".\\local\\file\\path",
...     path_in_repo="remote/file/path.h5",
...     repo_id="username/my-model",
...     token="my_token",
... )

>>> upload_file(
...     path_or_fileobj=".\\local\\file\\path",
...     path_in_repo="remote/file/path.h5",
...     repo_id="username/my-model",
...     token="my_token",
...     create_pr=True,
... )

upload_folder

< >

( repo_id: strfolder_path: str | Pathpath_in_repo: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonetoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = Noneallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonedelete_patterns: list[str] | str | None = Nonerun_as_future: bool = False ) → CommitInfo or Future

Tham số

  • repo_id (str) — Kho lưu trữ mà tệp sẽ được tải lên, ví dụ: "username/custom_transformers"
  • folder_path (str hoặc Path) — Đường dẫn đến thư mục cần tải lên trên hệ thống tệp cục bộ
  • path_in_repo (str, tùy chọn) — Đường dẫn tương đối của thư mục trong kho, ví dụ: "checkpoints/1fec34a/results". Mặc định sẽ là thư mục gốc của kho.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • repo_type (str, tùy chọn) — Đặt thành "dataset", "space" hoặc "kernel" nếu tải lên kho dataset, space hoặc kernel, None hoặc "model" nếu tải lên model. Mặc định là None.
  • revision (str, tùy chọn) — Phiên bản git để commit từ. Mặc định là đầu của nhánh "main".
  • commit_message (str, tùy chọn) — Tóm tắt / tiêu đề / dòng đầu tiên của commit được tạo. Mặc định là: f"Upload {path_in_repo} with huggingface_hub"
  • commit_description (str tùy chọn) — Mô tả của commit được tạo
  • create_pr (boolean, tùy chọn) — Có tạo Pull Request với commit đó hay không. Mặc định là False. PR luôn được mở đối với nhánh mặc định: việc đặt cả create_pr=True và revision sẽ gây ra ValueError. Lưu ý rằng mỗi lần gọi với create_pr=True sẽ mở một pull request mới: để tiếp tục một lần tải lên bị gián đoạn vào PR hiện có, hãy chạy lại với revision="refs/pr/N" thay vì vậy.
  • parent_commit (str, tuỳ chọn) — OID / SHA của commit cha, dưới dạng chuỗi hex. Các dạng viết tắt (7 ký tự đầu tiên) cũng được hỗ trợ. Nếu được chỉ định và create_pr là False, commit sẽ thất bại nếu revision không trỏ đến parent_commit. Việc chỉ định parent_commit đảm bảo rằng repo không bị thay đổi trước khi commit các thay đổi, và có thể đặc biệt hữu ích nếu repo được cập nhật / commit đồng thời. Nếu quá trình tải lên được chia thành nhiều commit (các thư mục lớn), parent_commit chỉ áp dụng cho commit đầu tiên.
  • allow_patterns (list[str] hoặc str, tùy chọn) — Nếu được cung cấp, chỉ các tệp khớp với ít nhất một mẫu mới được tải lên.
  • ignore_patterns (list[str] hoặc str, tùy chọn) — Nếu được cung cấp, các tệp khớp với bất kỳ mẫu nào sẽ không được tải lên.
  • delete_patterns (list[str] hoặc str, tùy chọn) — Nếu được cung cấp, các tệp từ xa khớp với bất kỳ mẫu nào trong danh sách sẽ bị xóa khỏi kho khi cam kết các tệp mới. Điều này hữu ích nếu bạn không biết tệp nào đã được tải lên. Lưu ý: để tránh sai lệch, tệp .gitattributes sẽ không bị xóa ngay cả khi nó khớp với mẫu.
  • run_as_future (bool, tùy chọn) — Có chạy phương thức này ở nền hay không. Các tác vụ nền được chạy tuần tự mà không chặn luồng chính. Truyền run_as_future=True sẽ trả về một đối tượng Future. Mặc định là False.

Trả về

CommitInfo hoặc Future

Thư mục CommitInfo chứa thông tin về commit mới được tạo (commit hash, commit url, pr url, commit message,…). Nếu run_as_future=True được truyền vào, sẽ trả về một đối tượng Future chứa kết quả khi được thực thi.

Tải lên một thư mục cục bộ lên kho đã cho. Việc tải lên được thực hiện thông qua các yêu cầu HTTP và không yêu cầu cài đặt git hoặc git-lfs.

Cấu trúc của thư mục sẽ được giữ nguyên. Các tệp có cùng tên đã có trong kho sẽ bị ghi đè. Các tệp khác sẽ không bị thay đổi.

Sử dụng các đối số allow_patterns và ignore_patterns để chỉ định các tệp cần tải lên. Các tham số này chấp nhận một mẫu duy nhất hoặc một danh sách các mẫu. Các mẫu là Standard Wildcards (mẫu globbing) như được tài liệu hóa tại đây. Nếu cả allow_patterns và ignore_patterns đều được cung cấp, cả hai ràng buộc đều được áp dụng. Mặc định, tất cả các tệp từ thư mục sẽ được tải lên.

Sử dụng đối số delete_patterns để chỉ định các tệp từ xa mà bạn muốn xóa. Kiểu đầu vào giống như của allow_patterns (xem bên trên). Nếu path_in_repo cũng được cung cấp, các mẫu sẽ được khớp với các đường dẫn tương đối so với thư mục này. Ví dụ, upload_folder(..., path_in_repo="experiment", delete_patterns="logs/*") sẽ xóa bất kỳ tệp từ xa nào dưới ./experiment/logs/. Lưu ý rằng tệp .gitattributes sẽ không bị xóa ngay cả khi nó khớp với các mẫu.

Bất kỳ thư mục .git/ nào có mặt trong bất kỳ thư mục con nào sẽ bị bỏ qua. Tuy nhiên, vui lòng lưu ý rằng tệp .gitignore không được tính đến.

Khi hf_xet được cài đặt (mặc định), các tệp được tải lên thông qua một pipeline dạng stream: quá trình tải lên bắt đầu trong khi thư mục vẫn đang được kiểm tra đối chiếu với Hub, các tệp được băm (hash) trong khi đang được chia nhỏ (chunk) để tải lên (chỉ đọc một lần), và các thư mục lớn được tự động cam kết (commit) thành nhiều lô để không vượt quá giới hạn của máy chủ (các cam kết tiếp theo sẽ có hậu tố (part N) trong thông điệp cam kết). Nếu quá trình tải lên bị gián đoạn, việc chạy lại cùng một lệnh sẽ tiếp tục quá trình đó: các tệp đã được cam kết sẽ bị bỏ qua và dữ liệu đã tải lên sẽ được khử trùng lặp. Khi hf_xet không được cài đặt, hệ thống sẽ chuyển sang tạo một cam kết duy nhất bằng create_commit().

Gây ra các lỗi sau:

  • HTTPError nếu API HuggingFace trả về một lỗi
  • ValueError nếu một số giá trị tham số không hợp lệ

upload_folder giả định rằng repo đã tồn tại trên Hub. Nếu bạn gặp lỗi Client 404, hãy đảm bảo rằng bạn đã xác thực, token của bạn có các quyền cần thiết, và repo_id cùng repo_type được đặt đúng. Nếu repo chưa tồn tại, hãy tạo nó trước bằng create_repo().

Ví dụ:

# Upload checkpoints folder except the log files
>>> upload_folder(
...     folder_path="local/checkpoints",
...     path_in_repo="remote/experiment/checkpoints",
...     repo_id="username/my-dataset",
...     repo_type="datasets",
...     token="my_token",
...     ignore_patterns="**/logs/*.txt",
... )

# Upload checkpoints folder including logs while deleting existing logs from the repo
# Useful if you don't know exactly which log files have already being pushed
>>> upload_folder(
...     folder_path="local/checkpoints",
...     path_in_repo="remote/experiment/checkpoints",
...     repo_id="username/my-dataset",
...     repo_type="datasets",
...     token="my_token",
...     delete_patterns="**/logs/*.txt",
... )

# Upload checkpoints folder while creating a PR
>>> upload_folder(
...     folder_path="local/checkpoints",
...     path_in_repo="remote/experiment/checkpoints",
...     repo_id="username/my-dataset",
...     repo_type="datasets",
...     token="my_token",
...     create_pr=True,
... )

verify_repo_checksums

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonelocal_dir: str | Path | None = Nonecache_dir: str | Path | None = Nonetoken: str | bool | None = None ) → FolderVerification

Tham số

  • repo_id (str) — Một namespace (người dùng hoặc tổ chức) và tên kho, phân tách bằng /.
  • repo_type (str, tùy chọn) — Loại kho cần lấy cây ("model", "dataset" hoặc "space". Mặc định là "model".
  • revision (str, tùy chọn) — Phiên bản của kho chứa mà bạn muốn lấy cây. Mặc định là nhánh "main".
  • local_dir (str hoặc Path, tùy chọn) — Thư mục cục bộ cần xác minh.
  • cache_dir (str hoặc Path, tùy chọn) — Thư mục cache cần kiểm tra.
  • token (Union[bool, str, None], optional) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.

Trả về

FolderVerification

kết quả có cấu trúc chứa các chi tiết xác minh.

Gây ra

RepositoryNotFoundError hoặc RevisionNotFoundError

  • RepositoryNotFoundError — Nếu không tìm thấy kho (lỗi 404): repo_id/repo_type sai, kho là riêng tư nhưng chưa xác thực hoặc kho không tồn tại.
  • RevisionNotFoundError — Nếu không tìm thấy revision (lỗi 404) trên repo.

Xác minh các tệp cục bộ của một kho với các mã kiểm tra trên Hub.

wait_for_job

< >

( job_id: str | list[str]timeout: float | None = Nonepoll_interval: float = 1.0stages: list[JobStage] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo or list[JobInfo]

Tham số

  • job_id (str hoặc list[str]) — ID của Job, hoặc danh sách các ID Job cần chờ. Nếu truyền vào một danh sách, một danh sách JobInfo sẽ được trả về (theo cùng thứ tự).
  • timeout (float, tùy chọn) — Thời gian tối đa để chờ Job hoàn thành, tính bằng giây. Nếu là None, sẽ chờ vô thời hạn.
  • poll_interval (float, tùy chọn) — Thời gian chờ giữa mỗi lần kiểm tra trạng thái, tính bằng giây. Mặc định là 1 giây.
  • stages (list[JobStage], tùy chọn) — Các giai đoạn cần chờ. Mặc định là các giai đoạn kết thúc ("COMPLETED", "CANCELED", "ERROR", "DELETED"). Truyền ví dụ [JobStage.RUNNING] để chờ Job bắt đầu chạy. Các giai đoạn kết thúc luôn dừng việc chờ bất kể giá trị này.
  • namespace (str, optional) — Namespace nơi Job(s) đang chạy. Mặc định là namespace của người dùng hiện tại.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Nếu không được cung cấp, token được lưu cục bộ sẽ được sử dụng, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Tham khảo: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Trả về

JobInfo hoặc list[JobInfo]

thông tin Job cuối cùng.

Gây ra

TimeoutError

  • TimeoutError — Nếu ít nhất một Job không đạt được một trong các giai đoạn đích sau timeout giây.

Chờ cho đến khi một hoặc nhiều Job tính toán trên hạ tầng Hugging Face đạt đến một giai đoạn nhất định.

Trạng thái của mỗi Job được kiểm tra (bằng inspect_job()) mỗi poll_interval giây cho đến khi giai đoạn của nó nằm trong số các stages (mặc định là các giai đoạn kết thúc: "COMPLETED", "CANCELED", "ERROR" hoặc "DELETED"). Đối tượng JobInfo cuối cùng sẽ được trả về trong mọi trường hợp: một Job thất bại hoặc bị hủy sẽ không gây ra ngoại lệ — hãy kiểm tra job.status.stage để xử lý kết quả.

Các giai đoạn cuối luôn dừng việc chờ, ngay cả khi không được liệt kê trong stages. Điều này tránh việc chờ vô hạn cho một giai đoạn mà Job sẽ không bao giờ đạt tới (ví dụ: chờ "RUNNING" trên một Job bị lỗi trong quá trình lập lịch).

Ví dụ:

>>> from huggingface_hub import run_job, wait_for_job
>>> job = run_job(image="python:3.12", command=["python", "-c", "print('Hello from HF compute!')"])
>>> wait_for_job(job_id=job.id).status.stage
'COMPLETED'

wait_for_space

< >

( repo_id: strtimeout: float | None = Nonepoll_interval: float = 1.0token: bool | str | None = None ) → SpaceRuntime

Tham số

  • repo_id (str) — ID của Space cần chờ. Ví dụ: "username/my-space".
  • timeout (float, tùy chọn) — Thời gian chờ tối đa tính bằng giây. Nếu là None, sẽ chờ vô thời hạn.
  • poll_interval (float, tùy chọn) — Số giây giữa các lần kiểm tra trạng thái. Mặc định là 1 giây.
  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ. Mặc định là token được lưu cục bộ, đây là phương thức xác thực được khuyến nghị. Đặt thành False để tắt xác thực. Xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Trả về

SpaceRuntime

Thông tin thời gian chạy cuối cùng khi Space đạt đến giai đoạn cuối.

Gây ra

TimeoutError

  • TimeoutError — Nếu Space chưa đạt đến giai đoạn cuối sau timeout giây.

Chờ cho đến khi một Space đạt đến giai đoạn cuối (không phải đang xây dựng/khởi động).

Các cuộc thăm dò get_space_runtime() mỗi poll_interval giây cho đến khi giai đoạn của Space không còn ở trạng thái trung gian (BUILDING, RUNNING_BUILDING, APP_STARTING, RUNNING_APP_STARTING). Trả về SpaceRuntime cuối cùng trong mọi trường hợp — kiểm tra runtime.stage để xử lý kết quả (ví dụ: RUNNING so với BUILD_ERROR).

Ví dụ:

>>> from huggingface_hub import restart_space, wait_for_space
>>> restart_space("username/my-space")
>>> runtime = wait_for_space("username/my-space")
>>> runtime.stage
'RUNNING'

whoami

< >

( token: bool | str | None = Nonecache: bool = False )

Tham số

  • token (bool hoặc str, tùy chọn) — Một token truy cập người dùng hợp lệ (chuỗi). Mặc định là token được lưu cục bộ, đây là phương pháp xác thực được khuyến nghị (xem https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Để tắt xác thực, truyền False.
  • cache (bool, tùy chọn) — Có nên lưu kết quả của cuộc gọi whoami cho các cuộc gọi tiếp theo hay không. Nếu xảy ra lỗi trong cuộc gọi đầu tiên, kết quả sẽ không được lưu. Mặc định là False.

Gọi HF API để biết “whoami”.

Nếu truyền cache=True, kết quả sẽ được lưu vào bộ nhớ đệm cho các lần gọi tiếp theo trong suốt thời gian tiến trình Python đang chạy. Điều này hữu ích nếu bạn dự định gọi whoami nhiều lần vì endpoint này bị giới hạn tần suất gọi (rate-limited) nghiêm ngặt vì lý do bảo mật.

API Dataclasses

AccessRequest

lớp huggingface_hub.hf_api.AccessRequest

< >

( username: str | Nonerequest_id: strfullname: str | Noneemail: str | Nonetimestamp: datetimestatus: Literal['pending', 'accepted', 'rejected']fields: dict[str, Any] | None = None )

Tham số

  • username (str, tùy chọn) — Tên người dùng của người đã yêu cầu quyền truy cập. None nếu kho được cấu hình để không chia sẻ tên người dùng của người yêu cầu. Trong trường hợp đó, hãy sử dụng request_id để chấp nhận, từ chối hoặc hủy yêu cầu.
  • request_id (str) — Id của yêu cầu truy cập. Luôn được đặt, ngay cả khi tên người dùng không được chia sẻ.
  • fullname (str, tùy chọn) — Họ và tên của người dùng đã yêu cầu quyền truy cập. None nếu kho được cấu hình để không chia sẻ tên người dùng của những người yêu cầu.
  • email (str, tùy chọn) — Email của người dùng đã yêu cầu quyền truy cập. None nếu người dùng được cấp quyền truy cập thủ công hoặc nếu kho được cấu hình để không chia sẻ email của người yêu cầu.
  • timestamp (datetime) — Thời điểm của yêu cầu.
  • status (Literal["pending", "accepted", "rejected"]) — Trạng thái của yêu cầu. Có thể là một trong ["pending", "accepted", "rejected"].
  • fields (dict[str, Any], tùy chọn) — Các trường bổ sung do người dùng điền vào biểu mẫu gate.

Cấu trúc dữ liệu chứa thông tin về một yêu cầu truy cập của người dùng.

BucketFile

lớp huggingface_hub.BucketFile

< >

( **kwargs )

Chứa thông tin về một tệp trong một bucket trên Hub. Đối tượng này được trả về bởi list_bucket_tree().

Tương tự như RepoFile nhưng dành cho các tệp trong các bucket.

BucketFileMetadata

lớp huggingface_hub.BucketFileMetadata

< >

( size: intxet_file_data: XetFileData )

Tham số

  • size (int) — Kích thước của tệp tính bằng byte.
  • xet_file_data (XetFileData) — Thông tin Xet cho tệp (hash và đường dẫn làm mới).

Cấu trúc dữ liệu chứa thông tin về một tệp trong bucket.

Được trả về bởi get_bucket_file_metadata().

BucketInfo

lớp huggingface_hub.BucketInfo

< >

( **kwargs )

Tham số

  • id (str) — ID của bucket.
  • private (bool) — Bucket có phải là riêng tư không.
  • created_at (datetime) — Ngày tạo bucket trên Hub.
  • size (int) — Kích thước của bucket tính bằng byte.
  • total_files (int) — Tổng số tệp trong bucket.

Chứa thông tin về một bucket trên Hub. Đối tượng này được trả về bởi bucket_info() và list_buckets().

BucketUrl

lớp huggingface_hub.BucketUrl

< >

( url: strendpoint: str = '' )

Tham số

Mô tả một URL bucket trên Hub.

BucketUrl được trả về bởi create_bucket(). Khi khởi tạo, URL được phân tích để điền vào các thuộc tính:

  • endpoint (str)
  • namespace (str)
  • bucket_id (str)
  • url (str)
  • uri (HfUri)

DatasetLeaderboardEntry

lớp huggingface_hub.DatasetLeaderboardEntry

< >

( **kwargs )

Tham số

  • rank (int) — Xếp hạng của mô hình trên bảng xếp hạng (bắt đầu từ 1).
  • model_id (str) — ID của model (ví dụ: "meta-llama/Llama-3-8b").
  • value (float) — Giá trị điểm đánh giá.
  • filename (str) — Tên của tệp kết quả chứa dữ liệu đánh giá.
  • verified (bool) — Kết quả đã được xác minh hay chưa.
  • source (dict[str, Any], tùy chọn) — Thông tin về nguồn của kết quả đánh giá. Chứa các khóa như "url", "name" và "isExternal". Không phải mục nào cũng có nguồn.
  • author (User hoặc Organization) — Tác giả của model, được phân tích dựa trên trường "type" trong phản hồi API.
  • pull_request (int, tùy chọn) — Số pull request liên quan đến mục trên bảng xếp hạng, nếu có.
  • notes (str, tùy chọn) — Ghi chú liên quan đến mục trên bảng xếp hạng, nếu có.

Chứa thông tin về một mục duy nhất trong bảng xếp hạng bộ dữ liệu trên Hub.

Bảng xếp hạng sắp xếp các mô hình dựa trên điểm đánh giá của chúng trên một bộ dữ liệu chuẩn (benchmark) nhất định. Đối tượng này được trả về bởi get_dataset_leaderboard(). Để lấy kết quả đánh giá cho một mô hình cụ thể trên các benchmark, hãy xem ModelInfo.eval_results (thông qua model_info() với expand=["evalResults"]) và EvalResultEntry.

EvalResultEntry

lớp huggingface_hub.EvalResultEntry

< >

( dataset_id: strtask_id: strvalue: typing.Anydataset_revision: str | None = Noneverify_token: str | None = Nonedate: str | None = Nonesource_url: str | None = Nonesource_name: str | None = Nonesource_user: str | None = Nonesource_org: str | None = Nonenotes: str | None = None )

Tham số

  • dataset_id (str) — ID của bộ dữ liệu benchmark từ Hub. Ví dụ: “cais/hle”, “Idavidrein/gpqa”.
  • task_id (str) — Định danh tác vụ trong bộ chuẩn. Ví dụ: “gpqa_diamond”.
  • value (Any) — Giá trị của chỉ số. Ví dụ: 20.90.
  • dataset_revision (str, tùy chọn) — SHA của Git cho bộ dữ liệu benchmark.
  • verify_token (str, tuỳ chọn) — Một chữ ký có thể được sử dụng để chứng minh rằng việc đánh giá có thể kiểm toán và tái tạo được một cách có thể chứng minh.
  • date (str, tùy chọn) — Thời điểm đánh giá được thực hiện (datetime ISO-8601). Mặc định là thời gian commit git.
  • source_url (str, tùy chọn) — Liên kết đến nguồn đánh giá (ví dụ: https://huggingface.co/spaces/SaylorTwift/smollm3-mmlu-pro). Bắt buộc nếu source_name, source_user, hoặc source_org được cung cấp.
  • source_name (str, tùy chọn) — Tên hiển thị cho nguồn. Ví dụ: “Eval Logs”.
  • source_user (str, tùy chọn) — Tên người dùng HF để ghi nhận nguồn gốc. Ví dụ: “celinah”.
  • source_org (str, tùy chọn) — Tên tổ chức HF để ghi nhận nguồn gốc. Ví dụ: “cais”.
  • notes (str, tùy chọn) — Chi tiết về cấu hình đánh giá. Ví dụ: “tools”, “no-tools”, “chain-of-thought”.

Mục kết quả đánh giá cho định dạng .eval_results/*.yaml.

Đại diện cho các điểm đánh giá được lưu trữ trong các kho mô hình, tự động hiển thị trên trang mô hình và bảng xếp hạng của bộ dữ liệu benchmark.

Đối với định dạng model-index cũ trong README.md, hãy sử dụng EvalResult thay thế.

Xem https://huggingface.co/docs/hub/eval-results để biết thêm chi tiết.

Ví dụ:

>>> from huggingface_hub import EvalResultEntry
>>> # Minimal example with required fields only
>>> result = EvalResultEntry(
...     dataset_id="Idavidrein/gpqa",
...     task_id="gpqa_diamond",
...     value=0.412,
... )
>>> # Full example with all fields
>>> result = EvalResultEntry(
...     dataset_id="cais/hle",
...     task_id="default",
...     value=20.90,
...     dataset_revision="5503434ddd753f426f4b38109466949a1217c2bb",
...     verify_token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
...     date="2025-01-15T10:30:00Z",
...     source_url="https://huggingface.co/datasets/cais/hle",
...     source_name="CAIS HLE",
...     source_org="cais",
...     notes="no-tools",
... )

SyncOperation

lớp huggingface_hub.SyncOperation

< >

( action: typing.Literal['upload', 'download', 'delete', 'skip']path: strsize: int | None = Nonereason: str = ''local_mtime: str | None = Noneremote_mtime: str | None = Nonebucket_file: huggingface_hub._buckets.BucketFile | None = None )

Đại diện cho một thao tác đồng bộ hóa cần thực hiện.

SyncPlan

lớp huggingface_hub.SyncPlan

< >

( source: strdest: strtimestamp: stroperations: list = <factory> )

Đại diện cho một kế hoạch đồng bộ hoàn chỉnh.

CommitInfo

lớp huggingface_hub.CommitInfo

< >

( commit_url: str*args**kwargs )

Tham số

  • commit_url (str) — Địa chỉ URL để tìm commit.
  • commit_message (str) — Tóm tắt (dòng đầu tiên) của commit đã được tạo.
  • commit_description (str) — Mô tả của commit đã được tạo. Có thể để trống.
  • oid (str) — ID hash của commit. Ví dụ: "91c54ad1727ee830252e457677f467be0bfd8a57".
  • pr_url (str, tùy chọn) — Url của PR đã được tạo, nếu có. Được điền khi create_pr=True được truyền vào.
  • pr_revision (str, tùy chọn) — Phiên bản của PR đã được tạo, nếu có. Được điền khi create_pr=True được truyền vào. Ví dụ: "refs/pr/1".
  • pr_num (int, tùy chọn) — Số của cuộc thảo luận PR đã được tạo, nếu có. Được điền khi create_pr=True được truyền vào. Có thể được truyền dưới dạng discussion_num trong get_discussion_details(). Ví dụ: 1.
  • repo_url (RepoUrl) — URL của repo cho commit chứa các thông tin như repo_id, repo_type, v.v.

Cấu trúc dữ liệu chứa thông tin về một commit mới được tạo.

Được trả về bởi bất kỳ phương thức nào tạo commit trên Hub: create_commit(), upload_file(), upload_folder(), delete_file(), delete_folder(). Nó kế thừa từ str để tương thích ngược, nhưng việc sử dụng các phương thức đặc thù của str đã bị ngừng hỗ trợ.

DatasetInfo

lớp huggingface_hub.DatasetInfo

< >

( **kwargs )

Tham số

  • id (str) — ID của bộ dữ liệu.
  • author (str) — Tác giả của bộ dữ liệu.
  • card_data (DatasetCardData, tùy chọn) — Metadata của Dataset Card dưới dạng đối tượng huggingface_hub.repocard_data.DatasetCardData.
  • citation (str, tùy chọn) — Thông tin trích dẫn cho bộ dữ liệu.
  • created_at (datetime, tùy chọn) — Ngày tạo kho trên Hub. Lưu ý rằng giá trị thấp nhất là 2022-03-02T23:29:04.000Z, tương ứng với ngày chúng tôi bắt đầu lưu trữ ngày tạo.
  • description (str, tùy chọn) — Mô tả của bộ dữ liệu.
  • disabled (bool, tùy chọn) — Kho có bị vô hiệu hóa hay không.
  • downloads (int) — Số lượt tải xuống của bộ dữ liệu trong 30 ngày qua.
  • downloads_all_time (int) — Tổng số lượt tải xuống của bộ dữ liệu kể từ khi được tạo.
  • gated (Literal["auto", "manual", False], tùy chọn) — Kho có được bảo vệ hay không. Nếu có, việc phê duyệt là thủ công hay tự động.
  • last_modified (datetime, tùy chọn) — Ngày của commit cuối cùng vào kho.
  • likes (int) — Số lượt thích của bộ dữ liệu.
  • main_size (int, tùy chọn) — Kích thước tính bằng byte của nhánh chính của bộ dữ liệu.
  • paperswithcode_id (str, tùy chọn) — ID Papers with code của bộ dữ liệu.
  • private (bool) — Kho có phải là kho riêng tư không.
  • resource_group (dict, tùy chọn) — Thông tin nhóm tài nguyên cho bộ dữ liệu.
  • sha (str) — SHA của kho tại phiên bản cụ thể này.
  • siblings (list[RepoSibling]) — Danh sách các đối tượng huggingface_hub.hf_api.RepoSibling cấu thành nên bộ dữ liệu.
  • tags (list[str]) — Danh sách các thẻ của bộ dữ liệu.
  • trending_score (int, tùy chọn) — Điểm xu hướng của bộ dữ liệu.
  • used_storage (int, tùy chọn) — Kích thước của bộ dữ liệu trên Hub, tính bằng byte.

Chứa thông tin về một bộ dữ liệu trên Hub. Đối tượng này được trả về bởi dataset_info() và list_datasets().

Hầu hết các thuộc tính của lớp này là tùy chọn. Điều này là do dữ liệu được trả về bởi Hub phụ thuộc vào truy vấn được thực hiện. Nhìn chung, truy vấn càng cụ thể thì càng nhiều thông tin được trả về. Ngược lại, khi liệt kê các bộ dữ liệu sử dụng list_datasets(), chỉ một tập con các thuộc tính được trả về.

DryRunFileInfo

lớp huggingface_hub.DryRunFileInfo

< >

( commit_hash: strfile_size: int | Nonefilename: strlocal_path: stris_cached: boolwill_download: bool )

Tham số

  • commit_hash (str) — commit_hash liên quan đến tệp.
  • file_size (int, tùy chọn) — Kích thước của tệp, nếu đã biết. Trong trường hợp tệp LFS, chứa kích thước của tệp LFS thực tế, không phải con trỏ.
  • filename (str) — Tên tệp trong kho.
  • is_cached (bool) — Cho biết tệp đã được lưu trong bộ nhớ đệm cục bộ hay chưa.
  • will_download (bool) — Liệu tệp có sẽ được tải xuống nếu hf_hub_download được gọi với dry_run=False hay không. Trên thực tế, will_download là True nếu tệp không được lưu trong bộ nhớ đệm hoặc nếu force_download=True.

Thông tin được trả về khi thực hiện chạy thử (dry run) việc tải xuống tệp.

Được trả về bởi hf_hub_download() khi dry_run=True.

DuplicatedRepoUrl

lớp huggingface_hub.DuplicatedRepoUrl

< >

( url: Anyendpoint: str | None = None )

Tham số

  • files_copy_pending (bool) — True nếu các tệp LFS/Xet của kho mới vẫn đang được sao chép ở nền. Cho đến khi quá trình sao chép hoàn tất, việc tải xuống các tệp này có thể thất bại.

RepoUrl được trả về bởi duplicate_repo().

GitRefInfo

lớp huggingface_hub.GitRefInfo

< >

( name: strref: strtarget_commit: str )

Tham số

  • name (str) — Tên của tham chiếu (ví dụ: tên tag hoặc tên nhánh).
  • ref (str) — Tham chiếu git đầy đủ trên Hub (ví dụ: "refs/heads/main" hoặc "refs/tags/v1.0").
  • target_commit (str) — OID của commit đích cho ref (ví dụ: "e7da7f221d5bf496a48136c0cd264e630fe9fcc8")

Chứa thông tin về một tham chiếu git cho một kho trên Hub.

GitCommitInfo

lớp huggingface_hub.GitCommitInfo

< >

( commit_id: strauthors: list[str]created_at: datetimetitle: strmessage: strformatted_title: str | Noneformatted_message: str | None )

Tham số

  • commit_id (str) — OID của commit (ví dụ: "e7da7f221d5bf496a48136c0cd264e630fe9fcc8")
  • authors (list[str]) — Danh sách các tác giả của commit.
  • created_at (datetime) — Thời điểm tạo commit.
  • title (str) — Tiêu đề của commit. Đây là giá trị văn bản tự do do các tác giả nhập vào.
  • message (str) — Mô tả của commit. Đây là giá trị văn bản tự do do các tác giả nhập vào.
  • formatted_title (str) — Tiêu đề của commit được định dạng dưới dạng HTML. Chỉ được trả về nếu formatted=True được đặt.
  • formatted_message (str) — Mô tả của commit được định dạng dưới dạng HTML. Chỉ được trả về nếu formatted=True được đặt.

Chứa thông tin về một commit git cho một kho trên Hub. Xem list_repo_commits() để biết thêm chi tiết.

GitRefs

lớp huggingface_hub.GitRefs

< >

( branches: list[GitRefInfo]converts: list[GitRefInfo]tags: list[GitRefInfo]pull_requests: list[GitRefInfo] | None = None )

Tham số

  • branches (list[GitRefInfo]) — Một danh sách GitRefInfo chứa thông tin về các nhánh trong kho.
  • converts (list[GitRefInfo]) — Một danh sách GitRefInfo chứa thông tin về các ref “convert” trong kho. Converts là các ref được sử dụng (nội bộ) để đẩy dữ liệu đã tiền xử lý trong các kho Dataset.
  • tags (list[GitRefInfo]) — Một danh sách GitRefInfo chứa thông tin về các tag trên kho.
  • pull_requests (list[GitRefInfo], tùy chọn) — Một danh sách GitRefInfo chứa thông tin về các pull request trên repo. Chỉ được trả về nếu include_prs=True được đặt.

Chứa thông tin về tất cả các tham chiếu git cho một kho trên Hub.

Object được trả về bởi list_repo_refs().

InferenceProviderMapping

lớp huggingface_hub.hf_api.InferenceProviderMapping

< >

( **kwargs )

KernelInfo

lớp huggingface_hub.KernelInfo

< >

( **kwargs )

Tham số

  • id (str) — ID của kho kernel.
  • author (str, tùy chọn) — Tác giả của kho kernel.
  • downloads (int, tùy chọn) — Số lượt tải xuống của kho kernel trong 30 ngày qua.
  • gated (Literal["auto", "manual", False], tùy chọn) — Kho có được bảo vệ hay không. Nếu có, việc phê duyệt là thủ công hay tự động.
  • last_modified (datetime, tùy chọn) — Ngày của commit cuối cùng vào kho.
  • likes (int, tùy chọn) — Số lượt thích của kho kernel.
  • private (bool, tuỳ chọn) — Kho có phải là kho riêng tư không.
  • sha (str, tùy chọn) — SHA của kho tại bản sửa đổi cụ thể này.

Chứa thông tin về một kho kernel trên Hub. Đối tượng này được trả về bởi kernel_info().

LFSFileInfo

lớp huggingface_hub.hf_api.LFSFileInfo

< >

( **kwargs )

Tham số

  • file_oid (str) — ID đối tượng SHA-256 của tệp. Đây là định danh cần truyền khi xóa vĩnh viễn tệp.
  • filename (str) — Tên tệp có thể có cho đối tượng LFS. Xem ghi chú ở trên để biết thêm thông tin.
  • oid (str) — OID của đối tượng LFS.
  • pushed_at (datetime) — Thời điểm đối tượng LFS được đẩy lên kho.
  • ref (str, tùy chọn) — Ref nơi đối tượng LFS đã được đẩy lên (nếu có).
  • size (int) — Kích thước của đối tượng LFS.

Chứa thông tin về một tệp được lưu trữ dưới dạng LFS trên một kho trên Hub.

Được sử dụng trong ngữ cảnh liệt kê và xóa vĩnh viễn các tệp LFS khỏi kho để giải phóng dung lượng. Xem list_lfs_files() và permanently_delete_lfs_files() để biết thêm chi tiết.

Các tệp Git LFS được theo dõi bằng các ID đối tượng SHA-256 thay vì đường dẫn tệp, nhằm tối ưu hiệu suất. Cách tiếp cận này là cần thiết vì một đối tượng duy nhất có thể được tham chiếu bởi nhiều đường dẫn khác nhau qua các commit khác nhau, khiến việc tìm kiếm và giải quyết các kết nối này trở nên không thực tế. Xem tài liệu của chúng tôi để tìm hiểu cách biết tệp nào liên kết với mỗi SHA.

Ví dụ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")

# Filter files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))

# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)

ModelInfo

lớp huggingface_hub.ModelInfo

< >

( **kwargs )

Tham số

  • id (str) — ID của model.
  • author (str, tùy chọn) — Tác giả của mô hình.
  • base_models (list[str], tùy chọn) — Danh sách các mô hình cơ sở mà mô hình này được phát triển từ đó.
  • card_data (ModelCardData, tùy chọn) — Metadata của Model Card dưới dạng đối tượng huggingface_hub.repocard_data.ModelCardData.
  • children_model_count (int, tùy chọn) — Số lượng mô hình con được suy ra từ mô hình này.
  • config (dict, tùy chọn) — Cấu hình mô hình.
  • created_at (datetime, tùy chọn) — Ngày tạo kho trên Hub. Lưu ý rằng giá trị thấp nhất là 2022-03-02T23:29:04.000Z, tương ứng với ngày chúng tôi bắt đầu lưu trữ ngày tạo.
  • disabled (bool, tùy chọn) — Kho có bị vô hiệu hóa hay không.
  • downloads (int) — Số lượt tải xuống của mô hình trong 30 ngày qua.
  • downloads_all_time (int) — Tổng số lượt tải xuống của mô hình kể từ khi được tạo.
  • eval_results (list[EvalResultEntry], tùy chọn) — Kết quả đánh giá của mô hình.
  • gated (Literal["auto", "manual", False], tùy chọn) — Kho có được bảo vệ hay không. Nếu có, việc phê duyệt là thủ công hay tự động.
  • gguf (dict, tùy chọn) — Thông tin GGUF của mô hình.
  • inference (Literal["warm"], tùy chọn) — Trạng thái của mô hình trên các nhà cung cấp suy luận. Warm nếu mô hình được phục vụ bởi ít nhất một nhà cung cấp.
  • inference_provider_mapping (list[InferenceProviderMapping], tùy chọn) — Một danh sách các InferenceProviderMapping được sắp xếp theo thứ tự nhà cung cấp của người dùng.
  • last_modified (datetime, tùy chọn) — Ngày của commit cuối cùng vào kho.
  • library_name (str, tùy chọn) — Thư viện liên quan đến mô hình.
  • likes (int) — Số lượt thích của mô hình.
  • mask_token (str, tùy chọn) — Token mask được mô hình sử dụng.
  • model_index (dict, tùy chọn) — Chỉ mục mô hình để đánh giá.
  • pipeline_tag (str, tùy chọn) — Thẻ pipeline liên quan đến mô hình.
  • private (bool) — Kho có phải là kho riêng tư không.
  • resource_group (dict, tùy chọn) — Thông tin nhóm tài nguyên cho mô hình.
  • safetensors (SafeTensorsInfo, tùy chọn) — Thông tin safetensors của mô hình.
  • security_repo_status (dict, tùy chọn) — Trạng thái quét bảo mật của model.
  • sha (str, tùy chọn) — SHA của kho tại bản sửa đổi cụ thể này.
  • siblings (list[RepoSibling]) — Danh sách các đối tượng huggingface_hub.hf_api.RepoSibling cấu thành nên model.
  • spaces (list[str], tùy chọn) — Danh sách các space sử dụng mô hình.
  • tags (list[str]) — Danh sách các thẻ của mô hình. So với card_data.tags, danh sách này chứa các thẻ bổ sung được tính toán bởi Hub (ví dụ: các thư viện được hỗ trợ, arXiv của mô hình).
  • transformers_info (TransformersInfo, tùy chọn) — Thông tin cụ thể của Transformers (auto class, processor, v.v.) liên quan đến mô hình.
  • trending_score (int, tùy chọn) — Điểm xu hướng của mô hình.
  • used_storage (int, tùy chọn) — Kích thước của mô hình trên Hub, tính bằng byte.
  • widget_data (Any, tùy chọn) — Dữ liệu widget liên quan đến mô hình.

Chứa thông tin về một mô hình trên Hub. Đối tượng này được trả về bởi model_info() và list_models().

Hầu hết các thuộc tính của lớp này là tùy chọn. Điều này là do dữ liệu được trả về bởi Hub phụ thuộc vào truy vấn được thực hiện. Nhìn chung, truy vấn càng cụ thể thì càng nhiều thông tin được trả về. Ngược lại, khi liệt kê các mô hình sử dụng list_models(), chỉ một tập con các thuộc tính được trả về.

RepoSibling

lớp huggingface_hub.hf_api.RepoSibling

< >

( rfilename: strsize: int | None = Noneblob_id: str | None = Nonelfs: BlobLfsInfo | None = None )

Tham số

  • rfilename (str) — tên tệp, tương đối so với gốc của kho.
  • size (int, tùy chọn) — Kích thước của tệp, tính bằng byte. Thuộc tính này được định nghĩa khi đối số files_metadata của repo_info() được đặt thành True. Ngược lại, giá trị là None.
  • blob_id (str, tuỳ chọn) — OID git của tệp. Thuộc tính này được định nghĩa khi đối số files_metadata của repo_info() được đặt thành True. Ngược lại, giá trị là None.
  • lfs (BlobLfsInfo, tuỳ chọn) — Dữ liệu metadata LFS của tệp. Thuộc tính này được định nghĩa khi đối số files_metadata của repo_info() được đặt thành True và tệp được lưu trữ bằng Git LFS. Ngược lại, giá trị là None.

Chứa thông tin cơ bản về một tệp trong kho trên Hub.

Tất cả các thuộc tính của lớp này đều là tùy chọn ngoại trừ rfilename. Điều này là do chỉ tên tệp được trả về khi liệt kê các kho trên Hub (với list_models(), list_datasets() hoặc list_spaces()). Nếu bạn cần thêm thông tin như kích thước tệp, blob id hoặc chi tiết lfs, bạn phải yêu cầu chúng cụ thể từ từng kho một (sử dụng model_info(), dataset_info() hoặc space_info()) vì điều này đặt thêm các ràng buộc lên máy chủ backend để thu thập những thông tin này.

RepoFile

lớp huggingface_hub.RepoFile

< >

( **kwargs )

Tham số

  • path (str) — đường dẫn tệp tương đối so với gốc kho.
  • size (int) — Kích thước tệp, tính bằng byte.
  • blob_id (str) — OID git của tệp.
  • lfs (BlobLfsInfo, tùy chọn) — Dữ liệu metadata LFS của tệp.
  • xet_hash (str, tuỳ chọn) — Băm Xet của tệp.
  • last_commit (LastCommitInfo, tuỳ chọn) — Dữ liệu metadata của commit cuối cùng của tệp. Chỉ được định nghĩa nếu list_repo_tree() và get_paths_info() được gọi với expand=True.
  • security (BlobSecurityInfo, tùy chọn) — Dữ liệu metadata của việc quét bảo mật tệp. Chỉ được định nghĩa nếu list_repo_tree() và get_paths_info() được gọi với expand=True.

Chứa thông tin về một tệp trên Hub.

RepoUrl

lớp huggingface_hub.RepoUrl

< >

( url: Anyendpoint: str | None = None )

Tham số

Gây ra

HfUriError

  • HfUriError — Nếu URL không thể được phân tích (ví dụ: kho một đoạn chính tắc, hoặc repo_type không xác định).

Lớp con của str mô tả một URL kho trên Hub.

RepoUrl được trả về bởi HfApi.create_repo. Nó kế thừa từ str để đảm bảo tương thích ngược. Khi khởi tạo, URL được phân tích để điền vào các thuộc tính:

  • endpoint (str)
  • namespace (str)
  • repo_name (str)
  • repo_id (str)
  • repo_type (Literal["model", "dataset", "space"])
  • url (str)

Ví dụ:

>>> RepoUrl('https://huggingface.co/openai-community/gpt2')
RepoUrl('https://huggingface.co/openai-community/gpt2', endpoint='https://huggingface.co', repo_type='model', repo_id='openai-community/gpt2')

>>> RepoUrl('https://huggingface.co/proxy/hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://huggingface.co/proxy/hub-ci.huggingface.co')
RepoUrl('https://huggingface.co/proxy/hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://huggingface.co/proxy/hub-ci.huggingface.co', repo_type='dataset', repo_id='dummy_user/dummy_dataset')

>>> RepoUrl('hf://datasets/my-user/my-dataset')
RepoUrl('hf://datasets/my-user/my-dataset', endpoint='https://huggingface.co', repo_type='dataset', repo_id='user/dataset')

>>> HfApi.create_repo("dummy_model")
RepoUrl('https://huggingface.co/Wauplin/dummy_model', endpoint='https://huggingface.co', repo_type='model', repo_id='Wauplin/dummy_model')

SafetensorsRepoMetadata

lớp huggingface_hub.utils.SafetensorsRepoMetadata

< >

( metadata: dict | Nonesharded: boolweight_map: dictfiles_metadata: dict )

Tham số

  • metadata (dict, tùy chọn) — Dữ liệu mô tả chứa trong tệp ‘model.safetensors.index.json’, nếu tệp này tồn tại. Chỉ được điền cho các mô hình phân mảnh.
  • sharded (bool) — Chỉ định xem kho có chứa mô hình phân mảnh hay không.
  • weight_map (dict[str, str]) — Bản đồ của tất cả các trọng số. Các khóa là tên tensor và các giá trị là tên tệp của các tệp chứa các tensor.
  • files_metadata (dict[str, SafetensorsFileMetadata]) — Bản đồ chứa metadata của tất cả các tệp. Các khóa là tên tệp và các giá trị là metadata của tệp tương ứng, dưới dạng một đối tượng SafetensorsFileMetadata.
  • parameter_count (dict[str, int]) — Bản đồ số lượng tham số theo từng kiểu dữ liệu. Các khóa là kiểu dữ liệu và các giá trị là số lượng tham số của kiểu dữ liệu đó.

Metadata cho một kho Safetensors.

Một repo được coi là repo Safetensors nếu nó chứa tệp trọng số ‘model.safetensors’ (mô hình không chia sẻ) hoặc tệp chỉ mục ‘model.safetensors.index.json’ (mô hình phân mảnh) ở thư mục gốc.

Lớp này được trả về bởi get_safetensors_metadata().

Để biết thêm chi tiết về định dạng safetensors, hãy xem https://huggingface.co/docs/safetensors/index#format.

SafetensorsFileMetadata

lớp huggingface_hub.utils.SafetensorsFileMetadata

< >

( metadata: dicttensors: dict )

Tham số

  • metadata (dict) — Dữ liệu mô tả chứa trong tệp.
  • tensors (dict[str, TensorInfo]) — Bản đồ của tất cả các tensor. Các khóa là tên tensor và các giá trị là thông tin về tensor tương ứng, dưới dạng đối tượng TensorInfo.
  • parameter_count (dict[str, int]) — Bản đồ số lượng tham số theo từng kiểu dữ liệu. Các khóa là kiểu dữ liệu và các giá trị là số lượng tham số của kiểu dữ liệu đó.

Metadata cho tệp Safetensors được lưu trữ trên Hub.

Lớp này được trả về bởi parse_safetensors_file_metadata().

Để biết thêm chi tiết về định dạng safetensors, hãy xem https://huggingface.co/docs/safetensors/index#format.

SpaceInfo

lớp huggingface_hub.SpaceInfo

< >

( **kwargs )

Tham số

  • id (str) — ID của Space.
  • author (str, tùy chọn) — Tác giả của Space.
  • card_data (SpaceCardData, tùy chọn) — Space Card Metadata dưới dạng đối tượng huggingface_hub.repocard_data.SpaceCardData.
  • created_at (datetime, tùy chọn) — Ngày tạo kho trên Hub. Lưu ý rằng giá trị thấp nhất là 2022-03-02T23:29:04.000Z, tương ứng với ngày chúng tôi bắt đầu lưu trữ ngày tạo.
  • datasets (list[str], tùy chọn) — Danh sách các bộ dữ liệu được Space sử dụng.
  • disabled (bool, tùy chọn) — Không gian có bị vô hiệu hóa hay không.
  • gated (Literal["auto", "manual", False], tùy chọn) — Kho có được bảo vệ hay không. Nếu có, việc phê duyệt là thủ công hay tự động.
  • host (str, tùy chọn) — URL của máy chủ cho Space.
  • last_modified (datetime, tùy chọn) — Ngày của commit cuối cùng vào kho.
  • likes (int) — Số lượt thích của Space.
  • models (list[str], tùy chọn) — Danh sách các model được Space sử dụng.
  • private (bool) — Kho có phải là kho riêng tư không.
  • region (Literal["us", "eu"], tùy chọn) — Khu vực đám mây nơi Space được lưu trữ.
  • resource_group (dict, tùy chọn) — Thông tin nhóm tài nguyên của Space.
  • runtime (SpaceRuntime, tùy chọn) — Thông tin runtime của Space dưới dạng đối tượng huggingface_hub.hf_api.SpaceRuntime.
  • sdk (str, tùy chọn) — SDK được sử dụng bởi Space.
  • sha (str, tùy chọn) — SHA của kho tại bản sửa đổi cụ thể này.
  • siblings (list[RepoSibling]) — Danh sách các đối tượng huggingface_hub.hf_api.RepoSibling cấu thành nên Space.
  • subdomain (str, tùy chọn) — Subdomain của Space.
  • tags (list[str]) — Danh sách các thẻ của Space.
  • trending_score (int, tùy chọn) — Điểm xu hướng của Space.
  • used_storage (int, tùy chọn) — Kích thước của Space trên Hub tính bằng byte.

Chứa thông tin về một Space trên Hub. Đối tượng này được trả về bởi space_info() và list_spaces().

Hầu hết các thuộc tính của lớp này là tùy chọn. Điều này là do dữ liệu được trả về bởi Hub phụ thuộc vào truy vấn được thực hiện. Nhìn chung, truy vấn càng cụ thể thì càng nhiều thông tin được trả về. Ngược lại, khi liệt kê các space sử dụng list_spaces(), chỉ một tập con các thuộc tính được trả về.

SpaceSearchResult

lớp huggingface_hub.SpaceSearchResult

< >

( data: dict )

Tham số

  • id (str) — ID của Space (ví dụ: "username/repo-name").
  • author (str) — Tác giả của Space.
  • title (str) — Tiêu đề hiển thị của Space.
  • emoji (str or None) — Emoji icon of the Space.
  • sdk (str hoặc None) — SDK được sử dụng bởi Space (ví dụ: "gradio", "docker", "static").
  • likes (int) — Số lượt thích.
  • private (bool) — Xác định xem Space có phải là riêng tư hay không.
  • tags (list[str] hoặc None) — Danh sách các thẻ.
  • runtime (SpaceRuntime hoặc None) — Thông tin về thời gian thực thi (giai đoạn, phần cứng, v.v.).
  • ai_short_description (str hoặc None) — Mô tả ngắn do AI tạo ra.
  • ai_category (str hoặc None) — Danh mục do AI tạo ra (ví dụ: "Image Generation").
  • semantic_relevancy_score (float hoặc None) — Điểm liên quan ngữ nghĩa (0-1) so với truy vấn tìm kiếm.
  • trending_score (int hoặc None) — Điểm xu hướng.

Một kết quả duy nhất từ API tìm kiếm ngữ nghĩa của Spaces.

Được trả về bởi HfApi.search_spaces().

TensorInfo

lớp huggingface_hub.utils.TensorInfo

< >

( dtype: typing.Literal['F64', 'F32', 'F16', 'BF16', 'I64', 'I32', 'I16', 'I8', 'U8', 'U3', 'BOOL']shape: listdata_offsets: tuple )

Tham số

  • dtype (str) — Kiểu dữ liệu của tensor (“F64”, “F32”, “F16”, “BF16”, “I64”, “I32”, “I16”, “I8”, “U8”, “U3”, “BOOL”).
  • shape (list[int]) — Hình dạng của tensor.
  • data_offsets (tuple[int, int]) — Các offset của dữ liệu trong tệp dưới dạng tuple [BEGIN, END].
  • parameter_count (int) — Số lượng tham số trong tensor.

Thông tin về một tensor.

Để biết thêm chi tiết về định dạng safetensors, hãy xem https://huggingface.co/docs/safetensors/index#format.

Người dùng

lớp huggingface_hub.User

< >

( **kwargs )

Tham số

  • username (str) — Tên của người dùng trên Hub (duy nhất).
  • fullname (str) — Họ và tên đầy đủ của người dùng.
  • avatar_url (str) — URL của avatar người dùng.
  • details (str, tùy chọn) — Chi tiết của người dùng.
  • is_following (bool, tùy chọn) — Người dùng đã xác thực có đang theo dõi người dùng này hay không.
  • is_pro (bool, tùy chọn) — Liệu người dùng có phải là người dùng pro hay không.
  • num_models (int, tùy chọn) — Số lượng mô hình do người dùng tạo ra.
  • num_datasets (int, tùy chọn) — Số lượng bộ dữ liệu do người dùng tạo.
  • num_spaces (int, tùy chọn) — Số lượng không gian do người dùng tạo.
  • num_discussions (int, tùy chọn) — Số lượng cuộc thảo luận do người dùng khởi tạo.
  • num_papers (int, tùy chọn) — Số lượng bài báo do người dùng viết.
  • num_upvotes (int, tùy chọn) — Số lượt upvote mà người dùng nhận được.
  • num_likes (int, tùy chọn) — Số lượt thích do người dùng thực hiện.
  • num_following (int, tùy chọn) — Số lượng người dùng mà người dùng này đang theo dõi.
  • num_followers (int, tùy chọn) — Số lượng người dùng đang theo dõi người dùng này.
  • orgs (list of Organization) — Danh sách các tổ chức mà người dùng là thành viên.

Chứa thông tin về một người dùng trên Hub.

UserLikes

lớp huggingface_hub.UserLikes

< >

( user: strtotal: intdatasets: list[str]kernels: list[str]models: list[str]spaces: list[str] )

Tham số

  • user (str) — Tên của người dùng mà chúng ta đã lấy các lượt thích.
  • total (int) — Tổng số lượt thích.
  • datasets (list[str]) — Danh sách các datasets được người dùng thích (dưới dạng repo_ids).
  • kernels (list[str]) — Danh sách các kernel được người dùng thích (dưới dạng repo_ids).
  • models (list[str]) — Danh sách các model mà người dùng đã thích (dưới dạng repo_ids).
  • spaces (list[str]) — Danh sách các spaces được người dùng thích (dưới dạng repo_ids).

Chứa thông tin về các mục người dùng thích trên Hub.

WebhookInfo

lớp huggingface_hub.WebhookInfo

< >

( id: strurl: str | Nonejob: JobSpec | Nonewatched: list[WebhookWatchedItem]domains: list[constants.WEBHOOK_DOMAIN_T]secret: str | Nonedisabled: bool )

Tham số

  • id (str) — ID của webhook.
  • url (str, tùy chọn) — URL của webhook.
  • job (JobSpec, tùy chọn) — Quy cách của Job cần kích hoạt.
  • watched (list[WebhookWatchedItem]) — Danh sách các mục được webhook theo dõi, xem WebhookWatchedItem.
  • domains (list[WEBHOOK_DOMAIN_T]) — Danh sách các domain mà webhook đang theo dõi. Có thể là một trong ["repo", "discussion"].
  • secret (str, tùy chọn) — Bí mật của webhook.
  • disabled (bool) — Xác định xem webhook có bị vô hiệu hóa hay không.

Cấu trúc dữ liệu chứa thông tin về một webhook.

Một trong url hoặc job được chỉ định, nhưng không phải cả hai.

WebhookWatchedItem

lớp huggingface_hub.WebhookWatchedItem

< >

( type: Literal['bucket', 'dataset', 'model', 'org', 'space', 'user']name: str )

Tham số

  • type (Literal["bucket", "dataset", "model", "org", "space", "user"]) — Loại của mục cần theo dõi. Có thể là một trong ["bucket", "dataset", "model", "org", "space", "user"].
  • name (str) — Tên của mục cần theo dõi. Có thể là tên người dùng, tên tổ chức, tên model, tên dataset, tên space hoặc tên bucket.

Cấu trúc dữ liệu chứa thông tin về các mục được theo dõi bởi một webhook.

CommitOperation

Dưới đây là các giá trị được hỗ trợ cho CommitOperation():

lớp huggingface_hub.CommitOperationAdd

< >

( path_in_repo: strpath_or_fileobj: str | pathlib.Path | bytes | typing.BinaryIO )

Tham số

  • path_in_repo (str) — Đường dẫn tệp tương đối trong kho, ví dụ: "checkpoints/1fec34a/weights.bin"
  • path_or_fileobj (str, Path, bytes, hoặc BinaryIO) — Một trong các lựa chọn sau:
    • đường dẫn đến một tệp cục bộ (dưới dạng str hoặc pathlib.Path) để tải lên
    • một bộ đệm các byte (bytes) chứa nội dung của tệp cần tải lên
    • một “file object” (lớp con của io.BufferedIOBase), thường được lấy bằng open(path, "rb"). Nó phải hỗ trợ các phương thức seek() và tell().

Gây ra

ValueError

  • ValueError — Nếu path_or_fileobj không phải là một trong str, Path, bytes hoặc io.BufferedIOBase.
  • ValueError — Nếu path_or_fileobj là str hoặc Path nhưng không phải là đường dẫn đến một tệp hiện có.
  • ValueError — Nếu path_or_fileobj là một io.BufferedIOBase nhưng không hỗ trợ cả seek() và tell().

Cấu trúc dữ liệu chứa thông tin cần thiết để tải lên tệp lên một kho trên Hub.

as_file

< >

( with_tqdm: bool = False )

Tham số

  • with_tqdm (bool, tùy chọn, mặc định là False) — Nếu là True, việc lặp qua đối tượng tệp sẽ hiển thị thanh tiến trình. Chỉ hoạt động nếu đối tượng dạng tệp là đường dẫn đến một tệp. Không hỗ trợ bytes thuần và buffer.

Một trình quản lý ngữ cảnh (context manager) trả về một đối tượng giống tệp (file-like object) cho phép đọc dữ liệu cơ bản phía sau path_or_fileobj.

Ví dụ:

>>> operation = CommitOperationAdd(
...        path_in_repo="remote/dir/weights.h5",
...        path_or_fileobj="./local/weights.h5",
... )
CommitOperationAdd(path_in_repo='remote/dir/weights.h5', path_or_fileobj='./local/weights.h5')

>>> with operation.as_file() as file:
...     content = file.read()

>>> with operation.as_file(with_tqdm=True) as file:
...     while True:
...         data = file.read(1024)
...         if not data:
...              break
config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]

>>> with operation.as_file(with_tqdm=True) as file:
...     httpx2.put(..., data=file)
config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]

b64content

< >

( )

Nội dung được mã hóa base64 của path_or_fileobj

Trả về: bytes

lớp huggingface_hub.CommitOperationDelete

< >

( path_in_repo: stris_folder: typing.Union[bool, typing.Literal['auto']] = 'auto' )

Tham số

  • path_in_repo (str) — Đường dẫn tệp tương đối trong repo, ví dụ: "checkpoints/1fec34a/weights.bin" cho một tệp hoặc "checkpoints/1fec34a/" cho một thư mục.
  • is_folder (bool hoặc Literal["auto"], tùy chọn) — Xác định xem Thao tác Xóa có áp dụng cho thư mục hay không. Nếu là “auto”, loại đường dẫn (tệp hoặc thư mục) sẽ được suy đoán tự động bằng cách kiểm tra xem đường dẫn có kết thúc bằng ”/” (thư mục) hay không (tệp). Để đặt rõ loại đường dẫn, bạn có thể đặt is_folder=True hoặc is_folder=False.

Cấu trúc dữ liệu chứa thông tin cần thiết để xóa một tệp hoặc một thư mục khỏi một kho lưu trữ trên Hub.

lớp huggingface_hub.CommitOperationCopy

< >

( src_path_in_repo: strpath_in_repo: strsrc_revision: str | None = Nonesrc_repo_id: str | None = Nonesrc_repo_type: str | None = None_src_oid: str | None = None_dest_oid: str | None = None_is_duplicated: bool = False )

Tham số

  • src_path_in_repo (str) — Đường dẫn tệp tương đối trong kho của tệp cần sao chép, ví dụ "checkpoints/1fec34a/weights.bin".
  • path_in_repo (str) — Đường dẫn tệp tương đối trong kho để sao chép tệp, ví dụ "checkpoints/1fec34a/weights_copy.bin".
  • src_revision (str, tùy chọn) — Phiên bản git của tệp cần sao chép. Có thể là bất kỳ phiên bản git hợp lệ nào. Mặc định là phiên bản commit đích.
  • src_repo_id (str, tùy chọn) — Kho nguồn để sao chép (ví dụ: "username/source-model"). Mặc định là kho đích (sao chép nội bộ kho).
  • src_repo_type (str, tùy chọn) — Loại của kho lưu trữ nguồn ("model", "dataset" hoặc "space"). Bắt buộc khi src_repo_id được đặt.

Cấu trúc dữ liệu chứa thông tin cần thiết để sao chép một tệp trong kho trên Hub.

Cả tệp LFS và tệp thông thường đều được hỗ trợ. Tệp LFS được sao chép phía máy chủ trong khi tệp thông thường được tải xuống và tải lên lại như một phần của commit.

Bản sao giữa các kho được hỗ trợ bằng cách đặt src_repo_id và src_repo_type. Đối với bản sao LFS giữa các kho, các đối tượng LFS được nhân bản sang kho đích trước khi tạo commit. Điều này được xử lý tự động bởi create_commit(). Lưu ý rằng bản sao giữa các kho chỉ hoạt động trong cùng một storage region; việc sao chép giữa các region không được hỗ trợ.

Lưu ý: bạn có thể kết hợp CommitOperationCopy và CommitOperationDelete để đổi tên một tệp LFS trên Hub.

CommitScheduler

lớp huggingface_hub.CommitScheduler

< >

( repo_id: strfolder_path: str | pathlib.Pathevery: int | float = 5path_in_repo: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneprivate: bool | None = Nonetoken: str | None = Noneallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonesquash_history: bool = Falsehf_api: typing.Optional[ForwardRef('HfApi')] = None )

Tham số

  • repo_id (str) — ID của kho cần commit.
  • folder_path (str hoặc Path) — Đường dẫn đến thư mục cục bộ để tải lên định kỳ.
  • every (int hoặc float, tùy chọn) — Số phút giữa mỗi lần commit. Mặc định là 5 phút.
  • path_in_repo (str, tùy chọn) — Đường dẫn tương đối của thư mục trong kho, ví dụ: "checkpoints/". Mặc định là thư mục gốc của kho.
  • repo_type (str, tùy chọn) — Loại repo để commit. Mặc định là model.
  • revision (str, tùy chọn) — Phiên bản của repo để commit. Mặc định là main.
  • private (bool, optional) — Xác định có làm cho kho (repo) ở chế độ riêng tư hay không. Nếu là None (mặc định), kho sẽ ở chế độ công khai trừ khi mặc định của tổ chức là riêng tư. Giá trị này bị bỏ qua nếu kho đã tồn tại.
  • token (str, tùy chọn) — Token được sử dụng để commit vào repo. Mặc định là token đã được lưu trên máy.
  • allow_patterns (list[str] hoặc str, tùy chọn) — Nếu được cung cấp, chỉ các tệp khớp với ít nhất một mẫu mới được tải lên.
  • ignore_patterns (list[str] hoặc str, tùy chọn) — Nếu được cung cấp, các tệp khớp với bất kỳ mẫu nào sẽ không được tải lên.
  • squash_history (bool, tùy chọn) — Có nên nén lịch sử của kho sau mỗi lần commit hay không. Mặc định là False. Việc nén các commit có ích để tránh hiệu năng giảm khi kho trở nên quá lớn.
  • hf_api (HfApi, tùy chọn) — Khách hàng HfApi được sử dụng để commit lên Hub. Có thể được thiết lập với các cài đặt tùy chỉnh (user agent, token,…).

Trình lập lịch để tải lên Hub một thư mục cục bộ theo các khoảng thời gian đều đặn (ví dụ: đẩy lên hub mỗi 5 phút).

Cách được khuyến nghị để sử dụng scheduler là dùng nó như một context manager. Điều này đảm bảo rằng scheduler được dừng đúng cách và commit cuối cùng được kích hoạt khi script kết thúc. Scheduler cũng có thể được dừng thủ công bằng phương thức stop. Xem hướng dẫn upload để tìm hiểu thêm về cách sử dụng nó.

Ví dụ:

>>> from pathlib import Path
>>> from huggingface_hub import CommitScheduler

# Scheduler uploads every 10 minutes
>>> csv_path = Path("watched_folder/data.csv")
>>> CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path=csv_path.parent, every=10)

>>> with csv_path.open("a") as f:
...     f.write("first line")

# Some time later (...)
>>> with csv_path.open("a") as f:
...     f.write("second line")

Ví dụ sử dụng trình quản lý ngữ cảnh:

>>> from pathlib import Path
>>> from huggingface_hub import CommitScheduler

>>> with CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path="watched_folder", every=10) as scheduler:
...     csv_path = Path("watched_folder/data.csv")
...     with csv_path.open("a") as f:
...         f.write("first line")
...     (...)
...     with csv_path.open("a") as f:
...         f.write("second line")

# Scheduler is now stopped and last commit have been triggered

push_to_hub

< >

( )

Đẩy thư mục lên Hub và trả về thông tin commit.

Phương thức này không được thiết kế để gọi trực tiếp. Nó được chạy ở nền bởi trình lập lịch, tuân theo một cơ chế hàng đợi để tránh các lần commit đồng thời. Việc gọi trực tiếp phương thức này có thể dẫn đến các vấn đề về đồng thời.

Hành vi mặc định của push_to_hub là giả định rằng thư mục chỉ được thêm vào (append-only). Phương thức này liệt kê tất cả các tệp trong thư mục và chỉ tải lên các tệp đã bị thay đổi. Nếu không tìm thấy thay đổi nào, phương thức sẽ trả về mà không thực hiện bất kỳ cam kết (commit) nào. Nếu bạn muốn thay đổi hành vi này, bạn có thể kế thừa từ CommitScheduler và ghi đè phương thức này. Điều này có thể hữu ích, chẳng hạn như để nén dữ liệu thành một tệp duy nhất trước khi cam kết. Để biết thêm chi tiết và ví dụ, hãy xem hướng dẫn tích hợp của chúng tôi.

stop

< >

( )

Dừng trình lập lịch.

Trình lập lịch đã dừng không thể khởi động lại. Chủ yếu dùng cho mục đích kiểm thử.

kích hoạt

< >

( )

Kích hoạt push_to_hub và trả về một future.

Phương thức này được gọi tự động mỗi every phút. Bạn cũng có thể gọi thủ công để kích hoạt một commit ngay lập tức, mà không cần chờ đến lần commit được lên lịch tiếp theo.

Update on GitHub

←Biến môi trường CLI→