diff --git a/docs/source/fr/guides/cli.md b/docs/source/fr/guides/cli.md deleted file mode 100644 index f18e3fe743..0000000000 --- a/docs/source/fr/guides/cli.md +++ /dev/null @@ -1,478 +0,0 @@ - - -# Invite de commande (CLI) - -Le module Python `huggingface_hub` offre un CLI intégré appelé `huggingface-cli`. Cet outil vous permet d'intéragir avec le Hub Hugging -Face directement depuis un terminal. Par exemple, vous pouvez vous connecter à votre compte, créer un dépot, upload/download des fichiers, etc. -Le CLI contient aussi des fonctionnalités pratiques pour configurer votre machine ou gérer votre cache. Dans ce guide, nous regarderons les -fonctionnalités principales du CLI et comment les utiliser. - - -## Installation - -Tout d'abord, installons le CLI: - -``` ->>> pip install -U "huggingface_hub[cli]" -``` - - - -Dans les snippet ci dessus, nous avons aussi installé les dépendances `[cli]` pour que vous ayez une meilleure expérience utilisateur, en particulier lors de l'utilisation de la commande `delete-cache`. - - - -Une fois cette première étape terminée, vous pouvez vérifier que le CLI est correctement installé : - -``` ->>> huggingface-cli --help -usage: huggingface-cli [] - -positional arguments: - {env,login,whoami,logout,repo,upload,download,lfs-enable-largefiles,lfs-multipart-upload,scan-cache,delete-cache} - huggingface-cli command helpers - env Print information about the environment. - login Log in using a token from huggingface.co/settings/tokens - whoami Find out which huggingface.co account you are logged in as. - logout Log out - repo {create} Commands to interact with your huggingface.co repos. - upload Upload a file or a folder to a repo on the Hub - download Download files from the Hub - lfs-enable-largefiles - Configure your repository to enable upload of files > 5GB. - scan-cache Scan cache directory. - delete-cache Delete revisions from the cache directory. - -options: - -h, --help show this help message and exit -``` - -Si le CLI est installé correctement, vous devriez voir une liste de toutes les options disponibles dans le CLI. Si vous obtenez un message d'erreur -tel que `command not found: huggingface-cli`, veuillez vous référer au guide disponible ici : [Installation](../installation) - - - -L'option `--help` est assez pratique pour obtenir plus de détails sur une commande. Vous pouvez l'utiliser n'importe quand pour lister toutes les options -disponibles et leur détail. Par exemple, `huggingface-cli upload --help` fournira des informations permettant d'upload des fichiers en utilisant le -CLI. - - - -## Connexion à huggingface-cli - -Dans la plupart des cas, vous devez être connectés à un compte Hugging Face pour intéragir avec le Hub (par exempel pour télécharger des dépôts privés, upload des fichiers, créer des pull requests, etc.). Pour ce faire, vous avez besoin d'un [token d'authentification](https://huggingface.co/docs/hub/security-tokens) généré depuis vos [paramètres](https://huggingface.co/settings/tokens). Ce token est utilisé pour authentifier votre identité au Hub. -Vérifiez bien que vous générez un token avec les accès write si vous voulez upload ou modifier du contenu. - -Une fois que vous avez votre token d'authentification, lancez la commande suivante dans votre terminal : - -```bash ->>> huggingface-cli login -``` - -Cette commande devrait vous demaner un token. Copiez-collez le vôtre et appuyez sur *Entrée*. Ensuite, le CLI devrait vous demander si le token -doit aussi être sauvegardé en tant que credential git. Appuyez sur *Entrée* encore (oui par défaut) si vous comptez utiliser `git` en local. -Enfin, le CLI vérifiera auprès du Hub si votre token est valide et l'enregistra en local. - -``` -_| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_| -_| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _| -_|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_| -_| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _| -_| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_| - -To login, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens . -Token: -Add token as git credential? (Y/n) -Token is valid (permission: write). -Your token has been saved in your configured git credential helpers (store). -Your token has been saved to /home/wauplin/.cache/huggingface/token -Login successful -``` - -Alternativement, si vous souhaitez vous connecter sans que le CLI vous demande quoi que ce soit, vous pouvez passer votre token directement depuis -l'invite de commande. Pour que le processus soit plus sécurisé, nous vous recommandons de mettre votre token dans une variable d'environnement -pour éviter de le laisser dans l'historique de votre invite de commande. - -```bash -# Utilisation d'une variable d'environnement ->>> huggingface-cli login --token $HUGGINGFACE_TOKEN --add-to-git-credential -Token is valid (permission: write). -Your token has been saved in your configured git credential helpers (store). -Your token has been saved to /home/wauplin/.cache/huggingface/token -Login successful -``` - -## huggingface-cli whoami - -Si vous voulez vérifier que vous êtes bien connecté, vous pouvez utiliser `huggingface-cli whoami`. Cette commande ne prend aucune option en entré et print votre nom d'utilisateur et l'organisation dont vous faites parti dans le Hub : - -```bash -huggingface-cli whoami -Wauplin -orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster -``` - -Si vous n'êtes pas connecté, un message d'erreur sera renvoyé. - -## huggingface-cli logout - -Cette commande vous déconnecte. En pratique, elle supprime le token enregistré sur votre machine. - -Cette commande ne vous déconnectera pas si vous vous êtes connecté en utilisant la variable d'environnement `HF_TOKEN` (voir [référence](../package_reference/environment_variables#hftoken)). Si c'est le cas, vous devez désactiver la variable dans les paramètres de votre machine. - -## huggingface-cli download - -Utilisez la commande `huggingface-cli download` pour télécharger des fichiers directement depuis le Hub. En arrière-plan, cette commande utilise -les mêmes helpers [`hf_hub_download`] et [`snapshot_download`] décrits dans le guide [Téléchargement](./download) et affiche le chemin -renvoyé dans le terminal. Dans les exemples ci-dessous, nous verrons les cas d'usage les plus communs. Pour afficher la liste des -options disponibles, vous pouvez lancer la commande: - -```bash -huggingface-cli download --help -``` - -### Télécharger un fichier - -Pour télécharger un unique fichier d'un dépôt, mettez le repo_id et le nom du fichier ainsi : - -```bash ->>> huggingface-cli download gpt2 config.json -downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o -(…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s] -/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json -``` - -La commande affichera toujours sur la dernière ligne le chemin vers le fichier. - -### Télécharger un dépôt entier - -Dans le cas où vous voudriez télécharger tous les fichier d'un dépôt, vous pouvez ne mettre que l'id du dépôt: - -```bash ->>> huggingface-cli download HuggingFaceH4/zephyr-7b-beta -Fetching 23 files: 0%| | 0/23 [00:00>> huggingface-cli download gpt2 config.json model.safetensors -Fetching 2 files: 0%| | 0/2 [00:00>> huggingface-cli download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"* -Fetching 8 files: 0%| | 0/8 [00:00>> huggingface-cli download HuggingFaceH4/ultrachat_200k --repo-type dataset - -# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat ->>> huggingface-cli download HuggingFaceH4/zephyr-chat --repo-type space - -... -``` - -### Télécharger une version spécifique - -Les exemples ci-dessus montrent comment télécharger le dernier commit sur la branche main. Pour télécharger une version spécifique (hash de commit, -nom de la branche ou tag), utilisez l'option `revision`: - -```bash ->>> huggingface-cli download bigcode/the-stack --repo-type dataset --revision v1.1 -... -``` - -### Télécharger vers un dossier local - -La manière recommandée (et appliquée par défaut) pour télécharger des fichiers depuis le Hub est d'utiliser le cache-system. Toutefois, dans certains cas, vous aurez besoin de télécharger des fichiers et de les déplacer dans un dossier spécifique. C'est utile pour avoir un fonctionnement proche de celui de git. Vous pouvez le faire en utilisant l'option `--local_dir`. - - - -Le téléchargement vers un chemin local a des désavantages. Veuillez vérifier les limitations dans le guide -[Téléchargement](./download#download-files-to-local-folder) avant d'utiliser `--local-dir`. - - - -```bash ->>> huggingface-cli download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir . -... -./model-00001-of-00002.safetensors -``` - -### Spécifier le chemin du cache - -Par défaut, tous les fichiers seront téléchargés dans le chemin du cache définit par la [variable d'environnement](../package_reference/environment_variables#hfhome) `HF_HOME`. Vous pouvez spécifier un cache personnalisé en utilisant `--cache-dir`: - -```bash ->>> huggingface-cli download adept/fuyu-8b --cache-dir ./path/to/cache -... -./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745 -``` - -### Préciser un token - -Pour avoir accès à des dépôts privés ou sécurisés, vous aurez besoin d'un token. Par défaut, le token enregistré en local -(lors de l'utilsation de `huggingface-cli login`) sera utilisé. Si vous voulez vous authentifier de manière explicite, utilisez l'option `--token`: - -```bash ->>> huggingface-cli download gpt2 config.json --token=hf_**** -/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json -``` - -### Mode silencieux - -Par défaut, la commande `huggingface-cli download` affichera des détails tels que des avertissements, des informations sur les fichiers téléchargés -et des barres de progression. Si vous ne voulez pas de ce type de message, utilisez l'option `--quiet`. Seule la dernière ligne (i.e. le chemin vers le fichier téléchargé) sera affiché. Ceci peut-être utile si vous voulez utiliser l'output d'une autre commande dans un script. - -```bash ->>> huggingface-cli download gpt2 --quiet -/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 -``` - -## huggingface-cli upload - -Utilisez la commande `huggingface-cli upload` pour upload des fichiers directement dans le Hub. En arrière plan, cette commande utilise les mêmes helpers -que [`upload_file`] et [`upload_folder`] décrits dans le guide [upload](./upload). Dans les exemples ci-dessous, nous verrons les cas d'utilisation les plus communs. -Pour une liste exhaustive des options disponibles, vous pouvez lancer: - -```bash ->>> huggingface-cli upload --help -``` - -### Upload un fichier - -L'utilisation par défaut de cette commande est: - -```bash -# Utilisation: huggingface-cli upload [repo_id] [local_path] [path_in_repo] -``` - -Pour upload le chemin actuel à la racine du dépôt, utilisez: - -```bash ->>> huggingface-cli upload mon-super-modele . . -https://huggingface.co/Wauplin/mon-super-modele/tree/main/ -``` - - - -Si le dépôt n'existe pas encore, il sera créé automatiquement. - - - -Vous pouvez aussi upload un dossier spécifique: - -```bash ->>> huggingface-cli upload mon-super-modele ./models . -https://huggingface.co/Wauplin/mon-super-modele/tree/main/ -``` -Enfin, vous pouvez upload un dossier dans une destination spécifique dans le dépot: - -```bash ->>> huggingface-cli upload mon-super-modele ./path/to/curated/data /data/train -https://huggingface.co/Wauplin/mon-super-modele/tree/main/data/train -``` - -### Upload un seul fichier - -Vous pouvez aussi upload un seul fichier en définissant `local_path` pour qu'il pointe vers ce fichier dans votre machine. Si c'est le cas, `path_in_repo` est optionnel et aura, comme valeur par défaut, le nom de votre fichier local: - -```bash ->>> huggingface-cli upload Wauplin/mon-super-modele ./models/model.safetensors -https://huggingface.co/Wauplin/mon-super-modele/blob/main/model.safetensors -``` - -Si vous voulez upload un seul fichier vers un chemin spécifique, choisissez `path_in_repo` de la bonne manière: - -```bash ->>> huggingface-cli upload Wauplin/mon-super-modele ./models/model.safetensors /vae/model.safetensors -https://huggingface.co/Wauplin/mon-super-modele/blob/main/vae/model.safetensors -``` - -### Upload plusieurs fichiers - -Pour upload plusieurs fichiers d'un coup depuis un dossier sans upload tout le dossier, vous pouvez utiliser `--include` et `--exclude`. Cette méthode peut aussi être combinée avec l'option `--delete` pour supprimer des fichiers du dépôt tout en uploadant les nouveaux fichiers. Dans l'exemple ci-dessous, nous synchronisons le space local en supprimant les fichiers distants et en uploadant tous les fichiers sauf ceux dans `/logs`: - -```bash -# Synchronisation du space local avec le Hub (upload des nouveaux fichier excepté ceux de logs/, supression des fichiers retirés) ->>> huggingface-cli upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Synchronisation du space local avec le Hub" -... -``` - -### Upload vers un dataset ou un space - -Pour upload vers un dataset ou un space, utilisez l'option `--repo-type`: - -```bash ->>> huggingface-cli upload Wauplin/mon-super-dataset ./data /train --repo-type=dataset -... -``` - -### Upload vers une organisation - -Pour upload du contenu vers un dépôt appartenant à une organisation aulieu d'un dépôt personnel, vous devez le spécifier explicitement dans le `repo_id`: - -```bash ->>> huggingface-cli upload MonOrganisation/mon-super-modele . . -https://huggingface.co/MonOrganisation/mon-super-modele/tree/main/ -``` - -### Upload vers une version spécifique - -Par défaut, les fichiers sont upload vers la branche `main`. Si vous voulez upload des fichiers vers une autre branche, utilisez l'option `--revision` - -```bash -# Upload des fichiers vers une pull request ->>> huggingface-cli upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104 -... -``` - -**Note:** Si la `revision` n'existe pas et que `--create-pr` n'est pas utilisé, une branche sera créé automatiquement à partir de la branche `main`. - -### Upload et créer une pull request - -Si vous n'avez pas la permission de push vers un dépôt, vous devez ouvrir une pull request et montrer aux propriétaires les changements que vous voulez faire. Vous pouvez le faire en utilisant l'option `--create-pr`: - -```bash -# Création d'une pull request et upload des fichiers dessus ->>> huggingface-cli upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104 -https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/ -``` - -### Upload a des intervalles réguliers - -Dans certains cas, vous aurez peut-être besoin de push des mise à jour régulières vers un dépôt. Par exemple, si vous entrainez un modèle et que vous voulez upload le fichier log toutes les dix minutes. Pour faire ceci, utilisez l'option `--every`: - -```bash -# Upload de nouveaux logs toutes les dix minutes -huggingface-cli upload training-model logs/ --every=10 -``` - -### Mettre un message de commit - -Utilisez les options `--commit-message` et `--commit-description` pour mettre votre propre message et description pour votre commit aulieu de ceux par défaut. - -```bash ->>> huggingface-cli upload Wauplin/mon-super-modele ./models . --commit-message="Epoch 34/50" --commit-description="Accuracy sur le set de validation : 68%, vérifiez le tensorboard pour plus de détails" -... -https://huggingface.co/Wauplin/mon-super-modele/tree/main -``` - -### Préciser un token - -Pour upload des fichiers, vous devez utiliser un token. Par défaut, le token enregistré en local (lors de l'utilisation de `huggingface-cli login`) sera utilisé. Si vous voulez vous authentifier de manière explicite, utilisez l'option `--token`: - -```bash ->>> huggingface-cli upload Wauplin/mon-super-modele ./models . --token=hf_**** -... -https://huggingface.co/Wauplin/mon-super-modele/tree/main -``` - -### Mode silencieux - -Par défaut, la commande `huggingface-cli upload` affichera des détails tels que des avertissements, des informations sur les fichiers téléchargés -et des barres de progression.Si vous ne voulez pas de ce type de message, utilisez l'option `--quiet`. Seule la dernière ligne (i.e. l'url vers le fichier uploadé) sera affiché. Cette option peut-être utile si vous voulez utiliser l'output d'une autre commande dans un script. - -```bash ->>> huggingface-cli upload Wauplin/mon-super-modele ./models . --quiet -https://huggingface.co/Wauplin/mon-super-modele/tree/main -``` - -## huggingface-cli scan-cache - -Scanner le chemin de votre cache peut être utile si vous voulez connaître les dépôts que vous avez téléchargé et l'espace qu'ils prennent sur votre disque. Vous pouvez faire ceci en utilisant `huggingface-cli scan-cache`: - -```bash ->>> huggingface-cli scan-cache -REPO ID REPO TYPE SIZE ON DISK NB FILES LAST_ACCESSED LAST_MODIFIED REFS LOCAL PATH ---------------------------- --------- ------------ -------- ------------- ------------- ------------------- ------------------------------------------------------------------------- -glue dataset 116.3K 15 4 days ago 4 days ago 2.4.0, main, 1.17.0 /home/wauplin/.cache/huggingface/hub/datasets--glue -google/fleurs dataset 64.9M 6 1 week ago 1 week ago refs/pr/1, main /home/wauplin/.cache/huggingface/hub/datasets--google--fleurs -Jean-Baptiste/camembert-ner model 441.0M 7 2 weeks ago 16 hours ago main /home/wauplin/.cache/huggingface/hub/models--Jean-Baptiste--camembert-ner -bert-base-cased model 1.9G 13 1 week ago 2 years ago /home/wauplin/.cache/huggingface/hub/models--bert-base-cased -t5-base model 10.1K 3 3 months ago 3 months ago main /home/wauplin/.cache/huggingface/hub/models--t5-base -t5-small model 970.7M 11 3 days ago 3 days ago refs/pr/1, main /home/wauplin/.cache/huggingface/hub/models--t5-small - -Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G. -Got 1 warning(s) while scanning. Use -vvv to print details. -``` - -Pour plus de détails sur comment scanner le chemin vers votre cache, consultez le guide [Gérez votre cache](./manage-cache#scan-cache-from-the-terminal). - -## huggingface-cli delete-cache - -`huggingface-cli delete-cache` est un outil qui vous permet de supprimer des parties de votre cache que vous n'utilisez plus. Cette commande permet de libérer de la mémoire disque. Pour en apprendre plus sur cette commande, consultez le guide [Gérez votre cache](./manage-cache#clean-cache-from-the-terminal). - -## huggingface-cli env - -La commande `huggingface-cli env` affiche des détails sur le setup de votre machine. C'est particulièrement utile si vous ouvrez une issue sur [GitHub](https://github.com/huggingface/huggingface_hub) pour aider les mainteneurs à enquêter sur vos problèmes. - -```bash ->>> huggingface-cli env - -Copy-and-paste the text below in your GitHub issue. - -- huggingface_hub version: 0.19.0.dev0 -- Platform: Linux-6.2.0-36-generic-x86_64-with-glibc2.35 -- Python version: 3.10.12 -- Running in iPython ?: No -- Running in notebook ?: No -- Running in Google Colab ?: No -- Token path ?: /home/wauplin/.cache/huggingface/token -- Has saved token ?: True -- Who am I ?: Wauplin -- Configured git credential helpers: store -- FastAI: N/A -- Tensorflow: 2.11.0 -- Torch: 1.12.1 -- Jinja2: 3.1.2 -- Graphviz: 0.20.1 -- Pydot: 1.4.2 -- Pillow: 9.2.0 -- hf_transfer: 0.1.3 -- gradio: 4.0.2 -- tensorboard: 2.6 -- numpy: 1.23.2 -- pydantic: 2.4.2 -- aiohttp: 3.8.4 -- ENDPOINT: https://huggingface.co -- HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub -- HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets -- HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token -- HF_HUB_OFFLINE: False -- HF_HUB_DISABLE_TELEMETRY: False -- HF_HUB_DISABLE_PROGRESS_BARS: None -- HF_HUB_DISABLE_SYMLINKS_WARNING: False -- HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False -- HF_HUB_DISABLE_IMPLICIT_TOKEN: False -- HF_HUB_ENABLE_HF_TRANSFER: False -- HF_HUB_ETAG_TIMEOUT: 10 -- HF_HUB_DOWNLOAD_TIMEOUT: 10 -``` \ No newline at end of file diff --git a/docs/source/fr/guides/collections.md b/docs/source/fr/guides/collections.md deleted file mode 100644 index c83cb5e4f7..0000000000 --- a/docs/source/fr/guides/collections.md +++ /dev/null @@ -1,230 +0,0 @@ - - -# Collections - -Une collection est un groupe d'objets reliés entre eux sur le Hub (par exemple des modèles, des datases, des spaces ou des articles) qui sont organisés ensemble sur la même page. Les collections sont utiles pour créer votre propre portefeuille de contenu, mettre du contenu dans des catégories ou présenter une liste précise d'objets que vous voulez partager. Consultez ce [guide](https://huggingface.co/docs/hub/collections) pour comprendre en détail ce que sont les collections et ce à quoi elles ressemblent sur le Hub. - -Vous pouvez gérer directement les collections depuis le navigateur, mais dans ce guide, nous nous concetrerons sur le code. - -## Afficher une collection - -Utiliser [`get_collection`] pour afficher vos collections ou n'importe quelle collection publique. Vous avez besoin du *slug* de la collection pour en récupérer une. Un slug est un identifiant pour une collection qui dépend du titre et de l'ID de la collection. Vous pouvez trouver le slug dans l'URL de la page dédiée à la collection. - -
- -
- -Affichons la collection qui a pour slug `"TheBloke/recent-models-64f9a55bb3115b4f513ec026"`: - -```py ->>> from huggingface_hub import get_collection ->>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026") ->>> collection -Collection( - slug='TheBloke/recent-models-64f9a55bb3115b4f513ec026', - title='Recent models', - owner='TheBloke', - items=[...], - last_updated=datetime.datetime(2023, 10, 2, 22, 56, 48, 632000, tzinfo=datetime.timezone.utc), - position=1, - private=False, - theme='green', - upvotes=90, - description="Models I've recently quantized. Please note that currently this list has to be updated manually, and therefore is not guaranteed to be up-to-date." -) ->>> collection.items[0] -CollectionItem( - item_object_id='651446103cd773a050bf64c2', - item_id='TheBloke/U-Amethyst-20B-AWQ', - item_type='model', - position=88, - note=None -) -``` - -L'objet [`Collection`] retourné par [`get_collection`] contient: -- Des métadonnées: `slug`, `owner`, `title`, `description`, etc. -- Une liste d'objets [`CollectionItem`]; chaque objet représente un modèle, un dataset, un space ou un article. - -Chaque objet d'une collection aura forcément: -- Un `item_object_id` unique: c'est l'id de l'objet de la collection dans la base de données -- Un `item_id`: c'est l'id dans le Hub de l'objet sous-jacent (modèle, dataset, space ou article); il n'est pas nécessairement unique, et seule la paire `item_id`/`item_type` sont uniques -- Un `item_type`: modèle, dataset, space ou article -- La `position` de l'objet dans la collection, qui peut-être mise à jour pour réorganiser votre collection (consultez [`update_collection_item`] ci dessous) - -Une note peut aussi être attachée à un objet. Cette note permet d'ajouter des informations supplémentaire sur l'objet (un commentaire, un lien vers le post d'un blog, etc.). L'attribut a toujours une valeur `None` si un objet n'a pas de note. - -En plus de ces attributs de base, les objets peuvent avoir des attributs supplémentaires en fonction de leur type: `author`, `private`, `lastModified`,`gated`, `title`, `likes`, `upvotes`, etc. Aucun de ces attribut ne sera retourné à coup sûr. - -## Lister les collections - -Vous pouvez aussi récupérer les collection en utilisant [`list_collections`]. Les collections peuvent être filtrées en utilisant certains paramètres. Listons toutes les collections de l'utilisateur [`teknium`](https://huggingface.co/teknium). -```py ->>> from huggingface_hub import list_collections - ->>> collections = list_collections(owner="teknium") -``` - -Ce code renvoie un itérable d'objets `Collection`. On peut itérer sur ce dernier pour afficher, par exemple, le nombre d'upvote de chaque collection. - -```py ->>> for collection in collections: -... print("Number of upvotes:", collection.upvotes) -Number of upvotes: 1 -Number of upvotes: 5 -``` - - - -Lorsque vous listez des collections, la liste d'objet est tronquée à 4 objets au maximum. Pour récupérer tous les objets d'une collection, vous devez utilisez [`get_collection`] - - - -Il est possible d'avoir un filtrage plus avancé. Obtenons toutes les collections contenant le modèle [TheBloke/OpenHermes-2.5-Mistral-7B-GGUF](https://huggingface.co/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF), triées par popularité, et en limitant au nombre de 5, le nombre de collections affichées. - -```py ->>> collections = list_collections(item="models/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF", sort="trending", limit=5): ->>> for collection in collections: -... print(collection.slug) -teknium/quantized-models-6544690bb978e0b0f7328748 -AmeerH/function-calling-65560a2565d7a6ef568527af -PostArchitekt/7bz-65479bb8c194936469697d8c -gnomealone/need-to-test-652007226c6ce4cdacf9c233 -Crataco/favorite-7b-models-651944072b4fffcb41f8b568 -``` - -Le paramètre `sort` doit prendre l'une des valeurs suivantes : `"last_modified"`, `"trending"` ou `"upvotes"`. Le paramètre `item` prend -n'importe quel objet. Par exemple: -* `"models/teknium/OpenHermes-2.5-Mistral-7B"` -* `"spaces/julien-c/open-gpt-rhyming-robot"` -* `"datasets/squad"` -* `"papers/2311.12983"` - -Pour plus de détails, consultez la référence à [`list_collections`]. - -## Créer une nouvelle collection - -Maintenant que nous savons comment avoir une [`Collection`], créons la nôtre! Utilisez [`create_collection`] avec un titre et une description. Pour créer une collection sur la page d'une organisation, passez `namespace=mon_organisation` lors de la création de la collection. Enfin, vous pouvez aussi créer des collections privées en passant `private=True` - -```py ->>> from huggingface_hub import create_collection - ->>> collection = create_collection( -... title="ICCV 2023", -... description="Portefeuille de modèles, articles et démes présentées à l'ICCV 2023 -... ) -``` - -Un objet [`Collection`] sera retourné avec les métadonnées (titre, description, propriétaire, etc.) et une liste vide d'objets. Vous pourrez ensuite vous référer à cette collection en utilisant son `slug`. - -```py ->>> collection.slug -'owner/iccv-2023-15e23b46cb98efca45' ->>> collection.title -"ICCV 2023" ->>> collection.owner -"username" ->>> collection.url -'https://huggingface.co/collections/owner/iccv-2023-15e23b46cb98efca45' -``` - -## Gérer des objets dans une collection - -Maintenant que nous avons notre [`Collection`], nous allons y ajouter des objets et les organiser. - -### Ajouter des objets - -Les objets doivent être ajoutés un par un en utilisant [`add_collection_item`]. Le seules données dont vous aurez besoin seront le `collection_slug`, l'`item_id` et l'`item_type`. En option, vous pouvez aussi ajouter une `note` à l'objet (500 caractères max). - -```py ->>> from huggingface_hub import create_collection, add_collection_item - ->>> collection = create_collection(title="OS Week Highlights - Sept 18 - 24", namespace="osanseviero") ->>> collection.slug -"osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" - ->>> add_collection_item(collection.slug, item_id="coqui/xtts", item_type="space") ->>> add_collection_item( -... collection.slug, -... item_id="warp-ai/wuerstchen", -... item_type="model", -... note="Würstchen is a new fast and efficient high resolution text-to-image architecture and model" -... ) ->>> add_collection_item(collection.slug, item_id="lmsys/lmsys-chat-1m", item_type="dataset") ->>> add_collection_item(collection.slug, item_id="warp-ai/wuerstchen", item_type="space") # même item_id, mais l'item_type est différent -``` - -Si un objet existe déjà dans une collection (même paire `item_id`/`item_type`), une erreur HTTP 409 sera levée. Vous pouvez ignorer cette erreur en passant `exists_ok=True` dans la fonction. - -### Ajouter une note à un objet de la collection - -Vous pouvez modifier un objet existant pour ajouter ou changer la note attachée à l'objet en utilisant [`update_collection_item`]. -Réutilisons l'exemple ci-dessus: - -```py ->>> from huggingface_hub import get_collection, update_collection_item - -# Récupère la collection avec les objets nouvellement ajoutés ->>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" ->>> collection = get_collection(collection_slug) - -# Ajoute une note au dataset `lmsys-chat-1m` ->>> update_collection_item( -... collection_slug=collection_slug, -... item_object_id=collection.items[2].item_object_id, -... note="This dataset contains one million real-world conversations with 25 state-of-the-art LLMs.", -... ) -``` - -### Remettre en ordre les objets - -Les objets dans une collection sont rangés dans un ordre. Cet ordre est déterminé par l'attribut `position` de chacun des objets. Par défaut, les objets sont triés dans l'ordre d'ajout (du plus ancien au plus récent). Vous pouvez mettre à jour cet ordre en utilisant [`update_collection_item`] de la même manière que vous ajouteriez unr note - -Réutilisons notre exemple ci-dessus: - -```py ->>> from huggingface_hub import get_collection, update_collection_item - -# Récupère la collection ->>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" ->>> collection = get_collection(collection_slug) - -# Change l'ordre pour mettre les deux objets `Wuerstchen` ensemble ->>> update_collection_item( -... collection_slug=collection_slug, -... item_object_id=collection.items[3].item_object_id, -... position=2, -... ) -``` - -### Supprimer des objets - -Enfin, vous pouvez aussi supprimer un objet en utilisant [`delete_collection_item`]. - -```py ->>> from huggingface_hub import get_collection, update_collection_item - -# Récupère la collection ->>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" ->>> collection = get_collection(collection_slug) - -# Supprime le space `coqui/xtts` de la liste ->>> delete_collection_item(collection_slug=collection_slug, item_object_id=collection.items[0].item_object_id) -``` - -## Supprimer une collection - -Une collection peut être supprimée en utilisant [`delete_collection`]. - - - -Cette action est irréversible. Une collection supprimée ne peut pas être restaurée. - - - -```py ->>> from huggingface_hub import delete_collection ->>> collection = delete_collection("username/useless-collection-64f9a55bb3115b4f513ec026", missing_ok=True) -``` \ No newline at end of file diff --git a/docs/source/fr/guides/community.md b/docs/source/fr/guides/community.md deleted file mode 100644 index 8afcbebe97..0000000000 --- a/docs/source/fr/guides/community.md +++ /dev/null @@ -1,153 +0,0 @@ - - -# Intéragir avec les discussions et les pull requests - -La librairie `huggingface_hub` fournir une interface Python pour intéragir avec les discussions et les pull requests du Hub. -Consultez [la page de documentation dédiée](https://huggingface.co/docs/hub/repositories-pull-requests-discussions) -pour un aperçu plus détaillé de ce que les discussions et les pull requests sur le Hub sont, et comment celles ci -fonctionnent en arrière plan. - -## Récupérer les discussions et les pull requests depuis le Hub - -La classe `HfApi` vous permet de récupérer des discussions et des pulls requests d'un dépôt: - -```python ->>> from huggingface_hub import get_repo_discussions ->>> for discussion in get_repo_discussions(repo_id="bigscience/bloom"): -... print(f"{discussion.num} - {discussion.title}, pr: {discussion.is_pull_request}") - -# 11 - Add Flax weights, pr: True -# 10 - Update README.md, pr: True -# 9 - Training languages in the model card, pr: True -# 8 - Update tokenizer_config.json, pr: True -# 7 - Slurm training script, pr: False -[...] -``` - -`HfApi.get_repo_discussions` vous permet de filtrer par auteur, type (pull request ou discussion), et statut (`open` ou `closed`): - - -```python ->>> from huggingface_hub import get_repo_discussions ->>> for discussion in get_repo_discussions( -... repo_id="bigscience/bloom", -... author="ArthurZ", -... discussion_type="pull_request", -... discussion_status="open", -... ): -... print(f"{discussion.num} - {discussion.title} by {discussion.author}, pr: {discussion.is_pull_request}") - -# 19 - Add Flax weights by ArthurZ, pr: True -``` - -`HfApi.get_repo_discussions` renvoie un [générateur](https://docs.python.org/3.7/howto/functional.html#generators) qui prend -en charge des objets [`Discussion`]. Pour avoir toutes les discussions dans une seul liste, lancez: - -```python ->>> from huggingface_hub import get_repo_discussions ->>> discussions_list = list(get_repo_discussions(repo_id="bert-base-uncased")) -``` - -L'objet [`Discussion`] retourné par [`HfApi.get_repo_discussions`] contient une vue d'ensemble de la discussion -ou la pull request. Vous pouvez aussi obtenir des informations plus détaillée en utilisant [`HfApi.get_discussion_details`]: - -```python ->>> from huggingface_hub import get_discussion_details - ->>> get_discussion_details( -... repo_id="bigscience/bloom-1b3", -... discussion_num=2 -... ) -DiscussionWithDetails( - num=2, - author='cakiki', - title='Update VRAM memory for the V100s', - status='open', - is_pull_request=True, - events=[ - DiscussionComment(type='comment', author='cakiki', ...), - DiscussionCommit(type='commit', author='cakiki', summary='Update VRAM memory for the V100s', oid='1256f9d9a33fa8887e1c1bf0e09b4713da96773a', ...), - ], - conflicting_files=[], - target_branch='refs/heads/main', - merge_commit_oid=None, - diff='diff --git a/README.md b/README.md\nindex a6ae3b9294edf8d0eda0d67c7780a10241242a7e..3a1814f212bc3f0d3cc8f74bdbd316de4ae7b9e3 100644\n--- a/README.md\n+++ b/README.md\n@@ -132,7 +132,7 [...]', -) -``` - -[`HfApi.get_discussion_details`] renvoie un objet [`DiscuccionWithDetails`], qui est une sous-classe de [`Discussion`] -contenant des informations plus détaillées sur la discussion ou la pull request. Ces informations contiennent tous les commentaires, -les changements de statut, et les changements de nom de la discussion via [`DiscussionWithDetails.events`]. - -En cas de pull request, vous pouvez récupérer la différence des versions git avec [`DiscussionWithDetails.diff`]. Tous les -commits de la pull request sont listés dans [`DiscussionWithDetails.events`]. - - -## Créer et changer une discussion ou une pull request par le code - -La classe [`HfApi`] fournit aussi des méthodes pour créer et d'éditer des discussions et -des pull requests. Vous aurez besoin d'un [token d'authentification](https://huggingface.co/docs/hub/security-tokens) -pour créer et modifier ces dernières. - -La manière la plus simple de proposer des changements sur un dépôt du Hub est d'utiliser l'API [`create_commit`]: -mettez simplement le paramètre `create_pr` à `True`. Ce paramètre est aussi disponible avec d'autres méthodes -autour de [`create_commit`] telles que: - - * [`upload_file`] - * [`upload_folder`] - * [`delete_file`] - * [`delete_folder`] - * [`metadata_update`] - -```python ->>> from huggingface_hub import metadata_update - ->>> metadata_update( -... repo_id="username/repo_name", -... metadata={"tags": ["computer-vision", "awesome-model"]}, -... create_pr=True, -... ) -``` - -Vous pouvez aussi utiliser [`HfApi.create_discussion`] (respectivement [`hfApi.create_pull_request`]) pour créer une discussion (respectivement une pull -request) sur un dépôt. Ouvrir une pull request de cette manière peut-être utile si vous avez besoin de travailler sur des changements en local. Les -pull requests ouvertes de cette manière seront en mode `"draft"`. - -```python ->>> from huggingface_hub import create_discussion, create_pull_request - ->>> create_discussion( -... repo_id="username/repo-name", -... title="Hi from the huggingface_hub library!", -... token="", -... ) -DiscussionWithDetails(...) - ->>> create_pull_request( -... repo_id="username/repo-name", -... title="Hi from the huggingface_hub library!", -... token="", -... ) -DiscussionWithDetails(..., is_pull_request=True) -``` - -La gestion des pull requests et des discussions peut être réalisée entièrement avec la classe [`HfApi`]. Par exemple, en utilisant: - - * [`comment_discussion`] pour ajouter des commentaires - * [`edit_discussion_comment`] pour modifier des commentaires - * [`rename_discussion`] pour renommer une discussion ou un pull request - * [`change_discussion_status`] pour ouvrir ou fermer une discussion ou une pull request - * [`merge_pull_request`] pour merge une pull request - - -Consultez la page de documentation [`HfApi`] pour une référence exhaustive de toutes les méthodes disponibles. - -## Push les changement vers une pull request - -*Arrive bientôt !* - -## Voir aussi - -Pour des références plus détaillées, consultez les pages de documentation [Discussions and Pull Requests](../package_reference/community) et [hf_api](../package_reference/hf_api). diff --git a/docs/source/fr/guides/hf_file_system.md b/docs/source/fr/guides/hf_file_system.md deleted file mode 100644 index 749ddc43ff..0000000000 --- a/docs/source/fr/guides/hf_file_system.md +++ /dev/null @@ -1,110 +0,0 @@ - - -# Intéragire avec le Hub à partir de l'API Filesystem - -En plus d'[`HfApi`], la librairie `huggingface_hub` fournit [`HfFileSystem`], une interface vers le Hub Hugging Face, basée sur Python, et [compatible fsspec](https://filesystem-spec.readthedocs.io/en/latest/). [`HfFileSystem`] fournit les opérations classiques des filesystem telles que -`cp`, `mv`, `ls`, `du`, `glob`, `get_file`, et `put_file`. - -## Utilisation - -```python ->>> from huggingface_hub import HfFileSystem ->>> fs = HfFileSystem() - ->>> # Liste tous les fichiers d'un chemin ->>> fs.ls("datasets/my-username/my-dataset-repo/data", detail=False) -['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv'] - ->>> # Liste tous les fichiers ".csv" d'un dépôt ->>> fs.glob("datasets/my-username/my-dataset-repo/**.csv") -['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv'] - ->>> # Lis un fichier distant ->>> with fs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f: -... train_data = f.readlines() - ->>> # Lis le contenu d'un fichier distant en renvoyant un string ->>> train_data = fs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev") - ->>> # Lis un fichier distant ->>> with fs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f: -... f.write("text,label") -... f.write("Fantastic movie!,good") -``` - -L'argument optionnel `revision` peut être passé pour exécuter une opération sur un commit spécifique en précisant la branche, le tag, ou le hash de commit. - -À la différence des fonction natives de Python `open`, la fonction `open` de `fsspec` est en mode binaire par défaut, `"rb"`. Ceci signifie que vous devez explicitement définir le mode à `"r"` pour lire et `"w"` pour écrire en mode texte. Les modes `"a"` et `"ab"` ne sont pas encore supportés. - -## Intégrations - -[`HfFileSystem`] peut être utilisé avec toutes les librairies qui intègrent `fsspec`, tant que l'URL a le schéma suivant: - -``` -hf://[][@]/ -``` - -Le `repo_type_prefix` vaut `datasets/` pour les datasets, `spaces/` pour les spaces, et les modèles n'ont pas besoin de préfixe dans l'URL. - -Ci-dessous quelques intégrations intéressantes où [`HfFileSystem`] simplifie l'intéraction avec le Hub: - -* Lire/modifier un dataframe [Pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#reading-writing-remote-files) depuis/vers un dépôt du Hub: - - ```python - >>> import pandas as pd - - >>> # Lis un fichier CSV distant en renvoyant un dataframe - >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv") - - >>> # Enregistre un dataframe vers un fichier CSV distant - >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv") - ``` - -Un workflow similaire peut-être utilisé pour les dataframes [Dask](https://docs.dask.org/en/stable/how-to/connect-to-remote-data.html) et [Polars](https://pola-rs.github.io/polars/py-polars/html/reference/io.html) - -* Requête afin d'obtenir des fichiers du Hub (distants) avec [DuckDB](https://duckdb.org/docs/guides/python/filesystems): - - ```python - >>> from huggingface_hub import HfFileSystem - >>> import duckdb - - >>> fs = HfFileSystem() - >>> duckdb.register_filesystem(fs) - >>> # Requête pour obtenir un fichier distant et récupérer les résultats sous forme de dataframe - >>> fs_query_file = "hf://datasets/my-username/my-dataset-repo/data_dir/data.parquet" - >>> df = duckdb.query(f"SELECT * FROM '{fs_query_file}' LIMIT 10").df() - ``` - -* Utilisation du Hub pour stocker des tableau avec [Zarr](https://zarr.readthedocs.io/en/stable/tutorial.html#io-with-fsspec): - - ```python - >>> import numpy as np - >>> import zarr - - >>> embeddings = np.random.randn(50000, 1000).astype("float32") - - >>> # Écriture d'un tableau vers un dépôt - >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w") as root: - ... foo = root.create_group("embeddings") - ... foobar = foo.zeros('experiment_0', shape=(50000, 1000), chunks=(10000, 1000), dtype='f4') - ... foobar[:] = embeddings - - >>> # Lecture d'un tableau depuis un dépôt - >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r") as root: - ... first_row = root["embeddings/experiment_0"][0] - ``` - -## Authentification - -Souvent, vous devrez être connecté avec un compte Hugging Face pour intéragir avec le Hub. Consultez la section [connexion](../quick-start#login) de la documentation pour en apprendre plus sur les méthodes d'authentification sur le Hub. - -Il est aussi possible de se connecter par le code en passant l'agument `token` à [`HfFileSystem`]: - -```python ->>> from huggingface_hub import HfFileSystem ->>> fs = HfFileSystem(token=token) -``` - -Si vous vous connectez de cette manière, faites attention à ne pas accidentellement révéler votre token en cas de partage du code source! diff --git a/docs/source/fr/guides/inference.md b/docs/source/fr/guides/inference.md deleted file mode 100644 index 1196b95231..0000000000 --- a/docs/source/fr/guides/inference.md +++ /dev/null @@ -1,344 +0,0 @@ - - -# Faire de l'inférence sur des serveurs - -L'inférence est le fait d'utiliser un modèle déjà entrainé pour faire des prédictions sur de nouvelles données. Comme ce -processus peut demander beaucoup de ressources computationnelles, le lancer sur un serveur dédié peut être une option -intéressante. La librairie `huggingface_hub` offre une manière facile d'appeler un service qui fait de l'inférence pour -les modèles hébergés. Il y a plusieurs services auxquels vous pouvez vous connecter: -- [Inference API](https://huggingface.co/docs/api-inference/index): un service qui vous permet de faire des inférences accélérées -sur l'infrastructure Hugging Face gratuitement. Ce service est une manière rapide de commencer, tester différents modèles et -créer des premiers prototypes de produits IA. --[Inference Endpoints](https://huggingface.co/inference-endpoints): un produit qui permet de déployer facilement des modèles en production. -L'inférence est assurée par Hugging Face dans l'infrastructure dédiée d'un cloud provider de votre choix. - -Ces services peuvent être appelés avec l'objet [`InferenceClient`]. Ce dernier remplace le client historique [`InferenceApi`], -en ajoutant plus de support pour les tâches et la gestion de l'inférence avec [Inference API](https://huggingface.co/docs/api-inference/index) and [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index). Apprenez comment migrer vers le nouveau client dans la section -[client historique InferenceAPI](#legacy-inferenceapi-client). - - - -[`InferenceClient`] est un client Python qui fait des appels HTTP à nos APIs. Si vous voulez faire des appels HTTP -directement en utilisant votre outil préféré (curl, postman,...), consultez les pages de documentation -d'[Inference API](https://huggingface.co/docs/api-inference/index) ou d'[Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) - - -Pour le développement web, un [JS client](https://huggingface.co/docs/huggingface.js/inference/README) a été créé. -Si vous êtes intéressés par le développement de jeu, consultez notre [projet C#](https://github.com/huggingface/unity-api). - - - -## Commencer avec les inférences - -Commençons avec du text-to-image: - -```python ->>> from huggingface_hub import InferenceClient ->>> client = InferenceClient() - ->>> image = client.text_to_image("An astronaut riding a horse on the moon.") ->>> image.save("astronaut.png") -``` - -Nous avons initialisé un [`InferenceClient`] avec les paramètres par défaut. La seule chose que vous avez besoin de savoir est la -[tâche](#supported-tasks) que vous voulez réaliser. Par défaut, le client se connectera à Inference API et sélectionnera un modèle -pour assurer la tâche. Dans notre exemple, nous avons généré une image depuis un prompt textuel. La valeur renvoyée est un objet -`PIL.image` qui peut être enregistré en tant que fichier. - - - -L'API est fait pour être simple. Cette paramètres et options ne sont pas disponibles pour l'utilisateur. Consultez -[cette page](https://huggingface.co/docs/api-inference/detailed_parameters) si vous voulez en apprendre plus sur -tous les paramètres disponibles pour chacune des tâches. - - - -### Utiliser un modèle spécifique - -Et si vous voulez utiliser un modèle spécifique? Vous pouvez le préciser soit en tant que paramètre ou directement -au niveau de l'instance: - -```python ->>> from huggingface_hub import InferenceClient -# Initialise le client pour un modèle spécifique ->>> client = InferenceClient(model="prompthero/openjourney-v4") ->>> client.text_to_image(...) -# Ou bien utiliser un client générique mais mettre son modèle en argument ->>> client = InferenceClient() ->>> client.text_to_image(..., model="prompthero/openjourney-v4") -``` - - - -Il y a plus de 200 000 modèles sur le HUb Hugging Face! Chaque tâche dans [`InferenceClient`] a un modèle recommandé -qui lui est assigné. Attention, les recommendantions HF peuvent changer du jour au lendemain sans avertissement préalable. -Par conséquent il vaut mieux définir explicitement un modèle une fois que vous l'avez choisi. En plus dans la plupart des -cas, vous aurez besoin d'un modèle qui colle à vos besoins spécifiques. Consultez la page [Models](https://huggingface.co/models) -sur le Hub pour explorer vos possibilités. - - - -### Utiliser un URL spécifique - -Les exemples vu ci dessis utilisent l'API hébergé gratuitement. Cette API est très utile pour les prototypes -et les tests agiles. Une fois que vous êtes prêts à déployer vos modèles en production, vous aurez besoin d'utiliser -des infrastructures dédiées. C'est là que les [enpoints d'inférence](https://huggingface.co/docs/inference-endpoints/index) -rentrent en jeu. Cet outil permet de déployer n'importe quel modèle et de l'exposer en tant que'API privé. Une fois déployé, -vous obtiendrez un URL auquel vous pouvez vous connecter en utilisant exactement le même code qu'avant, vous aurez juste -à changer le paramètre `model`: - -```python ->>> from huggingface_hub import InferenceClient ->>> client = InferenceClient(model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") -# ou bien ->>> client = InferenceClient() ->>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") -``` - -### Authentification - -Les appels faits avec le client [`InferenceClient`] peuvent passer par de l'authentification en utilisant un -[token d'authentification](https://huggingface.co/docs/hub/security-tokens). Par défaut, le token enregistré sur votre machine sera -utilisé si vous êtes connectés (consultez [comment se connecter](https://huggingface.co/docs/huggingface_hub/quick-start#login) -pour plus de détails). Si vous n'êtes pas connectés, vous pouvez passer votre token comme paramètre d'instance: - -```python ->>> from huggingface_hub import InferenceClient ->>> client = InferenceClient(token="hf_***") -``` - - - -L'authentification n'est PAS obligatoire lorsque que vous utilisez Inference API. Cependant, les utilisateur authentifiés -ont droit à un free-tier. Les tokens sont de plus obligatoires si vous voulez faire de l'inférence sur vos modèles privés -ou sur des endpoints privés. - - - -## Tâches supportés - -Le but d'[`InferenceClient`] est de fournir l'interface la plus simple possible pour faire de l'inférence -sur des modèles Hugging Face. Ce client possède une API simple qui supporte la plupart des tâches usuelles. -Voici une liste des tâches actuellement supportées: - -| Domaine | Tâche | Supporté | Documentation | -|--------|--------------------------------|--------------|------------------------------------| -| Audio | [Classification audio ](https://huggingface.co/tasks/audio-classification) | ✅ | [`~InferenceClient.audio_classification`] | -| | [Reconaissance vocal automatique](https://huggingface.co/tasks/automatic-speech-recognition)| ✅ | [`~InferenceClient.automatic_speech_recognition`] | -| | [Text-to-Speech](https://huggingface.co/tasks/text-to-speech) | ✅ | [`~InferenceClient.text_to_speech`] | -| Computer Vision | [Classification d'images](https://huggingface.co/tasks/image-classification) | ✅ | [`~InferenceClient.image_classification`] | -| | [Ségmentation d'images ](https://huggingface.co/tasks/image-segmentation) | ✅ | [`~InferenceClient.image_segmentation`] | -| | [Image-to-image](https://huggingface.co/tasks/image-to-image) | ✅ | [`~InferenceClient.image_to_image`] | -| | [Image-to-text](https://huggingface.co/tasks/image-to-text) | ✅ | [`~InferenceClient.image_to_text`] | -| | [Détection d'objets](https://huggingface.co/tasks/object-detection) | ✅ | [`~InferenceClient.object_detection`] | -| | [Text-to-image](https://huggingface.co/tasks/text-to-image) | ✅ | [`~InferenceClient.text_to_image`] | -| | [Classification d'image zero-shot](https://huggingface.co/tasks/zero-shot-image-classification)| ✅ |[`~InferenceClient.zero_shot_image_classification`]| -| Multimodal | [Réponse de questions liées à de la documentation](https://huggingface.co/tasks/document-question-answering) | ✅ | [`~InferenceClient.document_question_answering`] -| | [Réponse de questions visuelles](https://huggingface.co/tasks/visual-question-answering) | ✅ | [`~InferenceClient.visual_question_answering`] | -| NLP | [conversationnel](https://huggingface.co/tasks/conversational) | ✅ | [`~InferenceClient.conversational`] | -| | [Feature Extraction](https://huggingface.co/tasks/feature-extraction) | ✅ | [`~InferenceClient.feature_extraction`] | -| | [Fill Mask](https://huggingface.co/tasks/fill-mask) | ✅ | [`~InferenceClient.fill_mask`] | -| | [Réponse à des questions](https://huggingface.co/tasks/question-answering) | ✅ | [`~InferenceClient.question_answering`] -| | [Similarité de phrase](https://huggingface.co/tasks/sentence-similarity) | ✅ | [`~InferenceClient.sentence_similarity`] | -| | [Création de résumés](https://huggingface.co/tasks/summarization) | ✅ | [`~InferenceClient.summarization`] | -| | [Réponse de questions sous forme de tables](https://huggingface.co/tasks/table-question-answering) | ✅ | [`~InferenceClient.table_question_answering`] | -| | [Classification de texte](https://huggingface.co/tasks/text-classification) | ✅ | [`~InferenceClient.text_classification`] | -| | [Génération de texte](https://huggingface.co/tasks/text-generation) | ✅ | [`~InferenceClient.text_generation`] | -| | [Classification de tokens](https://huggingface.co/tasks/token-classification) | ✅ | [`~InferenceClient.token_classification`] | -| | [Traduction](https://huggingface.co/tasks/translation) | ✅ | [`~InferenceClient.translation`] | -| | [Classification zero-shot](https://huggingface.co/tasks/zero-shot-classification) | ✅ | [`~InferenceClient.zero_shot_classification`] | -| Tabular | [Classification tabulaire](https://huggingface.co/tasks/tabular-classification) | ✅ | [`~InferenceClient.tabular_classification`] | -| | [Régression Tabulaire](https://huggingface.co/tasks/tabular-regression) | ✅ | [`~InferenceClient.tabular_regression`] | - - - -Consultez la page de [Tâches](https://huggingface.co/tasks) pour en savoir plus sur chaque tâche, comment les utiliser -et les modèles les plus populaires pour chacune des tâches. - - - -## Requêtes personnalisées - -Toutefois, il n'est pas toujours possible de couvrir tous les cas d'usages avec ces tâches. Pour faire des requêtes -personnalisées, la méthode [`InferenceClient.post`] vous offre la flexibilité d'envoyer n'importe quelle requête à -l'API d'inférence. Par exemple, vous pouvez spécifier comment parser les entrées et les sorties. Dans l'exemple -ci-dessous, l'image générée est renvoyée en bytes aulieu d'être parsée en tant qu'`image PIL`. -Ceci peut s'avérer utile si vous n'avez pas `Pillow` d'installé sur votre machine et que vous voulez juste avoir -le contenu binaire de l'image. [`InferenceClient.post`] est aussi utile pour gérer les tâches qui ne sont pas -encore supportées officiellement - -```python ->>> from huggingface_hub import InferenceClient ->>> client = InferenceClient() ->>> response = client.post(json={"inputs": "An astronaut riding a horse on the moon."}, model="stabilityai/stable-diffusion-2-1") ->>> response.content # bytes -b'...' -``` - -## Client asynchrone - -Une version asynchrone du client est aussi fournie, basée sur `asyncio` et `aiohttp`. Vous avez le choix entre installer -`aiohttp` directmeent ou utiliser l'extra `[inference]`: - -```sh -pip install --upgrade huggingface_hub[inference] -# ou alors -# pip install aiohttp -``` - -Après l'installation, toutes les API asynchrones sont disponibles via [`AsyncInferenceClient`]. Son initialisation et -les APIs sont exactement les mêmes que sur la version synchrone. - -```py -# Le code doit tourner dans un contexte asyncio -# $ python -m asyncio ->>> from huggingface_hub import AsyncInferenceClient ->>> client = AsyncInferenceClient() - ->>> image = await client.text_to_image("An astronaut riding a horse on the moon.") ->>> image.save("astronaut.png") - ->>> async for token in await client.text_generation("The Huggingface Hub is", stream=True): -... print(token, end="") - a platform for sharing and discussing ML-related content. -``` - -Pour plus d'informations sur le module `asyncio`, consultez la [documentation officielle](https://docs.python.org/3/library/asyncio.html). - -## Astuces avancées - -Dans la section ci-dessus, nous avons vu les aspects principaux d' [`InferenceClient`]. Voyons maintenant les -astuces plus avanceées. - -### Timeout - -Lorsque vous faites de l'inférence, il y a deux causes principales qui causent un timeout: -- Le processus d'inférence prend beaucoup de temps à finir. -- Le modèle n'est pas disponible, par exemple quand Inference API charge le modèle pour la première fois. - -[`InferenceClient`] possède un paramètre global `timeout` qui gère ces deux aspects. Par défaut, il a pour valeur -`None`, ce qui signifie que le client attendra indéfiniment pour que l'inférence soit complète. Si vous voulez plus -de controle sur votre workflow, vous pouvez lui donner une valeur spécifique en secondes. Si le délai de timeout -expire, une erreur [`InferenceTimeoutError`] est levée. Vous pouvez la catch et la gérer dans votre code: - -```python ->>> from huggingface_hub import InferenceClient, InferenceTimeoutError ->>> client = InferenceClient(timeout=30) ->>> try: -... client.text_to_image(...) -... except InferenceTimeoutError: -... print("Inference timed out after 30s.") -``` - -### Entrée binaires - -Certaines tâches demandent des entrées binaire, par exemple, lorsque vous utilisez des images ou des fichiers audio. Dans -ce cas, [`InferenceClient`] essaye d'accepter différent types: -- Des`bytes` -- Un fichier, ouvert en tant que binaire (`with open("audio.flac", "rb") as f: ...`) -- un chemin (`str` ou `path`) qui pointe vers un fichier local -- Un URL (`str`) qui pointe vers un fichier distant (i.e. `https://...`). Dans ce cas là, le fichier sera téléchargé en local -avant d'être envoyé à l'API. - -```py ->>> from huggingface_hub import InferenceClient ->>> client = InferenceClient() ->>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg") -[{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...] -``` - -## Client historique InferenceAPI - -[`InferenceClient`] sert de remplacement pour l'approche historique [`InferenceApi`]. Il ajoute des supports spécifiques -pour des tâches et gère l'inférence avec [Inference API](https://huggingface.co/docs/api-inference/index) et [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index). - -Voici un guide très court qui vous aidera à migrer d'[`InferenceApi`] à [`InferenceClient`]. - -### Initialisation - -Remplacez - -```python ->>> from huggingface_hub import InferenceApi ->>> inference = InferenceApi(repo_id="bert-base-uncased", token=API_TOKEN) -``` - -par - -```python ->>> from huggingface_hub import InferenceClient ->>> inference = InferenceClient(model="bert-base-uncased", token=API_TOKEN) -``` - -### Réaliser une tâche spécifique - -Remplacez - -```python ->>> from huggingface_hub import InferenceApi ->>> inference = InferenceApi(repo_id="paraphrase-xlm-r-multilingual-v1", task="feature-extraction") ->>> inference(...) -``` - -Par - -```python ->>> from huggingface_hub import InferenceClient ->>> inference = InferenceClient() ->>> inference.feature_extraction(..., model="paraphrase-xlm-r-multilingual-v1") -``` - - - -C'est la méthode recommandée pour adapter votre code à [`InferenceClient`]. Elle vous permet de bénéficier des -méthodes spécifiques à une tâche telles que `feature_extraction`. - - - -### Faire un requête personnalisée - -Remplacez - -```python ->>> from huggingface_hub import InferenceApi ->>> inference = InferenceApi(repo_id="bert-base-uncased") ->>> inference(inputs="The goal of life is [MASK].") -[{'sequence': 'the goal of life is life.', 'score': 0.10933292657136917, 'token': 2166, 'token_str': 'life'}] -``` - -par - -```python ->>> from huggingface_hub import InferenceClient ->>> client = InferenceClient() ->>> response = client.post(json={"inputs": "The goal of life is [MASK]."}, model="bert-base-uncased") ->>> response.json() -[{'sequence': 'the goal of life is life.', 'score': 0.10933292657136917, 'token': 2166, 'token_str': 'life'}] -``` - -### INférence avec des paramètres - -Remplacez - -```python ->>> from huggingface_hub import InferenceApi ->>> inference = InferenceApi(repo_id="typeform/distilbert-base-uncased-mnli") ->>> inputs = "Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!" ->>> params = {"candidate_labels":["refund", "legal", "faq"]} ->>> inference(inputs, params) -{'sequence': 'Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!', 'labels': ['refund', 'faq', 'legal'], 'scores': [0.9378499388694763, 0.04914155602455139, 0.013008488342165947]} -``` - -par - -```python ->>> from huggingface_hub import InferenceClient ->>> client = InferenceClient() ->>> inputs = "Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!" ->>> params = {"candidate_labels":["refund", "legal", "faq"]} ->>> response = client.post(json={"inputs": inputs, "parameters": params}, model="typeform/distilbert-base-uncased-mnli") ->>> response.json() -{'sequence': 'Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!', 'labels': ['refund', 'faq', 'legal'], 'scores': [0.9378499388694763, 0.04914155602455139, 0.013008488342165947]} -``` diff --git a/docs/source/fr/guides/inference_endpoints.md b/docs/source/fr/guides/inference_endpoints.md deleted file mode 100644 index 9783c30282..0000000000 --- a/docs/source/fr/guides/inference_endpoints.md +++ /dev/null @@ -1,261 +0,0 @@ -# Inference Endpoints - -Inference Endpoints fournit une solution sécurisée viable pour la production pour déployer facilement n'importe quel modèle `transformers`, `sentence-transformers`, et `diffusers` sur une infrastructure dédiée et scalable gérée par Hugging Face. Un inference endpoint est construit à partir d'un modèle du [Hub](https://huggingface.co/models). -Dans ce guide, nous apprendront comment gérer les endpoints d'inférence par le code en utilisant `huggingface_hub`. Pour plus d'informations sur le produit lui même, consultez sa [documentation officielle](https://huggingface.co/docs/inference-endpoints/index). - -Ce guide suppose que vous avez installé `huggingface_hub` correctement et que votre machine est connectée. Consultez le [guide quick start](https://huggingface.co/docs/huggingface_hub/quick-start#quickstart) si ce n'est pas le cas. La version la plus ancienne supportant l'API d'inference endpoints est `v0.19.0`. - - -## Créez un inference endpoint - -La première étape pour créer un inference endpoint est d'utiliser [`create_inference_endpoint`]: - -```py ->>> from huggingface_hub import create_inference_endpoint - ->>> endpoint = create_inference_endpoint( -... "my-endpoint-name", -... repository="gpt2", -... framework="pytorch", -... task="text-generation", -... accelerator="cpu", -... vendor="aws", -... region="us-east-1", -... type="protected", -... instance_size="medium", -... instance_type="c6i" -... ) -``` - -Dans cet exemple, nous avons créé un inference endpoint de type `protected` qui a pour nom `"my-endpoint-name"`, il utilise [gpt2](https://huggingface.co/gpt2) pour faire de la génération de texte (`text-generation`). Le type `protected` signfie que votre token sera demandé pour accéder à l'API. Il faudra aussi fournir des informations supplémentaires pour préciser le hardware nécessaire, telles que le provider, la région, l'accélérateur, le type d'instance et la taille. Vous pouvez consulter la liste des ressources disponibles [ici](https://api.endpoints.huggingface.cloud/#/v2%3A%3Aprovider/list_vendors). Par ailleurs, vous pouvez aussi créer un inference endpoint manuellement en utilisant l'[interface web](https://ui.endpoints.huggingface.co/new) si c'est plus pratique pour vous. Consultez ce [guide](https://huggingface.co/docs/inference-endpoints/guides/advanced) pour des détails sur les paramètres avancés et leur utilisation. - -La valeur renvoyée par [`create_inference_endpoint`] est un objet [`InferenceEndpoint`]: - -```py ->>> endpoint -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) -``` - -C'est une dataclass qui contient des informations sur l'endpoint. Vous pouvez avoir accès à des attributs importants tels que `name`, `repository`, `status`, `task`, `created_at`, `updated_at`, etc. (respectivement le nom, le dépôt d'origine, le statut, la tâche assignée, la date de création et la date de dernière modification). Si vous en avez besoin, vous pouvez aussi avoir accès à la réponse brute du serveur avec `endpoint.raw`. - -Une fois que votre inference endpoint est créé, vous pouvez le retrouver sur votre [dashboard personnel](https://ui.endpoints.huggingface.co/). - -![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/huggingface_hub/inference_endpoints_created.png) - -#### Utiliser une image personnalisée - -Par défaut, l'inference endpoint est construit à partir d'une image docker fournie par Hugging Face. Cependant, il est possible de préciser n'importe quelle image docker en utilisant le paramètre `custom_image`. Un cas d'usage fréquent est l'utilisation des LLM avec le framework [text-generation-inference](https://github.com/huggingface/text-generation-inference). On peut le faire ainsi: - -```python -# Créé un inference endpoint utilisant le modèle Zephyr-7b-beta sur une TGI ->>> from huggingface_hub import create_inference_endpoint ->>> endpoint = 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="protected", -... instance_size="medium", -... instance_type="g5.2xlarge", -... custom_image={ -... "health_route": "/health", -... "env": { -... "MAX_BATCH_PREFILL_TOKENS": "2048", -... "MAX_INPUT_LENGTH": "1024", -... "MAX_TOTAL_TOKENS": "1512", -... "MODEL_ID": "/repository" -... }, -... "url": "ghcr.io/huggingface/text-generation-inference:1.1.0", -... }, -... ) -``` - -La valeur à passer dans `custom_image` est un dictionnaire contenant un url vers le conteneur docker et la configuration pour le lancer. Pour plus de détails, consultez la [documentation Swagger](https://api.endpoints.huggingface.cloud/#/v2%3A%3Aendpoint/create_endpoint). - -### Obtenir ou lister tous les endpoints d"inférence existants - -Dans certains cas, vous aurez besoin de gérer les endpoints d'inférence précédemment créés. Si vous connaissez leur nom, vous pouvez les récupérer en utilisant [`get_inference_endpoint`], qui renvoie un objet [`InferenceEndpoint`]. Sinon, vous pouvez utiliser [`list_inference_endpoints`] pour récupérer une liste de tous les endpoints d'inférence. Les deux méthodes acceptent en paramètre optionnel `namespace`. Vous pouvez mettre en `namespace` n'importe quelle organisation dont vous faites partie. Si vous ne renseignez pas ce paramètre, votre nom d'utilisateur sera utilisé par défaut. - -```py ->>> from huggingface_hub import get_inference_endpoint, list_inference_endpoints - -# Obtient un endpoint ->>> get_inference_endpoint("my-endpoint-name") -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) - -# Liste tous les endpoints d'une organisation ->>> list_inference_endpoints(namespace="huggingface") -[InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...] - -# Liste tous les endpoints de toutes les organisation dont l'utilisateur fait partie ->>> list_inference_endpoints(namespace="*") -[InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...] -``` - -## Vérifier le statut de déploiement - -Dans le reste de ce guide, nous supposons que nous possèdons un objet [`InferenceEndpoint`] appelé `endpoint`. Vous avez peut-être remarqué que l'endpoint a un attribut `status` de type [`InferenceEndpointStatus`]. Lorsque l'inference endpoint est déployé et accessible, le statut est `"running"` et l'attribut `url` est défini: - -```py ->>> endpoint -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') -``` - -Avant d'atteindre l'état `"running"`, l'inference endpoint passe généralement par une phase `"initializing"` ou `"pending"`. Vous pouvez récupérer le nouvel état de l'endpoint en lançant [`~InferenceEndpoint.fetch`]. Comme toutes les autres méthodes d'[`InferenceEndpoint`] qui envoient une requête vers le serveur, les attributs internes d'`endpoint` sont mutés: - -```py ->>> endpoint.fetch() -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) -``` - -Aulieu de récupérer le statut de l'inference endpoint lorsque vous attendez qu'il soit lancé, vous pouvez directement appeler -[`~InferenceEndpoint.wait`]. Cet helper prend en entrée les paramètres `timeout` et `fetch_every` (en secondes) et bloquera le thread jusqu'à ce que l'inference endpoint soit déployé. Les valeurs par défaut sont respectivement `None` (pas de timeout) et `5` secondes. - -```py -# Endpoint en attente ->>> endpoint -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) - -# Attend 10s puis lève une InferenceEndpointTimeoutError ->>> endpoint.wait(timeout=10) - raise InferenceEndpointTimeoutError("Timeout while waiting for Inference Endpoint to be deployed.") -huggingface_hub._inference_endpoints.InferenceEndpointTimeoutError: Timeout while waiting for Inference Endpoint to be deployed. - -# Attend plus longtemps ->>> endpoint.wait() -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') -``` - -Si `timeout` est définit et que l'inference endpoint prend trop de temps à charger, une erreur [`InferenceEndpointTimeouError`] est levée. - -## Lancer des inférences - -Une fois que votre inference endpoint est fonctionnel, vous pouvez enfin faire de l'inférence! - -[`InferenceEndpoint`] a deux propriétés `client` et `async_client` qui renvoient respectivement des objets [`InferenceClient`] et [`AsyncInferenceClient`]. - -```py -# Lance un tâche de génération de texte: ->>> endpoint.client.text_generation("I am") -' not a fan of the idea of a "big-budget" movie. I think it\'s a' - -# Ou dans un contexte asynchrone: ->>> await endpoint.async_client.text_generation("I am") -``` - -Si l'inference endpoint n'est pas opérationnel, une exception [`InferenceEndpointError`] est levée: - -```py ->>> endpoint.client -huggingface_hub._inference_endpoints.InferenceEndpointError: Cannot create a client for this Inference Endpoint as it is not yet deployed. Please wait for the Inference Endpoint to be deployed using `endpoint.wait()` and try again. -``` - -Pour plus de détails sur l'utilisation d'[`InferenceClient`], consultez le [guide d'inférence](../guides/inference). - -## Gérer les cycles de vie - - -Maintenant que nous avons vu comment créer un inference endpoint et faire de l'inférence avec, regardons comment gérer son cycle de vie. - - - -Dans cette section, nous verrons des méthodes telles que [`~InferenceEndpoint.pause`], [`~InferenceEndpoint.resume`], [`~InferenceEndpoint.scale_to_zero`], [`~InferenceEndpoint.update`] et [`~InferenceEndpoint.delete`]. Toutes ces méthodes sont des alias ajoutés à [`InferenceEndpoint`]. Si vous le préférez, vous pouvez aussi utiliser les méthodes génériques définies dans `HfApi`: [`pause_inference_endpoint`], [`resume_inference_endpoint`], [`scale_to_zero_inference_endpoint`], [`update_inference_endpoint`], et [`delete_inference_endpoint`]. - - - -### Mettre en pause ou scale à zéro - -Pour réduire les coûts lorsque votre inference endpoint n'est pas utilisé, vous pouvez choisir soit de le mettre en pause en utilisant [`~InferenceEndpoint.pause`] ou de réaliser un scaling à zéro en utilisant [`~InferenceEndpoint.scale_to_zero`]. - - - -Un inference endpoint qui est *en pause* ou *scalé à zéro* ne coute rien. La différence entre ces deux méthodes est qu'un endpoint *en pause* doit être *relancé* explicitement en utilisant [`~InferenceEndpoint.resume`]. A l'opposé, un endpoint *scalé à zéro* sera automatiquement lancé si un appel d'inférence est fait, avec un délai de "cold start" (temps de démarrage des instances) additionnel. Un inference endpoint peut aussi être configuré pour scale à zero automatiquement après une certaine durée d'inactivité. - - - -```py -# Met en pause et relance un endpoint ->>> endpoint.pause() -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='paused', url=None) ->>> endpoint.resume() -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) ->>> endpoint.wait().client.text_generation(...) -... - -# Scale à zéro ->>> endpoint.scale_to_zero() -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='scaledToZero', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') -# L'endpoint n'est pas en mode 'running' mais a tout de même un URL et sera relancé au premier call -``` - -### Mettre à jour le modèle ou le hardware de l'endpoint - -Dans certains cas, vous aurez besoin de mettre à jour votre inference endpoint sans en créer de nouveau. Vous avez le choix entre mettre à jour le modèle hébergé par l'endpoint ou le hardware utilisé pour faire tourner le modèle. Vous pouvez le faire en utilisant [`~InferenceEndpoint.update`]: - -```py -# Change le modèle utilisé ->>> endpoint.update(repository="gpt2-large") -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) - -# Met à jour le nombre de replicas ->>> endpoint.update(min_replica=2, max_replica=6) -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) - -# Met à jour la taille de l'instance ->>> endpoint.update(accelerator="cpu", instance_size="large", instance_type="c6i") -InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) -``` - -### Supprimer un endpoint - -Si vous n'utilisez plus un inference endpoint, vous pouvez simplement appeler la méthode [`~InferenceEndpoint.delete()`]. - - - -Cette action est irréversible et supprimera complètement l'endpoint, dont sa configuration, ses logs et ses métriques. Vous ne pouvez pas retrouver un inference endpoint supprimé. - - - - -## Exemple de A à Z - -Un cas d'usage typique d'Hugging Face pour les endpoints d'inférence est de gérer une liste de tâche d'un coup pour limiter les coûts en infrastructure. Vous pouvez automatiser ce processus en utilisant ce que nous avons vu dans ce guide: - -```py ->>> import asyncio ->>> from huggingface_hub import create_inference_endpoint - -# Lance un endpoint et attend qu'il soit initialisé ->>> endpoint = create_inference_endpoint(name="batch-endpoint",...).wait() - -# Fait des inféreces ->>> client = endpoint.client ->>> results = [client.text_generation(...) for job in jobs] - -# Ou bien avec asyncio ->>> async_client = endpoint.async_client ->>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs]) - -# Met en pause l'endpoint ->>> endpoint.pause() -``` - -Ou si votre inference endpoint existe et est en pause: - -```py ->>> import asyncio ->>> from huggingface_hub import get_inference_endpoint - -# Récupère l'endpoint et attend son initialisation ->>> endpoint = get_inference_endpoint("batch-endpoint").resume().wait() - -# Fait des inféreces ->>> async_client = endpoint.async_client ->>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs]) - -# Met en pause l'endpoint ->>> endpoint.pause() -``` \ No newline at end of file diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md deleted file mode 100644 index 3a8b6a93d9..0000000000 --- a/docs/source/fr/guides/integrations.md +++ /dev/null @@ -1,290 +0,0 @@ - - -# Intégrez n'importe quel framework de ML avec le Hub - -Le Hub Hugging face rend l'hébergement et le partage de modèles avec la communauté facile. -Il supporte des [dizaines de librairies](https://huggingface.co/docs/hub/models-libraries) -dans l'écosystem open source. Nous somme constamment entrain de travailler pour étendre ce support -afin de pousser vers l'avant le machine learning collaboratif. La librairie `huggingface_hub` joue un rôle -clé dans ce processus, ce qui permet à n'import quel script Python de push et télécharger des fichiers facilement. - -Il y a quatre manière principales d'intégrer une librairie avec le Hub: -1. **Push to Hub** implémente une méthode pour upload un modèle vers le Hub. Ceci inclus les poids du modèle, la - [carte du modèle](https://huggingface.co/docs/huggingface_hub/how-to-model-cards) et toute autre information - pertinente ou donnée nécessaire pour faire tourner modèle (par exemple, les logs d'entrainement). Cette méthode est - souvent appelée `push_to_hub()`. -2. **Download from Hub** implémente une méthode pour charger un modèlle depuis le Hub. La méthode doit télécharger la - configuration et les poids du modèle et charger le modèle. Cette méthode est souvent appelée `from_pretrained` ou - `load_from_hub()`. -3. **Inference API** utilise nos serveurs pour faire de l'inférence gratuitement sur des modèles supportés par votre librairie. -4. **Widgets** affiche un widget sur la page d'acceuil de votre modèle dans le Hub. Widgets permet aux utilisateur de rapidement -essayer un modèle depuis le navigateur. - -Dans ce guide, nous nous concentreront sur les deux premiers sujets. Nous présenterons les deux approches principales -que vous pouvez utiliser pour intégrer une librairie, avec leur avantages et leur défauts. Tout est résumé à la fin du guide -pour vous aider à choisir entre les deux. Veuillez garder à l'esprit que ce ne sont que des conseils, vous êtes libres de -les adapter à votre cas d'usage. - -Si Inferenc API et Widgets vous intéressent, vous pouvez suivre [ce guide](https://huggingface.co/docs/hub/models-adding-libraries#set-up-the-inference-api). -Dans les deux cas, vous pouvez nous contacter si vous intégrez une librairie au HUb et que vous voulez apparaître -[dans notre documentation](https://huggingface.co/docs/hub/models-libraries). - -## Une approche flexible: les helpers - -La première approche pour intégrer une librairie au Hub est d'implémenter les méthodes `push_to_hub` et `from_pretrained` -vous même. Ceci vous donne une flexibilité totale sur le choix du fichier que vous voulez upload/download et sur comment -gérer les inputs spécifiques à votre framework. Vous pouvez vous référer aux guides : [upload des fichiers](./upload) -et [télécharger des fichiers](./download) pour en savoir plus sur la manière de faire. C'est de cette manière que l'intégration -de FastAI est implémentée par exemple (voir [`push_to_hub_fastai`] et [`from_pretrained_fastai`]). - -L'implémentation peut varier entre différentes librairies, mais le workflow est souvent similaire. - -### from_pretrained - -Voici comment une méthode `from_pretrained` fonctionne d'habitude: - -```python -def from_pretrained(model_id: str) -> MyModelClass: - # Téléchargement du modèles depuis le Hub - cached_model = hf_hub_download( - repo_id=repo_id, - filename="model.pkl", - library_name="fastai", - library_version=get_fastai_version(), - ) - - # Chargement du modèle - return load_model(cached_model) -``` - -### push_to_hub - -La méthode `push_to_hub` demande souvent un peu plus de complexité pour gérer la création du dépôt, générer le modèle et enregistrer les poids. -Une approche commune est de sauvegarder tous ces fichiers dans un dossier temporaire, les upload et ensuite les supprimer. - -```python -def push_to_hub(model: MyModelClass, repo_name: str) -> None: - api = HfApi() - - # Créez d'un dépôt s'il n'existe pas encore, et obtenez le repo_id associé - repo_id = api.create_repo(repo_name, exist_ok=True) - - # Sauvegardez tous les fichiers dans un chemin temporaire, et pushez les en un seul commit - with TemporaryDirectory() as tmpdir: - tmpdir = Path(tmpdir) - - # Sauvegardez les poids - save_model(model, tmpdir / "model.safetensors") - - # Générez le chemin du modèle - card = generate_model_card(model) - (tmpdir / "README.md").write_text(card) - - # Sauvegardez les logs - # Sauvegardez le métriques d'évaluation - # ... - - # Pushez vers le Hub - return api.upload_folder(repo_id=repo_id, folder_path=tmpdir) -``` - -Ceci n'est qu'un exemple. Si vous êtes intéressés par des manipulations plus complexes (supprimer des fichiers distants, -upload des poids à la volée, maintenir les poids localement, etc.) consultez le guide [upload des fichiers](./upload) - -### Limitations - -Bien que très flexible, cette approche a quelques défauts, particulièrement en terme de maintenance. Les utilisateurs -d'Hugging Face sont habitués à utiliser des fonctionnalités lorsqu'ils travaillent avec `huggingface_hub`. Par exemple, -lors du chargement de fichiers depuis le Hub, il est commun de passer ds paramètres tels que: -- `token`: pour télécharger depuis un dépôt privé -- `revision`: pour télécharger depuis une branche spécifique -- `cache_dir`: pour mettre en cache des fichiers d'un chemin spécifique -- `force_download`/`resume_download`/`local_files_only`: pour réutiliser le cache ou pas -- `api_endpoint`/`proxies`: pour configurer la session HTTP - -Lorsque vous pushez des modèles, des paramètres similaires sont utilisables: -- `commit_message`: message de commit personnalisé -- `private`: créé un dépôt privé s'il en manque un -- `create_pr`: créé un pull request aulieu de push vers `main` -- `branch`: push vers une branche aulieu de push sur `main` -- `allow_patterns`/`ignore_patterns`: filtre les fichiers à upload -- `token` -- `api_endpoint` -- ... - -Tous ces paramètres peuvent être ajoutés aux implémentations vues ci dessus et passés aux méthodes de `huggingface_hub`. -Toutefois, si un paramètre change ou qu'une nouvelle fonctionnalité est ajoutée, vous devrez mettre à jour votre package. -Avoir du support pour ces paramètres implique aussi plus de documentation à maintenir de votre côté. Pour voir comment -outrepasser ces limitations, regardons dans notre prochaine section **class inheritance**. - -## Une approche plus complexe: class inheritance - -Comme vu ci dessus, il y a deux méthodes principales à inclure dans votre librairie pour l'intégrer avec le Hub: -la méthode permettant d'upload des fichiers (`push_to_hub`) et celle pour télécharger des fichiers (`from_pretrained`). -Vous pouvez implémenter ces méthodes vous même mais cela a des inconvénients. Pour gérer ça, `huggingface_hub` fournit -un outil qui utilise l'héritage de classe. Regardons comment ça marche ! - -Dans beaucoup de cas, une librairie implémente déjà les modèles en utilisant une classe Python. La classe contient les -propriétés du modèle et des méthodes pour charger, lancer, entrainer et évaluer le modèle. Notre approche est d'étendre -cette classe pour inclure les fonctionnalités upload et download en utilisant les mixins. Un [mixin](https://stackoverflow.com/a/547714) -est une classe qui est faite pour étendre une classe existante avec une liste de fonctionnalités spécifiques en utilisant plusieurs héritages. -`huggingface_hub` offre son propre mixin, le [`ModelHubMixin`]. La clef ici est de comprendre son comportement et comment le customiser. - -La classe [`ModelHubMixin`] implémente 3 méthodes *public* (`push_to_hub`, `save_pretrained` et `from_pretrained`). Ce -sont les méthodes que vos utilisateurs appeleront pour charger/enregistrer des modèles avec votre librairie. -[`ModelHubMixin`] définit aussi 2 méthodes *private* (`_save_pretrained` et `from_pretrained`). Ce sont celle que vous -devez implémenter. Ainsi, pour intégrer votre librairie, vous devez : - -1. Faure en sorte que votre classe Model hérite de [`ModelHubMixin`]. -2. Implémenter les méthodes privées: - - [`~ModelHubMixin._save_pretrained`]: méthode qui prend en entrée un chemin vers un directory et qui sauvegarde le modèle. - Vous devez écrire toute la logique pour dump votre modèle de cette manière: model card, poids du modèle, fichiers de configuration, - logs d'entrainement et chiffres. Toute information pertinente pour ce modèle doit être gérée par cette méthode. Les - [model cards](https://huggingface.co/docs/hub/model-cards) sont particulièrement importantes pour décrire votre modèle. Vérifiez - [notre guide d'implémentation](./model-cards) pour plus de détails. - - [`~ModelHubMixin._from_pretrained`]: **méthode de classe** prenant en entrée un `model_id` et qui return un modèle instantié. - Cette méthode doit télécharger le fichier pertinent et les charger. -3. Fini! - -L'avantage d'utiliser [`ModelHubMixin`] est qu'une fois que vous vous êtes occupés de la sérialisation et du chargement du fichier, -vous êtes prêts. Vous n'avez pas besoin de vous soucier de la création du dépôt, des commits, des pull requests ou des révisions. -Tout ceci est géré par le mixin et est disponible pour vos utilisateurs. Le Mixin s'assure aussi que les méthodes publiques sont -bien documentées et que le type est spécifié. - -### Un exemple concret: PyTorch - -Un bon exemple de ce que nous avons vu ci-dessus est [`PyTorchModelHubMixin`], notre intégration pour le framework PyTorch. -C'est une intégration prête à l'emploi. - -#### Comment l'utiliser ? - -Voici comment n'import quel utilisateur peut charger/enregistrer un modèle Pytorch depuis/vers le Hub: - -```python ->>> import torch ->>> import torch.nn as nn ->>> from huggingface_hub import PyTorchModelHubMixin - -# 1. Définissez votre modèle Pytorch exactement comme vous êtes habitués à le faire ->>> class MyModel(nn.Module, PyTorchModelHubMixin): # héritage multiple -... def __init__(self): -... super().__init__() -... self.param = nn.Parameter(torch.rand(3, 4)) -... self.linear = nn.Linear(4, 5) - -... def forward(self, x): -... return self.linear(x + self.param) ->>> model = MyModel() - -# 2. (optionnel) Sauvegarder le modèle dans un chemin local ->>> model.save_pretrained("path/to/my-awesome-model") - -# 3. Pushez les poids du modèle vers le Hub ->>> model.push_to_hub("my-awesome-model") - -# 4. initialisez le modèle depuis le Hub ->>> model = MyModel.from_pretrained("username/my-awesome-model") -``` - -#### Implémentation - -L'implémentation est enfait très direct, l'implémentation complète peut être retrouvée [ici](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py). - -1. Premièrement, faites hériter votre classe de `ModelHubMixin`: - -```python -from huggingface_hub import ModelHubMixin - -class PyTorchModelHubMixin(ModelHubMixin): - (...) -``` - -2. Implémentez la méthode `_save_pretrained`: - -```py -from huggingface_hub import ModelCard, ModelCardData - -class PyTorchModelHubMixin(ModelHubMixin): - (...) - - def _save_pretrained(self, save_directory: Path): - """Générez une model card et enregistrez les poids d'un modèle Pytroch vers un chemin local.""" - model_card = ModelCard.from_template( - card_data=ModelCardData( - license='mit', - library_name="pytorch", - ... - ), - model_summary=..., - model_type=..., - ... - ) - (save_directory / "README.md").write_text(str(model)) - torch.save(obj=self.module.state_dict(), f=save_directory / "pytorch_model.bin") -``` - -3. Implémentez la méthode `_from_pretrained`: - -```python -class PyTorchModelHubMixin(ModelHubMixin): - (...) - - @classmethod # Doit absolument être une méthode de clase ! - def _from_pretrained( - cls, - *, - model_id: str, - revision: str, - cache_dir: str, - force_download: bool, - proxies: Optional[Dict], - resume_download: bool, - local_files_only: bool, - token: Union[str, bool, None], - map_location: str = "cpu", # argument supplémentaire - strict: bool = False, # argument supplémentaire - **model_kwargs, - ): - """Chargez les poids pré-entrainés et renvoyez les au modèle chargé.""" - if os.path.isdir(model_id): # Peut être un chemin local - print("Loading weights from local directory") - model_file = os.path.join(model_id, "pytorch_model.bin") - else: # Ou un modèle du Hub - model_file = hf_hub_download( # Téléchargez depuis le Hub, en passant le mêmes arguments d'entrée - repo_id=model_id, - filename="pytorch_model.bin", - revision=revision, - cache_dir=cache_dir, - force_download=force_download, - proxies=proxies, - resume_download=resume_download, - token=token, - local_files_only=local_files_only, - ) - - # Chargez le modèle et reoutnez une logique personnalisée dépendant de votre framework - model = cls(**model_kwargs) - state_dict = torch.load(model_file, map_location=torch.device(map_location)) - model.load_state_dict(state_dict, strict=strict) - model.eval() - return model -``` - -Et c'est fini ! Votre librairie permet maintenant aux utilisateurs d'upload et de télécharger des fichiers vers et depuis le Hub. - -## Comparaison - -Résumons rapidement les deux approches que nous avons vu avec leurs avantages et leurs défauts. Les table ci-dessous -sont uniquement indicatives. Votre framework aura peut-êre des spécifités que vous devez prendre en compte. Ce guide -est ici uniquement pour vous donner des indications et des idées sur comment gérer l'intégration. Dans tous les cas, -n'hésitez pas à nous contacter si vous avez une question ! - - -| Intégration | Utilisant des helpers | Utilisant [`ModelHubMixin`] | -|:---:|:---:|:---:| -| Expérience utilisateur | `model = load_from_hub(...)`
`push_to_hub(model, ...)` | `model = MyModel.from_pretrained(...)`
`model.push_to_hub(...)` | -| Flexible | Très flexible.
Vous controllez complètement l'implémentation. | Moins flexible.
Votre framework doit avoir une classe de modèle. | -| Maintenance | Plus de maintenance pour ajouter du support pour la configuration, et de nouvelles fonctionnalités. Peut aussi nécessiter de fixx des problèmes signalés par les utilisateurs.| Moins de maintenance vu que la plupart des intégrations avec le Hub sont implémentés dans `huggingface_hub` | -| Documentation / Anotation de type| A écrire à la main | Géré partiellement par `huggingface_hub`. | \ No newline at end of file diff --git a/docs/source/fr/guides/manage-cache.md b/docs/source/fr/guides/manage-cache.md deleted file mode 100644 index 0e37bbc3ea..0000000000 --- a/docs/source/fr/guides/manage-cache.md +++ /dev/null @@ -1,569 +0,0 @@ - - -# Gérer le cache-system `huggingface_hub` - -## Comprendre le caching - -Le cache-system Hugging Face Hub a été créé pour être le cache central partagé par toutes les -librairies dépendant du Hub. Il a été mis à jour dans la version v0.8.0 pour éviter de -retélécharger les mêmes fichiers entre chaque révisions. - -Le système de cache fonctionne comme suit: - -``` - -├─ -├─ -├─ -``` - -Le `` est souvent votre chemin vers la home de votre utilisateur. Cependant, vous pouvez le personnaliser avec l'argument `cache_dir` sur -n'importe quelle méthode, où en spécifiant les variables d'environnement `HF_HOME` ou `HF_HUB_CACHE`. - -Les modèles, datasets et spaces ont tous la même racine. Chacun de ces dépôts contient -le type de dépôt, le namespace (nom de l'organisation ou du nom d'utilisateur) s'il existe -et le nom du dépôt: - -``` - -├─ models--julien-c--EsperBERTo-small -├─ models--lysandrejik--arxiv-nlp -├─ models--bert-base-cased -├─ datasets--glue -├─ datasets--huggingface--DataMeasurementsFiles -├─ spaces--dalle-mini--dalle-mini -``` - -C'est parmi ces dossiers que tous les fichiers seront maintenant téléchargés depuis le Hub. Cacher -vous assure qu'un fichier n'est pas téléchargé deux fois s'il a déjà été téléchargé et qu'il n'a -pas été mis à jour; s'il a été mis à jour et que vous cherchez le dernier fichier, alors il téléchargera -le dernier fichier (tout en gardant les fichiers précédents intacts au cas où vous en auriez besoin). - -Pour ce faire, tous les dossiers contiennent le même squelette: - -``` - -├─ datasets--glue -│ ├─ refs -│ ├─ blobs -│ ├─ snapshots -... -``` - -Chaque dossier est fait pour contenir les dossiers suivants: - -### Refs - -Le fichier `refs` contient des dossiers qui indiquent la dernière révision d'une référence donnée. Par -exemple, si précédemment, nous avions ajouté un fichier depuis la branche `main` d'un dépôt, le dossier -`refs` contiendra un fichier nommé `main`, qui lui même contiendra l'identifier de commit du head actuel. - -Si le dernier commit de `main` a pour identifier `aaaaaa`, alors le fichier dans ``refs` -contiendra `aaaaaa`. - -Si cette même branche est mise à jour avec un nouveau commit, qui a `bbbbbb` en tant -qu'identifier, alors re-télécharger un fichier de cette référence mettra à jour le fichier -`refs/main` afin qu'il contienne `bbbbbb`. - -### Blobs - -Le dossier `blobs` contient les fichiers que nous avons téléchargé. Le nom de chaque fichier est -son hash. - -### Snapshots - -Le dossier `snapshots` contient des symlinks vers les blobs mentionnés ci dessus. Il est lui même fait -de plusieurs dossiers: -un par révision connue! - -Dans l'exemple ci-dessus, nous avons initialement ajouté un fichier depuis la révision `aaaaaa`, avant d'ajouter -un fichier basé sur la révision `bbbbbb`. Dans cette situation, nous aurions maintenant deux dossiers dans le -dossier `snapshots`: `aaaaaaa` et `bbbbbbb`. - -Dans chacun de ces dossiers, il y a des symlinks qui ont le nom des fichiers que nous avons téléchargé. Par -exemple, si nous avions téléchargé le fichier `README.md` dans la révision `aaaaaa`, nous aurions ce chemin: - -``` -//snapshots/aaaaaa/README.md -``` - -Ce fichier `README.md` est enfaite un symlink qui dirige vers le blob qui a le hash du fichier. - -En créant le squelette de cette manière, nous ouvrons le mécanisme au partage de fichiers: si ce même -fichier était ajouté dans la révision `bbbbbb`, il aurait le même hash et le fichier n'aurait pas besoin -d'être re-téléchargé. - -### .no_exist (avancé) - -En plus des fichiers `blobs`, `refs` et `snapshots`, vous pourrez aussi trouver un dossier `.no_exist` -dans votre cache. Ce dossier garde une trace des fichiers que vous avez essayé de télécharger une fois -mais qui n'existent pas sur le Hub. Sa structure est la même que le dossier `snapshots` avec 1 sous-dossier -par révision connue: - -``` -//.no_exist/aaaaaa/config_inexistante.json -``` - -Contrairement au dossier `snapshots`, les fichiers sont de simples fichiers vides (sans symlinks). -Dans cet exemple, le fichier `"config_inexistante.json"` n'existe pas sur le Hub pour la révision -`"aaaaaa"`. Comme il ne sauvegarde que des fichiers vides, ce dossier est négligeable en terme d'utilisation -d'espace sur le disque. - -Maintenant, vous vous demandez peut être, pourquoi cette information est elle pertinente ? -Dans certains cas, un framework essaye de charger des fichiers optionnels pour un modèle. -Enregistrer la non-existence d'un fichier optionnel rend le chargement d'un fichier plus -rapide vu qu'on économise 1 appel HTTP par fichier optionnel possible. -C'est par exemple le cas dans `transformers`, où chacun des tokenizer peut accepter des fichiers additionnels. -La première fois que vous chargez le tokenizer sur votre machine, il mettra en cache quels fichiers -optionnels existent (et lesquels n'existent pas) pour faire en sorte que le chargement soit plus rapide -lors des prochaines initialisations. - -Pour tester si un fichier est en cache en local (sans faire aucune requête HTTP), vous pouvez utiliser -le helper [`try_to_load_from_cache`]. Il retournera soit le chemin du fichier (s'il existe est qu'il est -dans le cache), soit l'objet `_CACHED_NO_EXIST` (si la non existence est en cache), soit `None` -(si on ne sait pas). - -```python -from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST - -filepath = try_to_load_from_cache() -if isinstance(filepath, str): - # Le fichier existe et est dans le cache - ... -elif filepath is _CACHED_NO_EXIST: - # La non-existence du fichier est dans le cache - ... -else: - # Le fichier n'est pas dans le cache - ... -``` - -### En pratique - -En pratique, votre cache devrait ressembler à l'arbre suivant: - -```text - [ 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 -``` - -### Limitations - -Afin d'avoir un système de cache efficace, `huggingface_hub` utilise les symlinks. -Cependant, les symlinks ne sont pas acceptés avec toutes les machines. C'est une -limitation connue en particulier sur Windows. Lorsque c'est le cas, `huggingface_hub` -n'utilise pas le chemin `blobs/` à la plce, elle enregistre les fichiers directement dans -`snapshots/`. Ceci permet aux utilisateurs de télécharger et mettre en cache des fichiers -directement depuis le Hub de la même manière que si tout marchait. Les outils pour -inspecter et supprimer le cache (voir ci-deccous) sont aussi fonctionnels. Toutefois, -le cache-system est moins efficace vu qu'un fichier risque d'être téléchargé un grand -nombre de fois si plusieurs révisions du même dépôt sont téléchargés. - -Si vous voulez bénéficier d'un cache-system basé sur symlink sur une machine Windows, -vous avez le choix entre [activer le mode développeur](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) -ou lancer Python en tant qu'administrateur. - -Lorsque les symlinks ne sont pas supportés, un message d'avertissement est affiché -à l'utilisateur afin de les prévenir qu'ils utilisent une version dégradée du -cache-system. Cet avertissement peut être désactivé en attribuant la valeur -"true" à la varialbe d'environnement `HF_HUB_DISABLE_SYMLINKS_WARNING`. - -## Les assets - -En plus de pouvoir mettre en cache des fichiers du Hub, les librairies demandent souvent -de mettre en cache d'autres fichiers liés à HF mais pas gérés directement par -`huggingface_hub` (par exemple: les fichiers téléchargés depuis GitHub, des données -pré-nettoyés, les logs,...). Afin de mettre en cache ces fichiers appelés `assets`, -[`cached_assets_path`] peut s'avérer utile. Ce petit helper génère des chemins dans le -cache HF d'une manière unifiée selon sur le nom de la librairie qui le demande et -peut aussi générer un chemin sur un namespace ou un nom de sous-dossier. Le but est de -permettre à toutes les librairies de gérer ses assets de sa propre manière -(i.e. pas de règle sur la structure) tant que c'est resté dans le bon dossier -d'assets. Ces librairies peuvent s'appuyer sur des outil d'`huggingface_hub` pour gérer -le cache, en partiluier pour scanner et supprimer des parties d'assets grace à une -commande du CLI. - -```py -from huggingface_hub import cached_assets_path - -assets_path = cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download") -something_path = assets_path / "something.json" # Faites ce que vous voulez dans votre dossier d'assets ! -``` - - - -[`cached_assets_path`] est la manière recommandé de sauvegarder des assets, mais vous -n'êtes pas obligés de l'utiliser. Si votre librairie utilise déjà son propre cache, -n'hésitez pas à l'utiliser! - - - -### Les assets en pratique - -En pratique, votre cache d'asset devrait ressembler à l'arbre suivant: - -```text - assets/ - └── datasets/ - │ ├── SQuAD/ - │ │ ├── downloaded/ - │ │ ├── extracted/ - │ │ └── processed/ - │ ├── Helsinki-NLP--tatoeba_mt/ - │ ├── downloaded/ - │ ├── extracted/ - │ └── processed/ - └── transformers/ - ├── default/ - │ ├── something/ - ├── bert-base-cased/ - │ ├── default/ - │ └── training/ - hub/ - └── models--julien-c--EsperBERTo-small/ - ├── blobs/ - │ ├── (...) - │ ├── (...) - ├── refs/ - │ └── (...) - └── [ 128] snapshots/ - ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/ - │ ├── (...) - └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/ - └── (...) -``` - -## Scannez votre cache - -Pour l'instant, les fichiers en cache ne sont jamais supprimés de votre chemin local: -lorsque vous téléchargez une nouvelle révision de la branche, les fichiers précédents -sont gardés au cas où vous en auriez encore besoin. Par conséquent, il peut être utile -de scanner votre chemin où se trouvent le cache afin de savoir quel dépôts et -révisions prennent le plus de place sur votre disque. `huggingface_hub` fournit -un helper pour effectuer ce scan qui peut être utilisé via `huggingface-cli` -où un script Python. - - -### Scannez le cache depuis le terminal - -La manière la plus simple de scanner votre cache-system HF est d'utiliser la -commande `scan-cache` depuis l'outil `huggingface-clie`. CEtte commande scan le cache -et affiche un rapport avec des informations telles ques l'id du dépôt, le type de -dépôt, l'utilisation du disque, des références et un chemin local complet. - -Le snippet ci-dessous montre le rapport d'un scan dans un dossier qui contient 4 -modèles et 2 datasets en cache. - -```text -➜ huggingface-cli scan-cache -REPO ID REPO TYPE SIZE ON DISK NB FILES LAST_ACCESSED LAST_MODIFIED REFS LOCAL PATH ---------------------------- --------- ------------ -------- ------------- ------------- ------------------- ------------------------------------------------------------------------- -glue dataset 116.3K 15 4 days ago 4 days ago 2.4.0, main, 1.17.0 /home/wauplin/.cache/huggingface/hub/datasets--glue -google/fleurs dataset 64.9M 6 1 week ago 1 week ago refs/pr/1, main /home/wauplin/.cache/huggingface/hub/datasets--google--fleurs -Jean-Baptiste/camembert-ner model 441.0M 7 2 weeks ago 16 hours ago main /home/wauplin/.cache/huggingface/hub/models--Jean-Baptiste--camembert-ner -bert-base-cased model 1.9G 13 1 week ago 2 years ago /home/wauplin/.cache/huggingface/hub/models--bert-base-cased -t5-base model 10.1K 3 3 months ago 3 months ago main /home/wauplin/.cache/huggingface/hub/models--t5-base -t5-small model 970.7M 11 3 days ago 3 days ago refs/pr/1, main /home/wauplin/.cache/huggingface/hub/models--t5-small - -Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G. -Got 1 warning(s) while scanning. Use -vvv to print details. -``` - -Pour avoir un rapport plus détaillé, utilisez l'option `--verbose`. Pour chacun des -dépôts, vous obtenez une liste de toutes les révisions qui ont été téléchargées. Comme -expliqué ci-dessus, les fichiers qui ne changent pas entre 2 révisions sont partagés -grâce aux symlinks. Ceci signifie que la taille du dépôt sur le disque doit être plus -petite que la somme des tailles de chacune de ses révisions. Par exemple, ici, -`bert-based-cased` a 2 révisions de 1.4G et 1.5G, mais l'utilisation totale du disque est -uniquement de 1.9G. - -```text -➜ huggingface-cli scan-cache -v -REPO ID REPO TYPE REVISION SIZE ON DISK NB FILES LAST_MODIFIED REFS LOCAL PATH ---------------------------- --------- ---------------------------------------- ------------ -------- ------------- ----------- ---------------------------------------------------------------------------------------------------------------------------- -glue dataset 9338f7b671827df886678df2bdd7cc7b4f36dffd 97.7K 14 4 days ago main, 2.4.0 /home/wauplin/.cache/huggingface/hub/datasets--glue/snapshots/9338f7b671827df886678df2bdd7cc7b4f36dffd -glue dataset f021ae41c879fcabcf823648ec685e3fead91fe7 97.8K 14 1 week ago 1.17.0 /home/wauplin/.cache/huggingface/hub/datasets--glue/snapshots/f021ae41c879fcabcf823648ec685e3fead91fe7 -google/fleurs dataset 129b6e96cf1967cd5d2b9b6aec75ce6cce7c89e8 25.4K 3 2 weeks ago refs/pr/1 /home/wauplin/.cache/huggingface/hub/datasets--google--fleurs/snapshots/129b6e96cf1967cd5d2b9b6aec75ce6cce7c89e8 -google/fleurs dataset 24f85a01eb955224ca3946e70050869c56446805 64.9M 4 1 week ago main /home/wauplin/.cache/huggingface/hub/datasets--google--fleurs/snapshots/24f85a01eb955224ca3946e70050869c56446805 -Jean-Baptiste/camembert-ner model dbec8489a1c44ecad9da8a9185115bccabd799fe 441.0M 7 16 hours ago main /home/wauplin/.cache/huggingface/hub/models--Jean-Baptiste--camembert-ner/snapshots/dbec8489a1c44ecad9da8a9185115bccabd799fe -bert-base-cased model 378aa1bda6387fd00e824948ebe3488630ad8565 1.5G 9 2 years ago /home/wauplin/.cache/huggingface/hub/models--bert-base-cased/snapshots/378aa1bda6387fd00e824948ebe3488630ad8565 -bert-base-cased model a8d257ba9925ef39f3036bfc338acf5283c512d9 1.4G 9 3 days ago main /home/wauplin/.cache/huggingface/hub/models--bert-base-cased/snapshots/a8d257ba9925ef39f3036bfc338acf5283c512d9 -t5-base model 23aa4f41cb7c08d4b05c8f327b22bfa0eb8c7ad9 10.1K 3 1 week ago main /home/wauplin/.cache/huggingface/hub/models--t5-base/snapshots/23aa4f41cb7c08d4b05c8f327b22bfa0eb8c7ad9 -t5-small model 98ffebbb27340ec1b1abd7c45da12c253ee1882a 726.2M 6 1 week ago refs/pr/1 /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/98ffebbb27340ec1b1abd7c45da12c253ee1882a -t5-small model d0a119eedb3718e34c648e594394474cf95e0617 485.8M 6 4 weeks ago /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/d0a119eedb3718e34c648e594394474cf95e0617 -t5-small model d78aea13fa7ecd06c29e3e46195d6341255065d5 970.7M 9 1 week ago main /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/d78aea13fa7ecd06c29e3e46195d6341255065d5 - -Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G. -Got 1 warning(s) while scanning. Use -vvv to print details. -``` - -#### Exemple de grep - -Vu que l'output de la commande est sous forme de donnée tabulaire, vous pouvez le combiner -avec n'importe quel outil similaire à `grep` pour filtrer les entrées. Voici un exemple -pour filtrer uniquement les révision du modèle "t5-small" sur une machine basée sur -Unix. - -```text -➜ eval "huggingface-cli scan-cache -v" | grep "t5-small" -t5-small model 98ffebbb27340ec1b1abd7c45da12c253ee1882a 726.2M 6 1 week ago refs/pr/1 /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/98ffebbb27340ec1b1abd7c45da12c253ee1882a -t5-small model d0a119eedb3718e34c648e594394474cf95e0617 485.8M 6 4 weeks ago /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/d0a119eedb3718e34c648e594394474cf95e0617 -t5-small model d78aea13fa7ecd06c29e3e46195d6341255065d5 970.7M 9 1 week ago main /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/d78aea13fa7ecd06c29e3e46195d6341255065d5 -``` - -### Scannez le cache depuis Python - -Pour une utilisation plus avancée, utilisez [`scan_cache_dir`] qui est la fonction Python -appelée par l'outil du CLI - -Vous pouvez l'utiliser pour avoir un rapport structuré autour des 4 dataclasses: - -- [`HFCacheInfo`]: rapport complet retourné par [`scan_cache_dir`] -- [`CachedRepoInfo`]: informations sur le dépôt en cache -- [`CachedRevisionInfo`]: informations sur une révision en cache (i.e. "snapshot") à - l'intérieur d'un dépôt -- [`CachedFileInfo`]: informations sur un fichier en cache dans une snapshot - -Voici un exemple simple d'utilisation. Consultez les références pour plus de détails. - -```py ->>> from huggingface_hub import scan_cache_dir - ->>> hf_cache_info = scan_cache_dir() -HFCacheInfo( - size_on_disk=3398085269, - repos=frozenset({ - CachedRepoInfo( - repo_id='t5-small', - repo_type='model', - repo_path=PosixPath(...), - size_on_disk=970726914, - nb_files=11, - last_accessed=1662971707.3567169, - last_modified=1662971107.3567169, - revisions=frozenset({ - CachedRevisionInfo( - commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5', - size_on_disk=970726339, - snapshot_path=PosixPath(...), - # Pas de `last_accessed` car les blobs sont partagés entre les révisions - last_modified=1662971107.3567169, - files=frozenset({ - CachedFileInfo( - file_name='config.json', - size_on_disk=1197 - file_path=PosixPath(...), - blob_path=PosixPath(...), - blob_last_accessed=1662971707.3567169, - blob_last_modified=1662971107.3567169, - ), - CachedFileInfo(...), - ... - }), - ), - CachedRevisionInfo(...), - ... - }), - ), - CachedRepoInfo(...), - ... - }), - warnings=[ - CorruptedCacheException("Le chemin vers les snapshots n'existe par dans les dépôts en cache: ..."), - CorruptedCacheException(...), - ... - ], -) -``` - -## Néttoyez votre cache - -Scanner votre cache est intéressant mais après, vous aurez surement envie de supprimer -certaines parties du cache pour libérer de l'espace dans votre drive. C'est faisable -en utilisant la commande CLI `delete-cache`. L'helper [`~HFCacheInfo.delete_revisions`] -peut aussi être utilisé depuis le code depuis l'objet [`HFCacheInfo`] retourné lors -du scan du cache. - -### Stratégie de suppression - -Pour supprimer des dossiers du cache, vous devez passer une liste de révisions à -supprimer. L'outil définira une stratégie pour libérer de l'espace basé sur cette -liste. Il renvoie un objet [`DeleteCacheStrategy`] qui décrit les fichiers et dossiers -qui seront supprimés. [`DeleteCacheStrategy`] vous donne l'espace qui devrait être -libéré. Une fois que vous acceptez la suppression, vous devez l'exécuter pour que la -suppression soit effective. Afin d'éviter les différentces, vous ne pouvez pas modifier -manuellement un objet stratégie. - -La stratégie pour supprimer des révisions est la suivante: - -- Le dossier `snapshot` contenant les symlinks des révisions est supprimé. -- Les fichiers blobs qui sont visés uniquement par les révisions à supprimer sont supprimés aussi. -- Si une révision est lié à une `refs` ou plus, les références sont supprimées. -- Si toutes les révisions d'un dépôt sont supprimées, le dépôts en cache est supprimé. - - - -Les hash de révision sont uniques parmi tous les dépôts. Ceci signifie que -vous n'avez pas besoin de fournir un `repo_id` ou un `repo_type` lors de la -suppression d'une révision. - - - - -Si une révision n'est pas trouvée dans le cache, elle sera ignorée. En dehors de ça, -si un fichier où un dossier ne peut pas être trouvé lorsque vous essayez de le supprimer, -un avertissement sera affiché mais aucune erreur ne sera retournée. La suppression -continue pour d'autres chemins contenus dans l'objet [`DeleteCacheStrategy`]. - - - -### Nettoyez le cache depuis le terminal - -La manière la plus simple de supprimer des révision de votre cache-system HF est -d'utiliser la commande `delete-cache` depuis l'outil `huggingface-cli`. Cette -commande a deux modes. Par défaut, un TUI (Terminla User Interface) es affiché -à l'utilisateur pour sélectionner la révision à supprimer. Ce TUI est actuellement -en beta car il n'a pas été testé sur toutes les plateformes. Si le TUI ne marche pas -sur votre machine, vous pouvez le désactiver en utilisant le flag `--disable-tui`. - -#### Utilisation du TUI - -C'est le mode par défaut. Pour l'utliser, vous avez d'abord besoin d'installer les -dépendances supplémentaire en lançant la commande suivante: - -``` -pip install huggingface_hub["cli"] -``` - -Ensuite lancez la commande: - -``` -huggingface-cli delete-cache -``` - -Vous devriez maintenant voir une liste de révisions que vous pouvez sélectionner/désélectionner: - -
- -
- -Instructions: - - Appuyez lsur les flèches `` et `` du clavier pour bouger le curseur. - - Appuyez sur `` pour sélectionner/désélectionner un objet. - - Lorsqu'une révision est sélectionnée, la première ligne est mise à jour pour vous montrer - l'espace libéré - - Appuyez sur `` pour confirmer votre sélection. - - Si vous voulez annuler l'opération et quitter, vous pouvez sélectionner le premier item - ("none of the following"). Si cet item est sélectionné, le processus de suppression sera - annulé, et ce, quel que soit les autres items sélectionnés. Sinon, vous pouvez aussi - appuyer sur `` pour quitter le TUI. - -Une fois que vous avez sélectionné les révision que vous voulez supprimer et que vous -avez appuyé sur ``, un dernier message de confirmation sera affiché. Appuyez -sur `` encore une fois et la suppression sera effective. Si vous voulez l'annuler, -appuyez sur `n`. - -```txt -✗ huggingface-cli delete-cache --dir ~/.cache/huggingface/hub -? Select revisions to delete: 2 revision(s) selected. -? 2 revisions selected counting for 3.1G. Confirm deletion ? Yes -Start deletion. -Done. Deleted 1 repo(s) and 0 revision(s) for a total of 3.1G. -``` - -#### sans le TUI - -Comme mentionné ci-dessus, le mode TUI est actuellement en beta et est optionnel. Il -se pourrait qu'il ne marche pas sur votre machine ou que vous ne le trouvez pas -pratique. - -une autre approche est d'utiliser le flag `--disable-tui`. Le process est très similaire -a ce qu'on vous demandera pour review manuellement la liste des révisions à supprimer. -Cependant, cette étape manuelle ne se passera pas dans le terminal directement mais -dans un fichier temporaire généré sur le volet et que vous pourrez éditer manuellement. - -Ce fichier a toutes les instructions dont vous avez besoin dans le header. Ouvrez le dans -votre éditeur de texte favoris. Pour sélectionner ou déselectionner une révision, commentez -ou décommentez simplement avec un `#`. Une fois que la review du manuel fini et que le fichier -est édité, vous pouvez le sauvegarder. Revenez à votre terminal et appuyez sur ``. -Par défaut, l'espace libéré sera calculé avec la liste des révisions mise à jour. Vous -pouvez continuer de modifier le fichier ou confirmer avec `"y"`. - -```sh -huggingface-cli delete-cache --disable-tui -``` - -Exemple de fichier de commande: -```txt -# INSTRUCTIONS -# ------------ -# This is a temporary file created by running `huggingface-cli delete-cache` with the -# `--disable-tui` option. It contains a set of revisions that can be deleted from your -# local cache directory. -# -# Please manually review the revisions you want to delete: -# - Revision hashes can be commented out with '#'. -# - Only non-commented revisions in this file will be deleted. -# - Revision hashes that are removed from this file are ignored as well. -# - If `CANCEL_DELETION` line is uncommented, the all cache deletion is cancelled and -# no changes will be applied. -# -# Once you've manually reviewed this file, please confirm deletion in the terminal. This -# file will be automatically removed once done. -# ------------ - -# KILL SWITCH -# ------------ -# Un-comment following line to completely cancel the deletion process -# CANCEL_DELETION -# ------------ - -# REVISIONS -# ------------ -# Dataset chrisjay/crowd-speech-africa (761.7M, used 5 days ago) - ebedcd8c55c90d39fd27126d29d8484566cd27ca # Refs: main # modified 5 days ago - -# Dataset oscar (3.3M, used 4 days ago) -# 916f956518279c5e60c63902ebdf3ddf9fa9d629 # Refs: main # modified 4 days ago - -# Dataset wikiann (804.1K, used 2 weeks ago) - 89d089624b6323d69dcd9e5eb2def0551887a73a # Refs: main # modified 2 weeks ago - -# Dataset z-uo/male-LJSpeech-italian (5.5G, used 5 days ago) -# 9cfa5647b32c0a30d0adfca06bf198d82192a0d1 # Refs: main # modified 5 days ago -``` - -### Nettoyez le cache depuis Python - -Pour plus de flexibilité, vous pouvez aussi utiliser la méthode [`~HFCacheInfo.delete_revisions`] -depuis le code. Voici un exemple simple, consultez la référence pour plus de détails. - -```py ->>> from huggingface_hub import scan_cache_dir - ->>> delete_strategy = scan_cache_dir().delete_revisions( -... "81fd1d6e7847c99f5862c9fb81387956d99ec7aa" -... "e2983b237dccf3ab4937c97fa717319a9ca1a96d", -... "6c0e6080953db56375760c0471a8c5f2929baf11", -... ) ->>> print("Will free " + delete_strategy.expected_freed_size_str) -Will free 8.6G - ->>> delete_strategy.execute() -Cache deletion done. Saved 8.6G. -``` diff --git a/docs/source/fr/guides/manage-spaces.md b/docs/source/fr/guides/manage-spaces.md deleted file mode 100644 index 520b593ce3..0000000000 --- a/docs/source/fr/guides/manage-spaces.md +++ /dev/null @@ -1,379 +0,0 @@ - - -# Gérez votre space - -Dans ce guide, nous allons voir comment gérer le temps de calcul sur votre space, -([les secrets](https://huggingface.co/docs/hub/spaces-overview#managing-secrets), -[le hardware](https://huggingface.co/docs/hub/spaces-gpus), et [le stockage](https://huggingface.co/docs/hub/spaces-storage#persistent-storage)) -en utilisant `huggingface_hub`. - -## Un exemple simple: configurez les secrets et le hardware. - -Voici un exemple de A à Z pour créer et mettre en place un space sur le Hub. - -**1. Créez un space sur le Hub.** - -```py ->>> from huggingface_hub import HfApi ->>> repo_id = "Wauplin/my-cool-training-space" ->>> api = HfApi() - -# Par exemple, avec un SDK Gradio ->>> api.create_repo(repo_id=repo_id, repo_type="space", space_sdk="gradio") -``` - -**1. (bis) Dupliquez un space.** - -Ceci peut-être utile si vous voulez construire depuis un space existant aulieu de commencer à zéro. -C'est aussi utile si vous voulez controler la configuration et les paramètres d'un space publique. -Consultez [`duplicate_space`] pour plus de détails. - -```py ->>> api.duplicate_space("multimodalart/dreambooth-training") -``` - -**2. Uploadez votre code en utilisant votre solution préférée.** - -Voici un exemple pour upload le dossier local `src/` depuis votre machine vers votre space: - -```py ->>> api.upload_folder(repo_id=repo_id, repo_type="space", folder_path="src/") -``` - -A ce niveau là, votre application devrait déjà être en train de tourner sur le Hub gratuitement ! -Toutefois, vous voudez peut-être la configurer plus en détail avec des secrets et un -meilleur hardware. - -**3. Configurez des secrets et des variables** - -Votre space aura peut-être besoin d'une clef secrète, un token ou de variables -pour fonctionner. Consultez [la doc](https://huggingface.co/docs/hub/spaces-overview#managing-secrets) -pour plus de détails. Par exemple, un token HF pour upload un dataset d'image vers le Hub -une fois généré depuis votre space. - -```py ->>> api.add_space_secret(repo_id=repo_id, key="HF_TOKEN", value="hf_api_***") ->>> api.add_space_variable(repo_id=repo_id, key="MODEL_REPO_ID", value="user/repo") -``` - -Les secrets et les variables peuvent supprimés aussi: -```py ->>> api.delete_space_secret(repo_id=repo_id, key="HF_TOKEN") ->>> api.delete_space_variable(repo_id=repo_id, key="MODEL_REPO_ID") -``` - - -Depuis votre space, les secrets sont définissables en tant que variables -(ou en tant que management de secrets Streamlit si vous utilisez Streamlit). -Pas besoin de les ajouter via l'API! - - - -Tout changement dans la configuration de votre space (secrets ou hardware) relancera votre -application. - - -**Bonus: définissez les secrets et les variables lors de la création ou la duplication du space!** - -Les secrets et les variables peuvent être défini lors de la création ou la duplication d'un space: - -```py ->>> api.create_repo( -... repo_id=repo_id, -... repo_type="space", -... space_sdk="gradio", -... space_secrets=[{"key"="HF_TOKEN", "value"="hf_api_***"}, ...], -... space_variables=[{"key"="MODEL_REPO_ID", "value"="user/repo"}, ...], -... ) -``` - -```py ->>> api.duplicate_space( -... from_id=repo_id, -... secrets=[{"key"="HF_TOKEN", "value"="hf_api_***"}, ...], -... variables=[{"key"="MODEL_REPO_ID", "value"="user/repo"}, ...], -... ) -``` - -**4. Configurez le hardware** - -Par défaut, votre space tournera sur un CPU gratuitement. Vous pouvez améliorer le -hardware pour le faire tourner sur des GPUs. Une carte bleue ou un community grant sera -nécessaire pour accéder à l'amélioration de votre space. Consultez [la doc](https://huggingface.co/docs/hub/spaces-gpus) -pour plus de détails. - -```py -# Utilisez l'enum `SpaceHardware` ->>> from huggingface_hub import SpaceHardware ->>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM) - -# Ou simplement passez un string ->>> api.request_space_hardware(repo_id=repo_id, hardware="t4-medium") -``` - -Les mises à jour d'hardware ne sont pas faites immédiatement vu que votre space doit -être rechargé sur nos serveurs. A n'importe quel moment, vous pouvez vérifier sur quel -hardware votre space tourne pour vérifier que votre demande a été réalisée. - -```py ->>> runtime = api.get_space_runtime(repo_id=repo_id) ->>> runtime.stage -"RUNNING_BUILDING" ->>> runtime.hardware -"cpu-basic" ->>> runtime.requested_hardware -"t4-medium" -``` - -Vous avez maintenant un space totalement configuré. Une fois que vous avez fini avec les -GPUs, assurez vous de revenir à "cpu-classic". -You now have a Space fully configured. Make sure to downgrade your Space back to "cpu-classic" -when you are done using it. - -**Bonus: demandez du hardware lors de la création ou la duplication d'un space!** - -Les nouvel hardware sera automatiquement assigné à votre space une fois qu'il -a été construit. - -```py ->>> api.create_repo( -... repo_id=repo_id, -... repo_type="space", -... space_sdk="gradio" -... space_hardware="cpu-upgrade", -... space_storage="small", -... space_sleep_time="7200", # 2 heure en secondes -... ) -``` -```py ->>> api.duplicate_space( -... from_id=repo_id, -... hardware="cpu-upgrade", -... storage="small", -... sleep_time="7200", # 2 heures en secondes -... ) -``` - -**5. Mettez en pause et relancez votre space** - -Par défaut, si votre space tourne sur un hardware amélioré, il ne sera jamais arrêté. Toutefois pour éviter de vous -faire facturer, vous aurez surement besoin de le mettre en pause lorsque vous ne l'utilisez pas. C'est possible en -utilisant [`pause_space`]. Un space en pause sera inactif tant que le propriétaire du space ne l'a pas relancé, -soit avec l'interface utliisateur ou via l'API en utilisant [`restart_space`]. Pour plus de détails sur le mode "en pause", -consultez [cette section](https://huggingface.co/docs/hub/spaces-gpus#pause) du guide. - -```py -# Met en pause le space pour éviter de payer ->>> api.pause_space(repo_id=repo_id) -# (...) -# Relance le space quand vous en avez besoin ->>> api.restart_space(repo_id=repo_id) -``` - -Une auter possibilité est de définir un timeout pour votre space. Si votre space est inactif pour une durée -plus grande que la durée de timeout, alors il se mettra en pause automatiquement. N'importe quel visiteur qui -arrive sur votre space le relancera. Vous pouvez définir un timeout en utilisant [`set_space_sleep_time`]. -Pour plus de détails sur le mode "en pause", consultez [cette section](https://huggingface.co/docs/hub/spaces-gpus#sleep-time). - -```py -# Met le space en pause après une heure d'inactivité ->>> api.set_space_sleep_time(repo_id=repo_id, sleep_time=3600) -``` - -Note: si vous utlisez du du hardware 'cpu-basic', vous ne pouvez pas configurer un timeout personnalisé. Votre space -se mettra en pause automatiquement aprèss 48h d'inactivité. - -**Bonus: définissez le temps de timeout lorsque vous demandez le hardware** - -Le hardware amélioré sera automatiquement assigné à votre space une fois construit. - -```py ->>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM, sleep_time=3600) -``` - -**Bonus: définissez un temps de timeout lors de la création ou de la duplication d'un space!** - -```py ->>> api.create_repo( -... repo_id=repo_id, -... repo_type="space", -... space_sdk="gradio" -... space_hardware="t4-medium", -... space_sleep_time="3600", -... ) -``` -```py ->>> api.duplicate_space( -... from_id=repo_id, -... hardware="t4-medium", -... sleep_time="3600", -... ) -``` - -**6. Ajoutez du stockage persistant à votre space** - -Vous pouvez choisir le stockage de votre choix pour accéder au disque dont la mémoire ne s'écrase pas lors du redémarrage du space. Ceci signifie que -vous pouvez lire et écrire sur ce disque comme vous l'auriez fait avec un disque dur traditionnel. -Consultez See [la doc](https://huggingface.co/docs/hub/spaces-storage#persistent-storage) pour plus de détails. - -```py ->>> from huggingface_hub import SpaceStorage ->>> api.request_space_storage(repo_id=repo_id, storage=SpaceStorage.LARGE) -``` - -Vous pouvez aussi supprimer votre stockage, mais vous perdrez toute la donnée de manière irréversible. -```py ->>> api.delete_space_storage(repo_id=repo_id) -``` - -Note: Vous ne pouvez pas diminuer le niveau de stockage de votre space une fois qu'il a été -donné. Pour ce faire, vous devez d'abord supprimer le stockage -(attention, les données sont supprimés définitivement) puis demander le niveau de stockage désiré. - -**Bonus: demandez du stockage lors de la création ou la duplication du space!** - -```py ->>> api.create_repo( -... repo_id=repo_id, -... repo_type="space", -... space_sdk="gradio" -... space_storage="large", -... ) -``` -```py ->>> api.duplicate_space( -... from_id=repo_id, -... storage="large", -... ) -``` - -## Avancé: améliorez votre space pour un durée déterminée! - -Les spaces ont un grand nombre de cas d'application. Parfois, vous aurez -peut-être envie de faire un tourner un space pendant une durée déterminée sur un hardware -spécifique, faire quelque chose puis éteindre le space. dans cette section, nous explorerons -les avantgaes des spaces pour finetune un modèle sur demande. C'est la seule manière de -résoudre ce problème. Toutefois, ces tutoriaux ne sont que des suggestions et doivent être -adaptés à votre cas d'usage. - -Supposons que nous avons un space pour finetune un modèle. C'est une aplication Gradio qui -prend en entrée l'id d'un modèle et l'id d'un dataset. Le workflow est le suivant: - -0.Demander à l'utilisateur un modèle et un dataset. -1.Charger le modèle depuis le Hub. -2.Charger le dataset depuis le Hub. -3.Finetune le modèle sur le dataset. -4.Upload le nouveau modèle vers le Hub. - -La 3ème étape demande un hardware personnalisé mais vous n'aurez surement pas envie que votre space -tourne tout le temps sur un GPU que vous payez. Une solution est de demander du hardware de manière -dynmaique pour l'entrainement et l'éteindre après. Vu que demander du hardware redémarre voter space, -votre application doit d'une manière ou d'une autre "se rappeler" la tache qu'il est entrain de réaliser. -Il y a plusieurs manières de faire ceci. Dans ce guide, nous verrons une solution utilisant un dataset -qui fera office de "programmateur de tâche". - -### Le squelette de l'application - -Voici ce à quoi votre application ressemblerait. Au lancement, elle vérifie si une tâche est -programmée et si oui, cette tâche sera lancée sur le bon hardware. Une fois fini, le -hardware est remis au CPU du plan gratuit et demande à l'utilisateur une nouvelle tâche. - - -Un tel workflow ne permet pas un accès simultané en tant que démo -normales. En particulier, l'interface sera supprimée lors de -l'entrainement. il est préférable de mettre votre dépôt en privé -pour vous assurer que vous êtes le seul utilisateur. - - -```py -# Un space aura besoin de votre token pour demander du hardware: définissez le en temps que secret! -HF_TOKEN = os.environ.get("HF_TOKEN") - -# Le repo_id du space -TRAINING_SPACE_ID = "Wauplin/dreambooth-training" - -from huggingface_hub import HfApi, SpaceHardware -api = HfApi(token=HF_TOKEN) - -# Lors du lancement du space, vérifiez si une tâche est programmée. Si oui, finetunez le modèle. Si non, -# affichez une interface pour demander une nouvelle tâche. -task = get_task() -if task is None: - # Lancez l'application Gradio - def gradio_fn(task): - # Lorsque l'utilisateur le demande, ajoutez une tâche et demandez du hardware. - add_task(task) - api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.T4_MEDIUM) - - gr.Interface(fn=gradio_fn, ...).launch() -else: - runtime = api.get_space_runtime(repo_id=TRAINING_SPACE_ID) - # Vérifiez si le space est chargé avec un GPU. - if runtime.hardware == SpaceHardware.T4_MEDIUM: - # Si oui, fintunez le modèle de base sur le dataset! - train_and_upload(task) - - # Ensuite, signalez la tâche comme finie - mark_as_done(task) - - # N'OUBLIEZ PAS: remettez le hardware en mode CPU - api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.CPU_BASIC) - else: - api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.T4_MEDIUM) -``` - -### Le task scheduler - -Programmer une tâche peut-être fait de plusieurs manières. Voici un exemple de comment -on pourrait le faire en utilisant un simple CSV enregistré en tant que dataset. - -```py -# ID du dataset dans lequel un fichier `task.csv` cotient la tâche à accomplir. -# Voici un exemple basique pour les inputs de `tasks.csv` et le status PEDING (en cours) ou DONE (fait). -# multimodalart/sd-fine-tunable,Wauplin/concept-1,DONE -# multimodalart/sd-fine-tunable,Wauplin/concept-2,PENDING -TASK_DATASET_ID = "Wauplin/dreambooth-task-scheduler" - -def _get_csv_file(): - return hf_hub_download(repo_id=TASK_DATASET_ID, filename="tasks.csv", repo_type="dataset", token=HF_TOKEN) - -def get_task(): - with open(_get_csv_file()) as csv_file: - csv_reader = csv.reader(csv_file, delimiter=',') - for row in csv_reader: - if row[2] == "PENDING": - return row[0], row[1] # model_id, dataset_id - -def add_task(task): - model_id, dataset_id = task - with open(_get_csv_file()) as csv_file: - with open(csv_file, "r") as f: - tasks = f.read() - - api.upload_file( - repo_id=repo_id, - repo_type=repo_type, - path_in_repo="tasks.csv", - # Manière simple et inélégante d'ajouter une tâche - path_or_fileobj=(tasks + f"\n{model_id},{dataset_id},PENDING").encode() - ) - -def mark_as_done(task): - model_id, dataset_id = task - with open(_get_csv_file()) as csv_file: - with open(csv_file, "r") as f: - tasks = f.read() - - api.upload_file( - repo_id=repo_id, - repo_type=repo_type, - path_in_repo="tasks.csv", - # Manière simple et inélégante de marquer une tâche comme DONE - path_or_fileobj=tasks.replace( - f"{model_id},{dataset_id},PENDING", - f"{model_id},{dataset_id},DONE" - ).encode() - ) -``` \ No newline at end of file diff --git a/docs/source/fr/guides/model-cards.md b/docs/source/fr/guides/model-cards.md deleted file mode 100644 index 74bcdcfaf0..0000000000 --- a/docs/source/fr/guides/model-cards.md +++ /dev/null @@ -1,373 +0,0 @@ - - -# Créer en partager des cartes de modèle - -La librairie `huggingface_hub` fournit une interface Python pour créer, partager et mettre à jour -des cartes de modèle. Consultez [page de documentation dédiée](https://huggingface.co/docs/hub/models-cards) -pour une vue en profondeur de ce que les cartes de modèle sont et comment elles fonctionnent -en arrière-plan. - - - -[`Nouveaux : Testez notre application de création de carte de modèle`](https://huggingface.co/spaces/huggingface/Model_Cards_Writing_Tool) - - - -## Chargez une carte de modèle depuis le Hub - -Pour charger une carte existante depuis le Hub, vous pouvez utiliser la fonction [`ModelCard.load`]. Ici, nous chargeront la carte depuis [`nateraw/vit-base-beans`](https://huggingface.co/nateraw/vit-base-beans). - -```python -from huggingface_hub import ModelCard - -card = ModelCard.load('nateraw/vit-base-beans') -``` - -Cette carte a des attributs très utiles que vous aurez peut-être envie d'utiliser: - - `card.data`: Retourne une instance [`ModelCardData`] avec les métadonnées de la carte de modèle. Les appels à `.to_dict()` sur cette instance pour obtenir les représentations en tant que dictionnaire. - - `card.text`: Retourne le texte de la carte *sans le header des métadonnées*. - - `card.content`: Retourne le contenu textuel de la carte, *dont le header des métadonnées*. - -## Créez des cartes de modèle - -### Depuis le texte - -Pour initialiser une carte de modèle depuis le texte, passez simplement en tant qu'argument le -prochain contenu de la carte au `ModelCard` à l'initialisation. - -```python -content = """ ---- -language: en -license: mit ---- - -# Ma carte de modèle -""" - -card = ModelCard(content) -card.data.to_dict() == {'language': 'en', 'license': 'mit'} # True -``` - -Une autre manière que vous aurez peut-être besoin d'utiliser est celle utilisant les -f-strings. Dans l'exemple suivant nous: - -- Utiliseront [`ModelCardData.to_yaml`] pour convertir la métadonnée que nous avons définie en YAML afin de pouvoir l'utiliser pour - insérer le block YAML dans la carte de modèle. -- Montreront comment vous pourriez utiliser une variable dans un template via les f-strings Python. - -```python -card_data = ModelCardData(language='en', license='mit', library='timm') - -example_template_var = 'nateraw' -content = f""" ---- -{ card_data.to_yaml() } ---- - -# Ma carte de modèle - -Ce modèle créé par [@{example_template_var}](https://github.com/{example_template_var}) -""" - -card = ModelCard(content) -print(card) -``` - -L'exemple ci-dessus nous laisserait avec une carte qui ressemble à ça: - -``` ---- -language: en -license: mit -library: timm ---- - -# Ma carte de modèle - -Ce modèle a été créé par [@nateraw](https://github.com/nateraw) -``` - -### Depuis un template Jinja - -Si `Jinja2` est installé, vous pouvez créer une carte de modèle depuis un template jinja. Consultons un exemple -basique: - -```python -from pathlib import Path - -from huggingface_hub import ModelCard, ModelCardData - -# Définissez votre template jinja -template_text = """ ---- -{{ card_data }} ---- - -# Carte de modèle de MyCoolModel - -Ce modèle fait ceci, il peut aussi faire cela... - -Ce modèle a été créé par [@{{ author }}](https://hf.co/{{author}}). -""".strip() - -# Écrivez le template vers un fichier -Path('custom_template.md').write_text(template_text) - -# Définissez la métadonnée de la carte -card_data = ModelCardData(language='en', license='mit', library_name='keras') - -# Créez une carte depuis le template vous pouvez passer n'importe quelle variable de template jinja que vous voulez. -# Dans notre cas, nous passeront author -card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw') -card.save('my_model_card_1.md') -print(card) -``` - -Le markdown de la carte affiché ressemblera à ça: - -``` ---- -language: en -license: mit -library_name: keras ---- - -# Carte de modèle pour MyCoolModel - -Ce modèle fait ceci et cela. - -Ce modèle a été créé par [@nateraw](https://hf.co/nateraw). -``` - -Si vous mettez à jour n'importe quelle card.data, elle sera aussi -modifiée dans la carte elle même. - -``` -card.data.library_name = 'timm' -card.data.language = 'fr' -card.data.license = 'apache-2.0' -print(card) -``` - -Maintenant, comme vous pouvez le voir, le header de métadonnée -a été mis à jour: - -``` ---- -language: fr -license: apache-2.0 -library_name: timm ---- - -# Carte de modèle pour MyCoolModel - -Ce modèle peut faire ceci et cela... - -Ce modèle a été créé par [@nateraw](https://hf.co/nateraw). -``` - -Tout en mettant à jour la donnée de carte, vous pouvez vérifier que la carte est toujours valide pour le Hub en appelant [`ModelCard.validate`]. Ceci vous assure que la carte passera n'importe quelle règle de validation existante sur le Hub Hugging Face. - -### Depuis le template par défaut - -Aulieu d'utiliser votre propre template, vous pouvez aussi utiliser le [template par défaut](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md), qui est une carte de modèle avec toutes les fonctionnalités possibles contenant des tonnes de sections que vous aurez peut-être besoin de remplir. En arrière plan, ce template utilise [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) pour remplir un fichier de template. - - - -Notez que vous aurez besoin d'avoir Jinja2 installé pour utiliser `from_template`. Vous pouvez le faire avec -`pip install Jinja2`. - - - -```python -card_data = ModelCardData(language='en', license='mit', library_name='keras') -card = ModelCard.from_template( - card_data, - model_id='my-cool-model', - model_description="this model does this and that", - developers="Nate Raw", - repo="https://github.com/huggingface/huggingface_hub", -) -card.save('my_model_card_2.md') -print(card) -``` - -## Partagez une carte de modèle - -Si vous êtes authentifié dans le Hub Hugging Face (soit en utilisant `huggingface-cli login` ou [`login`]), vous pouvez push des cartes vers le Hub -en appelant [`ModelCard.push_to_hub`]. Regardons comment le faire: - -Tout d'abord, nous allons créer un nouveau dépôt qu'on appelera 'hf-hub-modelcards-pr-test' sur le namespace -de l'utilisateur authentifié: - -```python -from huggingface_hub import whoami, create_repo - -user = whoami()['name'] -repo_id = f'{user}/hf-hub-modelcards-pr-test' -url = create_repo(repo_id, exist_ok=True) -``` - -Ensuite, nous créerons la carte pour le template par défaut (de la même manière que celui défini dans la section ci-dessus): - -```python -card_data = ModelCardData(language='en', license='mit', library_name='keras') -card = ModelCard.from_template( - card_data, - model_id='my-cool-model', - model_description="this model does this and that", - developers="Nate Raw", - repo="https://github.com/huggingface/huggingface_hub", -) -``` - -Enfin, nous pushong le tout sur le Hub - -```python -card.push_to_hub(repo_id) -``` - -Vous pouvez vérifier la carte créé [ici](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/blob/main/README.md). - -Si vous avez envie de faire une pull request, vous pouvez juste préciser `create_pr=True` lors de l'appel -`push_to_hub`: - -```python -card.push_to_hub(repo_id, create_pr=True) -``` - -Une pull request créé de cette commande peut-être vue [ici](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/discussions/3). - -## Mettre à jour les métadonnées - -Dans cette section, nous verons ce que les métadonnées sont dans les cartes de dépôt -et comment les mettre à jour. - -`metadata` fait référence à un contexte de hash map (ou clé-valeur) qui fournit des informations haut niveau sur un modèle, un dataset ou un space. Cette information peut inclure des détails tels que le `type de pipeline`, le `model_id` ou le `model_description`. Pour plus de détails, vous pouvez consulter ces guides: [carte de modèle](https://huggingface.co/docs/hub/model-cards#model-card-metadata), [carte de dataset](https://huggingface.co/docs/hub/datasets-cards#dataset-card-metadata) and [Spaces Settings](https://huggingface.co/docs/hub/spaces-settings#spaces-settings). Maintenant voyons des exemples de mise à jour de ces métadonnées. - - -Commençons avec un premier exemple: - -```python ->>> from huggingface_hub import metadata_update ->>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"}) -``` - -Avec ces deux lignes de code vous mettez à jour la métadonnée pour définir un nouveau `pipeline_tag`. - -Par défaut, vous ne pouvez pas mettre à jour une clé qui existe déjà sur la carte. Si vous voulez le faire, -vous devez passer explicitement `overwrite=True`: - - -```python ->>> from huggingface_hub import metadata_update ->>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True) -``` - -Souvent, vous aurez envie de suggérer des changements dans un dépôt sur -lequel vous avez pas les permissions d'écriture. Vous pouvez faire ainsi -en créant une pull request sur ce dépôt qui permettra aux propriétaires -de review et de fusionner vos suggestions. - -```python ->>> from huggingface_hub import metadata_update ->>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True) -``` - -## Inclure des résultats d'évaluation - -Pour inclure des résultats d'évaluation dans la métadonnée `model-index`, vous pouvez passer un [`EvalResult`] ou une liste d'`EvalResult` avec vos résultats d'évaluation associés. En arrière-plan, le `model-index` sera créé lors de l'appel de `card.data.to_dict()`. Pour plus d'informations sur la manière dont tout ça fonctionne, vous pouvez consulter [cette section de la documentation du Hub](https://huggingface.co/docs/hub/models-cards#evaluation-results). - - - -Notez qu'utiliser cette fonction vous demande d'inclure l'attribut `model_name` dans [`ModelCardData`]. - - - -```python -card_data = ModelCardData( - language='en', - license='mit', - model_name='my-cool-model', - eval_results = EvalResult( - task_type='image-classification', - dataset_type='beans', - dataset_name='Beans', - metric_type='accuracy', - metric_value=0.7 - ) -) - -card = ModelCard.from_template(card_data) -print(card.data) -``` - -Le `card.data` résultant devrait ressembler à ceci: - -``` -language: en -license: mit -model-index: -- name: my-cool-model - results: - - task: - type: image-classification - dataset: - name: Beans - type: beans - metrics: - - type: accuracy - value: 0.7 -``` - -Si vous avez plus d'un résultat d'évaluation que vous voulez partager, passez simplement une liste -d'`EvalResult`: - -```python -card_data = ModelCardData( - language='en', - license='mit', - model_name='my-cool-model', - eval_results = [ - EvalResult( - task_type='image-classification', - dataset_type='beans', - dataset_name='Beans', - metric_type='accuracy', - metric_value=0.7 - ), - EvalResult( - task_type='image-classification', - dataset_type='beans', - dataset_name='Beans', - metric_type='f1', - metric_value=0.65 - ) - ] -) -card = ModelCard.from_template(card_data) -card.data -``` - -Ce qui devrait donner le `card.data` suivant: - -``` -language: en -license: mit -model-index: -- name: my-cool-model - results: - - task: - type: image-classification - dataset: - name: Beans - type: beans - metrics: - - type: accuracy - value: 0.7 - - type: f1 - value: 0.65 -``` \ No newline at end of file diff --git a/docs/source/fr/guides/overview.md b/docs/source/fr/guides/overview.md deleted file mode 100644 index 6c1e10fbae..0000000000 --- a/docs/source/fr/guides/overview.md +++ /dev/null @@ -1,131 +0,0 @@ - - -# Guides conceptuels - -Dans cette section, vous trouverez des guides pratiques pour vous aider à accomplir un but spécifique. -Consultez ces guides pour apprendre à utiliser `huggingface_hub` pour résoudre des problèmes pratiques: - -
-
- - -
- Dépôts -

- Comment créer un dépôt sur le Hub ? Comment le configurer ? Comment intéragir avec ? -

- - - -
- Télécharger des fichiers -

- Comment télécharger un fichier du Hub? Comment télécharger un dépôt? -

- - - -
- Upload des fichiers -

- Comment upload un fichier ou un dossier? Comment modifier un dépôt existant sur le Hub? -

- - - -
- Recherche -

- Comment faire une recherche efficace parmi les plus de 200 000 modèles, datasets et spaces? -

- - - -
- HfFileSystem -

- Comment intéragir avec le Hub à travers une interface pratique qui colle parfaitement à l'interface fichier de Python? -

- - - -
- Inférence -

- Comment faire des prédictions en utilisant l'API d'inférence accélérée? -

- - - -
- Community Tab -

- Comment intéragir avec la communauté (discussions et pull requests)? -

- - - -
- Collections -

- Comment construire des collections depuis le code? -

- - - -
- Cache -

- Comment le système cache fonctionne? Comment l'utiliser à son avantage? -

- - - -
- Carte de modèle -

- Comment créer et partager une carte de modèle? -

- - - -
- Gérez votre space -

- Comment gérer le hardware d'un space et sa configuration? -

- - - -
- Intégrez une librairie -

- Que signifie intégrer une librairie avec le Hub? Et comment le faire? -

- - - -
- Serveurs WebHooks -

- Comment créer un serveur pour recevoir des webhooks et le déployer en tant que space? -

- - -
-
diff --git a/docs/source/fr/guides/repository.md b/docs/source/fr/guides/repository.md deleted file mode 100644 index db635a310d..0000000000 --- a/docs/source/fr/guides/repository.md +++ /dev/null @@ -1,248 +0,0 @@ - - -# Créer et gérer un dépôt - -Le Hub Hugging Face est une collection de dépôt git. [Git](https://git-scm.com/) est un outil utilisé par tous les développeurs -de software, il permet de versionner facilement des projet lors de travaux en équipe. Ce guide vous montrera commen intéragir -avec les dépôts sur le Hub, ne particulier: - -- Créer et supprimer un dépôt. -- Gérer les branches et les tags. -- Renommer votre dépôt. -- Mettre à jour la visibilité de votre dépôt. -- Gérer une copie local de votre dépôt. - - - -Si vous êtes habitués à utiliser des plateformes telles que GitLab/GitHub/Bitbucket, votre premier -instinct sera peut-être d'utiliser le CLI `git` pour cloner votre dépôt (`git clone`), commit les changements -(`git add, git commit`) et les push (`git push`). C'est faisable lors de l'utilisation d'Hugging Face Hub. -Cependant, le développement d'application et le machine learning n'ont pas les même besoins et workflow. Les dépôts de -modèles ont souvent des fichiers avec les poids du modèle très volumineux pour différents frameworks et outils, cloner -un dépôt peut donc demander de gérer des fichiers de très grande taille en local. Ainsi, il peut être plus efficace d'utiliser -nos méthodes HTTP personnalisées. Vous pouvez lire notre page de docuemntation [paradigme Git vs HTTP](../concepts/git_vs_http) -pour plus de détails. - - - -Si vous voulez créer et gérer un dépôt sur le Hub, votre machine doit être authentifiée. Si vous ne l'êtes pas, consultez -[this section](../quick-start#login). Dans le reste de ce guide, nous supposerons que votre machien est connectée. - -## Création et suppression d'un dépôt - -La première étape est de savoir comment créer et supprimer des dépôts. Vous ne pouvez gérer que des dépôts que vous -possédez (qui sont à votre nom) ou d'une organisation dont vous avez les permissions d'écriture. - -### Créer un dépôt - -Le code ci dessous créé un dépôt vide avec [`create_repo`] et lui donne un nom avec le paramètre `repo_id`. Le `repo_id` est votre namespace suivi -du nom du dépôt: `nom_utilisateur_ou_organisation/nom_depot` - -```py ->>> from huggingface_hub import create_repo ->>> create_repo("lysandre/test-model") -'https://huggingface.co/lysandre/test-model' -``` - -Par défaut, [`create_repo`] créé un dépôt de modèle, mais vous pouvez utiliser le paramètre `repo_type` pour spécifier un autre type de dépôt. Par exemple, si vous voulez créer un dépôt de dataset: - -```py ->>> from huggingface_hub import create_repo ->>> create_repo("lysandre/test-dataset", repo_type="dataset") -'https://huggingface.co/datasets/lysandre/test-dataset' -``` - -Lorsque vous créer un dépôt, vous pouvez définir la visibilité de votre dépôt avec le paramètre `private`. - -```py ->>> from huggingface_hub import create_repo ->>> create_repo("lysandre/test-private", private=True) -``` - -Si vous voulez changer la visibilité du dépôt plus tard, vous pouvez utiliser la fonction [`update_repo_visibility`]. - -### Supprimer un dépôt - -Vous pouvez supprimer un dépôt avec [`delete_repo`]. Assurez vous que vous voulez supprimer ce dépôt avant car c'est un processus irréversible! - -Précisez le `repo_id` du dépôt que vous voulez supprimer: - -```py ->>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset") -``` - -### Dupliquer un dépôt (uniquement pour les spaces) - -Dans certains cas, vous avez besoin de copier les dépôts de quelqu'un d'autre pour l'adapter à votre cas d'utilisation. -C'est possible pour les spaces en utilisant la méthode [`duplicate_space`]. Elle dupliquera le dépôt entier. -Vous aurez toujours besoin de configurer vos propres paramètres (hardware, temps de veille, stockage, variables et secrets). -Consultez notre guide [gérez vos spaces](./manage-spaces) pour plus de détails. - -```py ->>> from huggingface_hub import duplicate_space ->>> duplicate_space("multimodalart/dreambooth-training", private=False) -RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...) -``` - -## Upload et téléchargement de fichiers - -Maintenant que vous avez créé votre dépôt, vous aurez besoin de push des changements dessus et de télécharger des fichiers -de votre dépôt. - -Ces deux sujets méritent leur propre guides. Consultez les guides [upload](./upload) et [téléchargement](./download) -pour apprendre à utiliser vos dépôts. - - -## Branches et tags - -Les dépôts Git utilisent souvent des branches pour enregistrer différentes version d'un même dépôt. -Les tags peuvent aussi être utilisés pour flager un état spécifique de votre dépôt, par exemple, -lors de la sortie d'une version. PLus généralement, on désigne les branches et les tags par le terme [git references](https://git-scm.com/book/en/v2/Git-Internals-Git-References). - -### Créer des branches et de tags - -Vous pouvez créer de nouvelles branches et de nouveaux tags en utilisant [`create_branch`] et [`create_tag`]: - -```py ->>> from huggingface_hub import create_branch, create_tag - -# Créé une branche sur le dépôt d'un space basée sur la branche `main` ->>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker") - -# Créé un tag sur un dépôt de dataset à partir de la branche `v0.1-release` ->>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.") -``` - -Vous pouvez utiliser les fonctions [`delete_branch`] et [`deelte_tag`] de la même manière pour supprimer une branche ou un tag. - -### Lister toutes les branches et les tags - -Vous pouvez aussi lister toutes les références git d'un dépôt en utilisant [`list_repo_refs`]: - -```py ->>> from huggingface_hub import list_repo_refs ->>> 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') - ] -) -``` - -## Changer les paramètres de dépôt - -Les dépôts ont certains paramètres que vous pouvez configurer. La plupart du temps, vous aurez envie de faire ceci à la main -dans la page de paramètre du dépôt dans votre navigateur. Vous devez avoir la permission en mode écriture sur un dépôt pour le -configure (soit en étant le propriétaire ou en faisant partie d'une organisation). Dans cette secction, nous verrons les -paramètres que vous pouvez aussi configurer par le code en utilisant `huggingface_hub`. - -Certains paramètres sont spécifique aux spaces (hardware, variables d'environnement,...). Pour les configurern, consultez notre guide [Gérez vos spaces](../guides/manage-spaces) - -### Changer la visibilité - -Un dépôt peut être public ou privé. Un dépôt privé n'est visible que par vous ou les membres de l'organisation dans laquelle le dépôt est situé. Passez un dépôt en mode privé en faisant ceci: - -```py ->>> from huggingface_hub import update_repo_visibility ->>> update_repo_visibility(repo_id=repo_id, private=True) -``` - -### Renommez votre dépôt - -Vous pouvez renommer votre dépôt sur le Hub en utilisant [`move_repo`]. En utilisant cette même méthode, vous pouvez aussi faire -passer le dépôt d'un utilisateur à une organisation. Lorsque vous faites ainsi, il y a [quelques limitations](https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo) qu'il vous faut connaitre. Par exemple, vous ne pouvez pas transférer le dépôt à -un autre utilisateur. - -```py ->>> from huggingface_hub import move_repo ->>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model") -``` - -## Gérer une copie locale de votre dépôt - -Toutes les actions décrites ci dessus peuvent être faites en utilisant des requêtes HTTP. Cependant, dans certains cas vous -aurez peut-être besoin d'avoir une copie local de votre dépôt et intéragir avec les commandes Git que vous connaissez déjà. - -La classe [`Repository`] vous permet d'intéragir avec des fichiers et des dépôts sur le Hub avec des fonctions similaire aux commandes Git. C'est un wrapper autour des méthodes Git et Git-LFS pour utiliser les commandes git que vous conaissez déjà. Avant de commencer, assurez vous que Git-LFS est bien installé sur votre machine (voir [ici](https://git-lfs.github.com/) pour les instructions d'installation). - - - -[`Repository`] est aujourd'hui deprecated en faveur des alternatives basées sur de http implémentées dans [`HfApi`]. Au vu de son adoption assez large, la suppression complète de [`Repository`] ne sera faite que dans la version `v1.0`. Pour plus de détails, consultez [cette page](./concepts/git_vs_http). - - - -### Utiliser un dépôt local - -Instanciez un objet [`Repository`] avec un chemin vers un dépôt local: - -```py ->>> from huggingface_hub import Repository ->>> repo = Repository(local_dir="//") -``` - -### Cloner - -Le paramètre `clone_from` clone un dépôt à partir de l'ID du dépôt Hugging Face vers un chemin local spécifié avec l'argument `local_dir`: - -```py ->>> from huggingface_hub import Repository ->>> repo = Repository(local_dir="w2v2", clone_from="facebook/wav2vec2-large-960h-lv60") -``` - -`clone_from` peut aussi cloner un dépôt en utilisant un URL: - -```py ->>> repo = Repository(local_dir="huggingface-hub", clone_from="https://huggingface.co/facebook/wav2vec2-large-960h-lv60") -``` - -Vous pouvez combiner le paramètre `clone_from` avec [`create_repo`] pour créer et cloner un dépôt: - -```py ->>> repo_url = create_repo(repo_id="repo_name") ->>> repo = Repository(local_dir="repo_local_path", clone_from=repo_url) -``` - -Vous pouvez aussi configurer un nom d'utilisateur Git et un email vers un dépôt cloné en précisant les paramètres `git_user` et `git_email` lorsque vous clonez un dépôt. Lorsque les utilisateurs feront des commits sur ce dépôt, Git connaitre l'auteur du commit. - -```py ->>> repo = Repository( -... "my-dataset", -... clone_from="/", -... token=True, -... repo_type="dataset", -... git_user="MyName", -... git_email="me@cool.mail" -... ) -``` - -### Branche - -Les branches sont importante pour la collaboration l'expérimentation sans impact sur vos fichiers ou votre code actuel. Changez de branche avec [`~Repository.git_checkout`]. Par exemple, si vous voulez passer de `branche1` à `branche2`: - -```py ->>> from huggingface_hub import Repository ->>> repo = Repository(local_dir="huggingface-hub", clone_from="/", revision='branche1') ->>> repo.git_checkout("branche2") -``` - -### Pull - -[`~Repository.git_pull`] vous permet de mettre à jour une branche local avec des changements d'un dépôt distant: - -```py ->>> from huggingface_hub import Repository ->>> repo.git_pull() -``` - -Utilisez `rebase=True` si vous voulez que vos commits locaux soient opérationnels après que votre branche ai été mise à jour avec les nouveaux commits: - -```py ->>> repo.git_pull(rebase=True) -``` diff --git a/docs/source/fr/guides/search.md b/docs/source/fr/guides/search.md deleted file mode 100644 index 6df3dda91f..0000000000 --- a/docs/source/fr/guides/search.md +++ /dev/null @@ -1,69 +0,0 @@ - - -# Faites des recherches dans le Hub - -Dans ce tutoriel, vous apprendrez à chercher des modèles, des datasets et des spaces du Hub en utilisant `huggingface_hub`. - -## Comment lister les dépôts ? - -La librairie `huggingface_hub` inclus un client HTTP [`HfApi`] pour intéragir avec le Hub. -Ce client peut, entre autres, lister les modèles, les dataset et les spaces enregistrés sur le Hub: - -```py ->>> from huggingface_hub import HfApi ->>> api = HfApi() ->>> models = api.list_models() -``` - -La sortie de [`list_models`] est un itérateur sur les modèles stockés dans le Hub. - -De la même manière, vous pouvez utiliser [`list_datasets`] pour lister les datasets et [`list_spaces`] pour lister les spaces. - -## Comment filtrer des dépôts ? - -Lister les dépôts est très utile, mais vous aurez surement besoin de filtrer votre recherche. -Les helpers ont plusieurs attributs tels que: -- `filter` -- `author` -- `search` -- ... - -Deux de ces paramètres sont assez intuitifs (`author` et `search`) mais qu'en est il de `filter`? -`filter` prend en entrée un objet [`ModelFilter`] (ou [`DatasetFilter`]). Vous pouvez l'instancier -en précisang quels modèles vous voulez filtrer. - -Regaardons comment nous pouvons avoir tous les modèles sur le Hub qui font de la classification -d'images, qui ont été entrainé sur le dataset imagenet et qui utilisent PyTorch. On peut le -faire en utilisant un seul [`ModelFilter`]. Les attributs sont combinés comme des "ET" logiques: - -```py -models = hf_api.list_models( - filter=ModelFilter( - task="image-classification", - library="pytorch", - trained_dataset="imagenet" - ) -) -``` - -Lors du filtrage, vous pouvez aussi trier les modèles en prendre uniquement les premiers -résultats. L'exemple suivant récupère les 5 datasets les plus téléchargés du Hub: - -```py ->>> list(list_datasets(sort="downloads", direction=-1, limit=5)) -[DatasetInfo( - id='argilla/databricks-dolly-15k-curated-en', - author='argilla', - sha='4dcd1dedbe148307a833c931b21ca456a1fc4281', - last_modified=datetime.datetime(2023, 10, 2, 12, 32, 53, tzinfo=datetime.timezone.utc), - private=False, - downloads=8889377, - (...) -``` - - - -Pour explorer tous les filtres disponibles sur le HUb, consultez les pages [modèles](https://huggingface.co/models) et [datasets](https://huggingface.co/datasets) dans votre navigateur, cherchez des paramètres et regardez les valeurs dans l'URL. - diff --git a/docs/source/fr/guides/upload.md b/docs/source/fr/guides/upload.md deleted file mode 100644 index c3af60ff4a..0000000000 --- a/docs/source/fr/guides/upload.md +++ /dev/null @@ -1,596 +0,0 @@ - - -# Upload des fichiers vers le Hub - -Partager vos fichiers et votre travail est un aspect important du Hub. La librairie `huggingface_hub` offre plusieurs options pour upload vos fichiers vers le Hub. Vous pouvez utiliser ces fonction indépendemment ou les intégrer à votre librairie, pour rendre l'intéraction avec le Hub plus pratique pour vos utilisateurs. Ce guide vous montrera comment push des fichiers: - -- Sans utiliser Git. -- Qui sont très volumineux avec [Git LFS](https://git-lfs.github.com/). -- Avec le gestionnaire de contexte des `commit`. -- Avec la fonction [`~Repository.push_to_hub`]. - -Lorsque vous voulez upload des fichiers sur le HUb, vous devez vous connecter à votre compte Hugging Face: - -- Connectez vous à votre compte Hugging Face avec la commande suivante: - - ```bash - huggingface-cli login - # Ou en utilisant une variable d\'environnement - huggingface-cli login --token $HUGGINGFACE_TOKEN - ``` - -- Sinon, vous pouvez vous connecter par le code en utilisant [`login`] dans un notebook ou un script: - - ```python - >>> from huggingface_hub import login - >>> login() - ``` - - Si lancé dans un notebook Jupyter ou Colaboratory, [`login`] démarera un widget - depuis lequel vous pouvez rentrer vos token d'authentification Hugging Face. Sinon, - un message sera affiché dans le terminal. - - Il est aussi possible de se connecter par le code sans widget en passant directement - votre token à la méthode [`login`]. Si vous faites ainsi, faites attention lors du - partage de votre notenook. Une bonne pratique est de charger le token d'un trousseau - sécurisé aulieu de le sauvegarder en clair dans votre notebook. - -## Upload un fichier - -Une fois que vous avez créé un dépôt avec [`create_repo`], vous puovez upload un fichier sur votre dépôt en utilisant [`upload_file`]. - -Précisez le chemin du fichier à upload, le nom du dépôt dans lequel vous voulez ajouter le fichier et l'endroit du dépôt dans lequel vous voulez qu'il soit. Selon votre type de dépôt, vous pouvez, facultativement définir le type de dépôt à `dataset`, `model` ou `space`. - -```py ->>> from huggingface_hub import HfApi ->>> api = HfApi() ->>> api.upload_file( -... path_or_fileobj="/path/to/local/folder/README.md", -... path_in_repo="README.md", -... repo_id="username/test-dataset", -... repo_type="dataset", -... ) -``` - -## Upload un dossier - -Utilisez la fonction [`upload_folder`] pour upload un dossier local vers un dépôt. Précisez le chemin du dossier local, -où vous voulez que le dossier soit upload dans le dépôt et le nom du dépôt dans lequel vous voulez ajouter le dossier. Selon -votre type de dépôt, vous pouvez facultativement définir le type de dépôt à `dataset`, `model` ou `space`. - -```py ->>> from huggingface_hub import HfApi ->>> api = HfApi() - -# Upload tout le contenu du fichier local vers votre space distant -# Par défaut, les fichiers sont upload à la racine du dépôt ->>> api.upload_folder( -... folder_path="/path/to/local/space", -... repo_id="username/my-cool-space", -... repo_type="space", -... ) -``` - -Par défaut, le fichier `.gitignore` sera pris en compte pour savoir quels fichiers doivent être commit ou pas. Par défaut, nous vérifions si un fichier `.gitignore` est présent dans un commit, s'il n'y en a pas, nous vérifions s'il existe sur le Hub. Notez que seul un fichier `.gitignore` présent à la racine du chemin sera utilisé. Nous ne cherchons pas de fichiers `.gitignore` dans les sous-dossiers. - -Si vous ne voulez pas utiliser un fichier `.gitignore` codé en dur, vous pouvez utiliser les arguments `allow_patterns` et `ignore_patterns` pour filtrer les fichiers à upload. Ces paramètres prennent en entrée soit un pattern, soit une liste de patterns. Plus d'informations sur ce que sont les patterns [ici](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). Si `allow_patterns` et `ignore_patterns` sont donnés, les deux contraintes s'appliquent. - -En plus du fichier `.gitignore` et des patterns allow/ignore, n'importe quel dossier `.git/` présent dans n'import quel sous chemin sera ignoré. - -```py ->>> api.upload_folder( -... folder_path="/path/to/local/folder", -... path_in_repo="my-dataset/train", # Upload vers un dossier spécifique -... repo_id="username/test-dataset", -... repo_type="dataset", -... ignore_patterns="**/logs/*.txt", # Ignore tous les logs en .txt -... ) -``` - -Vous pouvez aussi utiliser l'argument `delete_patterns` pour préciser les fichiers que vous voulez supprimer du dépôt -dans le même commit. Cet argument peut-être utile si voulez nettoyer un fichier distant avant de push vos fichiers dedans -et que vous ne savez pas quels fichiers existent déjà. - -L'exemple ci-dessous upload le fichier local `./logs` vers le fichier distant `/experiment/logs/`. Seul les fichiers textuels -sont upload. Avant ça, tous les logs précédents sur le dépôt sont supprimés, le tout dans un seul commit. -```py ->>> api.upload_folder( -... folder_path="/path/to/local/folder/logs", -... repo_id="username/trained-model", -... path_in_repo="experiment/logs/", -... allow_patterns="*.txt", # Upload tous les fichiers textes locaux -... delete_patterns="*.txt", # Supprime tous les fichiers textes distants avant d'upload -... ) -``` - -## Upload depuis le CLI - -Vous pouvez utiliser la commande `huggingface-cli upload` depuis le terminal pour upload directement des fichiers vers le Hub. En interneelle utilise aussi les helpers [`upload_file`] et [`upload_folder`] décrits ci dessus. - -Vous pouvez upload un unique fichier ou un dossier entier: - -```bash -# Cas d'usage: huggingface-cli upload [repo_id] [local_path] [path_in_repo] ->>> huggingface-cli upload Wauplin/my-cool-model ./models/model.safetensors model.safetensors -https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors - ->>> huggingface-cli upload Wauplin/my-cool-model ./models . -https://huggingface.co/Wauplin/my-cool-model/tree/main -``` - -`local_path` et `path_in_repo` sont optionnels et peuvent être déterminés implicitement. Si `local_path` n'est pas défini, -l'outil vérifiera si un dossier local ou un fichier a le même nom que le `repo_id`. Si ce n'est pas le cas, son contenu -sera upload. Sinon, une exception est levée demandant à l'utilisateur de définir exxplicitement `local_path`. Dans tous -les cas, si `path_in_repo` n'est pas défini, les fichiers sont upload à la racine du dépôt. - -Pour plus de détails sur la commande uplaod du CLI, consultez le[guide CLI](./cli#huggingface-cli-upload). - -## Fonctionnalités avancées - -Dans la plupart des cas, vous n'aurez besoin de rien de plus que [`upload_file`] et [`upload_folder`] pour upload -vos fichiers sur le Hub. Cependant, `huggingface_hub` a des fonctionnalités plus avancées pour rendre le processus -plus simple. Regardons les dans la suite de ce guide. - - -### Uploads non bloquants - -Dans certains cas, vous aura envie de push des données sans blocker votre thread principale. C'est particulièrement -utile pour upload des logs des artefacts tout en continuant à entrainer un modèle. Pour ce faire, vous pouvez utiliser -l'argument `run_as_future` dans [`upload_file`] et [`upload_folder`]. La méthode renvera un objet -[`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#future-objects) que vous pouvez utiliser -pour vérifier le statu de l'upload. - -```py ->>> from huggingface_hub import HfApi ->>> api = HfApi() ->>> future = api.upload_folder( # Upload en arrière plan (action non bloquante) -... repo_id="username/my-model", -... folder_path="checkpoints-001", -... run_as_future=True, -... ) ->>> future -Future(...) ->>> future.done() -False ->>> future.result() # Attend que l'upload soit finie (action bloquante) -... -``` - - - -Le tâche d'arrière plan sont mise dans une queue en utilisat `run_as_future=True`. Ceci signfie que vous êtes sur que -la tâche sera exécutée dans le bon ordre. - - - -Même si les tâches en arrière plan sont la plupart du temps utiles pour upload des données ou créer des commits, vous -pouvez mettre dans la queue la méthode que vous voulez en utilisant [`run_as_future`]. Par exemple, vous pouvez l'utiliser -pour créer un dépôt puis upload des données dessus en arrière plan. L'argument `run_as_future` dans les méthodes d'upload -est juste un alias autour de cette méthode. - -```py ->>> from huggingface_hub import HfApi ->>> api = HfApi() ->>> api.run_as_future(api.create_repo, "username/my-model", exists_ok=True) -Future(...) ->>> api.upload_file( -... repo_id="username/my-model", -... path_in_repo="file.txt", -... path_or_fileobj=b"file content", -... run_as_future=True, -... ) -Future(...) -``` - -### Upload un dossier par morceaux - -[`upload_folder`] rend l'upload d'un dossier entier sur le Hub facile. Cependant, pour des fichiers volumineux (des -milliers de fichiers ou des centaines de GB), cette tâche peut rester ardue. Si vous avez un dossier avec beaucoup de fichiers, -vous aurez peut-être envie de l'upload en plusieurs commits. Si vous avez une erreur ou des problèmes de connection pendant -l'upload, vous n'aurez surement pas envie de tout recommencer à zéro. - -Pour upload un dossier en plusieurs commits, passez simplement l'argument `multi_commits=True`. En arrière plan, -`huggingface_hub` listera tous les fichiers pour upload/supprimer et découper le tout en plusieurs commits. La -"stratégie" (i.e. comment les commits sont séparés) est basée sur le nombre et la taille des fichiers à upload. Une -pull request sera ouverte sur le Hub pour push tous les commits. Une fois la pull request prête, les commits sont -regroupés en un seul commit. Si le processu est interrompu avant sa fin, vous pouvez relancer votre script pour continuer -l'upload. La pull request créé sera automatiquement détectée et l'upload continuera là où il a été arrêté. Il est -recommandé d'utiliser l'argument `multi_commits_verbose=True` pour avoir une meilleure compréhension de l'upload et -de sont avancement. - -L'exemple ci dessous uploadera plusieurs dossiers vers un dataset en plusieurs commits. Une pull request sera créé sur le -Hub, elle sera merge automatiquement une fois que l'upload est finie. Si vous préférez que la pull request reste ouverte -pour pouvoir faire une review manuelle, utiliser `create_pr=True`. - -```py ->>> upload_folder( -... folder_path="local/checkpoints", -... repo_id="username/my-dataset", -... repo_type="dataset", -... multi_commits=True, -... multi_commits_verbose=True, -... ) -``` - -Si vous voulez un meilleur controle de la stratégie d'upload (i.e. les commits créés), vous pouvez consulter les -méthodes bas niveau [`plan_multi_commits`] et [`create_commits_on_pr`]. - - - -`multi_commits` est toujours une fonctionnalité expérimentale. Son API et son comportement pourraient changer dans le futur -sans avertissement préalable. - - - -### Uploads planifiées - -Le Hub Hugging Face rend facile l'enregistrement et le versionning de données. Cependant, il y a des limitations lorsqu'on met à jour un même fichier des milliers de fois. Par exemple, vous aurez peut-être envie d'enregistrer les logs d'un processus d'entrainement ou le feedback des utilisateur sur un space déployé. Dans ces deux cas, upload la donnée en tant que dataset sur le Hub semble logique, mais il peut-être difficile de le faire correctement. La raison principale est que vous ne voulez pas versionner toutes les mises à jour de vos donnée, car cela rendrait le dépôt git inutilisable. La classe [`CommitScheduler`] offre une solution à ce problème. - -L'idée est de faire tourner une tâche en arrière plan qui va push à intervalles réguliers un dossier local vers le Hub. -Supposons que vous avez un space Gradio qui prend en entré du texte et qui génére deux traductions. Dans ce cas, l'utilisateur peut sélectionner sa traduction préférée. Pour chaque traduction, vous voulez enregistrer l'input, output et les préférences de l'uitlisateur pour analyser les résultats. -C'est un cas d'usage parfait pour [`CommitScheduler`]; vous voulez enregistrer des données sur le Hub (potentiellement des millions -de retour utilisateurs) mais vous n'avez pas besoin d'enregistrer en temps réel chaque input de l'utilisateur. Aulieu de ça, -vous pouvez enregistrer les données en local dans un fichier JSON et l'upload toutes les 10 minutes. Par exemple: - -```py ->>> import json ->>> import uuid ->>> from pathlib import Path ->>> import gradio as gr ->>> from huggingface_hub import CommitScheduler - -# Définit le fichier dans lequel il faut enregistrer les données. On utilise le UUID pour s'assurer de ne pas overwrite des données existantes d'un feedback préalable ->>> feedback_file = Path("user_feedback/") / f"data_{uuid.uuid4()}.json" ->>> feedback_folder = feedback_file.parent - -# Planifie des uploads réguliers. Le dépôt distant et le dossier local sont créés s'il n'existent pas déjà ->>> scheduler = CommitScheduler( -... repo_id="report-translation-feedback", -... repo_type="dataset", -... folder_path=feedback_folder, -... path_in_repo="data", -... every=10, -... ) - -# Définit la fonction qui sera appelée lorsque l'utilisateur enverra son feedback ->>> def save_feedback(input_text:str, output_1: str, output_2:str, user_choice: int) -> None: -... """ -... Append input/outputs and user feedback to a JSON Lines file using a thread lock to avoid concurrent writes from different users. -... """ -... with scheduler.lock: -... with feedback_file.open("a") as f: -... f.write(json.dumps({"input": input_text, "output_1": output_1, "output_2": output_2, "user_choice": user_choice})) -... f.write("\n") - -# Lancement de Gradio ->>> with gr.Blocks() as demo: ->>> ... # Définition de la démo Gradio, ne pas oublier d'utiliser `save_feedback` ->>> demo.launch() -``` - -Et c'est tout! Lesinputs/outputs et feedback des utilisateur seront disponible en tant que dataset sur le Hub. En utilisant un unique nom de fichier JSON, vous êtes sur que vous n'overwriterez pas de données qui se pushent en même sur le même dépôt. - -Pour plus de détails sur le [`CommitScheduler`], voici ce que vous devez savoir: -- **append-only:** - Il est supposé que vous ne faites qu'ajouter du contenu au dossier. Vous devez uniquement ajouter des données à - des fichiers existants ou créer de nouveaux fichier. Supprimer ou overwrite des fichiers pourrait corrompre votre - dépôt. -- **historique git:** - Le planificateur commitera le dossier toutes les `every` minutes. Pour éviter de polluer le dépôt git, il est reccomadé - de mettre une valeur minimal d'aumoins 5 minutes. Par ailleurs, les planificateur est créé pour éviter les commits - vides. Si aucun nouveau contenu n'est détecté dans le dossier, le commit planifié sera abandonné. -- **erreurs:** - Le planificateur tourne en tant que thread en arrière plan. Il commance quand vous instantiez la classe et ne s'arrête - jamais. En particulier, si une erreur arrive pendant l'upload (par exemple un problème de connexion), le planificateur - ignorera cette erreur et réessaiera au prochain commit planifié -- **sécurité des threads:** - Dans la plupart des cas, il est plus sécuriser de supposer que vous pouvez écrire dans un fichier sans se soucier des - fichiers bloqués. Le planificateur de crashera pas et ne sera pas corrumpu si vous écrivez du contenue sur le dossier - pendant l'upload. En pratique, il est possible que de telles problèmes arrivent pour des applications lourdes. Dans - ce cas, nous conseillons d'utiliser le lock `scheduler.lock` pour s'assurer que le thread soient sécurisés. Le lock - est bloquée uniquement lorsque le planificateur scan le dossier à la recherche de changements, pas lors de l'upload - de données. Vous pouvez sans problème supposer que ça n'affectera pas l'expérience utilisateur sur votre space. - -#### Space persistence demo - -Faire persister des données d'un space vers un dataset sur le Hub est le cas d'usage le plus courant pour [`CommitScheduler`]. -Selon les cas d'usages, vous aurez peut-être envie de structurer vos données différemment. La structure doit être assez robuste -pour gérer simultanément la connexion d'un utilisateur et le redémarrage ce qui implique souvent la génération d'UUIDs. -En plus de la robustesse, vous devez upload des données dans un format lisible pour les librairies de datasets 🤗, afin -de pouvoir les réuitiliser plus tard. Nous avons créé un [space](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) -qui montre comment enregistrer plusieurs formats de données ddifférents (vous aurez peut-être besoin de l'adapter à vos -propres besoins). - -#### Uploads personnalisées - -[`CommitScheduler`] suppose que votre donnée est append-only. Cependant, vous aurez peut-être besoin de -customiser la manière dont la donnée est uploadée. Vous pouvez faire ça en créant une classe qui hérite -de [`CommitScheduler`] et qui overvrite la méthode `push_to_hub`. Vous êtes sur que cette méthode -sera appelée toutes les `every` minutes dans un thread en arrière plan. Vous n'avez pas besoin de vous -occuper des erreurs et des utilisations simultanées, mais vous devez faire attention à d'autres aspects, -tels que les commits vides ou les données dupliquées. - -Dans l'exemple simplifié ci dessous, nous faisons un overwrite de `push_to_hub` pour ziper tous les fichiers PNG -dans une unique archive pour éviter de surcharger le dépôt sur le Hub: - -```py -class ZipScheduler(CommitScheduler): - def push_to_hub(self): - # 1. Liste les fichiers PNG - png_files = list(self.folder_path.glob("*.png")) - if len(png_files) == 0: - return None # return directement si rien à commit - - # 2. Zip les fichiers PNG dans une unique archive - with tempfile.TemporaryDirectory() as tmpdir: - archive_path = Path(tmpdir) / "train.zip" - with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as zip: - for png_file in png_files: - zip.write(filename=png_file, arcname=png_file.name) - - # 3. Upload l'archive - self.api.upload_file(..., path_or_fileobj=archive_path) - - # 4. Supprime les fichiers PNG locaux pour éviter de les ré-upload plus tard - for png_file in png_files: - png_file.unlink() -``` - -Lorsque vous modifier `push_to_hub` en faisant un overwrite, vous avez accès aux attributs de [`CommitScheduler`], plus précisément: -- Le client [`HfApi`]: `api` -- Les paramètres du dossier: `folder_path` et `path_in_repo` -- Les paramètres du dépôt: `repo_id`, `repo_type` et `revision` -- Le lock du thread `lock` - - - -Pour plus d'exemples de planififcateurs personnalisés, consultez notre -[space de démo](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) contenant différentes implementations -dépendant de votre cas d'usage. - - - -### create_commit - -Les fonctions [`upload_file`] et [`upload_folder`] sonr des APIs de haut niveau qui sont généralement assez pratiques à -utiliser. Il est recommandé d'essayer ces fonction en premier si vous ne voulez pas travailler à un plus bas niveau. -Cependant, si vous voulez travailler au niveau du commit, vous pouvez utiliser directement la fonction [`create_commit`]. - -Il y a trois types d'opérations supportées par [`create_commit`]: - -- [`CommitOperationAdd`] upload un fichier vers le Hub. Si le fichier existe déjà, le contenu du fichier seront overwrite. Cette opération accepte deux arguments: - - `path_in_repo`: le chemin vers le dépôt sur lequel vous voulez upload un fichier. - - `path_or_fileobj`: soit le chemin vers un fichier sur votre machine ou un fichier lui même. C'est le contenu du fichier à upload vers le Hub. - -- [`CommitOperationDelete`] supprime un fichier ou un dossier d'un dépôt. Cette opération accepte `path_in_repo` en argument. - -- [`CommitOperationCopy`] copie un fichier d'un dépôt. Cette opération prend en entré trois arguments: - - - `src_path_in_repo`: le chemin vers le dépôt du fichier à copier. - - `path_in_repo`: le chemin vers le dépôt sur lequel le fichier doit être copié. - - `src_revision`: argument optionnel - la révision du fichier à copier si vous voulez copier un fichiers d'une branche/version différente de main. - -Par exmeple, si vous voulez upload deux fichiers et supprimer dossier: - -1. Utilisez la bonne `CommitOperation` pour ajouter ou supprimer un fichier en supprimer un dossier: - -```py ->>> from huggingface_hub import HfApi, CommitOperationAdd, CommitOperationDelete ->>> api = HfApi() ->>> operations = [ -... CommitOperationAdd(path_in_repo="LICENSE.md", path_or_fileobj="~/repo/LICENSE.md"), -... CommitOperationAdd(path_in_repo="weights.h5", path_or_fileobj="~/repo/weights-final.h5"), -... CommitOperationDelete(path_in_repo="old-weights.h5"), -... CommitOperationDelete(path_in_repo="logs/"), -... CommitOperationCopy(src_path_in_repo="image.png", path_in_repo="duplicate_image.png"), -... ] -``` - -2. Passez vos opérations à [`create_commit`]: - -```py ->>> api.create_commit( -... repo_id="lysandre/test-model", -... operations=operations, -... commit_message="Upload my model weights and license", -... ) -``` - -En plus d'[`upload_file`] et [`upload_folder`], les fonctions suivante utilisent aussi [`create_commit`] en arrière plan: - -- [`delete_file`] supprime un fichier d'un dépôt sur le Hub. -- [`delete_folder`] supprime un dossier d'un dépôt sur le Hub. -- [`metadata_update`] Met à jour les métadonnées d'un dépôt. - -Pour plus d'informations, consultez la référence [`HfApi`]. - -### Preupload des fichier LFS avant le commit - -Dans certains cas, vous aurez peut-être envie d'upload d'immense fichiers vers S3 **avant** de faire le commit. Par -exemple, si vous commitez un dataset dans plusieurs shards qui sont générées in-memory, vous aurez besoin d'upload -les shards une par une pour éviter de manquer de mémoire. Une solution est d'upload chaque shard comme commit séparé -sur le dépôt. Tout en étant parfaitement valide, cette solution a le désavantage de brouiller l'historique git en -générant de dizaines de commits. Pour éviter ce problème, vous pouvez upload vos fichier un par un vers S3 puis créer -un seul commit à la fin. C'est possible en utilisatn [`preupload_lfs_files`] en combinaison avec [`create_commit`]. - - - -Cette méthode est complexe. Utiliser directement [`upload_file`], [`upload_folder`] ou [`create_commit`] aulieu de -gérer la logique bas niveau des fichiers qui s'uploadent en avance est la meilleur manière ed faire dans la plupart -des cas. Le problème principal de [`preupload_lfs_files`] est que tant que le commit est fait, les fichiers ne sont pas -accessibles sur le dépôt du Hub. Si vous avez une question, n'hésitez pas à nous ping sur Discord ou en créant -une issue GitHub. - - - -Voici un exemple simple illustrant comme pre-upload des fichiers: - -```py ->>> from huggingface_hub import CommitOperationAdd, preupload_lfs_files, create_commit, create_repo - ->>> repo_id = create_repo("test_preupload").repo_id - ->>> operations = [] # Liste de toutes les objets `CommitOperationsAdd` qui seront générés ->>> for i in range(5): -... content = ... # génère un contenu binaire -... addition = CommitOperationAdd(path_in_repo=f"shard_{i}_of_5.bin", path_or_fileobj=content) -... preupload_lfs_files(repo_id, additions=[addition]) -... operations.append(addition) - ->>> # Créé un commit ->>> create_commit(repo_id, operations=operations, commit_message="Commit all shards") -``` - -Premièrement, nous créons les objets [`CommitOperationAdd`] un par un. Dans un vrai exemple, ils contiendraient -les shard générées. Chaque fichier est uploadé avant de générer le suivant. Pendant l'étape [`preupload_lfs_files`], -**L'objet `CommitoperationAdd` est muté**. Vous devez uniquement l'utiliser pour le passer directement à [`create_commit`]. -Le changement principal sur l'objet est **la suppression du contenu binaire**, ce qui signifie que le ramasse miette -le supprimera si vous ne stockez pas une autre référence à ce contenu. C'est un mécanisime prévu car nous ne voulons pas -garder en mémoire le contenu qui est déjà upload. Enfin, nous créons un commit en passant toutes les opérations à -[`create_commit`]. Vous pouvez passer des opérations supplémentaires (add, delete ou copy) qui n'ont pas encore été -gérées et elles le seront correctement. - -## Quelques astuces pour les uploads volumineux - -Il y a des limitations à connaitre lors de l'utilisation de grandes quantités de données sur votre dépôt. Étant donné le délai pour transférer -la donnée, faire un upload pour avoir une erreur à la fin du processus, que ce soit sur hf.co ou en local, peut être très frustrant. - -Consultez notre guide sur les [limitations des dépôts et recommendations](https://huggingface.co/docs/hub/repositories-recommendations) afin de connaitre les bonnes pratiques sur la structuration de dépôts sur le Hub. Maintenant, continuons avec des conseils pratiques pour faire en sorte que vos upload fonctionnent de la manière la plus fluide possible. - -- **Commencez petit**: Nous vous recommandons de commencer avec une petite quantité de données pour tester votre script -d'upload. Ce sera plus facile d'itérer sur une script lorsque les erreur ne prennent que très peu de temps à arriver. -- **Attendez vous à avoir des erreurs**: Déplacer de grandes quantités de donées est un vrai challenge. Vous ne savez -pas ce qui peut se passer, mais il est troujours mieux de considérer que quelque chose va malfonctionner aumoins une fois, -que ce soit votre machine, votre connexion, ou nos serveurs. Par exemple, si vous comptez upload un grand nombre de fichiers, -il vaut mieux garder une trace locale des fichiers que vous avez déjà upload avant d'upload le dossier suivant. Normalement -un fichier LFS déjà commit ne sera jamais re-uploadé deux fois mais le vérifier côté client peut quand même vous faire -gagner du temps. -- **Utilisez `hf_transfer`**: c'est une [librarie basée sur Rust](https://github.com/huggingface/hf_transfer) qui a pour -but d'accélérer les upload sur les machines avec une grande bande passante. Pour l'utiliser, vous devez l'installer -(`pip install hf_transfer`) et l'activer en définissant la variable d'environnement `HF_HUB_ENABLE_HF_TRANSFER=1`. Vous -pouvez enfuiste utiliser `huggingface_hub` normalement. Disclaimer: c'est un outil complexe. Il est testé et prêt à la -mise en production mais n'a pas toutes les fonctionnalités user-friendly telles que la gestion d'erreurs avancée ou les -proxys. Pour plus de détails, consultez cette [section](https://huggingface.co/docs/huggingface_hub/hf_transfer). - - - -Les barres de progression sont supportées par `hf_transfer` à partir de la version `0.1.4`. Mettez à jour (`pip install -U hf_transfer`) si vous comptez activer les uploads rapides. - - - -## (approche historique) Uploadez des fichiers avec Git LFS - -Toutes les méthodes décrites ci-dessus utilisent l'API du Hub pour upload des fichiers. C'est la méthode recommandée pour -upload des fichiers sur le Hub. Toutesfois, nous fournissons aussi [`Repository`], un wrapper autour de git pour gérer -un dépôt local. - - - -Bien que [`Repository`] ne soit pas réellement deprecated, nous recommandons l'utilisation des méthodes basées sur -l'HTTP décrite ci dessus. Pour plus de détails sur cette recommandation, consultez [ce guide](../concepts/git_vs_http) -qui explique les différences fondamentales entre les deux approches. - - - -Git LFS gère automatiquement des fichiers d'une taille supérieure à 10MB. Mais pour les fichiers très larges (>5GB), vous devez installer un agent -de transfert personnalisé pour Git LFS: - -```bash -huggingface-cli lfs-enable-largefiles -``` - -Vous devez faire cette installation pour chaque dépôt qui a un fichier de taille supérieure à 5GB. Une fois installé, vous pourrez push -des fichiers volumineux. - -### Gestionnaire de contexte de commit - -Le gestionnaire de contexte de `commit` gère quatre des commandes les plus utilisées sur Git: pull, add, commit et push. `git-lfs` traque automatiquement n'importe quel fichier d'une taille supérieure à 10MB. Dans les exemples suivant, le Le gestionnaire de contexte de `commit`: - -1. Pull depuis le dépôt `text-files`. -2. Ajoute un changment fait à `file.txt` -3. Commit le changement. -4. Push le changement vers le dépôt `text-files`. - -```python ->>> from huggingface_hub import Repository ->>> with Repository(local_dir="text-files", clone_from="/text-files").commit(commit_message="My first file :)"): -... with open("file.txt", "w+") as f: -... f.write(json.dumps({"hey": 8})) -``` - -Voici un autre exemple expliquant comment utiliser le gestionnaire de contexte de `commit` pour sauvegarder et -upload un fichier vers un dépôt: - -```python ->>> import torch ->>> model = torch.nn.Transformer() ->>> with Repository("torch-model", clone_from="/torch-model", token=True).commit(commit_message="My cool model :)"): -... torch.save(model.state_dict(), "model.pt") -``` - -Définissez `blocking=False` si vous voulez push vous commits de manière asynchrone. Les comportements non bloquants sont utiles quand vous voulez continuer à faire tourner un script lorsque vous pushez vos commits. - -```python ->>> with repo.commit(commit_message="My cool model :)", blocking=False) -``` - -Vous pouvez vérifier le statut de votre push avec la méthode `command_queue`: - -```python ->>> last_command = repo.command_queue[-1] ->>> last_command.status -``` - -Référez vous à la table ci dessous pour la liste de statuts possibles: - -| Statut | Description | -| -------- | ------------------------------------ | -| -1 | Le push est en cours | -| 0 | Le push s'est fini sans erreurs. | -| Non-zero | Il y a eu une erreur. | - -Lorsque vous utilisez `blocking=False`, les commandes sont suivies, et votre script se finira uniquement lorsque toues les push sont finis, même si d'autres erreurs arrivent dans votre script. Voici des commandes utiles pour vérifier le statut d'un push: - -```python -# Inspecte une erreur ->>> last_command.stderr - -# Vérifie si un push est fini ou en cours ->>> last_command.is_done - -# Vérifie si une commande push a donné une erreur ->>> last_command.failed -``` - -### push_to_hub - -la classe [`Repository`] a une fonction [`~Repository.push_to_hub`] pour ajouter des fichiers, faire un commit et les push vers un dépôt. A la différence du gestionnaire de contexte de `commit`, vous aurez besoin de pull depuis un dépôt d'abord avant d'appeler [`~Repository.push_to_hub`]. - -Par exemple, si vous avez déjà cloné un dépôt du Hub, vous pouvez initialiser le `repo` depuis le chemin local: - -```python ->>> from huggingface_hub import Repository ->>> repo = Repository(local_dir="path/to/local/repo") -``` - -Mettez à jour votre clone local avec [`~Repository.git_pull`] et pushez ensuite votre fichier vers le Hub: - -```py ->>> repo.git_pull() ->>> repo.push_to_hub(commit_message="Commit my-awesome-file to the Hub") -``` - -Cependant si vous n'êtes pas prêt à push un fichier, vous pouvez utiliser [`~Repository.git_add`] et [`~Repository.git_commit`] pour simplement add et commit votre fichier: - -```py ->>> repo.git_add("path/to/file") ->>> repo.git_commit(commit_message="add my first model config file :)") -``` - -Une fois que vous êtes prêt, push le fichier vers votre dépôt avec [`~Repository.git_push`]: - -```py ->>> repo.git_push() -```