Hugging Face's logo

Hub Python Library documentation

API de sistema de arquivos

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

API de sistema de arquivos

A classe HfFileSystem fornece uma interface de arquivo pythonic para o Hugging Face Hub com base no fsspec.

HfFileSystem

HfFileSystem é baseado em fsspec, portanto é compatível com a maioria das APIs que ele oferece. Para mais detalhes, consulte nossa guia e a API Reference do fsspec.

classe huggingface_hub.HfFileSystem

< >

( *args**kwargs )

Parâmetros

  • endpoint (str, opcional) — Endpoint do Hub. O padrão é https://huggingface.co.
  • token (bool or str, opcional) — Um token de acesso de usuário válido (string). O padrão é o token salvo localmente, que é o método recomendado para autenticação (veja https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Para desabilitar a autenticação, passe False.
  • block_size (int, opcional) — Tamanho do bloco para leitura e gravação de arquivos.
  • expand_info (bool, opcional) — Se deve expandir as informações dos arquivos.
  • max_workers (int, opcional) — Número máximo de solicitações concorrentes usadas para listar grandes diretórios em paralelo (veja find()). O padrão é 16. Defina como 1 para desativar listagens paralelas.
  • live_follow (bool, opcional) — Se deve acompanhar as alterações nos arquivos dos buckets conforme elas ocorrem no Hub, para que as listagens em cache permaneçam atualizadas sem chamadas manuais de HfFileSystem.invalidate_cache(). Quando habilitado, listar um bucket abre uma conexão em segundo plano para o feed de eventos do Hub correspondente a esse bucket. Não tem efeito em repositórios de modelos, datasets e spaces (o Hub não fornece alterações para esses tipos).
  • **storage_options (dict, opcional) — Opções adicionais para o sistema de arquivos. Consulte a documentação do fsspec.

Acesse um repositório remoto do Hugging Face Hub como se fosse um sistema de arquivos local.

HfFileSystem oferece compatibilidade com fsspec, o que é útil para bibliotecas que a exigem (por exemplo, ler datasets do Hugging Face diretamente com pandas). No entanto, isso introduz sobrecarga adicional devido a essa camada de compatibilidade. Para melhor desempenho e confiabilidade, recomenda-se usar os métodos de HfApi sempre que possível.

O sistema de arquivos suporta caminhos para o protocolo hf://, que segue os seguintes esquemas de URL:

  • Repositórios de Modelos, Datasets e 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 (armazenamento genérico):
hf://buckets/<bucket-id>/<path/in/bucket>

Nota: ao usar o HfFileSystem diretamente, a passagem do prefixo de protocolo hf:// é opcional nos caminhos.

Uso:

>>> 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)

Especifique um token para autenticação:

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

cp_file

< >

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

Parâmetros

  • path1 (str) — Caminho de origem para copiar.
  • path2 (str) — Caminho de destino para a cópia.
  • revision (str, opcional) — A revisão git de onde copiar.

Copie um arquivo dentro ou entre repositórios, ou para um bucket.

Observação: Sempre que possível, use HfApi.upload_file() para obter melhor desempenho.

existe

< >

( path**kwargs ) → bool

Parâmetros

  • path (str) — Caminho a ser verificado.

Retorna

bool

True se o arquivo existir, False caso contrário.

Verifique se um arquivo existe.

Para mais detalhes, consulte a documentação do fsspec.

Observação: Sempre que possível, use HfApi.file_exists() para melhor desempenho.

find

< >

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

Parâmetros

  • path (str) — Caminho raiz para listar os arquivos.
  • maxdepth (int, opcional) — Profundidade máxima para descer em subdiretórios.
  • withdirs (bool, opcional) — Inclui caminhos de diretório na saída. O valor padrão é False.
  • detail (bool, opcional) — Se True, retorna um dict mapeando caminhos para informações de arquivo. O padrão é False.
  • refresh (bool, opcional) — Se True, ignora o cache e busca os dados mais recentes. O valor padrão é False.
  • revision (str, opcional) — A revisão git a partir da qual listar.

Retorna

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

Lista de caminhos ou dicionário de informações de arquivo.

Liste todos os arquivos abaixo do caminho.

Para mais detalhes, consulte a documentação do fsspec.

Repositórios grandes são listados diretório por diretório, em paralelo, para contornar a paginação baseada em cursor do endpoint tree do Hub. Ajuste isso com o argumento max_workers de HfFileSystem.

get_file

< >

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

Parâmetros

  • rpath (str) — Caminho remoto para download.
  • lpath (str, opcional) — Caminho local para onde baixar. Pode ser omitido se outfile for fornecido.
  • callback (Callback, optional) — Optional callback to track download progress. Defaults to no callback.
  • outfile (IO, opcional) — Objeto semelhante a arquivo opcional para gravação. Se fornecido, lpath é ignorado.

Copiar um arquivo remoto individual para o local.

Nota: Sempre que possível, use HfApi.hf_hub_download() ou HfApi.download_bucket_files para melhor desempenho.

glob

< >

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

Parâmetros

  • path (str) — Padrão de caminho para corresponder.
  • maxdepth (int, opcional) — Profundidade máxima para descer nos diretórios. Por padrão, sem limite.

Retorna

list[str]

Lista de caminhos que correspondem ao padrão.

Encontre arquivos por correspondência de glob.

Para mais detalhes, consulte a documentação do fsspec.

info

< >

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

Parâmetros

  • path (str) — Caminho para o qual obter informações.
  • refresh (bool, opcional) — Se True, ignora o cache e busca os dados mais recentes. O valor padrão é False.
  • revision (str, opcional) — A revisão git de onde obter as informações.

Retorna

dict[str, Any]

Dicionário contendo informações do arquivo (tipo, tamanho, informações do commit, etc.).

Obtém informações sobre um arquivo ou diretório.

Para mais detalhes, consulte a documentação do fsspec.

Nota: Sempre que possível, use HfApi.get_paths_info() ou HfApi.repo_info() para melhor desempenho (ou HfApi.get_bucket_paths_info() ou HfApi.bucket_info() para buckets)

invalidate_cache

< >

( path: str | None = None )

Parâmetros

  • path (str, opcional) — Caminho a ser limpo do cache. Se não for fornecido, o cache inteiro será limpo.

Limpe o cache para um caminho específico.

Para mais detalhes, consulte a documentação do fsspec.

isdir

< >

( path ) → bool

Parâmetros

  • path (str) — Caminho a ser verificado.

Retorna

bool

True se o path for um diretório, False caso contrário.

Verifique se um caminho é um diretório.

Para mais detalhes, consulte a documentação do fsspec.

isfile

< >

( path ) → bool

Parâmetros

  • path (str) — Caminho a ser verificado.

Retorna

bool

True se o path for um arquivo, False caso contrário.

Verifique se um caminho é um arquivo.

Para mais detalhes, consulte a documentação do fsspec.

ls

< >

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

Parâmetros

  • path (str) — Caminho para o diretório.
  • detail (bool, opcional) — Se True, retorna uma lista de dicionários contendo informações dos arquivos. Se False, retorna uma lista de caminhos de arquivos. O valor padrão é True.
  • refresh (bool, opcional) — Se True, ignora o cache e busca os dados mais recentes. O valor padrão é False.
  • revision (str, opcional) — A revisão git a partir da qual listar.

Retorna

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

Lista de caminhos de arquivo (se detail=False) ou lista de dicionários de informações de arquivo (se detail=True).

Liste o conteúdo de um diretório.

Para mais detalhes, consulte a documentação do fsspec.

Observação: Sempre que possível, use HfApi.list_repo_tree() para melhor desempenho.

modificado

< >

( path: str**kwargs ) → datetime

Parâmetros

  • path (str) — Caminho para o arquivo.

Retorna

datetime

Hora da última modificação do arquivo.

Obtenha a data e a hora da última modificação de um arquivo.

Para mais detalhes, consulte a documentação do fsspec.

resolve_path

< >

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

Parâmetros

  • path (str) — Caminho a ser resolvido.
  • revision (str, opcional) — A revisão do repositório a ser resolvida. O padrão é a revisão especificada no caminho.

Retorna

HfFileSystemResolvedPath

Informações do caminho resolvido contendo repo_type, repo_id, revision e path_in_repo.

Exceções

ValueError ou NotImplementedError

  • ValueError — Se o path contiver informações de revisão conflitantes.
  • NotImplementedError — Ao tentar listar repositórios.

Resolve um caminho de sistema de arquivos do Hugging Face em seus componentes.

rm

< >

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

Parâmetros

  • path (str) — Caminho a ser excluído.
  • recursive (bool, opcional) — Se True, exclui o diretório e todo o seu conteúdo. O padrão é False.
  • maxdepth (int, opcional) — Número máximo de subdiretórios a serem visitados ao excluir recursivamente.
  • revision (str, opcional) — A revisão git a partir da qual excluir.

Excluir arquivos de um repositório.

Para mais detalhes, consulte a documentação do fsspec.

Nota: Sempre que possível, use HfApi.delete_file() para melhor desempenho.

url

< >

( path: str ) → str

Parâmetros

  • path (str) — Caminho para obter a URL.

Retorna

str

URL HTTP para acessar o arquivo ou diretório no Hub.

Obtenha a URL HTTP do caminho fornecido.

andar

< >

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

Parâmetros

  • path (str) — Caminho raiz para listar os arquivos.

Retorna

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

Um iterador de tuplas (caminho, lista de nomes de diretórios, lista de nomes de arquivos).

Retorna todos os arquivos abaixo do caminho especificado.

Para mais detalhes, consulte a documentação do fsspec.

Update on GitHub

←Cliente MCP URIs do HF→