Hugging Face's logo

Hub Python Library documentation

Cliente HfApi

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Cliente HfApi

Abaixo está a documentação da classe HfApi, que atua como um wrapper em Python para a API do Hugging Face Hub.

Todos os métodos da HfApi também são acessíveis diretamente pela raiz do pacote. Ambas as abordagens são detalhadas abaixo.

O uso do método raiz é mais direto, mas a classe HfApi oferece mais flexibilidade. Em particular, você pode passar um token que será reutilizado em todas as chamadas HTTP. Isso é diferente de hf auth login ou login(), pois o token não é persistido na máquina. Também é possível fornecer um endpoint diferente ou configurar um user-agent personalizado.

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

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

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.
  • library_name (str, opcional) — O nome da biblioteca que está fazendo a requisição HTTP. Será adicionado ao cabeçalho user-agent. Exemplo: "transformers".
  • library_version (str, opcional) — A versão da biblioteca que está fazendo a requisição HTTP. Será adicionada ao cabeçalho user-agent. Exemplo: "4.24.0".
  • user_agent (str, dict, opcional) — As informações do user agent na forma de um dicionário ou de uma única string. Serão complementadas com informações sobre os pacotes instalados.
  • headers (dict, opcional) — Cabeçalhos adicionais a serem enviados com cada solicitação. Exemplo: {"X-My-Header": "value"}. Os cabeçalhos passados aqui têm precedência sobre os cabeçalhos padrão.

Cliente para interagir com o Hugging Face Hub via HTTP.

O cliente é inicializado com algumas configurações de alto nível usadas em todas as solicitações feitas ao Hub (endpoint do HF, autenticação, user agents…). O uso do cliente HfApi é preferível, mas não obrigatório, pois todos os seus métodos públicos são expostos diretamente na raiz de huggingface_hub.

accept_access_request

< >

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

Parâmetros

  • repo_id (str) — O id do repositório para o qual a solicitação de acesso será aceita.
  • user (str, opcional) — O nome de usuário do usuário cuja solicitação de acesso deve ser aceita. Exatamente um de user ou request_id deve ser fornecido.
  • request_id (str, opcional) — O id da solicitação de acesso a ser aceita (veja AccessRequest). Obrigatório quando o repositório está configurado para não compartilhar os nomes de usuário dos solicitantes. Exatamente um de user ou request_id deve ser fornecido.
  • repo_type (str, opcional) — O tipo do repositório para o qual a solicitação de acesso será aceita. Deve ser um de model, dataset ou space. Padrão: model.
  • 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.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 se o repositório não for restrito.
  • HfHubHTTPError — HTTP 403 se você tiver apenas acesso somente leitura ao repositório. Isso pode ocorrer se você não tiver o papel write ou admin na organização à qual o repositório pertence, ou se você tiver passado um token read.
  • HfHubHTTPError — HTTP 404 se o usuário não existir no Hub.
  • HfHubHTTPError — HTTP 404 se a solicitação de acesso do usuário não puder ser encontrada.
  • HfHubHTTPError — HTTP 404 se a solicitação de acesso do usuário já estiver na lista de aceitos.

Aceitar uma solicitação de acesso de um usuário para um repositório restrito específico.

Uma vez que a solicitação é aceita, o usuário poderá baixar qualquer arquivo do repositório e acessar a aba de comunidade. Se o modo de aprovação for automático, não é necessário aceitar solicitações manualmente. Uma solicitação aceita pode ser cancelada ou rejeitada a qualquer momento usando cancel_access_request() e reject_access_request().

Para mais informações sobre repositórios com acesso controlado, consulte 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 )

Parâmetros

  • collection_slug (str) — Slug da coleção a ser atualizada. Exemplo: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • item_id (str) — ID do item a ser adicionado à coleção. Use o repo_id para repositórios/espaces/datasets, o ID do paper para papers, o slug de outra coleção (por exemplo, "moonshotai/kimi-k2") ou um ID de bucket (por exemplo, "namespace/bucket-name").
  • item_type (str) — Tipo do item a ser adicionado. Pode ser um de "model", "dataset", "space", "paper", "collection" ou "bucket".
  • note (str, opcional) — Uma nota para anexar ao item na coleção. O tamanho máximo para uma nota é de 500 caracteres.
  • exists_ok (bool, opcional) — Se True, não levanta um erro se o item já existir.
  • 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.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 403 se você tiver apenas acesso somente leitura ao repositório. Isso pode ocorrer se você não tiver o papel write ou admin na organização à qual o repositório pertence, ou se você tiver passado um token read.
  • HfHubHTTPError — HTTP 404 se o item que você tenta adicionar à coleção não existir no Hub.
  • HfHubHTTPError — HTTP 409 se o item que você tenta adicionar à coleção já estiver na coleção (e exists_ok=False)

Adicione um item a uma coleção no Hub.

Retorna: Collection

Exemplo:

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

Parâmetros

  • repo_id (str) — ID do repositório a ser atualizado. Exemplo: "bigcode/in-the-stack".
  • key (str) — Chave secreta. Exemplo: "GITHUB_API_KEY"
  • value (str) — Valor do segredo. Exemplo: "your_github_api_key".
  • description (str, opcional) — Descrição do segredo. Exemplo: "Github API key to access the Github API".
  • 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.

Adiciona ou atualiza um segredo em um Space.

Secrets permitem definir chaves ou tokens secretos em um Space sem codificá-los diretamente no código. Para mais detalhes, consulte https://huggingface.co/docs/hub/spaces-overview#managing-secrets.

add_space_variable

< >

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

Parâmetros

  • repo_id (str) — ID do repositório a ser atualizado. Exemplo: "bigcode/in-the-stack".
  • key (str) — Chave da variável. Exemplo: "MODEL_REPO_ID"
  • value (str) — Valor da variável. Exemplo: "the_model_repo_id".
  • description (str) — Descrição da variável. Exemplo: "Model Repo ID of the implemented model".
  • 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.

Adiciona ou atualiza uma variável em um Space.

Variáveis permitem definir variáveis de ambiente em um Space sem codificá-las diretamente. Para mais detalhes, consulte 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 )

Parâmetros

  • repo_id (str) — O repositório para verificar o acesso. O formato deve ser "user/repo_name". Exemplo: "user/my-cool-model".
  • repo_type (str, opcional) — O tipo do repositório. Deve ser um de "model", "dataset" ou "space". Se não for especificado, o padrão é "model".
  • token (Union[bool, str, None], opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será usado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.
  • write (bool, opcional) — Se True, verifica se o usuário tem permissão de escrita de conteúdo no repositório. Se False (padrão), verifica apenas o acesso de leitura.

Exceções

RepositoryNotFoundError ou GatedRepoError

  • RepositoryNotFoundError — Exceção lançada se o repositório não existir, for privado ou se o usuário não tiver acesso. Isso pode ocorrer se o repo_id ou o repo_type estiverem incorretos, ou se o repositório for privado e o usuário não estiver autenticado.

  • GatedRepoError — Exceção lançada se o repositório existir, mas for restrito e o usuário não estiver autorizado a acessá-lo.

Verifique se o token de usuário fornecido tem acesso a um repositório específico no Hugging Face Hub.

Este método verifica se o usuário, autenticado por meio do token fornecido, tem acesso ao repositório especificado. Se o repositório não for encontrado ou se o usuário não tiver as permissões necessárias para acessá-lo, o método lança uma exceção apropriada.

Exemplo:

Verifique se o usuário tem acesso a um repositório:

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

Neste exemplo:

  • Se o usuário tiver acesso, o método é concluído com sucesso.
  • Se o repositório for restrito ou não existir, exceções apropriadas são lançadas, permitindo que o usuário as trate de acordo.

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 )

Parâmetros

  • bucket_id (str) — O ID do bucket (por exemplo, "username/my-bucket").
  • add (list de tuple, opcional) — Arquivos para enviar. Cada elemento é uma tupla (source, destination) em que source é um caminho para um arquivo local (str ou Path) ou conteúdo bruto em bytes, e destination é o caminho no bucket.
  • copy (list de tuple, opcional) — Arquivos para copiar por hash xet. Cada elemento é uma (source_repo_type, source_repo_id, xet_hash, destination) tupla onde:
    • source_repo_type é o tipo do repositório de origem: "model", "dataset", "space" ou "bucket".
    • source_repo_id é o ID do repositório ou bucket de origem (por exemplo, "username/my-model").
    • xet_hash é o hash xet do arquivo a ser copiado.
    • destination é o caminho de destino no bucket. Esta é uma operação no lado do servidor — nenhum dado é baixado ou reenviado.
  • delete (list de str, opcional) — Caminhos dos arquivos a serem excluídos do bucket.
  • 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.

Exceções

BucketBatchError

  • BucketBatchError — Se o servidor relatar que algumas operações falharam. O erro é lançado uma vez que todas as operações tenham sido enviadas, de modo que as outras operações do lote tenham sido aplicadas.

Adicione, copie e/ou exclua arquivos em um bucket.

Esta é uma operação não transacional. Se um erro ocorrer durante o processo, alguns arquivos podem ter sido enviados, copiados ou excluídos, enquanto outros não.

Exemplo:

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

Parâmetros

  • bucket_id (str) — O ID do bucket (por exemplo, "username/my-bucket").
  • 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.

Retorna

BucketInfo

As informações do bucket.

Exceções

BucketNotFoundError ou or

  • BucketNotFoundError — Se o bucket não puder ser encontrado. Isso pode ocorrer porque ele não existe,
  • or — porque está definido como private e você não tem acesso.

Obtenha informações sobre um bucket específico no Hub.

Exemplo:

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

Parâmetros

  • repo_id (str) — O id do repositório para o qual a solicitação de acesso será cancelada.
  • user (str, opcional) — O nome de usuário do usuário cuja solicitação de acesso deve ser cancelada. Exatamente um de user ou request_id deve ser fornecido.
  • request_id (str, opcional) — O id da solicitação de acesso a ser cancelada (veja AccessRequest). Obrigatório quando o repositório está configurado para não compartilhar os nomes de usuário dos solicitantes. Exatamente um de user ou request_id deve ser fornecido.
  • repo_type (str, opcional) — O tipo do repositório para o qual a solicitação de acesso será cancelada. Deve ser um de model, dataset ou space. Padrão: model.
  • 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.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 se o repositório não for restrito.
  • HfHubHTTPError — HTTP 403 se você tiver apenas acesso somente leitura ao repositório. Isso pode ocorrer se você não tiver o papel write ou admin na organização à qual o repositório pertence, ou se você tiver passado um token read.
  • HfHubHTTPError — HTTP 404 se o usuário não existir no Hub.
  • HfHubHTTPError — HTTP 404 se a solicitação de acesso do usuário não puder ser encontrada.
  • HfHubHTTPError — HTTP 404 se a solicitação de acesso do usuário já estiver na lista de pendentes.

Cancelar uma solicitação de acesso de um usuário para um repositório restrito específico.

Uma solicitação cancelada voltará para a lista de pendentes e o usuário perderá o acesso ao repositório.

Para mais informações sobre repositórios com acesso controlado, consulte https://huggingface.co/docs/hub/models-gated.

cancel_job

< >

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

Parâmetros

  • job_id (str) — ID do Job.
  • namespace (str, opcional) — O namespace onde o Job está em execução. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Cancelar um Job de computação na infraestrutura do 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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • discussion_num (int) — O número da Discussion ou Pull Request. Deve ser um inteiro estritamente positivo.
  • new_status (str) — O novo status para a discussão, seja "open" ou "closed".
  • comment (str, opcional) — Um comentário opcional para publicar junto com a alteração de status.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.
  • 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.

Retorna

DiscussionStatusChange

o evento de mudança de status

Fecha ou reabre uma Discussão ou Pull Request.

Exemplos:

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

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

comment_discussion

< >

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • discussion_num (int) — O número da Discussion ou Pull Request. Deve ser um inteiro estritamente positivo.
  • comment (str) — O conteúdo do comentário a ser criado. Os comentários suportam formatação em markdown.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.
  • 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.

Retorna

DiscussionComment

o comentário recém-criado

Cria um novo comentário na Discussion especificada.

Exemplos:


>>> 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', ...)

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

copy_files

< >

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

Parâmetros

  • source (str) — Localização de origem como um URI hf://. Pode ser um caminho de bucket (por exemplo, "hf://buckets/my-bucket/path/to/file") ou um caminho de repositório (por exemplo, "hf://username/my-model/weights.bin", "hf://datasets/username/my-dataset/data/").
  • destination (str) — Localização de destino como um URI hf:// apontando para um bucket (por exemplo, "hf://buckets/my-bucket/target/path") ou um repositório (por exemplo, "hf://username/my-model/target/path").
  • 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.

Exceções

ValueError

  • ValueError — Se os URIs de origem/destino forem inválidos ou se a cópia for de um bucket para um repositório.

Copie arquivos entre localizações no Hub.

Copie arquivos de um bucket ou repositório (modelo, conjunto de dados, espaço) para um bucket ou outro repositório. Tanto arquivos individuais quanto pastas inteiras são suportados.

Ao copiar pastas, um / no final do caminho de origem usa semântica estilo rsync: copia o conteúdo da pasta para o destino, sem aninhar a própria pasta de origem. Sem um / no final, a pasta de origem é aninhada dentro do destino (como no cp -r).

Ao copiar de um repositório para um bucket, os arquivos .gitattributes são excluídos automaticamente, pois são metadados específicos do git e não são relevantes em um contexto de bucket.

Cópias de repositório para repositório usam CommitOperationCopy por baixo dos panos e criam um commit no repositório de destino. Cópias de bucket para repositório não são suportadas.

Cópias no lado do servidor funcionam apenas dentro da mesma região de armazenamento.

Exemplo:

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

Parâmetros

  • repo_id (str) — O repositório no qual o branch será criado. Exemplo: "user/my-cool-model".
  • branch (str) — O nome do branch a ser criado.
  • revision (str, opcional) — A revisão git a partir da qual criar o branch. Pode ser o nome de um branch ou o OID/SHA de um commit, como uma string hexadecimal. O padrão é o head do branch "main".
  • 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.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" ao criar um branch em um dataset ou space, None ou "model" ao marcar uma tag em um model. O padrão é None.
  • exist_ok (bool, opcional, padrão False) — Se True, não levanta um erro se o branch já existir.

Exceções

RepositoryNotFoundError ou BadRequestError ou HfHubHTTPError

  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou o repositório não existe.
  • BadRequestError — Se a referência para um branch for inválida. Ex.: refs/pr/5 ou ‘refs/foo/bar’.
  • HfHubHTTPError — Se o branch já existir no repositório (erro 409) e exist_ok estiver definido como False.

Crie um novo branch para um repositório no Hub, a partir da revisão especificada (padrão é main). Para encontrar uma revisão adequada às suas necessidades, você pode usar list_repo_refs() ou 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

Parâmetros

  • bucket_id (str) — Um namespace (usuário ou organização) e um nome de bucket separados por /. Se nenhum namespace for fornecido, o bucket será criado no namespace do usuário atual.
  • private (bool, opcional) — Se deve tornar o bucket privado. Se None (padrão), o bucket será público, a menos que o padrão da organização seja privado. Não pode ser passado junto com visibility.
  • visibility (Literal["public", "private"], opcional) — Visibilidade do bucket. Pode ser "public" ou "private". Se None (padrão), o bucket será público, a menos que o padrão da organização seja privado.
  • resource_group_id (str, opcional) — Grupo de recursos no qual criar o bucket. Grupos de recursos estão disponíveis apenas para organizações Enterprise Hub e permitem definir quais membros da organização podem acessar o recurso. O ID de um grupo de recursos pode ser encontrado na URL da página do recurso no Hub (por exemplo, "66670e5163145ca562cb1988"). Para saber mais sobre grupos de recursos, consulte https://huggingface.co/docs/hub/en/security-resource-groups.
  • region (Literal["us", "eu"], opcional) — Região da nuvem em que o bucket será criado. Pode ser "us" ou "eu". Se não for especificada, o bucket será criado na região padrão. Requer o plano Team ou superior.
  • exist_ok (bool, opcional, padrão False) — Se True, não levanta um erro se o bucket já existir.
  • 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.

Retorna

BucketUrl

URL do bucket recém-criado contendo atributos como endpoint, namespace e bucket_id.

Crie um bucket no Hub.

Exemplo:

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

Parâmetros

  • title (str) — Título da coleção a ser criada. Exemplo: "Recent models".
  • namespace (str, opcional) — Namespace da coleção a ser criada (nome de usuário ou organização). O padrão será o nome do proprietário.
  • description (str, opcional) — Descrição da coleção a ser criada. O tamanho máximo para uma descrição é de 150 caracteres.
  • private (bool, opcional) — Se a coleção deve ser privada ou não. O padrão é False (ou seja, coleção pública).
  • resource_group_id (str, opcional) — Atribui a coleção a um grupo de recursos da organização proprietária. Válido apenas para coleções pertencentes a organizações. O ID do grupo de recursos é uma string hexadecimal de 24 caracteres.
  • exists_ok (bool, opcional) — Se True, não lança um erro se a coleção já existir.
  • 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.

Crie uma nova Collection no Hub.

Retorna: Collection

Exemplo:

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

Parâmetros

  • repo_id (str) — O repositório no qual o commit será criado, por exemplo: "username/custom_transformers"
  • operations (Iterable de ~hf_api.CommitOperation) — Um iterável de operações a incluir no commit, sendo:
    • ~hf_api.CommitOperationAdd para enviar um arquivo
    • ~hf_api.CommitOperationDelete para excluir um arquivo
    • ~hf_api.CommitOperationCopy para copiar um arquivo

    Os objetos de operação serão alterados para incluir informações relativas ao upload. Não reutilize os mesmos objetos para múltiplos commits.

  • commit_message (str) — O resumo (primeira linha) do commit que será criado.
  • commit_description (str, opcional) — A descrição do commit que será criado
  • 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.
  • repo_type (str, opcional) — Defina como "dataset", "space" ou "kernel" se estiver fazendo upload para um repositório de dataset, space ou kernel, None ou "model" se estiver fazendo upload para um modelo. O padrão é None.
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo do ramo "main".
  • create_pr (boolean, opcional) — Se deve ou não criar um Pull Request com esse commit. O padrão é False. Se revision não estiver definido, o PR será aberto contra o ramo "main". Se revision estiver definido e for um ramo, o PR será aberto contra esse ramo. Se revision estiver definido e não for um nome de ramo (exemplo: um oid de commit), um RevisionNotFoundError será retornado pelo servidor.
  • num_threads (int, opcional) — Número de threads concorrentes para upload de arquivos. O padrão é 5. Definir como 2 significa que no máximo 2 arquivos serão enviados simultaneamente.
  • parent_commit (str, opcional) — O OID / SHA do commit pai, como uma string hexadecimal. Abreviações (os 7 primeiros caracteres) também são suportadas. Se especificado e create_pr for False, o commit falhará se revision não apontar para parent_commit. Se especificado e create_pr for True, a pull request será criada a partir de parent_commit. Especificar parent_commit garante que o repositório não foi alterado antes de commitar as mudanças, e pode ser especialmente útil se o repositório for atualizado / commitado simultaneamente.
  • run_as_future (bool, opcional) — Se este método deve ser executado em segundo plano ou não. Os trabalhos em segundo plano são executados sequencialmente sem bloquear a thread principal. Passar run_as_future=True retornará um objeto Future. O valor padrão é False.

Retorna

CommitInfo ou Future

Instância de CommitInfo contendo informações sobre o commit recém-criado (hash do commit, url do commit, url do pr, mensagem do commit,…). Se run_as_future=True for passado, retorna um objeto Future que conterá o resultado quando executado.

Exceções

ValueError ou RepositoryNotFoundError

  • ValueError — Se a mensagem de commit estiver vazia.
  • ValueError — Se o commit pai não for um OID de commit válido.
  • ValueError — Se um arquivo README.md com uma seção de metadados inválida for commitado. Nesse caso, o commit falhará precoce, antes de tentar enviar qualquer arquivo.
  • ValueError — If create_pr is True and revision is neither None nor "main".
  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou o repositório não existe.

Cria um commit no repositório informado, excluindo e enviando arquivos conforme necessário.

A lista de entrada de CommitOperation será alterada durante o processo de commit. Não reutilize os mesmos objetos para múltiplos commits.

create_commit pressupõe que o repositório já exista no Hub. Se você receber um erro de cliente 404, verifique se está autenticado, se seu token possui as permissões necessárias e se repo_id e repo_type estão configurados corretamente. Se o repositório não existir, crie-o primeiro usando create_repo().

create_commit é limitado a 25 mil arquivos LFS e a um payload de 1 GB para arquivos regulares.

create_discussion

< >

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • title (str) — O título da discussão. Pode ter até 200 caracteres e deve ter pelo menos 3 caracteres. Espaços em branco no início e no final serão removidos.
  • 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.
  • description (str, opcional) — Uma descrição opcional para o Pull Request. Padrão: "Discussion opened with the huggingface_hub Python library"
  • pull_request (bool, opcional) — Se deve criar um Pull Request ou uma discussão. Se True, cria um Pull Request. Se False, cria uma discussão. O padrão é False.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.

Cria uma Discussão ou uma Pull Request.

Pull Requests criados programaticamente estarão no status "draft".

A criação de um Pull Request com alterações também pode ser feita de uma só vez com HfApi.create_commit().

Retorna: DiscussionWithDetails

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

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

Parâmetros

  • name (str) — O nome exclusivo para o novo Inference Endpoint.
  • repository (str) — O nome do repositório de modelos associado ao Inference Endpoint (por exemplo, "gpt2").
  • framework (str) — O framework de machine learning usado para o modelo (por exemplo, "custom").
  • accelerator (str) — O acelerador de hardware a ser usado para inferência (por exemplo, "cpu").
  • instance_size (str) — O tamanho ou o tipo da instância a ser usada para hospedar o modelo (por exemplo, "x4").
  • instance_type (str) — O tipo de instância na nuvem onde o Inference Endpoint será implantado (por exemplo, "intel-icl").
  • region (str) — A região da nuvem na qual o Inference Endpoint será criado (por exemplo, "us-east-1").
  • vendor (str) — O provedor de nuvem ou fornecedor onde o Inference Endpoint será hospedado (por exemplo, "aws").
  • account_id (str, opcional) — Descontinuado e ignorado. Use private_link_account_id e private_link_region para configurar o AWS PrivateLink.
  • private_link_account_id (str, opcional) — O ID da conta AWS autorizado a acessar o Inference Endpoint por meio do AWS PrivateLink. Exige private_link_region.
  • private_link_region (str, opcional) — A região da AWS do ponto de entrada do PrivateLink ("us-east-1" ou "eu-west-1"), onde o endpoint da VPC de private_link_account_id se conectará. Independente da region e do vendor de computação.
  • min_replica (int, opcional) — O número mínimo de réplicas (instâncias) a manter em execução para o Inference Endpoint. Para habilitar o dimensionamento para zero, defina este valor como 0 e ajuste scale_to_zero_timeout de acordo. O valor padrão é 1.
  • max_replica (int, opcional) — O número máximo de réplicas (instâncias) para as quais o Inference Endpoint será dimensionado. O valor padrão é 1.
  • scaling_metric (str ou InferenceEndpointScalingMetric , opcional) — A métrica de referência para o dimensionamento. Deve ser “pendingRequests” ou “hardwareUsage” quando fornecida. O valor padrão é None (ou seja: deixa o serviço HF Endpoints especificar a métrica).
  • scaling_threshold (float, opcional) — O limiar da métrica de escala usado para acionar o aumento de escala. Ignorado quando a métrica de escala não é fornecida. Padrão: None (significa: deixar o serviço HF Endpoints especificar o limiar).
  • scale_to_zero_timeout (int, opcional) — A duração, em minutos, antes de um endpoint inativo ser reduzido a zero, ou sem redução a zero se definido como None e min_replica não for 0. O valor padrão é None.
  • revision (str, opcional) — A revisão específica do modelo a ser implantada no Inference Endpoint (por exemplo, "6c0e6080953db56375760c0471a8c5f2929baf11").
  • task (str, opcional) — A tarefa na qual o modelo será implantado (por exemplo, "text-classification").
  • custom_image (dict, opcional) — A imagem de container a ser executada. Pode ser um dicionário com chaves por variante de imagem (por exemplo, {"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}‌}, também sGLang, tgi, tei, llamacpp, hfServe, …), que é encaminhado como está, ou um dicionário simples descrevendo um container personalizado (por exemplo, {"url": ..., "port": ...}), que é enviado como {"custom": ...} (veja os exemplos). O padrão é a imagem gerenciada pela Hugging Face.
  • container_registry_username (str, opcional) — Nome de usuário usado para autenticar com o registro que hospeda uma imagem de container personalizada.
  • container_registry_password (str, opcional) — Senha usada para autenticar no registro que hospeda uma imagem de container personalizada. Exige container_registry_username. Omitida do payload da API quando não fornecida.
  • container_command (list[str], opcional) — Substitui o comando de entrada do container (corresponde a model.command no payload da API). Funciona com imagens de engine gerenciadas (por exemplo, vLLM, SGLang) e imagens personalizadas.
  • container_args (list[str], opcional) — Argumentos adicionados ao entrypoint do container (corresponde a model.args no payload da API). Funciona com imagens de engine gerenciadas (por exemplo, vLLM, SGLang) e imagens personalizadas.
  • env (dict[str, str], opcional) — Variáveis de ambiente não confidenciais para injetar no ambiente do contêiner.
  • secrets (dict[str, str], opcional) — Valores de segredo a serem injetados no ambiente do contêiner.
  • type ([`InferenceEndpointType], *optional*) -- The type of the Inference Endpoint, which can be “authenticated”(default),“public”or“private”`.
  • domain (str, opcional) — O domínio personalizado para a implantação do Inference Endpoint. Se configurado, o Inference Endpoint ficará disponível neste domínio (por exemplo, "my-new-domain.cool-website.woof").
  • path (str, opcional) — O caminho personalizado para o modelo implantado, deve começar com / (ex.: "/models/google-bert/bert-base-uncased").
  • cache_http_responses (bool, opcional) — Se deve ou não fazer cache das respostas HTTP do Inference Endpoint. O padrão é False.
  • tags (list[str], opcional) — Uma lista de tags para associar ao Inference Endpoint.
  • namespace (str, opcional) — O namespace onde o Inference Endpoint será criado. O padrão é o namespace do usuário atual.
  • 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.

Retorna

InferenceEndpoint

informações sobre o Inference Endpoint atualizado.

Crie um novo Inference Endpoint.

Os valores de accelerator, instance_size, instance_type, region e vendor dependem uns dos outros; use list_inference_endpoints_hardware() para listar as combinações válidas.

Exemplo:

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

Parâmetros

  • repo_id (str, opcional) — O ID do modelo no catálogo a ser implantado como um Inference Endpoint. Mutuamente exclusivo com recipe_id.
  • recipe_id (str, opcional) — O ID da receita do catálogo a ser implantada (veja InferenceCatalogRecipe). Mutuamente exclusivo com repo_id.
  • name (str, opcional) — O nome exclusivo para o novo Inference Endpoint. Se não for fornecido, um nome aleatório será gerado.
  • accelerator (str, opcional) — O acelerador de hardware a ser usado para inferência. Os valores possíveis incluem "cpu", "gpu" e "neuron". Se não for fornecido, o servidor usará um padrão adequado para o modelo. Válido apenas com repo_id.
  • gguf_file (str, opcional) — O arquivo GGUF a ser implantado, para modelos que possuem uma receita por quantização (por exemplo, "Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf"). Válido apenas com repo_id.
  • token (bool ou 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).
  • namespace (str, opcional) — O namespace onde o Inference Endpoint será criado. O padrão é o namespace do usuário atual.

Retorna

InferenceEndpoint

informações sobre o novo Inference Endpoint.

Crie um novo Inference Endpoint a partir do Inference Catalog do Hugging Face.

O objetivo do Inference Catalog é fornecer uma lista curada de modelos otimizados para inferência e para os quais as configurações padrão foram testadas. Consulte https://huggingface.co/proxy/endpoints.huggingface.co/catalog para ver a lista de modelos disponíveis no catálogo.

Cada modelo do catálogo é implantado por meio de uma receita: uma combinação de hardware e motor que foi testada para ele. Passe repo_id para implantar a receita padrão de um modelo, opcionalmente refinada com accelerator e gguf_file, ou passe recipe_id para implantar uma receita exata listada por list_inference_catalog().

create_inference_endpoint_from_catalog é experimental. Sua API está sujeita a alterações no futuro. Por favor, forneça feedback se você tiver alguma sugestão ou solicitação.

create_pull_request

< >

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • title (str) — O título da discussão. Pode ter até 200 caracteres e deve ter pelo menos 3 caracteres. Espaços em branco no início e no final serão removidos.
  • 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.
  • description (str, opcional) — Uma descrição opcional para o Pull Request. Padrão: "Discussion opened with the huggingface_hub Python library"
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.

Cria um Pull Request. Pull Requests criados programaticamente ficarão no status "draft".

A criação de um Pull Request com alterações também pode ser feita de uma só vez com HfApi.create_commit();

Este é um wrapper em torno de HfApi.create_discussion().

Retorna: DiscussionWithDetails

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • 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.
  • private (bool, opcional) — Se deve tornar o repositório privado. Se None (padrão), o repositório será público, a menos que o padrão da organização seja privado. Este valor é ignorado se o repositório já existir. Não pode ser passado junto com visibility.
  • visibility (Literal["public", "private", "protected"], opcional) — Visibilidade do repositório. Pode ser "public" ou "private", ou "protected" para Spaces. Se None (padrão), o repositório será público, a menos que o padrão da organização seja privado. Este valor é ignorado se o repositório já existir.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.
  • exist_ok (bool, opcional, padrão False) — Se True, não levanta um erro se o repositório já existir.
  • resource_group_id (str, opcional) — Grupo de recursos no qual criar o repositório. Grupos de recursos estão disponíveis apenas para organizações Enterprise do Hub e permitem definir quais membros da organização podem acessar o recurso. O ID de um grupo de recursos pode ser encontrado na URL da página do recurso no Hub (por exemplo, "66670e5163145ca562cb1988"). Para saber mais sobre grupos de recursos, consulte https://huggingface.co/docs/hub/en/security-resource-groups.
  • region (Literal["us", "eu"], opcional) — Região da nuvem em que o repositório será criado. Pode ser "us" ou "eu". Se não for especificada, o repositório será criado na região padrão. Requer o plano Team ou superior.
  • space_sdk (str, opcional) — Escolha do SDK a ser usado se repo_type for “space”. Pode ser “streamlit”, “gradio”, “docker” ou “static”. Spaces "static" são gratuitos para todos. Os outros SDKs rodam em hardware de computação: no hardware gratuito cpu-basic, eles exigem uma assinatura (PRO para usuários, Team ou Enterprise para organizações), enquanto o hardware pago exige apenas faturamento (um método de pagamento e créditos pré-pagos).
  • space_hardware (SpaceHardware ou str, opcional) — Escolha de Hardware se repo_type for “space”. Veja SpaceHardware para uma lista completa.
  • space_sleep_time (int, opcional) — Número de segundos de inatividade a aguardar antes de um Space ser colocado em modo de suspensão. Defina como -1 se você não quiser que seu Space entre em suspensão (comportamento padrão para hardware atualizado). Para hardware gratuito, você não pode configurar o tempo de suspensão (o valor é fixado em 48 horas de inatividade). Veja https://huggingface.co/docs/hub/spaces-gpus#sleep-time para mais detalhes.
  • space_secrets (list[dict[str, str]], opcional) — Uma lista de chaves de segredo para definir no seu Space. Cada item está no formato {"key": ..., "value": ..., "description": ...}, em que description é opcional. Para mais detalhes, consulte https://huggingface.co/docs/hub/spaces-overview#managing-secrets.
  • space_variables (list[dict[str, str]], opcional) — Uma lista de variáveis de ambiente públicas para definir no seu Space. Cada item está no formato {"key": ..., "value": ..., "description": ...}, em que description é opcional. Para mais detalhes, consulte https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables.
  • space_volumes (list[Volume], opcional) — Uma lista de objetos Volume para montar no Space no momento da criação. Cada volume possui um type ("bucket", "model", "dataset" ou "space"), um source (ID do repositório ou bucket), um mount_path (caminho dentro do container) e os campos opcionais revision, read_only e path. Aplicável apenas se repo_type for “space”.
  • space_template (str, opcional) — Semeie o novo Space a partir de um modelo oficial. Pode ser o id do repositório do modelo (por exemplo, "SpacesExamples/jupyterlab") ou seu nome curto (por exemplo, "JupyterLab"). Use HfApi.list_space_templates() para listar os modelos disponíveis. Aplicável apenas se repo_type for “space”. Se o modelo for recomendado como privado e a visibilidade não for definida explicitamente, o Space será criado como privado.

Retorna

RepoUrl

URL do repositório recém-criado. O valor é uma subclasse de str contendo atributos como endpoint, repo_type e repo_id.

Crie um repositório vazio no 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 )

Parâmetros

  • image (str) — A imagem Docker a ser usada. Exemplos: "ubuntu", "python:3.12", "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel". Exemplo com uma imagem de um Space: "hf.co/spaces/lhoestq/duckdb".
  • command (list[str]) — O comando a ser executado. Exemplo: ["echo", "hello"].
  • schedule (str) — Um dos valores “@annually”, “@yearly”, “@monthly”, “@weekly”, “@daily”, “@hourly”, ou uma expressão de agendamento CRON (por exemplo, ‘0 9 * * 1’ para 9h de toda segunda-feira).
  • suspend (bool, opcional) — Se True, o Job agendado é suspenso (pausado). O valor padrão é False.
  • concurrency (bool, opcional) — Se True, múltiplas instâncias deste Job podem ser executadas simultaneamente. O valor padrão é False.
  • env (dict[str, Any], opcional) — Define as variáveis de ambiente para o Job.
  • secrets (dict[str, Any], opcional) — Define as variáveis de ambiente secretas para o Job.
  • flavor (str, opcional) — Flavor para o hardware. Consulte JobHardware para os valores possíveis. Padrão: "cpu-basic".
  • timeout (Union[int, float, str], opcional) — Duração máxima para o Job: int com s (segundos, padrão), m (minutos), h (horas) ou d (dias). Exemplo: 300 ou "5m" para 5 minutos.
  • attempts (int, opcional) — Número máximo de tentativas para cada execução, incluindo a tentativa inicial. O valor padrão é 1.
  • name (str, opcional) — Um nome para o Job agendado. Armazenado como o rótulo name. Não pode ser passado junto com uma chave name em labels. Os nomes não precisam ser únicos. O padrão é um nome derivado da imagem e do comando (com um sufixo de hash curto).
  • labels (dict[str, str], opcional) — Rótulos a serem anexados ao job (pares chave-valor).
  • volumes (list[Volume], opcional) — Buckets ou Repos do Hugging Face a serem montados como volumes no contêiner do job. Cada volume é um Volume com type ("bucket", "model", "dataset" ou "space"), source (por exemplo, "username/my-bucket") e mount_path (por exemplo, "/data").
  • expose (list[int], opcional) — Portas de contêiner a serem expostas através do proxy de jobs. Cada porta listada é acessível no domínio público de jobs (ex.: https://<job_id>--8000.hf.jobs). O acesso sempre requer um token HF com permissão de leitura no namespace do job. Use expose_public para acesso não autenticado.
  • expose_public (list[int], opcional) — Portas a serem expostas através do proxy de Jobs sem autenticação. Elas não precisam estar listadas em expose.
  • resource_group_id (str, opcional) — O ID do grupo de recursos em que o Job agendado será criado. Usado para controlar o acesso a recursos dentro de uma organização e para recursos de atribuição de custos/limites de gastos. Se não for fornecido, o Job agendado será criado fora de qualquer grupo de recursos.
  • namespace (str, opcional) — O namespace onde o Job será criado. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Crie Jobs de computação agendados na infraestrutura do Hugging Face.

Exemplo:

Crie seu primeiro Job agendado:

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

Use uma expressão de agendamento 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 * * * *")

Crie um Job de GPU agendado:

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

Parâmetros

  • script (str) — Caminho ou URL do script UV, ou um comando.
  • script_args (list[str], opcional) — Argumentos a serem passados para o script ou para um comando.
  • schedule (str) — Um dos valores “@annually”, “@yearly”, “@monthly”, “@weekly”, “@daily”, “@hourly”, ou uma expressão de agendamento CRON (por exemplo, ‘0 9 * * 1’ para 9h de toda segunda-feira).
  • suspend (bool, opcional) — Se True, o Job agendado é suspenso (pausado). O valor padrão é False.
  • concurrency (bool, opcional) — Se True, múltiplas instâncias deste Job podem ser executadas simultaneamente. O valor padrão é False.
  • dependencies (list[str], opcional) — Dependências a serem usadas para executar o script UV.
  • python (str, opcional) — Use uma versão específica do Python. O padrão é 3.12.
  • image (str, opcional, padrão “ghcr.io/astral-sh/uv —python3.12-bookworm”): Use uma imagem Docker personalizada com uv instalado.
  • env (dict[str, Any], opcional) — Define as variáveis de ambiente para o Job.
  • secrets (dict[str, Any], opcional) — Define as variáveis de ambiente secretas para o Job.
  • flavor (str, opcional) — Flavor para o hardware. Consulte JobHardware para os valores possíveis. Padrão: "cpu-basic".
  • timeout (Union[int, float, str], opcional) — Duração máxima para o Job: int com s (segundos, padrão), m (minutos), h (horas) ou d (dias). Exemplo: 300 ou "5m" para 5 minutos.
  • attempts (int, opcional) — Número máximo de tentativas para cada execução, incluindo a tentativa inicial. O valor padrão é 1.
  • name (str, opcional) — Um nome para o Job agendado. Armazenado como o rótulo name. Não pode ser passado junto com uma chave name em labels. Os nomes não precisam ser únicos. O padrão é um nome derivado do script e de seus argumentos (com um sufixo de hash curto).
  • labels (dict[str, str], opcional) — Rótulos a serem anexados ao job (pares chave-valor).
  • volumes (list[Volume], opcional) — Buckets ou Repos do Hugging Face a serem montados como volumes no contêiner do job. Cada volume é um Volume com type ("bucket", "model", "dataset" ou "space"), source (por exemplo, "username/my-bucket") e mount_path (por exemplo, "/data").
  • expose (list[int], opcional) — Portas de contêiner a serem expostas através do proxy de jobs. Cada porta listada é acessível no domínio público de jobs (ex.: https://<job_id>--8000.hf.jobs). O acesso sempre requer um token HF com permissão de leitura no namespace do job. Use expose_public para acesso não autenticado.
  • expose_public (list[int], opcional) — Portas a serem expostas através do proxy de Jobs sem autenticação. Elas não precisam estar listadas em expose.
  • resource_group_id (str, opcional) — O ID do grupo de recursos em que o Job agendado será criado. Usado para controlar o acesso a recursos dentro de uma organização e para recursos de atribuição de custos/limites de gastos. Se não for fornecido, o Job agendado será criado fora de qualquer grupo de recursos.
  • namespace (str, opcional) — O namespace onde o Job será criado. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Execute um Job de script UV na infraestrutura do Hugging Face.

Diferentemente de hf jobs uv run, este método ignora a tabela opcional [tool.hf-jobs] que um script UV pode carregar em seu cabeçalho PEP 723 (veja o guia de Jobs): a configuração de lançamento deve ser passada explicitamente aqui.

Exemplo:

Agendar um script a partir de uma 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")

Agendar um script local:

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

Agendar um comando:

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

Parâmetros

  • repo_id (str) — O repositório no qual um commit será marcado. Exemplo: "user/my-cool-model".
  • tag (str) — O nome da tag a ser criada.
  • tag_message (str, opcional) — A descrição da tag a ser criada.
  • revision (str, opcional) — A revisão git a ser marcada. Pode ser o nome de um branch ou o OID/SHA de um commit, como uma string hexadecimal. Abreviações (os 7 primeiros caracteres) também são suportadas. O padrão é o head do branch "main".
  • 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.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" ao marcar um dataset ou space, None ou "model" ao marcar um modelo. O padrão é None.
  • exist_ok (bool, opcional, padrão False) — Se True, não levanta um erro se a tag já existir.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError ou HfHubHTTPError

  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou o repositório não existe.
  • RevisionNotFoundError — Se a revisão não for encontrada (erro 404) no repositório.
  • HfHubHTTPError — Se o branch já existir no repositório (erro 409) e exist_ok estiver definido como False.

Marque um commit específico de um repositório no 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

Parâmetros

  • url (str) — URL para onde enviar o payload.
  • job_id (str) — ID do Job de origem a ser acionado com o payload do webhook na variável de ambiente WEBHOOK_PAYLOAD. Variáveis de ambiente adicionais estão disponíveis para conveniência: WEBHOOK_REPO_ID, WEBHOOK_REPO_TYPE e WEBHOOK_SECRET.
  • watched (list[WebhookWatchedItem]) — Lista de WebhookWatchedItem a serem monitorados pelo webhook. Pode ser usuários, organizações, modelos, conjuntos de dados, espaços ou buckets. Os itens monitorados também podem ser fornecidos como dicionários simples.
  • domains (list[Literal["repo", "discussion"]], opcional) — Lista de domínios para monitorar. Pode ser “repo”, “discussion” ou ambos. O padrão é ambos.
  • secret (str, opcional) — Um segredo para assinar a carga útil.
  • secrets (dict[str, str], opcional) — Variáveis de ambiente secretas para o Job acionado pelo webhook (por exemplo, {"HF_TOKEN": "hf_***"}). Válido apenas com job_id. Os segredos do Job de origem não são copiados para o webhook, portanto, passe-os aqui.
  • 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.

Retorna

WebhookInfo

Informações sobre o webhook recém-criado.

Crie um novo webhook.

O webhook pode enviar um payload para uma URL ou acionar a execução de um Job na infraestrutura do Hugging Face. Esta função deve ser chamada com um de url ou job_id, mas não com ambos.

Exemplo:

Crie um webhook que envia um payload para uma 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,
)

Execute um Job e, em seguida, crie um webhook que aciona esse Job

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • revision (str, opcional) — A revisão do repositório do dataset de onde obter as informações.
  • timeout (float, opcional) — Se deve definir um tempo limite para a solicitação ao Hub.
  • files_metadata (bool, opcional) — Se deve ou não recuperar metadados dos arquivos no repositório (tamanho, metadados do LFS, etc). O padrão é False.
  • expand (list[ExpandDatasetProperty_T], opcional) — Lista as propriedades a serem retornadas na resposta. Quando usado, apenas as propriedades da lista serão retornadas. Este parâmetro não pode ser usado se files_metadata for passado. Os valores possíveis são "author", "cardData", "citation", "createdAt", "disabled", "description", "downloads", "downloadsAllTime", "gated", "lastModified", "likes", "mainSize", "paperswithcode_id", "private", "siblings", "sha", "tags", "trendingScore", "usedStorage" e "resourceGroup".
  • 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.

Retorna

hf_api.DatasetInfo

As informações do repositório do conjunto de dados.

Obtenha informações sobre um dataset específico no huggingface.co.

O Dataset pode ser privado se você passar um token aceitável.

Gera os seguintes erros:

  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
  • RevisionNotFoundError Se a revisão de onde o download deve ser feito não for encontrada.

delete_branch

< >

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

Parâmetros

  • repo_id (str) — O repositório no qual um ramo será excluído. Exemplo: "user/my-cool-model".
  • branch (str) — O nome do branch a ser excluído.
  • 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.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" ao criar um branch em um dataset ou space, None ou "model" ao marcar uma tag em um model. O padrão é None.

Exceções

RepositoryNotFoundError ou HfHubHTTPError

  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou o repositório não existe.
  • HfHubHTTPError — Se estiver tentando excluir uma branch protegida. Ex.: main não pode ser excluída.
  • HfHubHTTPError — Se você tentar excluir uma branch que não existe.

Excluir um branch de um repositório no Hub.

delete_bucket

< >

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

Parâmetros

  • bucket_id (str) — O ID do bucket (por exemplo, "username/my-bucket").
  • missing_ok (bool, opcional, padrão False) — Se True, não levanta um erro se o bucket não existir.
  • 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.

Exceções

BucketNotFoundError

  • BucketNotFoundError — Se o bucket não for encontrado e missing_ok estiver definido como False (padrão).

Excluir um bucket do Hub.

Exemplo:

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

Parâmetros

  • collection_slug (str) — Slug da coleção a ser excluída. Exemplo: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • missing_ok (bool, opcional) — Se True, não levanta um erro se a coleção não existir.
  • 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.

Excluir uma coleção no Hub.

Exemplo:

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

Esta é uma ação irreversível. Uma coleção excluída não pode ser restaurada.

delete_collection_item

< >

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

Parâmetros

  • collection_slug (str) — Slug da coleção a ser atualizada. Exemplo: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • item_object_id (str) — ID do item na coleção. Este não é o id do item no Hub (repo_id ou paper id). Ele deve ser obtido de um objeto CollectionItem. Exemplo: collection.items[0].item_object_id.
  • missing_ok (bool, opcional) — Se True, não levanta um erro se o item não existir.
  • 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.

Excluir um item de uma coleção.

Exemplo:

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

Parâmetros

  • path_in_repo (str) — Caminho de arquivo relativo no repositório, por exemplo: "checkpoints/1fec34a/weights.bin"
  • repo_id (str) — O repositório do qual o arquivo será excluído, por exemplo: "username/custom_transformers"
  • 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.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se o arquivo estiver em um dataset ou space, None ou "model" se estiver em um model. O padrão é None.
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo do ramo "main".
  • commit_message (str, opcional) — O resumo / título / primeira linha do commit gerado. O padrão é f"Delete {path_in_repo} with huggingface_hub".
  • commit_description (str, opcional) — A descrição do commit gerado
  • create_pr (boolean, opcional) — Se deve ou não criar um Pull Request com esse commit. O padrão é False. Se revision não estiver definido, o PR será aberto contra o ramo "main". Se revision estiver definido e for um ramo, o PR será aberto contra esse ramo. Se revision estiver definido e não for um nome de ramo (exemplo: um oid de commit), um RevisionNotFoundError será retornado pelo servidor.
  • parent_commit (str, opcional) — O OID / SHA do commit pai, como uma string hexadecimal. Abreviações (os 7 primeiros caracteres) também são suportadas. Se especificado e create_pr for False, o commit falhará se revision não apontar para parent_commit. Se especificado e create_pr for True, a pull request será criada a partir de parent_commit. Especificar parent_commit garante que o repositório não tenha sido alterado antes de commitar as mudanças, o que pode ser especialmente útil se o repositório for atualizado / commitado simultaneamente.

Exclui um arquivo no repositório especificado.

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
  • RevisionNotFoundError Se a revisão de onde o download deve ser feito não for encontrada.
  • EntryNotFoundError Se o arquivo a ser baixado não for encontrado.

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 )

Parâmetros

  • repo_id (str) — O repositório do qual a pasta será excluída, por exemplo: "username/custom_transformers"
  • delete_patterns (list[str]) — Lista de arquivos ou pastas para excluir. Cada string pode ser um caminho de arquivo, um caminho de pasta ou um padrão de curinga. Os padrões são curingas padrão (padrões de globbing) conforme documentado aqui. A correspondência de padrões é baseada em fnmatch. Observe que fnmatch faz a correspondência de * através de fronteiras de caminho, ao contrário do globbing tradicional do shell Unix. Por exemplo, ["file.txt", "folder/", "data/*.parquet"]
  • token (bool ou 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. para o token armazenado.
  • repo_type (str, opcional) — Tipo do repositório do qual os arquivos serão excluídos. Pode ser "model", "dataset" ou "space". O padrão é "model".
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo do ramo "main".
  • commit_message (str, opcional) — O resumo (primeira linha) do commit gerado. O padrão é f"Delete files using huggingface_hub".
  • commit_description (str, opcional) — A descrição do commit gerado.
  • create_pr (boolean, opcional) — Se deve ou não criar um Pull Request com esse commit. O padrão é False. Se revision não estiver definido, o PR será aberto contra o ramo "main". Se revision estiver definido e for um ramo, o PR será aberto contra esse ramo. Se revision estiver definido e não for um nome de ramo (exemplo: um oid de commit), um RevisionNotFoundError será retornado pelo servidor.
  • parent_commit (str, opcional) — O OID / SHA do commit pai, como uma string hexadecimal. Abreviações (os 7 primeiros caracteres) também são suportadas. Se especificado e create_pr for False, o commit falhará se revision não apontar para parent_commit. Se especificado e create_pr for True, a pull request será criada a partir de parent_commit. Especificar parent_commit garante que o repositório não tenha sido alterado antes de commitar as mudanças, o que pode ser especialmente útil se o repositório for atualizado / commitado simultaneamente.

Excluir arquivos de um repositório no Hub.

Se um caminho de pasta for fornecido, a pasta inteira será excluída, bem como todos os arquivos que ela continha.

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 )

Parâmetros

  • path_in_repo (str) — Caminho relativo da pasta no repositório, por exemplo: "checkpoints/1fec34a".
  • repo_id (str) — O repositório do qual a pasta será excluída, por exemplo: "username/custom_transformers"
  • token (bool ou 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. para o token armazenado.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se a pasta estiver em um dataset ou space, None ou "model" se estiver em um model. O padrão é None.
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo do ramo "main".
  • commit_message (str, opcional) — O resumo / título / primeira linha do commit gerado. O padrão é f"Delete folder {path_in_repo} with huggingface_hub".
  • commit_description (str, opcional) — A descrição do commit gerado.
  • create_pr (boolean, opcional) — Se deve ou não criar um Pull Request com esse commit. O padrão é False. Se revision não estiver definido, o PR será aberto contra o ramo "main". Se revision estiver definido e for um ramo, o PR será aberto contra esse ramo. Se revision estiver definido e não for um nome de ramo (exemplo: um oid de commit), um RevisionNotFoundError será retornado pelo servidor.
  • parent_commit (str, opcional) — O OID / SHA do commit pai, como uma string hexadecimal. Abreviações (os 7 primeiros caracteres) também são suportadas. Se especificado e create_pr for False, o commit falhará se revision não apontar para parent_commit. Se especificado e create_pr for True, a pull request será criada a partir de parent_commit. Especificar parent_commit garante que o repositório não tenha sido alterado antes de commitar as mudanças, o que pode ser especialmente útil se o repositório for atualizado / commitado simultaneamente.

Exclui uma pasta no repositório especificado.

Wrapper simples ao redor do método create_commit().

delete_inference_endpoint

< >

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

Parâmetros

  • name (str) — O nome do Inference Endpoint a ser excluído.
  • namespace (str, opcional) — O namespace em que o Inference Endpoint está localizado. O padrão é o usuário atual.
  • 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.

Excluir um Inference Endpoint.

Esta operação não é reversível. Se você não deseja ser cobrado por um Inference Endpoint, é preferível pausá-lo com pause_inference_endpoint() ou reduzi-lo a zero com scale_to_zero_inference_endpoint().

Para sua conveniência, você também pode excluir um Inference Endpoint usando InferenceEndpoint.delete().

delete_repo

< >

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • 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.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model.
  • missing_ok (bool, opcional, padrão False) — Se True, não lança um erro se o repositório não existir.

Exceções

RepositoryNotFoundError

  • RepositoryNotFoundError — Se o repositório a ser excluído não for encontrado e missing_ok estiver definido como False (padrão).

Excluir um repositório do HuggingFace Hub. ATENÇÃO: essa ação é irreversível.

delete_scheduled_job

< >

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

Parâmetros

  • scheduled_job_id (str) — ID do Job agendado.
  • namespace (str, opcional) — O namespace onde o Job agendado está. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Excluir um Job de computação agendado na infraestrutura do Hugging Face.

delete_space_secret

< >

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

Parâmetros

  • repo_id (str) — ID do repositório a ser atualizado. Exemplo: "bigcode/in-the-stack".
  • key (str) — Chave secreta. Exemplo: "GITHUB_API_KEY".
  • 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.

Exclui um segredo de um Space.

Secrets permitem definir chaves ou tokens secretos em um Space sem codificá-los diretamente no código. Para mais detalhes, consulte https://huggingface.co/docs/hub/spaces-overview#managing-secrets.

delete_space_variable

< >

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

Parâmetros

  • repo_id (str) — ID do repositório a ser atualizado. Exemplo: "bigcode/in-the-stack".
  • key (str) — Chave da variável. Exemplo: "MODEL_REPO_ID"
  • 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.

Exclui uma variável de um Space.

Variáveis permitem definir variáveis de ambiente em um Space sem codificá-las diretamente. Para mais detalhes, consulte https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

delete_space_volumes

< >

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

Parâmetros

  • repo_id (str) — ID do Space a ser atualizado. Exemplo: "username/my-space".
  • 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.

Exceções

BadRequestError

  • BadRequestError — Se o Space não tiver volumes anexados.

Remove todos os volumes de um Space.

Exemplo:

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

Parâmetros

  • repo_id (str) — O repositório no qual uma tag será excluída. Exemplo: "user/my-cool-model".
  • tag (str) — O nome da tag a ser excluída.
  • 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.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" ao marcar um dataset ou space, None ou "model" ao marcar um modelo. O padrão é None.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError

  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou o repositório não existe.
  • RevisionNotFoundError — Se a tag não for encontrada.

Excluir uma tag de um repositório no Hub.

delete_webhook

< >

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

Parâmetros

  • webhook_id (str) — O identificador único do webhook a ser excluído.
  • 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.

Retorna

None

Excluir um webhook.

Exemplo:

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

disable_space_dev_mode

< >

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

Parâmetros

  • repo_id (str) — ID do Space para desativar o modo de desenvolvimento. Exemplo: "Salesforce/BLIP2".
  • 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.

Retorna

SpaceRuntime

Informações de tempo de execução sobre seu Space.

Exceções

RepositoryNotFoundError ou HfHubHTTPError ou BadRequestError

  • RepositoryNotFoundError — Se o seu Space não for encontrado (erro 404). Provavelmente o repo_id está incorreto ou o seu space é privado, mas você não está autenticado.
  • HfHubHTTPError — 403 Forbidden: apenas o proprietário de um Space pode definir o modo de desenvolvimento. Se você deseja gerenciar um Space que não é seu, peça ao proprietário abrindo uma Discussion ou duplique o Space.
  • BadRequestError — Se o seu Space for um Space estático. Spaces estáticos estão sempre em execução e nunca são cobrados. Se você deseja ocultar um Space estático, pode configurá-lo como privado.

Desative o modo de desenvolvimento em um Space.

O Spaces Dev Mode facilita o depuramento do seu aplicativo e torna a iteração em Spaces mais rápida, permitindo que você reinicie seu aplicativo sem parar o próprio contêiner do Space. A ativação do dev mode requer um plano PRO ou Team & Enterprise, mas a desativação é sempre permitida (por exemplo, após o vencimento de uma assinatura). Consulte https://huggingface.co/docs/hub/spaces-dev-mode para mais detalhes.

disable_webhook

< >

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

Parâmetros

  • webhook_id (str) — O identificador único do webhook a ser desativado.
  • 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.

Retorna

WebhookInfo

Informações sobre o webhook desativado.

Desativar um webhook (torna-o “desativado”).

Exemplo:

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

Parâmetros

  • bucket_id (str) — O ID do bucket (por exemplo, "username/my-bucket").
  • files (list[tuple[Union[str, BucketFile], Union[str, Path]]]) — Arquivos a serem baixados como uma lista de tuplas (origem, destino). Consulte a descrição acima para detalhes do formato.
  • raise_on_missing_files (bool, opcional) — Se True, levanta um EntryNotFoundError quando um arquivo solicitado não existe no bucket. Se False (padrão), arquivos ausentes são ignorados com um aviso.
  • 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.

Baixe arquivos de um bucket.

O parâmetro de entrada Files é uma lista de tuplas (remote file, local file) em que remote file é o caminho do arquivo no bucket ou um objeto BucketFile, e local file é o caminho de destino no sistema de arquivos local. Ao passar um objeto BucketFile (obtido de list_bucket_tree()), o método ignora a etapa de obtenção de metadados e baixa os arquivos diretamente.

Exemplo:

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

Parâmetros

  • from_id (str) — ID do repositório a ser duplicado. Exemplo: "openai/gdpval".
  • to_id (str, opcional) — ID do novo repositório. Exemplo: "myorg/my-gdpval". Se não for fornecido, o novo repositório terá o mesmo nome do repositório original, mas na sua conta.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver duplicando um dataset ou Space, None ou "model" se estiver duplicando um modelo. O padrão é None.
  • private (bool, opcional) — Se o novo repositório deve ser privado ou não. O padrão é a mesma privacidade do repositório original. Não pode ser passado junto com visibility.
  • visibility (Literal["public", "private", "protected"], opcional) — Visibilidade do novo repositório. Pode ser "public" ou "private", ou "protected" para Spaces. O padrão é a mesma visibilidade do repositório original.
  • 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.
  • exist_ok (bool, opcional, padrão False) — Se True, não levanta um erro se o repositório já existir.
  • resource_group_id (str, opcional) — Grupo de recursos no qual criar o novo repositório. Grupos de recursos estão disponíveis apenas para organizações Enterprise do Hub e permitem definir quais membros da organização podem acessar o recurso. O ID de um grupo de recursos pode ser encontrado na URL da página do recurso no Hub (por exemplo, "66670e5163145ca562cb1988"). Para saber mais sobre grupos de recursos, consulte https://huggingface.co/docs/hub/en/security-resource-groups.
  • space_hardware (SpaceHardware ou str, opcional) — Escolha de Hardware se repo_type for “space”. Exemplo: "t4-medium". Veja SpaceHardware para uma lista completa.
  • space_sleep_time (int, opcional) — Número de segundos de inatividade a aguardar antes de um Space ser colocado em modo de suspensão. Defina como -1 se você não quiser que seu Space entre em suspensão (comportamento padrão para hardware atualizado). Para hardware gratuito, você não pode configurar o tempo de suspensão (o valor é fixado em 48 horas de inatividade). Aplicável apenas se repo_type for “space”. Veja https://huggingface.co/docs/hub/spaces-gpus#sleep-time para mais detalhes.
  • space_secrets (list[dict[str, str]], opcional) — Uma lista de chaves de segredo para definir no seu Space. Cada item está no formato {"key": ..., "value": ..., "description": ...}, em que description é opcional. Aplicável apenas se repo_type for “space”. Para mais detalhes, consulte https://huggingface.co/docs/hub/spaces-overview#managing-secrets.
  • space_variables (list[dict[str, str]], opcional) — Uma lista de variáveis de ambiente públicas para definir no seu Space. Cada item está na forma {"key": ..., "value": ..., "description": ...}, onde description é opcional. Aplicável apenas se repo_type for “space”. Para mais detalhes, consulte https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables.
  • space_volumes (list[Volume], opcional) — Uma lista de objetos Volume para montar no Space no momento da duplicação. Cada volume possui um type ("bucket", "model", "dataset" ou "space"), um source (ID do repositório ou bucket), um mount_path (caminho dentro do container) e os campos opcionais revision, read_only e path. Aplicável apenas se repo_type for “space”.

Retorna

DuplicatedRepoUrl

URL do repositório recém-criado. O valor é uma subclasse de RepoUrl (e de str) contendo atributos como endpoint, repo_type, repo_id e files_copy_pending.

Exceções

RepositoryNotFoundError ou HfHubHTTPError

  • RepositoryNotFoundError — Se um dos parâmetros from_id ou to_id não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
  • HfHubHTTPError — Se a API do HuggingFace retornou um erro

Duplicar um repositório no Hub (modelo, conjunto de dados ou Space).

Isso executa uma cópia no servidor que preserva o histórico completo do git e os objetos LFS, sem exigir um ciclo de download/upload local.

O histórico do git é copiado imediatamente, mas os arquivos LFS/Xet ainda podem estar sendo copiados em segundo plano após o retorno deste método. Nesse caso, files_copy_pending é True no valor retornado e o download desses arquivos do novo repositório pode falhar até que a cópia seja concluída.

Exemplo:

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • discussion_num (int) — O número da Discussion ou Pull Request. Deve ser um inteiro estritamente positivo.
  • comment_id (str) — O ID do comentário a ser editado.
  • new_content (str) — O novo conteúdo do comentário. Os comentários suportam formatação em markdown.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.
  • 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.

Retorna

DiscussionComment

o comentário editado

Edita um comentário em uma Discussão / Pull Request.

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

enable_space_dev_mode

< >

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

Parâmetros

  • repo_id (str) — ID do Space para ativar o modo de desenvolvimento. Exemplo: "Salesforce/BLIP2".
  • 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.

Retorna

SpaceRuntime

Informações de tempo de execução sobre seu Space.

Exceções

RepositoryNotFoundError ou HfHubHTTPError ou BadRequestError

  • RepositoryNotFoundError — Se o seu Space não for encontrado (erro 404). Provavelmente o repo_id está incorreto ou o seu space é privado, mas você não está autenticado.
  • HfHubHTTPError — 403 Forbidden: apenas o proprietário de um Space pode definir o modo de desenvolvimento. Se você deseja gerenciar um Space que não é seu, peça ao proprietário abrindo uma Discussion ou duplique o Space.
  • BadRequestError — Se o seu Space for um Space estático. Spaces estáticos estão sempre em execução e nunca são cobrados. Se você deseja ocultar um Space estático, pode configurá-lo como privado.

Ative o modo de desenvolvimento em um Space.

O Spaces Dev Mode facilita o depuramento do seu aplicativo e torna a iteração em Spaces mais rápida, permitindo que você reinicie seu aplicativo sem parar o próprio contêiner do Space. Este recurso está disponível como parte de um plano PRO ou Team & Enterprise. Consulte https://huggingface.co/docs/hub/spaces-dev-mode para mais detalhes.

enable_webhook

< >

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

Parâmetros

  • webhook_id (str) — O identificador único do webhook a ser habilitado.
  • 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.

Retorna

WebhookInfo

Informações sobre o webhook habilitado.

Ative um webhook (torna-o “ativo”).

Exemplo:

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

Parâmetros

  • job_id (str) — ID do Job.
  • namespace (str, opcional) — O namespace onde o Job está em execução. O padrão é o namespace do usuário atual.
  • follow (bool, opcional) — Se True, transmite os logs em tempo real até que o job seja concluído (bloqueante). Se False (padrão), busca apenas os logs atualmente disponíveis e retorna imediatamente (não bloqueante).
  • tail (int, opcional) — Número máximo de linhas a retornar dos logs. Quando combinado com follow=True, começa pelas últimas N linhas e continua transmitindo novos logs. Quando follow=False, retorna apenas as últimas N linhas dos logs atualmente disponíveis.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Obtenha todos os logs de um Job de computação na infraestrutura do Hugging Face.

Exemplo:

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

Parâmetros

  • job_id (str) — ID do Job.
  • namespace (str, opcional) — O namespace onde o Job está em execução. O padrão é o namespace do usuário atual.
  • follow (bool, opcional) — Se True, transmite as métricas em tempo real até a conclusão do job (bloqueante). Se False (padrão), busca apenas as métricas atuais e retorna (não bloqueante).
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Obtenha as métricas em tempo real de um Job de computação na infraestrutura do Hugging Face.

Exemplo:

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

Parâmetros

  • repo_id (str) — ID do Space. Exemplo: "bigcode/in-the-stack".
  • build (bool, opcional, padrão False) — Se True, busca os logs de build do container (útil quando um Space está travado em BUILD_ERROR). Se False (padrão), busca os logs de execução, ou seja, o stdout/stderr da aplicação em execução.
  • follow (bool, opcional, padrão False) — Se True, transmite os logs em tempo real (bloqueante) até que o servidor feche o fluxo ou KeyboardInterrupt seja lançado. Se False (padrão), busca apenas os logs atualmente em buffer e retorna imediatamente (não bloqueante, como docker logs).
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. O padrão é o token salvo localmente, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retorna

Iterable[str]

Um gerador que produz linhas de log conforme elas ficam disponíveis.

Obtenha os logs de execução ou de compilação de um Space no Hub.

Útil para depurar um Space que está falhando ao compilar ou travando em tempo de execução, especialmente a partir de um script ou fluxo de trabalho agêntico, onde ler logs em um navegador não é uma opção.

Exemplo:

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • filename (str) — O nome do arquivo a ser verificado, por exemplo: "config.json"
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver obtendo informações do repositório de um dataset ou de um space, None ou "model" se estiver obtendo informações do repositório de um model. O padrão é None.
  • revision (str, opcional) — A revisão do repositório de onde obter as informações. O padrão é o branch "main".
  • 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.

Verifica se um arquivo existe em um repositório no Hugging Face Hub.

Exemplos:

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

Parâmetros

  • bucket_id (str) — O ID do bucket (por exemplo, "username/my-bucket").
  • remote_path (str) — O caminho do arquivo no bucket.
  • 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.

Retorna

BucketFileMetadata

O arquivo de metadados contendo informações de tamanho e xet.

Obter metadados de um arquivo em um bucket.

Exemplo:

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

Parâmetros

  • bucket_id (str) — O ID do bucket (por exemplo, "username/my-bucket").
  • paths (Iterable[str]) — Os caminhos sobre os quais obter informações. Se um caminho não existir, ele é ignorado sem lançar uma exceção. Apenas caminhos de arquivo são suportados.
  • 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.

Retorna

Iterable[BucketFile]

As informações sobre os caminhos, como um iterável de objetos BucketFile.

Obtenha informações sobre os caminhos de um bucket.

As chamadas são feitas em lotes de 1000 caminhos. Os resultados são retornados conforme são recebidos.

Exemplo:

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

Parâmetros

  • collection_slug (str) — Slug da coleção do Hub. Exemplo: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • 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.

Obtém informações sobre uma Collection no Hub.

Retorna: Collection

Exemplo:

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /. Por exemplo: "allenai/olmOCR-bench".
  • base_model_only (bool ou None, opcional) — Por padrão, o ranking inclui apenas modelos que não possuem uma relação base_model declarada (ou seja, repositórios canônicos/radical), correspondendo à visualização padrão do ranking do Hub. Repositórios de fine-tuning ou derivados que declaram um modelo pai são excluídos. Passe base_model_only=False para desativar esse filtro e incluir todos os resultados submetidos, independentemente de o modelo declarar uma relação de modelo base.
  • token (bool or str, opcional) — Um token de acesso de usuário válido. 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.
  • timeout (float, opcional) — Se deve definir um tempo limite para a solicitação ao Hub.

Retorna

list[DatasetLeaderboardEntry]

Uma lista de objetos DatasetLeaderboardEntry representando as entradas do ranking, ordenadas por posição.

Obtenha o ranking de um conjunto de dados no Hub.

O ranking classifica os modelos com base em suas pontuações de avaliação no conjunto de dados de referência fornecido. Nem todos os conjuntos de dados possuem rankings — apenas conjuntos de dados de referência com resultados de avaliação submetidos a eles. Isso oferece uma visão centrada no conjunto de dados das pontuações; para uma visão centrada no modelo, use model_info() com expand=["evalResults"].

Gera os seguintes erros:

  • RepositoryNotFoundError Se o repositório não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
  • HfHubHTTPError Se o conjunto de dados não tiver um ranking.

Exemplo:

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

< >

( )

Liste todas as tags de conjunto de dados válidas como um objeto de namespace aninhado.

get_discussion_details

< >

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • discussion_num (int) — O número da Discussion ou Pull Request. Deve ser um inteiro estritamente positivo.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.
  • 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.

Obtém os detalhes de uma Discussão / Pull Request do Hub.

Retorna: DiscussionWithDetails

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

get_full_repo_name

< >

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

Parâmetros

  • model_id (str) — O nome do modelo.
  • organization (str, opcional) — Se fornecida, o nome do repositório estará no namespace da organização em vez do namespace do usuário.
  • 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.

Retorna

str

O nome do repositório no namespace do usuário ({username}/{model_id}) se nenhuma organização for passada, e no namespace da organização ({organization}/{model_id}) caso contrário.

Retorna o nome do repositório para um ID de modelo e uma organização opcionais.

get_hf_file_metadata

< >

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

Parâmetros

  • url (str) — URL do arquivo, por exemplo, retornada por hf_hub_url().
  • 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.
  • timeout (float, opcional, padrão 10) — Quantos segundos esperar o servidor enviar metadados antes de desistir.

Obtém os metadados de um arquivo versionado no Hub para uma URL fornecida.

get_inference_endpoint

< >

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

Parâmetros

  • name (str) — O nome do Inference Endpoint sobre o qual as informações devem ser recuperadas.
  • namespace (str, opcional) — O namespace em que o Inference Endpoint está localizado. O padrão é o usuário atual.
  • 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.

Retorna

InferenceEndpoint

informações sobre o Inference Endpoint solicitado.

Obtenha informações sobre um Inference Endpoint.

Exemplo:

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

< >

( )

Liste todas as tags de modelo válidas como um objeto de namespace aninhado

get_organization_overview

< >

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

Parâmetros

  • organization (str) — Nome da organização para a qual se deseja obter uma visão geral.
  • 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.

Retorna

Organization

Um objeto Organization com a visão geral da organização.

Exceções

HTTPError

  • HTTPError — HTTP 404 Se a organização não existir no Hub.

Obtenha uma visão geral de uma organização no 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]]

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por /.
  • paths (Union[list[str], str], opcional) — Os caminhos para obter informações. Se um caminho não existir, ele é ignorado sem lançar uma exceção.
  • expand (bool, opcional, padrão False) — Se deve buscar mais informações sobre os caminhos (por exemplo, o último commit e os resultados do scan de segurança dos arquivos). Essa operação é mais cara para o servidor, portanto apenas 50 resultados são retornados por página (em vez de 1000). Como a paginação é implementada no huggingface_hub, isso é transparente para você, exceto pelo tempo que leva para obter os resultados.
  • revision (str, opcional) — A revisão do repositório de onde obter as informações. O padrão é o branch "main".
  • repo_type (str, opcional) — O tipo do repositório do qual obter as informações ("model", "dataset" ou "space". Padrão: "model".
  • 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.

Retorna

list[Union[RepoFile, RepoFolder]]

As informações sobre os caminhos, como uma lista de objetos RepoFile e RepoFolder.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError

  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou repositório inexistente.
  • RevisionNotFoundError — Se a revisão não for encontrada (erro 404) no repositório.

Obtenha informações sobre os caminhos de um repositório.

Exemplo:

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • author (str, opcional) — Passa um valor para filtrar pelo autor da discussão. None significa sem filtro. O padrão é None.
  • discussion_type (str, opcional) — Defina como "pull_request" para buscar apenas pull requests, "discussion" para buscar apenas discussões. Defina como "all" ou None para buscar ambos. O padrão é None.
  • discussion_status (str, opcional) — Defina como "open" (respectivamente "closed") para buscar apenas discussões abertas (respectivamente fechadas). Defina como "all" ou None para buscar ambas. O padrão é None.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver buscando de um dataset ou space, None ou "model" se estiver buscando de um model. O padrão é None.
  • 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.

Retorna

Iterator[Discussion]

Um iterador de objetos Discussion.

Obtém Discussões e Pull Requests para o repositório especificado.

Exemplo:

Coletando todas as discussões de um repositório em uma lista:

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

Iterando sobre as discussões de um repositório:

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

Parâmetros

  • repo_id (str) — Nome de um usuário ou organização e nome de um repositório separados por /.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se o arquivo estiver em um dataset ou space, None ou "model" se estiver em um modelo. O padrão é None.
  • revision (str, opcional) — A revisão git de onde o arquivo será obtido. Pode ser o nome de um branch, uma tag ou um hash de commit. O padrão é o topo do branch "main".
  • 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.
  • timeout (float, opcional, padrão 10) — Quantos segundos esperar o servidor enviar dados antes de desistir, passado a cada solicitação que obtém o cabeçalho de um arquivo safetensors. Defina como None para desativar o tempo limite (não recomendado, pois uma conexão travada pode suspender a chamada indefinidamente).

Retorna

SafetensorsRepoMetadata

informações relacionadas ao repositório safetensors.

Exceções

NotASafetensorsRepoError ou SafetensorsParsingError

  • NotASafetensorsRepoError — Se o repositório não for um repositório safetensors, ou seja, não possuir um arquivo model.safetensors ou um arquivo model.safetensors.index.json.
  • SafetensorsParsingError — Se o cabeçalho de um arquivo safetensors não pôde ser analisado corretamente.

Analisa os metadados de um repositório safetensors no Hub.

Primeiro, verificamos se o repositório possui um único arquivo safetensors ou se é um repositório de safetensors fragmentado. Se for um único arquivo safetensors, analisamos os metadados desse arquivo. Se for um repositório de safetensors fragmentado, analisamos os metadados do arquivo de índice e, em seguida, os metadados de cada fragmento.

Para analisar metadados de um único arquivo safetensors, use parse_safetensors_file_metadata(). Para obter todos os cabeçalhos de shards de um modelo shardado em main em uma única solicitação, use get_sharded_safetensors_metadata().

Para mais detalhes sobre o formato safetensors, consulte https://huggingface.co/docs/safetensors/index#format.

Exemplo:

# 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

Parâmetros

  • repo_id (str) — Nome de um usuário ou organização e nome de um repositório separados por /.
  • filename (str, opcional) — Caminho do arquivo de índice safetensors no repositório. O padrão é "model.safetensors.index.json".
  • 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.
  • timeout (float, opcional, padrão 10) — Quantos segundos esperar o servidor enviar dados antes de desistir. Defina como None para desabilitar o timeout (não recomendado, pois uma conexão travada pode suspender a chamada indefinidamente).

Retorna

SafetensorsRepoMetadata

os mesmos metadados de get_safetensors_metadata().

Obtenha os metadados de todos os shards de um modelo safetensors segmentado em main do Hub em uma única solicitação, em vez de get_safetensors_metadata() analisar o cabeçalho de cada shard. Somente no Hugging Face Hub.

Exemplo:

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

Parâmetros

  • repo_id (str) — ID do repositório a ser atualizado. Exemplo: "bigcode/in-the-stack".
  • 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.

Retorna

SpaceRuntime

Informações de tempo de execução sobre um Space, incluindo o estágio e o hardware do Space.

Obtém informações de tempo de execução sobre um Space.

get_space_secrets

< >

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

Parâmetros

  • repo_id (str) — ID do repositório a ser consultado. Exemplo: "bigcode/in-the-stack".
  • 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.

Retorna

dict[str, SpaceSecret]

Dicionário de objetos SpaceSecret indexados pelo nome do segredo.

Obtém todos os segredos de um Space.

Os valores secretos são somente de gravação e não podem ser lidos de volta. Somente a chave, a descrição e a hora da última atualização são retornadas.

Secrets permitem definir chaves ou tokens secretos em um Space sem codificá-los diretamente no código. Para mais detalhes, consulte https://huggingface.co/docs/hub/spaces-overview#managing-secrets.

Exemplo:

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

Parâmetros

  • repo_id (str) — ID do repositório a ser consultado. Exemplo: "bigcode/in-the-stack".
  • 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.

Obtém todas as variáveis de um Space.

Variáveis permitem definir variáveis de ambiente em um Space sem codificá-las diretamente. Para mais detalhes, consulte https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

get_user_overview

< >

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

Parâmetros

  • username (str) — Nome de usuário do usuário para o qual se deseja obter uma visão geral.
  • 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.

Retorna

User

Um objeto User com a visão geral do usuário.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Se o usuário não existir no Hub.

Obtenha uma visão geral de um usuário no Hub.

get_webhook

< >

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

Parâmetros

  • webhook_id (str) — O identificador único do webhook a ser obtido.
  • 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.

Retorna

WebhookInfo

Informações sobre o webhook.

Obtenha um webhook pelo seu id.

Exemplo:

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

Parâmetros

  • token (bool ou 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). Um token de granularidade fina deve ter a permissão “Billing > Read billing usage and payment method status” e um token OAuth deve ter o escopo read-billing.

Retorna

ZeroGpuQuota

A cota ZeroGPU do usuário autenticado.

Obtenha a cota ZeroGPU do usuário autenticado.

Útil para acompanhar o uso de ZeroGPU ao chamar Spaces ZeroGPU programaticamente (por exemplo, de um aplicativo, um agente ou um servidor MCP). Consulte https://huggingface.co/docs/hub/spaces-zerogpu para mais detalhes.

Exemplo:

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

Parâmetros

  • repo_id (str) — O id do repositório ao qual conceder acesso.
  • user (str) — O nome de usuário do usuário ao qual conceder acesso.
  • repo_type (str, opcional) — O tipo do repositório ao qual conceder acesso. Deve ser um de model, dataset ou space. Padrão é model.
  • 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.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 se o repositório não for restrito.
  • HfHubHTTPError — HTTP 400 se o usuário já tiver acesso ao repositório.
  • HfHubHTTPError — HTTP 403 se você tiver apenas acesso somente leitura ao repositório. Isso pode ocorrer se você não tiver o papel write ou admin na organização à qual o repositório pertence, ou se você tiver passado um token read.
  • HfHubHTTPError — HTTP 404 se o usuário não existir no Hub.

Conceder acesso a um usuário para um repositório restrito específico.

Conceder acesso não exige que o usuário envie uma solicitação de acesso por conta própria. O usuário é adicionado automaticamente à lista de aceitos, o que significa que ele pode baixar os arquivos. Você pode revogar o acesso concedido a qualquer momento usando cancel_access_request() ou reject_access_request().

Para mais informações sobre repositórios com acesso controlado, consulte 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

Parâmetros

  • repo_id (str) — Nome de um usuário ou organização e nome de um repositório separados por /.
  • filename (str) — O nome do arquivo no repositório.
  • subfolder (str, opcional) — Um valor opcional correspondente a uma pasta dentro do repositório.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver baixando de um dataset ou space, None ou "model" se estiver baixando de um model. O padrão é None.
  • revision (str, opcional) — Um id de revisão Git opcional, que pode ser um nome de branch, uma tag ou um hash de commit.
  • cache_dir (str, Path, opcional) — Caminho para a pasta onde os arquivos em cache são armazenados.
  • local_dir (str ou Path, opcional) — Se fornecido, o arquivo baixado será colocado neste diretório.
  • force_download (bool, opcional, padrão False) — Se o arquivo deve ser baixado mesmo que já exista no cache local.
  • etag_timeout (float, opcional, padrão 10) — Ao buscar o ETag, quantos segundos esperar o servidor enviar dados antes de desistir, valor passado para httpx2.request.
  • 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.
  • local_files_only (bool, opcional, padrão False) — Se True, evita o download do arquivo e retorna o caminho para o arquivo em cache local, se ele existir.
  • tqdm_class (tqdm, opcional) — Se fornecida, sobrescreve o comportamento padrão da barra de progresso. O argumento passado deve herdar de tqdm.auto.tqdm ou, pelo menos, imitar seu comportamento. Padrão: a barra de progresso personalizada do HF, que pode ser desativada definindo a variável de ambiente HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool, opcional, padrão False) — Se True, executa uma simulação sem efetivamente baixar o arquivo. Retorna um objeto DryRunFileInfo contendo informações sobre o que seria baixado.

Retorna

str ou DryRunFileInfo

  • Se dry_run=False: caminho local do arquivo ou, se a rede estiver desativada, a última versão do arquivo em cache no disco.
  • Se dry_run=True: um objeto DryRunFileInfo contendo informações de download.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError ou ~utils.RemoteEntryNotFoundError ou LocalEntryNotFoundError ou EnvironmentError ou OSError ou ValueError

  • RepositoryNotFoundError — Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
  • RevisionNotFoundError — Se a revisão de onde o download deve ser feito não for encontrada.
  • ~utils.RemoteEntryNotFoundError — Se o arquivo a ser baixado não puder ser encontrado.
  • LocalEntryNotFoundError — Se a rede estiver desativada ou indisponível e o arquivo não for encontrado no cache.
  • EnvironmentError — Se token=True, mas o token não puder ser encontrado.
  • OSError — Se o ETag não puder ser determinado.
  • ValueError — Se o valor de algum parâmetro for inválido.

Baixe um arquivo específico, caso ele ainda não esteja presente no cache local.

O novo layout de arquivo de cache é o seguinte:

  • O diretório de cache contém uma subpasta por repo_id (namespaced por tipo de repositório)
  • dentro de cada pasta de repositório:
    • refs é uma lista dos pares mais recentes conhecidos de revisão => commit_hash
    • blobs contém os blobs de arquivo reais (identificados pelo git-sha ou sha256, dependendo de se são arquivos LFS ou não)
    • snapshots contém uma subpasta por commit, e cada “commit” contém o subconjunto dos arquivos que foram resolvidos naquele commit específico. Cada nome de arquivo é um symlink para o blob naquele commit específico.
[  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

Se local_dir for fornecido, a estrutura de arquivos do repositório será replicada neste local. Ao usar esta opção, o cache_dir não será utilizado e uma pasta .cache/huggingface/ será criada na raiz de local_dir para armazenar alguns metadados relacionados aos arquivos baixados. Embora esse mecanismo não seja tão robusto quanto o sistema de cache principal, ele é otimizado para buscar regularmente a versão mais recente de um repositório.

ocultar_comentário_da_discussão

< >

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • discussion_num (int) — O número da Discussion ou Pull Request. Deve ser um inteiro estritamente positivo.
  • comment_id (str) — O ID do comentário a ser editado.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.
  • 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.

Retorna

DiscussionComment

o comentário oculto

Oculta um comentário em uma Discussão / Pull Request.

O conteúdo de comentários ocultos não pode mais ser recuperado. Ocultar um comentário é irreversível.

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

inspect_job

< >

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

Parâmetros

  • job_id (str) — ID do Job.
  • namespace (str, opcional) — O namespace onde o Job está em execução. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Inspecionar um Job de computação na infraestrutura do Hugging Face.

Exemplo:

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

Parâmetros

  • scheduled_job_id (str) — ID do Job agendado.
  • namespace (str, opcional) — O namespace onde o Job agendado está. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Inspecionar um Job de computação agendado na infraestrutura do Hugging Face.

Exemplo:

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por /.
  • revision (str, opcional) — A revisão do repositório do kernel de onde obter as informações.
  • timeout (float, opcional) — Se deve definir um tempo limite para a solicitação ao Hub.
  • 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.

Retorna

ModelInfo

As informações do repositório do kernel.

Obtenha informações sobre um kernel específico em huggingface.co.

list_accepted_access_requests

< >

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

Parâmetros

  • repo_id (str) — O id do repositório para o qual se deseja obter as solicitações de acesso.
  • repo_type (str, opcional) — O tipo do repositório para o qual se deseja obter solicitações de acesso. Deve ser um de model, dataset ou space. Padrão: model.
  • 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.

Retorna

Iterable[AccessRequest]

Um iterável de objetos AccessRequest. Cada item contém os atributos username, request_id, email, status e timestamp. Se o repositório com controle de acesso tiver um formulário personalizado, o atributo fields será preenchido com as respostas do usuário.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 se o repositório não for restrito.
  • HfHubHTTPError — HTTP 403 se você tiver apenas acesso somente leitura ao repositório. Isso pode ocorrer se você não tiver o papel write ou admin na organização à qual o repositório pertence, ou se você tiver passado um token read.

Obtenha as solicitações de acesso aceitas para um repositório restrito específico.

Uma solicitação aceita significa que o usuário solicitou acesso ao repositório e a solicitação foi aceita. O usuário pode baixar qualquer arquivo do repositório. Se o modo de aprovação for automático, esta lista deve conter, por padrão, todas as solicitações. Solicitações aceitas podem ser canceladas ou rejeitadas a qualquer momento usando cancel_access_request() e reject_access_request(). Uma solicitação cancelada voltará para a lista de pendentes, enquanto uma solicitação rejeitada irá para a lista de rejeitadas. Em ambos os casos, o usuário perderá o acesso ao repositório.

Para mais informações sobre repositórios com acesso controlado, consulte https://huggingface.co/docs/hub/models-gated.

Exemplo:

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

Parâmetros

  • bucket_id (str) — O ID do bucket (por exemplo, "username/my-bucket").
  • prefix (str, opcional) — Filtra os resultados para arquivos cujo caminho começa com esse prefixo.
  • recursive (bool, opcional) — Se True, lista os arquivos recursivamente. Se False (padrão), lista apenas arquivos e diretórios na raiz.
  • 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.

Retorna

Iterable[Union[BucketFile, BucketFolder]]

Um iterável de objetos BucketFile e BucketFolder contendo informações de arquivo e diretório (caminho, etc.).

Liste os arquivos em um bucket.

Exemplo:

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

Parâmetros

  • namespace (str, opcional) — Lista os buckets sob este namespace (usuário ou organização). Por padrão, lista os buckets do usuário.
  • search (str, opcional) — Uma string de busca para filtrar nomes de buckets.
  • 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.

Retorna

Iterable[BucketInfo]

Um iterável de objetos BucketInfo.

Liste os buckets no Hub sob um determinado namespace.

Exemplo:

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

Parâmetros

  • owner (list[str] ou str, opcional) — Filtre pelo nome de usuário do proprietário.
  • item (list[str] ou str, opcional) — Filtre coleções contendo um item específico. Exemplo: "models/teknium/OpenHermes-2.5-Mistral-7B", "datasets/squad" ou "papers/2311.12983".
  • sort (Literal["lastModified", "trending", "upvotes"], opcional) — Ordena coleções por data de última modificação, em alta ou por votos.
  • limit (int, opcional) — Número máximo de coleções a serem retornadas.
  • 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.

Retorna

Iterable[Collection]

um iterável de objetos Collection.

Liste coleções no Huggingface Hub, dado alguns filtros.

Ao listar coleções, a lista de itens por coleção é truncada para no máximo 4 itens. Para recuperar todos os itens de uma coleção, você deve usar 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]

Parâmetros

  • date (str, opcional) — Data no formato ISO (AAAA-MM-DD) para a qual buscar os artigos diários. Padrão: os mais recentes.
  • token (Union[bool, str, None], opcional) — Um token de acesso de usuário válido (string). O padrão é o token salvo localmente. Para desabilitar a autenticação, passe False.
  • week (str, opcional) — Semana no formato ISO (YYYY-Www) para a qual buscar os artigos diários. Exemplo, 2025-W09.
  • month (str, opcional) — Mês no formato ISO (YYYY-MM) para o qual buscar os artigos diários. Exemplo, 2025-02.
  • submitter (str, opcional) — Nome de usuário do submissor para filtrar os artigos diários.
  • sort (Literal["publishedAt", "trending"], opcional) — Ordem de classificação dos artigos diários. Pode ser por publishedAt ou por trending. Padrão é "publishedAt"
  • p (int, opcional) — Número da página para paginação. Padrão é 0.
  • limit (int, opcional) — Limite de artigos a serem obtidos. O padrão é 50.

Retorna

Iterable[PaperInfo]

um iterável de objetos huggingface_hub.hf_api.PaperInfo.

Liste os artigos diários publicados em uma data específica no Hugging Face Hub.

Exemplo:

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

Parâmetros

  • repo_id (str) — O ID do repositório do conjunto de dados (por exemplo, "username/dataset-name").
  • config (str, opcional) — Filtre por um nome específico de config/subconjunto. Quando fornecido, apenas os arquivos parquet para essa config são retornados.
  • 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.

Retorna

list[DatasetParquetEntry]

uma lista de objetos DatasetParquetEntry contendo config, split, url e size para cada arquivo parquet.

Liste os arquivos parquet disponíveis para um conjunto de dados no Hub.

Todos os conjuntos de dados hospedados no Hub são convertidos automaticamente para Parquet pelo Dataset Viewer. Este método retorna a lista de arquivos parquet com seus URLs, configs, splits e tamanhos.

Exemplo:

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

Parâmetros

  • filter (str ou Iterable[str], opcional) — Uma string ou lista de strings para filtrar conjuntos de dados no hub.
  • author (str, opcional) — Uma string que identifica o autor dos conjuntos de dados retornados.
  • benchmark (True, "official", str, opcional) — Filtra conjuntos de dados por benchmark. Pode ser True ou "official" para retornar conjuntos de dados de benchmark oficiais. Para compatibilidade futura, também pode ser uma string representando o nome do benchmark (atualmente, apenas “official” é suportado).
  • dataset_name (str, opcional) — Uma string ou lista de strings que pode ser usada para identificar conjuntos de dados no Hub pelo nome, como SQAC ou wikineural
  • gated (bool, opcional) — Um valor booleano para filtrar conjuntos de dados no Hub que são restritos ou não. Por padrão, todos os conjuntos de dados são retornados. Se gated=True for passado, apenas conjuntos de dados restritos são retornados. Se gated=False for passado, apenas conjuntos de dados não restritos são retornados.
  • language_creators (str ou List, opcional) — Uma string ou lista de strings que pode ser usada para identificar conjuntos de dados no Hub com base em como os dados foram curados, como crowdsourced ou machine_generated.
  • language (str ou List, opcional) — Uma string ou lista de strings representando um idioma de dois caracteres para filtrar conjuntos de dados no Hub.
  • multilinguality (str ou List, opcional) — Uma string ou lista de strings representando um filtro para conjuntos de dados que contêm múltiplos idiomas.
  • size_categories (str ou List, opcional) — Uma string ou lista de strings que pode ser usada para identificar conjuntos de dados no Hub pelo tamanho do conjunto de dados, como 100K<n<1M ou 1M<n<10M.
  • task_categories (str ou List, opcional) — Uma string ou lista de strings que pode ser usada para identificar conjuntos de dados no Hub pela tarefa designada, como audio_classification ou named_entity_recognition.
  • task_ids (str ou List, opcional) — Uma string ou lista de strings que pode ser usada para identificar conjuntos de dados no Hub pela tarefa específica, como speech_emotion_recognition ou paraphrase.
  • search (str, opcional) — Uma string que estará contida nos datasets retornados.
  • sort (DatasetSort_T, opcional) — A chave com a qual ordenar os conjuntos de dados resultantes. Os valores possíveis são “created_at”, “downloads”, “last_modified”, “likes” e “trending_score”.
  • limit (int, opcional) — O limite para o número de conjuntos de dados obtidos. Deixar esta opção como None obtém todos os conjuntos de dados.
  • expand (list[ExpandDatasetProperty_T], opcional) — Lista as propriedades a serem retornadas na resposta. Quando usado, apenas as propriedades da lista serão retornadas. Este parâmetro não pode ser usado se full for passado. Os valores possíveis são "author", "cardData", "citation", "createdAt", "disabled", "description", "downloads", "downloadsAllTime", "gated", "lastModified", "likes", "mainSize", "paperswithcode_id", "private", "siblings", "sha", "tags", "trendingScore", "usedStorage" e "resourceGroup".
  • full (bool, opcional) — Se deve buscar todos os dados do conjunto de dados, incluindo o last_modified, o card_data e os arquivos. Pode conter informações úteis, como o ID do PapersWithCode.
  • 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.

Retorna

Iterable[DatasetInfo]

um iterável de objetos huggingface_hub.hf_api.DatasetInfo.

Liste os conjuntos de dados hospedados no Huggingface Hub, com base em alguns filtros.

Exemplo de uso com o argumento 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")

Exemplo de uso com o argumento 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]

Parâmetros

  • accelerator (str, opcional) — Retorna apenas modelos que possuem uma receita para este acelerador ("cpu", "gpu" ou "neuron").
  • engine (str, opcional) — Retorna apenas modelos que possuem uma receita para este motor de inferência (por exemplo, "vllm", "llamacpp", "tei", "sglang").
  • license (str, opcional) — Retorna apenas modelos sob esta licença (por exemplo, "Apache 2.0").
  • task (str, opcional) — Retorna apenas modelos para esta tarefa (por exemplo, "text-generation").
  • search (str, opcional) — Retorna apenas os modelos que correspondem a esta consulta de pesquisa.
  • limit (int, opcional) — O número máximo de modelos a serem retornados.
  • token (bool ou 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).

Retorna

list[InferenceCatalogModel]

Os modelos disponíveis no catálogo, cada um com suas receitas testadas.

Liste os modelos disponíveis no Catálogo de Inferência do Hugging Face.

O objetivo do Inference Catalog é fornecer uma lista curada de modelos otimizados para inferência e para os quais as configurações padrão foram testadas. Consulte https://huggingface.co/proxy/endpoints.huggingface.co/catalog para ver a lista de modelos disponíveis no catálogo.

Use create_inference_endpoint_from_catalog() para implantar um modelo ou uma receita do catálogo.

Exemplo:

>>> 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 é experimental. Sua API está sujeita a alterações no futuro. Por favor, forneça feedback se você tiver alguma sugestão ou solicitação.

list_inference_endpoints

< >

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

Parâmetros

  • namespace (str, opcional) — O namespace para listar os endpoints. O padrão é o usuário atual. Defina como "*" para listar todos os endpoints de todos os namespaces (ou seja, o namespace pessoal e todas as organizações às quais o usuário pertence).
  • 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.

Retorna

listInferenceEndpoint

Uma lista de todos os endpoints de inferência para o namespace fornecido.

Lista todos os endpoints de inferência para o namespace fornecido.

Exemplo:

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

Parâmetros

  • namespace (str, opcional) — O namespace cujo hardware disponível e cota de aceleradores devem ser listados. O padrão é o usuário atual.
  • token (bool ou 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).

Retorna

list[InferenceEndpointHardware]

O hardware disponível em cada fornecedor e região, incluindo o hardware que está atualmente indisponível ou descontinuado.

Liste o hardware disponível para implantar um Inference Endpoint.

Cada entrada contém os valores exatos de vendor, region, accelerator, instance_type e instance_size esperados por create_inference_endpoint(), além do preço e da cota de aceleradores do namespace.

Exemplo:

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

Parâmetros

  • status (JobStage, str ou list, opcional) — Retorne apenas Jobs com o(s) status informado(s), por exemplo, "RUNNING" ou [JobStage.RUNNING, JobStage.SCHEDULING]. Veja JobStage para os valores possíveis.
  • labels (dict[str, str], opcional) — Retorne apenas Jobs que tenham todos os rótulos key=value especificados, por exemplo, {"env": "prod", "team": "ml"}.
  • timeout (float, opcional) — Se deve definir um tempo limite para a solicitação ao Hub.
  • namespace (str, opcional) — O namespace de onde ele lista os jobs. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retorna

Iterable[JobInfo]

um iterável de objetos JobInfo.

Liste Jobs de computação na infraestrutura do Hugging Face.

list_jobs_hardware

< >

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

Retorna

list[JobHardwareInfo]

Uma lista de configurações de hardware disponíveis.

Liste as opções de hardware disponíveis para Jobs na infraestrutura do Hugging Face.

Exemplo:

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

Parâmetros

  • repo_id (str) — O repositório para o qual você está listando os arquivos LFS.
  • repo_type (str, opcional) — Tipo de repositório. Defina como "dataset" ou "space" se estiver listando de um dataset ou space, None ou "model" se estiver listando de um model. O padrão é None.
  • 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.

Retorna

Iterable[LFSFileInfo]

Um iterador de objetos LFSFileInfo.

Liste todos os arquivos LFS em um repositório no Hub.

Isso é útil principalmente para contar quanto armazenamento um repositório está usando e, eventualmente, limpar arquivos grandes com permanently_delete_lfs_files(). Observe que essa seria uma ação permanente que afetará todos os commits que fazem referência a esses arquivos excluídos e que não pode ser desfeita.

Exemplo:

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

Parâmetros

  • user (str, opcional) — Nome do usuário para o qual você deseja buscar as curtidas.
  • 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.

Retorna

UserLikes

objeto contendo o nome do usuário e 3 listas de ids de repositórios (1 para modelos, 1 para conjuntos de dados e 1 para Spaces).

Exceções

ValueError

  • ValueError — Se user não for passado e nenhum token for encontrado (seja pelo argumento ou pela máquina).

Liste todos os repositórios públicos curtidos por um usuário no huggingface.co.

Esta lista é pública, portanto o token é opcional. Se user não for passado, o padrão é o usuário conectado.

Veja também unlike().

Exemplo:

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

Parâmetros

  • filter (str ou Iterable[str], opcional) — Uma string ou lista de strings para filtrar modelos no Hub. Os modelos podem ser filtrados por biblioteca, idioma, tarefa, tags e mais.
  • author (str, opcional) — Uma string que identifica o autor (usuário ou organização) dos modelos retornados.
  • apps (str ou List, opcional) — Uma string ou lista de strings para filtrar modelos no Hub que suportam os aplicativos especificados. Exemplos de valores incluem "ollama" ou ["ollama", "vllm"].
  • gated (bool, opcional) — Um valor booleano para filtrar modelos no Hub que são ou não restritos. Por padrão, todos os modelos são retornados. Se gated=True for passado, apenas modelos restritos são retornados. Se gated=False for passado, apenas modelos não restritos são retornados.
  • inference (Literal["warm"], opcional) — Se “warm”, filtra modelos no Hub atualmente servidos por pelo menos um provedor.
  • inference_provider (Literal["all"] ou str, opcional) — Uma string para filtrar modelos no Hub que são servidos por um provedor específico. Passe "all" para obter todos os modelos servidos por pelo menos um provedor.
  • trained_dataset (str ou List, opcional) — Uma tag de string ou uma lista de tags de string do conjunto de dados treinado para um modelo no Hub.
  • search (str, opcional) — Uma string que estará contida nos ids de modelo retornados.
  • pipeline_tag (str, opcional) — Uma string de tag de pipeline para filtrar modelos no Hub, como summarization.
  • num_parameters (str, opcional) — Filtre modelos pela contagem de parâmetros. Aceita a mesma sintaxe de intervalo que a interface e a API do Hub, por exemplo "min:6B,max:128B", "min:6B" ou "max:128B".
  • emissions_thresholds (Tuple, opcional) — Uma tupla de dois ints ou floats representando uma pegada de carbono mínima e máxima para filtrar os modelos resultantes, em gramas.
  • sort (ModelSort_T, opcional) — A chave com a qual ordenar os modelos resultantes. Os valores possíveis são “created_at”, “downloads”, “last_modified”, “likes” e “trending_score”.
  • limit (int, opcional) — O limite para o número de modelos recuperados. Deixar esta opção como None recupera todos os modelos.
  • expand (list[ExpandModelProperty_T], opcional) — Lista as propriedades a serem retornadas na resposta. Quando usado, apenas as propriedades da lista serão retornadas. Este parâmetro não pode ser usado se full, cardData ou fetch_config forem passados. Os valores possíveis são "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" e "resourceGroup".
  • full (bool, opcional) — Se deve buscar todos os dados do modelo, incluindo o last_modified, o sha, os arquivos e as tags. Isso é definido como True por padrão ao usar um filtro.
  • cardData (bool, opcional) — Se deve obter também os metadados do modelo. Pode conter informações úteis, como emissões de carbono, métricas e conjuntos de dados usados no treinamento.
  • fetch_config (bool, opcional) — Se deve buscar também as configurações do modelo. Isso não está incluído em full devido ao seu tamanho.
  • 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.

Retorna

Iterable[ModelInfo]

um iterável de objetos huggingface_hub.hf_api.ModelInfo.

Liste os modelos hospedados no Huggingface Hub, com base em alguns filtros.

Exemplo:

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

Parâmetros

  • organization (str) — Nome da organização para a qual se deseja obter os seguidores.
  • 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.

Retorna

Iterable[User]

Uma lista de objetos User com os seguidores da organização.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Se a organização não existir no Hub.

Liste os seguidores de uma organização no Hub.

list_organization_members

< >

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

Parâmetros

  • organization (str) — Nome da organização para a qual se deseja obter os membros.
  • 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.

Retorna

Iterable[User]

Uma lista de objetos User com os membros da organização.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Se a organização não existir no Hub.

Lista de membros de uma organização no Hub.

list_papers

< >

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

Parâmetros

  • query (str, opcional) — Uma string de consulta de pesquisa para encontrar artigos. Se fornecida, retorna artigos que correspondem à consulta.
  • limit (int, opcional) — O número máximo de artigos a serem retornados.
  • token (Union[bool, str, None], 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.

Retorna

Iterable[PaperInfo]

um iterável de objetos huggingface_hub.hf_api.PaperInfo.

Liste os artigos diários no Hugging Face Hub com base em uma consulta de pesquisa.

Exemplo:

>>> from huggingface_hub import HfApi

>>> api = HfApi()

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

list_pending_access_requests

< >

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

Parâmetros

  • repo_id (str) — O id do repositório para o qual se deseja obter as solicitações de acesso.
  • repo_type (str, opcional) — O tipo do repositório para o qual se deseja obter solicitações de acesso. Deve ser um de model, dataset ou space. Padrão: model.
  • 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.

Retorna

Iterable[AccessRequest]

Um iterável de objetos AccessRequest. Cada item contém os atributos username, request_id, email, status e timestamp. Se o repositório com controle de acesso tiver um formulário personalizado, o atributo fields será preenchido com as respostas do usuário.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 se o repositório não for restrito.
  • HfHubHTTPError — HTTP 403 se você tiver apenas acesso somente leitura ao repositório. Isso pode ocorrer se você não tiver o papel write ou admin na organização à qual o repositório pertence, ou se você tiver passado um token read.

Obtenha as solicitações de acesso pendentes para um repositório restrito específico.

Uma solicitação pendente significa que o usuário solicitou acesso ao repositório, mas a solicitação ainda não foi processada. Se o modo de aprovação for automático, esta lista deve estar vazia. Solicitações pendentes podem ser aceitas ou rejeitadas usando accept_access_request() e reject_access_request().

Para mais informações sobre repositórios com acesso controlado, consulte https://huggingface.co/docs/hub/models-gated.

Exemplo:

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

Parâmetros

  • repo_id (str) — O id do repositório para o qual se deseja obter as solicitações de acesso.
  • repo_type (str, opcional) — O tipo do repositório para o qual se deseja obter solicitações de acesso. Deve ser um de model, dataset ou space. Padrão: model.
  • 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.

Retorna

Iterable[AccessRequest]

Um iterável de objetos AccessRequest. Cada item contém os atributos username, request_id, email, status e timestamp. Se o repositório com controle de acesso tiver um formulário personalizado, o atributo fields será preenchido com as respostas do usuário.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 se o repositório não for restrito.
  • HfHubHTTPError — HTTP 403 se você tiver apenas acesso somente leitura ao repositório. Isso pode ocorrer se você não tiver o papel write ou admin na organização à qual o repositório pertence, ou se você tiver passado um token read.

Obtenha as solicitações de acesso rejeitadas para um repositório restrito específico.

Uma solicitação rejeitada significa que o usuário solicitou acesso ao repositório e a solicitação foi explicitamente rejeitada por um proprietário do repositório (seja você ou outro usuário da sua organização). O usuário não pode baixar nenhum arquivo do repositório. Solicitações rejeitadas podem ser aceitas ou canceladas a qualquer momento usando accept_access_request() e cancel_access_request(). Uma solicitação cancelada voltará para a lista pendente, enquanto uma solicitação aceita irá para a lista de aceitas.

Para mais informações sobre repositórios com acesso controlado, consulte https://huggingface.co/docs/hub/models-gated.

Exemplo:

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por /.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver listando commits de um dataset ou de um Space, None ou "model" se estiver listando de um modelo. O padrão é None.
  • 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.
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo do ramo "main".
  • formatted (bool) — Se deve retornar o título e a descrição dos commits formatados em HTML. O padrão é False.

Retorna

list[GitCommitInfo]

lista de objetos contendo informações sobre os commits de um repositório no Hub.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError

  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou repositório inexistente.
  • RevisionNotFoundError — Se a revisão não for encontrada (erro 404) no repositório.

Obtém a lista de commits de uma revisão específica para um repositório no Hub.

Os commits são ordenados por data (o commit mais recente primeiro).

Exemplo:

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por /.
  • revision (str, opcional) — A revisão do repositório de onde obter as informações.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.
  • 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.

Retorna

list[str]

a lista de arquivos em um repositório específico.

Obtenha a lista de arquivos em um repositório específico.

list_repo_likers

< >

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

Parâmetros

  • repo_id (str) — O repositório a ser recuperado. Exemplo: "user/my-cool-model".
  • 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.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.

Retorna

Iterable[User]

um iterável de objetos huggingface_hub.hf_api.User.

Liste todos os usuários que curtiram um repositório específico no hugging Face Hub.

Veja também list_liked_repos().

list_repo_refs

< >

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • repo_type (str, opcional) — Defina como "dataset", "space" ou "kernel" se estiver listando refs de um dataset, um Space ou um Kernel, None ou "model" se estiver listando de um modelo. O padrão é None.
  • include_pull_requests (bool, opcional) — Se deve incluir refs de pull requests na lista. O padrão é False.
  • 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.

Retorna

GitRefs

objeto contendo todas as informações sobre ramos e tags para um repositório no Hub.

Obtenha a lista de refs de um repositório específico (tanto tags quanto branches).

Exemplo:

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por /.
  • path_in_repo (str, opcional) — Caminho relativo da árvore (pasta) no repositório, por exemplo: "checkpoints/1fec34a/results". O padrão é a árvore (pasta) raiz do repositório.
  • recursive (bool, opcional, padrão False) — Se deve listar os arquivos e pastas da árvore recursivamente.
  • expand (bool, opcional, padrão False) — Se deve buscar mais informações sobre os arquivos e pastas da árvore (por exemplo, o último commit e os resultados do scan de segurança dos arquivos). Essa operação é mais cara para o servidor, portanto apenas 50 resultados são retornados por página (em vez de 1000). Como a paginação é implementada no huggingface_hub, isso é transparente para você, exceto pelo tempo que leva para obter os resultados.
  • revision (str, opcional) — A revisão do repositório de onde obter a árvore. O padrão é o branch "main".
  • repo_type (str, opcional) — O tipo do repositório do qual obter a árvore ("model", "dataset", "space" ou "kernel"). Padrão: "model".
  • 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.

Retorna

Iterable[Union[RepoFile, RepoFolder]]

As informações sobre os arquivos e pastas da árvore, como um iterável de objetos RepoFile e RepoFolder. A ordem dos arquivos e pastas não é garantida.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError ou ~utils.RemoteEntryNotFoundError

  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou repositório inexistente.
  • RevisionNotFoundError — Se a revisão não for encontrada (erro 404) no repositório.
  • ~utils.RemoteEntryNotFoundError — Se a árvore (pasta) não existir (erro 404) no repositório.

Liste os arquivos e pastas de uma árvore de repositório e obtenha informações sobre eles.

Exemplos:

Obtenha informações sobre a árvore de um repositório.

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

Obtenha ainda mais informações sobre a árvore de um repositório (último commit e resultados do scan de segurança dos arquivos)

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

Parâmetros

  • labels (dict[str, str], opcional) — Retorne apenas Jobs agendados que possuam todos os rótulos key=value especificados, por exemplo, {"env": "prod", "team": "ml"}.
  • timeout (float, opcional) — Se deve definir um tempo limite para a solicitação ao Hub.
  • namespace (str, opcional) — O namespace de onde ele lista os jobs. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retorna

list[ScheduledJobInfo]

uma lista de objetos ScheduledJobInfo.

Liste os Jobs de computação agendados na infraestrutura do Hugging Face.

list_space_templates

< >

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

Parâmetros

Retorna

list[SpaceTemplate]

A lista de modelos de Space disponíveis.

Liste os modelos de Space oficiais disponíveis no Hub.

O repo_id de um modelo retornado (ou seu name curto) pode ser passado como space_template para HfApi.create_repo() para criar um novo Space a partir desse modelo.

Exemplo:

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

Parâmetros

  • filter (str ou Iterable, opcional) — Uma tag de string ou uma lista de tags que pode ser usada para identificar Spaces no Hub.
  • author (str, opcional) — Uma string que identifica o autor dos Spaces retornados.
  • search (str, opcional) — Uma string que estará contida nos Spaces retornados.
  • datasets (str ou Iterable, opcional) — Se deve retornar Spaces que fazem uso de um dataset. O nome de um dataset específico pode ser passado como uma string.
  • models (str ou Iterable, opcional) — Se deve retornar Spaces que fazem uso de um modelo. O nome de um modelo específico pode ser passado como uma string.
  • linked (bool, opcional) — Se deve retornar Spaces que fazem uso de um modelo ou de um dataset.
  • sort (SpaceSort_T, opcional) — A chave pela qual ordenar os espaços resultantes. Os valores possíveis são “created_at”, “last_modified”, “likes” e “trending_score”.
  • limit (int, opcional) — O limite para o número de Spaces obtidos. Deixar esta opção como None obtém todos os Spaces.
  • expand (list[ExpandSpaceProperty_T], opcional) — Lista de propriedades a serem retornadas na resposta. Quando usado, apenas as propriedades da lista serão retornadas. Este parâmetro não pode ser usado se full for passado. Os valores possíveis são "author", "cardData", "datasets", "disabled", "lastModified", "createdAt", "likes", "models", "private", "region", "runtime", "sdk", "siblings", "sha", "subdomain", "tags", "trendingScore", "usedStorage" e "resourceGroup".
  • full (bool, opcional) — Se deve buscar todos os dados dos Spaces, incluindo os campos last_modified, siblings e card_data.
  • 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.

Retorna

Iterable[SpaceInfo]

um iterável de objetos huggingface_hub.hf_api.SpaceInfo.

Liste os espaços hospedados no Huggingface Hub, com base em alguns filtros.

list_spaces_hardware

< >

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

Retorna

list[JobHardwareInfo]

Uma lista de configurações de hardware disponíveis.

Liste as opções de hardware disponíveis para Spaces.

Exemplo:

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

Parâmetros

  • username (str) — Nome de usuário do usuário do qual se deseja obter os seguidores.
  • 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.

Retorna

Iterable[User]

Uma lista de objetos User com os seguidores do usuário.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Se o usuário não existir no Hub.

Obtenha a lista de seguidores de um usuário no Hub.

list_user_following

< >

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

Parâmetros

  • username (str) — Nome de usuário do usuário do qual se deseja obter os usuários seguidos.
  • 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.

Retorna

Iterable[User]

Uma lista de objetos User com os usuários seguidos pelo usuário.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Se o usuário não existir no Hub.

Obtenha a lista de usuários seguidos por um usuário no Hub.

list_user_repos

< >

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

Parâmetros

  • namespace (str, opcional) — Nome da organização. Se não for fornecido, lista os repositórios do usuário autenticado.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. O padrão é o token salvo localmente.

Retorna

Iterable[RepoStorageInfo]

Um iterável de objetos RepoStorageInfo.

Liste todos os repositórios (modelos, conjuntos de dados, espaços, buckets) de um usuário ou organização com informações de armazenamento.

Usa o endpoint /api/settings/repositories para o usuário autenticado ou /api/organizations/{namespace}/settings/repositories para uma organização.

Exemplo:

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

Parâmetros

Retorna

list[WebhookInfo]

Lista de objetos de informações de webhook.

Liste todos os webhooks configurados.

Exemplo:

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • discussion_num (int) — O número da Discussion ou Pull Request. Deve ser um inteiro estritamente positivo.
  • comment (str, opcional) — Um comentário opcional para publicar junto com a alteração de status.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.
  • 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.

Retorna

DiscussionStatusChange

o evento de mudança de status

Mescla uma Pull Request.

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • revision (str, opcional) — A revisão do repositório do modelo de onde obter as informações.
  • timeout (float, opcional) — Se deve definir um tempo limite para a solicitação ao Hub.
  • securityStatus (bool, opcional) — Se deve recuperar o status de segurança do repositório do modelo. O status de segurança será retornado no campo security_repo_status.
  • files_metadata (bool, opcional) — Se deve ou não recuperar metadados dos arquivos no repositório (tamanho, metadados do LFS, etc). O padrão é False.
  • expand (list[ExpandModelProperty_T], opcional) — Lista as propriedades a serem retornadas na resposta. Quando usado, apenas as propriedades da lista serão retornadas. Este parâmetro não pode ser usado se securityStatus ou files_metadata forem passados. Os valores possíveis são "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" e "resourceGroup".
  • 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.

Retorna

huggingface_hub.hf_api.ModelInfo

As informações do repositório do modelo.

Obter informações sobre um modelo específico no huggingface.co

O modelo pode ser privado se você passar um token aceitável ou estiver conectado.

Gera os seguintes erros:

  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
  • RevisionNotFoundError Se a revisão de onde o download deve ser feito não for encontrada.

move_bucket

< >

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

Parâmetros

  • from_id (str) — Um namespace (usuário ou organização) e um nome de bucket separados por /. Identificador original do bucket (ex.: "username/my-bucket").
  • to_id (str) — Um namespace (usuário ou organização) e um nome de bucket separados por /. Identificador final do bucket (por exemplo, "username/new-bucket-name" ou "organization/my-bucket").
  • 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.

Exceções

BucketNotFoundError

  • BucketNotFoundError — Se o bucket de origem não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

Mova um bucket de “namespace1/repo_name1” para “namespace2/repo_name2”

Observe que existem certas limitações. Para mais informações sobre mover repositórios, consulte https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo.

Exemplo:

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

Parâmetros

  • from_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por /. Identificador do repositório original.
  • to_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por /. Identificador final do repositório.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.
  • 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.

Movendo um repositório de namespace1/repo_name1 para namespace2/repo_name2

Observe que existem certas limitações. Para mais informações sobre mover repositórios, consulte https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo.

Gera os seguintes erros:

  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

paper_info

< >

( id: str ) → PaperInfo

Parâmetros

  • id (str, opcional) — id do ArXiv do artigo.

Retorna

PaperInfo

Um objeto PaperInfo.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Se o paper não existir no Hub.

Obtenha informações sobre um paper no Hub.

parse_safetensors_file_metadata

< >

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

Parâmetros

  • repo_id (str) — Nome de um usuário ou organização e nome de um repositório separados por /.
  • filename (str) — O nome do arquivo no repositório.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se o arquivo estiver em um dataset ou space, None ou "model" se estiver em um modelo. O padrão é None.
  • revision (str, opcional) — A revisão git de onde o arquivo será obtido. Pode ser o nome de um branch, uma tag ou um hash de commit. O padrão é o topo do branch "main".
  • 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.
  • timeout (float, opcional, padrão 10) — Quantos segundos esperar o servidor enviar dados antes de desistir. Defina como None para desabilitar o timeout (não recomendado, pois uma conexão travada pode suspender a chamada indefinidamente).

Retorna

SafetensorsFileMetadata

informações relacionadas a um arquivo safetensors.

Exceções

NotASafetensorsRepoError ou SafetensorsParsingError

  • NotASafetensorsRepoError — Se o repositório não for um repositório safetensors, ou seja, não possuir um arquivo model.safetensors ou um arquivo model.safetensors.index.json.
  • SafetensorsParsingError — Se o cabeçalho de um arquivo safetensors não pôde ser analisado corretamente.

Analise metadados de um arquivo safetensors no Hub.

Para analisar os metadados de todos os arquivos safetensors em um repositório de uma só vez, use get_safetensors_metadata().

Para mais detalhes sobre o formato safetensors, consulte https://huggingface.co/docs/safetensors/index#format.

pause_inference_endpoint

< >

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

Parâmetros

  • name (str) — O nome do Inference Endpoint a ser pausado.
  • namespace (str, opcional) — O namespace em que o Inference Endpoint está localizado. O padrão é o usuário atual.
  • 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.

Retorna

InferenceEndpoint

informações sobre o Inference Endpoint pausado.

Pausar um Inference Endpoint.

Um Inference Endpoint pausado não será cobrado. Ele pode ser retomado a qualquer momento usando resume_inference_endpoint(). Isso é diferente de escalar o Inference Endpoint para zero com scale_to_zero_inference_endpoint(), o que resultaria em sua reinicialização automática quando uma solicitação fosse feita a ele.

Para sua conveniência, você também pode pausar um Inference Endpoint usando pause_inference_endpoint().

pause_space

< >

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

Parâmetros

  • repo_id (str) — ID do Space a ser pausado. Exemplo: "Salesforce/BLIP2".
  • 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.

Retorna

SpaceRuntime

Informações de tempo de execução do seu Space, incluindo stage=PAUSED e o hardware solicitado.

Exceções

RepositoryNotFoundError ou HfHubHTTPError ou BadRequestError

  • RepositoryNotFoundError — Se o seu Space não for encontrado (erro 404). Provavelmente o repo_id está incorreto ou o seu space é privado, mas você não está autenticado.
  • HfHubHTTPError — 403 Forbidden: apenas o proprietário de um Space pode pausá-lo. Se você deseja gerenciar um Space que não é seu, peça ao proprietário abrindo uma Discussion ou duplique o Space.
  • BadRequestError — Se o seu Space for um Space estático. Spaces estáticos estão sempre em execução e nunca são cobrados. Se você deseja ocultar um Space estático, pode configurá-lo como privado.

Pausar seu Space.

Um Space pausado para de executar até ser reiniciado manualmente por seu proprietário. Isso é diferente do estado de suspensão, para o qual os Spaces gratuitos entram após 48h de inatividade. O tempo pausado não é cobrado na sua conta, independentemente do hardware selecionado. Para reiniciar seu Space, use restart_space() e acesse a página de configurações do seu Space.

Para mais detalhes, visite a documentação.

permanently_delete_lfs_files

< >

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

Parâmetros

  • repo_id (str) — O repositório para o qual você está listando os arquivos LFS.
  • lfs_files (Iterable[LFSFileInfo]) — Um iterável de itens LFSFileInfo para serem excluídos permanentemente do repositório. Use list_lfs_files() para listar todos os arquivos LFS de um repositório.
  • rewrite_history (bool, opcional, padrão True) — Se deve reescrever o histórico do repositório para remover ponteiros de arquivo que referenciam os arquivos LFS excluídos (recomendado).
  • repo_type (str, opcional) — Tipo de repositório. Defina como "dataset" ou "space" se estiver listando de um dataset ou space, None ou "model" se estiver listando de um model. O padrão é None.
  • 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.

Excluir permanentemente arquivos LFS de um repositório no Hub.

Esta é uma ação permanente que afetará todos os commits que referenciam os arquivos excluídos e pode corromper seu repositório. Esta é uma operação irreversível. Use-a apenas se você souber o que está fazendo.

Exemplo:

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

Parâmetros

  • repo_id (str) — O repositório no qual você vai commitar os arquivos, por exemplo: "username/custom_transformers".
  • additions (Iterable de CommitOperationAdd) — A lista de arquivos para enviar. Aviso: os objetos nesta lista serão alterados para incluir informações relativas ao envio. Não reutilize os mesmos objetos para múltiplos commits.
  • 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.
  • repo_type (str, opcional) — O tipo de repositório para o qual o upload será feito (por exemplo, "model" -padrão-, "dataset", "space" ou "kernel").
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo do ramo "main".
  • create_pr (boolean, opcional) — Se você planeja ou não criar um Pull Request com esse commit. O padrão é False.
  • num_threads (int, opcional) — Número de threads concorrentes para upload de arquivos. O padrão é 5. Definir como 2 significa que no máximo 2 arquivos serão enviados simultaneamente.
  • free_memory (bool, opcional, padrão True) — Se True, o atributo path_or_fileobj de cada CommitOperationAdd é substituído por um objeto bytes vazio após o upload para economizar memória. Defina como False se você precisar reutilizar os objetos de operação fora de uma chamada subsequente de create_commit().
  • gitignore_content (str, opcional) — O conteúdo do arquivo .gitignore para saber quais arquivos devem ser ignorados. A ordem de prioridade é verificar primeiro se gitignore_content foi passado, em seguida verificar se o arquivo .gitignore está presente na lista de arquivos a serem commitados e, por fim, usar o arquivo .gitignore já hospedado no Hub (se houver).

Envie arquivos LFS para o S3 antes do upload em preparação para um commit futuro.

Este método é útil se você estiver gerando os arquivos para upload em tempo real e não quiser armazená-los em memória antes de enviá-los todos de uma vez.

Este é um método para usuários avançados. Você não deve precisar chamá-lo diretamente para fazer um commit normal. Use create_commit() diretamente em vez disso.

As operações de commit serão alteradas durante o processo. Em particular, o path_or_fileobj anexado será removido após o upload para economizar memória (e substituído por um objeto bytes vazio). Não reutilize os mesmos objetos, exceto para passá-los a create_commit(). Se você não deseja remover o conteúdo anexado do objeto de operação de commit, passe free_memory=False.

Exemplo:

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

Parâmetros

  • id (str) — id do ArXiv do artigo.

Retorna

str

O conteúdo da página do artigo em markdown.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 404 Se o paper não existir no Hub.

Obtenha o conteúdo em Markdown de uma página de artigo no 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 )

Parâmetros

  • repo_id (str) — O id do repositório para o qual a solicitação de acesso será rejeitada.
  • user (str, opcional) — O nome de usuário do usuário cuja solicitação de acesso deve ser rejeitada. Exatamente um de user ou request_id deve ser fornecido.
  • request_id (str, opcional) — O id da solicitação de acesso a ser rejeitada (veja AccessRequest). Obrigatório quando o repositório está configurado para não compartilhar os nomes de usuário dos solicitantes. Exatamente um de user ou request_id deve ser fornecido.
  • repo_type (str, opcional) — O tipo do repositório para o qual a solicitação de acesso será rejeitada. Deve ser um de model, dataset ou space. Padrão: model.
  • rejection_reason (str, opcional) — Motivo opcional de rejeição que será visível para o usuário (máx. 200 caracteres).
  • 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.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 400 se o repositório não for restrito.
  • HfHubHTTPError — HTTP 403 se você tiver apenas acesso somente leitura ao repositório. Isso pode ocorrer se você não tiver o papel write ou admin na organização à qual o repositório pertence, ou se você tiver passado um token read.
  • HfHubHTTPError — HTTP 404 se o usuário não existir no Hub.
  • HfHubHTTPError — HTTP 404 se a solicitação de acesso do usuário não puder ser encontrada.
  • HfHubHTTPError — HTTP 404 se a solicitação de acesso do usuário já estiver na lista de rejeitados.

Rejeitar uma solicitação de acesso de um usuário para um repositório restrito específico.

Uma solicitação rejeitada será movida para a lista de rejeitadas. O usuário não poderá baixar nenhum arquivo do repositório. Solicitações rejeitadas podem ser aceitas ou canceladas a qualquer momento usando accept_access_request() e cancel_access_request(). Uma solicitação cancelada voltará para a lista de pendentes, enquanto uma solicitação aceita será movida para a lista de aceitas.

Para mais informações sobre repositórios com acesso controlado, consulte 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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • discussion_num (int) — O número da Discussion ou Pull Request. Deve ser um inteiro estritamente positivo.
  • new_title (str) — O novo título para a discussão
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver fazendo upload para um dataset ou space, None ou "model" se estiver fazendo upload para um model. O padrão é None.
  • 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.

Retorna

DiscussionTitleChange

o evento de alteração de título

Renomeia uma Discussão.

Exemplos:

>>> 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', ...)

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

repo_exists

< >

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver obtendo informações do repositório de um dataset ou de um space, None ou "model" se estiver obtendo informações do repositório de um model. O padrão é None.
  • 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.

Verifica se um repositório existe no Hugging Face Hub.

Exemplos:

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • revision (str, opcional) — A revisão do repositório de onde obter as informações.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver obtendo informações do repositório de um dataset ou de um space, None ou "model" se estiver obtendo informações do repositório de um model. O padrão é None.
  • timeout (float, opcional) — Se deve definir um tempo limite para a solicitação ao Hub.
  • expand (ExpandModelProperty_T ou ExpandDatasetProperty_T ou ExpandSpaceProperty_T, opcional) — Lista de propriedades a serem retornadas na resposta. Quando utilizado, apenas as propriedades da lista serão retornadas. Este parâmetro não pode ser usado se files_metadata for passado. Para uma lista exaustiva das propriedades disponíveis, consulte model_info(), dataset_info() ou space_info().
  • files_metadata (bool, opcional) — Se deve ou não recuperar metadados dos arquivos no repositório (tamanho, metadados do LFS, etc). O padrão é False.
  • 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.

Retorna

Union[SpaceInfo, DatasetInfo, ModelInfo]

As informações do repositório, como um objeto huggingface_hub.hf_api.DatasetInfo, huggingface_hub.hf_api.ModelInfo ou huggingface_hub.hf_api.SpaceInfo.

Obtenha o objeto de informações para um repositório de um determinado tipo.

Gera os seguintes erros:

  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
  • RevisionNotFoundError Se a revisão de onde o download deve ser feito não for encontrada.

request_space_hardware

< >

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

Parâmetros

  • repo_id (str) — ID do repositório a ser atualizado. Exemplo: "bigcode/in-the-stack".
  • hardware (str ou SpaceHardware) — Hardware no qual executar o Space. Exemplo: "t4-medium".
  • 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.
  • sleep_time (int, opcional) — Número de segundos de inatividade a aguardar antes de um Space ser colocado em modo de suspensão. Defina como -1 se você não quiser que seu Space entre em suspensão (comportamento padrão para hardware atualizado). Para hardware gratuito, você não pode configurar o tempo de suspensão (o valor é fixado em 48 horas de inatividade). Veja https://huggingface.co/docs/hub/spaces-gpus#sleep-time para mais detalhes.

Retorna

SpaceRuntime

Informações de tempo de execução sobre um Space, incluindo o estágio e o hardware do Space.

Solicitar novo hardware para um Space.

Também é possível solicitar hardware diretamente ao criar o repositório do Space! Consulte create_repo() para mais detalhes.

rerun_job

< >

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

Parâmetros

  • job_id (str) — ID do Job a ser reexecutado.
  • namespace (str, opcional) — Namespace do Job. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Token de acesso do usuário. O padrão é o token salvo localmente.

Retorna

JobInfo

O Job recém-iniciado.

Execute um novo Job usando a especificação do Job existente, incluindo suas configurações de repetição e recursos.

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

Parâmetros

  • repo_id (str) — Nome de um usuário ou organização e nome de um repositório separados por /.
  • repo_type (str, opcional) — Defina como "dataset", "space" ou "kernel" se o repositório for um repositório de dataset, space ou kernel, None ou "model" se for um modelo. O padrão é None.
  • revision (str, opcional) — A revisão a ser resolvida. Pode ser um nome de branch, uma tag, uma ref de PR ou um hash de commit. O padrão é a branch padrão. Se um ResolvedRevision for passado, ele é retornado como está - a menos que tenha sido resolvido contra outro repositório, caso em que a revisão inicialmente solicitada é resolvida novamente.
  • cache_dir (str, Path, opcional) — Caminho para a pasta onde os arquivos em cache são armazenados. O padrão é o valor de HF_HUB_CACHE.
  • local_files_only (bool, opcional, padrão False) — Se True, resolve a revisão apenas do cache local, sem contatar o Hub.
  • 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.

Retorna

ResolvedRevision

Uma subclasse de str que armazena tanto a revisão solicitada quanto o hash do commit para o qual ela é resolvida.

Exceções

RevisionResolutionError ou RevisionNotFoundError ou RepositoryNotFoundError

  • RevisionResolutionError — Se a revisão não puder ser resolvida: o Hub não pôde ser acessado e nada está em cache localmente.
  • RevisionNotFoundError — Se a revisão não existir no Hub.
  • RepositoryNotFoundError — Se o repositório não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

Resolve uma revisão (branch, tag, PR ref) para um hash de commit.

Isso é destinado a bibliotecas que baixam e carregam vários componentes de um repositório separadamente (config, pesos, tokenizer, ...). Resolver a revisão uma vez e passar o ResolvedRevision retornado garante que todas as chamadas subsequentes visem exatamente o mesmo commit, mesmo que o repositório seja atualizado no meio. Isso também economiza chamadas HTTP, pois downloads feitos com um hash de commit podem ser servidos do cache local sem contatar o Hub.

O mapeamento de revision -> commit hash é armazenado em cache no disco (na pasta refs/ do cache), com base em melhor esforço. Se o Hub não puder ser acessado posteriormente (modo offline, erro de conexão, tempo limite, indisponibilidade do Hub, …), o valor em cache é usado como alternativa.

Se você precisa apenas baixar um snapshot completo do repositório, uma única chamada de snapshot_download() é suficiente e já faz o que é necessário. resolve_revision é útil apenas ao baixar arquivos separadamente.

Exemplo:

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

Parâmetros

  • repo_id (str) — ID do Space a ser reiniciado. Exemplo: "Salesforce/BLIP2".
  • 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.
  • factory_reboot (bool, opcional) — Se True, o Space será reconstruído do zero, sem armazenar em cache nenhum requisito.

Retorna

SpaceRuntime

Informações de tempo de execução sobre seu Space.

Exceções

RepositoryNotFoundError ou HfHubHTTPError ou BadRequestError

  • RepositoryNotFoundError — Se o seu Space não for encontrado (erro 404). Provavelmente o repo_id está incorreto ou o seu space é privado, mas você não está autenticado.
  • HfHubHTTPError — 403 Forbidden: apenas o proprietário de um Space pode reiniciá-lo. Se você deseja reiniciar um Space que não é seu, peça ao proprietário abrindo uma Discussion ou duplique o Space.
  • BadRequestError — Se o seu Space for um Space estático. Spaces estáticos estão sempre em execução e nunca são cobrados. Se você deseja ocultar um Space estático, pode configurá-lo como privado.

Reinicie seu Space.

Esta é a única maneira de reiniciar um Space programaticamente se você o colocou em Pausa (veja pause_space()). Você deve ser o proprietário do Space para reiniciá-lo. Se você estiver usando hardware atualizado, sua conta será cobrada assim que o Space for reiniciado. Você pode acionar um reinício independentemente do estado atual do Space.

Para mais detalhes, visite a documentação.

resume_inference_endpoint

< >

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

Parâmetros

  • name (str) — O nome do Inference Endpoint a ser retomado.
  • namespace (str, opcional) — O namespace em que o Inference Endpoint está localizado. O padrão é o usuário atual.
  • running_ok (bool, opcional) — Se True, o método não lançará um erro se o Inference Endpoint já estiver em execução. O valor padrão é True.
  • 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.

Retorna

InferenceEndpoint

informações sobre o Inference Endpoint retomado.

Retomar um Inference Endpoint.

Para sua conveniência, você também pode retomar um Inference Endpoint usando InferenceEndpoint.resume().

resume_scheduled_job

< >

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

Parâmetros

  • scheduled_job_id (str) — ID do Job agendado.
  • namespace (str, opcional) — O namespace onde o Job agendado está. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retomar (despausar) um Job de computação agendado na infraestrutura do Hugging Face.

revision_exists

< >

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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • revision (str) — A revisão do repositório a ser verificada.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver obtendo informações do repositório de um dataset ou de um space, None ou "model" se estiver obtendo informações do repositório de um model. O padrão é None.
  • 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.

Verifica se uma revisão específica existe em um repositório no Hugging Face Hub.

Exemplos:

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

Parâmetros

  • fn (Callable) — O método a ser executado em segundo plano.
  • *args, **kwargs — Argumentos com os quais o método será chamado.

Retorna

Future

uma instância de Future para obter o resultado da tarefa.

Execute um método em segundo plano e retorne uma instância de Future.

O objetivo principal é executar métodos sem bloquear a thread principal (por exemplo, para enviar dados durante o treinamento). Os jobs em segundo plano são enfileirados para preservar a ordem, mas não são executados em paralelo. Se você precisar acelerar seus scripts paralelizando muitas chamadas à API, você deve configurar e usar seu próprio ThreadPoolExecutor.

Nota: Métodos mais usados, como upload_file(), upload_folder() e create_commit(), possuem um argumento run_as_future: bool para chamá-los diretamente em segundo plano. Isso é equivalente a chamá-los com api.run_as_future(...), mas é menos verboso.

Exemplo:

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

Parâmetros

  • image (str) — A imagem Docker a ser usada. Exemplos: "ubuntu", "python:3.12", "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel". Exemplo com uma imagem de um Space: "hf.co/spaces/lhoestq/duckdb".
  • command (list[str]) — O comando a ser executado. Exemplo: ["echo", "hello"].
  • env (dict[str, Any], opcional) — Define as variáveis de ambiente para o Job.
  • secrets (dict[str, Any], opcional) — Define as variáveis de ambiente secretas para o Job.
  • flavor (str, opcional) — Flavor para o hardware. Consulte JobHardware para os valores possíveis. Padrão: "cpu-basic".
  • timeout (Union[int, float, str], opcional) — Duração máxima para o Job: int com s (segundos, padrão), m (minutos), h (horas) ou d (dias). Exemplo: 300 ou "5m" para 5 minutos.
  • attempts (int, opcional) — Número máximo de tentativas, incluindo a execução inicial. O valor padrão é 1. Por exemplo, 3 significa que um Job com falha será reexecutado até 2 vezes.
  • name (str, opcional) — Um nome para o Job. Armazenado como o rótulo name. Não pode ser passado junto com uma chave name em labels. Os nomes não precisam ser únicos. O padrão é um nome derivado da imagem e do comando (com um sufixo de hash curto).
  • labels (dict[str, str], opcional) — Rótulos a serem anexados ao job (pares chave-valor).
  • volumes (list[Volume], opcional) — Buckets ou Repos do Hugging Face a serem montados como volumes no contêiner do job. Cada volume é um Volume com type ("bucket", "model", "dataset" ou "space"), source (por exemplo, "username/my-bucket") e mount_path (por exemplo, "/data").
  • expose (list[int], opcional) — Portas de contêiner a serem expostas através do proxy de jobs. Cada porta listada é acessível no domínio público de jobs (ex.: https://<job_id>--8000.hf.jobs). O acesso sempre requer um token HF com permissão de leitura no namespace do job. Use expose_public para acesso não autenticado.
  • expose_public (list[int], opcional) — Portas a serem expostas através do proxy de Jobs sem autenticação. Elas não precisam estar listadas em expose.
  • ssh (bool, opcional) — Se True, o container do job é acessível via SSH no URL fornecido por job.status.ssh_url (por exemplo, ssh <job_id>@ssh.hf.jobs, ou hf jobs ssh <job_id> a partir da CLI). A conexão requer acesso de escrita ao namespace do job e uma chave pública SSH registrada no Hub (https://huggingface.co/settings/keys). O valor padrão é False.
  • network_group (str, opcional) — Nome de um grupo de rede para participar. Jobs no mesmo namespace e resource group que compartilham um grupo são colocados juntos e podem se alcançar em todas as portas. Dentro de cada membro, HF_NETWORK_GROUP_HOSTNAME resolve para todos os membros do grupo. Alfanuméricos minúsculos e hífens, máximo de 46 caracteres.
  • network_aliases (list[str], opcional) — Aliases que este job reivindica em seu grupo de rede. Os membros acessam os jobs que reivindicam um alias em ${HF_NETWORK_GROUP_PREFIX}<alias>. Vários jobs podem reivindicar o mesmo alias. Alfanuméricos em minúsculas e hífens, no máximo 34 caracteres, únicos dentro do job. Exige network_group.
  • resource_group_id (str, opcional) — O ID do grupo de recursos em que o Job será criado. Usado para controlar o acesso a recursos dentro de uma organização e para recursos de atribuição de custos/limites de gastos. Se não for fornecido, o Job será criado fora de qualquer grupo de recursos.
  • namespace (str, opcional) — O namespace onde o Job será criado. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Execute Jobs de computação na infraestrutura do Hugging Face.

Exemplo:

Execute seu primeiro Job:

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

Executar um Job de 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")

Execute um Job com 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 )

Parâmetros

  • script (str) — Caminho ou URL do script UV, ou um comando.
  • script_args (list[str], opcional) — Argumentos a serem passados para o script ou comando.
  • dependencies (list[str], opcional) — Dependências a serem usadas para executar o script UV.
  • python (str, opcional) — Use uma versão específica do Python. O padrão é 3.12.
  • image (str, opcional, padrão “ghcr.io/astral-sh/uv —python3.12-bookworm”): Use uma imagem Docker personalizada com uv instalado.
  • env (dict[str, Any], opcional) — Define as variáveis de ambiente para o Job.
  • secrets (dict[str, Any], opcional) — Define as variáveis de ambiente secretas para o Job.
  • flavor (str, opcional) — Flavor para o hardware. Consulte JobHardware para os valores possíveis. Padrão: "cpu-basic".
  • timeout (Union[int, float, str], opcional) — Duração máxima para o Job: int com s (segundos, padrão), m (minutos), h (horas) ou d (dias). Exemplo: 300 ou "5m" para 5 minutos.
  • attempts (int, opcional) — Número máximo de tentativas, incluindo a execução inicial. O valor padrão é 1.
  • name (str, opcional) — Um nome para o Job. Armazenado como o rótulo name. Não pode ser passado junto com uma chave name em labels. Os nomes não precisam ser únicos. O padrão é um nome derivado do script e de seus argumentos (com um sufixo de hash curto).
  • labels (dict[str, str], opcional) — Rótulos a serem anexados ao job (pares chave-valor).
  • volumes (list[Volume], opcional) — Buckets ou Repos do Hugging Face a serem montados como volumes no contêiner do job. Cada volume é um Volume com type ("bucket", "model", "dataset" ou "space"), source (por exemplo, "username/my-bucket") e mount_path (por exemplo, "/data").
  • expose (list[int], opcional) — Portas de contêiner a serem expostas através do proxy de jobs. Cada porta listada é acessível no domínio público de jobs (ex.: https://<job_id>--8000.hf.jobs). O acesso sempre requer um token HF com permissão de leitura no namespace do job. Use expose_public para acesso não autenticado.
  • expose_public (list[int], opcional) — Portas a serem expostas através do proxy de Jobs sem autenticação. Elas não precisam estar listadas em expose.
  • ssh (bool, opcional) — Se True, o container do job é acessível via SSH no URL fornecido por job.status.ssh_url (por exemplo, ssh <job_id>@ssh.hf.jobs, ou hf jobs ssh <job_id> a partir da CLI). A conexão requer acesso de escrita ao namespace do job e uma chave pública SSH registrada no Hub (https://huggingface.co/settings/keys). O valor padrão é False.
  • network_group (str, opcional) — Nome de um grupo de rede para participar. Jobs no mesmo namespace e resource group que compartilham um grupo são colocados juntos e podem se alcançar em todas as portas. Dentro de cada membro, HF_NETWORK_GROUP_HOSTNAME resolve para todos os membros do grupo. Alfanuméricos minúsculos e hífens, máximo de 46 caracteres.
  • network_aliases (list[str], opcional) — Aliases que este job reivindica em seu grupo de rede. Os membros acessam os jobs que reivindicam um alias em ${HF_NETWORK_GROUP_PREFIX}<alias>. Vários jobs podem reivindicar o mesmo alias. Alfanuméricos em minúsculas e hífens, no máximo 34 caracteres, únicos dentro do job. Exige network_group.
  • resource_group_id (str, opcional) — O ID do grupo de recursos em que o Job será criado. Usado para controlar o acesso a recursos dentro de uma organização e para recursos de atribuição de custos/limites de gastos. Se não for fornecido, o Job será criado fora de qualquer grupo de recursos.
  • namespace (str, opcional) — O namespace onde o Job será criado. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Execute um Job de script UV na infraestrutura do Hugging Face.

Diferentemente de hf jobs uv run, este método ignora a tabela opcional [tool.hf-jobs] que um script UV pode carregar em seu cabeçalho PEP 723 (veja o guia de Jobs): a configuração de lançamento deve ser passada explicitamente aqui.

Exemplo:

Execute um script a partir de uma 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")

Execute um script local:

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

Execute um comando:

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

Monte volumes, por exemplo, para salvar checkpoints de modelos durante o treinamento:

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

Parâmetros

  • name (str) — O nome do Inference Endpoint para o qual a escalação para zero será aplicada.
  • namespace (str, opcional) — O namespace em que o Inference Endpoint está localizado. O padrão é o usuário atual.
  • 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.

Retorna

InferenceEndpoint

informações sobre o Inference Endpoint escalado para zero.

Escale o Endpoint de Inferência para zero.

Um Inference Endpoint escalado para zero não será cobrado. Ele será retomado na próxima solicitação a ele, com um atraso de inicialização a frio. Isso é diferente de pausar o Inference Endpoint com pause_inference_endpoint(), o que exigiria uma retomada manual com resume_inference_endpoint().

Para sua conveniência, você também pode escalar um Inference Endpoint para zero usando 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]

Parâmetros

  • query (str) — A string da consulta de pesquisa.
  • filter (str ou Iterable[str], opcional) — Uma tag de string ou uma lista de tags para filtrar.
  • sdk (str ou list[str], opcional) — Filtre por SDK (por exemplo, "gradio", "docker", "static").
  • include_non_running (bool, opcional) — Se deve incluir Spaces não em execução nos resultados. O padrão é False.
  • 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.

Retorna

Iterable[SpaceSearchResult]

um iterável de objetos SpaceSearchResult.

Espaços de Busca no Hub usando busca semântica.

Este endpoint usa busca semântica (baseada em embeddings) para consultas com múltiplas palavras e busca de texto completo para consultas com uma única palavra.

Exemplo:

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

Parâmetros

  • repo_id (str) — ID do repositório a ser atualizado. Exemplo: "bigcode/in-the-stack".
  • sleep_time (int, opcional) — Número de segundos de inatividade a aguardar antes de um Space ser colocado em modo de suspensão. Defina como -1 se você não quiser que seu Space pause (comportamento padrão para hardware atualizado). Para hardware gratuito, você não pode configurar o tempo de suspensão (o valor é fixado em 48 horas de inatividade). Veja https://huggingface.co/docs/hub/spaces-gpus#sleep-time para mais detalhes.
  • 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.

Retorna

SpaceRuntime

Informações de tempo de execução sobre um Space, incluindo o estágio e o hardware do Space.

Defina um tempo de inatividade personalizado para um Space em execução em hardware atualizado.

Seu Space entrará em modo de suspensão após X segundos de inatividade. Você não é cobrado quando seu Space está em modo de “suspensão”. Se um novo visitante acessar seu Space, ele será “acordado”. Apenas hardware atualizado pode ter um tempo de suspensão configurável. Para saber mais sobre a etapa de suspensão, consulte https://huggingface.co/docs/hub/spaces-gpus#sleep-time.

Também é possível definir um tempo de espera personalizado ao solicitar hardware com request_space_hardware().

set_space_volumes

< >

( repo_id: strvolumes: list[Volume]token: bool | str | None = None )

Parâmetros

  • repo_id (str) — ID do Space a ser atualizado. Exemplo: "username/my-space".
  • volumes (list[Volume]) — Lista de objetos Volume a serem montados. Cada volume possui um type ("bucket", "model", "dataset" ou "space"), um source (ID do repositório ou bucket), um mount_path (caminho dentro do container) e os campos opcionais revision, read_only e path.
  • 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.

Exceções

BadRequestError

  • BadRequestError — Se o Space for um Space estático (volumes não são suportados em Spaces estáticos).

Defina volumes para um Space.

Define (ou substitui) a lista de volumes montados no Space. Cada volume dá ao contêiner do Space acesso a um recurso do Hub (modelo, dataset ou bucket de armazenamento).

Exemplo:

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

Parâmetros

  • repo_id (str) — Nome de um usuário ou organização e nome de um repositório separados por /.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver baixando de um dataset ou space, None ou "model" se estiver baixando de um model. O padrão é None.
  • revision (str, opcional) — Um id de revisão Git opcional, que pode ser um nome de branch, uma tag ou um hash de commit.
  • cache_dir (str, Path, opcional) — Caminho para a pasta onde os arquivos em cache são armazenados.
  • local_dir (str ou Path, opcional) — Se fornecido, os arquivos baixados serão colocados sob este diretório.
  • etag_timeout (float, opcional, padrão 10) — Ao buscar o ETag, quantos segundos esperar o servidor enviar dados antes de desistir, valor passado para httpx2.request.
  • force_download (bool, opcional, padrão False) — Se o arquivo deve ser baixado mesmo que já exista no cache local.
  • 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.
  • local_files_only (bool, opcional, padrão False) — Se True, evita o download do arquivo e retorna o caminho para o arquivo em cache local, se ele existir.
  • allow_patterns (list[str] ou str, opcional) — Se fornecido, apenas os arquivos que corresponderem a pelo menos um padrão serão baixados.
  • ignore_patterns (list[str] ou str, opcional) — Se fornecido, os arquivos que corresponderem a qualquer um dos padrões não serão baixados.
  • max_workers (int, opcional) — Número de threads concorrentes para baixar arquivos (1 thread = 1 download de arquivo). Padrão: 8.
  • tqdm_class (tqdm, opcional) — Se fornecido, sobrescreve o comportamento padrão da barra de progresso. O argumento passado deve herdar de tqdm.auto.tqdm ou, pelo menos, imitar seu comportamento. Observe que a tqdm_class não é passada para cada download individual. Padrão: a barra de progresso personalizada do HF, que pode ser desativada definindo a variável de ambiente HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool, opcional, padrão False) — Se True, executa uma simulação sem efetivamente baixar os arquivos. Retorna uma lista de objetos DryRunFileInfo contendo informações sobre o que seria baixado.

Retorna

str ou lista de DryRunFileInfo

  • Se dry_run=False: Caminho da pasta do snapshot do repositório.
  • Se dry_run=True: uma lista de objetos DryRunFileInfo contendo informações de download.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError ou EnvironmentError ou OSError ou ValueError

  • RepositoryNotFoundError — Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
  • RevisionNotFoundError — Se a revisão de onde o download deve ser feito não for encontrada.
  • EnvironmentError — Se token=True e o token não puder ser encontrado.
  • OSError — se o ETag não puder ser determinado.
  • ValueError — se algum valor de parâmetro for inválido.

Baixe os arquivos do repositório.

Baixe um snapshot completo dos arquivos de um repositório na revisão especificada. Isso é útil quando você deseja todos os arquivos de um repositório, pois não sabe de antemão quais deles serão necessários. Todos os arquivos são aninhados dentro de uma pasta para manter seu nome de arquivo real relativo a essa pasta. Você também pode filtrar quais arquivos baixar usando allow_patterns e ignore_patterns.

Se local_dir for fornecido, a estrutura de arquivos do repositório será replicada neste local. Ao usar esta opção, o cache_dir não será utilizado e uma pasta .cache/huggingface/ será criada na raiz de local_dir para armazenar alguns metadados relacionados aos arquivos baixados. Embora este mecanismo não seja tão robusto quanto o sistema de cache principal, ele é otimizado para buscar regularmente a versão mais recente de um repositório.

Uma alternativa seria clonar o repositório, mas isso requer que o git e o git-lfs estejam instalados e configurados corretamente. Também não é possível filtrar quais arquivos baixar ao clonar um repositório usando o git.

space_info

< >

( repo_id: strrevision: str | None = Nonetimeout: float | None = Nonefiles_metadata: bool = Falseexpand: list[ExpandSpaceProperty_T] | None = Nonetoken: bool | str | None = None ) → SpaceInfo

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por um /.
  • revision (str, opcional) — A revisão do repositório do espaço de onde obter as informações.
  • timeout (float, opcional) — Se deve definir um tempo limite para a solicitação ao Hub.
  • files_metadata (bool, opcional) — Se deve ou não recuperar metadados dos arquivos no repositório (tamanho, metadados do LFS, etc). O padrão é False.
  • expand (list[ExpandSpaceProperty_T], opcional) — Lista de propriedades a serem retornadas na resposta. Quando usado, apenas as propriedades da lista serão retornadas. Este parâmetro não pode ser usado se full for passado. Os valores possíveis são "author", "cardData", "createdAt", "datasets", "disabled", "lastModified", "likes", "models", "private", "region", "runtime", "sdk", "siblings", "sha", "subdomain", "tags", "trendingScore", "usedStorage" e "resourceGroup".
  • 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.

Retorna

SpaceInfo

As informações do repositório do espaço.

Obtenha informações sobre um Space específico no huggingface.co.

O espaço pode ser privado se você passar um token aceitável.

Gera os seguintes erros:

  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
  • RevisionNotFoundError Se a revisão de onde o download deve ser feito não for encontrada.

super_squash_history

< >

( repo_id: strbranch: str | None = Nonecommit_message: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None )

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por /.
  • branch (str, opcional) — O branch a ser compactado. O padrão é o topo do branch "main".
  • commit_message (str, opcional) — A mensagem de commit a ser usada para o commit mesclado.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver listando commits de um dataset ou de um Space, None ou "model" se estiver listando de um modelo. O padrão é None.
  • 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.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError ou BadRequestError

  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou repositório inexistente.
  • RevisionNotFoundError — Se o branch a ser mesclado não puder ser encontrado.
  • BadRequestError — Se a referência para uma branch for inválida. Você não pode compactar o histórico em tags.

Compactar o histórico de commits em um branch de um repositório no Hub.

Compactar o histórico do repositório é útil quando você sabe que fará centenas de commits e não deseja poluir o histórico. A compactação de commits só pode ser executada a partir da ponta de um branch.

Uma vez compactados, o histórico de commits não pode ser recuperado. Esta é uma operação irreversível.

Uma vez que o histórico de um branch tenha sido compactado (squashed), não é possível mesclá-lo de volta em outro branch, pois seus históricos terão divergido.

Exemplo:

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

Parâmetros

  • scheduled_job_id (str) — ID do Job agendado.
  • namespace (str, opcional) — O namespace onde o Job agendado está. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Suspenda (pause) um Job de computação agendado na infraestrutura do 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]

Parâmetros

  • source (str, opcional) — Caminho de origem: diretório local ou hf://buckets/namespace/bucket_name(/prefix). Obrigatório, exceto ao usar apply.
  • dest (str, optional) — Destination path: local directory or hf://buckets/namespace/bucket_name(/prefix). Required unless using apply.
  • delete (bool, opcional, padrão False) — Exclui os arquivos de destino que não estão presentes na origem.
  • ignore_times (bool, opcional, padrão False) — Pula arquivos com base apenas no tamanho, ignorando os horários de modificação.
  • ignore_sizes (bool, opcional, padrão False) — Pula arquivos com base apenas nos horários de modificação, ignorando os tamanhos.
  • existing (bool, opcional, padrão False) — Pula a criação de novos arquivos no receptor (atualiza apenas os arquivos existentes).
  • ignore_existing (bool, opcional, padrão False) — Pula a atualização de arquivos que já existem no receptor (cria apenas arquivos novos).
  • include (list[str], opcional) — Inclui arquivos que correspondam a padrões (estilo fnmatch).
  • exclude (list[str], opcional) — Exclui arquivos que correspondam a padrões (estilo fnmatch).
  • filter_from (str, opcional) — Caminho para um arquivo de filtro com regras de inclusão/exclusão.
  • plan (str, opcional) — Salva o plano de sincronização neste arquivo JSONL em vez de executá-lo.
  • apply (str, optional) — Aplica um arquivo de plano salvo anteriormente. Quando definido, source e dest não são necessários.
  • dry_run (bool, opcional, padrão False) — Imprime o plano de sincronização no stdout como JSONL sem executar.
  • verbose (bool, opcional, padrão False) — Exibe operações detalhadas por arquivo.
  • quiet (bool, opcional, padrão False) — Suprime toda a saída e as barras de progresso.
  • token (Union[bool, str, None], opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado.

Retorna

[SyncPlan]

O plano de sincronização calculado (ou carregado).

Sincronize arquivos entre um diretório local e um bucket.

Isso é equivalente ao comando de CLI hf buckets sync. Um de source ou dest deve ser um caminho de bucket (hf://buckets/...) e o outro deve ser um caminho de diretório local.

Exemplo:

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

Parâmetros

  • source (str ou Path) — Caminho para um diretório local para sincronizar.
  • mount_path (str) — Caminho de montagem dentro do contêiner do Job, por exemplo, "/inputs". Deve começar com /.
  • remote_name (str, opcional) — Nome da subpasta do bucket para sincronizar. O padrão é um nome {dirname}-{hash} derivado do caminho de origem e do nome do host da máquina.
  • read_only (bool, opcional, padrão True) — Monta o volume somente leitura no Job. Passe False para permitir que o Job escreva de volta na pasta do bucket (por exemplo, para recuperar saídas com sync_bucket() em seguida).
  • namespace (str, opcional) — O namespace que possui o bucket jobs-artifacts. O padrão é o namespace do usuário atual. Use o mesmo namespace do Job que irá montar o volume.
  • token (Union[bool, str, None], opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será usado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retorna

Volume

Um volume de bucket limitado à subpasta sincronizada, para passar na lista volumes de run_job(), run_uv_job(), create_scheduled_job() ou create_scheduled_uv_job().

Sincronize um diretório local com um bucket e retorne um Volume pronto para ser montado em um Job.

Os arquivos são enviados para uma subpasta do bucket {namespace}/jobs-artifacts (criado automaticamente como privado; um aviso é emitido se ele já existir e for público) usando a mesma lógica de sincronização de sync_bucket(): re-sincronizar o mesmo diretório apenas envia arquivos novos ou modificados. Por padrão, o nome da subpasta é derivado do caminho do diretório e do nome do host da máquina, de modo que chamadas repetidas a partir do mesmo diretório reutilizam a mesma pasta remota. Passe remote_name para usar um nome fixo em vez disso.

Observe que os dados são copiados para o bucket, e não montados ao vivo: alterações feitas localmente após a sincronização não são visíveis para o Job (execute novamente sync_job_volume para atualizar), e o volume é montado somente leitura por padrão. Para recuperar os dados gravados por um Job em um volume de leitura e escrita, sincronize a pasta do bucket de volta com sync_bucket(). Se o diretório de origem estiver vazio (por exemplo, um diretório de saída), um arquivo placeholder .keep é enviado para que o volume ainda possa ser montado.

Exemplo:

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

Parâmetros

  • scheduled_job_id (str) — ID do Job agendado.
  • namespace (str, opcional) — O namespace onde o Job agendado está. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retorna

JobInfo

Informações sobre a execução acionada.

Exceções

HfHubHTTPError

  • HfHubHTTPError — HTTP 409 se outra instância já estiver em execução e concurrency estiver desabilitado no agendamento.

Disparar a execução imediata de um Job agendado.

Isso dispara uma execução imediata da especificação do job agendado. Ele não modifica o agendamento e não não afeta a próxima execução agendada. Se uma instância já estiver em execução e o job agendado não permitir execuções concorrentes, a solicitação será rejeitada (HTTP 409).

diferente de

< >

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

Parâmetros

  • repo_id (str) — O repositório para o qual você deseja remover a marcação de "curtir". Exemplo: "user/my-cool-model".
  • 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.
  • repo_type (str, opcional) — Defina como "dataset" ou "space" se estiver descurtando um dataset ou space, None ou "model" se estiver descurtando um model. O padrão é None.

Exceções

RepositoryNotFoundError

  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou o repositório não existe.

Diferente de um repositório específico no Hub (por exemplo, remover da lista de favoritos).

Para evitar o uso indevido, não é possível like um repositório a partir de um script.

Veja também list_liked_repos().

Exemplo:

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

Parâmetros

  • bucket_id (str) — O ID do bucket (por exemplo, "username/my-bucket").
  • private (bool) — Se o bucket deve ser privado.
  • 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.

Exceções

BucketNotFoundError ou or

  • BucketNotFoundError — Se o bucket não puder ser encontrado. Isso pode ocorrer porque ele não existe,
  • or — porque está definido como private e você não tem acesso.

Atualize as configurações de um bucket no Hub.

Atualmente, a única configuração suportada é a visibilidade do bucket.

Exemplo:

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

Parâmetros

  • collection_slug (str) — Slug da coleção a ser atualizada. Exemplo: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • item_object_id (str) — ID do item na coleção. Este não é o id do item no Hub (repo_id ou paper id). Ele deve ser obtido de um objeto CollectionItem. Exemplo: collection.items[0].item_object_id.
  • note (str, opcional) — Uma nota para anexar ao item na coleção. O tamanho máximo para uma nota é de 500 caracteres.
  • position (int, opcional) — Nova posição do item na coleção.
  • 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.

Atualize um item em uma coleção.

Exemplo:

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

Parâmetros

  • collection_slug (str) — Slug da coleção a ser atualizada. Exemplo: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • title (str) — Título da coleção a ser atualizada.
  • description (str, opcional) — Descrição da coleção a ser atualizada. O tamanho máximo para uma descrição é de 150 caracteres.
  • position (int, opcional) — Nova posição da coleção na lista de coleções do usuário.
  • private (bool, opcional) — Se a coleção deve ser privada ou não.
  • theme (str, opcional) — Tema da coleção no Hub.
  • 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.

Atualize os metadados de uma coleção no Hub.

Todos os argumentos são opcionais. Somente os metadados fornecidos serão atualizados.

Retorna: Collection

Exemplo:

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

Parâmetros

  • collection_slug (str) — Slug da coleção a ser atualizada. Exemplo: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
  • resource_group_id (str or None) — O grupo de recursos ao qual a coleção será atribuída, como uma string hexadecimal de 24 caracteres. Se None, a coleção é removida de qualquer grupo de recursos.
  • 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.

Atribua uma coleção a um grupo de recursos ou remova-a de qualquer grupo de recursos.

Válido apenas para coleções pertencentes a uma organização.

Exemplo:

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

Parâmetros

  • name (str) — O nome do Inference Endpoint a ser atualizado.
  • accelerator (str, opcional) — O acelerador de hardware a ser usado para inferência (por exemplo, "cpu").
  • instance_size (str, opcional) — O tamanho ou o tipo da instância a ser usada para hospedar o modelo (por exemplo, "x4").
  • instance_type (str, opcional) — O tipo de instância de nuvem onde o Inference Endpoint será implantado (por exemplo, "intel-icl").
  • min_replica (int, opcional) — O número mínimo de réplicas (instâncias) a manter em execução para o Inference Endpoint.
  • max_replica (int, opcional) — O número máximo de réplicas (instâncias) para as quais o Inference Endpoint deve ser dimensionado.
  • scale_to_zero_timeout (int, opcional) — A duração, em minutos, antes de um endpoint inativo ser reduzido a zero.
  • scaling_metric (str ou InferenceEndpointScalingMetric , opcional) — A métrica de referência para o dimensionamento. Deve ser “pendingRequests” ou “hardwareUsage” quando fornecida. Padrão: None.
  • scaling_threshold (float, opcional) — O limiar da métrica de escala usado para acionar o aumento de escala. Ignorado quando a métrica de escala não é fornecida. Padrão: None.
  • repository (str, opcional) — O nome do repositório de modelos associado ao Inference Endpoint (por exemplo, "gpt2").
  • framework (str, opcional) — O framework de machine learning usado para o modelo (por exemplo, "custom").
  • revision (str, opcional) — A revisão específica do modelo a ser implantada no Inference Endpoint (por exemplo, "6c0e6080953db56375760c0471a8c5f2929baf11").
  • task (str, opcional) — A tarefa na qual o modelo será implantado (por exemplo, "text-classification").
  • custom_image (dict, opcional) — A imagem de container a ser executada. Pode ser um dicionário com chaves por variante de imagem (por exemplo, {"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}‌}, também sGLang, tgi, tei, llamacpp, hfServe, …), que é encaminhado como está, ou um dicionário plano descrevendo um container personalizado (por exemplo, {"url": ..., "port": ...}), que é enviado como {"custom": ...}.
  • container_command (list[str], opcional) — Substitui o comando de entrada do container (corresponde a model.command no payload da API). Funciona com imagens de engine gerenciadas (por exemplo, vLLM, SGLang) e imagens personalizadas.
  • container_args (list[str], opcional) — Argumentos adicionados ao entrypoint do container (corresponde a model.args no payload da API). Funciona com imagens de engine gerenciadas (por exemplo, vLLM, SGLang) e imagens personalizadas.
  • tensor_parallel_size (int, opcional) — Número de aceleradores para dividir uma única cópia do modelo (imagens vLLM e SGLang). Gravado dentro da configuração da imagem do engine. A API requer model.image como um todo, portanto, quando custom_image não é fornecido, a imagem atualmente configurada no endpoint é obtida e atualizada no local.
  • data_parallel_size (int, opcional) — Número de cópias do modelo a serem executadas, uma por acelerador (imagens do vLLM). O tratamento é o mesmo de tensor_parallel_size.
  • env (dict[str, str], opcional) — Variáveis de ambiente não confidenciais para injetar no ambiente do contêiner
  • secrets (dict[str, str], opcional) — Valores de segredo a serem injetados no ambiente do contêiner.
  • domain (str, opcional) — O domínio personalizado para a implantação do Inference Endpoint. Se configurado, o Inference Endpoint ficará disponível neste domínio (por exemplo, "my-new-domain.cool-website.woof").
  • path (str, opcional) — O caminho personalizado para o modelo implantado, deve começar com / (ex.: "/models/google-bert/bert-base-uncased").
  • cache_http_responses (bool, opcional) — Se as respostas HTTP do Inference Endpoint devem ser armazenadas em cache.
  • tags (list[str], opcional) — Uma lista de tags para associar ao Inference Endpoint.
  • namespace (str, opcional) — O namespace onde o Inference Endpoint será atualizado. O padrão é o namespace do usuário atual.
  • 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.

Retorna

InferenceEndpoint

informações sobre o Inference Endpoint atualizado.

Atualize um Inference Endpoint.

Este método permite a atualização da configuração de computação, do modelo implantado, da rota ou de qualquer combinação. Todos os argumentos são opcionais, mas pelo menos um deve ser fornecido.

Para sua conveniência, você também pode atualizar um Inference Endpoint usando 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

Parâmetros

  • job_id (str) — ID do Job em execução.
  • expose (list[int], opcional) — Portas a serem expostas através do proxy de Jobs. O acesso requer um token do HF com acesso de leitura ao namespace do Job.
  • expose_public (list[int], opcional) — Portas a serem expostas através do proxy de Jobs sem autenticação. Elas não precisam estar listadas em expose.
  • namespace (str, opcional) — Namespace do Job. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Token de acesso do usuário. O padrão é o token salvo localmente.

Retorna

JobInfo

O Job atualizado.

Substitua as portas expostas de um Job em execução sem reexecutá-lo.

expose e expose_public juntos formam a configuração completa de portas: portas que não estão em nenhuma das listas são fechadas. Não passe nenhum dos dois para fechar todas as portas expostas.

update_job_labels

< >

( job_id: strlabels: dict[str, str]namespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo

Parâmetros

  • job_id (str) — ID do Job.
  • labels (dict[str, str]) — Novos rótulos a definir no job. Substitui todos os rótulos existentes. Tanto as chaves quanto os valores devem ter no máximo 100 caracteres e conter apenas caracteres alfanuméricos, hífens e sublinhados.
  • namespace (str, opcional) — O namespace onde o Job está em execução. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retorna

JobInfo

As informações atualizadas do Job.

Atualize os rótulos de um Job existente.

Substitui todos os rótulos fornecidos pelo usuário existentes pelos novos rótulos.

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 )

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por uma /.
  • gated (Literal["auto", "manual", False], opcional) — O status de acesso restrito do repositório. Se definido como None (padrão), a configuração gated do repositório não será atualizada.
    • “auto”: o repositório é restrito e as solicitações de acesso são aprovadas ou negadas automaticamente com base em critérios predefinidos.
    • “manual”: O repositório é restrito e as solicitações de acesso exigem aprovação manual.
    • False: O repositório não é restrito e qualquer pessoa pode acessá-lo.
  • private (bool, opcional) — Se o repositório deve ser privado. Não pode ser passado junto com visibility.
  • visibility (Literal["public", "private", "protected"], opcional) — Visibilidade do repositório. Pode ser "public" ou "private", ou "protected" para Spaces.
  • token (Union[str, bool, None], 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.
  • repo_type (str, opcional) — O tipo do repositório do qual as configurações serão atualizadas ("model", "dataset" ou "space"). Padrão: "model".

Exceções

ValueError ou HfHubHTTPError ou RepositoryNotFoundError

  • ValueError — Se gated não for um dos valores “auto”, “manual” ou False.
  • ValueError — Se repo_type não for um dos valores em constants.REPO_TYPES.
  • HfHubHTTPError — Se a solicitação à API do Hugging Face Hub falhar.
  • RepositoryNotFoundError — Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.

Atualize as configurações de um repositório, incluindo acesso restrito e visibilidade.

Para dar mais controle sobre como os repositórios são usados, o Hub permite que os autores dos repositórios habilitem solicitações de acesso aos seus repositórios e também alterem a visibilidade do repositório.

update_scheduled_job_labels

< >

( scheduled_job_id: strlabels: dict[str, str]namespace: str | None = Nonetoken: bool | str | None = None ) → ScheduledJobInfo

Parâmetros

  • scheduled_job_id (str) — ID do Job agendado.
  • labels (dict[str, str]) — Novos rótulos a serem definidos no job agendado. Substitui todos os rótulos existentes. Tanto as chaves quanto os valores devem ter no máximo 100 caracteres e conter apenas caracteres alfanuméricos, hífens e sublinhados.
  • namespace (str, opcional) — O namespace onde o Job agendado está. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retorna

ScheduledJobInfo

As informações atualizadas do Job agendado.

Atualize os rótulos de um Job agendado existente.

Substitui todos os rótulos fornecidos pelo usuário existentes pelos novos rótulos.

update_scheduled_job_schedule

< >

( scheduled_job_id: strschedule: strnamespace: str | None = Nonetoken: bool | str | None = None ) → ScheduledJobInfo

Parâmetros

  • scheduled_job_id (str) — ID do Job agendado.
  • schedule (str) — Um dos valores “@annually”, “@yearly”, “@monthly”, “@weekly”, “@daily”, “@hourly”, ou uma expressão de agendamento CRON (por exemplo, ‘0 9 * * 1’ para 9h de toda segunda-feira).
  • namespace (str, opcional) — O namespace onde o Job agendado está. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retorna

ScheduledJobInfo

As informações atualizadas do Job agendado.

Alterar quando um Job agendado existente é executado.

Apenas o cronograma é atualizado: a especificação do Job, os rótulos e o estado suspenso são mantidos. Para executar o Job agendado uma única vez agora, sem alterar seu cronograma, use trigger_scheduled_job() em vez disso.

Exemplo:

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

Parâmetros

  • webhook_id (str) — O identificador único do webhook a ser atualizado.
  • url (str, opcional) — A URL para a qual a carga útil será enviada.
  • job_id (str, opcional) — ID do Job de origem a ser acionado com o payload do webhook. Obrigatório ao definir secrets.
  • watched (list[WebhookWatchedItem], opcional) — Lista de itens para monitorar. Pode ser usuários, organizações, modelos, conjuntos de dados ou espaços. Consulte WebhookWatchedItem para mais detalhes. Os itens monitorados também podem ser fornecidos como dicionários simples.
  • domains (list[Literal["repo", "discussion"]], opcional) — Os domínios a serem monitorados. Isso pode incluir “repo”, “discussion” ou ambos.
  • secret (str, opcional) — Um segredo para assinar a carga útil, fornecendo uma camada adicional de segurança.
  • secrets (dict[str, str], opcional) — Variáveis de ambiente secretas para o Job acionado pelo webhook. As chaves listadas substituem o valor armazenado, uma string vazia remove aquele segredo e as chaves omitidas mantêm seu valor armazenado. Requer job_id.
  • 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.

Retorna

WebhookInfo

Informações sobre o webhook atualizado.

Atualize um webhook existente.

Exemplo:

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

Parâmetros

  • path (str ou Path) — Caminho para o arquivo a ser enviado. Os formatos suportados são PNG, JPEG, GIF, WebP, MP4, MOV, WebM, MP3 e WAV. Os arquivos devem ter menos de 10MB (50MB para vídeos).
  • token (bool ou 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). O token precisa da permissão discussion.write. Para fazer upload de forma anônima, passe False.

Retorna

str

a URL do arquivo enviado.

Exceções

ValueError

  • ValueError — Se o formato do arquivo não for suportado.

Envia uma imagem, um vídeo ou um arquivo de áudio para o Hub e retorna sua URL.

É isso que o editor web do Hub faz quando você arrasta um arquivo para a caixa de comentários de uma Discussion ou Pull Request. Incorpore a URL retornada em uma descrição ou em um comentário: ![alt text](url) para uma imagem, a URL simples para um vídeo e <audio controls src="url"></audio> para um arquivo de áudio.

Exemplo:

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

Parâmetros

  • path_or_fileobj (str, Path, bytes ou IO) — Caminho para um arquivo na máquina local ou fluxo de dados binário / fileobj / buffer.
  • path_in_repo (str) — Caminho de arquivo relativo no repositório, por exemplo: "checkpoints/1fec34a/weights.bin"
  • repo_id (str) — O repositório para o qual o arquivo será enviado, por exemplo: "username/custom_transformers"
  • 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.
  • repo_type (str, opcional) — Defina como "dataset", "space" ou "kernel" se estiver fazendo upload para um repositório de dataset, space ou kernel, None ou "model" se estiver fazendo upload para um modelo. O padrão é None.
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo do ramo "main".
  • commit_message (str, opcional) — O resumo / título / primeira linha do commit gerado
  • commit_description (str, opcional) — A descrição do commit gerado
  • create_pr (boolean, opcional) — Se deve ou não criar um Pull Request com esse commit. O padrão é False. Se revision não estiver definido, o PR será aberto contra o ramo "main". Se revision estiver definido e for um ramo, o PR será aberto contra esse ramo. Se revision estiver definido e não for um nome de ramo (exemplo: um oid de commit), um RevisionNotFoundError será retornado pelo servidor.
  • parent_commit (str, opcional) — O OID / SHA do commit pai, como uma string hexadecimal. Abreviações (os 7 primeiros caracteres) também são suportadas. Se especificado e create_pr for False, o commit falhará se revision não apontar para parent_commit. Se especificado e create_pr for True, a pull request será criada a partir de parent_commit. Especificar parent_commit garante que o repositório não tenha sido alterado antes de commitar as mudanças, o que pode ser especialmente útil se o repositório for atualizado / commitado simultaneamente.
  • run_as_future (bool, opcional) — Se este método deve ser executado em segundo plano ou não. Os trabalhos em segundo plano são executados sequencialmente sem bloquear a thread principal. Passar run_as_future=True retornará um objeto Future. O valor padrão é False.

Retorna

CommitInfo ou Future

Instância de CommitInfo contendo informações sobre o commit recém-criado (hash do commit, url do commit, url do pr, mensagem do commit,…). Se run_as_future=True for passado, retorna um objeto Future que conterá o resultado quando executado.

Envie um arquivo local (de até 50 GB) para o repositório indicado. O upload é realizado por meio de uma requisição HTTP post e não requer que o git ou o git-lfs estejam instalados.

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido
  • RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe ou porque está definido como private e você não tem acesso.
  • RevisionNotFoundError Se a revisão de onde o download deve ser feito não for encontrada.

upload_file pressupõe que o repositório já exista no Hub. Se você receber um erro de cliente 404, verifique se está autenticado, se o seu token possui as permissões necessárias e se repo_id e repo_type estão configurados corretamente. Se o repositório não existir, crie-o primeiro usando create_repo().

Exemplo:

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

Parâmetros

  • repo_id (str) — O repositório para o qual o arquivo será enviado, por exemplo: "username/custom_transformers"
  • folder_path (str ou Path) — Caminho para a pasta a ser enviada no sistema de arquivos local
  • path_in_repo (str, opcional) — Caminho relativo do diretório no repositório, por exemplo: "checkpoints/1fec34a/results". O padrão é a pasta raiz do repositório.
  • 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.
  • repo_type (str, opcional) — Defina como "dataset", "space" ou "kernel" se estiver fazendo upload para um repositório de dataset, space ou kernel, None ou "model" se estiver fazendo upload para um modelo. O padrão é None.
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo do ramo "main".
  • commit_message (str, opcional) — O resumo / título / primeira linha do commit gerado. Padrão: f"Upload {path_in_repo} with huggingface_hub"
  • commit_description (str opcional) — A descrição do commit gerado
  • create_pr (boolean, opcional) — Indica se um Pull Request deve ser criado com esse commit. O valor padrão é False. O PR é sempre aberto contra o branch padrão: definir tanto create_pr=True quanto revision levanta um ValueError. Observe que cada chamada com create_pr=True abre um novo pull request: para retomar um upload interrompido no PR existente, execute novamente com revision="refs/pr/N" em vez disso.
  • parent_commit (str, opcional) — O OID / SHA do commit pai, como uma string hexadecimal. Abreviações (os 7 primeiros caracteres) também são suportadas. Se especificado e create_pr for False, o commit falhará se revision não apontar para parent_commit. Especificar parent_commit garante que o repositório não tenha sido alterado antes de commitar as mudanças, o que pode ser especialmente útil se o repositório for atualizado / commitado simultaneamente. Se o upload for dividido em vários commits (pastas grandes), parent_commit se aplica apenas ao primeiro.
  • allow_patterns (list[str] ou str, opcional) — Se fornecido, apenas os arquivos que corresponderem a pelo menos um padrão serão enviados.
  • ignore_patterns (list[str] ou str, opcional) — Se fornecido, os arquivos que corresponderem a qualquer um dos padrões não serão enviados.
  • delete_patterns (list[str] ou str, opcional) — Se fornecido, os arquivos remotos que corresponderem a qualquer um dos padrões serão excluídos do repositório ao commitar novos arquivos. Isso é útil se você não souber quais arquivos já foram enviados. Observação: para evitar discrepâncias, o arquivo .gitattributes não é excluído, mesmo que corresponda ao padrão.
  • run_as_future (bool, opcional) — Se este método deve ser executado em segundo plano ou não. Os trabalhos em segundo plano são executados sequencialmente sem bloquear a thread principal. Passar run_as_future=True retornará um objeto Future. O valor padrão é False.

Retorna

CommitInfo ou Future

Instância de CommitInfo contendo informações sobre o commit recém-criado (hash do commit, url do commit, url do pr, mensagem do commit,…). Se run_as_future=True for passado, retorna um objeto Future que conterá o resultado quando executado.

Envie uma pasta local para o repositório especificado. O upload é realizado por meio de requisições HTTP e não requer que o git ou o git-lfs estejam instalados.

A estrutura da pasta será preservada. Arquivos com o mesmo nome já presentes no repositório serão sobrescritos. Os demais permanecerão intactos.

Use os argumentos allow_patterns e ignore_patterns para especificar quais arquivos enviar. Esses parâmetros aceitam um único padrão ou uma lista de padrões. Os padrões são curingas padrão (padrões de globbing), conforme documentado aqui. Se ambos allow_patterns e ignore_patterns forem fornecidos, ambas as restrições se aplicam. Por padrão, todos os arquivos da pasta são enviados.

Use o argumento delete_patterns para especificar os arquivos remotos que deseja excluir. O tipo de entrada é o mesmo de allow_patterns (veja acima). Se path_in_repo também for fornecido, os padrões são comparados com os caminhos relativos a esta pasta. Por exemplo, upload_folder(..., path_in_repo="experiment", delete_patterns="logs/*") excluirá qualquer arquivo remoto sob ./experiment/logs/. Observe que o arquivo .gitattributes não será excluído, mesmo que corresponda aos padrões.

Qualquer pasta .git/ presente em qualquer subdiretório será ignorada. No entanto, tenha em mente que o arquivo .gitignore não é considerado.

Quando o hf_xet está instalado (o padrão), os arquivos são enviados por meio de um pipeline em streaming: os uploads começam enquanto a pasta ainda está sendo verificada em relação ao Hub, os arquivos são hasheados enquanto são divididos em blocos para upload (uma única passagem de leitura) e pastas grandes são automaticamente commitadas em vários lotes para permanecer abaixo dos limites do servidor (commits subsequentes recebem um sufixo (part N) na mensagem do commit). Se o upload for interrompido, a reexecução da mesma chamada o retoma: arquivos já commitados são ignorados e dados já enviados são deduplicados. Quando o hf_xet não está instalado, o sistema recorre a um único commit criado com create_commit().

Gera os seguintes erros:

  • HTTPError se a API do HuggingFace retornou um erro
  • ValueError se algum valor de parâmetro for inválido

upload_folder pressupõe que o repositório já exista no Hub. Se você receber um erro de cliente 404, verifique se está autenticado, se seu token possui as permissões necessárias e se repo_id e repo_type estão configurados corretamente. Se o repositório não existir, crie-o primeiro usando create_repo().

Exemplo:

# 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

Parâmetros

  • repo_id (str) — Um namespace (usuário ou organização) e um nome de repositório separados por /.
  • repo_type (str, opcional) — O tipo do repositório do qual obter a árvore ("model", "dataset" ou "space". Padrão: "model".
  • revision (str, opcional) — A revisão do repositório de onde obter a árvore. O padrão é o branch "main".
  • local_dir (str ou Path, opcional) — O diretório local a ser verificado.
  • cache_dir (str ou Path, opcional) — O diretório de cache a ser verificado.
  • token (Union[bool, str, None], 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.

Retorna

FolderVerification

um resultado estruturado contendo os detalhes da verificação.

Exceções

RepositoryNotFoundError ou RevisionNotFoundError

  • RepositoryNotFoundError — Se o repositório não for encontrado (erro 404): repo_id/repo_type incorretos, repositório privado sem autenticação ou repositório inexistente.
  • RevisionNotFoundError — Se a revisão não for encontrada (erro 404) no repositório.

Verifique os arquivos locais de um repositório em relação aos checksums do 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]

Parâmetros

  • job_id (str ou list[str]) — ID do Job, ou uma lista de IDs de Job para aguardar. Se uma lista for passada, uma lista de JobInfo é retornada (na mesma ordem).
  • timeout (float, opcional) — O tempo máximo a ser aguardado para que o(s) Job(s) terminem, em segundos. Se None, aguardará indefinidamente.
  • poll_interval (float, opcional) — O tempo a ser aguardado entre cada verificação de status, em segundos. O padrão é 1s.
  • stages (list[JobStage], opcional) — Os estágios para os quais se deve aguardar. O padrão são os estágios terminais ("COMPLETED", "CANCELED", "ERROR", "DELETED"). Passe, por exemplo, [JobStage.RUNNING] para aguardar que o Job comece a ser executado. Estágios terminais sempre interrompem a espera, independentemente deste valor.
  • namespace (str, opcional) — O namespace onde o(s) Job(s) estão em execução. O padrão é o namespace do usuário atual.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. Se não for fornecido, o token salvo localmente será utilizado, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Consulte: https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retorna

JobInfo ou list[JobInfo]

as informações finais do Job.

Exceções

TimeoutError

  • TimeoutError — Se pelo menos um Job não tiver atingido um dos estágios-alvo após timeout segundos.

Aguarde até que um ou mais Jobs de computação na infraestrutura do Hugging Face atinjam um estágio específico.

Cada status de Job é consultado (com inspect_job()) a cada poll_interval segundos até que sua etapa seja uma de stages (etapas terminais por padrão: "COMPLETED", "CANCELED", "ERROR" ou "DELETED"). O JobInfo final é retornado em todos os casos: um Job falho ou cancelado não lança uma exceção — verifique job.status.stage para agir com base no resultado.

As etapas finais sempre interrompem a espera, mesmo quando não estão listadas em stages. Isso evita esperar indefinidamente por uma etapa que o Job nunca alcançará (por exemplo, esperar por "RUNNING" em um Job que falha durante o agendamento).

Exemplo:

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

Parâmetros

  • repo_id (str) — ID do Space para o qual aguardar. Exemplo: "username/my-space".
  • timeout (float, opcional) — Tempo máximo de espera em segundos. Se None, espera indefinidamente.
  • poll_interval (float, opcional) — Segundos entre as verificações de status. O padrão é 1s.
  • token (bool ou str, opcional) — Um token de acesso de usuário válido. O padrão é o token salvo localmente, que é o método de autenticação recomendado. Defina como False para desabilitar a autenticação. Veja https://huggingface.co/docs/huggingface_hub/quick-start#authentication.

Retorna

SpaceRuntime

As informações finais de tempo de execução quando o Space atinge um estágio terminal.

Exceções

TimeoutError

  • TimeoutError — Se o Space não tiver atingido um estágio terminal após timeout segundos.

Aguarde até que um Space atinja um estágio terminal (não esteja em construção/iniciando).

As consultas get_space_runtime() a cada poll_interval segundos até que o estágio do Space não seja mais intermediário (BUILDING, RUNNING_BUILDING, APP_STARTING, RUNNING_APP_STARTING). Retorna o SpaceRuntime final em todos os casos — verifique runtime.stage para agir com base no resultado (por exemplo, RUNNING vs BUILD_ERROR).

Exemplo:

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

Parâmetros

  • 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.
  • cache (bool, opcional) — Se deve armazenar em cache o resultado da chamada whoami para chamadas subsequentes. Se ocorrer um erro durante a primeira chamada, ele não será armazenado em cache. Padrão: False.

Chame a API do HF para saber “whoami”.

Se você passar cache=True, o resultado será armazenado em cache para chamadas subsequentes durante a duração do processo Python. Isso é útil se você planeja chamar whoami várias vezes, pois esse endpoint é fortemente limitado em taxa por motivos de segurança.

Dataclasses da API

AccessRequest

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

Parâmetros

  • username (str, opcional) — Nome de usuário do usuário que solicitou o acesso. None se o repositório estiver configurado para não compartilhar os nomes de usuário dos solicitantes. Nesse caso, use request_id para aceitar, rejeitar ou cancelar a solicitação.
  • request_id (str) — ID da solicitação de acesso. Sempre definido, mesmo que o nome de usuário não seja compartilhado.
  • fullname (str, opcional) — Nome completo do usuário que solicitou o acesso. None se o repositório estiver configurado para não compartilhar os nomes de usuário dos solicitantes.
  • email (str, opcional) — E-mail do usuário que solicitou o acesso. None se o usuário recebeu acesso manualmente ou se o repositório estiver configurado para não compartilhar os e-mails dos solicitantes.
  • timestamp (datetime) — Carimbo de data e hora da solicitação.
  • status (Literal["pending", "accepted", "rejected"]) — Status da solicitação. Pode ser um de ["pending", "accepted", "rejected"].
  • fields (dict[str, Any], opcional) — Campos adicionais preenchidos pelo usuário no formulário de gate.

Estrutura de dados contendo informações sobre uma solicitação de acesso de usuário.

BucketFile

classe huggingface_hub.BucketFile

< >

( **kwargs )

Contém informações sobre um arquivo em um bucket no Hub. Este objeto é retornado por list_bucket_tree().

Similar a RepoFile, mas para arquivos em buckets.

BucketFileMetadata

classe huggingface_hub.BucketFileMetadata

< >

( size: intxet_file_data: XetFileData )

Parâmetros

  • size (int) — Tamanho do arquivo em bytes.
  • xet_file_data (XetFileData) — Informações do Xet para o arquivo (hash e rota de atualização).

Estrutura de dados contendo informações sobre um arquivo em um bucket.

Retornado por get_bucket_file_metadata().

BucketInfo

classe huggingface_hub.BucketInfo

< >

( **kwargs )

Parâmetros

  • id (str) — ID do bucket.
  • private (bool) — Indica se o bucket é privado.
  • created_at (datetime) — Data de criação do bucket no Hub.
  • size (int) — Tamanho do bucket em bytes.
  • total_files (int) — Número total de arquivos no bucket.

Contém informações sobre um bucket no Hub. Este objeto é retornado por bucket_info() e list_buckets().

BucketUrl

classe huggingface_hub.BucketUrl

< >

( url: strendpoint: str = '' )

Parâmetros

  • url (str) — Valor de string da URL do bucket.
  • endpoint (str, opcional) — Endpoint do Hub. O padrão é https://huggingface.co.

Descreve uma URL de bucket no Hub.

BucketUrl é retornado por create_bucket(). Na inicialização, a URL é analisada para preencher as propriedades:

  • endpoint (str)
  • namespace (str)
  • bucket_id (str)
  • url (str)
  • uri (HfUri)

DatasetLeaderboardEntry

classe huggingface_hub.DatasetLeaderboardEntry

< >

( **kwargs )

Parâmetros

  • rank (int) — Posição do modelo no quadro de líderes (1-indexed).
  • model_id (str) — ID do modelo (por exemplo, "meta-llama/Llama-3-8b").
  • value (float) — Valor da pontuação de avaliação.
  • filename (str) — Nome do arquivo de resultado contendo os dados de avaliação.
  • verified (bool) — Indica se o resultado foi verificado.
  • source (dict[str, Any], opcional) — Informações sobre a origem do resultado da avaliação. Contém chaves como "url", "name" e "isExternal". Nem todas as entradas possuem uma origem.
  • author (User ou Organization) — O autor do modelo, analisado com base no campo "type" na resposta da API.
  • pull_request (int, opcional) — Número da pull request associada à entrada do leaderboard, se houver.
  • notes (str, opcional) — Notas associadas à entrada do ranking, se houver.

Contém informações sobre uma única entrada em um ranking de conjuntos de dados no Hub.

Um leaderboard classifica modelos com base em suas pontuações de avaliação em um conjunto de dados de benchmark específico. Este objeto é retornado por get_dataset_leaderboard(). Para obter os resultados de avaliação de um modelo específico em vários benchmarks, consulte ModelInfo.eval_results (via model_info() com expand=["evalResults"]) e EvalResultEntry.

EvalResultEntry

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

Parâmetros

  • dataset_id (str) — ID do conjunto de dados de benchmark do Hub. Exemplo: “cais/hle”, “Idavidrein/gpqa”.
  • task_id (str) — Identificador da tarefa dentro do benchmark. Exemplo: “gpqa_diamond”.
  • value (Any) — O valor da métrica. Exemplo: 20.90.
  • dataset_revision (str, opcional) — SHA do Git do conjunto de dados de benchmark.
  • verify_token (str, opcional) — Uma assinatura que pode ser usada para provar que a avaliação é auditável e reproduzível de forma comprovável.
  • date (str, opcional) — Quando a avaliação foi executada (data e hora no formato ISO-8601). O padrão é o horário do commit do git.
  • source_url (str, opcional) — Link para a fonte de avaliação (por exemplo, https://huggingface.co/spaces/SaylorTwift/smollm3-mmlu-pro). Obrigatório se source_name, source_user ou source_org for fornecido.
  • source_name (str, opcional) — Nome de exibição da origem. Exemplo: “Eval Logs”.
  • source_user (str, opcional) — Nome de usuário do HF para atribuição. Exemplo: “celinah”.
  • source_org (str, opcional) — Nome da organização do HF para atribuição. Exemplo: “cais”.
  • notes (str, opcional) — Detalhes sobre a configuração da avaliação. Exemplo: “tools”, “no-tools”, “chain-of-thought”.

Entrada de resultado de avaliação para o formato .eval_results/*.yaml.

Representa as pontuações de avaliação armazenadas nos repositórios de modelos que aparecem automaticamente na página do modelo e no ranking do conjunto de dados de benchmark.

Para o formato legado model-index em README.md, use EvalResult em vez disso.

Veja https://huggingface.co/docs/hub/eval-results para mais detalhes.

Exemplo:

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

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

Representa uma operação de sincronização a ser executada.

SyncPlan

classe huggingface_hub.SyncPlan

< >

( source: strdest: strtimestamp: stroperations: list = <factory> )

Representa um plano de sincronização completo.

CommitInfo

classe huggingface_hub.CommitInfo

< >

( commit_url: str*args**kwargs )

Parâmetros

  • commit_url (str) — URL onde encontrar o commit.
  • commit_message (str) — O resumo (primeira linha) do commit que foi criado.
  • commit_description (str) — Descrição do commit que foi criado. Pode estar vazio.
  • oid (str) — ID do hash do commit. Exemplo: "91c54ad1727ee830252e457677f467be0bfd8a57".
  • pr_url (str, opcional) — URL para o PR que foi criado, se houver. Preenchido quando create_pr=True é passado.
  • pr_revision (str, opcional) — Revisão do PR que foi criado, se houver. Preenchido quando create_pr=True é passado. Exemplo: "refs/pr/1".
  • pr_num (int, opcional) — Número da discussão de PR criada, se houver. Preenchido quando create_pr=True é passado. Pode ser passado como discussion_num em get_discussion_details(). Exemplo: 1.
  • repo_url (RepoUrl) — URL do repositório do commit contendo informações como repo_id, repo_type, etc.

Estrutura de dados contendo informações sobre um commit recém-criado.

Retornado por qualquer método que cria um commit no Hub: create_commit(), upload_file(), upload_folder(), delete_file(), delete_folder(). Ele herda de str por compatibilidade reversa, mas o uso de métodos específicos de str está obsoleto.

DatasetInfo

classe huggingface_hub.DatasetInfo

< >

( **kwargs )

Parâmetros

  • id (str) — ID do conjunto de dados.
  • author (str) — Autor do conjunto de dados.
  • card_data (DatasetCardData, opcional) — Metadados do Dataset Card como um objeto huggingface_hub.repocard_data.DatasetCardData.
  • citation (str, opcional) — Informações de citação do conjunto de dados.
  • created_at (datetime, opcional) — Data de criação do repositório no Hub. Observe que o menor valor é 2022-03-02T23:29:04.000Z, correspondente à data em que começamos a armazenar as datas de criação.
  • description (str, opcional) — Descrição do conjunto de dados.
  • disabled (bool, opcional) — Indica se o repositório está desativado.
  • downloads (int) — Número de downloads do conjunto de dados nos últimos 30 dias.
  • downloads_all_time (int) — Número acumulado de downloads do dataset desde sua criação.
  • gated (Literal["auto", "manual", False], opcional) — Indica se o repositório é restrito. Se for, especifica se a aprovação é manual ou automática.
  • last_modified (datetime, opcional) — Data do último commit no repositório.
  • likes (int) — Número de curtidas do conjunto de dados.
  • main_size (int, opcional) — Tamanho em bytes do ramo principal do conjunto de dados.
  • paperswithcode_id (str, opcional) — ID do Papers with code do conjunto de dados.
  • private (bool) — Indica se o repositório é privado.
  • resource_group (dict, opcional) — Informações do grupo de recursos para o conjunto de dados.
  • sha (str) — SHA do repositório nesta revisão específica.
  • siblings (list[RepoSibling]) — Lista de objetos huggingface_hub.hf_api.RepoSibling que constituem o conjunto de dados.
  • tags (list[str]) — Lista de tags do conjunto de dados.
  • trending_score (int, opcional) — Pontuação de tendência do conjunto de dados.
  • used_storage (int, opcional) — Tamanho em bytes do conjunto de dados no Hub.

Contém informações sobre um dataset no Hub. Este objeto é retornado por dataset_info() e list_datasets().

A maioria dos atributos desta classe é opcional. Isso ocorre porque os dados retornados pelo Hub dependem da consulta feita. Em geral, quanto mais específica for a consulta, mais informações serão retornadas. Por outro lado, ao listar conjuntos de dados usando list_datasets(), apenas um subconjunto dos atributos é retornado.

DryRunFileInfo

classe huggingface_hub.DryRunFileInfo

< >

( commit_hash: strfile_size: int | Nonefilename: strlocal_path: stris_cached: boolwill_download: bool )

Parâmetros

  • commit_hash (str) — O commit_hash relacionado ao arquivo.
  • file_size (int, opcional) — Tamanho do arquivo, se conhecido. No caso de um arquivo LFS, contém o tamanho do arquivo LFS real, não o do ponteiro.
  • filename (str) — Nome do arquivo no repositório.
  • is_cached (bool) — Indica se o arquivo já está em cache localmente.
  • will_download (bool) — Indica se o arquivo será baixado quando hf_hub_download for chamado com dry_run=False. Na prática, will_download é True se o arquivo não estiver em cache ou se force_download=True.

Informações retornadas ao executar uma simulação de download de arquivo.

Retornado por hf_hub_download() quando dry_run=True.

DuplicatedRepoUrl

classe huggingface_hub.DuplicatedRepoUrl

< >

( url: Anyendpoint: str | None = None )

Parâmetros

  • files_copy_pending (bool) — True se os arquivos LFS/Xet do novo repositório ainda estão sendo copiados em segundo plano. Até que a cópia seja concluída, o download desses arquivos pode falhar.

RepoUrl retornado por duplicate_repo().

GitRefInfo

classe huggingface_hub.GitRefInfo

< >

( name: strref: strtarget_commit: str )

Parâmetros

  • name (str) — Nome da referência (por exemplo, nome da tag ou nome do branch).
  • ref (str) — Ref git completa no Hub (por exemplo, "refs/heads/main" ou "refs/tags/v1.0").
  • target_commit (str) — OID do commit de destino para a ref (por exemplo, "e7da7f221d5bf496a48136c0cd264e630fe9fcc8")

Contém informações sobre uma referência git para um repositório no Hub.

GitCommitInfo

classe huggingface_hub.GitCommitInfo

< >

( commit_id: strauthors: list[str]created_at: datetimetitle: strmessage: strformatted_title: str | Noneformatted_message: str | None )

Parâmetros

  • commit_id (str) — OID do commit (por exemplo, "e7da7f221d5bf496a48136c0cd264e630fe9fcc8")
  • authors (list[str]) — Lista de autores do commit.
  • created_at (datetime) — Data e hora em que o commit foi criado.
  • title (str) — Título do commit. Este é um valor de texto livre inserido pelos autores.
  • message (str) — Descrição do commit. Este é um valor de texto livre inserido pelos autores.
  • formatted_title (str) — Título do commit formatado como HTML. Retornado apenas se formatted=True estiver definido.
  • formatted_message (str) — Descrição do commit formatada como HTML. Retornada apenas se formatted=True estiver definido.

Contém informações sobre um commit git para um repositório no Hub. Consulte list_repo_commits() para mais detalhes.

GitRefs

classe huggingface_hub.GitRefs

< >

( branches: list[GitRefInfo]converts: list[GitRefInfo]tags: list[GitRefInfo]pull_requests: list[GitRefInfo] | None = None )

Parâmetros

  • branches (list[GitRefInfo]) — Uma lista de GitRefInfo contendo informações sobre os ramos do repositório.
  • converts (list[GitRefInfo]) — Uma lista de GitRefInfo contendo informações sobre refs de “convert” no repositório. Converts são refs usados (internamente) para enviar dados pré-processados em repositórios de Dataset.
  • tags (list[GitRefInfo]) — Uma lista de GitRefInfo contendo informações sobre as tags do repositório.
  • pull_requests (list[GitRefInfo], opcional) — Uma lista de GitRefInfo contendo informações sobre pull requests no repositório. Retornado apenas se include_prs=True estiver definido.

Contém informações sobre todas as referências git de um repositório no Hub.

Object é retornado por list_repo_refs().

InferenceProviderMapping

classe huggingface_hub.hf_api.InferenceProviderMapping

< >

( **kwargs )

KernelInfo

classe huggingface_hub.KernelInfo

< >

( **kwargs )

Parâmetros

  • id (str) — ID do repositório do kernel.
  • author (str, opcional) — Autor do repositório do kernel.
  • downloads (int, opcional) — Número de downloads do repositório do kernel nos últimos 30 dias.
  • gated (Literal["auto", "manual", False], opcional) — Indica se o repositório é restrito. Em caso afirmativo, especifica se a aprovação é manual ou automática.
  • last_modified (datetime, opcional) — Data do último commit no repositório.
  • likes (int, opcional) — Número de curtidas do repositório do kernel.
  • private (bool, opcional) — Indica se o repositório é privado.
  • sha (str, opcional) — SHA do repositório nesta revisão específica.

Contém informações sobre um repositório de kernel no Hub. Este objeto é retornado por kernel_info().

LFSFileInfo

classe huggingface_hub.hf_api.LFSFileInfo

< >

( **kwargs )

Parâmetros

  • file_oid (str) — ID do objeto SHA-256 do arquivo. Este é o identificador a ser passado ao excluir o arquivo permanentemente.
  • filename (str) — Nome de arquivo possível para o objeto LFS. Consulte a observação acima para mais informações.
  • oid (str) — OID do objeto LFS.
  • pushed_at (datetime) — Data em que o objeto LFS foi enviado para o repositório.
  • ref (str, opcional) — Ref para onde o objeto LFS foi enviado (se houver).
  • size (int) — Tamanho do objeto LFS.

Contém informações sobre um arquivo armazenado como LFS em um repositório no Hub.

Usado no contexto de listar e excluir permanentemente arquivos LFS de um repositório para liberar espaço. Veja list_lfs_files() e permanently_delete_lfs_files() para mais detalhes.

Os arquivos Git LFS são rastreados usando IDs de objeto SHA-256, em vez de caminhos de arquivo, para otimizar o desempenho. Essa abordagem é necessária porque um único objeto pode ser referenciado por múltiplos caminhos em diferentes commits, tornando impraticável a busca e a resolução dessas conexões. Consulte nossa documentação para saber como identificar qual(is) nome(s) de arquivo está(ão) associado(s) a cada SHA.

Exemplo:

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

classe huggingface_hub.ModelInfo

< >

( **kwargs )

Parâmetros

  • id (str) — ID do modelo.
  • author (str, opcional) — Autor do modelo.
  • base_models (list[str], opcional) — Lista de modelos base dos quais este modelo é derivado.
  • card_data (ModelCardData, opcional) — Metadados do Model Card como um objeto huggingface_hub.repocard_data.ModelCardData.
  • children_model_count (int, opcional) — Número de modelos filhos derivados deste modelo.
  • config (dict, opcional) — Configuração do modelo.
  • created_at (datetime, opcional) — Data de criação do repositório no Hub. Observe que o menor valor é 2022-03-02T23:29:04.000Z, correspondente à data em que começamos a armazenar as datas de criação.
  • disabled (bool, opcional) — Indica se o repositório está desativado.
  • downloads (int) — Número de downloads do modelo nos últimos 30 dias.
  • downloads_all_time (int) — Número acumulado de downloads do modelo desde sua criação.
  • eval_results (list[EvalResultEntry], opcional) — Resultados de avaliação do modelo.
  • gated (Literal["auto", "manual", False], opcional) — Indica se o repositório é restrito. Se for, especifica se a aprovação é manual ou automática.
  • gguf (dict, opcional) — Informações GGUF do modelo.
  • inference (Literal["warm"], opcional) — Status do modelo nos Inference Providers. Warm se o modelo for servido por pelo menos um provedor.
  • inference_provider_mapping (list[InferenceProviderMapping], opcional) — Uma lista de InferenceProviderMapping ordenada de acordo com a ordem dos provedores do usuário.
  • last_modified (datetime, opcional) — Data do último commit no repositório.
  • library_name (str, opcional) — Biblioteca associada ao modelo.
  • likes (int) — Número de curtidas do modelo.
  • mask_token (str, opcional) — Token de máscara usado pelo modelo.
  • model_index (dict, opcional) — Índice do modelo para avaliação.
  • pipeline_tag (str, opcional) — Tag de pipeline associada ao modelo.
  • private (bool) — Indica se o repositório é privado.
  • resource_group (dict, opcional) — Informações do grupo de recursos para o modelo.
  • safetensors (SafeTensorsInfo, opcional) — Informações do safetensors do modelo.
  • security_repo_status (dict, opcional) — Status do scan de segurança do modelo.
  • sha (str, opcional) — SHA do repositório nesta revisão específica.
  • siblings (list[RepoSibling]) — Lista de objetos huggingface_hub.hf_api.RepoSibling que constituem o modelo.
  • spaces (list[str], opcional) — Lista de espaços que usam o modelo.
  • tags (list[str]) — Lista de tags do modelo. Em comparação com card_data.tags, contém tags extras calculadas pelo Hub (p. ex., bibliotecas suportadas, arXiv do modelo).
  • transformers_info (TransformersInfo, opcional) — Informações específicas do Transformers (auto class, processor, etc.) associadas ao modelo.
  • trending_score (int, opcional) — Pontuação de tendência do modelo.
  • used_storage (int, opcional) — Tamanho em bytes do modelo no Hub.
  • widget_data (Any, opcional) — Dados do widget associados ao modelo.

Contém informações sobre um modelo no Hub. Este objeto é retornado por model_info() e list_models().

A maioria dos atributos desta classe é opcional. Isso ocorre porque os dados retornados pelo Hub dependem da consulta realizada. Em geral, quanto mais específica for a consulta, mais informações serão retornadas. Por outro lado, ao listar modelos usando list_models(), apenas um subconjunto dos atributos é retornado.

RepoSibling

classe huggingface_hub.hf_api.RepoSibling

< >

( rfilename: strsize: int | None = Noneblob_id: str | None = Nonelfs: BlobLfsInfo | None = None )

Parâmetros

  • rfilename (str) — nome do arquivo, relativo à raiz do repositório.
  • size (int, opcional) — O tamanho do arquivo, em bytes. Este atributo é definido quando o argumento files_metadata de repo_info() é definido como True. Caso contrário, é None.
  • blob_id (str, opcional) — O OID git do arquivo. Este atributo é definido quando o argumento files_metadata de repo_info() é definido como True. Caso contrário, é None.
  • lfs (BlobLfsInfo, opcional) — Metadados de LFS do arquivo. Este atributo é definido quando o argumento files_metadata de repo_info() é definido como True e o arquivo é armazenado com Git LFS. Caso contrário, é None.

Contém informações básicas sobre um arquivo de repositório dentro de um repositório no Hub.

Todos os atributos desta classe são opcionais, exceto rfilename. Isso ocorre porque apenas os nomes dos arquivos são retornados ao listar repositórios no Hub (com list_models(), list_datasets() ou list_spaces()). Se você precisar de mais informações, como tamanho do arquivo, id do blob ou detalhes do lfs, deve solicitá-las especificamente de um repositório por vez (usando model_info(), dataset_info() ou space_info()), pois isso impõe mais restrições ao servidor de backend para recuperá-las.

RepoFile

classe huggingface_hub.RepoFile

< >

( **kwargs )

Parâmetros

  • path (str) — caminho do arquivo relativo à raiz do repositório.
  • size (int) — O tamanho do arquivo, em bytes.
  • blob_id (str) — O OID git do arquivo.
  • lfs (BlobLfsInfo, opcional) — Metadados de LFS do arquivo.
  • xet_hash (str, opcional) — O hash Xet do arquivo.
  • last_commit (LastCommitInfo, opcional) — Metadados do último commit do arquivo. Definido apenas se list_repo_tree() e get_paths_info() forem chamados com expand=True.
  • security (BlobSecurityInfo, opcional) — Metadados do scan de segurança do arquivo. Definido apenas se list_repo_tree() e get_paths_info() forem chamados com expand=True.

Contém informações sobre um arquivo no Hub.

RepoUrl

classe huggingface_hub.RepoUrl

< >

( url: Anyendpoint: str | None = None )

Parâmetros

  • url (Any) — Valor de string da URL do repositório.
  • endpoint (str, opcional) — Endpoint do Hub. O padrão é https://huggingface.co.

Exceções

HfUriError

  • HfUriError — Se a URL não puder ser analisada (por exemplo, repositório canônico de segmento único ou repo_type desconhecido).

Subclasse de str que descreve uma URL de repositório no Hub.

RepoUrl é retornado por HfApi.create_repo. Ele herda de str para compatibilidade com versões anteriores. Na inicialização, a URL é analisada para preencher as propriedades:

  • endpoint (str)
  • namespace (str)
  • repo_name (str)
  • repo_id (str)
  • repo_type (Literal["model", "dataset", "space"])
  • url (str)

Exemplo:

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

classe huggingface_hub.utils.SafetensorsRepoMetadata

< >

( metadata: dict | Nonesharded: boolweight_map: dictfiles_metadata: dict )

Parâmetros

  • metadata (dict, opcional) — Os metadados contidos no arquivo ‘model.safetensors.index.json’, se ele existir. Preenchido apenas para modelos fragmentados.
  • sharded (bool) — Indica se o repositório contém um modelo fragmentado ou não.
  • weight_map (dict[str, str]) — Um mapa de todos os pesos. As chaves são os nomes dos tensores e os valores são os nomes dos arquivos que contêm os tensores.
  • files_metadata (dict[str, SafetensorsFileMetadata]) — Um mapa com os metadados de todos os arquivos. As chaves são os nomes dos arquivos e os valores são os metadados do arquivo correspondente, como um objeto SafetensorsFileMetadata.
  • parameter_count (dict[str, int]) — Um mapa com o número de parâmetros por tipo de dados. As chaves são os tipos de dados e os valores são o número de parâmetros desse tipo de dados.

Metadados para um repositório Safetensors.

Um repositório é considerado um repositório Safetensors se contiver, na raiz, um arquivo de pesos ‘model.safetensors’ (modelo não compartilhado) ou um arquivo de índice ‘model.safetensors.index.json’ (modelo fragmentado).

Esta classe é retornada por get_safetensors_metadata().

Para mais detalhes sobre o formato safetensors, consulte https://huggingface.co/docs/safetensors/index#format.

SafetensorsFileMetadata

classe huggingface_hub.utils.SafetensorsFileMetadata

< >

( metadata: dicttensors: dict )

Parâmetros

  • metadata (dict) — Os metadados contidos no arquivo.
  • tensors (dict[str, TensorInfo]) — A map of all tensors. Keys are tensor names and values are information about the corresponding tensor, as a TensorInfo object.
  • parameter_count (dict[str, int]) — Um mapa com o número de parâmetros por tipo de dados. As chaves são os tipos de dados e os valores são o número de parâmetros desse tipo de dados.

Metadados de um arquivo Safetensors hospedado no Hub.

Esta classe é retornada por parse_safetensors_file_metadata().

Para mais detalhes sobre o formato safetensors, consulte https://huggingface.co/docs/safetensors/index#format.

SpaceInfo

classe huggingface_hub.SpaceInfo

< >

( **kwargs )

Parâmetros

  • id (str) — ID do Space.
  • author (str, opcional) — Autor do Space.
  • card_data (SpaceCardData, opcional) — Metadados do Card do Space como um objeto huggingface_hub.repocard_data.SpaceCardData.
  • created_at (datetime, opcional) — Data de criação do repositório no Hub. Observe que o menor valor é 2022-03-02T23:29:04.000Z, correspondente à data em que começamos a armazenar as datas de criação.
  • datasets (list[str], opcional) — Lista de conjuntos de dados usados pelo Space.
  • disabled (bool, opcional) — Indica se o Space está desativado.
  • gated (Literal["auto", "manual", False], opcional) — Indica se o repositório é restrito. Se for, especifica se a aprovação é manual ou automática.
  • host (str, optional) — Host URL of the Space.
  • last_modified (datetime, opcional) — Data do último commit no repositório.
  • likes (int) — Número de curtidas do Space.
  • models (list[str], opcional) — Lista de modelos usados pelo Space.
  • private (bool) — Indica se o repositório é privado.
  • region (Literal["us", "eu"], opcional) — Região da nuvem em que o Space é armazenado.
  • resource_group (dict, opcional) — Informações do grupo de recursos do Space.
  • runtime (SpaceRuntime, opcional) — Informações de runtime do Space como um objeto huggingface_hub.hf_api.SpaceRuntime.
  • sdk (str, opcional) — SDK usado pelo Space.
  • sha (str, opcional) — SHA do repositório nesta revisão específica.
  • siblings (list[RepoSibling]) — Lista de objetos huggingface_hub.hf_api.RepoSibling que constituem o Space.
  • subdomain (str, opcional) — Subdomínio do Space.
  • tags (list[str]) — Lista de tags do Space.
  • trending_score (int, opcional) — Pontuação de tendência do Space.
  • used_storage (int, opcional) — Tamanho em bytes do Space no Hub.

Contém informações sobre um Space no Hub. Este objeto é retornado por space_info() e list_spaces().

A maioria dos atributos desta classe é opcional. Isso ocorre porque os dados retornados pelo Hub dependem da consulta realizada. Em geral, quanto mais específica for a consulta, mais informações serão retornadas. Por outro lado, ao listar espaços usando list_spaces(), apenas um subconjunto dos atributos é retornado.

SpaceSearchResult

classe huggingface_hub.SpaceSearchResult

< >

( data: dict )

Parâmetros

  • id (str) — ID do Space (por exemplo, "username/repo-name").
  • author (str) — Autor do Space.
  • title (str) — Título de exibição do Space.
  • emoji (str or None) — Emoji icon of the Space.
  • sdk (str ou None) — SDK usado pelo Space (por exemplo, "gradio", "docker", "static").
  • likes (int) — Número de curtidas.
  • private (bool) — Se o Space é privado.
  • tags (list[str] ou None) — Lista de tags.
  • runtime (SpaceRuntime ou None) — Informações de tempo de execução (etapa, hardware, etc.).
  • ai_short_description (str ou None) — Descrição curta gerada por IA.
  • ai_category (str ou None) — Categoria gerada por IA (por exemplo, "Image Generation").
  • semantic_relevancy_score (float ou None) — Pontuação de relevância semântica (0-1) em relação à consulta de pesquisa.
  • trending_score (int ou None) — Pontuação de tendência.

Um único resultado da API de pesquisa semântica do Spaces.

Retornado por HfApi.search_spaces().

TensorInfo

classe huggingface_hub.utils.TensorInfo

< >

( dtype: typing.Literal['F64', 'F32', 'F16', 'BF16', 'I64', 'I32', 'I16', 'I8', 'U8', 'U3', 'BOOL']shape: listdata_offsets: tuple )

Parâmetros

  • dtype (str) — O tipo de dados do tensor (“F64”, “F32”, “F16”, “BF16”, “I64”, “I32”, “I16”, “I8”, “U8”, “U3”, “BOOL”).
  • shape (list[int]) — A forma do tensor.
  • data_offsets (tuple[int, int]) — Os deslocamentos dos dados no arquivo como uma tupla [BEGIN, END].
  • parameter_count (int) — O número de parâmetros no tensor.

Informações sobre um tensor.

Para mais detalhes sobre o formato safetensors, consulte https://huggingface.co/docs/safetensors/index#format.

Usuário

classe huggingface_hub.User

< >

( **kwargs )

Parâmetros

  • username (str) — Nome do usuário no Hub (único).
  • fullname (str) — Nome completo do usuário.
  • avatar_url (str) — URL do avatar do usuário.
  • details (str, opcional) — Detalhes do usuário.
  • is_following (bool, opcional) — Indica se o usuário autenticado está seguindo este usuário.
  • is_pro (bool, opcional) — Se o usuário é um usuário pro.
  • num_models (int, opcional) — Número de modelos criados pelo usuário.
  • num_datasets (int, opcional) — Número de conjuntos de dados criados pelo usuário.
  • num_spaces (int, opcional) — Número de espaços criados pelo usuário.
  • num_discussions (int, opcional) — Número de discussões iniciadas pelo usuário.
  • num_papers (int, opcional) — Número de artigos autorizados pelo usuário.
  • num_upvotes (int, opcional) — Número de votos positivos recebidos pelo usuário.
  • num_likes (int, opcional) — Número de curtidas dadas pelo usuário.
  • num_following (int, opcional) — Número de usuários que este usuário segue.
  • num_followers (int, opcional) — Número de usuários que seguem este usuário.
  • orgs (lista de Organization) — Lista de organizações das quais o usuário faz parte.

Contém informações sobre um usuário no Hub.

UserLikes

classe huggingface_hub.UserLikes

< >

( user: strtotal: intdatasets: list[str]kernels: list[str]models: list[str]spaces: list[str] )

Parâmetros

  • user (str) — Nome do usuário para o qual buscamos as curtidas.
  • total (int) — Total number of likes.
  • datasets (list[str]) — Lista de datasets curtidos pelo usuário (como repo_ids).
  • kernels (list[str]) — Lista de kernels curtidos pelo usuário (como repo_ids).
  • models (list[str]) — Lista de modelos curtidos pelo usuário (como repo_ids).
  • spaces (list[str]) — Lista de espaços curtidos pelo usuário (como repo_ids).

Contém informações sobre as curtidas de um usuário no Hub.

WebhookInfo

classe huggingface_hub.WebhookInfo

< >

( id: strurl: str | Nonejob: JobSpec | Nonewatched: list[WebhookWatchedItem]domains: list[constants.WEBHOOK_DOMAIN_T]secret: str | Nonedisabled: bool )

Parâmetros

  • id (str) — ID do webhook.
  • url (str, opcional) — URL do webhook.
  • job (JobSpec, opcional) — Especificações do Job a ser acionado.
  • watched (list[WebhookWatchedItem]) — Lista de itens monitorados pelo webhook, veja WebhookWatchedItem.
  • domains (list[WEBHOOK_DOMAIN_T]) — Lista de domínios que o webhook está monitorando. Pode ser um de ["repo", "discussion"].
  • secret (str, opcional) — Segredo do webhook.
  • disabled (bool) — Se o webhook está desativado ou não.

Estrutura de dados contendo informações sobre um webhook.

Um dos parâmetros url ou job é especificado, mas não ambos.

WebhookWatchedItem

classe huggingface_hub.WebhookWatchedItem

< >

( type: Literal['bucket', 'dataset', 'model', 'org', 'space', 'user']name: str )

Parâmetros

  • type (Literal["bucket", "dataset", "model", "org", "space", "user"]) — Tipo do item a ser monitorado. Pode ser um de ["bucket", "dataset", "model", "org", "space", "user"].
  • name (str) — Nome do item a ser monitorado. Pode ser o nome de usuário, nome da organização, nome do modelo, nome do dataset, nome do space ou nome do bucket.

Estrutura de dados contendo informações sobre os itens observados por um webhook.

CommitOperation

Abaixo estão os valores suportados para CommitOperation():

classe huggingface_hub.CommitOperationAdd

< >

( path_in_repo: strpath_or_fileobj: str | pathlib.Path | bytes | typing.BinaryIO )

Parâmetros

  • path_in_repo (str) — Caminho de arquivo relativo no repositório, por exemplo: "checkpoints/1fec34a/weights.bin"
  • path_or_fileobj (str, Path, bytes, ou BinaryIO) — Um dos seguintes:
    • um caminho para um arquivo local (como str ou pathlib.Path) para upload
    • um buffer de bytes (bytes) contendo o conteúdo do arquivo a ser enviado
    • um “objeto de arquivo” (subclasse de io.BufferedIOBase), normalmente obtido com open(path, "rb"). Ele deve suportar os métodos seek() e tell().

Exceções

ValueError

  • ValueError — Se path_or_fileobj não for um dos tipos str, Path, bytes ou io.BufferedIOBase.
  • ValueError — Se path_or_fileobj for um str ou Path, mas não for um caminho para um arquivo existente.
  • ValueError — Se path_or_fileobj for um io.BufferedIOBase que não suporta tanto seek() quanto tell().

Estrutura de dados que contém as informações necessárias para enviar um arquivo para um repositório no Hub.

as_file

< >

( with_tqdm: bool = False )

Parâmetros

  • with_tqdm (bool, opcional, padrão False) — Se True, iterar sobre o objeto de arquivo exibirá uma barra de progresso. Funciona apenas se o objeto semelhante a arquivo for um caminho para um arquivo. Puros bytes e buffers não são suportados.

Um gerenciador de contexto que retorna um objeto semelhante a um arquivo, permitindo ler os dados subjacentes em path_or_fileobj.

Exemplo:

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

< >

( )

O conteúdo codificado em base64 de path_or_fileobj

Retorna: bytes

classe huggingface_hub.CommitOperationDelete

< >

( path_in_repo: stris_folder: typing.Union[bool, typing.Literal['auto']] = 'auto' )

Parâmetros

  • path_in_repo (str) — Caminho relativo do arquivo no repositório, por exemplo: "checkpoints/1fec34a/weights.bin" para um arquivo ou "checkpoints/1fec34a/" para uma pasta.
  • is_folder (bool ou Literal["auto"], opcional) — Se a Operação de Exclusão se aplica a uma pasta ou não. Se “auto”, o tipo do caminho (arquivo ou pasta) é inferido automaticamente verificando se o caminho termina com “/” (pasta) ou não (arquivo). Para definir explicitamente o tipo do caminho, você pode definir is_folder=True ou is_folder=False.

Estrutura de dados que contém as informações necessárias para excluir um arquivo ou uma pasta de um repositório no Hub.

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

Parâmetros

  • src_path_in_repo (str) — Caminho relativo no repositório do arquivo a ser copiado, por exemplo, "checkpoints/1fec34a/weights.bin".
  • path_in_repo (str) — Caminho de arquivo relativo no repositório para onde o arquivo será copiado, por exemplo, "checkpoints/1fec34a/weights_copy.bin".
  • src_revision (str, opcional) — A revisão git do arquivo a ser copiado. Pode ser qualquer revisão git válida. Padrão: a revisão do commit de destino.
  • src_repo_id (str, opcional) — O repositório de origem a ser copiado (por exemplo, "username/source-model"). Padrão: o repositório de destino (cópia intra-repositório).
  • src_repo_type (str, opcional) — O tipo do repositório de origem ("model", "dataset" ou "space"). Obrigatório quando src_repo_id está definido.

Estrutura de dados que contém as informações necessárias para copiar um arquivo em um repositório no Hub.

Arquivos LFS e arquivos comuns são suportados. Os arquivos LFS são copiados no servidor, enquanto os arquivos comuns são baixados e reenviados como parte do commit.

Cópias entre repositórios são suportadas ao definir src_repo_id e src_repo_type. Para cópias LFS entre repositórios, os objetos LFS são duplicados para o repositório de destino antes da criação do commit. Isso é tratado automaticamente por create_commit(). Observe que cópias entre repositórios funcionam apenas dentro da mesma região de armazenamento; a cópia entre regiões não é suportada.

Observação: você pode combinar um CommitOperationCopy e um CommitOperationDelete para renomear um arquivo LFS no Hub.

CommitScheduler

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

Parâmetros

  • repo_id (str) — O id do repositório para o qual o commit será feito.
  • folder_path (str ou Path) — Caminho para a pasta local a ser enviada regularmente.
  • every (int ou float, opcional) — O número de minutos entre cada commit. O padrão é 5 minutos.
  • path_in_repo (str, opcional) — Caminho relativo do diretório no repositório, por exemplo: "checkpoints/". O padrão é a pasta raiz do repositório.
  • repo_type (str, opcional) — O tipo do repositório para o qual o commit será feito. O padrão é model.
  • revision (str, opcional) — A revisão do repositório para a qual o commit será feito. O padrão é main.
  • private (bool, opcional) — Se deve tornar o repositório privado. Se None (padrão), o repositório será público, a menos que o padrão da organização seja privado. Este valor é ignorado se o repositório já existir.
  • token (str, opcional) — O token a ser usado para fazer commit no repositório. O padrão é o token salvo na máquina.
  • allow_patterns (list[str] ou str, opcional) — Se fornecido, apenas os arquivos que corresponderem a pelo menos um padrão serão enviados.
  • ignore_patterns (list[str] ou str, opcional) — Se fornecido, os arquivos que corresponderem a qualquer um dos padrões não serão enviados.
  • squash_history (bool, opcional) — Se deve comprimir o histórico do repositório após cada commit. O padrão é False. A compressão de commits é útil para evitar o declínio de desempenho no repositório quando ele cresce demais.
  • hf_api (HfApi, opcional) — O cliente HfApi a ser usado para fazer commit no Hub. Pode ser configurado com configurações personalizadas (user agent, token, …).

Agendador para enviar uma pasta local para o Hub em intervalos regulares (por exemplo, push para o hub a cada 5 minutos).

A maneira recomendada de usar o scheduler é utilizá-lo como um context manager. Isso garante que o scheduler seja corretamente interrompido e que o último commit seja acionado quando o script termina. O scheduler também pode ser interrompido manualmente com o método stop. Consulte o guia de upload para saber mais sobre como usá-lo.

Exemplo:

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

Exemplo usando um gerenciador de contexto:

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

< >

( )

Envie a pasta para o Hub e retorne as informações do commit.

Este método não deve ser chamado diretamente. Ele é executado em segundo plano pelo agendador, respeitando um mecanismo de fila para evitar commits concorrentes. Fazer uma chamada direta ao método pode levar a problemas de concorrência.

O comportamento padrão de push_to_hub é assumir uma pasta somente de acréscimo. Ele lista todos os arquivos na pasta e envia apenas os arquivos alterados. Se nenhuma alteração for encontrada, o método retorna sem commitar nada. Se você quiser alterar esse comportamento, pode herdar de CommitScheduler e sobrescrever esse método. Isso pode ser útil, por exemplo, para comprimir os dados juntos em um único arquivo antes de commitar. Para mais detalhes e exemplos, confira nosso guia de integração.

parar

< >

( )

Pare o agendador.

Um agendador parado não pode ser reiniciado. Principalmente para fins de testes.

disparador

< >

( )

Dispare um push_to_hub e retorne um futuro.

Este método é chamado automaticamente a cada every minutos. Você também pode chamá-lo manualmente para acionar um commit imediatamente, sem esperar pelo próximo commit agendado.

Update on GitHub

←Variáveis de ambiente CLI→