Hub Python Library documentation

API Hệ thống tệp

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

API Hệ thống tệp

Lớp HfFileSystem cung cấp giao diện tệp theo phong cách Python cho Hugging Face Hub dựa trên fsspec.

HfFileSystem

HfFileSystem được xây dựng dựa trên fsspec, do đó nó tương thích với hầu hết các API mà thư viện này cung cấp. Để biết thêm chi tiết, hãy xem hướng dẫn của chúng tôi và Tham chiếu API của fsspec.

lớp huggingface_hub.HfFileSystem

( *args**kwargs )

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.
block_size (int, tùy chọn) — Kích thước khối để đọc và ghi tệp.
expand_info (bool, tùy chọn) — Có mở rộng thông tin của các tệp hay không.
max_workers (int, tùy chọn) — Số lượng yêu cầu đồng thời tối đa được sử dụng để liệt kê các thư mục lớn song song (xem find()). Mặc định là 16. Đặt thành 1 để tắt việc liệt kê song song.
live_follow (bool, tùy chọn) — Xác định có theo dõi các thay đổi tệp trong các bucket khi chúng xảy ra trên Hub hay không, để các danh sách được lưu trong bộ nhớ đệm luôn ở trạng thái mới nhất mà không cần gọi thủ công HfFileSystem.invalidate_cache(). Khi được bật, việc liệt kê một bucket sẽ mở một kết nối nền với luồng sự kiện của Hub cho bucket đó. Không có tác dụng đối với các kho lưu trữ model, dataset và space (Hub không cung cấp thông tin thay đổi cho những loại này).
**storage_options (dict, tùy chọn) — Các tùy chọn bổ sung cho hệ thống tệp. Xem tài liệu fsspec.

Truy cập kho lưu trữ Hugging Face Hub từ xa như thể nó là một hệ thống tệp cục bộ.

HfFileSystem cung cấp khả năng tương thích với fsspec, hữu ích cho các thư viện yêu cầu điều này (ví dụ: đọc trực tiếp các bộ dữ liệu Hugging Face bằng pandas). Tuy nhiên, lớp tương thích này gây ra thêm chi phí xử lý. Để đạt hiệu suất và độ tin cậy tốt hơn, nên sử dụng các phương thức của HfApi khi có thể.

Hệ thống tệp hỗ trợ các đường dẫn cho giao thức hf://, tuân theo các lược đồ URL sau:

Các kho lưu trữ Models, Datasets và Spaces:

hf://<repo-id>[@<revision>]/<path/in/repo>
hf://datasets/<repo-id>[@<revision>]/<path/in/repo>
hf://spaces/<repo-id>[@<revision>]/<path/in/repo>

Bucket (lưu trữ chung):

hf://buckets/<bucket-id>/<path/in/bucket>

Lưu ý: khi sử dụng HfFileSystem trực tiếp, việc truyền tiền tố giao thức hf:// trong các đường dẫn là tùy chọn.

Cách sử dụng:

>>> from huggingface_hub import hffs

>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']

>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)

Chỉ định một token để xác thực:

>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)

cp_file

( path1: strpath2: strrevision: str | None = None**kwargs )

Tham số

path1 (str) — Đường dẫn nguồn để sao chép.
path2 (str) — Đường dẫn đích để sao chép.
revision (str, tùy chọn) — Phiên bản git để sao chép từ đó.

Sao chép tệp trong hoặc giữa các kho, hoặc vào một bucket.

Lưu ý: Khi có thể, hãy sử dụng HfApi.upload_file() để đạt hiệu suất tốt hơn.

tồn tại

( path**kwargs ) → bool

Tham số

path (str) — Đường dẫn cần kiểm tra.

Trả về

bool

True nếu tệp tồn tại, False nếu không.

Kiểm tra xem tệp có tồn tại hay không.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

Lưu ý: Khi có thể, hãy sử dụng HfApi.file_exists() để đạt hiệu suất tốt hơn.

find

( path: strmaxdepth: int | None = Nonewithdirs: bool = Falsedetail: bool = Falserefresh: bool = Falserevision: str | None = None**kwargs ) → Union[list[str], dict[str, dict[str, Any]]]

Tham số

path (str) — Đường dẫn gốc để liệt kê các tệp từ đó.
maxdepth (int, tùy chọn) — Độ sâu tối đa để đi xuống các thư mục con.
withdirs (bool, tùy chọn) — Bao gồm đường dẫn thư mục trong đầu ra. Mặc định là False.
detail (bool, tùy chọn) — Nếu là True, trả về một dict ánh xạ các đường dẫn đến thông tin tệp. Mặc định là False.
refresh (bool, tùy chọn) — Nếu là True, bỏ qua bộ nhớ đệm và lấy dữ liệu mới nhất. Mặc định là False.
revision (str, tùy chọn) — Phiên bản git để liệt kê từ đó.

Trả về

Union[list[str], dict[str, dict[str, Any]]]

Danh sách các đường dẫn hoặc dict chứa thông tin tệp.

Liệt kê tất cả các tệp bên dưới đường dẫn.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

Các kho lớn được liệt kê theo từng thư mục, song song, để khắc phục phân trang dựa trên con trỏ của điểm cuối tree của Hub. Điều chỉnh điều này bằng đối số max_workers của HfFileSystem.

get_file

( rpathlpath = Nonecallback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>outfile = None**kwargs )

Tham số

rpath (str) — Đường dẫn từ xa để tải xuống.
lpath (str, tùy chọn) — Đường dẫn cục bộ để tải xuống. Có thể bỏ qua nếu đã cung cấp outfile.
callback (Callback, optional) — Optional callback to track download progress. Defaults to no callback.
outfile (IO, tùy chọn) — Đối tượng dạng tệp tùy chọn để ghi. Nếu được cung cấp, lpath sẽ bị bỏ qua.

Sao chép một tệp từ xa đơn lẻ về cục bộ.

Lưu ý: Khi có thể, hãy sử dụng HfApi.hf_hub_download() hoặc HfApi.download_bucket_files để đạt hiệu suất tốt hơn.

glob

( path: strmaxdepth: int | None = None**kwargs ) → list[str]

Tham số

path (str) — Mẫu đường dẫn cần khớp.
maxdepth (int, tùy chọn) — Độ sâu tối đa để đi xuống các thư mục. Mặc định là không giới hạn.

Trả về

list[str]

Danh sách các đường dẫn khớp với mẫu.

Tìm tệp bằng cách khớp glob.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

thông tin

( path: strrefresh: bool = Falserevision: str | None = None**kwargs ) → dict[str, Any]

Tham số

path (str) — Đường dẫn để lấy thông tin.
refresh (bool, tùy chọn) — Nếu là True, bỏ qua bộ nhớ đệm và lấy dữ liệu mới nhất. Mặc định là False.
revision (str, tùy chọn) — Phiên bản git để lấy thông tin từ đó.

Trả về

dict[str, Any]

Từ điển chứa thông tin tệp (kiểu, kích thước, thông tin commit, v.v.).

Lấy thông tin về một tệp hoặc thư mục.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

Lưu ý: Khi có thể, hãy sử dụng HfApi.get_paths_info() hoặc HfApi.repo_info() để đạt hiệu suất tốt hơn (hoặc HfApi.get_bucket_paths_info() hoặc HfApi.bucket_info() cho các bucket)

invalidate_cache

( path: str | None = None )

Tham số

path (str, tùy chọn) — Đường dẫn cần xóa khỏi bộ nhớ đệm. Nếu không được cung cấp, toàn bộ bộ nhớ đệm sẽ được xóa.

Xóa bộ nhớ đệm cho một đường dẫn nhất định.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

isdir

( path ) → bool

Tham số

path (str) — Đường dẫn cần kiểm tra.

Trả về

bool

Đúng nếu path là một thư mục, Sai trong trường hợp khác.

Kiểm tra xem một đường dẫn có phải là thư mục hay không.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

isfile

( path ) → bool

Tham số

path (str) — Đường dẫn cần kiểm tra.

Trả về

bool

Đúng nếu path là một tệp, Sai trong trường hợp khác.

Kiểm tra xem một đường dẫn có phải là tệp hay không.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

ls

( path: strdetail: bool = Truerefresh: bool = Falserevision: str | None = None**kwargs ) → list[Union[str, dict[str, Any]]]

Tham số

path (str) — Đường dẫn đến thư mục.
detail (bool, tùy chọn) — Nếu là True, trả về một danh sách các từ điển chứa thông tin tệp. Nếu là False, trả về một danh sách các đường dẫn tệp. Mặc định là True.
refresh (bool, tùy chọn) — Nếu là True, bỏ qua bộ nhớ đệm và lấy dữ liệu mới nhất. Mặc định là False.
revision (str, tùy chọn) — Phiên bản git để liệt kê từ đó.

Trả về

list[Union[str, dict[str, Any]]]

Danh sách đường dẫn tệp (nếu detail=False) hoặc danh sách các từ điển thông tin tệp (nếu detail=True).

Liệt kê nội dung của một thư mục.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

Lưu ý: Khi có thể, hãy sử dụng HfApi.list_repo_tree() để đạt hiệu suất tốt hơn.

đã sửa đổi

( path: str**kwargs ) → datetime

Tham số

path (str) — Đường dẫn đến tệp.

Trả về

datetime

Thời gian sửa đổi cuối cùng của tệp.

Lấy thời gian sửa đổi cuối cùng của một tệp.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

resolve_path

( path: strrevision: str | None = None ) → HfFileSystemResolvedPath

Tham số

path (str) — Đường dẫn cần phân giải.
revision (str, tùy chọn) — Phiên bản của kho cần phân giải. Mặc định là phiên bản được chỉ định trong đường dẫn.

Trả về

HfFileSystemResolvedPath

Thông tin đường dẫn đã được phân giải, bao gồm repo_type, repo_id, revision và path_in_repo.

Gây ra

ValueError hoặc NotImplementedError

ValueError — Nếu path chứa thông tin revision mâu thuẫn.
NotImplementedError — Nếu cố gắng liệt kê các kho lưu trữ.

Phân tích đường dẫn hệ thống tệp Hugging Face thành các thành phần của nó.

rm

( path: strrecursive: bool = Falsemaxdepth: int | None = Nonerevision: str | None = None**kwargs )

Tham số

path (str) — Đường dẫn cần xóa.
recursive (bool, tùy chọn) — Nếu là True, xóa thư mục và toàn bộ nội dung của nó. Mặc định là False.
maxdepth (int, tùy chọn) — Số lượng tối đa các thư mục con cần truy cập khi xóa đệ quy.
revision (str, tùy chọn) — Phiên bản git cần xóa.

Xóa tệp khỏi kho.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

Lưu ý: Khi có thể, hãy sử dụng HfApi.delete_file() để đạt hiệu suất tốt hơn.

url

( path: str ) → str

Tham số

path (str) — Đường dẫn để lấy URL.

Trả về

str

HTTP URL để truy cập tệp hoặc thư mục trên Hub.

Lấy URL HTTP của đường dẫn đã cho.

đi bộ

( path: str*args**kwargs ) → Iterator[tuple[str, list[str], list[str]]]

Tham số

path (str) — Đường dẫn gốc để liệt kê các tệp từ đó.

Trả về

Iterator[tuple[str, list[str], list[str]]]

Một trình lặp các bộ ba (path, danh sách tên thư mục, danh sách tên tệp).

Trả về tất cả các tệp bên dưới đường dẫn đã cho.

Để biết thêm chi tiết, hãy tham khảo tài liệu fsspec.

Update on GitHub

←MCP Client HF URIs→