Retorna o nível atual do logger raiz do HuggingFace Hub.

O HuggingFace Hub possui os seguintes níveis de log:

• huggingface_hub.logging.CRITICAL, huggingface_hub.logging.FATAL
• huggingface_hub.logging.ERROR
• huggingface_hub.logging.WARNING, huggingface_hub.logging.WARN
• huggingface_hub.logging.INFO
• huggingface_hub.logging.DEBUG

Define o nível do logger raiz do HuggingFace Hub.

Define a verbosidade para logging.INFO.

Define a verbosidade para logging.DEBUG.

Define a verbosidade para logging.WARNING.

Define a verbosidade para logging.ERROR.

Desative a propagação das saídas de log da biblioteca. Observe que a propagação de logs é desativada por padrão.

Ative a propagação das saídas de log da biblioteca. Desative o manipulador padrão do HuggingFace Hub para evitar log duplicado, caso o logger raiz tenha sido configurado.

Retorna um logger com o nome especificado. Esta função não deve ser acessada diretamente pelos usuários da biblioteca.

>>> from huggingface_hub import logging

>>> logger = logging.get_logger(__name__)
>>> logging.set_verbosity_info()

Verifique se as barras de progresso estão desativadas globalmente ou para um grupo específico.

Esta função retorna se as barras de progresso estão desativadas para um grupo específico ou globalmente. Ela verifica primeiro a variável de ambiente HF_HUB_DISABLE_PROGRESS_BARS e, em seguida, as configurações programáticas.

Desative as barras de progresso globalmente ou para um grupo especificado.

Esta função atualiza o estado das barras de progresso com base em um nome de grupo. Se nenhum nome de grupo for fornecido, todas as barras de progresso são desativadas. A operação respeita a configuração da variável de ambiente HF_HUB_DISABLE_PROGRESS_BARS.

Funciona tanto como uma chamada regular quanto como um gerenciador de contexto: disable_progress_bars() # desativa até enable_progress_bars() with disable_progress_bars(): # desativa para o bloco, reativa na saída …

Ative as barras de progresso globalmente ou para um grupo especificado.

Esta função define as barras de progresso como habilitadas para o grupo especificado ou globalmente, caso nenhum grupo seja especificado. A operação está sujeita à configuração de ambiente HF_HUB_DISABLE_PROGRESS_BARS.

Defina a fábrica de cliente HTTP a ser usada pelo huggingface_hub.

A fábrica de clientes é um método que retorna um objeto httpx2.Client. Na primeira chamada para get_session(), a fábrica de clientes será usada para criar um novo objeto httpx2.Client que será compartilhado entre todas as chamadas feitas por huggingface_hub.

Isso pode ser útil se você estiver executando seus scripts em um ambiente específico que exija configuração personalizada (por exemplo, proxy ou certificados personalizados).

Use get_session() para obter um httpx2.Client corretamente configurado.

Obtenha um objeto httpx2.Client, usando a fábrica de transporte do usuário.

Este cliente é compartilhado entre todas as chamadas feitas por huggingface_hub. Portanto, você não deve fechá-lo manualmente.

Use set_client_factory() para personalizar o httpx2.Client.

Feche o httpx2.Client global usado pelo huggingface_hub.

Se um Client for fechado, ele será recriado na próxima chamada para get_session().

Pode ser útil, por exemplo, se um certificado SSL tiver sido atualizado.

Defina a fábrica de cliente HTTP assíncrono a ser usada pelo huggingface_hub.

A fábrica de clientes assíncronos é um método que retorna um objeto httpx2.AsyncClient. Isso pode ser útil se você estiver executando seus scripts em um ambiente específico que exija configuração personalizada (por exemplo, proxy ou certificações personalizadas). Use get_async_session() para obter um httpx2.AsyncClient configurado corretamente.

Diferentemente do httpx2.Client, que é compartilhado entre todas as chamadas feitas por huggingface_hub, o httpx2.AsyncClient não é compartilhado. Recomenda-se o uso de um gerenciador de contexto assíncrono para garantir que o cliente seja fechado corretamente quando o contexto for encerrado.

Retorna um objeto httpx2.AsyncClient, usando a fábrica de transporte do usuário.

Use set_async_client_factory() para personalizar o httpx2.AsyncClient.

Diferentemente do httpx2.Client, que é compartilhado entre todas as chamadas feitas por huggingface_hub, o httpx2.AsyncClient não é compartilhado. Recomenda-se o uso de um gerenciador de contexto assíncrono para garantir que o cliente seja fechado corretamente quando o contexto for encerrado.

Versão interna de response.raise_for_status() que refinará um possível HTTPError. A exceção lançada será uma instância de HfHubHTTPError.

Este helper é destinado a ser o método único para raise_for_status ao fazer uma chamada ao Hugging Face Hub.

Levanta quando a solicitação falhou:

• RepositoryNotFoundError Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe, porque repo_type não está definido corretamente ou porque o repositório é private e você não tem acesso.
• GatedRepoError Se o repositório existir, mas for restrito e o usuário não estiver na lista autorizada.
• RevisionNotFoundError Se o repositório existir, mas a revisão não puder ser encontrada.
• EntryNotFoundError Se o repositório existe, mas a entrada (por exemplo, o arquivo solicitado) não pôde ser encontrada.
• BadRequestError Se a solicitação falhou com um erro HTTP 400 BadRequest.
• HfHubHTTPError Se a solicitação falhou por um motivo não listado acima.

Indica se estamos no modo offline para o Hub.

Quando o modo offline está ativado, todas as solicitações HTTP feitas com get_session levantarão uma exceção OfflineModeIsEnabled.

from huggingface_hub import is_offline_mode

def list_files(repo_id: str):
    if is_offline_mode():
        ... # list files from local cache (degraded experience but still functional)
    else:
        ... # list files from Hub (complete experience)

HTTPError para ser herdada por qualquer erro HTTP personalizado lançado no HF Hub.

Qualquer HTTPError é convertido, no mínimo, em um HfHubHTTPError. Se alguma informação for enviada de volta pelo servidor, ela será adicionada à mensagem de erro.

Detalhes adicionados:

• ID da solicitação obtido dos cabeçalhos, na seguinte ordem de precedência: “X-Request-Id”, “X-Amzn-Trace-Id”, “X-Amz-Cf-Id”.
• Mensagem de erro do servidor do cabeçalho “X-Error-Message”.
• Mensagem de erro do servidor, caso possamos encontrá-la no corpo da resposta.

    import httpx2
    from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError

    response = get_session().post(...)
    try:
        hf_raise_for_status(response)
    except HfHubHTTPError as e:
        print(str(e)) # formatted message
        e.request_id, e.server_message # details returned by server

        # Complete the error message with additional information once it's raised
        e.append_to_message("
ate_commit` expects the repository to exist.")
        raise

Disparada ao tentar acessar uma URL do hf.co com um nome de repositório inválido, ou com o nome de um repositório privado ao qual o usuário não tem acesso.

>>> from huggingface_hub import model_info
>>> model_info("<non_existent_repository>")
(...)
huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. (Request ID: PvMw_VjBMjVdMz53WKIzP)

Repository Not Found for url: https://huggingface.co/api/models/%3Cnon_existent_repository%3E.
Please make sure you specified the correct `repo_id` and `repo_type`.
If the repo is private, make sure you are authenticated and your token has the required permissions.
Invalid username or password.

Disparada ao tentar acessar um repositório restrito para o qual o usuário não está na lista autorizada.

Observação: deriva de RepositoryNotFoundError para garantir compatibilidade reversa.

>>> from huggingface_hub import model_info
>>> model_info("<gated_repository>")
(...)
huggingface_hub.errors.GatedRepoError: 403 Client Error. (Request ID: ViT1Bf7O_026LGSQuVqfa)

Cannot access gated repo for url https://huggingface.co/api/models/ardent-figment/gated-model.
Access to model ardent-figment/gated-model is restricted and you are not in the authorized list.
Visit https://huggingface.co/ardent-figment/gated-model to ask for access.

Disparada ao tentar acessar uma URL do hf.co com um repositório válido, mas uma revisão inválida.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
(...)
huggingface_hub.errors.RevisionNotFoundError: 404 Client Error. (Request ID: Mwhe_c3Kt650GcdKEFomX)

Revision Not Found for url: https://huggingface.co/bert-base-cased/resolve/%3Cnon-existent-revision%3E/config.json.

Disparado por HfApi.resolve_revision() quando uma revisão não pode ser resolvida para um hash de commit: o Hub não pôde ser atingido (modo offline, erro de conexão, tempo limite, indisponibilidade do Hub, …) e nenhuma entrada correspondente foi encontrada no cache local.

Disparada por hf_raise_for_status quando o servidor retorna um erro HTTP 400.

>>> resp = httpx2.post("hf.co/api/check", ...)
>>> hf_raise_for_status(resp, endpoint_name="check")
huggingface_hub.errors.BadRequestError: Bad request for check endpoint: {details} (Request ID: XXX)

Disparado quando a entrada não é encontrada, seja localmente ou remotamente.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.RemoteEntryNotFoundError (...)
>>> hf_hub_download('bert-base-cased', '<non-existent-file>', local_files_only=True)
(...)
huggingface_hub.utils.errors.LocalEntryNotFoundError (...)

Disparada ao tentar acessar uma URL do hf.co com um repositório e uma revisão válidos, mas com um nome de arquivo inválido.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.EntryNotFoundError: 404 Client Error. (Request ID: 53pNl6M0MxsnG5Sw8JA6x)

Entry Not Found for url: https://huggingface.co/bert-base-cased/resolve/main/%3Cnon-existent-file%3E.

Disparada ao tentar acessar um arquivo ou snapshot que não está no disco quando a rede está desativada ou indisponível (problema de conexão). A entrada pode existir no Hub.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
(...)
huggingface_hub.errors.LocalEntryNotFoundError: Cannot find the requested files in the disk cache and outgoing traffic has been disabled. To enable hf.co look-ups and downloads online, set 'local_files_only' to False.

Disparado por snapshot_download() quando o Hub não pode ser acessado (offline, problema de conexão ou local_files_only=True) e o snapshot em cache é conhecido por estar incompleto: alguns arquivos listados na árvore em cache do repositório estão ausentes do snapshot local.

Esta é uma subclasse de LocalEntryNotFoundError para compatibilidade reversa.

O atributo snapshot_path contém o caminho para o snapshot local incompleto, permitindo que uma biblioteca a jusante localize os arquivos mais recentes em cache, mesmo que sejam conhecidos por serem incompletos.

Lançada por get_cached_repo_tree() quando não há uma listagem de árvore em cache para a revisão solicitada.

A listagem da árvore é preenchida como efeito colateral de snapshot_download().

Ocorrida quando uma solicitação é feita, mas a variável de ambiente HF_HUB_OFFLINE=1 está definida.

Envia telemetria que ajuda a rastrear o uso de diferentes bibliotecas do HF.

Esses dados de uso nos ajudam a depurar problemas e priorizar novos recursos. No entanto, entendemos que nem todos desejam compartilhar informações adicionais e respeitamos sua privacidade. Você pode desativar a coleta de telemetria definindo HF_HUB_DISABLE_TELEMETRY=1 como variável de ambiente. A telemetria também é desativada no modo offline (ou seja, ao definir HF_HUB_OFFLINE=1).

A coleta de telemetria é executada em uma thread separada para minimizar o impacto para o usuário.

>>> from huggingface_hub.utils import send_telemetry

# Send telemetry without library information
>>> send_telemetry("ping")

# Send telemetry to subtopic with library information
>>> send_telemetry("gradio/local_link", library_name="gradio", library_version="3.22.1")

# Send telemetry with additional data
>>> send_telemetry(
...     topic="examples",
...     library_name="transformers",
...     library_version="4.26.0",
...     user_agent={"pipeline": "text_classification", "framework": "flax"},
... )

Valide os valores recebidos como argumento para qualquer método público de huggingface_hub.

O objetivo deste decorador é harmonizar a validação de argumentos reutilizados em todos os lugares. Por padrão, todos os validadores definidos são testados.

Validadores:

• validate_repo_id(): repo_id deve ser "repo_name" ou "namespace/repo_name". Namespace é um nome de usuário ou uma organização.
• ~utils.smoothly_deprecate_legacy_arguments: Ignore proxies ao baixar arquivos (deve ser definido globalmente).

>>> from huggingface_hub.utils import validate_hf_hub_args

>>> @validate_hf_hub_args
... def my_cool_method(repo_id: str):
...     print(repo_id)

>>> my_cool_method(repo_id="valid_repo_id")
valid_repo_id

>>> my_cool_method("other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

>>> my_cool_method(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Exceção genérica lançada pelos validadores do huggingface_hub.

Herdado de ValueError.

Valide se repo_id é válido.

Isso não tem a intenção de substituir a validação adequada feita no Hub, mas sim de evitar inconsistências locais sempre que possível (exemplo: passar repo_type no repo_id é proibido).

Regras:

• Entre 1 e 96 caracteres.
• Ou “repo_name” ou “namespace/repo_name”
• [a-zA-Z0-9] ou ”-”, ”_”, ”.”
• "—" e ".." são proibidos

Válido: "foo", "foo/bar", "123", "Foo-BAR_foo.bar123"

Não válido: "datasets/foo/bar", ".repo_id", "foo--bar", "foo.git"

>>> from huggingface_hub.utils import validate_repo_id
>>> validate_repo_id(repo_id="valid_repo_id")
>>> validate_repo_id(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Discutido em https://github.com/huggingface/huggingface_hub/issues/1008. Em moon-landing (repositório interno):

• https://github.com/huggingface/moon-landing/blob/main/server/lib/Names.ts#L27
• https://github.com/huggingface/moon-landing/blob/main/server/views/components/NewRepoForm/NewRepoForm.svelte#L138

Descontinuar suavemente os argumentos legados na base de código do huggingface_hub.

Esta função ignora alguns argumentos obsoletos dos kwargs e avisa o usuário de que eles estão sendo ignorados. O objetivo é evitar a quebra de código existente, ao mesmo tempo em que orienta o usuário para a nova maneira de fazer as coisas.

Lista de argumentos obsoletos:

• proxies: Para configurar proxies, o usuário deve usar a variável de ambiente HTTP_PROXY ou configurar manualmente o httpx2.Client usando a função set_client_factory().

  No huggingface_hub 0.x, proxies era um dicionário passado diretamente para requests.request. Desde o huggingface_hub 1.x, proxies por solicitação não são mais suportados. Em particular, não é possível configurar proxies em base por solicitação. A solução é configurá-los globalmente usando a função set_client_factory() ou usando a variável de ambiente HTTP_PROXY.

  Para mais detalhes, consulte:

  • https://httpx2.pydantic.dev/advanced/proxies/

• resume_download: descontinuado sem substituto. huggingface_hub sempre retoma downloads sempre que possível.

• force_filename: descontinuado sem substituto. O nome do arquivo é sempre o mesmo do Hub.

• local_dir_use_symlinks: descontinuado sem substituto. O download para um diretório local não usa mais links simbólicos.