Retourner le niveau actuel du journal racine du HuggingFace Hub.

Le HuggingFace Hub dispose des niveaux de journalisation suivants :

• 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

Définit le niveau du journal racine du HuggingFace Hub.

Définit le niveau de verbosité sur logging.INFO.

Définit le niveau de verbosité sur logging.DEBUG.

Définit le niveau de verbosité sur logging.WARNING.

Définit le niveau de verbosité sur logging.ERROR.

Désactiver la propagation des journaux de la bibliothèque. Notez que la propagation des journaux est désactivée par défaut.

Activez la propagation des journaux de la bibliothèque. Veuillez désactiver le gestionnaire par défaut du HuggingFace Hub pour éviter la double journalisation si le journal racine a été configuré.

Retourne un journal avec le nom spécifié. Cette fonction n'est pas censée être accédée directement par les utilisateurs de la bibliothèque.

>>> from huggingface_hub import logging

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

Vérifiez si les barres de progression sont désactivées globalement ou pour un groupe spécifique.

Cette fonction renvoie si les barres de progression sont désactivées pour un groupe donné ou de manière globale. Elle vérifie d'abord la variable d'environnement HF_HUB_DISABLE_PROGRESS_BARS, puis les paramètres programmés.

Désactivez les barres de progression, soit globalement, soit pour un groupe spécifié.

Cette fonction met à jour l’état des barres de progression en fonction d’un nom de groupe. Si aucun nom de groupe n’est fourni, toutes les barres de progression sont désactivées. L’opération respecte le paramètre de la variable d’environnement HF_HUB_DISABLE_PROGRESS_BARS.

Fonctionne à la fois comme un appel classique et comme un gestionnaire de contexte : disable_progress_bars() # désactive jusqu'à enable_progress_bars() with disable_progress_bars(): # désactive pour le bloc, réactive à la sortie …

Activez les barres de progression, soit globalement, soit pour un groupe spécifié.

Cette fonction active les barres de progression pour le groupe spécifié ou de manière globale si aucun groupe n’est spécifié. L’opération est soumise au paramètre d’environnement HF_HUB_DISABLE_PROGRESS_BARS.

Définissez la fabrique de client HTTP à utiliser par huggingface_hub.

La fabrique de client est une méthode qui renvoie un objet httpx2.Client. Lors du premier appel à get_session(), la fabrique de client est utilisée pour créer un nouvel objet httpx2.Client qui sera partagé entre tous les appels effectués par huggingface_hub.

Cela peut s’avérer utile si vous exécutez vos scripts dans un environnement spécifique nécessitant une configuration personnalisée (par exemple, un proxy ou des certificats personnalisés).

Utilisez get_session() pour obtenir un httpx2.Client correctement configuré.

Obtenez un objet httpx2.Client en utilisant la fabrique de transport de l'utilisateur.

Ce client est partagé entre tous les appels effectués par huggingface_hub. Vous ne devez donc pas le fermer manuellement.

Utilisez set_client_factory() pour personnaliser le httpx2.Client.

Fermer le httpx2.Client global utilisé par huggingface_hub.

Si un Client est fermé, il sera recréé lors de l'appel suivant à get_session().

Peut s'avérer utile si, par exemple, un certificat SSL a été mis à jour.

Définissez la fabrique de client HTTP asynchrone à utiliser par huggingface_hub.

La fabrique de client asynchrone est une méthode qui renvoie un objet httpx2.AsyncClient. Cela peut être utile si vous exécutez vos scripts dans un environnement spécifique nécessitant une configuration personnalisée (par exemple, un proxy ou des certificats personnalisés). Utilisez get_async_session() pour obtenir un httpx2.AsyncClient correctement configuré.

Contrairement au httpx2.Client qui est partagé entre tous les appels effectués par huggingface_hub, le httpx2.AsyncClient ne l’est pas. Il est recommandé d’utiliser un gestionnaire de contexte asynchrone pour s’assurer que le client est correctement fermé lorsque le contexte est quitté.

Retourner un objet httpx2.AsyncClient en utilisant la fabrique de transport de l'utilisateur.

Utilisez set_async_client_factory() pour personnaliser le httpx2.AsyncClient.

Contrairement au httpx2.Client qui est partagé entre tous les appels effectués par huggingface_hub, le httpx2.AsyncClient ne l’est pas. Il est recommandé d’utiliser un gestionnaire de contexte asynchrone pour s’assurer que le client est correctement fermé lorsque le contexte est quitté.

Version interne de response.raise_for_status() qui affinera une éventuelle HTTPError. L'exception levée sera une instance de HfHubHTTPError.

Cet utilitaire est conçu pour être la méthode unique pour raise_for_status lors de l’appel au Hugging Face Hub.

Lève une exception si la requête a échoué :

• RepositoryNotFoundError Si le dépôt à partir duquel le téléchargement doit être effectué ne peut pas être trouvé. Cela peut être dû au fait qu’il n’existe pas, que repo_type n’est pas défini correctement, ou que le dépôt est private et que vous n’y avez pas accès.
• GatedRepoError Si le dépôt existe mais est protégé et que l’utilisateur ne figure pas sur la liste des utilisateurs autorisés.
• RevisionNotFoundError Si le dépôt existe mais que la révision n’a pas pu être trouvée.
• EntryNotFoundError Si le dépôt existe mais que l’entrée (par exemple le fichier demandé) n’a pas pu être trouvée.
• BadRequestError Si la requête a échoué avec une erreur HTTP 400 BadRequest.
• HfHubHTTPError Si la requête a échoué pour une raison non listée ci-dessus.

Indique si nous sommes en mode hors ligne pour le Hub.

Lorsque le mode hors ligne est activé, toutes les requêtes HTTP effectuées avec get_session lèvent une exception 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 à hériter pour toute erreur HTTP personnalisée levée dans HF Hub.

Any HTTPError is converted at least into a HfHubHTTPError. If some information is sent back by the server, it will be added to the error message.

Détails ajoutés :

• L’identifiant de requête est extrait des en-têtes dans l’ordre de priorité suivant : “X-Request-Id”, “X-Amzn-Trace-Id”, “X-Amz-Cf-Id”.
• Message d'erreur du serveur issu de l'en-tête « X-Error-Message ».
• Message d'erreur du serveur si nous en trouvons un dans le corps de la réponse.

    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

Lévé lors de la tentative d'accès à une URL hf.co avec un nom de dépôt invalide, ou avec le nom d'un dépôt privé auquel l'utilisateur n'a pas accès.

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

Lévé lors de la tentative d'accès à un dépôt protégé pour lequel l'utilisateur ne figure pas sur la liste des personnes autorisées.

Note : dérive de RepositoryNotFoundError pour garantir la rétrocompatibilité.

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

Lévé lors de la tentative d'accès à une URL hf.co avec un dépôt valide mais une révision invalide.

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

Lévé par HfApi.resolve_revision() lorsqu'une révision ne peut pas être résolue en hachage de commit : le Hub n'a pas pu être atteint (mode hors ligne, erreur de connexion, délai d'attente, indisponibilité du Hub, …) et aucune entrée correspondante n'a été trouvée dans le cache local.

Lévé par hf_raise_for_status lorsque le serveur renvoie une erreur 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)

Lévé lorsque l'entrée n'est pas trouvée, que ce soit localement ou à distance.

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

Lévé lors de la tentative d'accès à une URL hf.co avec un dépôt et une révision valides, mais un nom de fichier invalide.

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

Lévé lors de la tentative d'accès à un fichier ou à un instantané qui n'est pas présent sur le disque lorsque le réseau est désactivé ou indisponible (problème de connexion). L'entrée peut exister sur le 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.

Lévé par snapshot_download() lorsque le Hub est inaccessible (hors ligne, problème de connexion ou local_files_only=True) et que le snapshot en cache est connu pour être incomplet : certains fichiers répertoriés dans l’arborescence en cache du dépôt sont absents du snapshot local.

Ceci est une sous-classe de LocalEntryNotFoundError pour la compatibilité ascendante.

L'attribut snapshot_path contient le chemin vers le snapshot local incomplet, permettant ainsi à une bibliothèque en aval de localiser les fichiers mis en cache les plus récents, même s'ils sont connus pour être incomplets.

Lévé par get_cached_repo_tree() lorsqu'aucune liste d'arborescence n'est mise en cache pour la révision demandée.

L'arborescence est remplie en tant qu'effet secondaire de snapshot_download().

Lévé lorsqu'une requête est effectuée mais que la variable d'environnement HF_HUB_OFFLINE=1 est définie.

Envoie des données de télémétrie qui aident à suivre l'utilisation des différentes bibliothèques HF.

Ces données d’utilisation nous aident à déboguer les problèmes et à prioriser les nouvelles fonctionnalités. Toutefois, nous comprenons que tout le monde ne souhaite pas partager d’informations supplémentaires et nous respectons votre vie privée. Vous pouvez désactiver la collecte de télémétrie en définissant HF_HUB_DISABLE_TELEMETRY=1 en tant que variable d’environnement. La télémétrie est également désactivée en mode hors ligne (c’est-à-dire lorsque HF_HUB_OFFLINE=1 est défini).

La collecte de télémétrie est exécutée dans un thread séparé afin de minimiser l'impact pour l'utilisateur.

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

Valider les valeurs reçues en argument pour toute méthode publique de huggingface_hub.

L'objectif de ce décorateur est d'harmoniser la validation des arguments réutilisés partout. Par défaut, tous les validateurs définis sont testés.

Validateurs :

• validate_repo_id() : repo_id doit être "repo_name" ou "namespace/repo_name". L'espace de noms est un nom d'utilisateur ou une organisation.
• ~utils.smoothly_deprecate_legacy_arguments : Ignorer proxies lors du téléchargement de fichiers (devrait être défini globalement).

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

Exception générique levée par les validateurs de huggingface_hub.

Hérite de ValueError.

Valider que repo_id est valide.

Ceci ne vise pas à remplacer la validation appropriée effectuée sur le Hub, mais plutôt à éviter les incohérences locales dans la mesure du possible (exemple : passer repo_type dans repo_id est interdit).

Règles :

• Entre 1 et 96 caractères.
• Soit « repo_name », soit « namespace/repo_name »
• [a-zA-Z0-9] ou ”-”, ”_”, ”.”
• « — » et « .. » sont interdits

Valide : "foo", "foo/bar", "123", "Foo-BAR_foo.bar123"

Non valide : "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'.

Discuté dans https://github.com/huggingface/huggingface_hub/issues/1008. Dans moon-landing (dépôt interne) :

• 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

Déprécier en douceur les arguments obsolètes dans la base de code huggingface_hub.

Cette fonction ignore certains arguments obsolètes présents dans les kwargs et avertit l'utilisateur qu'ils sont ignorés. L'objectif est d'éviter de casser le code existant tout en guidant l'utilisateur vers la nouvelle méthode.

Liste des arguments obsolètes :

• proxies : Pour configurer les proxys, l’utilisateur doit soit utiliser la variable d’environnement HTTP_PROXY, soit configurer manuellement le httpx2.Client à l’aide de la fonction set_client_factory().

  Dans huggingface_hub 0.x, proxies était un dictionnaire transmis directement à requests.request. Depuis huggingface_hub 1.x, les proxies par requête ne sont plus prises en charge. En particulier, il n'est plus possible de configurer les proxys au niveau de chaque requête. La solution consiste à le configurer globalement à l'aide de la fonction set_client_factory() ou en utilisant la variable d'environnement HTTP_PROXY.

  Pour plus de détails, voir :

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

• resume_download : obsolète sans remplacement. huggingface_hub reprend toujours les téléchargements lorsque c'est possible.

• force_filename : obsolète sans remplacement. Le nom de fichier est toujours identique à celui du Hub.

• local_dir_use_symlinks : obsolète sans remplacement. Le téléchargement vers un répertoire local n'utilise plus de liens symboliques.