# 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`](https://filesystem-spec.readthedocs.io/en/latest/).

## HfFileSystem[[huggingface_hub.HfFileSystem]]

`HfFileSystem` được xây dựng dựa trên [fsspec](https://filesystem-spec.readthedocs.io/en/latest/), 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](../guides/hf_file_system) và [Tham chiếu API](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem) của fsspec.

#### huggingface_hub.HfFileSystem[[huggingface_hub.HfFileSystem]]

```python
huggingface_hub.HfFileSystem(*args, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L370)

**Tham số:**

endpoint (`str`, *tùy chọn*) : Điểm cuối của Hub. Mặc định là .

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*) : Xác định có mở rộng thông tin của các tệp hay không.

max_workers (`int`, *optional*) : 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()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_file_system#huggingface_hub.HfFileSystem.find)). Mặc định là 16. Đặt thành 1 để tắt việc liệt kê song song.

live_follow (`bool`, *tuỳ chọn*) : Có theo dõi các thay đổi tệp trong các bucket theo thời gian thực trên Hub hay không, để các danh sách được lưu trong bộ nhớ đệm luôn cập nhật mà không cần gọi thủ công [HfFileSystem.invalidate_cache()](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_file_system#huggingface_hub.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ó hiệu ứng 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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.__init__).

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ộ.

> [!WARNING]
> [HfFileSystem](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_file_system#huggingface_hub.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>
```

* Buckets (lưu trữ chung):

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

Lưu ý: khi sử dụng [HfFileSystem](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_file_system#huggingface_hub.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:

```python
>>> 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:
```python
>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)
```

#### cp_file[[huggingface_hub.HfFileSystem.cp_file]]

```python
cp_file(path1: str, path2: str, revision: str | None = None, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1115)

**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*) : Bản sửa 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.

> [!WARNING]
> 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[[huggingface_hub.HfFileSystem.exists]]

```python
exists(path, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1336)

**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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.exists).

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

#### tìm[[huggingface_hub.HfFileSystem.find]]

```python
find(path: str, maxdepth: int | None = None, withdirs: bool = False, detail: bool = False, refresh: bool = False, revision: str | None = None, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1051)

**Tham số:**

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

maxdepth (`int`, *tuỳ 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 các đường dẫn thư mục trong kết quả đầu ra. Mặc định là False.

detail (`bool`, *tùy chọn*) : Nếu là True, sẽ 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*) : Bản sửa 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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.find).

> [!TIP]
> 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](/docs/huggingface_hub/v2.4.0/vi/package_reference/hf_file_system#huggingface_hub.HfFileSystem).

#### get_file[[huggingface_hub.HfFileSystem.get_file]]

```python
get_file(rpath, lpath = None, callback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>, outfile = None, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1444)

**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ộ.

> [!WARNING]
> 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[[huggingface_hub.HfFileSystem.glob]]

```python
glob(path: str, maxdepth: int | None = None, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1033)

**Tham số:**

path (`str`) : Mẫu đường dẫn cần khớp.

maxdepth (`int`, *tuỳ chọn*) : Độ sâu tối đa để đi xuống các thư mục. Mặc định, không có 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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.glob).

#### info[[huggingface_hub.HfFileSystem.info]]

```python
info(path: str, refresh: bool = False, revision: str | None = None, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1226)

**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*) : Bản sửa 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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.info).

> [!WARNING]
> 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[[huggingface_hub.HfFileSystem.invalidate_cache]]

```python
invalidate_cache(path: str | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L599)

**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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.invalidate_cache).

#### isdir[[huggingface_hub.HfFileSystem.isdir]]

```python
isdir(path)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1361)

**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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.isdir).

#### isfile[[huggingface_hub.HfFileSystem.isfile]]

```python
isfile(path)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1379)

**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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.isfile).

#### ls[[huggingface_hub.HfFileSystem.ls]]

```python
ls(path: str, detail: bool = True, refresh: bool = False, revision: str | None = None, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L788)

**Tham số:**

path (`str`) : Đường dẫn đến thư mục.

detail (`bool`, *tuỳ 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*) : Bản sửa 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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.ls).

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

#### đã chỉnh sửa[[huggingface_hub.HfFileSystem.modified]]

```python
modified(path: str, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1201)

**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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.modified).

#### resolve_path[[huggingface_hub.HfFileSystem.resolve_path]]

```python
resolve_path(path: str, revision: str | None = None)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L520)

**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`.

**Lỗi:** ``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.

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[[huggingface_hub.HfFileSystem.rm]]

```python
rm(path: str, recursive: bool = False, maxdepth: int | None = None, revision: str | None = None, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L738)

**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`, *optional*) : 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*) : Bản sửa git để xóa từ đó.

Xóa tệp khỏi kho.

Để biết thêm chi tiết, hãy tham khảo [tài liệu fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.rm).

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

#### url[[huggingface_hub.HfFileSystem.url]]

```python
url(path: str)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1397)

**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.

#### walk[[huggingface_hub.HfFileSystem.walk]]

```python
walk(path: str, *args, **kwargs)
```

[Nguồn](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1017)

**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](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.walk).