From cbde7dc797b7317f28369d8a8d31ca00699507f6 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 9 Dec 2023 13:39:46 +0100 Subject: [PATCH 001/129] Translated toctree & git_vs_htttp --- docs/source/fr/_redirects.yml | 14 + docs/source/fr/_toctree.yml | 84 +++ docs/source/fr/concepts/git_vs_http.md | 70 +++ docs/source/fr/guides/cli.md | 455 ++++++++++++++ docs/source/fr/guides/collections.md | 227 +++++++ docs/source/fr/guides/community.md | 149 +++++ docs/source/fr/guides/download.md | 202 ++++++ docs/source/fr/guides/hf_file_system.md | 109 ++++ docs/source/fr/guides/inference.md | 336 ++++++++++ docs/source/fr/guides/inference_endpoints.md | 259 ++++++++ docs/source/fr/guides/integrations.md | 285 +++++++++ docs/source/fr/guides/manage-cache.md | 543 ++++++++++++++++ docs/source/fr/guides/manage-spaces.md | 362 +++++++++++ docs/source/fr/guides/model-cards.md | 360 +++++++++++ docs/source/fr/guides/overview.md | 131 ++++ docs/source/fr/guides/repository.md | 243 ++++++++ docs/source/fr/guides/search.md | 70 +++ docs/source/fr/guides/upload.md | 579 ++++++++++++++++++ docs/source/fr/guides/webhooks_server.md | 199 ++++++ docs/source/fr/index.md | 60 ++ docs/source/fr/installation.md | 160 +++++ docs/source/fr/package_reference/cache.md | 59 ++ docs/source/fr/package_reference/cards.md | 78 +++ .../fr/package_reference/collections.md | 24 + docs/source/fr/package_reference/community.md | 34 + .../environment_variables.md | 175 ++++++ .../fr/package_reference/file_download.md | 38 ++ docs/source/fr/package_reference/hf_api.md | 132 ++++ .../fr/package_reference/hf_file_system.md | 16 + .../fr/package_reference/inference_client.md | 109 ++++ .../package_reference/inference_endpoints.md | 42 ++ docs/source/fr/package_reference/login.md | 24 + docs/source/fr/package_reference/mixins.md | 41 ++ docs/source/fr/package_reference/overview.md | 7 + .../source/fr/package_reference/repository.md | 51 ++ .../fr/package_reference/space_runtime.md | 37 ++ .../fr/package_reference/tensorboard.md | 19 + docs/source/fr/package_reference/utilities.md | 260 ++++++++ .../fr/package_reference/webhooks_server.md | 84 +++ docs/source/fr/quick-start.md | 157 +++++ 40 files changed, 6284 insertions(+) create mode 100644 docs/source/fr/_redirects.yml create mode 100644 docs/source/fr/_toctree.yml create mode 100644 docs/source/fr/concepts/git_vs_http.md create mode 100644 docs/source/fr/guides/cli.md create mode 100644 docs/source/fr/guides/collections.md create mode 100644 docs/source/fr/guides/community.md create mode 100644 docs/source/fr/guides/download.md create mode 100644 docs/source/fr/guides/hf_file_system.md create mode 100644 docs/source/fr/guides/inference.md create mode 100644 docs/source/fr/guides/inference_endpoints.md create mode 100644 docs/source/fr/guides/integrations.md create mode 100644 docs/source/fr/guides/manage-cache.md create mode 100644 docs/source/fr/guides/manage-spaces.md create mode 100644 docs/source/fr/guides/model-cards.md create mode 100644 docs/source/fr/guides/overview.md create mode 100644 docs/source/fr/guides/repository.md create mode 100644 docs/source/fr/guides/search.md create mode 100644 docs/source/fr/guides/upload.md create mode 100644 docs/source/fr/guides/webhooks_server.md create mode 100644 docs/source/fr/index.md create mode 100644 docs/source/fr/installation.md create mode 100644 docs/source/fr/package_reference/cache.md create mode 100644 docs/source/fr/package_reference/cards.md create mode 100644 docs/source/fr/package_reference/collections.md create mode 100644 docs/source/fr/package_reference/community.md create mode 100644 docs/source/fr/package_reference/environment_variables.md create mode 100644 docs/source/fr/package_reference/file_download.md create mode 100644 docs/source/fr/package_reference/hf_api.md create mode 100644 docs/source/fr/package_reference/hf_file_system.md create mode 100644 docs/source/fr/package_reference/inference_client.md create mode 100644 docs/source/fr/package_reference/inference_endpoints.md create mode 100644 docs/source/fr/package_reference/login.md create mode 100644 docs/source/fr/package_reference/mixins.md create mode 100644 docs/source/fr/package_reference/overview.md create mode 100644 docs/source/fr/package_reference/repository.md create mode 100644 docs/source/fr/package_reference/space_runtime.md create mode 100644 docs/source/fr/package_reference/tensorboard.md create mode 100644 docs/source/fr/package_reference/utilities.md create mode 100644 docs/source/fr/package_reference/webhooks_server.md create mode 100644 docs/source/fr/quick-start.md diff --git a/docs/source/fr/_redirects.yml b/docs/source/fr/_redirects.yml new file mode 100644 index 0000000000..6ab1ffef13 --- /dev/null +++ b/docs/source/fr/_redirects.yml @@ -0,0 +1,14 @@ +# Move "how-to" pages to the guides/ folder +how-to-cache: guides/manage-cache +how-to-discussions-and-pull-requests: guides/community +how-to-downstream: guides/download +how-to-inference: guides/inference +how-to-manage: guides/repository +how-to-model-cards: guides/model-cards +how-to-upstream: guides/upload +search-the-hub: guides/search +guides/manage_spaces: guides/manage-spaces +package_reference/inference_api: package_reference/inference_client + +# Alias for hf-transfer description +hf_transfer: package_reference/environment_variables#hfhubenablehftransfer \ No newline at end of file diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml new file mode 100644 index 0000000000..5ee183856a --- /dev/null +++ b/docs/source/fr/_toctree.yml @@ -0,0 +1,84 @@ +- title: "Get started" + sections: + - local: index + title: Home + - local: quick-start + title: Quickstart + - local: installation + title: Installation +- title: "Guides et instructions" + sections: + - local: guides/overview + title: Vue d'ensemble + - local: guides/download + title: Télécharger les fichiers + - local: guides/upload + title: Charger les fichiers + - local: guides/cli + title: Utiliser l'invite de commande + - local: guides/hf_file_system + title: HfFileSystem + - local: guides/repository + title: Repository + - local: guides/search + title: Rechercher + - local: guides/inference + title: Inférence + - local: guides/inference_endpoints + title: Endpoint d'Inférence + - local: guides/community + title: Community Tab + - local: guides/collections + title: Collections + - local: guides/manage-cache + title: Cache + - local: guides/model-cards + title: Carte de modèle + - local: guides/manage-spaces + title: Gérez votre espace + - local: guides/integrations + title: Intégrer une librairie + - local: guides/webhooks_server + title: Serveur Webhook +- title: "Guides conceptuels" + sections: + - local: concepts/git_vs_http + title: Le paradigme Git vs HTTP +- title: "Référence" + sections: + - local: package_reference/overview + title: Vue d'ensemble + - local: package_reference/login + title: Connexion et déconnexion + - local: package_reference/environment_variables + title: Variables d'environnement + - local: package_reference/repository + title: Gérer les dépôts locaux et en ligne + - local: package_reference/hf_api + title: API Hugging Face Hub + - local: package_reference/file_download + title: Téléchargement des fichiers + - local: package_reference/mixins + title: Mixins & méthodes de sérialisations + - local: package_reference/inference_client + title: Client d'inférence + - local: package_reference/inference_endpoints + title: Endpoints d'Inférence + - local: package_reference/hf_file_system + title: HfFileSystem + - local: package_reference/utilities + title: Utilitaires + - local: package_reference/community + title: Discussions et Pull Requests + - local: package_reference/cache + title: Référence au système de cache + - local: package_reference/cards + title: Repo Cards et données des Repo Card + - local: package_reference/space_runtime + title: Space runtime + - local: package_reference/collections + title: Collections + - local: package_reference/tensorboard + title: Logger Tensorboard + - local: package_reference/webhooks_server + title: Serveur Webhook \ No newline at end of file diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md new file mode 100644 index 0000000000..e5a6d4091c --- /dev/null +++ b/docs/source/fr/concepts/git_vs_http.md @@ -0,0 +1,70 @@ + + +# Paradigme Git vs HTTP + +La librairie `huggingface_hub` est une librairie qui permet d'intéragir avec le Hub Hugging Face, +qui est une collection de dépots Git (modèles, datasets ou espaces). +Il y a deux manières principales pour accéder au Hub en utilisant `huggingface_hub`. + +La première approche, basée sur Git, appelée approche "git-based", est rendue possible par la classe [`Repository`]. +Cette méthode utilise un wrapper autour de la commande `git` avec des fonctionnalités supplémentaires conçues pour intéragir avec le Hub. La deuxième option, appelée approche "HTTP-based" , +nécessite de faire des requêtes HTTP en utilisant le client [`HfApi`]. Éxaminions +les avantages et les inconvénients de ces deux méthodes. + +## Repository: L'approche hstorique basée sur git + +Au début, `huggingface_hub` était principalement construit autour de la classe [`Repository`]. Elle fournit des +wrappers Python pour les commandes `git` usuelles, telles que `"git add"`, `"git commit"`, `"git push"`, +`"git tag"`, `"git checkout"`, etc. + +Cette librairie permet aussi de définir les données d'identification et de suivre les fichiers volumineux, qui sont souvent utilisés dans les dépot Git de machine learning. De plus, la librairie vous permet d'exécuter ses +méthodes en arrière-plan, ce qui la rend utile pour upload des données pendant l'entrainement des modèles. + +L'avantage principal de l'utilisation de [`Repository`] est que cette méthode permet de garder une +copie en local de tout le dépot Git sur votre machine. Cela peut aussi devenir un désavantage, +car cette copie locale doit être mise à jour et maintenue constamment. C'est une manière de procéder +analogue au développement de logiciel traditionnel où chaque développeur maintient sa propre copie locale +et push les changement lorsqu'ils travaillent sur une fonctionnalité. +Toutefois, dans le contexte du machine learning, +elle n'est pas toujours pertinente car les utilisateurs ont parfois uniquement besoin d'avoir +les poids des modèles pour l'inférence ou de convertir ces poids d'un format à un autre sans avoir à cloner +tout le dépôt. + + + +[`Repository`] est maintenant deprecated et remplacé par les alternatives basées sur l'HTTP. Étant donné son adoption massive par les utilisateurs, +la suppression complète de [`Repository`] ne sera faite que pour la version `v1.0`. + + + +## HfApi: Un client HTTP flexible et pratique + +La classe [`HfApi`] a été développée afin de fournir une alternative aux dépôts git locaux, +qui peuvent être encombrant à maintenir, en particulier lors de l'utilisation de gros modèles ou de datasets volumineux. +La classe [`HfApi`] offre les mêmes fonctionnalités que les approches basées sur Git, +telles que le téléchargement et le push de fichier ainsi que la création de branches et de tags, mais sans +avoir besoin d'un fichier local qui doit être constamment synchronisé. + +En plus des fonctionnalités déjà fournies par `git`, La classe [`HfApi`] offre des fonctionnalités +additionnelles, telles que la capacité de gérer des dépots, le téléchargement des fichiers +en utilisant le cache pour une réutilisation plus efficace, la recherche dans le Hub pour trouver +des dépôts et des métadonnées, l'accès aux fonctionnalités de communautés telles que, les dicussions, +les pull requests, les commentaires, et la configuration d'espaces hardwares et de secrets. + +## Quelle méthode utiliser et quand ? + +En général, **L'approche basée sur l'HTTP est la méthode recommandée** pour l'utilisation d'`huggingface_hub`. +[`HfApi`] permet de pull et push des changements, travailler avec les pull requests, les tags et les branches, l'intréaction avec les discussions +et bien plus encore. Depuis la sortie `0.16`, les méthodes basées sur l'HTTP peuvent aussi tourner en arrière plan, ce qui était le +dernier gros avantage de la classe [`Repository`] sur [`HfApi`]. + +Toutefois, certaines commandes restent indisponibles en utilisant [`HfApi`]. +Peut être que certaines ne le seront jamais, mais nous essayons toujours de réduire le fossé entre les deux approches. +Si votre cas d'usage n'est pas couvert, nous serions ravis de vous aider. Pour cela, ouvrez +[une issue sur Github](https://github.com/huggingface/huggingface_hub)! Nous sommes prêt à entendre tout type de retour nous permettant de construire +l'écosystème 🤗 avec les utilisateurs et pour les utilisateurs. + +Cette préférence pour l'approche basé sur [`HfApi`] au détriment de celle basée sur [`Repository`] ne signifie pas que le versioning git disparaitra +du Hub Hugging Face. Il sera toujours possible d'utiliser les commandes `git` en local lorsque cela a du sens. \ No newline at end of file diff --git a/docs/source/fr/guides/cli.md b/docs/source/fr/guides/cli.md new file mode 100644 index 0000000000..e943660119 --- /dev/null +++ b/docs/source/fr/guides/cli.md @@ -0,0 +1,455 @@ + + +# Command Line Interface (CLI) + +The `huggingface_hub` Python package comes with a built-in CLI called `huggingface-cli`. This tool allows you to interact with the Hugging Face Hub directly from a terminal. For example, you can login to your account, create a repository, upload and download files, etc. It also comes with handy features to configure your machine or manage your cache. In this guide, we will have a look at the main features of the CLI and how to use them. + +## Getting started + +First of all, let's install the CLI: + +``` +>>> pip install -U "huggingface_hub[cli]" +``` + + + +In the snippet above, we also installed the `[cli]` extra dependencies to make the user experience better, especially when using the `delete-cache` command. + + + +Once installed, you can check that the CLI is correctly setup: + +``` +>>> 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 +``` + +If the CLI is correctly installed, you should see a list of all the options available in the CLI. If you get an error message such as `command not found: huggingface-cli`, please refer to the [Installation](../installation) guide. + + + +The `--help` option is very convenient for getting more details about a command. You can use it anytime to list all available options and their details. For example, `huggingface-cli upload --help` provides more information on how to upload files using the CLI. + + + +## huggingface-cli login + +In many cases, you must be logged in to a Hugging Face account to interact with the Hub (download private repos, upload files, create PRs, etc.). To do so, you need a [User Access Token](https://huggingface.co/docs/hub/security-tokens) from your [Settings page](https://huggingface.co/settings/tokens). The User Access Token is used to authenticate your identity to the Hub. Make sure to set a token with write access if you want to upload or modify content. + +Once you have your token, run the following command in your terminal: + +```bash +>>> huggingface-cli login +``` + +This command will prompt you for a token. Copy-paste yours and press *Enter*. Then you'll be asked if the token should also be saved as a git credential. Press *Enter* again (default to yes) if you plan to use `git` locally. Finally, it will call the Hub to check that your token is valid and save it locally. + +``` +_| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_| +_| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _| +_|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_| +_| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _| +_| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_| + +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 +``` + +Alternatively, if you want to log-in without being prompted, you can pass the token directly from the command line. To be more secure, we recommend passing your token as an environment variable to avoid pasting it in your command history. + +```bash +# Or using an environment variable +>>> 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 + +If you want to know if you are logged in, you can use `huggingface-cli whoami`. This command doesn't have any options and simply prints your username and the organizations you are a part of on the Hub: + +```bash +huggingface-cli whoami +Wauplin +orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster +``` + +If you are not logged in, an error message will be printed. + +## huggingface-cli logout + +This commands logs you out. In practice, it will delete the token saved on your machine. + +This command will not log you out if you are logged in using the `HF_TOKEN` environment variable (see [reference](../package_reference/environment_variables#hftoken)). If that is the case, you must unset the environment variable in your machine configuration. + +## huggingface-cli download + + +Use the `huggingface-cli download` command to download files from the Hub directly. Internally, it uses the same [`hf_hub_download`] and [`snapshot_download`] helpers described in the [Download](./download) guide and prints the returned path to the terminal. In the examples below, we will walk through the most common use cases. For a full list of available options, you can run: + +```bash +huggingface-cli download --help +``` + +### Download a single file + +To download a single file from a repo, simply provide the repo_id and filename as follow: + +```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 +``` + +The command will always print on the last line the path to the file on your local machine. + +### Download an entire repository + +In some cases, you just want to download all the files from a repository. This can be done by just specifying the repo id: + +```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 + +... +``` + +### Download a specific revision + +The examples above show how to download from the latest commit on the main branch. To download from a specific revision (commit hash, branch name or tag), use the `--revision` option: + +```bash +>>> huggingface-cli download bigcode/the-stack --repo-type dataset --revision v1.1 +... +``` + +### Download to a local folder + +The recommended (and default) way to download files from the Hub is to use the cache-system. However, in some cases you want to download files and move them to a specific folder. This is useful to get a workflow closer to what git commands offer. You can do that using the `--local_dir` option. + + + +Downloading to a local directory comes with some downsides. Please check out the limitations in the [Download](./download#download-files-to-local-folder) guide before using `--local-dir`. + + + +```bash +>>> huggingface-cli download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir . +... +./model-00001-of-00002.safetensors +``` + +### Specify cache directory + +By default, all files will be download to the cache directory defined by the `HF_HOME` [environment variable](../package_reference/environment_variables#hfhome). You can also specify a custom cache using `--cache-dir`: + +```bash +>>> huggingface-cli download adept/fuyu-8b --cache-dir ./path/to/cache +... +./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745 +``` + +### Specify a token + +To access private or gated repositories, you must use a token. By default, the token saved locally (using `huggingface-cli login`) will be used. If you want to authenticate explicitly, use the `--token` option: + +```bash +>>> huggingface-cli download gpt2 config.json --token=hf_**** +/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json +``` + +### Quiet mode + +By default, the `huggingface-cli download` command will be verbose. It will print details such as warning messages, information about the downloaded files, and progress bars. If you want to silence all of this, use the `--quiet` option. Only the last line (i.e. the path to the downloaded files) is printed. This can prove useful if you want to pass the output to another command in a script. + +```bash +>>> huggingface-cli download gpt2 --quiet +/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 +``` + +## huggingface-cli upload + +Use the `huggingface-cli upload` command to upload files to the Hub directly. Internally, it uses the same [`upload_file`] and [`upload_folder`] helpers described in the [Upload](./upload) guide. In the examples below, we will walk through the most common use cases. For a full list of available options, you can run: + +```bash +>>> huggingface-cli upload --help +``` + +### Upload an entire folder + +The default usage for this command is: + +```bash +# Usage: huggingface-cli upload [repo_id] [local_path] [path_in_repo] +``` + +To upload the current directory at the root of the repo, use: + +```bash +>>> huggingface-cli upload my-cool-model . . +https://huggingface.co/Wauplin/my-cool-model/tree/main/ +``` + + + +If the repo doesn't exist yet, it will be created automatically. + + + +You can also upload a specific folder: + +```bash +>>> huggingface-cli upload my-cool-model ./models . +https://huggingface.co/Wauplin/my-cool-model/tree/main/ +``` + +Finally, you can upload a folder to a specific destination on the repo: + +```bash +>>> huggingface-cli upload my-cool-model ./path/to/curated/data /data/train +https://huggingface.co/Wauplin/my-cool-model/tree/main/data/train +``` + +### Upload a single file + +You can also upload a single file by setting `local_path` to point to a file on your machine. If that's the case, `path_in_repo` is optional and will default to the name of your local file: + +```bash +>>> huggingface-cli upload Wauplin/my-cool-model ./models/model.safetensors +https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors +``` + +If you want to upload a single file to a specific directory, set `path_in_repo` accordingly: + +```bash +>>> huggingface-cli upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors +https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensors +``` + +### Upload multiple files + +To upload multiple files from a folder at once without uploading the entire folder, use the `--include` and `--exclude` patterns. It can also be combined with the `--delete` option to delete files on the repo while uploading new ones. In the example below, we sync the local Space by deleting remote files and uploading all files except the ones in `/logs`: + +```bash +# Sync local Space with Hub (upload new files except from logs/, delete removed files) +>>> huggingface-cli upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub" +... +``` + +### Upload to a dataset or Space + +To upload to a dataset or a Space, use the `--repo-type` option: + +```bash +>>> huggingface-cli upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset +... +``` + +### Upload to an organization + +To upload content to a repo owned by an organization instead of a personal repo, you must explicitly specify it in the `repo_id`: + +```bash +>>> huggingface-cli upload MyCoolOrganization/my-cool-model . . +https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/ +``` + +### Upload to a specific revision + +By default, files are uploaded to the `main` branch. If you want to upload files to another branch or reference, use the `--revision` option: + +```bash +# Upload files to a PR +>>> huggingface-cli upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104 +... +``` + +**Note:** if `revision` does not exist and `--create-pr` is not set, a branch will be created automatically from the `main` branch. + +### Upload and create a PR + +If you don't have the permission to push to a repo, you must open a PR and let the authors know about the changes you want to make. This can be done by setting the `--create-pr` option: + +```bash +# Create a PR and upload the files to it +>>> 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 at regular intervals + +In some cases, you might want to push regular updates to a repo. For example, this is useful if you're training a model and you want to upload the logs folder every 10 minutes. You can do this using the `--every` option: + +```bash +# Upload new logs every 10 minutes +huggingface-cli upload training-model logs/ --every=10 +``` + +### Specify a commit message + +Use the `--commit-message` and `--commit-description` to set a custom message and description for your commit instead of the default one + +```bash +>>> huggingface-cli upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details." +... +https://huggingface.co/Wauplin/my-cool-model/tree/main +``` + +### Specify a token + +To upload files, you must use a token. By default, the token saved locally (using `huggingface-cli login`) will be used. If you want to authenticate explicitly, use the `--token` option: + +```bash +>>> huggingface-cli upload Wauplin/my-cool-model ./models . --token=hf_**** +... +https://huggingface.co/Wauplin/my-cool-model/tree/main +``` + +### Quiet mode + +By default, the `huggingface-cli upload` command will be verbose. It will print details such as warning messages, information about the uploaded files, and progress bars. If you want to silence all of this, use the `--quiet` option. Only the last line (i.e. the URL to the uploaded files) is printed. This can prove useful if you want to pass the output to another command in a script. + +```bash +>>> huggingface-cli upload Wauplin/my-cool-model ./models . --quiet +https://huggingface.co/Wauplin/my-cool-model/tree/main +``` + +## huggingface-cli scan-cache + +Scanning your cache directory is useful if you want to know which repos you have downloaded and how much space it takes on your disk. You can do that by running `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. +``` + +For more details about how to scan your cache directory, please refer to the [Manage your cache](./manage-cache#scan-cache-from-the-terminal) guide. + +## huggingface-cli delete-cache + +`huggingface-cli delete-cache` is a tool that helps you delete parts of your cache that you don't use anymore. This is useful for saving and freeing disk space. To learn more about using this command, please refer to the [Manage your cache](./manage-cache#clean-cache-from-the-terminal) guide. + +## huggingface-cli env + +The `huggingface-cli env` command prints details about your machine setup. This is useful when you open an issue on [GitHub](https://github.com/huggingface/huggingface_hub) to help the maintainers investigate your problem. + +```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 new file mode 100644 index 0000000000..5dd408de09 --- /dev/null +++ b/docs/source/fr/guides/collections.md @@ -0,0 +1,227 @@ + + +# Collections + +A collection is a group of related items on the Hub (models, datasets, Spaces, papers) that are organized together on the same page. Collections are useful for creating your own portfolio, bookmarking content in categories, or presenting a curated list of items you want to share. Check out this [guide](https://huggingface.co/docs/hub/collections) to understand in more detail what collections are and how they look on the Hub. + +You can directly manage collections in the browser, but in this guide, we will focus on how to manage it programmatically. + +## Fetch a collection + +Use [`get_collection`] to fetch your collections or any public ones. You must have the collection's *slug* to retrieve a collection. A slug is an identifier for a collection based on the title and a unique ID. You can find the slug in the URL of the collection page. + +
+ +
+ +Let's fetch the collection with, `"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 +) +``` + +The [`Collection`] object returned by [`get_collection`] contains: +- high-level metadata: `slug`, `owner`, `title`, `description`, etc. +- a list of [`CollectionItem`] objects; each item represents a model, a dataset, a Space, or a paper. + +All collection items are guaranteed to have: +- a unique `item_object_id`: this is the id of the collection item in the database +- an `item_id`: this is the id on the Hub of the underlying item (model, dataset, Space, paper); it is not necessarily unique, and only the `item_id`/`item_type` pair is unique +- an `item_type`: model, dataset, Space, paper +- the `position` of the item in the collection, which can be updated to reorganize your collection (see [`update_collection_item`] below) + +A `note` can also be attached to the item. This is useful to add additional information about the item (a comment, a link to a blog post, etc.). The attribute still has a `None` value if an item doesn't have a note. + +In addition to these base attributes, returned items can have additional attributes depending on their type: `author`, `private`, `lastModified`, `gated`, `title`, `likes`, `upvotes`, etc. None of these attributes are guaranteed to be returned. + +## List collections + +We can also retrieve collections using [`list_collections`]. Collections can be filtered using some parameters. Let's list all the collections from the user [`teknium`](https://huggingface.co/teknium). +```py +>>> from huggingface_hub import list_collections + +>>> collections = list_collections(owner="teknium") +``` + +This returns an iterable of `Collection` objects. We can iterate over them to print, for example, the number of upvotes for each collection. + +```py +>>> for collection in collections: +... print("Number of upvotes:", collection.upvotes) +Number of upvotes: 1 +Number of upvotes: 5 +``` + + + +When listing collections, the item list per collection is truncated to 4 items maximum. To retrieve all items from a collection, you must use [`get_collection`]. + + + +It is possible to do more advanced filtering. Let's get all collections containing the model [TheBloke/OpenHermes-2.5-Mistral-7B-GGUF](https://huggingface.co/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF), sorted by trending, and limit the count to 5. +```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 +``` + +Parameter `sort` must be one of `"last_modified"`, `"trending"` or `"upvotes"`. Parameter `item` accepts any particular item. For example: +* `"models/teknium/OpenHermes-2.5-Mistral-7B"` +* `"spaces/julien-c/open-gpt-rhyming-robot"` +* `"datasets/squad"` +* `"papers/2311.12983"` + +For more details, please check out [`list_collections`] reference. + +## Create a new collection + +Now that we know how to get a [`Collection`], let's create our own! Use [`create_collection`] with a title and description. To create a collection on an organization page, pass `namespace="my-cool-org"` when creating the collection. Finally, you can also create private collections by passing `private=True`. + +```py +>>> from huggingface_hub import create_collection + +>>> collection = create_collection( +... title="ICCV 2023", +... description="Portfolio of models, papers and demos I presented at ICCV 2023", +... ) +``` + +It will return a [`Collection`] object with the high-level metadata (title, description, owner, etc.) and an empty list of items. You will now be able to refer to this collection using it's `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' +``` + +## Manage items in a collection + +Now that we have a [`Collection`], we want to add items to it and organize them. + +### Add items + +Items have to be added one by one using [`add_collection_item`]. You only need to know the `collection_slug`, `item_id` and `item_type`. Optionally, you can also add a `note` to the item (500 characters maximum). + +```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") # same item_id, different item_type +``` + +If an item already exists in a collection (same `item_id`/`item_type` pair), an HTTP 409 error will be raised. You can choose to ignore this error by setting `exists_ok=True`. + +### Add a note to an existing item + +You can modify an existing item to add or modify the note attached to it using [`update_collection_item`]. Let's reuse the example above: + +```py +>>> from huggingface_hub import get_collection, update_collection_item + +# Fetch collection with newly added items +>>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" +>>> collection = get_collection(collection_slug) + +# Add note the `lmsys-chat-1m` dataset +>>> 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.", +... ) +``` + +### Reorder items + +Items in a collection are ordered. The order is determined by the `position` attribute of each item. By default, items are ordered by appending new items at the end of the collection. You can update the order using [`update_collection_item`] the same way you would add a note. + +Let's reuse our example above: + +```py +>>> from huggingface_hub import get_collection, update_collection_item + +# Fetch collection +>>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" +>>> collection = get_collection(collection_slug) + +# Reorder to place the two `Wuerstchen` items together +>>> update_collection_item( +... collection_slug=collection_slug, +... item_object_id=collection.items[3].item_object_id, +... position=2, +... ) +``` + +### Remove items + +Finally, you can also remove an item using [`delete_collection_item`]. + +```py +>>> from huggingface_hub import get_collection, update_collection_item + +# Fetch collection +>>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" +>>> collection = get_collection(collection_slug) + +# Remove `coqui/xtts` Space from the list +>>> delete_collection_item(collection_slug=collection_slug, item_object_id=collection.items[0].item_object_id) +``` + +## Delete collection + +A collection can be deleted using [`delete_collection`]. + + + +This is a non-revertible action. A deleted collection cannot be restored. + + + +```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 new file mode 100644 index 0000000000..0baa34e4e5 --- /dev/null +++ b/docs/source/fr/guides/community.md @@ -0,0 +1,149 @@ + + +# Interact with Discussions and Pull Requests + +The `huggingface_hub` library provides a Python interface to interact with Pull Requests and Discussions on the Hub. +Visit [the dedicated documentation page](https://huggingface.co/docs/hub/repositories-pull-requests-discussions) +for a deeper view of what Discussions and Pull Requests on the Hub are, and how they work under the hood. + +## Retrieve Discussions and Pull Requests from the Hub + +The `HfApi` class allows you to retrieve Discussions and Pull Requests on a given repo: + +```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` supports filtering by author, type (Pull Request or Discussion) and status (`open` or `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` returns a [generator](https://docs.python.org/3.7/howto/functional.html#generators) that yields +[`Discussion`] objects. To get all the Discussions in a single list, run: + +```python +>>> from huggingface_hub import get_repo_discussions +>>> discussions_list = list(get_repo_discussions(repo_id="bert-base-uncased")) +``` + +The [`Discussion`] object returned by [`HfApi.get_repo_discussions`] contains high-level overview of the +Discussion or Pull Request. You can also get more detailed information using [`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`] returns a [`DiscussionWithDetails`] object, which is a subclass of [`Discussion`] +with more detailed information about the Discussion or Pull Request. Information includes all the comments, status changes, +and renames of the Discussion via [`DiscussionWithDetails.events`]. + +In case of a Pull Request, you can retrieve the raw git diff with [`DiscussionWithDetails.diff`]. All the commits of the +Pull Request are listed in [`DiscussionWithDetails.events`]. + + +## Create and edit a Discussion or Pull Request programmatically + +The [`HfApi`] class also offers ways to create and edit Discussions and Pull Requests. +You will need an [access token](https://huggingface.co/docs/hub/security-tokens) to create and edit Discussions +or Pull Requests. + +The simplest way to propose changes on a repo on the Hub is via the [`create_commit`] API: just +set the `create_pr` parameter to `True`. This parameter is also available on other methods that wrap [`create_commit`]: + + * [`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, +... ) +``` + +You can also use [`HfApi.create_discussion`] (respectively [`HfApi.create_pull_request`]) to create a Discussion (respectively a Pull Request) on a repo. +Opening a Pull Request this way can be useful if you need to work on changes locally. Pull Requests opened this way will be in `"draft"` mode. + +```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) +``` + +Managing Pull Requests and Discussions can be done entirely with the [`HfApi`] class. For example: + + * [`comment_discussion`] to add comments + * [`edit_discussion_comment`] to edit comments + * [`rename_discussion`] to rename a Discussion or Pull Request + * [`change_discussion_status`] to open or close a Discussion / Pull Request + * [`merge_pull_request`] to merge a Pull Request + + +Visit the [`HfApi`] documentation page for an exhaustive reference of all available methods. + +## Push changes to a Pull Request + +*Coming soon !* + +## See also + +For a more detailed reference, visit the [Discussions and Pull Requests](../package_reference/community) and the [hf_api](../package_reference/hf_api) documentation page. diff --git a/docs/source/fr/guides/download.md b/docs/source/fr/guides/download.md new file mode 100644 index 0000000000..459cdd7130 --- /dev/null +++ b/docs/source/fr/guides/download.md @@ -0,0 +1,202 @@ + + +# Download files from the Hub + +The `huggingface_hub` library provides functions to download files from the repositories +stored on the Hub. You can use these functions independently or integrate them into your +own library, making it more convenient for your users to interact with the Hub. This +guide will show you how to: + +* Download and cache a single file. +* Download and cache an entire repository. +* Download files to a local folder. + +## Download a single file + +The [`hf_hub_download`] function is the main function for downloading files from the Hub. +It downloads the remote file, caches it on disk (in a version-aware way), and returns its local file path. + + + +The returned filepath is a pointer to the HF local cache. Therefore, it is important to not modify the file to avoid +having a corrupted cache. If you are interested in getting to know more about how files are cached, please refer to our +[caching guide](./manage-cache). + + + +### From latest version + +Select the file to download using the `repo_id`, `repo_type` and `filename` parameters. By default, the file will +be considered as being part of a `model` repo. + +```python +>>> from huggingface_hub import hf_hub_download +>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") +'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' + +# Download from a dataset +>>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") +'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' +``` + +### From specific version + +By default, the latest version from the `main` branch is downloaded. However, in some cases you want to download a file +at a particular version (e.g. from a specific branch, a PR, a tag or a commit hash). +To do so, use the `revision` parameter: + +```python +# Download from the `v1.0` tag +>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") + +# Download from the `test-branch` branch +>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") + +# Download from Pull Request #3 +>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") + +# Download from a specific commit hash +>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") +``` + +**Note:** When using the commit hash, it must be the full-length hash instead of a 7-character commit hash. + +### Construct a download URL + +In case you want to construct the URL used to download a file from a repo, you can use [`hf_hub_url`] which returns a URL. +Note that it is used internally by [`hf_hub_download`]. + +## Download an entire repository + +[`snapshot_download`] downloads an entire repository at a given revision. It uses internally [`hf_hub_download`] which +means all downloaded files are also cached on your local disk. Downloads are made concurrently to speed-up the process. + +To download a whole repository, just pass the `repo_id` and `repo_type`: + +```python +>>> from huggingface_hub import snapshot_download +>>> snapshot_download(repo_id="lysandre/arxiv-nlp") +'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' + +# Or from a dataset +>>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") +'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' +``` + +[`snapshot_download`] downloads the latest revision by default. If you want a specific repository revision, use the +`revision` parameter: + +```python +>>> from huggingface_hub import snapshot_download +>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") +``` + +### Filter files to download + +[`snapshot_download`] provides an easy way to download a repository. However, you don't always want to download the +entire content of a repository. For example, you might want to prevent downloading all `.bin` files if you know you'll +only use the `.safetensors` weights. You can do that using `allow_patterns` and `ignore_patterns` parameters. + +These parameters accept either a single pattern or a list of patterns. Patterns are Standard Wildcards (globbing +patterns) as documented [here](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). The pattern matching is +based on [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). + +For example, you can use `allow_patterns` to only download JSON configuration files: + +```python +>>> from huggingface_hub import snapshot_download +>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json") +``` + +On the other hand, `ignore_patterns` can exclude certain files from being downloaded. The +following example ignores the `.msgpack` and `.h5` file extensions: + +```python +>>> from huggingface_hub import snapshot_download +>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"]) +``` + +Finally, you can combine both to precisely filter your download. Here is an example to download all json and markdown +files except `vocab.json`. + +```python +>>> from huggingface_hub import snapshot_download +>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json") +``` + +## Download file(s) to local folder + +The recommended (and default) way to download files from the Hub is to use the [cache-system](./manage-cache). +You can define your cache location by setting `cache_dir` parameter (both in [`hf_hub_download`] and [`snapshot_download`]). + +However, in some cases you want to download files and move them to a specific folder. This is useful to get a workflow +closer to what `git` commands offer. You can do that using the `local_dir` and `local_dir_use_symlinks` parameters: +- `local_dir` must be a path to a folder on your system. The downloaded files will keep the same file structure as in the +repo. For example if `filename="data/train.csv"` and `local_dir="path/to/folder"`, then the returned filepath will be +`"path/to/folder/data/train.csv"`. +- `local_dir_use_symlinks` defines how the file must be saved in your local folder. + - The default behavior (`"auto"`) is to duplicate small files (<5MB) and use symlinks for bigger files. Symlinks allow + to optimize both bandwidth and disk usage. However manually editing a symlinked file might corrupt the cache, hence + the duplication for small files. The 5MB threshold can be configured with the `HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD` + environment variable. + - If `local_dir_use_symlinks=True` is set, all files are symlinked for an optimal disk space optimization. This is + for example useful when downloading a huge dataset with thousands of small files. + - Finally, if you don't want symlinks at all you can disable them (`local_dir_use_symlinks=False`). The cache directory + will still be used to check wether the file is already cached or not. If already cached, the file is **duplicated** + from the cache (i.e. saves bandwidth but increases disk usage). If the file is not already cached, it will be + downloaded and moved directly to the local dir. This means that if you need to reuse it somewhere else later, it + will be **re-downloaded**. + +Here is a table that summarizes the different options to help you choose the parameters that best suit your use case. + + +| Parameters | File already cached | Returned path | Can read path? | Can save to path? | Optimized bandwidth | Optimized disk usage | +|---|:---:|:---:|:---:|:---:|:---:|:---:| +| `local_dir=None` | | symlink in cache | ✅ | ❌
_(save would corrupt the cache)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | file or symlink in folder | ✅ | ✅ _(for small files)_
⚠️ _(for big files do not resolve path before saving)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | symlink in folder | ✅ | ⚠️
_(do not resolve path before saving)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | No | file in folder | ✅ | ✅ | ❌
_(if re-run, file is re-downloaded)_ | ⚠️
(multiple copies if ran in multiple folders) | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | Yes | file in folder | ✅ | ✅ | ⚠️
_(file has to be cached first)_ | ❌
_(file is duplicated)_ | + +**Note:** if you are on a Windows machine, you need to enable developer mode or run `huggingface_hub` as admin to enable +symlinks. Check out the [cache limitations](../guides/manage-cache#limitations) section for more details. + +## Download from the CLI + +You can use the `huggingface-cli download` command from the terminal to directly download files from the Hub. +Internally, it uses the same [`hf_hub_download`] and [`snapshot_download`] helpers described above and prints the +returned path to the terminal. + +```bash +>>> huggingface-cli download gpt2 config.json +/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json +``` + +You can download multiple files at once which displays a progress bar and returns the snapshot path in which the files +are located: + +```bash +>>> huggingface-cli download gpt2 config.json model.safetensors +Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s] +/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 +``` + +For more details about the CLI download command, please refer to the [CLI guide](./cli#huggingface-cli-download). + +## Faster downloads + +If you are running on a machine with high bandwidth, you can increase your download speed with [`hf_transfer`](https://github.com/huggingface/hf_transfer), a Rust-based library developed to speed up file transfers with the Hub. To enable it, install the package (`pip install hf_transfer`) and set `HF_HUB_ENABLE_HF_TRANSFER=1` as an environment variable. + + + +Progress bars are supported in `hf_transfer` starting from version `0.1.4`. Consider upgrading (`pip install -U hf-transfer`) if you plan to enable faster downloads. + + + + + +`hf_transfer` is a power user tool! It is tested and production-ready, but it lacks user-friendly features like advanced error handling or proxies. For more details, please take a look at this [section](https://huggingface.co/docs/huggingface_hub/hf_transfer). + + \ No newline at end of file diff --git a/docs/source/fr/guides/hf_file_system.md b/docs/source/fr/guides/hf_file_system.md new file mode 100644 index 0000000000..5c68232168 --- /dev/null +++ b/docs/source/fr/guides/hf_file_system.md @@ -0,0 +1,109 @@ + + +# Interact with the Hub through the Filesystem API + +In addition to the [`HfApi`], the `huggingface_hub` library provides [`HfFileSystem`], a pythonic [fsspec-compatible](https://filesystem-spec.readthedocs.io/en/latest/) file interface to the Hugging Face Hub. The [`HfFileSystem`] builds of top of the [`HfApi`] and offers typical filesystem style operations like `cp`, `mv`, `ls`, `du`, `glob`, `get_file`, and `put_file`. + +## Usage + +```python +>>> from huggingface_hub import HfFileSystem +>>> fs = HfFileSystem() + +>>> # List all files in a directory +>>> 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'] + +>>> # List all ".csv" files in a repo +>>> 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'] + +>>> # Read a remote file +>>> with fs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f: +... train_data = f.readlines() + +>>> # Read the content of a remote file as a string +>>> train_data = fs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev") + +>>> # Write a remote file +>>> with fs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f: +... f.write("text,label") +... f.write("Fantastic movie!,good") +``` + +The optional `revision` argument can be passed to run an operation from a specific commit such as a branch, tag name, or a commit hash. + +Unlike Python's built-in `open`, `fsspec`'s `open` defaults to binary mode, `"rb"`. This means you must explicitly set mode as `"r"` for reading and `"w"` for writing in text mode. Appending to a file (modes `"a"` and `"ab"`) is not supported yet. + +## Integrations + +The [`HfFileSystem`] can be used with any library that integrates `fsspec`, provided the URL follows the scheme: + +``` +hf://[][@]/ +``` + +The `repo_type_prefix` is `datasets/` for datasets, `spaces/` for spaces, and models don't need a prefix in the URL. + +Some interesting integrations where [`HfFileSystem`] simplifies interacting with the Hub are listed below: + +* Reading/writing a [Pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#reading-writing-remote-files) DataFrame from/to a Hub repository: + + ```python + >>> import pandas as pd + + >>> # Read a remote CSV file into a dataframe + >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv") + + >>> # Write a dataframe to a remote CSV file + >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv") + ``` + +The same workflow can also be used for [Dask](https://docs.dask.org/en/stable/how-to/connect-to-remote-data.html) and [Polars](https://pola-rs.github.io/polars/py-polars/html/reference/io.html) DataFrames. + +* Querying (remote) Hub files with [DuckDB](https://duckdb.org/docs/guides/python/filesystems): + + ```python + >>> from huggingface_hub import HfFileSystem + >>> import duckdb + + >>> fs = HfFileSystem() + >>> duckdb.register_filesystem(fs) + >>> # Query a remote file and get the result back as a 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() + ``` + +* Using the Hub as an array store with [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") + + >>> # Write an array to a repo + >>> 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 + + >>> # Read an array from a repo + >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r") as root: + ... first_row = root["embeddings/experiment_0"][0] + ``` + +## Authentication + +In many cases, you must be logged in with a Hugging Face account to interact with the Hub. Refer to the [Login](../quick-start#login) section of the documentation to learn more about authentication methods on the Hub. + +It is also possible to login programmatically by passing your `token` as an argument to [`HfFileSystem`]: + +```python +>>> from huggingface_hub import HfFileSystem +>>> fs = HfFileSystem(token=token) +``` + +If you login this way, be careful not to accidentally leak the token when sharing your source code! diff --git a/docs/source/fr/guides/inference.md b/docs/source/fr/guides/inference.md new file mode 100644 index 0000000000..e2133aa39d --- /dev/null +++ b/docs/source/fr/guides/inference.md @@ -0,0 +1,336 @@ + + +# Run Inference on servers + +Inference is the process of using a trained model to make predictions on new data. As this process can be compute-intensive, +running on a dedicated server can be an interesting option. The `huggingface_hub` library provides an easy way to call a +service that runs inference for hosted models. There are several services you can connect to: +- [Inference API](https://huggingface.co/docs/api-inference/index): a service that allows you to run accelerated inference +on Hugging Face's infrastructure for free. This service is a fast way to get started, test different models, and +prototype AI products. +- [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index): a product to easily deploy models to production. +Inference is run by Hugging Face in a dedicated, fully managed infrastructure on a cloud provider of your choice. + +These services can be called with the [`InferenceClient`] object. It acts as a replacement for the legacy +[`InferenceApi`] client, adding specific support for tasks and handling inference on both +[Inference API](https://huggingface.co/docs/api-inference/index) and [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index). +Learn how to migrate to the new client in the [Legacy InferenceAPI client](#legacy-inferenceapi-client) section. + + + +[`InferenceClient`] is a Python client making HTTP calls to our APIs. If you want to make the HTTP calls directly using +your preferred tool (curl, postman,...), please refer to the [Inference API](https://huggingface.co/docs/api-inference/index) +or to the [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) documentation pages. + +For web development, a [JS client](https://huggingface.co/docs/huggingface.js/inference/README) has been released. +If you are interested in game development, you might have a look at our [C# project](https://github.com/huggingface/unity-api). + + + +## Getting started + +Let's get started with a text-to-image task: + +```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") +``` + +We initialized an [`InferenceClient`] with the default parameters. The only thing you need to know is the [task](#supported-tasks) you want +to perform. By default, the client will connect to the Inference API and select a model to complete the task. In our +example, we generated an image from a text prompt. The returned value is a `PIL.Image` object that can be saved to a +file. + + + +The API is designed to be simple. Not all parameters and options are available or described for the end user. Check out +[this page](https://huggingface.co/docs/api-inference/detailed_parameters) if you are interested in learning more about +all the parameters available for each task. + + + +### Using a specific model + +What if you want to use a specific model? You can specify it either as a parameter or directly at an instance level: + +```python +>>> from huggingface_hub import InferenceClient +# Initialize client for a specific model +>>> client = InferenceClient(model="prompthero/openjourney-v4") +>>> client.text_to_image(...) +# Or use a generic client but pass your model as an argument +>>> client = InferenceClient() +>>> client.text_to_image(..., model="prompthero/openjourney-v4") +``` + + + +There are more than 200k models on the Hugging Face Hub! Each task in the [`InferenceClient`] comes with a recommended +model. Be aware that the HF recommendation can change over time without prior notice. Therefore it is best to explicitly +set a model once you are decided. Also, in most cases you'll be interested in finding a model specific to _your_ needs. +Visit the [Models](https://huggingface.co/models) page on the Hub to explore your possibilities. + + + +### Using a specific URL + +The examples we saw above use the free-hosted Inference API. This proves to be very useful for prototyping +and testing things quickly. Once you're ready to deploy your model to production, you'll need to use a dedicated infrastructure. +That's where [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) comes into play. It allows you to deploy +any model and expose it as a private API. Once deployed, you'll get a URL that you can connect to using exactly the same +code as before, changing only the `model` parameter: + +```python +>>> from huggingface_hub import InferenceClient +>>> client = InferenceClient(model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") +# or +>>> client = InferenceClient() +>>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") +``` + +### Authentication + +Calls made with the [`InferenceClient`] can be authenticated using a [User Access Token](https://huggingface.co/docs/hub/security-tokens). +By default, it will use the token saved on your machine if you are logged in (check out +[how to login](https://huggingface.co/docs/huggingface_hub/quick-start#login)). If you are not logged in, you can pass +your token as an instance parameter: + +```python +>>> from huggingface_hub import InferenceClient +>>> client = InferenceClient(token="hf_***") +``` + + + +Authentication is NOT mandatory when using the Inference API. However, authenticated users get a higher free-tier to +play with the service. Token is also mandatory if you want to run inference on your private models or on private +endpoints. + + + +## Supported tasks + +[`InferenceClient`]'s goal is to provide the easiest interface to run inference on Hugging Face models. It +has a simple API that supports the most common tasks. Here is a list of the currently supported tasks: + +| Domain | Task | Supported | Documentation | +|--------|--------------------------------|--------------|------------------------------------| +| Audio | [Audio Classification](https://huggingface.co/tasks/audio-classification) | ✅ | [`~InferenceClient.audio_classification`] | +| | [Automatic Speech Recognition](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 | [Image Classification](https://huggingface.co/tasks/image-classification) | ✅ | [`~InferenceClient.image_classification`] | +| | [Image Segmentation](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`] | +| | [Object Detection](https://huggingface.co/tasks/object-detection) | ✅ | [`~InferenceClient.object_detection`] | +| | [Text-to-Image](https://huggingface.co/tasks/text-to-image) | ✅ | [`~InferenceClient.text_to_image`] | +| | [Zero-Shot-Image-Classification](https://huggingface.co/tasks/zero-shot-image-classification) | ✅ | [`~InferenceClient.zero_shot_image_classification`] | +| Multimodal | [Documentation Question Answering](https://huggingface.co/tasks/document-question-answering) | ✅ | [`~InferenceClient.document_question_answering`] +| | [Visual Question Answering](https://huggingface.co/tasks/visual-question-answering) | ✅ | [`~InferenceClient.visual_question_answering`] | +| NLP | [Conversational](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`] | +| | [Question Answering](https://huggingface.co/tasks/question-answering) | ✅ | [`~InferenceClient.question_answering`] +| | [Sentence Similarity](https://huggingface.co/tasks/sentence-similarity) | ✅ | [`~InferenceClient.sentence_similarity`] | +| | [Summarization](https://huggingface.co/tasks/summarization) | ✅ | [`~InferenceClient.summarization`] | +| | [Table Question Answering](https://huggingface.co/tasks/table-question-answering) | ✅ | [`~InferenceClient.table_question_answering`] | +| | [Text Classification](https://huggingface.co/tasks/text-classification) | ✅ | [`~InferenceClient.text_classification`] | +| | [Text Generation](https://huggingface.co/tasks/text-generation) | ✅ | [`~InferenceClient.text_generation`] | +| | [Token Classification](https://huggingface.co/tasks/token-classification) | ✅ | [`~InferenceClient.token_classification`] | +| | [Translation](https://huggingface.co/tasks/translation) | ✅ | [`~InferenceClient.translation`] | +| | [Zero Shot Classification](https://huggingface.co/tasks/zero-shot-classification) | ✅ | [`~InferenceClient.zero_shot_classification`] | +| Tabular | [Tabular Classification](https://huggingface.co/tasks/tabular-classification) | ✅ | [`~InferenceClient.tabular_classification`] | +| | [Tabular Regression](https://huggingface.co/tasks/tabular-regression) | ✅ | [`~InferenceClient.tabular_regression`] | + + + +Check out the [Tasks](https://huggingface.co/tasks) page to learn more about each task, how to use them, and the +most popular models for each task. + + + +## Custom requests + +However, it is not always possible to cover all use cases. For custom requests, the [`InferenceClient.post`] method +gives you the flexibility to send any request to the Inference API. For example, you can specify how to parse the inputs +and outputs. In the example below, the generated image is returned as raw bytes instead of parsing it as a `PIL Image`. +This can be helpful if you don't have `Pillow` installed in your setup and just care about the binary content of the +image. [`InferenceClient.post`] is also useful to handle tasks that are not yet officially supported. + +```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 # raw bytes +b'...' +``` + +## Async client + +An async version of the client is also provided, based on `asyncio` and `aiohttp`. You can either install `aiohttp` +directly or use the `[inference]` extra: + +```sh +pip install --upgrade huggingface_hub[inference] +# or +# pip install aiohttp +``` + +After installation all async API endpoints are available via [`AsyncInferenceClient`]. Its initialization and APIs are +strictly the same as the sync-only version. + +```py +# Code must be run in a asyncio concurrent context. +# $ 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. +``` + +For more information about the `asyncio` module, please refer to the [official documentation](https://docs.python.org/3/library/asyncio.html). + +## Advanced tips + +In the above section, we saw the main aspects of [`InferenceClient`]. Let's dive into some more advanced tips. + +### Timeout + +When doing inference, there are two main causes for a timeout: +- The inference process takes a long time to complete. +- The model is not available, for example when Inference API is loading it for the first time. + +[`InferenceClient`] has a global `timeout` parameter to handle those two aspects. By default, it is set to `None`, +meaning that the client will wait indefinitely for the inference to complete. If you want more control in your workflow, +you can set it to a specific value in seconds. If the timeout delay expires, an [`InferenceTimeoutError`] is raised. +You can catch it and handle it in your 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.") +``` + +### Binary inputs + +Some tasks require binary inputs, for example, when dealing with images or audio files. In this case, [`InferenceClient`] +tries to be as permissive as possible and accept different types: +- raw `bytes` +- a file-like object, opened as binary (`with open("audio.flac", "rb") as f: ...`) +- a path (`str` or `Path`) pointing to a local file +- a URL (`str`) pointing to a remote file (e.g. `https://...`). In this case, the file will be downloaded locally before +sending it to the Inference 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'}, ...] +``` + +## Legacy InferenceAPI client + +[`InferenceClient`] acts as a replacement for the legacy [`InferenceApi`] client. It adds specific support for tasks and +handles inference on both [Inference API](https://huggingface.co/docs/api-inference/index) and [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index). + +Here is a short guide to help you migrate from [`InferenceApi`] to [`InferenceClient`]. + +### Initialization + +Change from + +```python +>>> from huggingface_hub import InferenceApi +>>> inference = InferenceApi(repo_id="bert-base-uncased", token=API_TOKEN) +``` + +to + +```python +>>> from huggingface_hub import InferenceClient +>>> inference = InferenceClient(model="bert-base-uncased", token=API_TOKEN) +``` + +### Run on a specific task + +Change from + +```python +>>> from huggingface_hub import InferenceApi +>>> inference = InferenceApi(repo_id="paraphrase-xlm-r-multilingual-v1", task="feature-extraction") +>>> inference(...) +``` + +to + +```python +>>> from huggingface_hub import InferenceClient +>>> inference = InferenceClient() +>>> inference.feature_extraction(..., model="paraphrase-xlm-r-multilingual-v1") +``` + + + +This is the recommended way to adapt your code to [`InferenceClient`]. It lets you benefit from the task-specific +methods like `feature_extraction`. + + + +### Run custom request + +Change from + +```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'}] +``` + +to + +```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'}] +``` + +### Run with parameters + +Change from + +```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]} +``` + +to + +```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 new file mode 100644 index 0000000000..30b1113420 --- /dev/null +++ b/docs/source/fr/guides/inference_endpoints.md @@ -0,0 +1,259 @@ +# Inference Endpoints + +Inference Endpoints provides a secure production solution to easily deploy any `transformers`, `sentence-transformers`, and `diffusers` models on a dedicated and autoscaling infrastructure managed by Hugging Face. An Inference Endpoint is built from a model from the [Hub](https://huggingface.co/models). +In this guide, we will learn how to programmatically manage Inference Endpoints with `huggingface_hub`. For more information about the Inference Endpoints product itself, check out its [official documentation](https://huggingface.co/docs/inference-endpoints/index). + +This guide assumes `huggingface_hub` is correctly installed and that your machine is logged in. Check out the [Quick Start guide](https://huggingface.co/docs/huggingface_hub/quick-start#quickstart) if that's not the case yet. The minimal version supporting Inference Endpoints API is `v0.19.0`. + + +## Create an Inference Endpoint + +The first step is to create an Inference Endpoint using [`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" +... ) +``` + +In this example, we created a `protected` Inference Endpoint named `"my-endpoint-name"`, to serve [gpt2](https://huggingface.co/gpt2) for `text-generation`. A `protected` Inference Endpoint means your token is required to access the API. We also need to provide additional information to configure the hardware requirements, such as vendor, region, accelerator, instance type, and size. You can check out the list of available resources [here](https://api.endpoints.huggingface.cloud/#/v2%3A%3Aprovider/list_vendors). Alternatively, you can create an Inference Endpoint manually using the [Web interface](https://ui.endpoints.huggingface.co/new) for convenience. Refer to this [guide](https://huggingface.co/docs/inference-endpoints/guides/advanced) for details on advanced settings and their usage. + +The value returned by [`create_inference_endpoint`] is an [`InferenceEndpoint`] object: + +```py +>>> endpoint +InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) +``` + +It's a dataclass that holds information about the endpoint. You can access important attributes such as `name`, `repository`, `status`, `task`, `created_at`, `updated_at`, etc. If you need it, you can also access the raw response from the server with `endpoint.raw`. + +Once your Inference Endpoint is created, you can find it on your [personal dashboard](https://ui.endpoints.huggingface.co/). + +![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/huggingface_hub/inference_endpoints_created.png) + +#### Using a custom image + +By default the Inference Endpoint is built from a docker image provided by Hugging Face. However, it is possible to specify any docker image using the `custom_image` parameter. A common use case is to run LLMs using the [text-generation-inference](https://github.com/huggingface/text-generation-inference) framework. This can be done like this: + +```python +# Start an Inference Endpoint running Zephyr-7b-beta on 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", +... }, +... ) +``` + +The value to pass as `custom_image` is a dictionary containing a url to the docker container and configuration to run it. For more details about it, checkout the [Swagger documentation](https://api.endpoints.huggingface.cloud/#/v2%3A%3Aendpoint/create_endpoint). + +### Get or list existing Inference Endpoints + +In some cases, you might need to manage Inference Endpoints you created previously. If you know the name, you can fetch it using [`get_inference_endpoint`], which returns an [`InferenceEndpoint`] object. Alternatively, you can use [`list_inference_endpoints`] to retrieve a list of all Inference Endpoints. Both methods accept an optional `namespace` parameter. You can set the `namespace` to any organization you are a part of. Otherwise, it defaults to your username. + +```py +>>> from huggingface_hub import get_inference_endpoint, list_inference_endpoints + +# Get one +>>> get_inference_endpoint("my-endpoint-name") +InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) + +# List all endpoints from an organization +>>> list_inference_endpoints(namespace="huggingface") +[InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...] + +# List all endpoints from all organizations the user belongs to +>>> list_inference_endpoints(namespace="*") +[InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...] +``` + +## Check deployment status + +In the rest of this guide, we will assume that we have a [`InferenceEndpoint`] object called `endpoint`. You might have noticed that the endpoint has a `status` attribute of type [`InferenceEndpointStatus`]. When the Inference Endpoint is deployed and accessible, the status should be `"running"` and the `url` attribute is set: + +```py +>>> endpoint +InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') +``` + +Before reaching a `"running"` state, the Inference Endpoint typically goes through an `"initializing"` or `"pending"` phase. You can fetch the new state of the endpoint by running [`~InferenceEndpoint.fetch`]. Like every other method from [`InferenceEndpoint`] that makes a request to the server, the internal attributes of `endpoint` are mutated in place: + +```py +>>> endpoint.fetch() +InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) +``` + +Instead of fetching the Inference Endpoint status while waiting for it to run, you can directly call [`~InferenceEndpoint.wait`]. This helper takes as input a `timeout` and a `fetch_every` parameter (in seconds) and will block the thread until the Inference Endpoint is deployed. Default values are respectively `None` (no timeout) and `5` seconds. + +```py +# Pending endpoint +>>> endpoint +InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) + +# Wait 10s => raises a 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. + +# Wait more +>>> endpoint.wait() +InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') +``` + +If `timeout` is set and the Inference Endpoint takes too much time to load, a [`InferenceEndpointTimeoutError`] timeout error is raised. + +## Run inference + +Once your Inference Endpoint is up and running, you can finally run inference on it! + +[`InferenceEndpoint`] has two properties `client` and `async_client` returning respectively an [`InferenceClient`] and an [`AsyncInferenceClient`] objects. + +```py +# Run text_generation task: +>>> endpoint.client.text_generation("I am") +' not a fan of the idea of a "big-budget" movie. I think it\'s a' + +# Or in an asyncio context: +>>> await endpoint.async_client.text_generation("I am") +``` + +If the Inference Endpoint is not running, an [`InferenceEndpointError`] exception is raised: + +```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. +``` + +For more details about how to use the [`InferenceClient`], check out the [Inference guide](../guides/inference). + +## Manage lifecycle + +Now that we saw how to create an Inference Endpoint and run inference on it, let's see how to manage its lifecycle. + + + +In this section, we will see methods like [`~InferenceEndpoint.pause`], [`~InferenceEndpoint.resume`], [`~InferenceEndpoint.scale_to_zero`], [`~InferenceEndpoint.update`] and [`~InferenceEndpoint.delete`]. All of those methods are aliases added to [`InferenceEndpoint`] for convenience. If you prefer, you can also use the generic methods defined in `HfApi`: [`pause_inference_endpoint`], [`resume_inference_endpoint`], [`scale_to_zero_inference_endpoint`], [`update_inference_endpoint`], and [`delete_inference_endpoint`]. + + + +### Pause or scale to zero + +To reduce costs when your Inference Endpoint is not in use, you can choose to either pause it using [`~InferenceEndpoint.pause`] or scale it to zero using [`~InferenceEndpoint.scale_to_zero`]. + + + +An Inference Endpoint that is *paused* or *scaled to zero* doesn't cost anything. The difference between those two is that a *paused* endpoint needs to be explicitly *resumed* using [`~InferenceEndpoint.resume`]. On the contrary, a *scaled to zero* endpoint will automatically start if an inference call is made to it, with an additional cold start delay. An Inference Endpoint can also be configured to scale to zero automatically after a certain period of inactivity. + + + +```py +# Pause and resume 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 to zero +>>> 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') +# Endpoint is not 'running' but still has a URL and will restart on first call. +``` + +### Update model or hardware requirements + +In some cases, you might also want to update your Inference Endpoint without creating a new one. You can either update the hosted model or the hardware requirements to run the model. You can do this using [`~InferenceEndpoint.update`]: + +```py +# Change target model +>>> endpoint.update(repository="gpt2-large") +InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) + +# Update number of replicas +>>> endpoint.update(min_replica=2, max_replica=6) +InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) + +# Update to larger 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) +``` + +### Delete the endpoint + +Finally if you won't use the Inference Endpoint anymore, you can simply call [`~InferenceEndpoint.delete()`]. + + + +This is a non-revertible action that will completely remove the endpoint, including its configuration, logs and usage metrics. You cannot restore a deleted Inference Endpoint. + + + + +## An end-to-end example + +A typical use case of Inference Endpoints is to process a batch of jobs at once to limit the infrastructure costs. You can automate this process using what we saw in this guide: + +```py +>>> import asyncio +>>> from huggingface_hub import create_inference_endpoint + +# Start endpoint + wait until initialized +>>> endpoint = create_inference_endpoint(name="batch-endpoint",...).wait() + +# Run inference +>>> client = endpoint.client +>>> results = [client.text_generation(...) for job in jobs] + +# Or with asyncio +>>> async_client = endpoint.async_client +>>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs]) + +# Pause endpoint +>>> endpoint.pause() +``` + +Or if your Inference Endpoint already exists and is paused: + +```py +>>> import asyncio +>>> from huggingface_hub import get_inference_endpoint + +# Get endpoint + wait until initialized +>>> endpoint = get_inference_endpoint("batch-endpoint").resume().wait() + +# Run inference +>>> async_client = endpoint.async_client +>>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs]) + +# Pause 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 new file mode 100644 index 0000000000..87575a4e8a --- /dev/null +++ b/docs/source/fr/guides/integrations.md @@ -0,0 +1,285 @@ + + +# Integrate any ML framework with the Hub + +The Hugging Face Hub makes hosting and sharing models with the community easy. It supports +[dozens of libraries](https://huggingface.co/docs/hub/models-libraries) in the Open Source ecosystem. We are always +working on expanding this support to push collaborative Machine Learning forward. The `huggingface_hub` library plays a +key role in this process, allowing any Python script to easily push and load files. + +There are four main ways to integrate a library with the Hub: +1. **Push to Hub:** implement a method to upload a model to the Hub. This includes the model weights, as well as + [the model card](https://huggingface.co/docs/huggingface_hub/how-to-model-cards) and any other relevant information + or data necessary to run the model (for example, training logs). This method is often called `push_to_hub()`. +2. **Download from Hub:** implement a method to load a model from the Hub. The method should download the model + configuration/weights and load the model. This method is often called `from_pretrained` or `load_from_hub()`. +3. **Inference API:** use our servers to run inference on models supported by your library for free. +4. **Widgets:** display a widget on the landing page of your models on the Hub. It allows users to quickly try a model + from the browser. + +In this guide, we will focus on the first two topics. We will present the two main approaches you can use to integrate +a library, with their advantages and drawbacks. Everything is summarized at the end of the guide to help you choose +between the two. Please keep in mind that these are only guidelines that you are free to adapt to you requirements. + +If you are interested in Inference and Widgets, you can follow [this guide](https://huggingface.co/docs/hub/models-adding-libraries#set-up-the-inference-api). +In both cases, you can reach out to us if you are integrating a library with the Hub and want to be listed +[in our docs](https://huggingface.co/docs/hub/models-libraries). + +## A flexible approach: helpers + +The first approach to integrate a library to the Hub is to actually implement the `push_to_hub` and `from_pretrained` +methods by yourself. This gives you full flexibility on which files you need to upload/download and how to handle inputs +specific to your framework. You can refer to the two [upload files](./upload) and [download files](./download) guides +to learn more about how to do that. This is, for example how the FastAI integration is implemented (see [`push_to_hub_fastai`] +and [`from_pretrained_fastai`]). + +Implementation can differ between libraries, but the workflow is often similar. + +### from_pretrained + +This is how a `from_pretrained` method usually look like: + +```python +def from_pretrained(model_id: str) -> MyModelClass: + # Download model from Hub + cached_model = hf_hub_download( + repo_id=repo_id, + filename="model.pkl", + library_name="fastai", + library_version=get_fastai_version(), + ) + + # Load model + return load_model(cached_model) +``` + +### push_to_hub + +The `push_to_hub` method often requires a bit more complexity to handle repo creation, generate the model card and save weights. +A common approach is to save all of these files in a temporary folder, upload it and then delete it. + +```python +def push_to_hub(model: MyModelClass, repo_name: str) -> None: + api = HfApi() + + # Create repo if not existing yet and get the associated repo_id + repo_id = api.create_repo(repo_name, exist_ok=True) + + # Save all files in a temporary directory and push them in a single commit + with TemporaryDirectory() as tmpdir: + tmpdir = Path(tmpdir) + + # Save weights + save_model(model, tmpdir / "model.safetensors") + + # Generate model card + card = generate_model_card(model) + (tmpdir / "README.md").write_text(card) + + # Save logs + # Save figures + # Save evaluation metrics + # ... + + # Push to hub + return api.upload_folder(repo_id=repo_id, folder_path=tmpdir) +``` + +This is of course only an example. If you are interested in more complex manipulations (delete remote files, upload +weights on the fly, persist weights locally, etc.) please refer to the [upload files](./upload) guide. + +### Limitations + +While being flexible, this approach has some drawbacks, especially in terms of maintenance. Hugging Face users are often +used to additional features when working with `huggingface_hub`. For example, when loading files from the Hub, it is +common to offer parameters like: +- `token`: to download from a private repo +- `revision`: to download from a specific branch +- `cache_dir`: to cache files in a specific directory +- `force_download`/`resume_download`/`local_files_only`: to reuse the cache or not +- `api_endpoint`/`proxies`: configure HTTP session + +When pushing models, similar parameters are supported: +- `commit_message`: custom commit message +- `private`: create a private repo if missing +- `create_pr`: create a PR instead of pushing to `main` +- `branch`: push to a branch instead of the `main` branch +- `allow_patterns`/`ignore_patterns`: filter which files to upload +- `token` +- `api_endpoint` +- ... + +All of these parameters can be added to the implementations we saw above and passed to the `huggingface_hub` methods. +However, if a parameter changes or a new feature is added, you will need to update your package. Supporting those +parameters also means more documentation to maintain on your side. To see how to mitigate these limitations, let's jump +to our next section **class inheritance**. + +## A more complex approach: class inheritance + +As we saw above, there are two main methods to include in your library to integrate it with the Hub: upload files +(`push_to_hub`) and download files (`from_pretrained`). You can implement those methods by yourself but it comes with +caveats. To tackle this, `huggingface_hub` provides a tool that uses class inheritance. Let's see how it works! + +In a lot of cases, a library already implements its model using a Python class. The class contains the properties of +the model and methods to load, run, train, and evaluate it. Our approach is to extend this class to include upload and +download features using mixins. A [Mixin](https://stackoverflow.com/a/547714) is a class that is meant to extend an +existing class with a set of specific features using multiple inheritance. `huggingface_hub` provides its own mixin, +the [`ModelHubMixin`]. The key here is to understand its behavior and how to customize it. + +The [`ModelHubMixin`] class implements 3 *public* methods (`push_to_hub`, `save_pretrained` and `from_pretrained`). Those +are the methods that your users will call to load/save models with your library. [`ModelHubMixin`] also defines 2 +*private* methods (`_save_pretrained` and `_from_pretrained`). Those are the ones you must implement. So to integrate +your library, you should: + +1. Make your Model class inherit from [`ModelHubMixin`]. +2. Implement the private methods: + - [`~ModelHubMixin._save_pretrained`]: method taking as input a path to a directory and saving the model to it. + You must write all the logic to dump your model in this method: model card, model weights, configuration files, + training logs, and figures. Any relevant information for this model must be handled by this method. + [Model Cards](https://huggingface.co/docs/hub/model-cards) are particularly important to describe your model. Check + out [our implementation guide](./model-cards) for more details. + - [`~ModelHubMixin._from_pretrained`]: **class method** taking as input a `model_id` and returning an instantiated + model. The method must download the relevant files and load them. +3. You are done! + +The advantage of using [`ModelHubMixin`] is that once you take care of the serialization/loading of the files, you +are ready to go. You don't need to worry about stuff like repo creation, commits, PRs, or revisions. All +of this is handled by the mixin and is available to your users. The Mixin also ensures that public methods are well +documented and type annotated. + +### A concrete example: PyTorch + +A good example of what we saw above is [`PyTorchModelHubMixin`], our integration for the PyTorch framework. This is a +ready-to-use integration. + +#### How to use it? + +Here is how any user can load/save a PyTorch model from/to the Hub: + +```python +>>> import torch +>>> import torch.nn as nn +>>> from huggingface_hub import PyTorchModelHubMixin + +# 1. Define your Pytorch model exactly the same way you are used to +>>> class MyModel(nn.Module, PyTorchModelHubMixin): # multiple inheritance +... 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. (optional) Save model to local directory +>>> model.save_pretrained("path/to/my-awesome-model") + +# 3. Push model weights to the Hub +>>> model.push_to_hub("my-awesome-model") + +# 4. Initialize model from the Hub +>>> model = MyModel.from_pretrained("username/my-awesome-model") +``` + +#### Implementation + +The implementation is actually very straightforward, and the full implementation can be found [here](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py). + +1. First, inherit your class from `ModelHubMixin`: + +```python +from huggingface_hub import ModelHubMixin + +class PyTorchModelHubMixin(ModelHubMixin): + (...) +``` + +2. Implement the `_save_pretrained` method: + +```py +from huggingface_hub import ModelCard, ModelCardData + +class PyTorchModelHubMixin(ModelHubMixin): + (...) + + def _save_pretrained(self, save_directory: Path): + """Generate Model Card and save weights from a Pytorch model to a local directory.""" + 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. Implement the `_from_pretrained` method: + +```python +class PyTorchModelHubMixin(ModelHubMixin): + (...) + + @classmethod # Must be a classmethod! + 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", # additional argument + strict: bool = False, # additional argument + **model_kwargs, + ): + """Load Pytorch pretrained weights and return the loaded model.""" + if os.path.isdir(model_id): # Can either be a local directory + print("Loading weights from local directory") + model_file = os.path.join(model_id, "pytorch_model.bin") + else: # Or a model on the Hub + model_file = hf_hub_download( # Download from the hub, passing same input args + 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, + ) + + # Load model and return - custom logic depending on your 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 +``` + +And that's it! Your library now enables users to upload and download files to and from the Hub. + +## Quick comparison + +Let's quickly sum up the two approaches we saw with their advantages and drawbacks. The table below is only indicative. +Your framework might have some specificities that you need to address. This guide is only here to give guidelines and +ideas on how to handle integration. In any case, feel free to contact us if you have any questions! + + +| Integration | Using helpers | Using [`ModelHubMixin`] | +|:---:|:---:|:---:| +| User experience | `model = load_from_hub(...)`
`push_to_hub(model, ...)` | `model = MyModel.from_pretrained(...)`
`model.push_to_hub(...)` | +| Flexibility | Very flexible.
You fully control the implementation. | Less flexible.
Your framework must have a model class. | +| Maintenance | More maintenance to add support for configuration, and new features. Might also require fixing issues reported by users. | Less maintenance as most of the interactions with the Hub are implemented in `huggingface_hub`. | +| Documentation / Type annotation | To be written manually. | Partially handled by `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 new file mode 100644 index 0000000000..aad3be96c8 --- /dev/null +++ b/docs/source/fr/guides/manage-cache.md @@ -0,0 +1,543 @@ + + +# Manage `huggingface_hub` cache-system + +## Understand caching + +The Hugging Face Hub cache-system is designed to be the central cache shared across libraries +that depend on the Hub. It has been updated in v0.8.0 to prevent re-downloading same files +between revisions. + +The caching system is designed as follows: + +``` + +├─ +├─ +├─ +``` + +The `` is usually your user's home directory. However, it is customizable with the `cache_dir` argument on all methods, or by specifying either `HF_HOME` or `HF_HUB_CACHE` environment variable. + +Models, datasets and spaces share a common root. Each of these repositories contains the +repository type, the namespace (organization or username) if it exists and the +repository name: + +``` + +├─ models--julien-c--EsperBERTo-small +├─ models--lysandrejik--arxiv-nlp +├─ models--bert-base-cased +├─ datasets--glue +├─ datasets--huggingface--DataMeasurementsFiles +├─ spaces--dalle-mini--dalle-mini +``` + +It is within these folders that all files will now be downloaded from the Hub. Caching ensures that +a file isn't downloaded twice if it already exists and wasn't updated; but if it was updated, +and you're asking for the latest file, then it will download the latest file (while keeping +the previous file intact in case you need it again). + +In order to achieve this, all folders contain the same skeleton: + +``` + +├─ datasets--glue +│ ├─ refs +│ ├─ blobs +│ ├─ snapshots +... +``` + +Each folder is designed to contain the following: + +### Refs + +The `refs` folder contains files which indicates the latest revision of the given reference. For example, +if we have previously fetched a file from the `main` branch of a repository, the `refs` +folder will contain a file named `main`, which will itself contain the commit identifier of the current head. + +If the latest commit of `main` has `aaaaaa` as identifier, then it will contain `aaaaaa`. + +If that same branch gets updated with a new commit, that has `bbbbbb` as an identifier, then +re-downloading a file from that reference will update the `refs/main` file to contain `bbbbbb`. + +### Blobs + +The `blobs` folder contains the actual files that we have downloaded. The name of each file is their hash. + +### Snapshots + +The `snapshots` folder contains symlinks to the blobs mentioned above. It is itself made up of several folders: +one per known revision! + +In the explanation above, we had initially fetched a file from the `aaaaaa` revision, before fetching a file from +the `bbbbbb` revision. In this situation, we would now have two folders in the `snapshots` folder: `aaaaaa` +and `bbbbbb`. + +In each of these folders, live symlinks that have the names of the files that we have downloaded. For example, +if we had downloaded the `README.md` file at revision `aaaaaa`, we would have the following path: + +``` +//snapshots/aaaaaa/README.md +``` + +That `README.md` file is actually a symlink linking to the blob that has the hash of the file. + +By creating the skeleton this way we open the mechanism to file sharing: if the same file was fetched in +revision `bbbbbb`, it would have the same hash and the file would not need to be re-downloaded. + +### .no_exist (advanced) + +In addition to the `blobs`, `refs` and `snapshots` folders, you might also find a `.no_exist` folder +in your cache. This folder keeps track of files that you've tried to download once but don't exist +on the Hub. Its structure is the same as the `snapshots` folder with 1 subfolder per known revision: + +``` +//.no_exist/aaaaaa/config_that_does_not_exist.json +``` + +Unlike the `snapshots` folder, files are simple empty files (no symlinks). In this example, +the file `"config_that_does_not_exist.json"` does not exist on the Hub for the revision `"aaaaaa"`. +As it only stores empty files, this folder is neglectable is term of disk usage. + +So now you might wonder, why is this information even relevant? +In some cases, a framework tries to load optional files for a model. Saving the non-existence +of optional files makes it faster to load a model as it saves 1 HTTP call per possible optional file. +This is for example the case in `transformers` where each tokenizer can support additional files. +The first time you load the tokenizer on your machine, it will cache which optional files exists (and +which doesn't) to make the loading time faster for the next initializations. + +To test if a file is cached locally (without making any HTTP request), you can use the [`try_to_load_from_cache`] +helper. It will either return the filepath (if exists and cached), the object `_CACHED_NO_EXIST` (if non-existence +is cached) or `None` (if we don't know). + +```python +from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST + +filepath = try_to_load_from_cache() +if isinstance(filepath, str): + # file exists and is cached + ... +elif filepath is _CACHED_NO_EXIST: + # non-existence of file is cached + ... +else: + # file is not cached + ... +``` + +### In practice + +In practice, your cache should look like the following tree: + +```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 + +In order to have an efficient cache-system, `huggingface-hub` uses symlinks. However, +symlinks are not supported on all machines. This is a known limitation especially on +Windows. When this is the case, `huggingface_hub` do not use the `blobs/` directory but +directly stores the files in the `snapshots/` directory instead. This workaround allows +users to download and cache files from the Hub exactly the same way. Tools to inspect +and delete the cache (see below) are also supported. However, the cache-system is less +efficient as a single file might be downloaded several times if multiple revisions of +the same repo is downloaded. + +If you want to benefit from the symlink-based cache-system on a Windows machine, you +either need to [activate Developer Mode](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) +or to run Python as an administrator. + +When symlinks are not supported, a warning message is displayed to the user to alert +them they are using a degraded version of the cache-system. This warning can be disabled +by setting the `HF_HUB_DISABLE_SYMLINKS_WARNING` environment variable to true. + +## Caching assets + +In addition to caching files from the Hub, downstream libraries often requires to cache +other files related to HF but not handled directly by `huggingface_hub` (example: file +downloaded from GitHub, preprocessed data, logs,...). In order to cache those files, +called `assets`, one can use [`cached_assets_path`]. This small helper generates paths +in the HF cache in a unified way based on the name of the library requesting it and +optionally on a namespace and a subfolder name. The goal is to let every downstream +libraries manage its assets its own way (e.g. no rule on the structure) as long as it +stays in the right assets folder. Those libraries can then leverage tools from +`huggingface_hub` to manage the cache, in particular scanning and deleting parts of the +assets from a CLI command. + +```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" # Do anything you like in your assets folder ! +``` + + + +[`cached_assets_path`] is the recommended way to store assets but is not mandatory. If +your library already uses its own cache, feel free to use it! + + + +### Assets in practice + +In practice, your assets cache should look like the following tree: + +```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/ + └── (...) +``` + +## Scan your cache + +At the moment, cached files are never deleted from your local directory: when you download +a new revision of a branch, previous files are kept in case you need them again. +Therefore it can be useful to scan your cache directory in order to know which repos +and revisions are taking the most disk space. `huggingface_hub` provides an helper to +do so that can be used via `huggingface-cli` or in a python script. + +### Scan cache from the terminal + +The easiest way to scan your HF cache-system is to use the `scan-cache` command from +`huggingface-cli` tool. This command scans the cache and prints a report with information +like repo id, repo type, disk usage, refs and full local path. + +The snippet below shows a scan report in a folder in which 4 models and 2 datasets are +cached. + +```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. +``` + +To get a more detailed report, use the `--verbose` option. For each repo, you get a +list of all revisions that have been downloaded. As explained above, the files that don't +change between 2 revisions are shared thanks to the symlinks. This means that the size of +the repo on disk is expected to be less than the sum of the size of each of its revisions. +For example, here `bert-base-cased` has 2 revisions of 1.4G and 1.5G but the total disk +usage is only 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. +``` + +#### Grep example + +Since the output is in tabular format, you can combine it with any `grep`-like tools to +filter the entries. Here is an example to filter only revisions from the "t5-small" +model on a Unix-based machine. + +```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 +``` + +### Scan cache from Python + +For a more advanced usage, use [`scan_cache_dir`] which is the python utility called by +the CLI tool. + +You can use it to get a detailed report structured around 4 dataclasses: + +- [`HFCacheInfo`]: complete report returned by [`scan_cache_dir`] +- [`CachedRepoInfo`]: information about a cached repo +- [`CachedRevisionInfo`]: information about a cached revision (e.g. "snapshot") inside a repo +- [`CachedFileInfo`]: information about a cached file in a snapshot + +Here is a simple usage example. See reference for details. + +```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(...), + # No `last_accessed` as blobs are shared among revisions + 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("Snapshots dir doesn't exist in cached repo: ..."), + CorruptedCacheException(...), + ... + ], +) +``` + +## Clean your cache + +Scanning your cache is interesting but what you really want to do next is usually to +delete some portions to free up some space on your drive. This is possible using the +`delete-cache` CLI command. One can also programmatically use the +[`~HFCacheInfo.delete_revisions`] helper from [`HFCacheInfo`] object returned when +scanning the cache. + +### Delete strategy + +To delete some cache, you need to pass a list of revisions to delete. The tool will +define a strategy to free up the space based on this list. It returns a +[`DeleteCacheStrategy`] object that describes which files and folders will be deleted. +The [`DeleteCacheStrategy`] allows give you how much space is expected to be freed. +Once you agree with the deletion, you must execute it to make the deletion effective. In +order to avoid discrepancies, you cannot edit a strategy object manually. + +The strategy to delete revisions is the following: + +- the `snapshot` folder containing the revision symlinks is deleted. +- blobs files that are targeted only by revisions to be deleted are deleted as well. +- if a revision is linked to 1 or more `refs`, references are deleted. +- if all revisions from a repo are deleted, the entire cached repository is deleted. + + + +Revision hashes are unique across all repositories. This means you don't need to +provide any `repo_id` or `repo_type` when removing revisions. + + + + + +If a revision is not found in the cache, it will be silently ignored. Besides, if a file +or folder cannot be found while trying to delete it, a warning will be logged but no +error is thrown. The deletion continues for other paths contained in the +[`DeleteCacheStrategy`] object. + + + +### Clean cache from the terminal + +The easiest way to delete some revisions from your HF cache-system is to use the +`delete-cache` command from `huggingface-cli` tool. The command has two modes. By +default, a TUI (Terminal User Interface) is displayed to the user to select which +revisions to delete. This TUI is currently in beta as it has not been tested on all +platforms. If the TUI doesn't work on your machine, you can disable it using the +`--disable-tui` flag. + +#### Using the TUI + +This is the default mode. To use it, you first need to install extra dependencies by +running the following command: + +``` +pip install huggingface_hub["cli"] +``` + +Then run the command: + +``` +huggingface-cli delete-cache +``` + +You should now see a list of revisions that you can select/deselect: + +
+ +
+ +Instructions: + - Press keyboard arrow keys `` and `` to move the cursor. + - Press `` to toggle (select/unselect) an item. + - When a revision is selected, the first line is updated to show you how much space + will be freed. + - Press `` to confirm your selection. + - If you want to cancel the operation and quit, you can select the first item + ("None of the following"). If this item is selected, the delete process will be + cancelled, no matter what other items are selected. Otherwise you can also press + `` to quit the TUI. + +Once you've selected the revisions you want to delete and pressed ``, a last +confirmation message will be prompted. Press `` again and the deletion will be +effective. If you want to cancel, enter `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. +``` + +#### Without TUI + +As mentioned above, the TUI mode is currently in beta and is optional. It may be the +case that it doesn't work on your machine or that you don't find it convenient. + +Another approach is to use the `--disable-tui` flag. The process is very similar as you +will be asked to manually review the list of revisions to delete. However, this manual +step will not take place in the terminal directly but in a temporary file generated on +the fly and that you can manually edit. + +This file has all the instructions you need in the header. Open it in your favorite text +editor. To select/deselect a revision, simply comment/uncomment it with a `#`. Once the +manual review is done and the file is edited, you can save it. Go back to your terminal +and press ``. By default it will compute how much space would be freed with the +updated list of revisions. You can continue to edit the file or confirm with `"y"`. + +```sh +huggingface-cli delete-cache --disable-tui +``` + +Example of command file: + +```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 +``` + +### Clean cache from Python + +For more flexibility, you can also use the [`~HFCacheInfo.delete_revisions`] method +programmatically. Here is a simple example. See reference for details. + +```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 new file mode 100644 index 0000000000..95497e420f --- /dev/null +++ b/docs/source/fr/guides/manage-spaces.md @@ -0,0 +1,362 @@ + + +# Manage your Space + +In this guide, we will see how to manage your Space runtime +([secrets](https://huggingface.co/docs/hub/spaces-overview#managing-secrets), +[hardware](https://huggingface.co/docs/hub/spaces-gpus), and [storage](https://huggingface.co/docs/hub/spaces-storage#persistent-storage)) using `huggingface_hub`. + +## A simple example: configure secrets and hardware. + +Here is an end-to-end example to create and setup a Space on the Hub. + +**1. Create a Space on the Hub.** + +```py +>>> from huggingface_hub import HfApi +>>> repo_id = "Wauplin/my-cool-training-space" +>>> api = HfApi() + +# For example with a Gradio SDK +>>> api.create_repo(repo_id=repo_id, repo_type="space", space_sdk="gradio") +``` + +**1. (bis) Duplicate a Space.** + +This can prove useful if you want to build up from an existing Space instead of starting from scratch. +It is also useful is you want control over the configuration/settings of a public Space. See [`duplicate_space`] for more details. + +```py +>>> api.duplicate_space("multimodalart/dreambooth-training") +``` + +**2. Upload your code using your preferred solution.** + +Here is an example to upload the local folder `src/` from your machine to your Space: + +```py +>>> api.upload_folder(repo_id=repo_id, repo_type="space", folder_path="src/") +``` + +At this step, your app should already be running on the Hub for free ! +However, you might want to configure it further with secrets and upgraded hardware. + +**3. Configure secrets and variables** + +Your Space might require some secret keys, token or variables to work. +See [docs](https://huggingface.co/docs/hub/spaces-overview#managing-secrets) for more details. +For example, an HF token to upload an image dataset to the Hub once generated from your 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") +``` + +Secrets and variables can be deleted as well: +```py +>>> api.delete_space_secret(repo_id=repo_id, key="HF_TOKEN") +>>> api.delete_space_variable(repo_id=repo_id, key="MODEL_REPO_ID") +``` + + +From within your Space, secrets are available as environment variables (or +Streamlit Secrets Management if using Streamlit). No need to fetch them via the API! + + + +Any change in your Space configuration (secrets or hardware) will trigger a restart of your app. + + +**Bonus: set secrets and variables when creating or duplicating the Space!** + +Secrets and variables can be set when creating or duplicating a 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. Configure the hardware** + +By default, your Space will run on a CPU environment for free. You can upgrade the hardware +to run it on GPUs. A payment card or a community grant is required to access upgrade your +Space. See [docs](https://huggingface.co/docs/hub/spaces-gpus) for more details. + +```py +# Use `SpaceHardware` enum +>>> from huggingface_hub import SpaceHardware +>>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM) + +# Or simply pass a string value +>>> api.request_space_hardware(repo_id=repo_id, hardware="t4-medium") +``` + +Hardware updates are not done immediately as your Space has to be reloaded on our servers. +At any time, you can check on which hardware your Space is running to see if your request +has been met. + +```py +>>> runtime = api.get_space_runtime(repo_id=repo_id) +>>> runtime.stage +"RUNNING_BUILDING" +>>> runtime.hardware +"cpu-basic" +>>> runtime.requested_hardware +"t4-medium" +``` + +You now have a Space fully configured. Make sure to downgrade your Space back to "cpu-classic" +when you are done using it. + +**Bonus: request hardware when creating or duplicating the Space!** + +Upgraded hardware will be automatically assigned to your Space once it's built. + +```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 hours in secs +... ) +``` +```py +>>> api.duplicate_space( +... from_id=repo_id, +... hardware="cpu-upgrade", +... storage="small", +... sleep_time="7200", # 2 hours in secs +... ) +``` + +**5. Pause and restart your Space** + +By default if your Space is running on an upgraded hardware, it will never be stopped. However to avoid getting billed, +you might want to pause it when you are not using it. This is possible using [`pause_space`]. A paused Space will be +inactive until the owner of the Space restarts it, either with the UI or via API using [`restart_space`]. +For more details about paused mode, please refer to [this section](https://huggingface.co/docs/hub/spaces-gpus#pause) + +```py +# Pause your Space to avoid getting billed +>>> api.pause_space(repo_id=repo_id) +# (...) +# Restart it when you need it +>>> api.restart_space(repo_id=repo_id) +``` + +Another possibility is to set a timeout for your Space. If your Space is inactive for more than the timeout duration, +it will go to sleep. Any visitor landing on your Space will start it back up. You can set a timeout using +[`set_space_sleep_time`]. For more details about sleeping mode, please refer to [this section](https://huggingface.co/docs/hub/spaces-gpus#sleep-time). + +```py +# Put your Space to sleep after 1h of inactivity +>>> api.set_space_sleep_time(repo_id=repo_id, sleep_time=3600) +``` + +Note: if you are using a 'cpu-basic' hardware, you cannot configure a custom sleep time. Your Space will automatically +be paused after 48h of inactivity. + +**Bonus: set a sleep time while requesting hardware** + +Upgraded hardware will be automatically assigned to your Space once it's built. + +```py +>>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM, sleep_time=3600) +``` + +**Bonus: set a sleep time when creating or duplicating the 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. Add persistent storage to your Space** + +You can choose the storage tier of your choice to access disk space that persists across restarts of your Space. This means you can read and write from disk like you would with a traditional hard drive. See [docs](https://huggingface.co/docs/hub/spaces-storage#persistent-storage) for more details. + +```py +>>> from huggingface_hub import SpaceStorage +>>> api.request_space_storage(repo_id=repo_id, storage=SpaceStorage.LARGE) +``` + +You can also delete your storage, losing all the data permanently. +```py +>>> api.delete_space_storage(repo_id=repo_id) +``` + +Note: You cannot decrease the storage tier of your space once it's been granted. To do so, +you must delete the storage first then request the new desired tier. + +**Bonus: request storage when creating or duplicating the 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", +... ) +``` + +## More advanced: temporarily upgrade your Space ! + +Spaces allow for a lot of different use cases. Sometimes, you might want +to temporarily run a Space on a specific hardware, do something and then shut it down. In +this section, we will explore how to benefit from Spaces to finetune a model on demand. +This is only one way of solving this particular problem. It has to be taken as a suggestion +and adapted to your use case. + +Let's assume we have a Space to finetune a model. It is a Gradio app that takes as input +a model id and a dataset id. The workflow is as follows: + +0. (Prompt the user for a model and a dataset) +1. Load the model from the Hub. +2. Load the dataset from the Hub. +3. Finetune the model on the dataset. +4. Upload the new model to the Hub. + +Step 3. requires a custom hardware but you don't want your Space to be running all the time on a paid +GPU. A solution is to dynamically request hardware for the training and shut it +down afterwards. Since requesting hardware restarts your Space, your app must somehow "remember" +the current task it is performing. There are multiple ways of doing this. In this guide +we will see one solution using a Dataset as "task scheduler". + +### App skeleton + +Here is what your app would look like. On startup, check if a task is scheduled and if yes, +run it on the correct hardware. Once done, set back hardware to the free-plan CPU and +prompt the user for a new task. + + +Such a workflow does not support concurrent access as normal demos. +In particular, the interface will be disabled when training occurs. +It is preferable to set your repo as private to ensure you are the only user. + + +```py +# Space will need your token to request hardware: set it as a Secret ! +HF_TOKEN = os.environ.get("HF_TOKEN") + +# Space own repo_id +TRAINING_SPACE_ID = "Wauplin/dreambooth-training" + +from huggingface_hub import HfApi, SpaceHardware +api = HfApi(token=HF_TOKEN) + +# On Space startup, check if a task is scheduled. If yes, finetune the model. If not, +# display an interface to request a new task. +task = get_task() +if task is None: + # Start Gradio app + def gradio_fn(task): + # On user request, add task and request 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) + # Check if Space is loaded with a GPU. + if runtime.hardware == SpaceHardware.T4_MEDIUM: + # If yes, finetune base model on dataset ! + train_and_upload(task) + + # Then, mark the task as "DONE" + mark_as_done(task) + + # DO NOT FORGET: set back CPU hardware + 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) +``` + +### Task scheduler + +Scheduling tasks can be done in many ways. Here is an example how it could be done using +a simple CSV stored as a Dataset. + +```py +# Dataset ID in which a `tasks.csv` file contains the tasks to perform. +# Here is a basic example for `tasks.csv` containing inputs (base model and dataset) +# and status (PENDING or DONE). +# 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", + # Quick and dirty way to add a task + 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", + # Quick and dirty way to set the task as 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 new file mode 100644 index 0000000000..3b2c0d2ebd --- /dev/null +++ b/docs/source/fr/guides/model-cards.md @@ -0,0 +1,360 @@ + + +# Create and share Model Cards + +The `huggingface_hub` library provides a Python interface to create, share, and update Model Cards. +Visit [the dedicated documentation page](https://huggingface.co/docs/hub/models-cards) +for a deeper view of what Model Cards on the Hub are, and how they work under the hood. + + + +[New (beta)! Try our experimental Model Card Creator App](https://huggingface.co/spaces/huggingface/Model_Cards_Writing_Tool) + + + +## Load a Model Card from the Hub + +To load an existing card from the Hub, you can use the [`ModelCard.load`] function. Here, we'll load the card from [`nateraw/vit-base-beans`](https://huggingface.co/nateraw/vit-base-beans). + +```python +from huggingface_hub import ModelCard + +card = ModelCard.load('nateraw/vit-base-beans') +``` + +This card has some helpful attributes that you may want to access/leverage: + - `card.data`: Returns a [`ModelCardData`] instance with the model card's metadata. Call `.to_dict()` on this instance to get the representation as a dictionary. + - `card.text`: Returns the text of the card, *excluding the metadata header*. + - `card.content`: Returns the text content of the card, *including the metadata header*. + +## Create Model Cards + +### From Text + +To initialize a Model Card from text, just pass the text content of the card to the `ModelCard` on init. + +```python +content = """ +--- +language: en +license: mit +--- + +# My Model Card +""" + +card = ModelCard(content) +card.data.to_dict() == {'language': 'en', 'license': 'mit'} # True +``` + +Another way you might want to do this is with f-strings. In the following example, we: + +- Use [`ModelCardData.to_yaml`] to convert metadata we defined to YAML so we can use it to insert the YAML block in the model card. +- Show how you might use a template variable via Python f-strings. + +```python +card_data = ModelCardData(language='en', license='mit', library='timm') + +example_template_var = 'nateraw' +content = f""" +--- +{ card_data.to_yaml() } +--- + +# My Model Card + +This model created by [@{example_template_var}](https://github.com/{example_template_var}) +""" + +card = ModelCard(content) +print(card) +``` + +The above example would leave us with a card that looks like this: + +``` +--- +language: en +license: mit +library: timm +--- + +# My Model Card + +This model created by [@nateraw](https://github.com/nateraw) +``` + +### From a Jinja Template + +If you have `Jinja2` installed, you can create Model Cards from a jinja template file. Let's see a basic example: + +```python +from pathlib import Path + +from huggingface_hub import ModelCard, ModelCardData + +# Define your jinja template +template_text = """ +--- +{{ card_data }} +--- + +# Model Card for MyCoolModel + +This model does this and that. + +This model was created by [@{{ author }}](https://hf.co/{{author}}). +""".strip() + +# Write the template to a file +Path('custom_template.md').write_text(template_text) + +# Define card metadata +card_data = ModelCardData(language='en', license='mit', library_name='keras') + +# Create card from template, passing it any jinja template variables you want. +# In our case, we'll pass author +card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw') +card.save('my_model_card_1.md') +print(card) +``` + +The resulting card's markdown looks like this: + +``` +--- +language: en +license: mit +library_name: keras +--- + +# Model Card for MyCoolModel + +This model does this and that. + +This model was created by [@nateraw](https://hf.co/nateraw). +``` + +If you update any card.data, it'll reflect in the card itself. + +``` +card.data.library_name = 'timm' +card.data.language = 'fr' +card.data.license = 'apache-2.0' +print(card) +``` + +Now, as you can see, the metadata header has been updated: + +``` +--- +language: fr +license: apache-2.0 +library_name: timm +--- + +# Model Card for MyCoolModel + +This model does this and that. + +This model was created by [@nateraw](https://hf.co/nateraw). +``` + +As you update the card data, you can validate the card is still valid against the Hub by calling [`ModelCard.validate`]. This ensures that the card passes any validation rules set up on the Hugging Face Hub. + +### From the Default Template + +Instead of using your own template, you can also use the [default template](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md), which is a fully featured model card with tons of sections you may want to fill out. Under the hood, it uses [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) to fill out a template file. + + + +Note that you will have to have Jinja2 installed to use `from_template`. You can do so with `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) +``` + +## Share Model Cards + +If you're authenticated with the Hugging Face Hub (either by using `huggingface-cli login` or [`login`]), you can push cards to the Hub by simply calling [`ModelCard.push_to_hub`]. Let's take a look at how to do that... + +First, we'll create a new repo called 'hf-hub-modelcards-pr-test' under the authenticated user's namespace: + +```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) +``` + +Then, we'll create a card from the default template (same as the one defined in the section above): + +```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", +) +``` + +Finally, we'll push that up to the hub + +```python +card.push_to_hub(repo_id) +``` + +You can check out the resulting card [here](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/blob/main/README.md). + +If you instead wanted to push a card as a pull request, you can just say `create_pr=True` when calling `push_to_hub`: + +```python +card.push_to_hub(repo_id, create_pr=True) +``` + +A resulting PR created from this command can be seen [here](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/discussions/3). + +## Update metadata + +In this section we will see what metadata are in repo cards and how to update them. + +`metadata` refers to a hash map (or key value) context that provides some high-level information about a model, dataset or Space. That information can include details such as the model's `pipeline type`, `model_id` or `model_description`. For more detail you can take a look to these guides: [Model Card](https://huggingface.co/docs/hub/model-cards#model-card-metadata), [Dataset Card](https://huggingface.co/docs/hub/datasets-cards#dataset-card-metadata) and [Spaces Settings](https://huggingface.co/docs/hub/spaces-settings#spaces-settings). +Now lets see some examples on how to update those metadata. + + +Let's start with a first example: + +```python +>>> from huggingface_hub import metadata_update +>>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"}) +``` + +With these two lines of code you will update the metadata to set a new `pipeline_tag`. + +By default, you cannot update a key that is already existing on the card. If you want to do so, you must pass +`overwrite=True` explicitly: + + +```python +>>> from huggingface_hub import metadata_update +>>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True) +``` + +It often happen that you want to suggest some changes to a repository +on which you don't have write permission. You can do that by creating a PR on that repo which will allow the owners to +review and merge your suggestions. + +```python +>>> from huggingface_hub import metadata_update +>>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True) +``` + +## Include Evaluation Results + +To include evaluation results in the metadata `model-index`, you can pass an [`EvalResult`] or a list of `EvalResult` with your associated evaluation results. Under the hood it'll create the `model-index` when you call `card.data.to_dict()`. For more information on how this works, you can check out [this section of the Hub docs](https://huggingface.co/docs/hub/models-cards#evaluation-results). + + + +Note that using this function requires you to include the `model_name` attribute in [`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) +``` + +The resulting `card.data` should look like this: + +``` +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 +``` + +If you have more than one evaluation result you'd like to share, just pass a list of `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 +``` + +Which should leave you with the following `card.data`: + +``` +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 new file mode 100644 index 0000000000..b97bd6b76a --- /dev/null +++ b/docs/source/fr/guides/overview.md @@ -0,0 +1,131 @@ + + +# How-to guides + +In this section, you will find practical guides to help you achieve a specific goal. +Take a look at these guides to learn how to use huggingface_hub to solve real-world problems: + +
+
+ + +
+ Repository +

+ How to create a repository on the Hub? How to configure it? How to interact with it? +

+ + + +
+ Download files +

+ How do I download a file from the Hub? How do I download a repository? +

+ + + +
+ Upload files +

+ How to upload a file or a folder? How to make changes to an existing repository on the Hub? +

+ + + +
+ Search +

+ How to efficiently search through the 200k+ public models, datasets and spaces? +

+ + + +
+ HfFileSystem +

+ How to interact with the Hub through a convenient interface that mimics Python's file interface? +

+ + + +
+ Inference +

+ How to make predictions using the accelerated Inference API? +

+ + + +
+ Community Tab +

+ How to interact with the Community tab (Discussions and Pull Requests)? +

+ + + +
+ Collections +

+ How to programmatically build collections? +

+ + + +
+ Cache +

+ How does the cache-system work? How to benefit from it? +

+ + + +
+ Model Cards +

+ How to create and share Model Cards? +

+ + + +
+ Manage your Space +

+ How to manage your Space hardware and configuration? +

+ + + +
+ Integrate a library +

+ What does it mean to integrate a library with the Hub? And how to do it? +

+ + + +
+ Webhooks server +

+ How to create a server to receive Webhooks and deploy it as a Space? +

+ + +
+
diff --git a/docs/source/fr/guides/repository.md b/docs/source/fr/guides/repository.md new file mode 100644 index 0000000000..787a01afb9 --- /dev/null +++ b/docs/source/fr/guides/repository.md @@ -0,0 +1,243 @@ + + +# Create and manage a repository + +The Hugging Face Hub is a collection of git repositories. [Git](https://git-scm.com/) is a widely used tool in software +development to easily version projects when working collaboratively. This guide will show you how to interact with the +repositories on the Hub, especially: + +- Create and delete a repository. +- Manage branches and tags. +- Rename your repository. +- Update your repository visibility. +- Manage a local copy of your repository. + + + +If you are used to working with platforms such as GitLab/GitHub/Bitbucket, your first instinct +might be to use `git` CLI to clone your repo (`git clone`), commit changes (`git add, git commit`) and push them +(`git push`). This is valid when using the Hugging Face Hub. However, software engineering and machine learning do +not share the same requirements and workflows. Model repositories might maintain large model weight files for different +frameworks and tools, so cloning the repository can lead to you maintaining large local folders with massive sizes. As +a result, it may be more efficient to use our custom HTTP methods. You can read our [Git vs HTTP paradigm](../concepts/git_vs_http) +explanation page for more details. + + + +If you want to create and manage a repository on the Hub, your machine must be logged in. If you are not, please refer to +[this section](../quick-start#login). In the rest of this guide, we will assume that your machine is logged in. + +## Repo creation and deletion + +The first step is to know how to create and delete repositories. You can only manage repositories that you own (under +your username namespace) or from organizations in which you have write permissions. + +### Create a repository + +Create an empty repository with [`create_repo`] and give it a name with the `repo_id` parameter. The `repo_id` is your namespace followed by the repository name: `username_or_org/repo_name`. + +```py +>>> from huggingface_hub import create_repo +>>> create_repo("lysandre/test-model") +'https://huggingface.co/lysandre/test-model' +``` + +By default, [`create_repo`] creates a model repository. But you can use the `repo_type` parameter to specify another repository type. For example, if you want to create a dataset repository: + +```py +>>> from huggingface_hub import create_repo +>>> create_repo("lysandre/test-dataset", repo_type="dataset") +'https://huggingface.co/datasets/lysandre/test-dataset' +``` + +When you create a repository, you can set your repository visibility with the `private` parameter. + +```py +>>> from huggingface_hub import create_repo +>>> create_repo("lysandre/test-private", private=True) +``` + +If you want to change the repository visibility at a later time, you can use the [`update_repo_visibility`] function. + +### Delete a repository + +Delete a repository with [`delete_repo`]. Make sure you want to delete a repository because this is an irreversible process! + +Specify the `repo_id` of the repository you want to delete: + +```py +>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset") +``` + +### Duplicate a repository (only for Spaces) + +In some cases, you want to copy someone else's repo to adapt it to your use case. +This is possible for Spaces using the [`duplicate_space`] method. It will duplicate the whole repository. +You will still need to configure your own settings (hardware, sleep-time, storage, variables and secrets). Check out our [Manage your Space](./manage-spaces) guide for more details. + +```py +>>> from huggingface_hub import duplicate_space +>>> duplicate_space("multimodalart/dreambooth-training", private=False) +RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...) +``` + +## Upload and download files + +Now that you have created your repository, you are interested in pushing changes to it and downloading files from it. + +These 2 topics deserve their own guides. Please refer to the [upload](./upload) and the [download](./download) guides +to learn how to use your repository. + + +## Branches and tags + +Git repositories often make use of branches to store different versions of a same repository. +Tags can also be used to flag a specific state of your repository, for example, when releasing a version. +More generally, branches and tags are referred as [git references](https://git-scm.com/book/en/v2/Git-Internals-Git-References). + +### Create branches and tags + +You can create new branch and tags using [`create_branch`] and [`create_tag`]: + +```py +>>> from huggingface_hub import create_branch, create_tag + +# Create a branch on a Space repo from `main` branch +>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker") + +# Create a tag on a Dataset repo from `v0.1-release` branch +>>> create_branch("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.") +``` + +You can use the [`delete_branch`] and [`delete_tag`] functions in the same way to delete a branch or a tag. + +### List all branches and tags + +You can also list the existing git refs from a repository using [`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') + ] +) +``` + +## Change repository settings + +Repositories come with some settings that you can configure. Most of the time, you will want to do that manually in the +repo settings page in your browser. You must have write access to a repo to configure it (either own it or being part of +an organization). In this section, we will see the settings that you can also configure programmatically using `huggingface_hub`. + +Some settings are specific to Spaces (hardware, environment variables,...). To configure those, please refer to our [Manage your Spaces](../guides/manage-spaces) guide. + +### Update visibility + +A repository can be public or private. A private repository is only visible to you or members of the organization in which the repository is located. Change a repository to private as shown in the following: + +```py +>>> from huggingface_hub import update_repo_visibility +>>> update_repo_visibility(repo_id=repo_id, private=True) +``` + +### Rename your repository + +You can rename your repository on the Hub using [`move_repo`]. Using this method, you can also move the repo from a user to +an organization. When doing so, there are a [few limitations](https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo) +that you should be aware of. For example, you can't transfer your repo to another user. + +```py +>>> from huggingface_hub import move_repo +>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model") +``` + +## Manage a local copy of your repository + +All the actions described above can be done using HTTP requests. However, in some cases you might be interested in having +a local copy of your repository and interact with it using the Git commands you are familiar with. + +The [`Repository`] class allows you to interact with files and repositories on the Hub with functions similar to Git commands. It is a wrapper over Git and Git-LFS methods to use the Git commands you already know and love. Before starting, please make sure you have Git-LFS installed (see [here](https://git-lfs.github.com/) for installation instructions). + + + +[`Repository`] is deprecated in favor of the http-based alternatives implemented in [`HfApi`]. Given its large adoption in legacy code, the complete removal of [`Repository`] will only happen in release `v1.0`. For more details, please read [this explanation page](./concepts/git_vs_http). + + + +### Use a local repository + +Instantiate a [`Repository`] object with a path to a local repository: + +```py +>>> from huggingface_hub import Repository +>>> repo = Repository(local_dir="//") +``` + +### Clone + +The `clone_from` parameter clones a repository from a Hugging Face repository ID to a local directory specified by the `local_dir` argument: + +```py +>>> from huggingface_hub import Repository +>>> repo = Repository(local_dir="w2v2", clone_from="facebook/wav2vec2-large-960h-lv60") +``` + +`clone_from` can also clone a repository using a URL: + +```py +>>> repo = Repository(local_dir="huggingface-hub", clone_from="https://huggingface.co/facebook/wav2vec2-large-960h-lv60") +``` + +You can combine the `clone_from` parameter with [`create_repo`] to create and clone a repository: + +```py +>>> repo_url = create_repo(repo_id="repo_name") +>>> repo = Repository(local_dir="repo_local_path", clone_from=repo_url) +``` + +You can also configure a Git username and email to a cloned repository by specifying the `git_user` and `git_email` parameters when you clone a repository. When users commit to that repository, Git will be aware of the commit author. + +```py +>>> repo = Repository( +... "my-dataset", +... clone_from="/", +... token=True, +... repo_type="dataset", +... git_user="MyName", +... git_email="me@cool.mail" +... ) +``` + +### Branch + +Branches are important for collaboration and experimentation without impacting your current files and code. Switch between branches with [`~Repository.git_checkout`]. For example, if you want to switch from `branch1` to `branch2`: + +```py +>>> from huggingface_hub import Repository +>>> repo = Repository(local_dir="huggingface-hub", clone_from="/", revision='branch1') +>>> repo.git_checkout("branch2") +``` + +### Pull + +[`~Repository.git_pull`] allows you to update a current local branch with changes from a remote repository: + +```py +>>> from huggingface_hub import Repository +>>> repo.git_pull() +``` + +Set `rebase=True` if you want your local commits to occur after your branch is updated with the new commits from the remote: + +```py +>>> repo.git_pull(rebase=True) +``` diff --git a/docs/source/fr/guides/search.md b/docs/source/fr/guides/search.md new file mode 100644 index 0000000000..6f25d02296 --- /dev/null +++ b/docs/source/fr/guides/search.md @@ -0,0 +1,70 @@ + + +# Search the Hub + +In this tutorial, you will learn how to search models, datasets and spaces on the Hub using `huggingface_hub`. + +## How to list repositories ? + +`huggingface_hub` library includes an HTTP client [`HfApi`] to interact with the Hub. +Among other things, it can list models, datasets and spaces stored on the Hub: + +```py +>>> from huggingface_hub import HfApi +>>> api = HfApi() +>>> models = api.list_models() +``` + +The output of [`list_models`] is an iterator over the models stored on the Hub. + +Similarly, you can use [`list_datasets`] to list datasets and [`list_spaces`] to list Spaces. + +## How to filter repositories ? + +Listing repositories is great but now you might want to filter your search. +The list helpers have several attributes like: +- `filter` +- `author` +- `search` +- ... + +Two of these parameters are intuitive (`author` and `search`), but what about that `filter`? +`filter` takes as input a [`ModelFilter`] object (or [`DatasetFilter`]). You can instantiate +it by specifying which models you want to filter. + +Let's see an example to get all models on the Hub that does image classification, have been +trained on the imagenet dataset and that runs with PyTorch. That can be done with a single +[`ModelFilter`]. Attributes are combined as "logical AND". + +```py +models = hf_api.list_models( + filter=ModelFilter( + task="image-classification", + library="pytorch", + trained_dataset="imagenet" + ) +) +``` + +While filtering, you can also sort the models and take only the top results. For example, +the following example fetches the top 5 most downloaded datasets on the 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, + (...) +``` + + + +To explore available filter on the Hub, visit [models](https://huggingface.co/models) and [datasets](https://huggingface.co/datasets) pages +in your browser, search for some parameters and look at the values in the URL. + diff --git a/docs/source/fr/guides/upload.md b/docs/source/fr/guides/upload.md new file mode 100644 index 0000000000..19226fa541 --- /dev/null +++ b/docs/source/fr/guides/upload.md @@ -0,0 +1,579 @@ + + +# Upload files to the Hub + +Sharing your files and work is an important aspect of the Hub. The `huggingface_hub` offers several options for uploading your files to the Hub. You can use these functions independently or integrate them into your library, making it more convenient for your users to interact with the Hub. This guide will show you how to push files: + +- without using Git. +- that are very large with [Git LFS](https://git-lfs.github.com/). +- with the `commit` context manager. +- with the [`~Repository.push_to_hub`] function. + +Whenever you want to upload files to the Hub, you need to log in to your Hugging Face account: + +- Log in to your Hugging Face account with the following command: + + ```bash + huggingface-cli login + # or using an environment variable + huggingface-cli login --token $HUGGINGFACE_TOKEN + ``` + +- Alternatively, you can programmatically login using [`login`] in a notebook or a script: + + ```python + >>> from huggingface_hub import login + >>> login() + ``` + + If ran in a Jupyter or Colaboratory notebook, [`login`] will launch a widget from + which you can enter your Hugging Face access token. Otherwise, a message will be + prompted in the terminal. + + It is also possible to login programmatically without the widget by directly passing + the token to [`login`]. If you do so, be careful when sharing your notebook. It is + best practice to load the token from a secure vault instead of saving it in plain in + your Colaboratory notebook. + +## Upload a file + +Once you've created a repository with [`create_repo`], you can upload a file to your repository using [`upload_file`]. + +Specify the path of the file to upload, where you want to upload the file to in the repository, and the name of the repository you want to add the file to. Depending on your repository type, you can optionally set the repository type as a `dataset`, `model`, or `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 a folder + +Use the [`upload_folder`] function to upload a local folder to an existing repository. Specify the path of the local folder +to upload, where you want to upload the folder to in the repository, and the name of the repository you want to add the +folder to. Depending on your repository type, you can optionally set the repository type as a `dataset`, `model`, or `space`. + +```py +>>> from huggingface_hub import HfApi +>>> api = HfApi() + +# Upload all the content from the local folder to your remote Space. +# By default, files are uploaded at the root of the repo +>>> api.upload_folder( +... folder_path="/path/to/local/space", +... repo_id="username/my-cool-space", +... repo_type="space", +... ) +``` + +By default, the `.gitignore` file will be taken into account to know which files should be committed or not. By default we check if a `.gitignore` file is present in a commit, and if not, we check if it exists on the Hub. Please be aware that only a `.gitignore` file present at the root of the directory with be used. We do not check for `.gitignore` files in subdirectories. + +If you don't want to use an hardcoded `.gitignore` file, you can use the `allow_patterns` and `ignore_patterns` arguments to filter which files to upload. These parameters accept either a single pattern or a list of patterns. Patterns are Standard Wildcards (globbing patterns) as documented [here](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). If both `allow_patterns` and `ignore_patterns` are provided, both constraints apply. + +Beside the `.gitignore` file and allow/ignore patterns, any `.git/` folder present in any subdirectory will be ignored. + +```py +>>> api.upload_folder( +... folder_path="/path/to/local/folder", +... path_in_repo="my-dataset/train", # Upload to a specific folder +... repo_id="username/test-dataset", +... repo_type="dataset", +... ignore_patterns="**/logs/*.txt", # Ignore all text logs +... ) +``` + +You can also use the `delete_patterns` argument to specify files you want to delete from the repo in the same commit. +This can prove useful if you want to clean a remote folder before pushing files in it and you don't know which files +already exists. + +The example below uploads the local `./logs` folder to the remote `/experiment/logs/` folder. Only txt files are uploaded +but before that, all previous logs on the repo on deleted. All of this in a single 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 all local text files +... delete_patterns="*.txt", # Delete all remote text files before +... ) +``` + +## Upload from the CLI + +You can use the `huggingface-cli upload` command from the terminal to directly upload files to the Hub. Internally it uses the same [`upload_file`] and [`upload_folder`] helpers described above. + +You can either upload a single file or an entire folder: + +```bash +# 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` and `path_in_repo` are optional and can be implicitly inferred. If `local_path` is not set, the tool will +check if a local folder or file has the same name as the `repo_id`. If that's the case, its content will be uploaded. +Otherwise, an exception is raised asking the user to explicitly set `local_path`. In any case, if `path_in_repo` is not +set, files are uploaded at the root of the repo. + +For more details about the CLI upload command, please refer to the [CLI guide](./cli#huggingface-cli-upload). + +## Advanced features + +In most cases, you won't need more than [`upload_file`] and [`upload_folder`] to upload your files to the Hub. +However, `huggingface_hub` has more advanced features to make things easier. Let's have a look at them! + + +### Non-blocking uploads + +In some cases, you want to push data without blocking your main thread. This is particularly useful to upload logs and +artifacts while continuing a training. To do so, you can use the `run_as_future` argument in both [`upload_file`] and +[`upload_folder`]. This will return a [`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#future-objects) +object that you can use to check the status of the upload. + +```py +>>> from huggingface_hub import HfApi +>>> api = HfApi() +>>> future = api.upload_folder( # Upload in the background (non-blocking action) +... repo_id="username/my-model", +... folder_path="checkpoints-001", +... run_as_future=True, +... ) +>>> future +Future(...) +>>> future.done() +False +>>> future.result() # Wait for the upload to complete (blocking action) +... +``` + + + +Background jobs are queued when using `run_as_future=True`. This means that you are guaranteed that the jobs will be +executed in the correct order. + + + +Even though background jobs are mostly useful to upload data/create commits, you can queue any method you like using +[`run_as_future`]. For instance, you can use it to create a repo and then upload data to it in the background. The +built-in `run_as_future` argument in upload methods is just an alias around it. + +```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 a folder by chunks + +[`upload_folder`] makes it easy to upload an entire folder to the Hub. However, for large folders (thousands of files or +hundreds of GB), it can still be challenging. If you have a folder with a lot of files, you might want to upload +it in several commits. If you experience an error or a connection issue during the upload, you would not have to resume +the process from the beginning. + +To upload a folder in multiple commits, just pass `multi_commits=True` as argument. Under the hood, `huggingface_hub` +will list the files to upload/delete and split them in several commits. The "strategy" (i.e. how to split the commits) +is based on the number and size of the files to upload. A PR is open on the Hub to push all the commits. Once the PR is +ready, the commits are squashed into a single commit. If the process is interrupted before completing, you can rerun +your script to resume the upload. The created PR will be automatically detected and the upload will resume from where +it stopped. It is recommended to pass `multi_commits_verbose=True` to get a better understanding of the upload and its +progress. + +The example below will upload the checkpoints folder to a dataset in multiple commits. A PR will be created on the Hub +and merged automatically once the upload is complete. If you prefer the PR to stay open and review it manually, you can +pass `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, +... ) +``` + +If you want a better control on the upload strategy (i.e. the commits that are created), you can have a look at the +low-level [`plan_multi_commits`] and [`create_commits_on_pr`] methods. + + + +`multi_commits` is still an experimental feature. Its API and behavior is subject to change in the future without prior +notice. + + + +### Scheduled uploads + +The Hugging Face Hub makes it easy to save and version data. However, there are some limitations when updating the same file thousands of times. For instance, you might want to save logs of a training process or user +feedback on a deployed Space. In these cases, uploading the data as a dataset on the Hub makes sense, but it can be hard to do properly. The main reason is that you don't want to version every update of your data because it'll make the git repository unusable. The [`CommitScheduler`] class offers a solution to this problem. + +The idea is to run a background job that regularly pushes a local folder to the Hub. Let's assume you have a +Gradio Space that takes as input some text and generates two translations of it. Then, the user can select their preferred translation. For each run, you want to save the input, output, and user preference to analyze the results. This is a +perfect use case for [`CommitScheduler`]; you want to save data to the Hub (potentially millions of user feedback), but +you don't _need_ to save in real-time each user's input. Instead, you can save the data locally in a JSON file and +upload it every 10 minutes. For example: + +```py +>>> import json +>>> import uuid +>>> from pathlib import Path +>>> import gradio as gr +>>> from huggingface_hub import CommitScheduler + +# Define the file where to save the data. Use UUID to make sure not to overwrite existing data from a previous run. +>>> feedback_file = Path("user_feedback/") / f"data_{uuid.uuid4()}.json" +>>> feedback_folder = feedback_file.parent + +# Schedule regular uploads. Remote repo and local folder are created if they don't already exist. +>>> scheduler = CommitScheduler( +... repo_id="report-translation-feedback", +... repo_type="dataset", +... folder_path=feedback_folder, +... path_in_repo="data", +... every=10, +... ) + +# Define the function that will be called when the user submits its feedback (to be called in Gradio) +>>> 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") + +# Start Gradio +>>> with gr.Blocks() as demo: +>>> ... # define Gradio demo + use `save_feedback` +>>> demo.launch() +``` + +And that's it! User input/outputs and feedback will be available as a dataset on the Hub. By using a unique JSON file name, you are guaranteed you won't overwrite data from a previous run or data from another +Spaces/replicas pushing concurrently to the same repository. + +For more details about the [`CommitScheduler`], here is what you need to know: +- **append-only:** + It is assumed that you will only add content to the folder. You must only append data to existing files or create + new files. Deleting or overwriting a file might corrupt your repository. +- **git history**: + The scheduler will commit the folder every `every` minutes. To avoid polluting the git repository too much, it is + recommended to set a minimal value of 5 minutes. Besides, the scheduler is designed to avoid empty commits. If no + new content is detected in the folder, the scheduled commit is dropped. +- **errors:** + The scheduler run as background thread. It is started when you instantiate the class and never stops. In particular, + if an error occurs during the upload (example: connection issue), the scheduler will silently ignore it and retry + at the next scheduled commit. +- **thread-safety:** + In most cases it is safe to assume that you can write to a file without having to worry about a lock file. The + scheduler will not crash or be corrupted if you write content to the folder while it's uploading. In practice, + _it is possible_ that concurrency issues happen for heavy-loaded apps. In this case, we advice to use the + `scheduler.lock` lock to ensure thread-safety. The lock is blocked only when the scheduler scans the folder for + changes, not when it uploads data. You can safely assume that it will not affect the user experience on your Space. + +#### Space persistence demo + +Persisting data from a Space to a Dataset on the Hub is the main use case for [`CommitScheduler`]. Depending on the use +case, you might want to structure your data differently. The structure has to be robust to concurrent users and +restarts which often implies generating UUIDs. Besides robustness, you should upload data in a format readable by the 🤗 Datasets library for later reuse. We created a [Space](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) +that demonstrates how to save several different data formats (you may need to adapt it for your own specific needs). + +#### Custom uploads + +[`CommitScheduler`] assumes your data is append-only and should be uploading "as is". However, you +might want to customize the way data is uploaded. You can do that by creating a class inheriting from [`CommitScheduler`] +and overwrite the `push_to_hub` method (feel free to overwrite it any way you want). You are guaranteed it will +be called every `every` minutes in a background thread. You don't have to worry about concurrency and errors but you +must be careful about other aspects, such as pushing empty commits or duplicated data. + +In the (simplified) example below, we overwrite `push_to_hub` to zip all PNG files in a single archive to avoid +overloading the repo on the Hub: + +```py +class ZipScheduler(CommitScheduler): + def push_to_hub(self): + # 1. List PNG files + png_files = list(self.folder_path.glob("*.png")) + if len(png_files) == 0: + return None # return early if nothing to commit + + # 2. Zip png files in a single 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 archive + self.api.upload_file(..., path_or_fileobj=archive_path) + + # 4. Delete local png files to avoid re-uploading them later + for png_file in png_files: + png_file.unlink() +``` + +When you overwrite `push_to_hub`, you have access to the attributes of [`CommitScheduler`] and especially: +- [`HfApi`] client: `api` +- Folder parameters: `folder_path` and `path_in_repo` +- Repo parameters: `repo_id`, `repo_type`, `revision` +- The thread lock: `lock` + + + +For more examples of custom schedulers, check out our [demo Space](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) +containing different implementations depending on your use cases. + + + +### create_commit + +The [`upload_file`] and [`upload_folder`] functions are high-level APIs that are generally convenient to use. We recommend +trying these functions first if you don't need to work at a lower level. However, if you want to work at a commit-level, +you can use the [`create_commit`] function directly. + +There are three types of operations supported by [`create_commit`]: + +- [`CommitOperationAdd`] uploads a file to the Hub. If the file already exists, the file contents are overwritten. This operation accepts two arguments: + + - `path_in_repo`: the repository path to upload a file to. + - `path_or_fileobj`: either a path to a file on your filesystem or a file-like object. This is the content of the file to upload to the Hub. + +- [`CommitOperationDelete`] removes a file or a folder from a repository. This operation accepts `path_in_repo` as an argument. + +- [`CommitOperationCopy`] copies a file within a repository. This operation accepts three arguments: + + - `src_path_in_repo`: the repository path of the file to copy. + - `path_in_repo`: the repository path where the file should be copied. + - `src_revision`: optional - the revision of the file to copy if your want to copy a file from a different branch/revision. + +For example, if you want to upload two files and delete a file in a Hub repository: + +1. Use the appropriate `CommitOperation` to add or delete a file and to delete a folder: + +```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. Pass your operations to [`create_commit`]: + +```py +>>> api.create_commit( +... repo_id="lysandre/test-model", +... operations=operations, +... commit_message="Upload my model weights and license", +... ) +``` + +In addition to [`upload_file`] and [`upload_folder`], the following functions also use [`create_commit`] under the hood: + +- [`delete_file`] deletes a single file from a repository on the Hub. +- [`delete_folder`] deletes an entire folder from a repository on the Hub. +- [`metadata_update`] updates a repository's metadata. + +For more detailed information, take a look at the [`HfApi`] reference. + +### Preupload LFS files before commit + +In some cases, you might want to upload huge files to S3 **before** making the commit call. For example, if you are +committing a dataset in several shards that are generated in-memory, you would need to upload the shards one by one +to avoid an out-of-memory issue. A solution is to upload each shard as a separate commit on the repo. While being +perfectly valid, this solution has the drawback of potentially messing the git history by generating tens of commits. +To overcome this issue, you can upload your files one by one to S3 and then create a single commit at the end. This +is possible using [`preupload_lfs_files`] in combination with [`create_commit`]. + + + +This is a power-user method. Directly using [`upload_file`], [`upload_folder`] or [`create_commit`] instead of handling +the low-level logic of pre-uploading files is the way to go in the vast majority of cases. The main caveat of +[`preupload_lfs_files`] is that until the commit is actually made, the upload files are not accessible on the repo on +the Hub. If you have a question, feel free to ping us on our Discord or in a GitHub issue. + + + +Here is a simple example illustrating how to pre-upload files: + +```py +>>> from huggingface_hub import CommitOperationAdd, preupload_lfs_files, create_commit, create_repo + +>>> repo_id = create_repo("test_preupload").repo_id + +>>> operations = [] # List of all `CommitOperationAdd` objects that will be generated +>>> for i in range(5): +... content = ... # generate binary content +... addition = CommitOperationAdd(path_in_repo=f"shard_{i}_of_5.bin", path_or_fileobj=content) +... preupload_lfs_files(repo_id, additions=[addition]) +... operations.append(addition) + +>>> # Create commit +>>> create_commit(repo_id, operations=operations, commit_message="Commit all shards") +``` + +First, we create the [`CommitOperationAdd`] objects one by one. In a real-world example, those would contain the +generated shards. Each file is uploaded before generating the next one. During the [`preupload_lfs_files`] step, **the +`CommitOperationAdd` object is mutated**. You should only use it to pass it directly to [`create_commit`]. The main +update of the object is that **the binary content is removed** from it, meaning that it will be garbage-collected if +you don't store another reference to it. This is expected as we don't want to keep in memory the content that is +already uploaded. Finally we create the commit by passing all the operations to [`create_commit`]. You can pass +additional operations (add, delete or copy) that have not been processed yet and they will be handled correctly. + +## Tips and tricks for large uploads + +There are some limitations to be aware of when dealing with a large amount of data in your repo. Given the time it takes to stream the data, +getting an upload/push to fail at the end of the process or encountering a degraded experience, be it on hf.co or when working locally, can be very annoying. + +Check out our [Repository limitations and recommendations](https://huggingface.co/docs/hub/repositories-recommendations) guide for best practices on how to structure your repositories on the Hub. Next, let's move on with some practical tips to make your upload process as smooth as possible. + +- **Start small**: We recommend starting with a small amount of data to test your upload script. It's easier to iterate +on a script when failing takes only a little time. +- **Expect failures**: Streaming large amounts of data is challenging. You don't know what can happen, but it's always +best to consider that something will fail at least once -no matter if it's due to your machine, your connection, or our +servers. For example, if you plan to upload a large number of files, it's best to keep track locally of which files you +already uploaded before uploading the next batch. You are ensured that an LFS file that is already committed will never +be re-uploaded twice but checking it client-side can still save some time. +- **Use `hf_transfer`**: this is a Rust-based [library](https://github.com/huggingface/hf_transfer) meant to speed up +uploads on machines with very high bandwidth. To use it, you must install it (`pip install hf_transfer`) and enable it +by setting `HF_HUB_ENABLE_HF_TRANSFER=1` as an environment variable. You can then use `huggingface_hub` normally. +Disclaimer: this is a power user tool. It is tested and production-ready but lacks user-friendly features like advanced error handling or proxies. For more details, please refer to this [section](https://huggingface.co/docs/huggingface_hub/hf_transfer). + + + +Progress bars are supported in `hf_transfer` starting from version `0.1.4`. Consider upgrading (`pip install -U hf-transfer`) if you plan to enable faster uploads. + + + +## (legacy) Upload files with Git LFS + +All the methods described above use the Hub's API to upload files. This is the recommended way to upload files to the Hub. +However, we also provide [`Repository`], a wrapper around the git tool to manage a local repository. + + + +Although [`Repository`] is not formally deprecated, we recommend using the HTTP-based methods described above instead. +For more details about this recommendation, please have a look at [this guide](../concepts/git_vs_http) explaining the +core differences between HTTP-based and Git-based approaches. + + + +Git LFS automatically handles files larger than 10MB. But for very large files (>5GB), you need to install a custom transfer agent for Git LFS: + +```bash +huggingface-cli lfs-enable-largefiles +``` + +You should install this for each repository that has a very large file. Once installed, you'll be able to push files larger than 5GB. + +### commit context manager + +The `commit` context manager handles four of the most common Git commands: pull, add, commit, and push. `git-lfs` automatically tracks any file larger than 10MB. In the following example, the `commit` context manager: + +1. Pulls from the `text-files` repository. +2. Adds a change made to `file.txt`. +3. Commits the change. +4. Pushes the change to the `text-files` repository. + +```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})) +``` + +Here is another example of how to use the `commit` context manager to save and upload a file to a repository: + +```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") +``` + +Set `blocking=False` if you would like to push your commits asynchronously. Non-blocking behavior is helpful when you want to continue running your script while your commits are being pushed. + +```python +>>> with repo.commit(commit_message="My cool model :)", blocking=False) +``` + +You can check the status of your push with the `command_queue` method: + +```python +>>> last_command = repo.command_queue[-1] +>>> last_command.status +``` + +Refer to the table below for the possible statuses: + +| Status | Description | +| -------- | ------------------------------------ | +| -1 | The push is ongoing. | +| 0 | The push has completed successfully. | +| Non-zero | An error has occurred. | + +When `blocking=False`, commands are tracked, and your script will only exit when all pushes are completed, even if other errors occur in your script. Some additional useful commands for checking the status of a push include: + +```python +# Inspect an error. +>>> last_command.stderr + +# Check whether a push is completed or ongoing. +>>> last_command.is_done + +# Check whether a push command has errored. +>>> last_command.failed +``` + +### push_to_hub + +The [`Repository`] class has a [`~Repository.push_to_hub`] function to add files, make a commit, and push them to a repository. Unlike the `commit` context manager, you'll need to pull from a repository first before calling [`~Repository.push_to_hub`]. + +For example, if you've already cloned a repository from the Hub, then you can initialize the `repo` from the local directory: + +```python +>>> from huggingface_hub import Repository +>>> repo = Repository(local_dir="path/to/local/repo") +``` + +Update your local clone with [`~Repository.git_pull`] and then push your file to the Hub: + +```py +>>> repo.git_pull() +>>> repo.push_to_hub(commit_message="Commit my-awesome-file to the Hub") +``` + +However, if you aren't ready to push a file yet, you can use [`~Repository.git_add`] and [`~Repository.git_commit`] to only add and commit your file: + +```py +>>> repo.git_add("path/to/file") +>>> repo.git_commit(commit_message="add my first model config file :)") +``` + +When you're ready, push the file to your repository with [`~Repository.git_push`]: + +```py +>>> repo.git_push() +``` diff --git a/docs/source/fr/guides/webhooks_server.md b/docs/source/fr/guides/webhooks_server.md new file mode 100644 index 0000000000..1545c22938 --- /dev/null +++ b/docs/source/fr/guides/webhooks_server.md @@ -0,0 +1,199 @@ + + +# Webhooks Server + +Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on specific repos or to +all repos belonging to particular users/organizations you're interested in following. This guide will explain how to +leverage `huggingface_hub` to create a server listening to webhooks and deploy it to a Space. It assumes you are +familiar with the concept of webhooks on the Huggingface Hub. To learn more about webhooks themselves, you can read +this [guide](https://huggingface.co/docs/hub/webhooks) first. + +The base class that we will use in this guide is [`WebhooksServer`]. It is a class for easily configuring a server that +can receive webhooks from the Huggingface Hub. The server is based on a [Gradio](https://gradio.app/) app. It has a UI +to display instructions for you or your users and an API to listen to webhooks. + + + +To see a running example of a webhook server, check out the [Spaces CI Bot](https://huggingface.co/spaces/spaces-ci-bot/webhook) +one. It is a Space that launches ephemeral environments when a PR is opened on a Space. + + + + + +This is an [experimental feature](../package_reference/environment_variables#hfhubdisableexperimentalwarning). This +means that we are still working on improving the API. Breaking changes might be introduced in the future without prior +notice. Make sure to pin the version of `huggingface_hub` in your requirements. + + + + +## Create an endpoint + +Implementing a webhook endpoint is as simple as decorating a function. Let's see a first example to explain the main +concepts: + +```python +# app.py +from huggingface_hub import webhook_endpoint, WebhookPayload + +@webhook_endpoint +async def trigger_training(payload: WebhookPayload) -> None: + if payload.repo.type == "dataset" and payload.event.action == "update": + # Trigger a training job if a dataset is updated + ... +``` + +Save this snippet in a file called `'app.py'` and run it with `'python app.py'`. You should see a message like this: + +```text +Webhook secret is not defined. This means your webhook endpoints will be open to everyone. +To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: + `app = WebhooksServer(webhook_secret='my_secret', ...)` +For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret. +Running on local URL: http://127.0.0.1:7860 +Running on public URL: https://1fadb0f52d8bf825fc.gradio.live + +This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces + +Webhooks are correctly setup and ready to use: + - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training +Go to https://huggingface.co/settings/webhooks to setup your webhooks. +``` + +Good job! You just launched a webhook server! Let's break down what happened exactly: + +1. By decorating a function with [`webhook_endpoint`], a [`WebhooksServer`] object has been created in the background. +As you can see, this server is a Gradio app running on http://127.0.0.1:7860. If you open this URL in your browser, you +will see a landing page with instructions about the registered webhooks. +2. A Gradio app is a FastAPI server under the hood. A new POST route `/webhooks/trigger_training` has been added to it. +This is the route that will listen to webhooks and run the `trigger_training` function when triggered. FastAPI will +automatically parse the payload and pass it to the function as a [`WebhookPayload`] object. This is a `pydantic` object +that contains all the information about the event that triggered the webhook. +3. The Gradio app also opened a tunnel to receive requests from the internet. This is the interesting part: you can +configure a Webhook on https://huggingface.co/settings/webhooks pointing to your local machine. This is useful for +debugging your webhook server and quickly iterating before deploying it to a Space. +4. Finally, the logs also tell you that your server is currently not secured by a secret. This is not problematic for +local debugging but is to keep in mind for later. + + + +By default, the server is started at the end of your script. If you are running it in a notebook, you can start the +server manually by calling `decorated_function.run()`. Since a unique server is used, you only have to start the server +once even if you have multiple endpoints. + + + + +## Configure a Webhook + +Now that you have a webhook server running, you want to configure a Webhook to start receiving messages. +Go to https://huggingface.co/settings/webhooks, click on "Add a new webhook" and configure your Webhook. Set the target +repositories you want to watch and the Webhook URL, here `https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training`. + +
+ +
+ +And that's it! You can now trigger that webhook by updating the target repository (e.g. push a commit). Check the +Activity tab of your Webhook to see the events that have been triggered. Now that you have a working setup, you can +test it and quickly iterate. If you modify your code and restart the server, your public URL might change. Make sure +to update the webhook configuration on the Hub if needed. + +## Deploy to a Space + +Now that you have a working webhook server, the goal is to deploy it to a Space. Go to https://huggingface.co/new-space +to create a Space. Give it a name, select the Gradio SDK and click on "Create Space". Upload your code to the Space +in a file called `app.py`. Your Space will start automatically! For more details about Spaces, please refer to this +[guide](https://huggingface.co/docs/hub/spaces-overview). + +Your webhook server is now running on a public Space. If most cases, you will want to secure it with a secret. Go to +your Space settings > Section "Repository secrets" > "Add a secret". Set the `WEBHOOK_SECRET` environment variable to +the value of your choice. Go back to the [Webhooks settings](https://huggingface.co/settings/webhooks) and set the +secret in the webhook configuration. Now, only requests with the correct secret will be accepted by your server. + +And this is it! Your Space is now ready to receive webhooks from the Hub. Please keep in mind that if you run the Space +on a free 'cpu-basic' hardware, it will be shut down after 48 hours of inactivity. If you need a permanent Space, you +should consider setting to an [upgraded hardware](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs). + +## Advanced usage + +The guide above explained the quickest way to setup a [`WebhooksServer`]. In this section, we will see how to customize +it further. + +### Multiple endpoints + +You can register multiple endpoints on the same server. For example, you might want to have one endpoint to trigger +a training job and another one to trigger a model evaluation. You can do this by adding multiple `@webhook_endpoint` +decorators: + +```python +# app.py +from huggingface_hub import webhook_endpoint, WebhookPayload + +@webhook_endpoint +async def trigger_training(payload: WebhookPayload) -> None: + if payload.repo.type == "dataset" and payload.event.action == "update": + # Trigger a training job if a dataset is updated + ... + +@webhook_endpoint +async def trigger_evaluation(payload: WebhookPayload) -> None: + if payload.repo.type == "model" and payload.event.action == "update": + # Trigger an evaluation job if a model is updated + ... +``` + +Which will create two endpoints: + +```text +(...) +Webhooks are correctly setup and ready to use: + - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training + - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation +``` + +### Custom server + +To get more flexibility, you can also create a [`WebhooksServer`] object directly. This is useful if you want to +customize the landing page of your server. You can do this by passing a [Gradio UI](https://gradio.app/docs/#blocks) +that will overwrite the default one. For example, you can add instructions for your users or add a form to manually +trigger the webhooks. When creating a [`WebhooksServer`], you can register new webhooks using the +[`~WebhooksServer.add_webhook`] decorator. + +Here is a complete example: + +```python +import gradio as gr +from fastapi import Request +from huggingface_hub import WebhooksServer, WebhookPayload + +# 1. Define UI +with gr.Blocks() as ui: + ... + +# 2. Create WebhooksServer with custom UI and secret +app = WebhooksServer(ui=ui, webhook_secret="my_secret_key") + +# 3. Register webhook with explicit name +@app.add_webhook("/say_hello") +async def hello(payload: WebhookPayload): + return {"message": "hello"} + +# 4. Register webhook with implicit name +@app.add_webhook +async def goodbye(payload: WebhookPayload): + return {"message": "goodbye"} + +# 5. Start server (optional) +app.run() +``` + +1. We define a custom UI using Gradio blocks. This UI will be displayed on the landing page of the server. +2. We create a [`WebhooksServer`] object with a custom UI and a secret. The secret is optional and can be set with +the `WEBHOOK_SECRET` environment variable. +3. We register a webhook with an explicit name. This will create an endpoint at `/webhooks/say_hello`. +4. We register a webhook with an implicit name. This will create an endpoint at `/webhooks/goodbye`. +5. We start the server. This is optional as your server will automatically be started at the end of the script. \ No newline at end of file diff --git a/docs/source/fr/index.md b/docs/source/fr/index.md new file mode 100644 index 0000000000..15efbb1dd5 --- /dev/null +++ b/docs/source/fr/index.md @@ -0,0 +1,60 @@ + + +# 🤗 Hub client library + +The `huggingface_hub` library allows you to interact with the [Hugging Face +Hub](https://hf.co), a machine learning platform for creators and collaborators. +Discover pre-trained models and datasets for your projects or play with the hundreds of +machine learning apps hosted on the Hub. You can also create and share your own models +and datasets with the community. The `huggingface_hub` library provides a simple way to +do all these things with Python. + +Read the [quick start guide](quick-start) to get up and running with the +`huggingface_hub` library. You will learn how to download files from the Hub, create a +repository, and upload files to the Hub. Keep reading to learn more about how to manage +your repositories on the 🤗 Hub, how to interact in discussions or even how to access +the Inference API. + +
+
+ + +
How-to guides
+

Practical guides to help you achieve a specific goal. Take a look at these guides to learn how to use huggingface_hub to solve real-world problems.

+ + + +
Reference
+

Exhaustive and technical description of huggingface_hub classes and methods.

+ + + +
Conceptual guides
+

High-level explanations for building a better understanding of huggingface_hub philosophy.

+ + +
+
+ + + +## Contribute + +All contributions to the `huggingface_hub` are welcomed and equally valued! 🤗 Besides +adding or fixing existing issues in the code, you can also help improve the +documentation by making sure it is accurate and up-to-date, help answer questions on +issues, and request new features you think will improve the library. Take a look at the +[contribution +guide](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) to +learn more about how to submit a new issue or feature request, how to submit a pull +request, and how to test your contributions to make sure everything works as expected. + +Contributors should also be respectful of our [code of +conduct](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) to +create an inclusive and welcoming collaborative space for everyone. \ No newline at end of file diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md new file mode 100644 index 0000000000..1426f20818 --- /dev/null +++ b/docs/source/fr/installation.md @@ -0,0 +1,160 @@ + + +# Installation + +Before you start, you will need to setup your environment by installing the appropriate packages. + +`huggingface_hub` is tested on **Python 3.8+**. + +## Install with pip + +It is highly recommended to install `huggingface_hub` in a [virtual environment](https://docs.python.org/3/library/venv.html). +If you are unfamiliar with Python virtual environments, take a look at this [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). +A virtual environment makes it easier to manage different projects, and avoid compatibility issues between dependencies. + +Start by creating a virtual environment in your project directory: + +```bash +python -m venv .env +``` + +Activate the virtual environment. On Linux and macOS: + +```bash +source .env/bin/activate +``` + +Activate virtual environment on Windows: + +```bash +.env/Scripts/activate +``` + +Now you're ready to install `huggingface_hub` [from the PyPi registry](https://pypi.org/project/huggingface-hub/): + +```bash +pip install --upgrade huggingface_hub +``` + +Once done, [check installation](#check-installation) is working correctly. + +### Install optional dependencies + +Some dependencies of `huggingface_hub` are [optional](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) because they are not required to run the core features of `huggingface_hub`. However, some features of the `huggingface_hub` may not be available if the optional dependencies aren't installed. + +You can install optional dependencies via `pip`: +```bash +# Install dependencies for tensorflow-specific features +# /!\ Warning: this is not equivalent to `pip install tensorflow` +pip install 'huggingface_hub[tensorflow]' + +# Install dependencies for both torch-specific and CLI-specific features. +pip install 'huggingface_hub[cli,torch]' +``` + +Here is the list of optional dependencies in `huggingface_hub`: +- `cli`: provide a more convenient CLI interface for `huggingface_hub`. +- `fastai`, `torch`, `tensorflow`: dependencies to run framework-specific features. +- `dev`: dependencies to contribute to the lib. Includes `testing` (to run tests), `typing` (to run type checker) and `quality` (to run linters). + + + +### Install from source + +In some cases, it is interesting to install `huggingface_hub` directly from source. +This allows you to use the bleeding edge `main` version rather than the latest stable version. +The `main` version is useful for staying up-to-date with the latest developments, for instance +if a bug has been fixed since the last official release but a new release hasn't been rolled out yet. + +However, this means the `main` version may not always be stable. We strive to keep the +`main` version operational, and most issues are usually resolved +within a few hours or a day. If you run into a problem, please open an Issue so we can +fix it even sooner! + +```bash +pip install git+https://github.com/huggingface/huggingface_hub +``` + +When installing from source, you can also specify a specific branch. This is useful if you +want to test a new feature or a new bug-fix that has not been merged yet: + +```bash +pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch +``` + +Once done, [check installation](#check-installation) is working correctly. + +### Editable install + +Installing from source allows you to setup an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). +This is a more advanced installation if you plan to contribute to `huggingface_hub` +and need to test changes in the code. You need to clone a local copy of `huggingface_hub` +on your machine. + +```bash +# First, clone repo locally +git clone https://github.com/huggingface/huggingface_hub.git + +# Then, install with -e flag +cd huggingface_hub +pip install -e . +``` + +These commands will link the folder you cloned the repository to and your Python library paths. +Python will now look inside the folder you cloned to in addition to the normal library paths. +For example, if your Python packages are typically installed in `./.venv/lib/python3.11/site-packages/`, +Python will also search the folder you cloned `./huggingface_hub/`. + +## Install with conda + +If you are more familiar with it, you can install `huggingface_hub` using the [conda-forge channel](https://anaconda.org/conda-forge/huggingface_hub): + + +```bash +conda install -c conda-forge huggingface_hub +``` + +Once done, [check installation](#check-installation) is working correctly. + +## Check installation + +Once installed, check that `huggingface_hub` works properly by running the following command: + +```bash +python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" +``` + +This command will fetch information from the Hub about the [gpt2](https://huggingface.co/gpt2) model. +Output should look like this: + +```text +Model Name: gpt2 +Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space'] +Task: text-generation +``` + +## Windows limitations + +With our goal of democratizing good ML everywhere, we built `huggingface_hub` to be a +cross-platform library and in particular to work correctly on both Unix-based and Windows +systems. However, there are a few cases where `huggingface_hub` has some limitations when +run on Windows. Here is an exhaustive list of known issues. Please let us know if you +encounter any undocumented problem by opening [an issue on Github](https://github.com/huggingface/huggingface_hub/issues/new/choose). + +- `huggingface_hub`'s cache system relies on symlinks to efficiently cache files downloaded +from the Hub. On Windows, you must activate developer mode or run your script as admin to +enable symlinks. If they are not activated, the cache-system still works but in an non-optimized +manner. Please read [the cache limitations](./guides/manage-cache#limitations) section for more details. +- Filepaths on the Hub can have special characters (e.g. `"path/to?/my/file"`). Windows is +more restrictive on [special characters](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) +which makes it impossible to download those files on Windows. Hopefully this is a rare case. +Please reach out to the repo owner if you think this is a mistake or to us to figure out +a solution. + + +## Next steps + +Once `huggingface_hub` is properly installed on your machine, you might want +[configure environment variables](package_reference/environment_variables) or [check one of our guides](guides/overview) to get started. \ No newline at end of file diff --git a/docs/source/fr/package_reference/cache.md b/docs/source/fr/package_reference/cache.md new file mode 100644 index 0000000000..b3326c239e --- /dev/null +++ b/docs/source/fr/package_reference/cache.md @@ -0,0 +1,59 @@ + + +# Cache-system reference + +The caching system was updated in v0.8.0 to become the central cache-system shared +across libraries that depend on the Hub. Read the [cache-system guide](../guides/manage-cache) +for a detailed presentation of caching at HF. + +## Helpers + +### try_to_load_from_cache + +[[autodoc]] huggingface_hub.try_to_load_from_cache + +### cached_assets_path + +[[autodoc]] huggingface_hub.cached_assets_path + +### scan_cache_dir + +[[autodoc]] huggingface_hub.scan_cache_dir + +## Data structures + +All structures are built and returned by [`scan_cache_dir`] and are immutable. + +### HFCacheInfo + +[[autodoc]] huggingface_hub.HFCacheInfo + +### CachedRepoInfo + +[[autodoc]] huggingface_hub.CachedRepoInfo + - size_on_disk_str + - refs + +### CachedRevisionInfo + +[[autodoc]] huggingface_hub.CachedRevisionInfo + - size_on_disk_str + - nb_files + +### CachedFileInfo + +[[autodoc]] huggingface_hub.CachedFileInfo + - size_on_disk_str + +### DeleteCacheStrategy + +[[autodoc]] huggingface_hub.DeleteCacheStrategy + - expected_freed_size_str + +## Exceptions + +### CorruptedCacheException + +[[autodoc]] huggingface_hub.CorruptedCacheException \ No newline at end of file diff --git a/docs/source/fr/package_reference/cards.md b/docs/source/fr/package_reference/cards.md new file mode 100644 index 0000000000..4f64238bd7 --- /dev/null +++ b/docs/source/fr/package_reference/cards.md @@ -0,0 +1,78 @@ + + +# Repository Cards + +The huggingface_hub library provides a Python interface to create, share, and update Model/Dataset Cards. +Visit the [dedicated documentation page](https://huggingface.co/docs/hub/models-cards) for a deeper view of what +Model Cards on the Hub are, and how they work under the hood. You can also check out our [Model Cards guide](../how-to-model-cards) to +get a feel for how you would use these utilities in your own projects. + +## Repo Card + +The `RepoCard` object is the parent class of [`ModelCard`], [`DatasetCard`] and `SpaceCard`. + +[[autodoc]] huggingface_hub.repocard.RepoCard + - __init__ + - all + +## Card Data + +The [`CardData`] object is the parent class of [`ModelCardData`] and [`DatasetCardData`]. + +[[autodoc]] huggingface_hub.repocard_data.CardData + +## Model Cards + +### ModelCard + +[[autodoc]] ModelCard + +### ModelCardData + +[[autodoc]] ModelCardData + +## Dataset Cards + +Dataset cards are also known as Data Cards in the ML Community. + +### DatasetCard + +[[autodoc]] DatasetCard + +### DatasetCardData + +[[autodoc]] DatasetCardData + +## Space Cards + +### SpaceCard + +[[autodoc]] SpaceCard + +### SpaceCardData + +[[autodoc]] SpaceCardData + +## Utilities + +### EvalResult + +[[autodoc]] EvalResult + +### model_index_to_eval_results + +[[autodoc]] huggingface_hub.repocard_data.model_index_to_eval_results + +### eval_results_to_model_index + +[[autodoc]] huggingface_hub.repocard_data.eval_results_to_model_index + +### metadata_eval_result + +[[autodoc]] huggingface_hub.repocard.metadata_eval_result + +### metadata_update + +[[autodoc]] huggingface_hub.repocard.metadata_update \ No newline at end of file diff --git a/docs/source/fr/package_reference/collections.md b/docs/source/fr/package_reference/collections.md new file mode 100644 index 0000000000..37fe25039c --- /dev/null +++ b/docs/source/fr/package_reference/collections.md @@ -0,0 +1,24 @@ + + +# Managing collections + +Check out the [`HfApi`] documentation page for the reference of methods to manage your Space on the Hub. + +- Get collection content: [`get_collection`] +- Create new collection: [`create_collection`] +- Update a collection: [`update_collection_metadata`] +- Delete a collection: [`delete_collection`] +- Add an item to a collection: [`add_collection_item`] +- Update an item in a collection: [`update_collection_item`] +- Remove an item from a collection: [`delete_collection_item`] + + +### Collection + +[[autodoc]] Collection + +### CollectionItem + +[[autodoc]] CollectionItem \ No newline at end of file diff --git a/docs/source/fr/package_reference/community.md b/docs/source/fr/package_reference/community.md new file mode 100644 index 0000000000..d41d45c8a6 --- /dev/null +++ b/docs/source/fr/package_reference/community.md @@ -0,0 +1,34 @@ + + +# Interacting with Discussions and Pull Requests + +Check the [`HfApi`] documentation page for the reference of methods enabling +interaction with Pull Requests and Discussions on the Hub. + +- [`get_repo_discussions`] +- [`get_discussion_details`] +- [`create_discussion`] +- [`create_pull_request`] +- [`rename_discussion`] +- [`comment_discussion`] +- [`edit_discussion_comment`] +- [`change_discussion_status`] +- [`merge_pull_request`] + +## Data structures + +[[autodoc]] Discussion + +[[autodoc]] DiscussionWithDetails + +[[autodoc]] DiscussionEvent + +[[autodoc]] DiscussionComment + +[[autodoc]] DiscussionStatusChange + +[[autodoc]] DiscussionCommit + +[[autodoc]] DiscussionTitleChange diff --git a/docs/source/fr/package_reference/environment_variables.md b/docs/source/fr/package_reference/environment_variables.md new file mode 100644 index 0000000000..0ee1c2be89 --- /dev/null +++ b/docs/source/fr/package_reference/environment_variables.md @@ -0,0 +1,175 @@ + + +# Environment variables + +`huggingface_hub` can be configured using environment variables. + +If you are unfamiliar with environment variable, here are generic articles about them +[on macOS and Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) +and on [Windows](https://phoenixnap.com/kb/windows-set-environment-variable). + +This page will guide you through all environment variables specific to `huggingface_hub` +and their meaning. + +## Generic + +### HF_INFERENCE_ENDPOINT + +To configure the inference api base url. You might want to set this variable if your organization +is pointing at an API Gateway rather than directly at the inference api. + +Defaults to `"https://api-inference.huggingface.com"`. + +### HF_HOME + +To configure where `huggingface_hub` will locally store data. In particular, your token +and the cache will be stored in this folder. + +Defaults to `"~/.cache/huggingface"` unless [XDG_CACHE_HOME](#xdgcachehome) is set. + +### HF_HUB_CACHE + +To configure where repositories from the Hub will be cached locally (models, datasets and +spaces). + +Defaults to `"$HF_HOME/hub"` (e.g. `"~/.cache/huggingface/hub"` by default). + +### HF_ASSETS_CACHE + +To configure where [assets](../guides/manage-cache#caching-assets) created by downstream libraries +will be cached locally. Those assets can be preprocessed data, files downloaded from GitHub, +logs,... + +Defaults to `"$HF_HOME/assets"` (e.g. `"~/.cache/huggingface/assets"` by default). + +### HF_TOKEN + +To configure the User Access Token to authenticate to the Hub. If set, this value will +overwrite the token stored on the machine (in `"$HF_HOME/token"`). + +See [login reference](../package_reference/login) for more details. + +### HF_HUB_VERBOSITY + +Set the verbosity level of the `huggingface_hub`'s logger. Must be one of +`{"debug", "info", "warning", "error", "critical"}`. + +Defaults to `"warning"`. + +For more details, see [logging reference](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity). + +### HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD + +Integer value to define under which size a file is considered as "small". When downloading files to a local directory, +small files will be duplicated to ease user experience while bigger files are symlinked to save disk usage. + +For more details, see the [download guide](../guides/download#download-files-to-local-folder). + +### HF_HUB_ETAG_TIMEOUT + +Integer value to define the number of seconds to wait for server response when fetching the latest metadata from a repo before downloading a file. If the request times out, `huggingface_hub` will default to the locally cached files. Setting a lower value speeds up the workflow for machines with a slow connection that have already cached files. A higher value guarantees the metadata call to succeed in more cases. Default to 10s. + +### HF_HUB_DOWNLOAD_TIMEOUT + +Integer value to define the number of seconds to wait for server response when downloading a file. If the request times out, a TimeoutError is raised. Setting a higher value is beneficial on machine with a slow connection. A smaller value makes the process fail quicker in case of complete network outage. Default to 10s. + +## Boolean values + +The following environment variables expect a boolean value. The variable will be considered +as `True` if its value is one of `{"1", "ON", "YES", "TRUE"}` (case-insensitive). Any other value +(or undefined) will be considered as `False`. + +### HF_HUB_OFFLINE + +If set, no HTTP calls will me made when trying to fetch files. Only files that are already +cached will be accessed. This is useful in case your network is slow and you don't care +about having absolutely the latest version of a file. + +**Note:** even if the latest version of a file is cached, calling `hf_hub_download` still triggers +a HTTP request to check that a new version is not available. Setting `HF_HUB_OFFLINE=1` will +skip this call which speeds up your loading time. + +### HF_HUB_DISABLE_IMPLICIT_TOKEN + +Authentication is not mandatory for every requests to the Hub. For instance, requesting +details about `"gpt2"` model does not require to be authenticated. However, if a user is +[logged in](../package_reference/login), the default behavior will be to always send the token +in order to ease user experience (never get a HTTP 401 Unauthorized) when accessing private or gated repositories. For privacy, you can +disable this behavior by setting `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. In this case, +the token will be sent only for "write-access" calls (example: create a commit). + +**Note:** disabling implicit sending of token can have weird side effects. For example, +if you want to list all models on the Hub, your private models will not be listed. You +would need to explicitly pass `token=True` argument in your script. + +### HF_HUB_DISABLE_PROGRESS_BARS + +For time consuming tasks, `huggingface_hub` displays a progress bar by default (using tqdm). +You can disable all the progress bars at once by setting `HF_HUB_DISABLE_PROGRESS_BARS=1`. + +### HF_HUB_DISABLE_SYMLINKS_WARNING + +If you are on a Windows machine, it is recommended to enable the developer mode or to run +`huggingface_hub` in admin mode. If not, `huggingface_hub` will not be able to create +symlinks in your cache system. You will be able to execute any script but your user experience +will be degraded as some huge files might end-up duplicated on your hard-drive. A warning +message is triggered to warn you about this behavior. Set `HF_HUB_DISABLE_SYMLINKS_WARNING=1`, +to disable this warning. + +For more details, see [cache limitations](../guides/manage-cache#limitations). + +### HF_HUB_DISABLE_EXPERIMENTAL_WARNING + +Some features of `huggingface_hub` are experimental. This means you can use them but we do not guarantee they will be +maintained in the future. In particular, we might update the API or behavior of such features without any deprecation +cycle. A warning message is triggered when using an experimental feature to warn you about it. If you're comfortable debugging any potential issues using an experimental feature, you can set `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` to disable the warning. + +If you are using an experimental feature, please let us know! Your feedback can help us design and improve it. + +### HF_HUB_DISABLE_TELEMETRY + +By default, some data is collected by HF libraries (`transformers`, `datasets`, `gradio`,..) to monitor usage, debug issues and help prioritize features. +Each library defines its own policy (i.e. which usage to monitor) but the core implementation happens in `huggingface_hub` (see [`send_telemetry`]). + +You can set `HF_HUB_DISABLE_TELEMETRY=1` as environment variable to globally disable telemetry. + +### HF_HUB_ENABLE_HF_TRANSFER + +Set to `True` for faster uploads and downloads from the Hub using `hf_transfer`. + +By default, `huggingface_hub` uses the Python-based `requests.get` and `requests.post` functions. Although these are reliable and versatile, they may not be the most efficient choice for machines with high bandwidth. [`hf_transfer`](https://github.com/huggingface/hf_transfer) is a Rust-based package developed to maximize the bandwidth used by dividing large files into smaller parts and transferring them simultaneously using multiple threads. This approach can potentially double the transfer speed. To use `hf_transfer`, you need to install it separately [from PyPI](https://pypi.org/project/hf-transfer/) and set `HF_HUB_ENABLE_HF_TRANSFER=1` as an environment variable. + +Please note that using `hf_transfer` comes with certain limitations. Since it is not purely Python-based, debugging errors may be challenging. Additionally, `hf_transfer` lacks several user-friendly features such as resumable downloads and proxies. These omissions are intentional to maintain the simplicity and speed of the Rust logic. Consequently, `hf_transfer` is not enabled by default in `huggingface_hub`. + +## Deprecated environment variables + +In order to standardize all environment variables within the Hugging Face ecosystem, some variables have been marked as deprecated. Although they remain functional, they no longer take precedence over their replacements. The following table outlines the deprecated variables and their corresponding alternatives: + + +| Deprecated Variable | Replacement | +| --- | --- | +| `HUGGINGFACE_HUB_CACHE` | `HF_HUB_CACHE` | +| `HUGGINGFACE_ASSETS_CACHE` | `HF_ASSETS_CACHE` | +| `HUGGING_FACE_HUB_TOKEN` | `HF_TOKEN` | +| `HUGGINGFACE_HUB_VERBOSITY` | `HF_HUB_VERBOSITY` | + +## From external tools + +Some environment variables are not specific to `huggingface_hub` but are still taken into account when they are set. + +### NO_COLOR + +Boolean value. When set, `huggingface-cli` tool will not print any ANSI color. +See [no-color.org](https://no-color.org/). + +### XDG_CACHE_HOME + +Used only when `HF_HOME` is not set! + +This is the default way to configure where [user-specific non-essential (cached) data should be written](https://wiki.archlinux.org/title/XDG_Base_Directory) +on linux machines. + +If `HF_HOME` is not set, the default home will be `"$XDG_CACHE_HOME/huggingface"` instead +of `"~/.cache/huggingface"`. diff --git a/docs/source/fr/package_reference/file_download.md b/docs/source/fr/package_reference/file_download.md new file mode 100644 index 0000000000..1bc5b21478 --- /dev/null +++ b/docs/source/fr/package_reference/file_download.md @@ -0,0 +1,38 @@ + + +# Downloading files + +## Download a single file + +### hf_hub_download + +[[autodoc]] huggingface_hub.hf_hub_download + +### hf_hub_url + +[[autodoc]] huggingface_hub.hf_hub_url + +## Download a snapshot of the repo + +[[autodoc]] huggingface_hub.snapshot_download + +## Get metadata about a file + +### get_hf_file_metadata + +[[autodoc]] huggingface_hub.get_hf_file_metadata + +### HfFileMetadata + +[[autodoc]] huggingface_hub.HfFileMetadata + +## Caching + +The methods displayed above are designed to work with a caching system that prevents +re-downloading files. The caching system was updated in v0.8.0 to become the central +cache-system shared across libraries that depend on the Hub. + +Read the [cache-system guide](../guides/manage-cache) for a detailed presentation of caching at +at HF. diff --git a/docs/source/fr/package_reference/hf_api.md b/docs/source/fr/package_reference/hf_api.md new file mode 100644 index 0000000000..eeb15c1830 --- /dev/null +++ b/docs/source/fr/package_reference/hf_api.md @@ -0,0 +1,132 @@ + + +# HfApi Client + +Below is the documentation for the `HfApi` class, which serves as a Python wrapper for the Hugging Face Hub's API. + +All methods from the `HfApi` are also accessible from the package's root directly. Both approaches are detailed below. + +Using the root method is more straightforward but the [`HfApi`] class gives you more flexibility. +In particular, you can pass a token that will be reused in all HTTP calls. This is different +than `huggingface-cli login` or [`login`] as the token is not persisted on the machine. +It is also possible to provide a different endpoint or configure a custom user-agent. + +```python +from huggingface_hub import HfApi, list_models + +# Use root method +models = list_models() + +# Or configure a HfApi client +hf_api = HfApi( + endpoint="https://huggingface.co", # Can be a Private Hub endpoint. + token="hf_xxx", # Token is not persisted on the machine. +) +models = hf_api.list_models() +``` + +## HfApi + +[[autodoc]] HfApi + +[[autodoc]] plan_multi_commits + +## API Dataclasses + +### CommitInfo + +[[autodoc]] huggingface_hub.hf_api.CommitInfo + +### DatasetInfo + +[[autodoc]] huggingface_hub.hf_api.DatasetInfo + +### GitRefInfo + +[[autodoc]] huggingface_hub.hf_api.GitRefInfo + +### GitCommitInfo + +[[autodoc]] huggingface_hub.hf_api.GitCommitInfo + +### GitRefs + +[[autodoc]] huggingface_hub.hf_api.GitRefs + +### ModelInfo + +[[autodoc]] huggingface_hub.hf_api.ModelInfo + +### RepoSibling + +[[autodoc]] huggingface_hub.hf_api.RepoSibling + +### RepoFile + +[[autodoc]] huggingface_hub.hf_api.RepoFile + +### RepoUrl + +[[autodoc]] huggingface_hub.hf_api.RepoUrl + +### SafetensorsRepoMetadata + +[[autodoc]] huggingface_hub.utils.SafetensorsRepoMetadata + +### SafetensorsFileMetadata + +[[autodoc]] huggingface_hub.utils.SafetensorsFileMetadata + +### SpaceInfo + +[[autodoc]] huggingface_hub.hf_api.SpaceInfo + +### TensorInfo + +[[autodoc]] huggingface_hub.utils.TensorInfo + +### User + +[[autodoc]] huggingface_hub.hf_api.User + +### UserLikes + +[[autodoc]] huggingface_hub.hf_api.UserLikes + +## CommitOperation + +Below are the supported values for [`CommitOperation`]: + +[[autodoc]] CommitOperationAdd + +[[autodoc]] CommitOperationDelete + +[[autodoc]] CommitOperationCopy + +## CommitScheduler + +[[autodoc]] CommitScheduler + +## Token helper + +`huggingface_hub` stores the authentication information locally so that it may be re-used in subsequent +methods. + +It does this using the [`HfFolder`] utility, which saves data at the root of the user. + +[[autodoc]] HfFolder + +## Search helpers + +Some helpers to filter repositories on the Hub are available in the `huggingface_hub` package. + +### DatasetFilter + +[[autodoc]] DatasetFilter + +### ModelFilter + +[[autodoc]] ModelFilter + diff --git a/docs/source/fr/package_reference/hf_file_system.md b/docs/source/fr/package_reference/hf_file_system.md new file mode 100644 index 0000000000..f203ebd070 --- /dev/null +++ b/docs/source/fr/package_reference/hf_file_system.md @@ -0,0 +1,16 @@ + + +# Filesystem API + +The `HfFileSystem` class provides a pythonic file interface to the Hugging Face Hub based on [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/). + +## HfFileSystem + +`HfFileSystem` is based on [fsspec](https://filesystem-spec.readthedocs.io/en/latest/), so it is compatible with most of the APIs that it offers. For more details, check out [our guide](../guides/hf_file_system) and fsspec's [API Reference](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem). + +[[autodoc]] HfFileSystem + - __init__ + - resolve_path + - ls diff --git a/docs/source/fr/package_reference/inference_client.md b/docs/source/fr/package_reference/inference_client.md new file mode 100644 index 0000000000..a4fa6b358d --- /dev/null +++ b/docs/source/fr/package_reference/inference_client.md @@ -0,0 +1,109 @@ + + +# Inference + +Inference is the process of using a trained model to make predictions on new data. As this process can be compute-intensive, +running on a dedicated server can be an interesting option. The `huggingface_hub` library provides an easy way to call a +service that runs inference for hosted models. There are several services you can connect to: +- [Inference API](https://huggingface.co/docs/api-inference/index): a service that allows you to run accelerated inference +on Hugging Face's infrastructure for free. This service is a fast way to get started, test different models, and +prototype AI products. +- [Inference Endpoints](https://huggingface.co/inference-endpoints): a product to easily deploy models to production. +Inference is run by Hugging Face in a dedicated, fully managed infrastructure on a cloud provider of your choice. + +These services can be called with the [`InferenceClient`] object. Please refer to [this guide](../guides/inference) +for more information on how to use it. + +## Inference Client + +[[autodoc]] InferenceClient + +## Async Inference Client + +An async version of the client is also provided, based on `asyncio` and `aiohttp`. +To use it, you can either install `aiohttp` directly or use the `[inference]` extra: + +```sh +pip install --upgrade huggingface_hub[inference] +# or +# pip install aiohttp +``` + +[[autodoc]] AsyncInferenceClient + +## InferenceTimeoutError + +[[autodoc]] InferenceTimeoutError + +## Return types + +For most tasks, the return value has a built-in type (string, list, image...). Here is a list for the more complex types. + +### ClassificationOutput + +[[autodoc]] huggingface_hub.inference._types.ClassificationOutput + +### ConversationalOutputConversation + +[[autodoc]] huggingface_hub.inference._types.ConversationalOutputConversation + +### ConversationalOutput + +[[autodoc]] huggingface_hub.inference._types.ConversationalOutput + +### ImageSegmentationOutput + +[[autodoc]] huggingface_hub.inference._types.ImageSegmentationOutput + +### ModelStatus + +[[autodoc]] huggingface_hub.inference._common.ModelStatus + +### TokenClassificationOutput + +[[autodoc]] huggingface_hub.inference._types.TokenClassificationOutput + +### Text generation types + +[`~InferenceClient.text_generation`] task has a greater support than other tasks in `InferenceClient`. In +particular, user inputs and server outputs are validated using [Pydantic](https://docs.pydantic.dev/latest/) +if this package is installed. Therefore, we recommend installing it (`pip install pydantic`) +for a better user experience. + +You can find below the dataclasses used to validate data and in particular [`~huggingface_hub.inference._text_generation.TextGenerationParameters`] (input), +[`~huggingface_hub.inference._text_generation.TextGenerationResponse`] (output) and +[`~huggingface_hub.inference._text_generation.TextGenerationStreamResponse`] (streaming output). + +[[autodoc]] huggingface_hub.inference._text_generation.TextGenerationParameters + +[[autodoc]] huggingface_hub.inference._text_generation.TextGenerationResponse + +[[autodoc]] huggingface_hub.inference._text_generation.TextGenerationStreamResponse + +[[autodoc]] huggingface_hub.inference._text_generation.InputToken + +[[autodoc]] huggingface_hub.inference._text_generation.Token + +[[autodoc]] huggingface_hub.inference._text_generation.FinishReason + +[[autodoc]] huggingface_hub.inference._text_generation.BestOfSequence + +[[autodoc]] huggingface_hub.inference._text_generation.Details + +[[autodoc]] huggingface_hub.inference._text_generation.StreamDetails + +## InferenceAPI + +[`InferenceAPI`] is the legacy way to call the Inference API. The interface is more simplistic and requires knowing +the input parameters and output format for each task. It also lacks the ability to connect to other services like +Inference Endpoints or AWS SageMaker. [`InferenceAPI`] will soon be deprecated so we recommend using [`InferenceClient`] +whenever possible. Check out [this guide](../guides/inference#legacy-inferenceapi-client) to learn how to switch from +[`InferenceAPI`] to [`InferenceClient`] in your scripts. + +[[autodoc]] InferenceApi + - __init__ + - __call__ + - all + diff --git a/docs/source/fr/package_reference/inference_endpoints.md b/docs/source/fr/package_reference/inference_endpoints.md new file mode 100644 index 0000000000..37521f8bb1 --- /dev/null +++ b/docs/source/fr/package_reference/inference_endpoints.md @@ -0,0 +1,42 @@ +# Inference Endpoints + +Inference Endpoints provides a secure production solution to easily deploy models on a dedicated and autoscaling infrastructure managed by Hugging Face. An Inference Endpoint is built from a model from the [Hub](https://huggingface.co/models). This page is a reference for `huggingface_hub`'s integration with Inference Endpoints. For more information about the Inference Endpoints product, check out its [official documentation](https://huggingface.co/docs/inference-endpoints/index). + + + +Check out the [related guide](../guides/inference_endpoints) to learn how to use `huggingface_hub` to manage your Inference Endpoints programmatically. + + + +Inference Endpoints can be fully managed via API. The endpoints are documented with [Swagger](https://api.endpoints.huggingface.cloud/). The [`InferenceEndpoint`] class is a simple wrapper built on top on this API. + +## Methods + +A subset of the Inference Endpoint features are implemented in [`HfApi`]: + +- [`get_inference_endpoint`] and [`list_inference_endpoints`] to get information about your Inference Endpoints +- [`create_inference_endpoint`], [`update_inference_endpoint`] and [`delete_inference_endpoint`] to deploy and manage Inference Endpoints +- [`pause_inference_endpoint`] and [`resume_inference_endpoint`] to pause and resume an Inference Endpoint +- [`scale_to_zero_inference_endpoint`] to manually scale an Endpoint to 0 replicas + +## InferenceEndpoint + +The main dataclass is [`InferenceEndpoint`]. It contains information about a deployed `InferenceEndpoint`, including its configuration and current state. Once deployed, you can run inference on the Endpoint using the [`InferenceEndpoint.client`] and [`InferenceEndpoint.async_client`] properties that respectively return an [`InferenceClient`] and an [`AsyncInferenceClient`] object. + +[[autodoc]] InferenceEndpoint + - from_raw + - client + - async_client + - all + +## InferenceEndpointStatus + +[[autodoc]] InferenceEndpointStatus + +## InferenceEndpointType + +[[autodoc]] InferenceEndpointType + +## InferenceEndpointError + +[[autodoc]] InferenceEndpointError \ No newline at end of file diff --git a/docs/source/fr/package_reference/login.md b/docs/source/fr/package_reference/login.md new file mode 100644 index 0000000000..c100e3999b --- /dev/null +++ b/docs/source/fr/package_reference/login.md @@ -0,0 +1,24 @@ + + +# Login and logout + +The `huggingface_hub` library allows users to programmatically login and logout the +machine to the Hub. + +## login + +[[autodoc]] login + +## interpreter_login + +[[autodoc]] interpreter_login + +## notebook_login + +[[autodoc]] notebook_login + +## logout + +[[autodoc]] logout diff --git a/docs/source/fr/package_reference/mixins.md b/docs/source/fr/package_reference/mixins.md new file mode 100644 index 0000000000..41480dfa80 --- /dev/null +++ b/docs/source/fr/package_reference/mixins.md @@ -0,0 +1,41 @@ + + +# Mixins & serialization methods + +## Mixins + +The `huggingface_hub` library offers a range of mixins that can be used as a parent class for your objects, in order to +provide simple uploading and downloading functions. Check out our [integration guide](../guides/integrations) to learn +how to integrate any ML framework with the Hub. + +### Generic + +[[autodoc]] ModelHubMixin + - all + - _save_pretrained + - _from_pretrained + +### PyTorch + +[[autodoc]] PyTorchModelHubMixin + +### Keras + +[[autodoc]] KerasModelHubMixin + +[[autodoc]] from_pretrained_keras + +[[autodoc]] push_to_hub_keras + +[[autodoc]] save_pretrained_keras + +### Fastai + +[[autodoc]] from_pretrained_fastai + +[[autodoc]] push_to_hub_fastai + + + diff --git a/docs/source/fr/package_reference/overview.md b/docs/source/fr/package_reference/overview.md new file mode 100644 index 0000000000..f024f25692 --- /dev/null +++ b/docs/source/fr/package_reference/overview.md @@ -0,0 +1,7 @@ + + +# Overview + +This section contains an exhaustive and technical description of `huggingface_hub` classes and methods. \ No newline at end of file diff --git a/docs/source/fr/package_reference/repository.md b/docs/source/fr/package_reference/repository.md new file mode 100644 index 0000000000..9964f94859 --- /dev/null +++ b/docs/source/fr/package_reference/repository.md @@ -0,0 +1,51 @@ + + +# Managing local and online repositories + +The `Repository` class is a helper class that wraps `git` and `git-lfs` commands. It provides tooling adapted +for managing repositories which can be very large. + +It is the recommended tool as soon as any `git` operation is involved, or when collaboration will be a point +of focus with the repository itself. + +## The Repository class + +[[autodoc]] Repository + - __init__ + - current_branch + - all + +## Helper methods + +[[autodoc]] huggingface_hub.repository.is_git_repo + +[[autodoc]] huggingface_hub.repository.is_local_clone + +[[autodoc]] huggingface_hub.repository.is_tracked_with_lfs + +[[autodoc]] huggingface_hub.repository.is_git_ignored + +[[autodoc]] huggingface_hub.repository.files_to_be_staged + +[[autodoc]] huggingface_hub.repository.is_tracked_upstream + +[[autodoc]] huggingface_hub.repository.commits_to_push + +## Following asynchronous commands + +The `Repository` utility offers several methods which can be launched asynchronously: +- `git_push` +- `git_pull` +- `push_to_hub` +- The `commit` context manager + +See below for utilities to manage such asynchronous methods. + +[[autodoc]] Repository + - commands_failed + - commands_in_progress + - wait_for_commands + +[[autodoc]] huggingface_hub.repository.CommandInProgress \ No newline at end of file diff --git a/docs/source/fr/package_reference/space_runtime.md b/docs/source/fr/package_reference/space_runtime.md new file mode 100644 index 0000000000..277bff8e7c --- /dev/null +++ b/docs/source/fr/package_reference/space_runtime.md @@ -0,0 +1,37 @@ + + +# Managing your Space runtime + +Check the [`HfApi`] documentation page for the reference of methods to manage your Space on the Hub. + +- Duplicate a Space: [`duplicate_space`] +- Fetch current runtime: [`get_space_runtime`] +- Manage secrets: [`add_space_secret`] and [`delete_space_secret`] +- Manage hardware: [`request_space_hardware`] +- Manage state: [`pause_space`], [`restart_space`], [`set_space_sleep_time`] + +## Data structures + +### SpaceRuntime + +[[autodoc]] SpaceRuntime + +### SpaceHardware + +[[autodoc]] SpaceHardware + +### SpaceStage + +[[autodoc]] SpaceStage + +### SpaceStorage + +[[autodoc]] SpaceStorage + +### SpaceVariable + +[[autodoc]] SpaceVariable + + diff --git a/docs/source/fr/package_reference/tensorboard.md b/docs/source/fr/package_reference/tensorboard.md new file mode 100644 index 0000000000..560f03a19f --- /dev/null +++ b/docs/source/fr/package_reference/tensorboard.md @@ -0,0 +1,19 @@ + + +# TensorBoard logger + +TensorBoard is a visualization toolkit for machine learning experimentation. TensorBoard allows tracking and visualizing +metrics such as loss and accuracy, visualizing the model graph, viewing histograms, displaying images and much more. +TensorBoard is well integrated with the Hugging Face Hub. The Hub automatically detects TensorBoard traces (such as +`tfevents`) when pushed to the Hub which starts an instance to visualize them. To get more information about TensorBoard +integration on the Hub, check out [this guide](https://huggingface.co/docs/hub/tensorboard). + +To benefit from this integration, `huggingface_hub` provides a custom logger to push logs to the Hub. It works as a +drop-in replacement for [SummaryWriter](https://tensorboardx.readthedocs.io/en/latest/tensorboard.html) with no extra +code needed. Traces are still saved locally and a background job push them to the Hub at regular interval. + +## HFSummaryWriter + +[[autodoc]] HFSummaryWriter \ No newline at end of file diff --git a/docs/source/fr/package_reference/utilities.md b/docs/source/fr/package_reference/utilities.md new file mode 100644 index 0000000000..93e73e6c7e --- /dev/null +++ b/docs/source/fr/package_reference/utilities.md @@ -0,0 +1,260 @@ + + +# Utilities + +## Configure logging + +The `huggingface_hub` package exposes a `logging` utility to control the logging level of the package itself. +You can import it as such: + +```py +from huggingface_hub import logging +``` + +Then, you may define the verbosity in order to update the amount of logs you'll see: + +```python +from huggingface_hub import logging + +logging.set_verbosity_error() +logging.set_verbosity_warning() +logging.set_verbosity_info() +logging.set_verbosity_debug() + +logging.set_verbosity(...) +``` + +The levels should be understood as follows: + +- `error`: only show critical logs about usage which may result in an error or unexpected behavior. +- `warning`: show logs that aren't critical but usage may result in unintended behavior. + Additionally, important informative logs may be shown. +- `info`: show most logs, including some verbose logging regarding what is happening under the hood. + If something is behaving in an unexpected manner, we recommend switching the verbosity level to this in order + to get more information. +- `debug`: show all logs, including some internal logs which may be used to track exactly what's happening + under the hood. + +[[autodoc]] logging.get_verbosity +[[autodoc]] logging.set_verbosity +[[autodoc]] logging.set_verbosity_info +[[autodoc]] logging.set_verbosity_debug +[[autodoc]] logging.set_verbosity_warning +[[autodoc]] logging.set_verbosity_error +[[autodoc]] logging.disable_propagation +[[autodoc]] logging.enable_propagation + +### Repo-specific helper methods + +The methods exposed below are relevant when modifying modules from the `huggingface_hub` library itself. +Using these shouldn't be necessary if you use `huggingface_hub` and you don't modify them. + +[[autodoc]] logging.get_logger + +## Configure progress bars + +Progress bars are a useful tool to display information to the user while a long-running task is being executed (e.g. +when downloading or uploading files). `huggingface_hub` exposes a [`~utils.tqdm`] wrapper to display progress bars in a +consistent way across the library. + +By default, progress bars are enabled. You can disable them globally by setting `HF_HUB_DISABLE_PROGRESS_BARS` +environment variable. You can also enable/disable them using [`~utils.enable_progress_bars`] and +[`~utils.disable_progress_bars`]. If set, the environment variable has priority on the helpers. + + +```py +>>> from huggingface_hub import snapshot_download +>>> from huggingface_hub.utils import are_progress_bars_disabled, disable_progress_bars, enable_progress_bars + +>>> # Disable progress bars globally +>>> disable_progress_bars() + +>>> # Progress bar will not be shown ! +>>> snapshot_download("gpt2") + +>>> are_progress_bars_disabled() +True + +>>> # Re-enable progress bars globally +>>> enable_progress_bars() +``` + +### are_progress_bars_disabled + +[[autodoc]] huggingface_hub.utils.are_progress_bars_disabled + +### disable_progress_bars + +[[autodoc]] huggingface_hub.utils.disable_progress_bars + +### enable_progress_bars + +[[autodoc]] huggingface_hub.utils.enable_progress_bars + +## Configure HTTP backend + +In some environments, you might want to configure how HTTP calls are made, for example if you are using a proxy. +`huggingface_hub` let you configure this globally using [`configure_http_backend`]. All requests made to the Hub will +then use your settings. Under the hood, `huggingface_hub` uses `requests.Session` so you might want to refer to the +[`requests` documentation](https://requests.readthedocs.io/en/latest/user/advanced) to learn more about the available +parameters. + +Since `requests.Session` is not guaranteed to be thread-safe, `huggingface_hub` creates one session instance per thread. +Using sessions allows us to keep the connection open between HTTP calls and ultimately save time. If you are +integrating `huggingface_hub` in a third-party library and wants to make a custom call to the Hub, use [`get_session`] +to get a Session configured by your users (i.e. replace any `requests.get(...)` call by `get_session().get(...)`). + +[[autodoc]] configure_http_backend + +[[autodoc]] get_session + + +## Handle HTTP errors + +`huggingface_hub` defines its own HTTP errors to refine the `HTTPError` raised by +`requests` with additional information sent back by the server. + +### Raise for status + +[`~utils.hf_raise_for_status`] is meant to be the central method to "raise for status" from any +request made to the Hub. It wraps the base `requests.raise_for_status` to provide +additional information. Any `HTTPError` thrown is converted into a `HfHubHTTPError`. + +```py +import requests +from huggingface_hub.utils import hf_raise_for_status, HfHubHTTPError + +response = requests.post(...) +try: + hf_raise_for_status(response) +except HfHubHTTPError as e: + print(str(e)) # formatted message + e.request_id, e.server_message # details returned by server + + # Complete the error message with additional information once it's raised + e.append_to_message("\n`create_commit` expects the repository to exist.") + raise +``` + +[[autodoc]] huggingface_hub.utils.hf_raise_for_status + +### HTTP errors + +Here is a list of HTTP errors thrown in `huggingface_hub`. + +#### HfHubHTTPError + +`HfHubHTTPError` is the parent class for any HF Hub HTTP error. It takes care of parsing +the server response and format the error message to provide as much information to the +user as possible. + +[[autodoc]] huggingface_hub.utils.HfHubHTTPError + +#### RepositoryNotFoundError + +[[autodoc]] huggingface_hub.utils.RepositoryNotFoundError + +#### GatedRepoError + +[[autodoc]] huggingface_hub.utils.GatedRepoError + +#### RevisionNotFoundError + +[[autodoc]] huggingface_hub.utils.RevisionNotFoundError + +#### EntryNotFoundError + +[[autodoc]] huggingface_hub.utils.EntryNotFoundError + +#### BadRequestError + +[[autodoc]] huggingface_hub.utils.BadRequestError + +#### LocalEntryNotFoundError + +[[autodoc]] huggingface_hub.utils.LocalEntryNotFoundError + +## Telemetry + +`huggingface_hub` includes an helper to send telemetry data. This information helps us debug issues and prioritize new features. +Users can disable telemetry collection at any time by setting the `HF_HUB_DISABLE_TELEMETRY=1` environment variable. +Telemetry is also disabled in offline mode (i.e. when setting HF_HUB_OFFLINE=1). + +If you are maintainer of a third-party library, sending telemetry data is as simple as making a call to [`send_telemetry`]. +Data is sent in a separate thread to reduce as much as possible the impact for users. + +[[autodoc]] utils.send_telemetry + + +## Validators + +`huggingface_hub` includes custom validators to validate method arguments automatically. +Validation is inspired by the work done in [Pydantic](https://pydantic-docs.helpmanual.io/) +to validate type hints but with more limited features. + +### Generic decorator + +[`~utils.validate_hf_hub_args`] is a generic decorator to encapsulate +methods that have arguments following `huggingface_hub`'s naming. By default, all +arguments that has a validator implemented will be validated. + +If an input is not valid, a [`~utils.HFValidationError`] is thrown. Only +the first non-valid value throws an error and stops the validation process. + +Usage: + +```py +>>> from huggingface_hub.utils import validate_hf_hub_args + +>>> @validate_hf_hub_args +... def my_cool_method(repo_id: str): +... print(repo_id) + +>>> my_cool_method(repo_id="valid_repo_id") +valid_repo_id + +>>> my_cool_method("other..repo..id") +huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'. + +>>> my_cool_method(repo_id="other..repo..id") +huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'. + +>>> @validate_hf_hub_args +... def my_cool_auth_method(token: str): +... print(token) + +>>> my_cool_auth_method(token="a token") +"a token" + +>>> my_cool_auth_method(use_auth_token="a use_auth_token") +"a use_auth_token" + +>>> my_cool_auth_method(token="a token", use_auth_token="a use_auth_token") +UserWarning: Both `token` and `use_auth_token` are passed (...). `use_auth_token` value will be ignored. +"a token" +``` + +#### validate_hf_hub_args + +[[autodoc]] utils.validate_hf_hub_args + +#### HFValidationError + +[[autodoc]] utils.HFValidationError + +### Argument validators + +Validators can also be used individually. Here is a list of all arguments that can be +validated. + +#### repo_id + +[[autodoc]] utils.validate_repo_id + +#### smoothly_deprecate_use_auth_token + +Not exactly a validator, but ran as well. + +[[autodoc]] utils.smoothly_deprecate_use_auth_token diff --git a/docs/source/fr/package_reference/webhooks_server.md b/docs/source/fr/package_reference/webhooks_server.md new file mode 100644 index 0000000000..3d6847a3e0 --- /dev/null +++ b/docs/source/fr/package_reference/webhooks_server.md @@ -0,0 +1,84 @@ + + +# Webhooks Server + +Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on specific repos or to +all repos belonging to particular users/organizations you're interested in following. To learn +more about webhooks on the Huggingface Hub, you can read the Webhooks [guide](https://huggingface.co/docs/hub/webhooks). + + + +Check out this [guide](../guides/webhooks_server) for a step-by-step tutorial on how to setup your webhooks server and +deploy it as a Space. + + + + + +This is an experimental feature. This means that we are still working on improving the API. Breaking changes might be +introduced in the future without prior notice. Make sure to pin the version of `huggingface_hub` in your requirements. +A warning is triggered when you use an experimental feature. You can disable it by setting `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` as an environment variable. + + + +## Server + +The server is a [Gradio](https://gradio.app/) app. It has a UI to display instructions for you or your users and an API +to listen to webhooks. Implementing a webhook endpoint is as simple as decorating a function. You can then debug it +by redirecting the Webhooks to your machine (using a Gradio tunnel) before deploying it to a Space. + +### WebhooksServer + +[[autodoc]] huggingface_hub.WebhooksServer + +### @webhook_endpoint + +[[autodoc]] huggingface_hub.webhook_endpoint + +## Payload + +[`WebhookPayload`] is the main data structure that contains the payload from Webhooks. This is +a `pydantic` class which makes it very easy to use with FastAPI. If you pass it as a parameter to a webhook endpoint, it +will be automatically validated and parsed as a Python object. + +For more information about webhooks payload, you can refer to the Webhooks Payload [guide](https://huggingface.co/docs/hub/webhooks#webhook-payloads). + +[[autodoc]] huggingface_hub.WebhookPayload + +### WebhookPayload + +[[autodoc]] huggingface_hub.WebhookPayload + +### WebhookPayloadComment + +[[autodoc]] huggingface_hub.WebhookPayloadComment + +### WebhookPayloadDiscussion + +[[autodoc]] huggingface_hub.WebhookPayloadDiscussion + +### WebhookPayloadDiscussionChanges + +[[autodoc]] huggingface_hub.WebhookPayloadDiscussionChanges + +### WebhookPayloadEvent + +[[autodoc]] huggingface_hub.WebhookPayloadEvent + +### WebhookPayloadMovedTo + +[[autodoc]] huggingface_hub.WebhookPayloadMovedTo + +### WebhookPayloadRepo + +[[autodoc]] huggingface_hub.WebhookPayloadRepo + +### WebhookPayloadUrl + +[[autodoc]] huggingface_hub.WebhookPayloadUrl + +### WebhookPayloadWebhook + +[[autodoc]] huggingface_hub.WebhookPayloadWebhook diff --git a/docs/source/fr/quick-start.md b/docs/source/fr/quick-start.md new file mode 100644 index 0000000000..8d6e52b889 --- /dev/null +++ b/docs/source/fr/quick-start.md @@ -0,0 +1,157 @@ + + +# Quickstart + +The [Hugging Face Hub](https://huggingface.co/) is the go-to place for sharing machine learning +models, demos, datasets, and metrics. `huggingface_hub` library helps you interact with +the Hub without leaving your development environment. You can create and manage +repositories easily, download and upload files, and get useful model and dataset +metadata from the Hub. + +## Installation + +To get started, install the `huggingface_hub` library: + +```bash +pip install --upgrade huggingface_hub +``` + +For more details, check out the [installation](installation) guide. + +## Download files + +Repositories on the Hub are git version controlled, and users can download a single file +or the whole repository. You can use the [`hf_hub_download`] function to download files. +This function will download and cache a file on your local disk. The next time you need +that file, it will load from your cache, so you don't need to re-download it. + +You will need the repository id and the filename of the file you want to download. For +example, to download the [Pegasus](https://huggingface.co/google/pegasus-xsum) model +configuration file: + +```py +>>> from huggingface_hub import hf_hub_download +>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") +``` + +To download a specific version of the file, use the `revision` parameter to specify the +branch name, tag, or commit hash. If you choose to use the commit hash, it must be the +full-length hash instead of the shorter 7-character commit hash: + +```py +>>> from huggingface_hub import hf_hub_download +>>> hf_hub_download( +... repo_id="google/pegasus-xsum", +... filename="config.json", +... revision="4d33b01d79672f27f001f6abade33f22d993b151" +... ) +``` + +For more details and options, see the API reference for [`hf_hub_download`]. + +## Login + +In a lot of cases, you must be logged in with a Hugging Face account to interact with +the Hub: download private repos, upload files, create PRs,... +[Create an account](https://huggingface.co/join) if you don't already have one, and then sign in +to get your [User Access Token](https://huggingface.co/docs/hub/security-tokens) from +your [Settings page](https://huggingface.co/settings/tokens). The User Access Token is +used to authenticate your identity to the Hub. + +Once you have your User Access Token, run the following command in your terminal: + +```bash +huggingface-cli login +# or using an environment variable +huggingface-cli login --token $HUGGINGFACE_TOKEN +``` + +Alternatively, you can programmatically login using [`login`] in a notebook or a script: + +```py +>>> from huggingface_hub import login +>>> login() +``` + +It is also possible to login programmatically without being prompted to enter your token by directly +passing the token to [`login`] like `login(token="hf_xxx")`. If you do so, be careful when +sharing your source code. It is a best practice to load the token from a secure vault instead +of saving it explicitly in your codebase/notebook. + +You can be logged in only to 1 account at a time. If you login your machine to a new account, you will get logged out +from the previous. Make sure to always which account you are using with the command `huggingface-cli whoami`. +If you want to handle several accounts in the same script, you can provide your token when calling each method. This +is also useful if you don't want to store any token on your machine. + + + +Once you are logged in, all requests to the Hub -even methods that don't necessarily require authentication- will use your +access token by default. If you want to disable implicit use of your token, you should set the +`HF_HUB_DISABLE_IMPLICIT_TOKEN` environment variable. + + + +## Create a repository + +Once you've registered and logged in, create a repository with the [`create_repo`] +function: + +```py +>>> from huggingface_hub import HfApi +>>> api = HfApi() +>>> api.create_repo(repo_id="super-cool-model") +``` + +If you want your repository to be private, then: + +```py +>>> from huggingface_hub import HfApi +>>> api = HfApi() +>>> api.create_repo(repo_id="super-cool-model", private=True) +``` + +Private repositories will not be visible to anyone except yourself. + + + +To create a repository or to push content to the Hub, you must provide a User Access +Token that has the `write` permission. You can choose the permission when creating the +token in your [Settings page](https://huggingface.co/settings/tokens). + + + +## Upload files + +Use the [`upload_file`] function to add a file to your newly created repository. You +need to specify: + +1. The path of the file to upload. +2. The path of the file in the repository. +3. The repository id of where you want to add the file. + +```py +>>> from huggingface_hub import HfApi +>>> api = HfApi() +>>> api.upload_file( +... path_or_fileobj="/home/lysandre/dummy-test/README.md", +... path_in_repo="README.md", +... repo_id="lysandre/test-model", +... ) +``` + +To upload more than one file at a time, take a look at the [Upload](./guides/upload) guide +which will introduce you to several methods for uploading files (with or without git). + +## Next steps + +The `huggingface_hub` library provides an easy way for users to interact with the Hub +with Python. To learn more about how you can manage your files and repositories on the +Hub, we recommend reading our [how-to guides](./guides/overview) to: + +- [Manage your repository](./guides/repository). +- [Download](./guides/download) files from the Hub. +- [Upload](./guides/upload) files to the Hub. +- [Search the Hub](./guides/search) for your desired model or dataset. +- [Access the Inference API](./guides/inference) for fast inference. \ No newline at end of file From 7d596f8eec738b50ce56cbdc527b872fe495a160 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sun, 10 Dec 2023 19:16:09 +0100 Subject: [PATCH 002/129] Translated the cli guide --- docs/source/fr/guides/cli.md | 216 ++++++++++++++++++++--------------- 1 file changed, 122 insertions(+), 94 deletions(-) diff --git a/docs/source/fr/guides/cli.md b/docs/source/fr/guides/cli.md index e943660119..771ea2f4cc 100644 --- a/docs/source/fr/guides/cli.md +++ b/docs/source/fr/guides/cli.md @@ -2,13 +2,17 @@ rendered properly in your Markdown viewer. --> -# Command Line Interface (CLI) +# Invite de commande (CLI) -The `huggingface_hub` Python package comes with a built-in CLI called `huggingface-cli`. This tool allows you to interact with the Hugging Face Hub directly from a terminal. For example, you can login to your account, create a repository, upload and download files, etc. It also comes with handy features to configure your machine or manage your cache. In this guide, we will have a look at the main features of the CLI and how to use them. +Le module Python `huggingface_hub` offre un CLI intégré appelé `huggingface-cli`. Cet outil vous permet d'intéragir directement avec le Hub Hugging +Face directement depuis un terminal. Par exemple, vous pouvez vous connecter à votre compte, créer un dépot, upload et 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. -## Getting started -First of all, let's install the CLI: +## Installation + +Tout d'abord, installons le CLI: ``` >>> pip install -U "huggingface_hub[cli]" @@ -16,11 +20,12 @@ First of all, let's install the CLI: -In the snippet above, we also installed the `[cli]` extra dependencies to make the user experience better, especially when using the `delete-cache` command. +Dans les snippet ci dessus, nous avons aussi installé les dépendances `[cli]` pour rendre l'expérience utilisateur meilleur, en particulier lors de +l'utilisation de la commande `delete-cache`. -Once installed, you can check that the CLI is correctly setup: +Une fois cette première étape terminée, vous pouvez vérifier que le CLI est correctement installé : ``` >>> huggingface-cli --help @@ -45,25 +50,32 @@ options: -h, --help show this help message and exit ``` -If the CLI is correctly installed, you should see a list of all the options available in the CLI. If you get an error message such as `command not found: huggingface-cli`, please refer to the [Installation](../installation) guide. +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) -The `--help` option is very convenient for getting more details about a command. You can use it anytime to list all available options and their details. For example, `huggingface-cli upload --help` provides more information on how to upload files using the CLI. +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 pour upload des fichiers en utilisant le +CLI. -## huggingface-cli login +## Connexion à huggingface-cli -In many cases, you must be logged in to a Hugging Face account to interact with the Hub (download private repos, upload files, create PRs, etc.). To do so, you need a [User Access Token](https://huggingface.co/docs/hub/security-tokens) from your [Settings page](https://huggingface.co/settings/tokens). The User Access Token is used to authenticate your identity to the Hub. Make sure to set a token with write access if you want to upload or modify content. +Dans la plupart des cas, vous devez être connectés à un compte Hugging Face pour intéragir avec le Hub (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) 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. -Once you have your token, run the following command in your terminal: +Une fois que vous avez votre token d'authentification, lancez la commande suivante dans votre terminal : ```bash >>> huggingface-cli login ``` -This command will prompt you for a token. Copy-paste yours and press *Enter*. Then you'll be asked if the token should also be saved as a git credential. Press *Enter* again (default to yes) if you plan to use `git` locally. Finally, it will call the Hub to check that your token is valid and save it locally. +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. ``` _| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_| @@ -81,10 +93,12 @@ Your token has been saved to /home/wauplin/.cache/huggingface/token Login successful ``` -Alternatively, if you want to log-in without being prompted, you can pass the token directly from the command line. To be more secure, we recommend passing your token as an environment variable to avoid pasting it in your command history. +Alternativement, si vous souhaitez vous connecter sans que le CLI vous demande quoi que ce soit, vous pouvez mettre votre token directement depuis +l'invite de commande. Pour que le processus soit plus sécurisé, nous vous recommandons de mettre votre token en tant que variable d'environnement +pour éviter de le laisser dans l'historique de votre invite de commande. ```bash -# Or using an environment variable +# 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). @@ -94,7 +108,7 @@ Login successful ## huggingface-cli whoami -If you want to know if you are logged in, you can use `huggingface-cli whoami`. This command doesn't have any options and simply prints your username and the organizations you are a part of on the Hub: +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 @@ -102,26 +116,28 @@ Wauplin orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster ``` -If you are not logged in, an error message will be printed. +Si vous n'êtes pas connecté, un message d'erreur sera renvoyé. ## huggingface-cli logout -This commands logs you out. In practice, it will delete the token saved on your machine. +Cette commande vous déconecte. En pratique, elle supprime le token enregistré sur votre machine. -This command will not log you out if you are logged in using the `HF_TOKEN` environment variable (see [reference](../package_reference/environment_variables#hftoken)). If that is the case, you must unset the environment variable in your machine configuration. +Cette commande ne vous déconnectera pas si vous vous êtes connecté en utilisant la variable d'environnement `HF_TOKEN` (voir [reference](../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 - -Use the `huggingface-cli download` command to download files from the Hub directly. Internally, it uses the same [`hf_hub_download`] and [`snapshot_download`] helpers described in the [Download](./download) guide and prints the returned path to the terminal. In the examples below, we will walk through the most common use cases. For a full list of available options, you can run: +Utilisez la commande `huggingface-cli download` pour télécharger des fichiers directement depuis le Hub. En interne, cette commande utilise +les mêmes helpers [`hf_hub_download`] et [`snapshot_download`] Décrit dans le guide [Téléchargement](./download) et affiche le chemin +retourné 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 ``` -### Download a single file +### Télécharger un fichier -To download a single file from a repo, simply provide the repo_id and filename as follow: +Pour télécharger un unique fichier d'un dépôt, mettez simplement le repo_id et le nom du fichier ainsi : ```bash >>> huggingface-cli download gpt2 config.json @@ -130,11 +146,11 @@ downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/waupli /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` -The command will always print on the last line the path to the file on your local machine. +La commande affichera toujours sur la dernière ligne le chemin vers le fichier sur votre machine locale. -### Download an entire repository +### Télécharger un dépôt entier -In some cases, you just want to download all the files from a repository. This can be done by just specifying the repo id: +Dans le cas où vous voudriez télécharger tous les fichier d'un dépôt, vous pouvez ne spécifier que l'id du dépôt: ```bash >>> huggingface-cli download HuggingFaceH4/zephyr-7b-beta @@ -144,9 +160,10 @@ Fetching 23 files: 0%| | 0/23 [ /home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720 ``` -### Download multiple files +### Télécharger plusieurs fichiers -You can also download a subset of the files from a repository with a single command. This can be done in two ways. If you already have a precise list of the files you want to download, you can simply provide them sequentially: +Vous pouvez aussi télécharger un sous ensemble des fichiers d'un dépôts en une seule commande. Vous pouvez faire ceci de deux manières. Si vous avez +déjà une liste précise des fichiers à télécharger, vous pouvez simplement les mettre un par un: ```bash >>> huggingface-cli download gpt2 config.json model.safetensors @@ -157,7 +174,8 @@ Fetching 2 files: 100%|███████████████████ /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` -The other approach is to provide patterns to filter which files you want to download using `--include` and `--exclude`. For example, if you want to download all safetensors files from [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0), except the files in FP16 precision: +L'autre approche est de fournir des modèles en filtrant les fichiers que vous voulez télécharger en utilisant `--include` et `--exclude`. +Par exemple, si vous voulez télécharger tous les fichiers safetensors depuis [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) à l'exception des fichiers en précision P16: ```bash >>> huggingface-cli download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"* @@ -168,9 +186,10 @@ Fetching 8 files: 100%|███████████████████ /home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7b ``` -### Download a dataset or a Space +### Télécharger un dataset où un espace -The examples above show how to download from a model repository. To download a dataset or a Space, use the `--repo-type` option: +Les exemples ci-dessus montrent comment télécharger des fichiers depuis un dépôt. Pour télécharger un dataset ou un espace, utilisez +l'option `--repo-type`: ```bash # https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k @@ -182,22 +201,25 @@ The examples above show how to download from a model repository. To download a d ... ``` -### Download a specific revision +### Télécgarger une version spécifique -The examples above show how to download from the latest commit on the main branch. To download from a specific revision (commit hash, branch name or tag), use the `--revision` option: +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 ... ``` -### Download to a local folder +### Télécharger vers un dossier local -The recommended (and default) way to download files from the Hub is to use the cache-system. However, in some cases you want to download files and move them to a specific folder. This is useful to get a workflow closer to what git commands offer. You can do that using the `--local_dir` option. +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 les déplacer dans un dossier spécifique. C'est utile pour avoir un fonctionnement similaire à celui de git. Vous pouvez faire ceci en utilisant l'option `--local_dir`. -Downloading to a local directory comes with some downsides. Please check out the limitations in the [Download](./download#download-files-to-local-folder) guide before using `--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`. @@ -207,9 +229,9 @@ Downloading to a local directory comes with some downsides. Please check out the ./model-00001-of-00002.safetensors ``` -### Specify cache directory +### Spécifier le chemin du cache -By default, all files will be download to the cache directory defined by the `HF_HOME` [environment variable](../package_reference/environment_variables#hfhome). You can also specify a custom cache using `--cache-dir`: +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 @@ -217,18 +239,20 @@ By default, all files will be download to the cache directory defined by the `HF ./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745 ``` -### Specify a token +### Préciser un token -To access private or gated repositories, you must use a token. By default, the token saved locally (using `huggingface-cli login`) will be used. If you want to authenticate explicitly, use the `--token` option: +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 ``` -### Quiet mode +### Mode silencieux -By default, the `huggingface-cli download` command will be verbose. It will print details such as warning messages, information about the downloaded files, and progress bars. If you want to silence all of this, use the `--quiet` option. Only the last line (i.e. the path to the downloaded files) is printed. This can prove useful if you want to pass the output to another command in a script. +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 @@ -237,154 +261,158 @@ By default, the `huggingface-cli download` command will be verbose. It will prin ## huggingface-cli upload -Use the `huggingface-cli upload` command to upload files to the Hub directly. Internally, it uses the same [`upload_file`] and [`upload_folder`] helpers described in the [Upload](./upload) guide. In the examples below, we will walk through the most common use cases. For a full list of available options, you can run: +Utilisez la commande `huggingface-cli upload` pour uploader des fichiers directement dans le Hub. En interne, 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 an entire folder +### Upload un fichier -The default usage for this command is: +L'utilisation par défaut de cette commande est: ```bash # Usage: huggingface-cli upload [repo_id] [local_path] [path_in_repo] ``` -To upload the current directory at the root of the repo, use: +Pour upload le chemin courant dans la racine du dépôts, utilisez: ```bash ->>> huggingface-cli upload my-cool-model . . +>>> huggingface-cli upload mon-super-modele . . https://huggingface.co/Wauplin/my-cool-model/tree/main/ ``` -If the repo doesn't exist yet, it will be created automatically. +Si le dépôt n'existe pas encore, il sera créé automatiquement. -You can also upload a specific folder: +Vous pouvez aussi upload un dossier spécifique: ```bash ->>> huggingface-cli upload my-cool-model ./models . +>>> huggingface-cli upload mon-super-modele ./models . https://huggingface.co/Wauplin/my-cool-model/tree/main/ ``` - -Finally, you can upload a folder to a specific destination on the repo: +Enfin, vous pouvez upload un dossier dans une destination spécifique dans le dépot: ```bash ->>> huggingface-cli upload my-cool-model ./path/to/curated/data /data/train +>>> huggingface-cli upload mon-super-modele ./path/to/curated/data /data/train https://huggingface.co/Wauplin/my-cool-model/tree/main/data/train ``` -### Upload a single file +### Upload un seul fichier -You can also upload a single file by setting `local_path` to point to a file on your machine. If that's the case, `path_in_repo` is optional and will default to the name of your local file: +Vous pouvez aussi upload un seul fichier en définissant `loca_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/my-cool-model ./models/model.safetensors -https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors +>>> huggingface-cli upload Wauplin/mon-super-modele ./models/model.safetensors +https://huggingface.co/Wauplin/mon-super-modele/blob/main/model.safetensors ``` -If you want to upload a single file to a specific directory, set `path_in_repo` accordingly: +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/my-cool-model ./models/model.safetensors /vae/model.safetensors -https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensors +>>> 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 multiple files +### Upload plusieurs fichiers -To upload multiple files from a folder at once without uploading the entire folder, use the `--include` and `--exclude` patterns. It can also be combined with the `--delete` option to delete files on the repo while uploading new ones. In the example below, we sync the local Space by deleting remote files and uploading all files except the ones in `/logs`: +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 l'espace local en supprimant les fichiers distant et en uploadant tous les fichiers sauf ceux dans `/logs`: ```bash # Sync local Space with Hub (upload new files except from logs/, delete removed files) ->>> huggingface-cli upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub" +>>> huggingface-cli upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Synchronisation de l'espace local avec le Hub" ... ``` -### Upload to a dataset or Space +### Upload vers un dataset ou un espace -To upload to a dataset or a Space, use the `--repo-type` option: +Pour upload vers un dataset ou un espace, utilisez l'option `--repo-type`: ```bash ->>> huggingface-cli upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset +>>> huggingface-cli upload Wauplin/mon-super-dataset ./data /train --repo-type=dataset ... ``` -### Upload to an organization +### Upload vers une organisation -To upload content to a repo owned by an organization instead of a personal repo, you must explicitly specify it in the `repo_id`: +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 MyCoolOrganization/my-cool-model . . -https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/ +>>> huggingface-cli upload MonOrganisation/mon-super-modele . . +https://huggingface.co/MonOrganisation/mon-super-modele/tree/main/ ``` -### Upload to a specific revision +### Upload vers une version spécifique -By default, files are uploaded to the `main` branch. If you want to upload files to another branch or reference, use the `--revision` option: +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 files to a PR +# Upload des fichiers vers une pull request >>> huggingface-cli upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104 ... ``` -**Note:** if `revision` does not exist and `--create-pr` is not set, a branch will be created automatically from the `main` branch. +**Note:** Si `revision` n'existe pas et que `--create-pr` n'est pas utilisé, une branche sera créé automatiquement à partir de la branche `main`. -### Upload and create a PR +### Upload et créer une pull request -If you don't have the permission to push to a repo, you must open a PR and let the authors know about the changes you want to make. This can be done by setting the `--create-pr` option: +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 -# Create a PR and upload the files to it +# 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 at regular intervals +### Upload a des intervalles réguliers -In some cases, you might want to push regular updates to a repo. For example, this is useful if you're training a model and you want to upload the logs folder every 10 minutes. You can do this using the `--every` option: +Dans certains cas, vous aurez peut-être besoin de push des mise à jour régulières vers un dépôt. Par exemple, ça peut-être utile 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 new logs every 10 minutes +# Upload de nouveaux logs toutes les dix minutes huggingface-cli upload training-model logs/ --every=10 ``` -### Specify a commit message +### Mettre un message de commit -Use the `--commit-message` and `--commit-description` to set a custom message and description for your commit instead of the default one +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/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details." +>>> 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/my-cool-model/tree/main +https://huggingface.co/Wauplin/mon-super-modele/tree/main ``` -### Specify a token +### Préciser un token -To upload files, you must use a token. By default, the token saved locally (using `huggingface-cli login`) will be used. If you want to authenticate explicitly, use the `--token` option: +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/my-cool-model ./models . --token=hf_**** +>>> huggingface-cli upload Wauplin/mon-super-modele ./models . --token=hf_**** ... -https://huggingface.co/Wauplin/my-cool-model/tree/main +https://huggingface.co/Wauplin/mon-super-modele/tree/main ``` -### Quiet mode +### Mode silencieux -By default, the `huggingface-cli upload` command will be verbose. It will print details such as warning messages, information about the uploaded files, and progress bars. If you want to silence all of this, use the `--quiet` option. Only the last line (i.e. the URL to the uploaded files) is printed. This can prove useful if you want to pass the output to another command in a script. +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é. Ceci peut-être utile si vous voulez utiliser l'output d'une autre commande dans un script. ```bash ->>> huggingface-cli upload Wauplin/my-cool-model ./models . --quiet -https://huggingface.co/Wauplin/my-cool-model/tree/main +>>> huggingface-cli upload Wauplin/mon-super-modele ./models . --quiet +https://huggingface.co/Wauplin/mon-super-modele/tree/main ``` ## huggingface-cli scan-cache -Scanning your cache directory is useful if you want to know which repos you have downloaded and how much space it takes on your disk. You can do that by running `huggingface-cli scan-cache`: +Scanner le chemin de votre cache peut être utile si vous voulez savoir 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 @@ -401,7 +429,7 @@ 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. ``` -For more details about how to scan your cache directory, please refer to the [Manage your cache](./manage-cache#scan-cache-from-the-terminal) guide. +Pour plus de détails sur comment scanner le chemin vers votre cache, veuillez vous référer au guide [Gérez votre cache](./manage-cache#scan-cache-from-the-terminal). ## huggingface-cli delete-cache @@ -409,7 +437,7 @@ For more details about how to scan your cache directory, please refer to the [Ma ## huggingface-cli env -The `huggingface-cli env` command prints details about your machine setup. This is useful when you open an issue on [GitHub](https://github.com/huggingface/huggingface_hub) to help the maintainers investigate your problem. +La commande `huggingface-cli env` affiche des détails sur le setup de votre machine. C'est particulièrement utile si vous ouvrez une issu sur [GitHub](https://github.com/huggingface/huggingface_hub) pour aider les mainteneurs à enquêter sur vos problèmes. ```bash >>> huggingface-cli env From 9ab5ba7c3742edbafc190a74f5e538c44bc80080 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sun, 10 Dec 2023 20:56:03 +0100 Subject: [PATCH 003/129] Testing to see if user is well configured --- docs/source/fr/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/fr/index.md b/docs/source/fr/index.md index 15efbb1dd5..71b5e800b9 100644 --- a/docs/source/fr/index.md +++ b/docs/source/fr/index.md @@ -4,6 +4,7 @@ rendered properly in your Markdown viewer. # 🤗 Hub client library +test The `huggingface_hub` library allows you to interact with the [Hugging Face Hub](https://hf.co), a machine learning platform for creators and collaborators. Discover pre-trained models and datasets for your projects or play with the hundreds of From 56462202b1ef75fd3ce8300ec8e99d872522586c Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sun, 10 Dec 2023 21:01:50 +0100 Subject: [PATCH 004/129] TEsting to see if branch is well configured --- docs/source/fr/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/fr/index.md b/docs/source/fr/index.md index 71b5e800b9..7f7160ab6c 100644 --- a/docs/source/fr/index.md +++ b/docs/source/fr/index.md @@ -2,9 +2,9 @@ rendered properly in your Markdown viewer. --> -# 🤗 Hub client library +# La librairie client 🤗 Hub -test +La librairie The `huggingface_hub` library allows you to interact with the [Hugging Face Hub](https://hf.co), a machine learning platform for creators and collaborators. Discover pre-trained models and datasets for your projects or play with the hundreds of From 8d3cd26dc67bc9deec3195b2c026411c0b24e293 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sun, 10 Dec 2023 21:29:40 +0100 Subject: [PATCH 005/129] Translated index --- docs/source/fr/index.md | 66 ++++++++++++++++++++--------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/source/fr/index.md b/docs/source/fr/index.md index 7f7160ab6c..5258eaa74a 100644 --- a/docs/source/fr/index.md +++ b/docs/source/fr/index.md @@ -4,36 +4,37 @@ rendered properly in your Markdown viewer. # La librairie client 🤗 Hub -La librairie -The `huggingface_hub` library allows you to interact with the [Hugging Face -Hub](https://hf.co), a machine learning platform for creators and collaborators. -Discover pre-trained models and datasets for your projects or play with the hundreds of -machine learning apps hosted on the Hub. You can also create and share your own models -and datasets with the community. The `huggingface_hub` library provides a simple way to -do all these things with Python. - -Read the [quick start guide](quick-start) to get up and running with the -`huggingface_hub` library. You will learn how to download files from the Hub, create a -repository, and upload files to the Hub. Keep reading to learn more about how to manage -your repositories on the 🤗 Hub, how to interact in discussions or even how to access -the Inference API. +La librairie `huggingface_hub` vous permet d'intéragir avec le +[Hub Hugging Face](https://hf.co), une plateforme de machine learning +pour les créateurs et les collaborateurs. Découvrez des modèles pré- +entraineés et des datasets pour vos projets ou jouez avec des centraines +d'application machine learning hébergées sur le Hub. Vous pouvez aussi +créer et partager vos propres modèles et datasets avec la communauté. +La librairie `huggingface_hub` offre une manière simple de faire toutes +ces choses avec Python. + +Lisez le [quick start guide](quick-start) pour vous lancer avec la librairie +`huggingface_hub`. Vous apprendrez à télécharger des fichiers depuis le Hub, +à créer un dépôt et upload des fichiers dans le Hub. Continuez à lire pour +apprendre le management de dépôt sur le Hub 🤗, comment intéragir avec les discussions +ou même comment accéder à l'API d'inférence.
-
How-to guides
-

Practical guides to help you achieve a specific goal. Take a look at these guides to learn how to use huggingface_hub to solve real-world problems.

+
Vue d'ensemble
+

Guides pratiques pour vous aider à atteindre un but en particulier. Regardez ces guides pour apprendre à utiliser huggingface_hub pour résoudre des problèmes concrets.

 -
Reference
-

Exhaustive and technical description of huggingface_hub classes and methods.

+
Référence
+

Description exhaustive et technique des classes et méthodes huggingface_hub.

 -
Conceptual guides
-

High-level explanations for building a better understanding of huggingface_hub philosophy.

+
Guides conceptuels
+

Explications haut niveau permettant d'avoir une meilleure compréhension de la philosophie huggingface_hub.
@@ -41,21 +42,20 @@ the Inference API. -## Contribute +## Contributions -All contributions to the `huggingface_hub` are welcomed and equally valued! 🤗 Besides -adding or fixing existing issues in the code, you can also help improve the -documentation by making sure it is accurate and up-to-date, help answer questions on -issues, and request new features you think will improve the library. Take a look at the -[contribution -guide](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) to -learn more about how to submit a new issue or feature request, how to submit a pull -request, and how to test your contributions to make sure everything works as expected. +Toutes les contributions à `huggingface_hub` sont les bienvenues, nous le valorisons toutes +à la même hauteur. 🤗 Hormis l'ajout ou la correction de problèmes dans le code, vous +pouvez aussi aider à améliorer la documentation en vérifiant qu'elle est exacte et +à jour, répondre à des questions sur des issues, et demander de nouvelles fonctionnalités +qui amélioreront la librairie. Regardez le [guide de contribution](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) +pour en savoir plus sur comment lancer une nouvelle issue ou une demande de nouvelle +fonctionnalité, comment faire un pull request et comment tester vos contributions pour +vérifier que tout fonctionne comme prévu. -Contributors should also be respectful of our [code of -conduct](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) to -create an inclusive and welcoming collaborative space for everyone. \ No newline at end of file +Les contributeurs doivent aussi respecter notre [code de conduite](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) +pour créer un espace collaboratif inclusif et bienveillant pour tout le monde. \ No newline at end of file From 2687f875bf68e06809b4114afa321a4f035ff495 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sun, 10 Dec 2023 22:03:33 +0100 Subject: [PATCH 006/129] Translated quick-start --- docs/source/fr/quick-start.md | 136 ++++++++++++++++++---------------- 1 file changed, 71 insertions(+), 65 deletions(-) diff --git a/docs/source/fr/quick-start.md b/docs/source/fr/quick-start.md index 8d6e52b889..603d6c61b4 100644 --- a/docs/source/fr/quick-start.md +++ b/docs/source/fr/quick-start.md @@ -2,43 +2,44 @@ rendered properly in your Markdown viewer. --> -# Quickstart +# Démarrage rapide -The [Hugging Face Hub](https://huggingface.co/) is the go-to place for sharing machine learning -models, demos, datasets, and metrics. `huggingface_hub` library helps you interact with -the Hub without leaving your development environment. You can create and manage -repositories easily, download and upload files, and get useful model and dataset -metadata from the Hub. +Le [Hub Hugging Face](https://huggingface.co/) est le meilleur endroit pour partager des +modèles de machine learning, des démos, des datasets et des metriques. La librairie +`huggingface_hub` vous aide à intéragir avec le Hub sans sortir de votre environnement de +développement. Vous pouvez: créer et gérer des dépôts facilement, télécharger et upload des +fichiers, et obtenir des modèles et des metadata depuis le Hub. ## Installation -To get started, install the `huggingface_hub` library: +Pour commencer, installez la librairie `huggingface_hub`: ```bash pip install --upgrade huggingface_hub ``` -For more details, check out the [installation](installation) guide. +Pour plus de détails, vérifiez le guide [installation](installation) -## Download files +## Télécharger des fichiers -Repositories on the Hub are git version controlled, and users can download a single file -or the whole repository. You can use the [`hf_hub_download`] function to download files. -This function will download and cache a file on your local disk. The next time you need -that file, it will load from your cache, so you don't need to re-download it. +Les dépôts sur le Hub sont sous controle de version Git, et les utilisateurs peuvent +télécharger un fichier, ou dépôt entier. Vous pouvez utiliser la fonction [`hf_hub_download`] +pour télécharger des fichiers. Cette fonction télécharger et mettra dans le cache un fichier +sur votre disque local. La prochaine fois que vous aurez besoin de ce fichier, il sera chargé +depuis votre cache de façon à ce que vous n'ayez pas besoin de le retélécharger. -You will need the repository id and the filename of the file you want to download. For -example, to download the [Pegasus](https://huggingface.co/google/pegasus-xsum) model -configuration file: +Vous aurez besoin de l'id du dépôt et du nom du fichier que vous voulez télécharger. +Par exemple, pour télécharger le fichier de configuration du +modèle [Pegasus](https://huggingface.co/google/pegasus-xsum): ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") ``` -To download a specific version of the file, use the `revision` parameter to specify the -branch name, tag, or commit hash. If you choose to use the commit hash, it must be the -full-length hash instead of the shorter 7-character commit hash: +Pour télécharger une version spécifique du fichier, utilisez le paramètre `revision` afin +de spécifier le nom de la branche, le tag ou le hash de commit. Si vous décidez d'utiliser +le hash de commit, ce doit être le hash entier et pas le hash court de 7 caractères: ```py >>> from huggingface_hub import hf_hub_download @@ -49,18 +50,20 @@ full-length hash instead of the shorter 7-character commit hash: ... ) ``` -For more details and options, see the API reference for [`hf_hub_download`]. +Pour plus de détails et d'options, consultez la réference de l'API pour [`hf_hub_download`]. -## Login +## Connexion -In a lot of cases, you must be logged in with a Hugging Face account to interact with -the Hub: download private repos, upload files, create PRs,... -[Create an account](https://huggingface.co/join) if you don't already have one, and then sign in -to get your [User Access Token](https://huggingface.co/docs/hub/security-tokens) from -your [Settings page](https://huggingface.co/settings/tokens). The User Access Token is -used to authenticate your identity to the Hub. +Dans la plupart des cas, vous devez être connectés avec un compte Hugging Face pour intéragir +avec le Hub: pour télécharger des dépôts privés, upload des fichiers, créer des pull +requests... +[Créez un compte](https://huggingface.co/join) si vous n'en avez pas déjà un et connectez +vous pour obtenir votre [Token d'Authentification](https://huggingface.co/docs/hub/security-tokens) +depuis vos [Paramètres](https://huggingface.co/settings/tokens). Le token +est utilisé pour authentifier votre identité au Hub. -Once you have your User Access Token, run the following command in your terminal: +Une fois que vous avez votre token d'authentification, lancez la commande suivante +dans votre terminal: ```bash huggingface-cli login @@ -68,35 +71,37 @@ huggingface-cli login huggingface-cli login --token $HUGGINGFACE_TOKEN ``` -Alternatively, you can programmatically login using [`login`] in a notebook or a script: +Alternativement, vous pouvez vous connecter en utilisant [`login`] dans un notebook ou +un script: ```py >>> from huggingface_hub import login >>> login() ``` -It is also possible to login programmatically without being prompted to enter your token by directly -passing the token to [`login`] like `login(token="hf_xxx")`. If you do so, be careful when -sharing your source code. It is a best practice to load the token from a secure vault instead -of saving it explicitly in your codebase/notebook. +Il est aussi possible de se connecter automatiquement sans qu'on vous demande votre token en +passant le token dans [`login`] de cette manière: `login(token="hf_xxx")`. Si vous choisissez +cette méthode, faites attention lorsque vous partagez votre code source. Une bonne pratique est +de charger le token depuis un trousseau sécurisé aulieu de l'enregistrer en clair dans votre +codebase/notebook. -You can be logged in only to 1 account at a time. If you login your machine to a new account, you will get logged out -from the previous. Make sure to always which account you are using with the command `huggingface-cli whoami`. -If you want to handle several accounts in the same script, you can provide your token when calling each method. This -is also useful if you don't want to store any token on your machine. +Vous ne pouvez être connecté qu'à un seul compte à la fois. Si vous connectez votre machine à un autre compte, +vous serez déconnectés du premier compte. Vérifiez toujours le compte que vous utilisez avec la commande +`huggingface-cli whoami`. Si vous voulez gérer plusieurs compte dans le même script, vous pouvez passer votre +token à chaque appel de méthode. C'est aussi utile si vous ne voulez pas sauvegarder de token sur votre machine. -Once you are logged in, all requests to the Hub -even methods that don't necessarily require authentication- will use your -access token by default. If you want to disable implicit use of your token, you should set the -`HF_HUB_DISABLE_IMPLICIT_TOKEN` environment variable. +une fois que vous êtes connectés, toutes les requêtes vers le Hub (même les méthodes qui ne nécessite pas explicitement +d'authentification) utiliseront votre token d'authentification par défaut. Si vous voulez supprimer l'utilisation implicite +de votre token, vous devez définir la variable d'environnement `HF_HUB_DISABLE_IMPLICIT_TOKEN`. -## Create a repository +## Créer un dépôt -Once you've registered and logged in, create a repository with the [`create_repo`] -function: +Une fois que vous avez créer votre compte et que vous vous êtes connectés, +vous pouvez créer un dépôt avec la fonction [`create_repo`]: ```py >>> from huggingface_hub import HfApi @@ -104,7 +109,7 @@ function: >>> api.create_repo(repo_id="super-cool-model") ``` -If you want your repository to be private, then: +Si vous voulez que votre dépôt soit privé, alors: ```py >>> from huggingface_hub import HfApi @@ -112,24 +117,24 @@ If you want your repository to be private, then: >>> api.create_repo(repo_id="super-cool-model", private=True) ``` -Private repositories will not be visible to anyone except yourself. +Les dépôts privés ne seront visible que par vous. -To create a repository or to push content to the Hub, you must provide a User Access -Token that has the `write` permission. You can choose the permission when creating the -token in your [Settings page](https://huggingface.co/settings/tokens). +Pour créer un dépôt ou push du contenu sur le Hub, vous devez fournir un token +d'authentification qui a les permissions `write`. Vous pouvez choisir la permission +lorsque vous créez le token dans vos [Paramètres](https://huggingface.co/settings/tokens). -## Upload files +## Upload des fichiers -Use the [`upload_file`] function to add a file to your newly created repository. You -need to specify: +Utilisez la fonction [`upload_file`] pour ajouter un fichier à votre dépôt. +Vous devez spécifier: -1. The path of the file to upload. -2. The path of the file in the repository. -3. The repository id of where you want to add the file. +1. Le chemin du fichier à upload. +2. Le chemin du fichier dans le dépôt. +3. L'id du dépôt dans lequel vous voulez ajouter le fichier. ```py >>> from huggingface_hub import HfApi @@ -141,17 +146,18 @@ need to specify: ... ) ``` -To upload more than one file at a time, take a look at the [Upload](./guides/upload) guide -which will introduce you to several methods for uploading files (with or without git). +Pour upload plus d'un fichier à la fois, consultez le guide [Upload](./guides/upload) +qui vous expliqueras plusieurs méthodes pour upload des fichiers (avec ou sans Git). -## Next steps +## Prochaines étapes -The `huggingface_hub` library provides an easy way for users to interact with the Hub -with Python. To learn more about how you can manage your files and repositories on the -Hub, we recommend reading our [how-to guides](./guides/overview) to: +La librairie `huggingface_hub` offre une manière simple aux utilisateurs pour qu'ils puissent +intéragir avec le Hub via Python. Pour en apprendre plus sur comment gérer vos fichiers +et vos dépôts sur le Hub, nous vous recommandons de lire notre [how-to guides](./guides/overview) +pour : -- [Manage your repository](./guides/repository). -- [Download](./guides/download) files from the Hub. -- [Upload](./guides/upload) files to the Hub. -- [Search the Hub](./guides/search) for your desired model or dataset. -- [Access the Inference API](./guides/inference) for fast inference. \ No newline at end of file +- [Gérer votre dépôt](./guides/repository). +- [Télécharger](./guides/download) des fichiers depuis le HUb. +- [Upload](./guides/upload) des fichiers vers le Hub. +- [Faire des recherches dans le Hub](./guides/search) pour votre modèle ou dataset. +- [Accédder à l'API d'inférence](./guides/inference) pour faire des inférences rapides. \ No newline at end of file From 7aff9fd17fb2dae1f1c9c2fd243bec0eb4b02252 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 11 Dec 2023 09:50:22 +0100 Subject: [PATCH 007/129] Corrected a minor error in the english doc --- docs/source/en/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/en/installation.md b/docs/source/en/installation.md index 1426f20818..81d84cbf68 100644 --- a/docs/source/en/installation.md +++ b/docs/source/en/installation.md @@ -102,7 +102,7 @@ cd huggingface_hub pip install -e . ``` -These commands will link the folder you cloned the repository to and your Python library paths. +These commands will link the folder you cloned to the repository and your Python library paths. Python will now look inside the folder you cloned to in addition to the normal library paths. For example, if your Python packages are typically installed in `./.venv/lib/python3.11/site-packages/`, Python will also search the folder you cloned `./huggingface_hub/`. From 9fd8930b23ea59c4bf9f0fb9db9e96cb46de0157 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 11 Dec 2023 09:52:30 +0100 Subject: [PATCH 008/129] Reverting a wrong change --- docs/source/en/installation.md | 2 +- docs/source/fr/installation.md | 86 ++++++++++++++++++---------------- 2 files changed, 46 insertions(+), 42 deletions(-) diff --git a/docs/source/en/installation.md b/docs/source/en/installation.md index 81d84cbf68..1426f20818 100644 --- a/docs/source/en/installation.md +++ b/docs/source/en/installation.md @@ -102,7 +102,7 @@ cd huggingface_hub pip install -e . ``` -These commands will link the folder you cloned to the repository and your Python library paths. +These commands will link the folder you cloned the repository to and your Python library paths. Python will now look inside the folder you cloned to in addition to the normal library paths. For example, if your Python packages are typically installed in `./.venv/lib/python3.11/site-packages/`, Python will also search the folder you cloned `./huggingface_hub/`. diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 1426f20818..03cd32fd83 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -4,104 +4,108 @@ rendered properly in your Markdown viewer. # Installation -Before you start, you will need to setup your environment by installing the appropriate packages. +Avant de commmencer l'installation, vous allez avoir besoin de préparer votre environnement +en installant les packages appropriés. -`huggingface_hub` is tested on **Python 3.8+**. +`huggingface_hub` est testé sur **Python 3.8+**. -## Install with pip +## Installation avec pip -It is highly recommended to install `huggingface_hub` in a [virtual environment](https://docs.python.org/3/library/venv.html). -If you are unfamiliar with Python virtual environments, take a look at this [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). -A virtual environment makes it easier to manage different projects, and avoid compatibility issues between dependencies. +Il est fortement recommandé d'installer `huggingface_hub` dans un [environnement virtuel](https://docs.python.org/3/library/venv.html). +Si vous êtes familier avec les environnements virtuels python, regardez plutôt ce [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Un environnement virtuel sera utile lorsque vous devrez gérer des projets différents +et éviter les problèmes de compatibilité entre les différetnes dépendances. -Start by creating a virtual environment in your project directory: +Commencez par créer un environnement virtuel dans le chemin de votre projet: ```bash python -m venv .env ``` -Activate the virtual environment. On Linux and macOS: +Activez l'environnement virtuel sur Linux et macOS: ```bash source .env/bin/activate ``` -Activate virtual environment on Windows: +Activez l'environnement virtuel sur Windows: ```bash .env/Scripts/activate ``` -Now you're ready to install `huggingface_hub` [from the PyPi registry](https://pypi.org/project/huggingface-hub/): +Maintenant, vous êtes prêts à installer `hugginface_hub` [depuis PyPi ](https://pypi.org/project/huggingface-hub/): ```bash pip install --upgrade huggingface_hub ``` -Once done, [check installation](#check-installation) is working correctly. +Une fois l'installation finie, [vérifiez](#check-installation) que tout marche correctement. -### Install optional dependencies +### Installation des dépendances optionnelles -Some dependencies of `huggingface_hub` are [optional](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) because they are not required to run the core features of `huggingface_hub`. However, some features of the `huggingface_hub` may not be available if the optional dependencies aren't installed. +Certaines dépendances de `huggingface_hub` sont [optionnelles](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) car elles ne sont pas nécessaire pour faire marcher les fonctionnalités principales de `huggingface_hub`. +Toutefois, certaines fonctionnalités de `huggingface_hub` ne seront pas disponibles si les dépendancces optionnelles ne sont pas installées -You can install optional dependencies via `pip`: +Vous pouvez installer des dépendances optionelles via `pip`: ```bash -# Install dependencies for tensorflow-specific features -# /!\ Warning: this is not equivalent to `pip install tensorflow` +#Installation des dépendances pour les fonctionnalités spécifiques à Tensorflow. +#/!\ Attention : cette commande n'est pas équivalente à `pip install tensorflow`. pip install 'huggingface_hub[tensorflow]' -# Install dependencies for both torch-specific and CLI-specific features. +#Installation des dépendances spécifiques à Pytorch et au CLI. pip install 'huggingface_hub[cli,torch]' ``` -Here is the list of optional dependencies in `huggingface_hub`: -- `cli`: provide a more convenient CLI interface for `huggingface_hub`. -- `fastai`, `torch`, `tensorflow`: dependencies to run framework-specific features. -- `dev`: dependencies to contribute to the lib. Includes `testing` (to run tests), `typing` (to run type checker) and `quality` (to run linters). +Voici une liste des dépendances optionnelles dans `huggingface_hub`: +- `cli` fournit une interface d'invite de commande plus pratique pour `huggingface_hub`. +- `fastai`, `torch` et `tensorflow` sont des dépendances pour utiliser des fonctionnalités spécifique à un framework. +- `dev` permet de contribuer à la librairie. Cette dépendance inclut `testing` (pour lancer des tests), `typing` (pour lancer le vérifieur de type) et `quality` (pour lancer des linters). -### Install from source +### Installation depuis la source -In some cases, it is interesting to install `huggingface_hub` directly from source. -This allows you to use the bleeding edge `main` version rather than the latest stable version. -The `main` version is useful for staying up-to-date with the latest developments, for instance -if a bug has been fixed since the last official release but a new release hasn't been rolled out yet. +Dans certains cas, il est intéressant d'installer `huggingface_hub` directement depuis la source. +Ceci vous permet d'utiliser la version `main`, contenant les dernières mises à jour, plutôt que +d'utiliser la dernière version stable. La version `main` est utile pour rester à jour sur les +derniers développements, par exemple si un bug est réglé depuis la dernière sortie officielle +mais que la nouvelle sortie n'a pas encore été faite. -However, this means the `main` version may not always be stable. We strive to keep the -`main` version operational, and most issues are usually resolved -within a few hours or a day. If you run into a problem, please open an Issue so we can -fix it even sooner! +Toutefois, cela signifie que la version `main` pourrait ne pas stable. Nous travaillons +afin de rendre la version `main` optionnelle, et la pluspart des problèmes sont résolus +en quelques heure ou en une journée. Si vous avez un problème, ouvrez une Issue afin que +nous puissions la régler encore plus vite ! ```bash pip install git+https://github.com/huggingface/huggingface_hub ``` -When installing from source, you can also specify a specific branch. This is useful if you -want to test a new feature or a new bug-fix that has not been merged yet: +Lorsque vous faites l'installation depuis le code source, vous pouvez aussi préciser une +branche spécifique. C'est utile si vous voulez tester une nouvelle fonctionnalité ou un +nouveau bug-fix qui n'a pas encore été merge: ```bash -pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch +pip install git+https://github.com/huggingface/huggingface_hub@ma-branche ``` -Once done, [check installation](#check-installation) is working correctly. +Une fois fini, [vérifiez l'installation](#check-installation). -### Editable install +### Installation éditable -Installing from source allows you to setup an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). -This is a more advanced installation if you plan to contribute to `huggingface_hub` -and need to test changes in the code. You need to clone a local copy of `huggingface_hub` -on your machine. +L'installation depuis le code source vous permet de mettre en place une [installation éditable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). Cette installation est plus avancée et sert surtout si vous comptez contribuer à `huggingface_hub` +et que vous avez besoin de tester des changements dans le code. Vous devez cloner une copie locale de `huggingface_hub` sur votre machine. ```bash -# First, clone repo locally +#D'abord, clonez le dépôt en local git clone https://github.com/huggingface/huggingface_hub.git -# Then, install with -e flag +# Ensuite, installez avec le flag -e cd huggingface_hub pip install -e . ``` +Ces commandes lieront le dossier que vous avez cloné avec le dépôt et vos chemins de librairies Python. +Python regardera maintenant à l'intérieur du dossier dans lequel vous avez cloné le dépôt et These commands will link the folder you cloned the repository to and your Python library paths. Python will now look inside the folder you cloned to in addition to the normal library paths. For example, if your Python packages are typically installed in `./.venv/lib/python3.11/site-packages/`, From 1ea5fc749931acbd9db453afb189357ed55fb4ea Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 11 Dec 2023 10:15:09 +0100 Subject: [PATCH 009/129] Translated installation.md --- docs/source/fr/installation.md | 63 +++++++++++++++++----------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 03cd32fd83..528898039b 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -104,34 +104,33 @@ cd huggingface_hub pip install -e . ``` -Ces commandes lieront le dossier que vous avez cloné avec le dépôt et vos chemins de librairies Python. -Python regardera maintenant à l'intérieur du dossier dans lequel vous avez cloné le dépôt et -These commands will link the folder you cloned the repository to and your Python library paths. -Python will now look inside the folder you cloned to in addition to the normal library paths. -For example, if your Python packages are typically installed in `./.venv/lib/python3.11/site-packages/`, -Python will also search the folder you cloned `./huggingface_hub/`. +Ces commandes lieront le dossier dans lequel vous avez cloné le dépôt et vos chemins de librairies Python. +Python regardera maintenant à l'intérieur du dossier dans lequel vous avez cloné le dépôt en +plus des chemins de librairie classiques. Par exemple, si vos packages Python sont installés dans +`./.venv/lib/python3.11/site-packages/`, Python regardera uassi dans le dossier que vous avez +cloné `./huggingface_hub/`. -## Install with conda +## Installation avec conda -If you are more familiar with it, you can install `huggingface_hub` using the [conda-forge channel](https://anaconda.org/conda-forge/huggingface_hub): +Si vous avez plutôt l'habitude d'utiliser conda, vous pouvez installer `huggingface_hub` en utilisant le [channel conda-forge](https://anaconda.org/conda-forge/huggingface_hub): ```bash conda install -c conda-forge huggingface_hub ``` -Once done, [check installation](#check-installation) is working correctly. +Une fois fini, [vérifiez l'installation](#check-installation). -## Check installation +## Vérification de l'installation -Once installed, check that `huggingface_hub` works properly by running the following command: +Une fois installé, vérifiez que `huggingface_hub` marche correctement en lançant la commande suivante: ```bash python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" ``` -This command will fetch information from the Hub about the [gpt2](https://huggingface.co/gpt2) model. -Output should look like this: +Cette commande va récupérer des informations sur le modèle [gpt2](https://huggingface.co/gpt2) depuis le Hub. +La sortie devrait ressembler à ça: ```text Model Name: gpt2 @@ -139,26 +138,28 @@ Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-ge Task: text-generation ``` -## Windows limitations +## Les limitations Windows -With our goal of democratizing good ML everywhere, we built `huggingface_hub` to be a -cross-platform library and in particular to work correctly on both Unix-based and Windows -systems. However, there are a few cases where `huggingface_hub` has some limitations when -run on Windows. Here is an exhaustive list of known issues. Please let us know if you -encounter any undocumented problem by opening [an issue on Github](https://github.com/huggingface/huggingface_hub/issues/new/choose). +Afin de démocratiser le machine learning pour tous, nous avons construit `huggingface_hub` +de façon à voir une librairie cross-platform et en particulier, une librairie qui marche +sur les systèmes Windows et ceux basés sur Unix. Toutefois il y a certains cas où +`huggingface_hub` est plus limité lorsqu'il tourne sur Windows. Ci-dessous une liste exhaustive +des problèmes connus. N'hésitez pas à nous signaler si vous rencontrez un problème +sans documentation en ouvrant une [issue sur Github](https://github.com/huggingface/huggingface_hub/issues/new/choose). -- `huggingface_hub`'s cache system relies on symlinks to efficiently cache files downloaded -from the Hub. On Windows, you must activate developer mode or run your script as admin to -enable symlinks. If they are not activated, the cache-system still works but in an non-optimized -manner. Please read [the cache limitations](./guides/manage-cache#limitations) section for more details. -- Filepaths on the Hub can have special characters (e.g. `"path/to?/my/file"`). Windows is -more restrictive on [special characters](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) -which makes it impossible to download those files on Windows. Hopefully this is a rare case. -Please reach out to the repo owner if you think this is a mistake or to us to figure out -a solution. +- Le cache de `huggingface_hub` a besoin des symlinks pour mettre en cache les fichiers installé depuis le Hub. +Sur windows, vous devez activer le mode développeur pour lancer votre script en tant qu'administrateur +afin d'activer les symlinks. S'il ne sont pas activés, le système de cache fonctionnera toujours mais +de manière suboptimale. Consultez [limitations du cache](./guides/manage-cache#limitations) pour plus de détails. +- Les chemins de fichiers sur le Hub peuvent avoir des caractères spéciaux (par exemple `"path/to?/my/file"`). +Windows est plus restrictif sur les [caractères spéciaux](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) +ce qui rend ces fichiers ininstallables sur Windows. Heureusement c'est un cas assez rare. +Contactez le propriétaire du dépôt sir vous pensez que c'est une erreur ou contactez nous +pour que nous cherchions une solution. -## Next steps +## Prochaines étapes -Once `huggingface_hub` is properly installed on your machine, you might want -[configure environment variables](package_reference/environment_variables) or [check one of our guides](guides/overview) to get started. \ No newline at end of file +Une fois que `huggingface_hub` est installé correctement sur votre machine, vous aurez peut-être besoin de +[configurer les variables d'environnement](package_reference/environment_variables) ou de [lire un de nos guides](guides/overview) +pour vous lancer. \ No newline at end of file From 66c11a34730af896dde608509b097758cafe63b9 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 11 Dec 2023 10:19:52 +0100 Subject: [PATCH 010/129] Translated community.md --- docs/source/fr/package_reference/community.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/fr/package_reference/community.md b/docs/source/fr/package_reference/community.md index d41d45c8a6..ad5571e905 100644 --- a/docs/source/fr/package_reference/community.md +++ b/docs/source/fr/package_reference/community.md @@ -2,10 +2,10 @@ rendered properly in your Markdown viewer. --> -# Interacting with Discussions and Pull Requests +# Interagir avec les dicussions et les pull requestions -Check the [`HfApi`] documentation page for the reference of methods enabling -interaction with Pull Requests and Discussions on the Hub. +Regardez la page de documentation [`HfApi`] pour les références des méthodes permettant l'intéraction +avec des pull requests et des discussions sur le Hub. - [`get_repo_discussions`] - [`get_discussion_details`] @@ -17,7 +17,7 @@ interaction with Pull Requests and Discussions on the Hub. - [`change_discussion_status`] - [`merge_pull_request`] -## Data structures +## Structure des données [[autodoc]] Discussion From d2b4c304b30bd8e449404db509c88cadca5a1aef Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 11 Dec 2023 10:25:42 +0100 Subject: [PATCH 011/129] Translated download.md --- .../fr/package_reference/file_download.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/fr/package_reference/file_download.md b/docs/source/fr/package_reference/file_download.md index 1bc5b21478..97050065c6 100644 --- a/docs/source/fr/package_reference/file_download.md +++ b/docs/source/fr/package_reference/file_download.md @@ -2,9 +2,9 @@ rendered properly in your Markdown viewer. --> -# Downloading files +# Téléchargement des fichiers -## Download a single file +## Télécharger un unique fichier ### hf_hub_download @@ -14,11 +14,11 @@ rendered properly in your Markdown viewer. [[autodoc]] huggingface_hub.hf_hub_url -## Download a snapshot of the repo +## Télécharger un instantané du dépôt [[autodoc]] huggingface_hub.snapshot_download -## Get metadata about a file +## Obtenir une métadonnée sur un fichier ### get_hf_file_metadata @@ -28,11 +28,11 @@ rendered properly in your Markdown viewer. [[autodoc]] huggingface_hub.HfFileMetadata -## Caching +## Utilisation du cache -The methods displayed above are designed to work with a caching system that prevents -re-downloading files. The caching system was updated in v0.8.0 to become the central -cache-system shared across libraries that depend on the Hub. +Le méthodes affichées ci dessus sont faites pour fonctionner avec un système de cache +ce qui évite de retélécharger des fichiers. Le système de cache a été mis à jour dans +la version v0.8.0 afin d'être le système de cache central partagé dans toutes les +librairies dépendant du Hub. -Read the [cache-system guide](../guides/manage-cache) for a detailed presentation of caching at -at HF. +Consultez le [guide cache-system](../guides/manage-cache) pour une présentation détaillée du caching à HF. \ No newline at end of file From 87b5bbe73aa0622fd3a038b01ad2f03a2304f2e2 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 11 Dec 2023 10:29:38 +0100 Subject: [PATCH 012/129] Translated hf_file_system.md --- docs/source/fr/package_reference/hf_file_system.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/fr/package_reference/hf_file_system.md b/docs/source/fr/package_reference/hf_file_system.md index f203ebd070..e36c6393fa 100644 --- a/docs/source/fr/package_reference/hf_file_system.md +++ b/docs/source/fr/package_reference/hf_file_system.md @@ -2,13 +2,13 @@ rendered properly in your Markdown viewer. --> -# Filesystem API +# L'API FileSystem -The `HfFileSystem` class provides a pythonic file interface to the Hugging Face Hub based on [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/). +La classe `HfFileSystem` offre une interface Python pour le Hub Hugging Face basée sur [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/). ## HfFileSystem -`HfFileSystem` is based on [fsspec](https://filesystem-spec.readthedocs.io/en/latest/), so it is compatible with most of the APIs that it offers. For more details, check out [our guide](../guides/hf_file_system) and fsspec's [API Reference](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem). +`HfFileSystem` est basé sur [fsspec](https://filesystem-spec.readthedocs.io/en/latest/), donc cette classe est compatible avec la plupart des API offertes par fsspec. Pour plus de détails, consultez [notre guide](../guides/hf_file_system) et les [Références](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem) de l'API fsspec. [[autodoc]] HfFileSystem - __init__ From d18cbf96fbb788cd6ed6e37846f160c0ce7855b1 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 11 Dec 2023 18:36:26 +0100 Subject: [PATCH 013/129] Translated inference_client --- .../fr/package_reference/inference_client.md | 61 ++++++++++--------- 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/docs/source/fr/package_reference/inference_client.md b/docs/source/fr/package_reference/inference_client.md index a4fa6b358d..efebde11ad 100644 --- a/docs/source/fr/package_reference/inference_client.md +++ b/docs/source/fr/package_reference/inference_client.md @@ -2,28 +2,29 @@ rendered properly in your Markdown viewer. --> -# Inference +# Inférence -Inference is the process of using a trained model to make predictions on new data. As this process can be compute-intensive, -running on a dedicated server can be an interesting option. The `huggingface_hub` library provides an easy way to call a -service that runs inference for hosted models. There are several services you can connect to: -- [Inference API](https://huggingface.co/docs/api-inference/index): a service that allows you to run accelerated inference -on Hugging Face's infrastructure for free. This service is a fast way to get started, test different models, and -prototype AI products. -- [Inference Endpoints](https://huggingface.co/inference-endpoints): a product to easily deploy models to production. -Inference is run by Hugging Face in a dedicated, fully managed infrastructure on a cloud provider of your choice. +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ée +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. -These services can be called with the [`InferenceClient`] object. Please refer to [this guide](../guides/inference) -for more information on how to use it. +Ces services peuvent être appelés avec l'objet [`InferenceClient`]. Consultez [ce guide](../guides/inference) pour plus +d'informations sur le mode d'utilisation. -## Inference Client +## Client d'inférence [[autodoc]] InferenceClient -## Async Inference Client +## Client d'inférence asynchrone -An async version of the client is also provided, based on `asyncio` and `aiohttp`. -To use it, you can either install `aiohttp` directly or use the `[inference]` extra: +Une version asychrone du client basée sur `asyncio` et `aihttp` est aussi fournie. +Pour l'utiliser, vous pouvez soit installer `aiohttp` directement ou utiliser l'extra `[inference]`: ```sh pip install --upgrade huggingface_hub[inference] @@ -37,9 +38,9 @@ pip install --upgrade huggingface_hub[inference] [[autodoc]] InferenceTimeoutError -## Return types +## Types retournés -For most tasks, the return value has a built-in type (string, list, image...). Here is a list for the more complex types. +Pour la plupart des tâches, la valeur retournée a un type intégré (string, list, image...). Voici une liste de types plus complexes. ### ClassificationOutput @@ -65,15 +66,16 @@ For most tasks, the return value has a built-in type (string, list, image...). H [[autodoc]] huggingface_hub.inference._types.TokenClassificationOutput -### Text generation types +### Types pour la génération de texte -[`~InferenceClient.text_generation`] task has a greater support than other tasks in `InferenceClient`. In -particular, user inputs and server outputs are validated using [Pydantic](https://docs.pydantic.dev/latest/) -if this package is installed. Therefore, we recommend installing it (`pip install pydantic`) -for a better user experience. +La tâche [`~InferenceClient.text_generation`] a un meilleur support que d'autres tâches dans `InferenceClient`. +Plus précisément, les inputs des utilisateurs et les outputs des serveurs sont validés en utilisant [Pydantic](https://docs.pydantic.dev/latest/) +si ce package est installé. Par conséquent, nous vous recommandons de l'installer (`pip install pydantic`) pour +une meilleure expérience. -You can find below the dataclasses used to validate data and in particular [`~huggingface_hub.inference._text_generation.TextGenerationParameters`] (input), -[`~huggingface_hub.inference._text_generation.TextGenerationResponse`] (output) and +Vous pouvez trouver ci-dessous, les dataclasses utilisées pour valider des données et en particulier +[`~huggingface_hub.inference._text_generation.TextGenerationParameters`] (input) +[`~huggingface_hub.inference._text_generation.TextGenerationResponse`] (output) et [`~huggingface_hub.inference._text_generation.TextGenerationStreamResponse`] (streaming output). [[autodoc]] huggingface_hub.inference._text_generation.TextGenerationParameters @@ -96,11 +98,12 @@ You can find below the dataclasses used to validate data and in particular [`~hu ## InferenceAPI -[`InferenceAPI`] is the legacy way to call the Inference API. The interface is more simplistic and requires knowing -the input parameters and output format for each task. It also lacks the ability to connect to other services like -Inference Endpoints or AWS SageMaker. [`InferenceAPI`] will soon be deprecated so we recommend using [`InferenceClient`] -whenever possible. Check out [this guide](../guides/inference#legacy-inferenceapi-client) to learn how to switch from -[`InferenceAPI`] to [`InferenceClient`] in your scripts. +[`InferenceAPI`] est la méthode historique pour appeler l'API d'inférence. L'interface est plus simpliste et +demande une conaissance des paramètres d'entrées et du format de sortie de chacune des tâches. Cette interface +ne peut pas se connecter à d'autres services tels que Inference Endpoints or AWS SageMaker. [`InferenceAPI`] sera +bientôt deprecated, ainsi, nous recommendons l'utilisation de [`InferenceClient`] quand c'est possible. +Consultez [ce guide](../guides/inference#legacy-inferenceapi-client) pour apprendre comment passer +d'[`InferenceAPI`] à [`InferenceClient`] dans vos scripts. [[autodoc]] InferenceApi - __init__ From 3f3e83131943b3dfa1be7e237ad55756433dbde5 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 11 Dec 2023 18:48:14 +0100 Subject: [PATCH 014/129] Translated inference_endpoints.md --- docs/source/fr/_toctree.yml | 2 +- .../package_reference/inference_endpoints.md | 24 +++++++++++-------- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index 5ee183856a..cd25b21803 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -63,7 +63,7 @@ - local: package_reference/inference_client title: Client d'inférence - local: package_reference/inference_endpoints - title: Endpoints d'Inférence + title: Inference Endpoints - local: package_reference/hf_file_system title: HfFileSystem - local: package_reference/utilities diff --git a/docs/source/fr/package_reference/inference_endpoints.md b/docs/source/fr/package_reference/inference_endpoints.md index 37521f8bb1..739f1fd39b 100644 --- a/docs/source/fr/package_reference/inference_endpoints.md +++ b/docs/source/fr/package_reference/inference_endpoints.md @@ -1,27 +1,31 @@ # Inference Endpoints -Inference Endpoints provides a secure production solution to easily deploy models on a dedicated and autoscaling infrastructure managed by Hugging Face. An Inference Endpoint is built from a model from the [Hub](https://huggingface.co/models). This page is a reference for `huggingface_hub`'s integration with Inference Endpoints. For more information about the Inference Endpoints product, check out its [official documentation](https://huggingface.co/docs/inference-endpoints/index). +Inferrence Endpoints est une solutions permettant de déployer facilement les modèles en production sur une infrastructure dédiée et capaable de faire de l'autoscaling gérée par Hugging Face. Un Inference Endpoint peut être crée sur un modèle depuis le [Hub](https://huggingface.co/models). Cette page est +une référence pour l'intégration d'`huggingface_hub` avec Inference Endpoints. Pour plus d'informations à propos du produit Inference Endpoints, consulez +la [documentation officielle](https://huggingface.co/docs/inference-endpoints/index). -Check out the [related guide](../guides/inference_endpoints) to learn how to use `huggingface_hub` to manage your Inference Endpoints programmatically. +Consultez ce [guide](../guides/inference_endpoints) pour apprendre comment utiliser `huggingface_hub` pour gérer votre Inference Enpoints depuis le code. -Inference Endpoints can be fully managed via API. The endpoints are documented with [Swagger](https://api.endpoints.huggingface.cloud/). The [`InferenceEndpoint`] class is a simple wrapper built on top on this API. +Inference Endpoints peut-être complètement géré depuis une API. Les enpoints sont consultables via [Swagger](https://api.endpoints.huggingface.cloud/). +La classe [`InferenceEndpoint`] est un simple wrapper autour de cette API. -## Methods +## Méthodes -A subset of the Inference Endpoint features are implemented in [`HfApi`]: +Un sous ensemble des fonctionnalités de l'Inference Endpoint sont implémentées dans [`HfApi`]: -- [`get_inference_endpoint`] and [`list_inference_endpoints`] to get information about your Inference Endpoints -- [`create_inference_endpoint`], [`update_inference_endpoint`] and [`delete_inference_endpoint`] to deploy and manage Inference Endpoints -- [`pause_inference_endpoint`] and [`resume_inference_endpoint`] to pause and resume an Inference Endpoint -- [`scale_to_zero_inference_endpoint`] to manually scale an Endpoint to 0 replicas +- [`get_inference_endpoint`] et [`list_inference_endpoints`] pour obtenir de l'information sur votre Inference Endpoints +- [`create_inference_endpoint`], [`update_inference_endpoint`] et [`delete_inference_endpoint`] pour déployer et gérer Inference Endpoints +- [`pause_inference_endpoint`] et [`resume_inference_endpoint`] pour mettre en pause et relancer un Inference Enpoint +- [`scale_to_zero_inference_endpoint`] pour scale à la main l'Inference Endpoint à 0 replicas ## InferenceEndpoint -The main dataclass is [`InferenceEndpoint`]. It contains information about a deployed `InferenceEndpoint`, including its configuration and current state. Once deployed, you can run inference on the Endpoint using the [`InferenceEndpoint.client`] and [`InferenceEndpoint.async_client`] properties that respectively return an [`InferenceClient`] and an [`AsyncInferenceClient`] object. +La dataclass principale est [`InferenceEndpoint`]. Elle contient des informations sur un `InferenceEndpoint` déployé, incluant sa configuration et son +état actuel. Une fois déployé, vous pouvez faire des inférences sur l'enpoint en utilisant les propriétés [`InferenceEndpoint.client`] et [`InferenceEndpoint.async_client`] qui return respectivement un objet [`InferenceClient`] et [`AsyncInferenceClient`] [[autodoc]] InferenceEndpoint - from_raw From d492923560fd6380079d7bdc6e18bf838744d4f0 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Tue, 12 Dec 2023 18:50:55 +0100 Subject: [PATCH 015/129] Fixed a few errors in the translation --- docs/source/fr/_toctree.yml | 10 ++--- docs/source/fr/concepts/git_vs_http.md | 15 ++++--- docs/source/fr/guides/cli.md | 40 +++++++++---------- docs/source/fr/index.md | 12 +++--- docs/source/fr/installation.md | 30 +++++++------- docs/source/fr/package_reference/community.md | 2 +- .../fr/package_reference/inference_client.md | 4 +- .../package_reference/inference_endpoints.md | 17 ++++---- docs/source/fr/quick-start.md | 16 ++++---- 9 files changed, 71 insertions(+), 75 deletions(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index cd25b21803..d055e2adfc 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -11,21 +11,21 @@ - local: guides/overview title: Vue d'ensemble - local: guides/download - title: Télécharger les fichiers + title: Télécharger des fichiers - local: guides/upload - title: Charger les fichiers + title: Upload des fichiers - local: guides/cli - title: Utiliser l'invite de commande + title: Utiliser le CLI - local: guides/hf_file_system title: HfFileSystem - local: guides/repository - title: Repository + title: Dépôts - local: guides/search title: Rechercher - local: guides/inference title: Inférence - local: guides/inference_endpoints - title: Endpoint d'Inférence + title: Inference Endpoints - local: guides/community title: Community Tab - local: guides/collections diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index e5a6d4091c..d038138c22 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -9,8 +9,7 @@ qui est une collection de dépots Git (modèles, datasets ou espaces). Il y a deux manières principales pour accéder au Hub en utilisant `huggingface_hub`. La première approche, basée sur Git, appelée approche "git-based", est rendue possible par la classe [`Repository`]. -Cette méthode utilise un wrapper autour de la commande `git` avec des fonctionnalités supplémentaires conçues pour intéragir avec le Hub. La deuxième option, appelée approche "HTTP-based" , -nécessite de faire des requêtes HTTP en utilisant le client [`HfApi`]. Éxaminions +Cette méthode utilise un wrapper autour de la commande `git` avec des fonctionnalités supplémentaires conçues pour intéragir avec le Hub. La deuxième option, appelée approche "HTTP-based" , nécessite de faire des requêtes HTTP en utilisant le client [`HfApi`]. Éxaminions les avantages et les inconvénients de ces deux méthodes. ## Repository: L'approche hstorique basée sur git @@ -19,16 +18,16 @@ Au début, `huggingface_hub` était principalement construit autour de la classe wrappers Python pour les commandes `git` usuelles, telles que `"git add"`, `"git commit"`, `"git push"`, `"git tag"`, `"git checkout"`, etc. -Cette librairie permet aussi de définir les données d'identification et de suivre les fichiers volumineux, qui sont souvent utilisés dans les dépot Git de machine learning. De plus, la librairie vous permet d'exécuter ses +Cette librairie permet aussi de définir les données d'identification et de suivre les fichiers volumineux, qui sont souvent utilisés dans les dépôts Git de machine learning. De plus, la librairie vous permet d'exécuter ses méthodes en arrière-plan, ce qui la rend utile pour upload des données pendant l'entrainement des modèles. L'avantage principal de l'utilisation de [`Repository`] est que cette méthode permet de garder une copie en local de tout le dépot Git sur votre machine. Cela peut aussi devenir un désavantage, car cette copie locale doit être mise à jour et maintenue constamment. C'est une manière de procéder -analogue au développement de logiciel traditionnel où chaque développeur maintient sa propre copie locale -et push les changement lorsqu'ils travaillent sur une fonctionnalité. -Toutefois, dans le contexte du machine learning, -elle n'est pas toujours pertinente car les utilisateurs ont parfois uniquement besoin d'avoir +analogue au développement de logiciel classique où chaque développeur maintient sa propre copie locale +et push les changement lorsqu'il travaille sur une fonctionnalité. +Toutefois, dans le contexte du machine learning, elle n'est pas toujours pertinente car +les utilisateurs ont parfois uniquement besoin d'avoir les poids des modèles pour l'inférence ou de convertir ces poids d'un format à un autre sans avoir à cloner tout le dépôt. @@ -48,7 +47,7 @@ telles que le téléchargement et le push de fichier ainsi que la création de b avoir besoin d'un fichier local qui doit être constamment synchronisé. En plus des fonctionnalités déjà fournies par `git`, La classe [`HfApi`] offre des fonctionnalités -additionnelles, telles que la capacité de gérer des dépots, le téléchargement des fichiers +additionnelles, telles que la capacité de gérer des dépôts, le téléchargement des fichiers en utilisant le cache pour une réutilisation plus efficace, la recherche dans le Hub pour trouver des dépôts et des métadonnées, l'accès aux fonctionnalités de communautés telles que, les dicussions, les pull requests, les commentaires, et la configuration d'espaces hardwares et de secrets. diff --git a/docs/source/fr/guides/cli.md b/docs/source/fr/guides/cli.md index 771ea2f4cc..51a89a5fc2 100644 --- a/docs/source/fr/guides/cli.md +++ b/docs/source/fr/guides/cli.md @@ -4,7 +4,7 @@ rendered properly in your Markdown viewer. # Invite de commande (CLI) -Le module Python `huggingface_hub` offre un CLI intégré appelé `huggingface-cli`. Cet outil vous permet d'intéragir directement avec le Hub Hugging +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 et 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. @@ -20,7 +20,7 @@ Tout d'abord, installons le CLI: -Dans les snippet ci dessus, nous avons aussi installé les dépendances `[cli]` pour rendre l'expérience utilisateur meilleur, en particulier lors de +Dans les snippet ci dessus, nous avons aussi installé les dépendances `[cli]` pour rendre l'expérience utilisateur meilleure, en particulier lors de l'utilisation de la commande `delete-cache`. @@ -64,7 +64,7 @@ CLI. ## Connexion à huggingface-cli Dans la plupart des cas, vous devez être connectés à un compte Hugging Face pour intéragir avec le Hub (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) depuis vos [paramètres](https://huggingface.co/settings/tokens). Ce token est utilisé pour authentifier votre identité au Hub. +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) 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 : @@ -94,7 +94,7 @@ Login successful ``` Alternativement, si vous souhaitez vous connecter sans que le CLI vous demande quoi que ce soit, vous pouvez mettre votre token directement depuis -l'invite de commande. Pour que le processus soit plus sécurisé, nous vous recommandons de mettre votre token en tant que variable d'environnement +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 @@ -122,12 +122,12 @@ Si vous n'êtes pas connecté, un message d'erreur sera renvoyé. Cette commande vous déconecte. 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 [reference](../package_reference/environment_variables#hftoken)). Si c'est le cas, vous devez désactiver la variable dans les paramètres de 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 interne, cette commande utilise -les mêmes helpers [`hf_hub_download`] et [`snapshot_download`] Décrit dans le guide [Téléchargement](./download) et affiche le chemin +les mêmes helpers [`hf_hub_download`] et [`snapshot_download`] décrits dans le guide [Téléchargement](./download) et affiche le chemin retourné 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: @@ -162,7 +162,7 @@ Fetching 23 files: 0%| | 0/23 [ ### Télécharger plusieurs fichiers -Vous pouvez aussi télécharger un sous ensemble des fichiers d'un dépôts en une seule commande. Vous pouvez faire ceci de deux manières. Si vous avez +Vous pouvez aussi télécharger un sous ensemble des fichiers d'un dépôt en une seule commande. Vous pouvez faire ceci de deux manières. Si vous avez déjà une liste précise des fichiers à télécharger, vous pouvez simplement les mettre un par un: ```bash @@ -201,7 +201,7 @@ l'option `--repo-type`: ... ``` -### Télécgarger une version spécifique +### 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`: @@ -213,8 +213,7 @@ nom de la branche ou tag), utilisez l'option `revision`: ### 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 les déplacer dans un dossier spécifique. C'est utile pour avoir un fonctionnement similaire à celui de git. Vous pouvez faire ceci en utilisant l'option `--local_dir`. +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 les déplacer dans un dossier spécifique. C'est utile pour avoir un fonctionnement similaire à celui de git. Vous pouvez faire ceci en utilisant l'option `--local_dir`. @@ -262,7 +261,7 @@ et des barres de progression. Si vous ne voulez pas de ce type de message, utili ## huggingface-cli upload Utilisez la commande `huggingface-cli upload` pour uploader des fichiers directement dans le Hub. En interne, 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. +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 @@ -274,14 +273,14 @@ Pour une liste exhaustive des options disponibles, vous pouvez lancer: L'utilisation par défaut de cette commande est: ```bash -# Usage: huggingface-cli upload [repo_id] [local_path] [path_in_repo] +# Utilisation: huggingface-cli upload [repo_id] [local_path] [path_in_repo] ``` Pour upload le chemin courant dans la racine du dépôts, utilisez: ```bash >>> huggingface-cli upload mon-super-modele . . -https://huggingface.co/Wauplin/my-cool-model/tree/main/ +https://huggingface.co/Wauplin/mon-super-modele/tree/main/ ``` @@ -294,18 +293,18 @@ Vous pouvez aussi upload un dossier spécifique: ```bash >>> huggingface-cli upload mon-super-modele ./models . -https://huggingface.co/Wauplin/my-cool-model/tree/main/ +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/my-cool-model/tree/main/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 `loca_path` pour qu'il pointe vers ce fichier dans votre machine. Si c'est le cas, `path_in_repo` est optionnel +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 @@ -322,11 +321,10 @@ 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 l'espace local en supprimant les fichiers distant et en uploadant tous les fichiers sauf ceux dans `/logs`: +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 l'espace local en supprimant les fichiers distant et en uploadant tous les fichiers sauf ceux dans `/logs`: ```bash -# Sync local Space with Hub (upload new files except from logs/, delete removed files) +# Synchronisation de l'espace 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 de l'espace local avec le Hub" ... ``` @@ -433,11 +431,11 @@ Pour plus de détails sur comment scanner le chemin vers votre cache, veuillez v ## huggingface-cli delete-cache -`huggingface-cli delete-cache` is a tool that helps you delete parts of your cache that you don't use anymore. This is useful for saving and freeing disk space. To learn more about using this command, please refer to the [Manage your cache](./manage-cache#clean-cache-from-the-terminal) guide. +`huggingface-cli delete-cache` est un outil qui vous permet de supprimer des parties de votre cache que vous n'utilisez plus. C'est utile pour 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 issu sur [GitHub](https://github.com/huggingface/huggingface_hub) pour aider les mainteneurs à enquêter sur vos problèmes. +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 diff --git a/docs/source/fr/index.md b/docs/source/fr/index.md index 5258eaa74a..15ea3b9c8b 100644 --- a/docs/source/fr/index.md +++ b/docs/source/fr/index.md @@ -7,13 +7,13 @@ rendered properly in your Markdown viewer. La librairie `huggingface_hub` vous permet d'intéragir avec le [Hub Hugging Face](https://hf.co), une plateforme de machine learning pour les créateurs et les collaborateurs. Découvrez des modèles pré- -entraineés et des datasets pour vos projets ou jouez avec des centraines -d'application machine learning hébergées sur le Hub. Vous pouvez aussi +entrainés et des datasets pour vos projets ou jouez avec des centraines +d'applications machine learning hébergées sur le Hub. Vous pouvez aussi créer et partager vos propres modèles et datasets avec la communauté. La librairie `huggingface_hub` offre une manière simple de faire toutes ces choses avec Python. -Lisez le [quick start guide](quick-start) pour vous lancer avec la librairie +Lisez le [guide de démarrage rapide](quick-start) pour vous lancer avec la librairie `huggingface_hub`. Vous apprendrez à télécharger des fichiers depuis le Hub, à créer un dépôt et upload des fichiers dans le Hub. Continuez à lire pour apprendre le management de dépôt sur le Hub 🤗, comment intéragir avec les discussions @@ -28,7 +28,7 @@ ou même comment accéder à l'API d'inférence. -
Référence
+
Références

Description exhaustive et technique des classes et méthodes huggingface_hub.

 @@ -48,11 +48,11 @@ ou même comment accéder à l'API d'inférence. ## Contributions -Toutes les contributions à `huggingface_hub` sont les bienvenues, nous le valorisons toutes +Toutes les contributions à `huggingface_hub` sont les bienvenues, nous les valorisons toutes à la même hauteur. 🤗 Hormis l'ajout ou la correction de problèmes dans le code, vous pouvez aussi aider à améliorer la documentation en vérifiant qu'elle est exacte et à jour, répondre à des questions sur des issues, et demander de nouvelles fonctionnalités -qui amélioreront la librairie. Regardez le [guide de contribution](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) +qui amélioreront la librairie. Regardez le [guide de contributions](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) pour en savoir plus sur comment lancer une nouvelle issue ou une demande de nouvelle fonctionnalité, comment faire un pull request et comment tester vos contributions pour vérifier que tout fonctionne comme prévu. diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 528898039b..e10ab06b17 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -7,12 +7,12 @@ rendered properly in your Markdown viewer. Avant de commmencer l'installation, vous allez avoir besoin de préparer votre environnement en installant les packages appropriés. -`huggingface_hub` est testé sur **Python 3.8+**. +`huggingface_hub` est testée sur **Python 3.8+**. ## Installation avec pip Il est fortement recommandé d'installer `huggingface_hub` dans un [environnement virtuel](https://docs.python.org/3/library/venv.html). -Si vous êtes familier avec les environnements virtuels python, regardez plutôt ce [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Un environnement virtuel sera utile lorsque vous devrez gérer des projets différents +Si vous êtes familier avec les environnements virtuels Python, regardez plutôt ce [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Un environnement virtuel sera utile lorsque vous devrez gérer des projets différents et éviter les problèmes de compatibilité entre les différetnes dépendances. Commencez par créer un environnement virtuel dans le chemin de votre projet: @@ -33,7 +33,7 @@ Activez l'environnement virtuel sur Windows: .env/Scripts/activate ``` -Maintenant, vous êtes prêts à installer `hugginface_hub` [depuis PyPi ](https://pypi.org/project/huggingface-hub/): +Maintenant, vous êtes prêts à installer `hugginface_hub` [depuis PyPi](https://pypi.org/project/huggingface-hub/): ```bash pip install --upgrade huggingface_hub @@ -58,22 +58,22 @@ pip install 'huggingface_hub[cli,torch]' Voici une liste des dépendances optionnelles dans `huggingface_hub`: - `cli` fournit une interface d'invite de commande plus pratique pour `huggingface_hub`. -- `fastai`, `torch` et `tensorflow` sont des dépendances pour utiliser des fonctionnalités spécifique à un framework. +- `fastai`, `torch` et `tensorflow` sont des dépendances pour utiliser des fonctionnalités spécifiques à un framework. - `dev` permet de contribuer à la librairie. Cette dépendance inclut `testing` (pour lancer des tests), `typing` (pour lancer le vérifieur de type) et `quality` (pour lancer des linters). ### Installation depuis la source -Dans certains cas, il est intéressant d'installer `huggingface_hub` directement depuis la source. +Dans certains cas, il est intéressant d'installer `huggingface_hub` directement depuis le code source. Ceci vous permet d'utiliser la version `main`, contenant les dernières mises à jour, plutôt que d'utiliser la dernière version stable. La version `main` est utile pour rester à jour sur les derniers développements, par exemple si un bug est réglé depuis la dernière sortie officielle mais que la nouvelle sortie n'a pas encore été faite. -Toutefois, cela signifie que la version `main` pourrait ne pas stable. Nous travaillons +Toutefois, cela signifie que la version `main` pourrait ne pas être stable. Nous travaillons afin de rendre la version `main` optionnelle, et la pluspart des problèmes sont résolus -en quelques heure ou en une journée. Si vous avez un problème, ouvrez une Issue afin que +en quelques heure ou en une journée. Si vous avez un problème, ouvrez une issue afin que nous puissions la régler encore plus vite ! ```bash @@ -88,7 +88,7 @@ nouveau bug-fix qui n'a pas encore été merge: pip install git+https://github.com/huggingface/huggingface_hub@ma-branche ``` -Une fois fini, [vérifiez l'installation](#check-installation). +Une fois finie, [vérifiez l'installation](#check-installation). ### Installation éditable @@ -107,7 +107,7 @@ pip install -e . Ces commandes lieront le dossier dans lequel vous avez cloné le dépôt et vos chemins de librairies Python. Python regardera maintenant à l'intérieur du dossier dans lequel vous avez cloné le dépôt en plus des chemins de librairie classiques. Par exemple, si vos packages Python sont installés dans -`./.venv/lib/python3.11/site-packages/`, Python regardera uassi dans le dossier que vous avez +`./.venv/lib/python3.11/site-packages/`, Python regardera aussi dans le dossier que vous avez cloné `./huggingface_hub/`. ## Installation avec conda @@ -119,11 +119,11 @@ Si vous avez plutôt l'habitude d'utiliser conda, vous pouvez installer `hugging conda install -c conda-forge huggingface_hub ``` -Une fois fini, [vérifiez l'installation](#check-installation). +Une fois finie, [vérifiez l'installation](#check-installation). ## Vérification de l'installation -Une fois installé, vérifiez que `huggingface_hub` marche correctement en lançant la commande suivante: +Une fois installée, vérifiez que `huggingface_hub` marche correctement en lançant la commande suivante: ```bash python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" @@ -141,8 +141,8 @@ Task: text-generation ## Les limitations Windows Afin de démocratiser le machine learning pour tous, nous avons construit `huggingface_hub` -de façon à voir une librairie cross-platform et en particulier, une librairie qui marche -sur les systèmes Windows et ceux basés sur Unix. Toutefois il y a certains cas où +de façon à avoir une librairie cross-platform et en particulier, une librairie qui marche +sur tous les systèmes d'exploitation. Toutefois il y a certains cas où `huggingface_hub` est plus limité lorsqu'il tourne sur Windows. Ci-dessous une liste exhaustive des problèmes connus. N'hésitez pas à nous signaler si vous rencontrez un problème sans documentation en ouvrant une [issue sur Github](https://github.com/huggingface/huggingface_hub/issues/new/choose). @@ -150,11 +150,11 @@ sans documentation en ouvrant une [issue sur Github](https://github.com/huggingf - Le cache de `huggingface_hub` a besoin des symlinks pour mettre en cache les fichiers installé depuis le Hub. Sur windows, vous devez activer le mode développeur pour lancer votre script en tant qu'administrateur afin d'activer les symlinks. S'il ne sont pas activés, le système de cache fonctionnera toujours mais -de manière suboptimale. Consultez [limitations du cache](./guides/manage-cache#limitations) pour plus de détails. +de manière suboptimale. Consultez les [limitations du cache](./guides/manage-cache#limitations) pour plus de détails. - Les chemins de fichiers sur le Hub peuvent avoir des caractères spéciaux (par exemple `"path/to?/my/file"`). Windows est plus restrictif sur les [caractères spéciaux](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) ce qui rend ces fichiers ininstallables sur Windows. Heureusement c'est un cas assez rare. -Contactez le propriétaire du dépôt sir vous pensez que c'est une erreur ou contactez nous +Contactez le propriétaire du dépôt si vous pensez que c'est une erreur ou contactez nous pour que nous cherchions une solution. diff --git a/docs/source/fr/package_reference/community.md b/docs/source/fr/package_reference/community.md index ad5571e905..799a861b76 100644 --- a/docs/source/fr/package_reference/community.md +++ b/docs/source/fr/package_reference/community.md @@ -2,7 +2,7 @@ rendered properly in your Markdown viewer. --> -# Interagir avec les dicussions et les pull requestions +# Interagir avec les dicussions et les pull requests Regardez la page de documentation [`HfApi`] pour les références des méthodes permettant l'intéraction avec des pull requests et des discussions sur le Hub. diff --git a/docs/source/fr/package_reference/inference_client.md b/docs/source/fr/package_reference/inference_client.md index efebde11ad..8932918377 100644 --- a/docs/source/fr/package_reference/inference_client.md +++ b/docs/source/fr/package_reference/inference_client.md @@ -8,7 +8,7 @@ L'inférence est le fait d'utiliser un modèle déjà entrainé pour faire des p 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ée +- [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. @@ -69,7 +69,7 @@ Pour la plupart des tâches, la valeur retournée a un type intégré (string, l ### Types pour la génération de texte La tâche [`~InferenceClient.text_generation`] a un meilleur support que d'autres tâches dans `InferenceClient`. -Plus précisément, les inputs des utilisateurs et les outputs des serveurs sont validés en utilisant [Pydantic](https://docs.pydantic.dev/latest/) +Les inputs des utilisateurs et les outputs des serveurs sont validés en utilisant [Pydantic](https://docs.pydantic.dev/latest/) si ce package est installé. Par conséquent, nous vous recommandons de l'installer (`pip install pydantic`) pour une meilleure expérience. diff --git a/docs/source/fr/package_reference/inference_endpoints.md b/docs/source/fr/package_reference/inference_endpoints.md index 739f1fd39b..b8300670d2 100644 --- a/docs/source/fr/package_reference/inference_endpoints.md +++ b/docs/source/fr/package_reference/inference_endpoints.md @@ -1,31 +1,30 @@ # Inference Endpoints -Inferrence Endpoints est une solutions permettant de déployer facilement les modèles en production sur une infrastructure dédiée et capaable de faire de l'autoscaling gérée par Hugging Face. Un Inference Endpoint peut être crée sur un modèle depuis le [Hub](https://huggingface.co/models). Cette page est -une référence pour l'intégration d'`huggingface_hub` avec Inference Endpoints. Pour plus d'informations à propos du produit Inference Endpoints, consulez -la [documentation officielle](https://huggingface.co/docs/inference-endpoints/index). +Inferrence Endpoints est une solution permettant de déployer facilement les modèles en production sur une infrastructure gérée par Hugging Face et capable d'autoscaling . Un Inference Endpoint peut être crée sur un modèle depuis le [Hub](https://huggingface.co/models). Cette page est +une référence pour l'intégration d'`huggingface_hub` avec Inference Endpoints. Pour plus d'informations à propos du produit Inference Endpoints, consultez la [documentation officielle](https://huggingface.co/docs/inference-endpoints/index). -Consultez ce [guide](../guides/inference_endpoints) pour apprendre comment utiliser `huggingface_hub` pour gérer votre Inference Enpoints depuis le code. +Consultez ce [guide](../guides/inference_endpoints) pour apprendre à utiliser `huggingface_hub` pour gérer votre Inference Enpoints depuis le code. -Inference Endpoints peut-être complètement géré depuis une API. Les enpoints sont consultables via [Swagger](https://api.endpoints.huggingface.cloud/). +Inference Endpoints peut être entièrement géré depuis une API. Les endpoints sont consultables via [Swagger](https://api.endpoints.huggingface.cloud/). La classe [`InferenceEndpoint`] est un simple wrapper autour de cette API. ## Méthodes Un sous ensemble des fonctionnalités de l'Inference Endpoint sont implémentées dans [`HfApi`]: -- [`get_inference_endpoint`] et [`list_inference_endpoints`] pour obtenir de l'information sur votre Inference Endpoints -- [`create_inference_endpoint`], [`update_inference_endpoint`] et [`delete_inference_endpoint`] pour déployer et gérer Inference Endpoints +- [`get_inference_endpoint`] et [`list_inference_endpoints`] pour obtenir de l'information sur vos Inference Endpoints +- [`create_inference_endpoint`], [`update_inference_endpoint`] et [`delete_inference_endpoint`] pour déployer et gérer les Inference Endpoints - [`pause_inference_endpoint`] et [`resume_inference_endpoint`] pour mettre en pause et relancer un Inference Enpoint - [`scale_to_zero_inference_endpoint`] pour scale à la main l'Inference Endpoint à 0 replicas ## InferenceEndpoint -La dataclass principale est [`InferenceEndpoint`]. Elle contient des informations sur un `InferenceEndpoint` déployé, incluant sa configuration et son -état actuel. Une fois déployé, vous pouvez faire des inférences sur l'enpoint en utilisant les propriétés [`InferenceEndpoint.client`] et [`InferenceEndpoint.async_client`] qui return respectivement un objet [`InferenceClient`] et [`AsyncInferenceClient`] +La dataclass principale est [`InferenceEndpoint`]. Elle contient des informations sur un `InferenceEndpoint` déployé, notamment sa configuration et son +état actuel. Une fois déployé, vous pouvez faire des inférences sur l'enpoint en utilisant les propriétés [`InferenceEndpoint.client`] et [`InferenceEndpoint.async_client`] qui retournent respectivement un objet [`InferenceClient`] et [`AsyncInferenceClient`] [[autodoc]] InferenceEndpoint - from_raw diff --git a/docs/source/fr/quick-start.md b/docs/source/fr/quick-start.md index 603d6c61b4..bf3cfb7821 100644 --- a/docs/source/fr/quick-start.md +++ b/docs/source/fr/quick-start.md @@ -5,7 +5,7 @@ rendered properly in your Markdown viewer. # Démarrage rapide Le [Hub Hugging Face](https://huggingface.co/) est le meilleur endroit pour partager des -modèles de machine learning, des démos, des datasets et des metriques. La librairie +modèles de machine learning, des démos, des datasets et des métriques. La librairie `huggingface_hub` vous aide à intéragir avec le Hub sans sortir de votre environnement de développement. Vous pouvez: créer et gérer des dépôts facilement, télécharger et upload des fichiers, et obtenir des modèles et des metadata depuis le Hub. @@ -18,12 +18,12 @@ Pour commencer, installez la librairie `huggingface_hub`: pip install --upgrade huggingface_hub ``` -Pour plus de détails, vérifiez le guide [installation](installation) +Pour plus de détails, vérifiez le guide d'[installation](installation) ## Télécharger des fichiers Les dépôts sur le Hub sont sous controle de version Git, et les utilisateurs peuvent -télécharger un fichier, ou dépôt entier. Vous pouvez utiliser la fonction [`hf_hub_download`] +télécharger un fichier, ou un dépôt entier. Vous pouvez utiliser la fonction [`hf_hub_download`] pour télécharger des fichiers. Cette fonction télécharger et mettra dans le cache un fichier sur votre disque local. La prochaine fois que vous aurez besoin de ce fichier, il sera chargé depuis votre cache de façon à ce que vous n'ayez pas besoin de le retélécharger. @@ -58,8 +58,8 @@ Dans la plupart des cas, vous devez être connectés avec un compte Hugging Face avec le Hub: pour télécharger des dépôts privés, upload des fichiers, créer des pull requests... [Créez un compte](https://huggingface.co/join) si vous n'en avez pas déjà un et connectez -vous pour obtenir votre [Token d'Authentification](https://huggingface.co/docs/hub/security-tokens) -depuis vos [Paramètres](https://huggingface.co/settings/tokens). Le token +vous pour obtenir votre [token d'authentification](https://huggingface.co/docs/hub/security-tokens) +depuis vos [paramètres](https://huggingface.co/settings/tokens). Le token est utilisé pour authentifier votre identité au Hub. Une fois que vous avez votre token d'authentification, lancez la commande suivante @@ -67,7 +67,7 @@ dans votre terminal: ```bash huggingface-cli login -# or using an environment variable +# ou en utilisant une varible d'environnement: huggingface-cli login --token $HUGGINGFACE_TOKEN ``` @@ -123,7 +123,7 @@ Les dépôts privés ne seront visible que par vous. Pour créer un dépôt ou push du contenu sur le Hub, vous devez fournir un token d'authentification qui a les permissions `write`. Vous pouvez choisir la permission -lorsque vous créez le token dans vos [Paramètres](https://huggingface.co/settings/tokens). +lorsque vous générez le token dans vos [paramètres](https://huggingface.co/settings/tokens). @@ -146,7 +146,7 @@ Vous devez spécifier: ... ) ``` -Pour upload plus d'un fichier à la fois, consultez le guide [Upload](./guides/upload) +Pour upload plus d'un fichier à la fois, consultez le guide [upload](./guides/upload) qui vous expliqueras plusieurs méthodes pour upload des fichiers (avec ou sans Git). ## Prochaines étapes From 1127be0fb3d9ad0d4541d7d2f9cbbfc4771d2244 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Wed, 13 Dec 2023 20:00:44 +0100 Subject: [PATCH 016/129] Translated integrations.md --- docs/source/fr/guides/integrations.md | 265 +++++++++++++------------- 1 file changed, 135 insertions(+), 130 deletions(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 87575a4e8a..3a8b6a93d9 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -2,48 +2,52 @@ rendered properly in your Markdown viewer. --> -# Integrate any ML framework with the Hub - -The Hugging Face Hub makes hosting and sharing models with the community easy. It supports -[dozens of libraries](https://huggingface.co/docs/hub/models-libraries) in the Open Source ecosystem. We are always -working on expanding this support to push collaborative Machine Learning forward. The `huggingface_hub` library plays a -key role in this process, allowing any Python script to easily push and load files. - -There are four main ways to integrate a library with the Hub: -1. **Push to Hub:** implement a method to upload a model to the Hub. This includes the model weights, as well as - [the model card](https://huggingface.co/docs/huggingface_hub/how-to-model-cards) and any other relevant information - or data necessary to run the model (for example, training logs). This method is often called `push_to_hub()`. -2. **Download from Hub:** implement a method to load a model from the Hub. The method should download the model - configuration/weights and load the model. This method is often called `from_pretrained` or `load_from_hub()`. -3. **Inference API:** use our servers to run inference on models supported by your library for free. -4. **Widgets:** display a widget on the landing page of your models on the Hub. It allows users to quickly try a model - from the browser. - -In this guide, we will focus on the first two topics. We will present the two main approaches you can use to integrate -a library, with their advantages and drawbacks. Everything is summarized at the end of the guide to help you choose -between the two. Please keep in mind that these are only guidelines that you are free to adapt to you requirements. - -If you are interested in Inference and Widgets, you can follow [this guide](https://huggingface.co/docs/hub/models-adding-libraries#set-up-the-inference-api). -In both cases, you can reach out to us if you are integrating a library with the Hub and want to be listed -[in our docs](https://huggingface.co/docs/hub/models-libraries). - -## A flexible approach: helpers - -The first approach to integrate a library to the Hub is to actually implement the `push_to_hub` and `from_pretrained` -methods by yourself. This gives you full flexibility on which files you need to upload/download and how to handle inputs -specific to your framework. You can refer to the two [upload files](./upload) and [download files](./download) guides -to learn more about how to do that. This is, for example how the FastAI integration is implemented (see [`push_to_hub_fastai`] -and [`from_pretrained_fastai`]). - -Implementation can differ between libraries, but the workflow is often similar. +# 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 -This is how a `from_pretrained` method usually look like: +Voici comment une méthode `from_pretrained` fonctionne d'habitude: ```python def from_pretrained(model_id: str) -> MyModelClass: - # Download model from Hub + # Téléchargement du modèles depuis le Hub cached_model = hf_hub_download( repo_id=repo_id, filename="model.pkl", @@ -51,120 +55,120 @@ def from_pretrained(model_id: str) -> MyModelClass: library_version=get_fastai_version(), ) - # Load model + # Chargement du modèle return load_model(cached_model) ``` ### push_to_hub -The `push_to_hub` method often requires a bit more complexity to handle repo creation, generate the model card and save weights. -A common approach is to save all of these files in a temporary folder, upload it and then delete it. +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() - # Create repo if not existing yet and get the associated repo_id + # 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) - # Save all files in a temporary directory and push them in a single commit + # Sauvegardez tous les fichiers dans un chemin temporaire, et pushez les en un seul commit with TemporaryDirectory() as tmpdir: tmpdir = Path(tmpdir) - # Save weights + # Sauvegardez les poids save_model(model, tmpdir / "model.safetensors") - # Generate model card + # Générez le chemin du modèle card = generate_model_card(model) (tmpdir / "README.md").write_text(card) - # Save logs - # Save figures - # Save evaluation metrics + # Sauvegardez les logs + # Sauvegardez le métriques d'évaluation # ... - # Push to hub + # Pushez vers le Hub return api.upload_folder(repo_id=repo_id, folder_path=tmpdir) ``` -This is of course only an example. If you are interested in more complex manipulations (delete remote files, upload -weights on the fly, persist weights locally, etc.) please refer to the [upload files](./upload) guide. +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 -While being flexible, this approach has some drawbacks, especially in terms of maintenance. Hugging Face users are often -used to additional features when working with `huggingface_hub`. For example, when loading files from the Hub, it is -common to offer parameters like: -- `token`: to download from a private repo -- `revision`: to download from a specific branch -- `cache_dir`: to cache files in a specific directory -- `force_download`/`resume_download`/`local_files_only`: to reuse the cache or not -- `api_endpoint`/`proxies`: configure HTTP session - -When pushing models, similar parameters are supported: -- `commit_message`: custom commit message -- `private`: create a private repo if missing -- `create_pr`: create a PR instead of pushing to `main` -- `branch`: push to a branch instead of the `main` branch -- `allow_patterns`/`ignore_patterns`: filter which files to upload +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` - ... -All of these parameters can be added to the implementations we saw above and passed to the `huggingface_hub` methods. -However, if a parameter changes or a new feature is added, you will need to update your package. Supporting those -parameters also means more documentation to maintain on your side. To see how to mitigate these limitations, let's jump -to our next section **class inheritance**. +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**. -## A more complex approach: class inheritance +## Une approche plus complexe: class inheritance -As we saw above, there are two main methods to include in your library to integrate it with the Hub: upload files -(`push_to_hub`) and download files (`from_pretrained`). You can implement those methods by yourself but it comes with -caveats. To tackle this, `huggingface_hub` provides a tool that uses class inheritance. Let's see how it works! +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 ! -In a lot of cases, a library already implements its model using a Python class. The class contains the properties of -the model and methods to load, run, train, and evaluate it. Our approach is to extend this class to include upload and -download features using mixins. A [Mixin](https://stackoverflow.com/a/547714) is a class that is meant to extend an -existing class with a set of specific features using multiple inheritance. `huggingface_hub` provides its own mixin, -the [`ModelHubMixin`]. The key here is to understand its behavior and how to customize it. +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. -The [`ModelHubMixin`] class implements 3 *public* methods (`push_to_hub`, `save_pretrained` and `from_pretrained`). Those -are the methods that your users will call to load/save models with your library. [`ModelHubMixin`] also defines 2 -*private* methods (`_save_pretrained` and `_from_pretrained`). Those are the ones you must implement. So to integrate -your library, you should: +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. Make your Model class inherit from [`ModelHubMixin`]. -2. Implement the private methods: - - [`~ModelHubMixin._save_pretrained`]: method taking as input a path to a directory and saving the model to it. - You must write all the logic to dump your model in this method: model card, model weights, configuration files, - training logs, and figures. Any relevant information for this model must be handled by this method. - [Model Cards](https://huggingface.co/docs/hub/model-cards) are particularly important to describe your model. Check - out [our implementation guide](./model-cards) for more details. - - [`~ModelHubMixin._from_pretrained`]: **class method** taking as input a `model_id` and returning an instantiated - model. The method must download the relevant files and load them. -3. You are done! +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! -The advantage of using [`ModelHubMixin`] is that once you take care of the serialization/loading of the files, you -are ready to go. You don't need to worry about stuff like repo creation, commits, PRs, or revisions. All -of this is handled by the mixin and is available to your users. The Mixin also ensures that public methods are well -documented and type annotated. +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é. -### A concrete example: PyTorch +### Un exemple concret: PyTorch -A good example of what we saw above is [`PyTorchModelHubMixin`], our integration for the PyTorch framework. This is a -ready-to-use integration. +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. -#### How to use it? +#### Comment l'utiliser ? -Here is how any user can load/save a PyTorch model from/to the Hub: +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. Define your Pytorch model exactly the same way you are used to ->>> class MyModel(nn.Module, PyTorchModelHubMixin): # multiple inheritance +# 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)) @@ -174,21 +178,21 @@ Here is how any user can load/save a PyTorch model from/to the Hub: ... return self.linear(x + self.param) >>> model = MyModel() -# 2. (optional) Save model to local directory +# 2. (optionnel) Sauvegarder le modèle dans un chemin local >>> model.save_pretrained("path/to/my-awesome-model") -# 3. Push model weights to the Hub +# 3. Pushez les poids du modèle vers le Hub >>> model.push_to_hub("my-awesome-model") -# 4. Initialize model from the Hub +# 4. initialisez le modèle depuis le Hub >>> model = MyModel.from_pretrained("username/my-awesome-model") ``` -#### Implementation +#### Implémentation -The implementation is actually very straightforward, and the full implementation can be found [here](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py). +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. First, inherit your class from `ModelHubMixin`: +1. Premièrement, faites hériter votre classe de `ModelHubMixin`: ```python from huggingface_hub import ModelHubMixin @@ -197,7 +201,7 @@ class PyTorchModelHubMixin(ModelHubMixin): (...) ``` -2. Implement the `_save_pretrained` method: +2. Implémentez la méthode `_save_pretrained`: ```py from huggingface_hub import ModelCard, ModelCardData @@ -206,7 +210,7 @@ class PyTorchModelHubMixin(ModelHubMixin): (...) def _save_pretrained(self, save_directory: Path): - """Generate Model Card and save weights from a Pytorch model to a local directory.""" + """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', @@ -221,13 +225,13 @@ class PyTorchModelHubMixin(ModelHubMixin): torch.save(obj=self.module.state_dict(), f=save_directory / "pytorch_model.bin") ``` -3. Implement the `_from_pretrained` method: +3. Implémentez la méthode `_from_pretrained`: ```python class PyTorchModelHubMixin(ModelHubMixin): (...) - @classmethod # Must be a classmethod! + @classmethod # Doit absolument être une méthode de clase ! def _from_pretrained( cls, *, @@ -239,16 +243,16 @@ class PyTorchModelHubMixin(ModelHubMixin): resume_download: bool, local_files_only: bool, token: Union[str, bool, None], - map_location: str = "cpu", # additional argument - strict: bool = False, # additional argument + map_location: str = "cpu", # argument supplémentaire + strict: bool = False, # argument supplémentaire **model_kwargs, ): - """Load Pytorch pretrained weights and return the loaded model.""" - if os.path.isdir(model_id): # Can either be a local directory + """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: # Or a model on the Hub - model_file = hf_hub_download( # Download from the hub, passing same input args + 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, @@ -260,7 +264,7 @@ class PyTorchModelHubMixin(ModelHubMixin): local_files_only=local_files_only, ) - # Load model and return - custom logic depending on your framework + # 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) @@ -268,18 +272,19 @@ class PyTorchModelHubMixin(ModelHubMixin): return model ``` -And that's it! Your library now enables users to upload and download files to and from the Hub. +Et c'est fini ! Votre librairie permet maintenant aux utilisateurs d'upload et de télécharger des fichiers vers et depuis le Hub. -## Quick comparison +## Comparaison -Let's quickly sum up the two approaches we saw with their advantages and drawbacks. The table below is only indicative. -Your framework might have some specificities that you need to address. This guide is only here to give guidelines and -ideas on how to handle integration. In any case, feel free to contact us if you have any questions! +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 ! - -| Integration | Using helpers | Using [`ModelHubMixin`] | + +| Intégration | Utilisant des helpers | Utilisant [`ModelHubMixin`] | |:---:|:---:|:---:| -| User experience | `model = load_from_hub(...)`
`push_to_hub(model, ...)` | `model = MyModel.from_pretrained(...)`
`model.push_to_hub(...)` | -| Flexibility | Very flexible.
You fully control the implementation. | Less flexible.
Your framework must have a model class. | -| Maintenance | More maintenance to add support for configuration, and new features. Might also require fixing issues reported by users. | Less maintenance as most of the interactions with the Hub are implemented in `huggingface_hub`. | -| Documentation / Type annotation | To be written manually. | Partially handled by `huggingface_hub`. | \ No newline at end of file +| 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 From c12624a09b6c2908caa8148297ce6d20936a84a8 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Thu, 14 Dec 2023 23:29:08 +0100 Subject: [PATCH 017/129] Translated mana-cache.md. Did not find a good translfation for cache-system --- docs/source/fr/guides/manage-cache.md | 408 ++++++++++++++------------ 1 file changed, 217 insertions(+), 191 deletions(-) diff --git a/docs/source/fr/guides/manage-cache.md b/docs/source/fr/guides/manage-cache.md index aad3be96c8..fb96c3c24b 100644 --- a/docs/source/fr/guides/manage-cache.md +++ b/docs/source/fr/guides/manage-cache.md @@ -2,15 +2,15 @@ rendered properly in your Markdown viewer. --> -# Manage `huggingface_hub` cache-system +# Gérer le cache-system `huggingface_hub` -## Understand caching +## Comprendre le caching -The Hugging Face Hub cache-system is designed to be the central cache shared across libraries -that depend on the Hub. It has been updated in v0.8.0 to prevent re-downloading same files -between revisions. +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. -The caching system is designed as follows: +Le système de cache fonctionne comme suit: ``` @@ -19,11 +19,12 @@ The caching system is designed as follows: ├─ ``` -The `` is usually your user's home directory. However, it is customizable with the `cache_dir` argument on all methods, or by specifying either `HF_HOME` or `HF_HUB_CACHE` environment variable. +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`. -Models, datasets and spaces share a common root. Each of these repositories contains the -repository type, the namespace (organization or username) if it exists and the -repository name: +Les modèles, datasets et espaces 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: ``` @@ -35,12 +36,12 @@ repository name: ├─ spaces--dalle-mini--dalle-mini ``` -It is within these folders that all files will now be downloaded from the Hub. Caching ensures that -a file isn't downloaded twice if it already exists and wasn't updated; but if it was updated, -and you're asking for the latest file, then it will download the latest file (while keeping -the previous file intact in case you need it again). +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). -In order to achieve this, all folders contain the same skeleton: +Pour ce faire, tous les dossiers contiennent le même squelette: ``` @@ -51,87 +52,97 @@ In order to achieve this, all folders contain the same skeleton: ... ``` -Each folder is designed to contain the following: +Chaque dossier est fait pour contenir les dossiers suivants: ### Refs -The `refs` folder contains files which indicates the latest revision of the given reference. For example, -if we have previously fetched a file from the `main` branch of a repository, the `refs` -folder will contain a file named `main`, which will itself contain the commit identifier of the current head. +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. -If the latest commit of `main` has `aaaaaa` as identifier, then it will contain `aaaaaa`. +Si le dernier commit de `main` a pour identifier `aaaaaa`, alors le fichier dans ``refs` +contiendra `aaaaaa`. -If that same branch gets updated with a new commit, that has `bbbbbb` as an identifier, then -re-downloading a file from that reference will update the `refs/main` file to contain `bbbbbb`. +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 -The `blobs` folder contains the actual files that we have downloaded. The name of each file is their hash. +Le dossier `blobs` contient les fichiers que nous avons téléchargé. Le nom de chaque fichier est +son hash. ### Snapshots -The `snapshots` folder contains symlinks to the blobs mentioned above. It is itself made up of several folders: -one per known revision! +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! -In the explanation above, we had initially fetched a file from the `aaaaaa` revision, before fetching a file from -the `bbbbbb` revision. In this situation, we would now have two folders in the `snapshots` folder: `aaaaaa` -and `bbbbbb`. +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`. -In each of these folders, live symlinks that have the names of the files that we have downloaded. For example, -if we had downloaded the `README.md` file at revision `aaaaaa`, we would have the following path: +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 ``` -That `README.md` file is actually a symlink linking to the blob that has the hash of the file. +Ce fichier `README.md` est enfaite un symlink qui dirige vers le blob qui a le hash du fichier. -By creating the skeleton this way we open the mechanism to file sharing: if the same file was fetched in -revision `bbbbbb`, it would have the same hash and the file would not need to be re-downloaded. +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 (advanced) +### .no_exist (avancé) -In addition to the `blobs`, `refs` and `snapshots` folders, you might also find a `.no_exist` folder -in your cache. This folder keeps track of files that you've tried to download once but don't exist -on the Hub. Its structure is the same as the `snapshots` folder with 1 subfolder per known revision: +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_that_does_not_exist.json +//.no_exist/aaaaaa/config_inexistante.json ``` -Unlike the `snapshots` folder, files are simple empty files (no symlinks). In this example, -the file `"config_that_does_not_exist.json"` does not exist on the Hub for the revision `"aaaaaa"`. -As it only stores empty files, this folder is neglectable is term of disk usage. - -So now you might wonder, why is this information even relevant? -In some cases, a framework tries to load optional files for a model. Saving the non-existence -of optional files makes it faster to load a model as it saves 1 HTTP call per possible optional file. -This is for example the case in `transformers` where each tokenizer can support additional files. -The first time you load the tokenizer on your machine, it will cache which optional files exists (and -which doesn't) to make the loading time faster for the next initializations. - -To test if a file is cached locally (without making any HTTP request), you can use the [`try_to_load_from_cache`] -helper. It will either return the filepath (if exists and cached), the object `_CACHED_NO_EXIST` (if non-existence -is cached) or `None` (if we don't know). +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): - # file exists and is cached + # Le fichier existe et est dans le cache ... elif filepath is _CACHED_NO_EXIST: - # non-existence of file is cached + # La non-existence du fichier est dans le cache ... else: - # file is not cached + # Le fichier n'est pas dans le cache ... ``` -### In practice +### En pratique -In practice, your cache should look like the following tree: +En pratique, votre cache devrait ressembler à l'arbre suivant: ```text [ 96] . @@ -153,53 +164,58 @@ In practice, your cache should look like the following tree: ### Limitations -In order to have an efficient cache-system, `huggingface-hub` uses symlinks. However, -symlinks are not supported on all machines. This is a known limitation especially on -Windows. When this is the case, `huggingface_hub` do not use the `blobs/` directory but -directly stores the files in the `snapshots/` directory instead. This workaround allows -users to download and cache files from the Hub exactly the same way. Tools to inspect -and delete the cache (see below) are also supported. However, the cache-system is less -efficient as a single file might be downloaded several times if multiple revisions of -the same repo is downloaded. - -If you want to benefit from the symlink-based cache-system on a Windows machine, you -either need to [activate Developer Mode](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) -or to run Python as an administrator. - -When symlinks are not supported, a warning message is displayed to the user to alert -them they are using a degraded version of the cache-system. This warning can be disabled -by setting the `HF_HUB_DISABLE_SYMLINKS_WARNING` environment variable to true. - -## Caching assets - -In addition to caching files from the Hub, downstream libraries often requires to cache -other files related to HF but not handled directly by `huggingface_hub` (example: file -downloaded from GitHub, preprocessed data, logs,...). In order to cache those files, -called `assets`, one can use [`cached_assets_path`]. This small helper generates paths -in the HF cache in a unified way based on the name of the library requesting it and -optionally on a namespace and a subfolder name. The goal is to let every downstream -libraries manage its assets its own way (e.g. no rule on the structure) as long as it -stays in the right assets folder. Those libraries can then leverage tools from -`huggingface_hub` to manage the cache, in particular scanning and deleting parts of the -assets from a CLI command. +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" # Do anything you like in your assets folder ! +something_path = assets_path / "something.json" # Faites ce que vous voulez dans votre dossier d'assets ! ``` -[`cached_assets_path`] is the recommended way to store assets but is not mandatory. If -your library already uses its own cache, feel free to use it! +[`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! -### Assets in practice +### Les assets en pratique -In practice, your assets cache should look like the following tree: +En pratique, votre cache d'asset devrait ressembler à l'arbre suivant: ```text assets/ @@ -232,22 +248,26 @@ In practice, your assets cache should look like the following tree: └── (...) ``` -## Scan your cache +## 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. -At the moment, cached files are never deleted from your local directory: when you download -a new revision of a branch, previous files are kept in case you need them again. -Therefore it can be useful to scan your cache directory in order to know which repos -and revisions are taking the most disk space. `huggingface_hub` provides an helper to -do so that can be used via `huggingface-cli` or in a python script. -### Scan cache from the terminal +### Scannez le cache depuis le terminal -The easiest way to scan your HF cache-system is to use the `scan-cache` command from -`huggingface-cli` tool. This command scans the cache and prints a report with information -like repo id, repo type, disk usage, refs and full local path. +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. -The snippet below shows a scan report in a folder in which 4 models and 2 datasets are -cached. +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 @@ -264,12 +284,13 @@ 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. ``` -To get a more detailed report, use the `--verbose` option. For each repo, you get a -list of all revisions that have been downloaded. As explained above, the files that don't -change between 2 revisions are shared thanks to the symlinks. This means that the size of -the repo on disk is expected to be less than the sum of the size of each of its revisions. -For example, here `bert-base-cased` has 2 revisions of 1.4G and 1.5G but the total disk -usage is only 1.9G. +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 @@ -291,11 +312,12 @@ 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. ``` -#### Grep example +#### Exemple de grep -Since the output is in tabular format, you can combine it with any `grep`-like tools to -filter the entries. Here is an example to filter only revisions from the "t5-small" -model on a Unix-based machine. +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" @@ -304,19 +326,20 @@ t5-small model d0a119eedb3718e34c648e594394474cf95e0617 t5-small model d78aea13fa7ecd06c29e3e46195d6341255065d5 970.7M 9 1 week ago main /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/d78aea13fa7ecd06c29e3e46195d6341255065d5 ``` -### Scan cache from Python +### Scannez le cache depuis Python -For a more advanced usage, use [`scan_cache_dir`] which is the python utility called by -the CLI tool. +Pour une utilisation plus avancée, utilisez [`scan_cache_dir`] qui est la fonction Python +appelée par l'outil du CLI -You can use it to get a detailed report structured around 4 dataclasses: +Vous pouvez l'utiliser pour avoir un rapport structuré autour des 4 dataclasses: -- [`HFCacheInfo`]: complete report returned by [`scan_cache_dir`] -- [`CachedRepoInfo`]: information about a cached repo -- [`CachedRevisionInfo`]: information about a cached revision (e.g. "snapshot") inside a repo -- [`CachedFileInfo`]: information about a cached file in a snapshot +- [`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 -Here is a simple usage example. See reference for details. +Voici un exemple simple d'utilisation. Consultez les références pour plus de détails. ```py >>> from huggingface_hub import scan_cache_dir @@ -338,7 +361,7 @@ HFCacheInfo( commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5', size_on_disk=970726339, snapshot_path=PosixPath(...), - # No `last_accessed` as blobs are shared among revisions + # Pas de `last_accessed` car les blobs sont partagés entre les révisions last_modified=1662971107.3567169, files=frozenset({ CachedFileInfo( @@ -361,97 +384,99 @@ HFCacheInfo( ... }), warnings=[ - CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."), + CorruptedCacheException("Le chemin vers les snapshots n'existe par dans les dépôts en cache: ..."), CorruptedCacheException(...), ... ], ) ``` -## Clean your cache +## Néttoyez votre cache -Scanning your cache is interesting but what you really want to do next is usually to -delete some portions to free up some space on your drive. This is possible using the -`delete-cache` CLI command. One can also programmatically use the -[`~HFCacheInfo.delete_revisions`] helper from [`HFCacheInfo`] object returned when -scanning the 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. -### Delete strategy +### Stratégie de suppression -To delete some cache, you need to pass a list of revisions to delete. The tool will -define a strategy to free up the space based on this list. It returns a -[`DeleteCacheStrategy`] object that describes which files and folders will be deleted. -The [`DeleteCacheStrategy`] allows give you how much space is expected to be freed. -Once you agree with the deletion, you must execute it to make the deletion effective. In -order to avoid discrepancies, you cannot edit a strategy object manually. +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. -The strategy to delete revisions is the following: +La stratégie pour supprimer des révisions est la suivante: -- the `snapshot` folder containing the revision symlinks is deleted. -- blobs files that are targeted only by revisions to be deleted are deleted as well. -- if a revision is linked to 1 or more `refs`, references are deleted. -- if all revisions from a repo are deleted, the entire cached repository is deleted. +- 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é. -Revision hashes are unique across all repositories. This means you don't need to -provide any `repo_id` or `repo_type` when removing revisions. - +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. -If a revision is not found in the cache, it will be silently ignored. Besides, if a file -or folder cannot be found while trying to delete it, a warning will be logged but no -error is thrown. The deletion continues for other paths contained in the -[`DeleteCacheStrategy`] object. +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`]. -### Clean cache from the terminal +### Nettoyez le cache depuis le terminal -The easiest way to delete some revisions from your HF cache-system is to use the -`delete-cache` command from `huggingface-cli` tool. The command has two modes. By -default, a TUI (Terminal User Interface) is displayed to the user to select which -revisions to delete. This TUI is currently in beta as it has not been tested on all -platforms. If the TUI doesn't work on your machine, you can disable it using the -`--disable-tui` flag. +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`. -#### Using the TUI +#### Utilisation du TUI -This is the default mode. To use it, you first need to install extra dependencies by -running the following command: +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"] ``` -Then run the command: +Ensuite lancez la commande: ``` huggingface-cli delete-cache ``` -You should now see a list of revisions that you can select/deselect: +Vous devriez maintenant voir une liste de révisions que vous pouvez sélectionner/désélectionner:
Instructions: - - Press keyboard arrow keys `` and `` to move the cursor. - - Press `` to toggle (select/unselect) an item. - - When a revision is selected, the first line is updated to show you how much space - will be freed. - - Press `` to confirm your selection. - - If you want to cancel the operation and quit, you can select the first item - ("None of the following"). If this item is selected, the delete process will be - cancelled, no matter what other items are selected. Otherwise you can also press - `` to quit the TUI. - -Once you've selected the revisions you want to delete and pressed ``, a last -confirmation message will be prompted. Press `` again and the deletion will be -effective. If you want to cancel, enter `n`. + - 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 @@ -461,28 +486,29 @@ Start deletion. Done. Deleted 1 repo(s) and 0 revision(s) for a total of 3.1G. ``` -#### Without TUI +#### sans le TUI -As mentioned above, the TUI mode is currently in beta and is optional. It may be the -case that it doesn't work on your machine or that you don't find it convenient. +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. -Another approach is to use the `--disable-tui` flag. The process is very similar as you -will be asked to manually review the list of revisions to delete. However, this manual -step will not take place in the terminal directly but in a temporary file generated on -the fly and that you can manually edit. +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. -This file has all the instructions you need in the header. Open it in your favorite text -editor. To select/deselect a revision, simply comment/uncomment it with a `#`. Once the -manual review is done and the file is edited, you can save it. Go back to your terminal -and press ``. By default it will compute how much space would be freed with the -updated list of revisions. You can continue to edit the file or confirm with `"y"`. +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 ``` -Example of command file: - +Exemple de fichier de commande: ```txt # INSTRUCTIONS # ------------ @@ -522,10 +548,10 @@ Example of command file: # 9cfa5647b32c0a30d0adfca06bf198d82192a0d1 # Refs: main # modified 5 days ago ``` -### Clean cache from Python +### Nettoyez le cache depuis Python -For more flexibility, you can also use the [`~HFCacheInfo.delete_revisions`] method -programmatically. Here is a simple example. See reference for details. +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 From a56ee9b168415afc9d09a7ebfc201a6eec887272 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Fri, 15 Dec 2023 21:27:58 +0100 Subject: [PATCH 018/129] Translated manage-space.md --- docs/source/fr/guides/manage-spaces.md | 223 +++++++++++++------------ 1 file changed, 120 insertions(+), 103 deletions(-) diff --git a/docs/source/fr/guides/manage-spaces.md b/docs/source/fr/guides/manage-spaces.md index 95497e420f..75975e3ad5 100644 --- a/docs/source/fr/guides/manage-spaces.md +++ b/docs/source/fr/guides/manage-spaces.md @@ -2,76 +2,82 @@ rendered properly in your Markdown viewer. --> -# Manage your Space +# Gérez votre espace -In this guide, we will see how to manage your Space runtime -([secrets](https://huggingface.co/docs/hub/spaces-overview#managing-secrets), -[hardware](https://huggingface.co/docs/hub/spaces-gpus), and [storage](https://huggingface.co/docs/hub/spaces-storage#persistent-storage)) using `huggingface_hub`. +Dans ce guide, nous allons voir comment gérer le temps de calcul sur votre espace, +([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`. -## A simple example: configure secrets and hardware. +## Un exemple simple: configurez les secrets et le hardware. -Here is an end-to-end example to create and setup a Space on the Hub. +Voici un exemple de A à Z pour créer et mettre en place un espace sur le Hub. -**1. Create a Space on the Hub.** +**1. Créez un espace sur le Hub.** ```py >>> from huggingface_hub import HfApi >>> repo_id = "Wauplin/my-cool-training-space" >>> api = HfApi() -# For example with a Gradio SDK +# Par exemple, avec un SDK Gradio >>> api.create_repo(repo_id=repo_id, repo_type="space", space_sdk="gradio") ``` -**1. (bis) Duplicate a Space.** +**1. (bis) Dupliquez un espace.** -This can prove useful if you want to build up from an existing Space instead of starting from scratch. -It is also useful is you want control over the configuration/settings of a public Space. See [`duplicate_space`] for more details. +Ceci peut-être utile si vous voulez construire depuis un espace existant aulieu de commencer à zéro. +C'est aussi utile si vous voulez controler la configuration et les paramètres d'un espace publique. +Consultez [`duplicate_space`] pour plus de détails. ```py >>> api.duplicate_space("multimodalart/dreambooth-training") ``` -**2. Upload your code using your preferred solution.** +**2. Uploadez votre code en utilisant votre solution préférée.** -Here is an example to upload the local folder `src/` from your machine to your Space: +Voici un exemple pour upload le dossier local `src/` depuis votre machine vers votre espace: ```py >>> api.upload_folder(repo_id=repo_id, repo_type="space", folder_path="src/") ``` -At this step, your app should already be running on the Hub for free ! -However, you might want to configure it further with secrets and upgraded hardware. +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. Configure secrets and variables** +**3. Configurez des secrets et des variables** -Your Space might require some secret keys, token or variables to work. -See [docs](https://huggingface.co/docs/hub/spaces-overview#managing-secrets) for more details. -For example, an HF token to upload an image dataset to the Hub once generated from your Space. +Votre espace 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 espace. ```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") ``` -Secrets and variables can be deleted as well: +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") ``` -From within your Space, secrets are available as environment variables (or -Streamlit Secrets Management if using Streamlit). No need to fetch them via the API! +Depuis votre espace, 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! -Any change in your Space configuration (secrets or hardware) will trigger a restart of your app. +Tout changement dans la configuration de votre espace (secrets ou hardware) relancera votre +application. -**Bonus: set secrets and variables when creating or duplicating the Space!** +**Bonus: définissez les secrets et les variables lors de la création ou la duplication de l'espace!** -Secrets and variables can be set when creating or duplicating a space: +Les secrets et les variables peuvent être défini lors de la création ou la duplication d'un espace: ```py >>> api.create_repo( @@ -91,24 +97,25 @@ Secrets and variables can be set when creating or duplicating a space: ... ) ``` -**4. Configure the hardware** +**4. Configurez le hardware** -By default, your Space will run on a CPU environment for free. You can upgrade the hardware -to run it on GPUs. A payment card or a community grant is required to access upgrade your -Space. See [docs](https://huggingface.co/docs/hub/spaces-gpus) for more details. +Par défaut, votre espace 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 espace. Consultez [la doc](https://huggingface.co/docs/hub/spaces-gpus) +pour plus de détails. ```py -# Use `SpaceHardware` enum +# Utilisez l'enum `SpaceHardware` >>> from huggingface_hub import SpaceHardware >>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM) -# Or simply pass a string value +# Ou simplement passez un string >>> api.request_space_hardware(repo_id=repo_id, hardware="t4-medium") ``` -Hardware updates are not done immediately as your Space has to be reloaded on our servers. -At any time, you can check on which hardware your Space is running to see if your request -has been met. +Les mises à jour d'hardware ne sont pas faites immédiatement vu que votre espace doit +être rechargé sur nos serveurs. A n'importe quel moment, vous pouvez vérifier sur quel +hardware votre espace tourne pour vérifier que votre demande a été réalisée. ```py >>> runtime = api.get_space_runtime(repo_id=repo_id) @@ -120,12 +127,15 @@ has been met. "t4-medium" ``` +Vous avez maintenant un espace 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: request hardware when creating or duplicating the Space!** +**Bonus: demandez du hardware lors de la création ou la duplication d'un espace!** -Upgraded hardware will be automatically assigned to your Space once it's built. +Les nouvel hardware sera automatiquement assigné à votre espace une fois qu'il +a été construit. ```py >>> api.create_repo( @@ -134,7 +144,7 @@ Upgraded hardware will be automatically assigned to your Space once it's built. ... space_sdk="gradio" ... space_hardware="cpu-upgrade", ... space_storage="small", -... space_sleep_time="7200", # 2 hours in secs +... space_sleep_time="7200", # 2 heure en secondes ... ) ``` ```py @@ -142,46 +152,48 @@ Upgraded hardware will be automatically assigned to your Space once it's built. ... from_id=repo_id, ... hardware="cpu-upgrade", ... storage="small", -... sleep_time="7200", # 2 hours in secs +... sleep_time="7200", # 2 heures en secondes ... ) ``` -**5. Pause and restart your Space** +**5. Mettez en pause et relancez votre espace** -By default if your Space is running on an upgraded hardware, it will never be stopped. However to avoid getting billed, -you might want to pause it when you are not using it. This is possible using [`pause_space`]. A paused Space will be -inactive until the owner of the Space restarts it, either with the UI or via API using [`restart_space`]. -For more details about paused mode, please refer to [this section](https://huggingface.co/docs/hub/spaces-gpus#pause) +Par défaut, si votre espace 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 espace en pause sera inactif tant que le propriétaire de l'espace 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 -# Pause your Space to avoid getting billed +# Mettez en pause votre espace pour éviter de payer >>> api.pause_space(repo_id=repo_id) # (...) -# Restart it when you need it +# Relancez le quand vous en avez besoin >>> api.restart_space(repo_id=repo_id) ``` -Another possibility is to set a timeout for your Space. If your Space is inactive for more than the timeout duration, -it will go to sleep. Any visitor landing on your Space will start it back up. You can set a timeout using -[`set_space_sleep_time`]. For more details about sleeping mode, please refer to [this section](https://huggingface.co/docs/hub/spaces-gpus#sleep-time). +Une auter possibilité est de définir un timeout pour votre espace. Si votre espace 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 espace 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 -# Put your Space to sleep after 1h of inactivity +# Mettez votre espace en pause après une heure d'inactivité >>> api.set_space_sleep_time(repo_id=repo_id, sleep_time=3600) ``` -Note: if you are using a 'cpu-basic' hardware, you cannot configure a custom sleep time. Your Space will automatically -be paused after 48h of inactivity. +Note: si vous utlisez du du hardware 'cpu-basic', vous ne pouvez pas configurer un timeout personnalisé. Votre espace +se mettre en pause automatiquement aprèss 48h d'inactivité. -**Bonus: set a sleep time while requesting hardware** +**Bonus: définissez le temps de timeout lorsque vous demandez le hardware** -Upgraded hardware will be automatically assigned to your Space once it's built. +Le hardware amélioré sera automatiquement assigné à votre espace une fois construit. ```py >>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM, sleep_time=3600) ``` -**Bonus: set a sleep time when creating or duplicating the Space!** +**Bonus: définissez un temps de timeout lors de la création ou de la duplication d'un espace!** ```py >>> api.create_repo( @@ -200,24 +212,27 @@ Upgraded hardware will be automatically assigned to your Space once it's built. ... ) ``` -**6. Add persistent storage to your Space** +**6. Ajoutez du stockage persistant à votre espace** -You can choose the storage tier of your choice to access disk space that persists across restarts of your Space. This means you can read and write from disk like you would with a traditional hard drive. See [docs](https://huggingface.co/docs/hub/spaces-storage#persistent-storage) for more details. +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 de l'espace. 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) ``` -You can also delete your storage, losing all the data permanently. +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: You cannot decrease the storage tier of your space once it's been granted. To do so, -you must delete the storage first then request the new desired tier. +Note: Vous ne pouvez pas diminuer le niveau de stockage de votre espace 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: request storage when creating or duplicating the Space!** +**Bonus: demandez du stockage lors de la création ou la duplication de l'espace!** ```py >>> api.create_repo( @@ -234,87 +249,89 @@ you must delete the storage first then request the new desired tier. ... ) ``` -## More advanced: temporarily upgrade your Space ! +## Avancé: améliorez votre espace pour un durée déterminée! -Spaces allow for a lot of different use cases. Sometimes, you might want -to temporarily run a Space on a specific hardware, do something and then shut it down. In -this section, we will explore how to benefit from Spaces to finetune a model on demand. -This is only one way of solving this particular problem. It has to be taken as a suggestion -and adapted to your use case. +Les espaces ont un grand nombre de cas d'application. Parfois, vous aurez +peut-être envie de faire un tourner un espace pendant une durée déterminée sur un hardware +spécifique, faire quelque chose puis éteindre l'espace. dans cette section, nous explorerons +les avantgaes des espaces 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. -Let's assume we have a Space to finetune a model. It is a Gradio app that takes as input -a model id and a dataset id. The workflow is as follows: +Supposons que nous avons un espace 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. (Prompt the user for a model and a dataset) -1. Load the model from the Hub. -2. Load the dataset from the Hub. -3. Finetune the model on the dataset. -4. Upload the new model to the Hub. +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. -Step 3. requires a custom hardware but you don't want your Space to be running all the time on a paid -GPU. A solution is to dynamically request hardware for the training and shut it -down afterwards. Since requesting hardware restarts your Space, your app must somehow "remember" -the current task it is performing. There are multiple ways of doing this. In this guide -we will see one solution using a Dataset as "task scheduler". +La 3ème étape demande un hardware personnalisé mais vous n'aurez surement pas envie que votre espace +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 espace, +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". -### App skeleton +### Le squelette de l'application -Here is what your app would look like. On startup, check if a task is scheduled and if yes, -run it on the correct hardware. Once done, set back hardware to the free-plan CPU and -prompt the user for a new task. +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. -Such a workflow does not support concurrent access as normal demos. -In particular, the interface will be disabled when training occurs. -It is preferable to set your repo as private to ensure you are the only user. +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 -# Space will need your token to request hardware: set it as a Secret ! +# Un espace aura besoin de votre token pour demander du hardware: définissez le en temps que secret! HF_TOKEN = os.environ.get("HF_TOKEN") -# Space own repo_id +# Le repo_id de l'espace TRAINING_SPACE_ID = "Wauplin/dreambooth-training" from huggingface_hub import HfApi, SpaceHardware api = HfApi(token=HF_TOKEN) -# On Space startup, check if a task is scheduled. If yes, finetune the model. If not, -# display an interface to request a new task. +# Lors du lancement de l'espace, 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: - # Start Gradio app + # Lancez l'application Gradio def gradio_fn(task): - # On user request, add task and request hardware + # 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) - # Check if Space is loaded with a GPU. + # Vérifiez si l'espace est chargé avec un GPU. if runtime.hardware == SpaceHardware.T4_MEDIUM: - # If yes, finetune base model on dataset ! + # Si oui, fintunez le modèle de base sur le dataset! train_and_upload(task) - # Then, mark the task as "DONE" + # Ensuite, signalez la tâche comme finie mark_as_done(task) - # DO NOT FORGET: set back CPU hardware + # 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) ``` -### Task scheduler +### Le task scheduler -Scheduling tasks can be done in many ways. Here is an example how it could be done using -a simple CSV stored as a Dataset. +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 -# Dataset ID in which a `tasks.csv` file contains the tasks to perform. -# Here is a basic example for `tasks.csv` containing inputs (base model and dataset) -# and status (PENDING or DONE). +# 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" @@ -339,7 +356,7 @@ def add_task(task): repo_id=repo_id, repo_type=repo_type, path_in_repo="tasks.csv", - # Quick and dirty way to add a task + # Manière simple et inélégante d'ajouter une tâche path_or_fileobj=(tasks + f"\n{model_id},{dataset_id},PENDING").encode() ) @@ -353,7 +370,7 @@ def mark_as_done(task): repo_id=repo_id, repo_type=repo_type, path_in_repo="tasks.csv", - # Quick and dirty way to set the task as DONE + # 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" From 158220b27a5a598d7e739322cbd5f6dc78872d29 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 16 Dec 2023 11:04:51 +0100 Subject: [PATCH 019/129] Translated overview.md --- docs/source/fr/guides/overview.md | 50 ++++++++++---------- docs/source/fr/package_reference/overview.md | 4 +- 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/source/fr/guides/overview.md b/docs/source/fr/guides/overview.md index b97bd6b76a..2661c8128b 100644 --- a/docs/source/fr/guides/overview.md +++ b/docs/source/fr/guides/overview.md @@ -2,10 +2,10 @@ rendered properly in your Markdown viewer. --> -# How-to guides +# Guides conceptuels -In this section, you will find practical guides to help you achieve a specific goal. -Take a look at these guides to learn how to use huggingface_hub to solve real-world problems: +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:
@@ -13,36 +13,36 @@ Take a look at these guides to learn how to use huggingface_hub to solve real-wo
- Repository + Dépôts

- How to create a repository on the Hub? How to configure it? How to interact with it? + Comment créer un dépôt sur le Hub ? Comment le configurer ? Comment intéragir avec ?

- Download files + Télécharger des fichiers

- How do I download a file from the Hub? How do I download a repository? + Comment télécharger un fichier du Hub? Comment télécharger un dépôt?

- Upload files + Upload des fichiers

- How to upload a file or a folder? How to make changes to an existing repository on the Hub? + Comment upload un fichier ou un dossier? Comment modifier un dépôt existant sur le Hub?

- Search + Recherche

- How to efficiently search through the 200k+ public models, datasets and spaces? + Comment faire une recherche efficace parmi les plus de 200 000 modèles, datasets et espaces?

@@ -51,16 +51,16 @@ Take a look at these guides to learn how to use huggingface_hub to solve real-wo
HfFileSystem

- How to interact with the Hub through a convenient interface that mimics Python's file interface? + Comment intéragir avec le Hub à travers une interface pratique qui colle parfaitement à l'interface fichier de Python?

- Inference + Inférence

- How to make predictions using the accelerated Inference API? + Comment faire des prédictions en utilisant l'API d'inférence accélérée?

@@ -69,7 +69,7 @@ Take a look at these guides to learn how to use huggingface_hub to solve real-wo
Community Tab

- How to interact with the Community tab (Discussions and Pull Requests)? + Comment intéragir avec la communauté (discussions et pull requests)?

@@ -78,7 +78,7 @@ Take a look at these guides to learn how to use huggingface_hub to solve real-wo
Collections

- How to programmatically build collections? + Comment construire des collections depuis le code?

@@ -87,43 +87,43 @@ Take a look at these guides to learn how to use huggingface_hub to solve real-wo
Cache

- How does the cache-system work? How to benefit from it? + Comment le système cache fonctionne? Comment l'utiliser à son avantage?

- Model Cards + Carte de modèle

- How to create and share Model Cards? + Comment créer et partager une carte de modèle?

- Manage your Space + Gérez votre espace

- How to manage your Space hardware and configuration? + Comment gérer le hardware d'un espace et sa configuration?

- Integrate a library + Intégrez une librairie

- What does it mean to integrate a library with the Hub? And how to do it? + Que signifie intégrer une librairie avec le Hub? Et comment le faire?

- Webhooks server + Serveurs WebHooks

- How to create a server to receive Webhooks and deploy it as a Space? + Comment créer un serveur pour recevoir des webhooks et le dépployer en tant qu'espace?

diff --git a/docs/source/fr/package_reference/overview.md b/docs/source/fr/package_reference/overview.md index f024f25692..c9f66d28c5 100644 --- a/docs/source/fr/package_reference/overview.md +++ b/docs/source/fr/package_reference/overview.md @@ -2,6 +2,6 @@ rendered properly in your Markdown viewer. --> -# Overview +# Vue d'ensemble -This section contains an exhaustive and technical description of `huggingface_hub` classes and methods. \ No newline at end of file +Cette section contiens une description technique et exhaustive des classes `huggingface_hub` et des méthodes. \ No newline at end of file From 9e2910a526bb9fc1eef90e2cfe58c0a7070b6854 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 16 Dec 2023 12:23:19 +0100 Subject: [PATCH 020/129] Translated package-reference file --- docs/source/fr/package_reference/cache.md | 16 +- docs/source/fr/package_reference/cards.md | 23 +-- .../fr/package_reference/collections.md | 23 +-- docs/source/fr/package_reference/community.md | 2 +- .../environment_variables.md | 177 ++++++++++-------- 5 files changed, 128 insertions(+), 113 deletions(-) diff --git a/docs/source/fr/package_reference/cache.md b/docs/source/fr/package_reference/cache.md index b3326c239e..502156ef66 100644 --- a/docs/source/fr/package_reference/cache.md +++ b/docs/source/fr/package_reference/cache.md @@ -2,13 +2,14 @@ rendered properly in your Markdown viewer. --> -# Cache-system reference +# Référence au système cache -The caching system was updated in v0.8.0 to become the central cache-system shared -across libraries that depend on the Hub. Read the [cache-system guide](../guides/manage-cache) -for a detailed presentation of caching at HF. +Le système de caching a été mis à jour dans la version v0.8.0 pour devenir un système +cache central et partagé par toutes les librairies dépendant du Hub. Consultez le +[guide système cache](../guides/manage-cache) pour une présentation détaillée du +cache à HF. -## Helpers +## Les Helpers ### try_to_load_from_cache @@ -22,9 +23,10 @@ for a detailed presentation of caching at HF. [[autodoc]] huggingface_hub.scan_cache_dir -## Data structures +## Structures de données -All structures are built and returned by [`scan_cache_dir`] and are immutable. +Toutes les structures sont construites et retournées par [`scan_cache_dir`] +et sont immuables. ### HFCacheInfo diff --git a/docs/source/fr/package_reference/cards.md b/docs/source/fr/package_reference/cards.md index 4f64238bd7..71bc71fa2b 100644 --- a/docs/source/fr/package_reference/cards.md +++ b/docs/source/fr/package_reference/cards.md @@ -2,28 +2,29 @@ rendered properly in your Markdown viewer. --> -# Repository Cards +# Cartes de dépôts -The huggingface_hub library provides a Python interface to create, share, and update Model/Dataset Cards. -Visit the [dedicated documentation page](https://huggingface.co/docs/hub/models-cards) for a deeper view of what -Model Cards on the Hub are, and how they work under the hood. You can also check out our [Model Cards guide](../how-to-model-cards) to -get a feel for how you would use these utilities in your own projects. +La librairie `huggingface_hub` fournit une interface Python pour créer, partager et mettre à jour les +cartes de modèles ou de dataset. Consultez la [page de documentation dédiée](https://huggingface.co/docs/hub/models-cards) +Pour une vue plus profonde de ce que son les cartes de modèle sur le Hub et de comment elles fonctionnent +en arrière plan. Vous pouvez aussi consulter notre [guide de cartes de modèle](../how-to-model-cards) +pour avoir une intuition de la manière dont vous pourriez les utiliser dans vos projets. -## Repo Card +## Carte de dépôt -The `RepoCard` object is the parent class of [`ModelCard`], [`DatasetCard`] and `SpaceCard`. +L'objet `RepoCard` est la classe parent de [`ModelCard`], [`DatasetCard`] et `SpaceCard`. [[autodoc]] huggingface_hub.repocard.RepoCard - __init__ - all -## Card Data +## Donnée de cartes -The [`CardData`] object is the parent class of [`ModelCardData`] and [`DatasetCardData`]. +L'objet [`CardData`] est la classe parent de [`ModelCardData`] et [`DatasetCardData`]. [[autodoc]] huggingface_hub.repocard_data.CardData -## Model Cards +## Cartes de modèles ### ModelCard @@ -45,7 +46,7 @@ Dataset cards are also known as Data Cards in the ML Community. [[autodoc]] DatasetCardData -## Space Cards +## Cartes d'espace ### SpaceCard diff --git a/docs/source/fr/package_reference/collections.md b/docs/source/fr/package_reference/collections.md index 37fe25039c..ed9e79cb71 100644 --- a/docs/source/fr/package_reference/collections.md +++ b/docs/source/fr/package_reference/collections.md @@ -2,17 +2,18 @@ rendered properly in your Markdown viewer. --> -# Managing collections - -Check out the [`HfApi`] documentation page for the reference of methods to manage your Space on the Hub. - -- Get collection content: [`get_collection`] -- Create new collection: [`create_collection`] -- Update a collection: [`update_collection_metadata`] -- Delete a collection: [`delete_collection`] -- Add an item to a collection: [`add_collection_item`] -- Update an item in a collection: [`update_collection_item`] -- Remove an item from a collection: [`delete_collection_item`] +# Gérer les collections + +Consultez la page de documentation [`HfApi`] pour les références des méthodes qui vous permettront +de gérer votre espace sur le Hub. + +- Afficher le contenu d'une collection: [`get_collection`] +- Créer une nouvelle collection: [`create_collection`] +- Mettre à jour une collection: [`update_collection_metadata`] +- Supprimer une collection: [`delete_collection`] +- Ajouter un item à une collection: [`add_collection_item`] +- Mettre à jour un item dans une collection: [`update_collection_item`] +- Supprimer un item d'une collection: [`delete_collection_item`] ### Collection diff --git a/docs/source/fr/package_reference/community.md b/docs/source/fr/package_reference/community.md index 799a861b76..38e9065ff8 100644 --- a/docs/source/fr/package_reference/community.md +++ b/docs/source/fr/package_reference/community.md @@ -4,7 +4,7 @@ rendered properly in your Markdown viewer. # Interagir avec les dicussions et les pull requests -Regardez la page de documentation [`HfApi`] pour les références des méthodes permettant l'intéraction +Consultez la page de documentation [`HfApi`] pour les références des méthodes permettant l'intéraction avec des pull requests et des discussions sur le Hub. - [`get_repo_discussions`] diff --git a/docs/source/fr/package_reference/environment_variables.md b/docs/source/fr/package_reference/environment_variables.md index 0ee1c2be89..418545806a 100644 --- a/docs/source/fr/package_reference/environment_variables.md +++ b/docs/source/fr/package_reference/environment_variables.md @@ -2,174 +2,185 @@ rendered properly in your Markdown viewer. --> -# Environment variables +# Variables d'environnement -`huggingface_hub` can be configured using environment variables. +`huggingface_hub` peut être configuré en utilisant des variables d'environnement. -If you are unfamiliar with environment variable, here are generic articles about them -[on macOS and Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) -and on [Windows](https://phoenixnap.com/kb/windows-set-environment-variable). +Si vous n'êtes pas familier avec le principe de variable d'environnement, voici des +articles assez générique sur ces dernières [sur macOS et Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) +et sur [Windows](https://phoenixnap.com/kb/windows-set-environment-variable). -This page will guide you through all environment variables specific to `huggingface_hub` -and their meaning. +Cette page vous guidera à travers toutes les variables d'environnement spécifiques à +`huggingface_hub` et leur signification. -## Generic +## Les variables génériques ### HF_INFERENCE_ENDPOINT -To configure the inference api base url. You might want to set this variable if your organization -is pointing at an API Gateway rather than directly at the inference api. +Pour configurer l'url de base de l'api d'inférence, vous aurez peut-être besoin de définir +cette variable si votre organisation pointe vers un gateway d'API plutôt que directement vers +l'API d'inférence. -Defaults to `"https://api-inference.huggingface.com"`. +Par défaut, l'endpoint sera `"https://api-inference.huggingface.com"`. ### HF_HOME -To configure where `huggingface_hub` will locally store data. In particular, your token -and the cache will be stored in this folder. +Pour configurer le chemin vers lequel `huggingface_hub` enregistrera de la donnée par +défaut. En particulier, votre token d'authentification et le cache seront enregistrés +dans ce dossier. -Defaults to `"~/.cache/huggingface"` unless [XDG_CACHE_HOME](#xdgcachehome) is set. +Par défaut, ce chemin sera `"~/.cache/huggingface"` sauf si [XDG_CACHE_HOME](#xdgcachehome) +est définie. ### HF_HUB_CACHE -To configure where repositories from the Hub will be cached locally (models, datasets and -spaces). +Pour configurer le chemin vers lequels les dépôts du Hub seront mis en cache en local +(modèles, datasets et espaces). -Defaults to `"$HF_HOME/hub"` (e.g. `"~/.cache/huggingface/hub"` by default). +Par défaut, ce sera `"$HF_HOME/hub"` (i.e. `"~/.cache/huggingface/hub"` par défaut). ### HF_ASSETS_CACHE -To configure where [assets](../guides/manage-cache#caching-assets) created by downstream libraries -will be cached locally. Those assets can be preprocessed data, files downloaded from GitHub, -logs,... +Pour configurer le chemin vers lequel les [assets](../guides/manage-cache#caching-assets) créés +par des librairies seront mis en cache en local. Ces assets peuvent être de la donnée pré-traitée, +des fichiers téléchargés depuis GitHub, des logs,... -Defaults to `"$HF_HOME/assets"` (e.g. `"~/.cache/huggingface/assets"` by default). +Par défaut, le chemin sera `"$HF_HOME/assets"` (i.e. `"~/.cache/huggingface/assets"` par défaut). ### HF_TOKEN -To configure the User Access Token to authenticate to the Hub. If set, this value will -overwrite the token stored on the machine (in `"$HF_HOME/token"`). +Pour configurer le token d'authentification qui permet de vous authentifier sur le Hub. +Si définie, cette valeur écrasera le token enregistré sur la machine (dans `"$HF_HOME/token"`). -See [login reference](../package_reference/login) for more details. +Consultez [la référence aux connexions](../package_reference/login) pour plus de détails. ### HF_HUB_VERBOSITY -Set the verbosity level of the `huggingface_hub`'s logger. Must be one of -`{"debug", "info", "warning", "error", "critical"}`. +Définissez le niveau de verbosité du logger `huggingface_hub`. La variable doit +être choisie parmi `{"debug", "info", "warning", "error", "critical"}`. -Defaults to `"warning"`. +Par défaut, la variable sera `"warning"`. -For more details, see [logging reference](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity). +Pour plus de détails, consultez [la référence aux connexions](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity). ### HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD -Integer value to define under which size a file is considered as "small". When downloading files to a local directory, -small files will be duplicated to ease user experience while bigger files are symlinked to save disk usage. +Valeur entière définissant en dessous de quelle taille un fichier est considéré comme "petit". Lors du téléchargement +de fichiers vers un chemin local, les petits fichiers seront dupliqués pour faciliter l'expérience utilisateur là où +les fichiers plus gros n'auront qu'un symlink vers eux pour conserver de l'espace sur le disque. -For more details, see the [download guide](../guides/download#download-files-to-local-folder). +Pour plus de détails, consultez le [guide de téléchargement](../guides/download#download-files-to-local-folder). ### HF_HUB_ETAG_TIMEOUT -Integer value to define the number of seconds to wait for server response when fetching the latest metadata from a repo before downloading a file. If the request times out, `huggingface_hub` will default to the locally cached files. Setting a lower value speeds up the workflow for machines with a slow connection that have already cached files. A higher value guarantees the metadata call to succeed in more cases. Default to 10s. +Valeur entière définissant le nombre de secondes pendant lesquelles il faut attendre la réponse du serveur lors de l'affichage des dernières metadonnées depuis un dépôt avant de télécharger un fichier. En cas de timeout, alors, par défaut, `huggingface_hub` se limitera aux fichiers en cache en local. Définir une valeur plus faible accélère le workflow pour des machines avec une connexion lente qui ont déjà des fichiers en cache. Une plus grande valeur garanti l'appel aux métadonnées pour réussir dans plus de cas. Par défaut, la valeur est de 10s. ### HF_HUB_DOWNLOAD_TIMEOUT -Integer value to define the number of seconds to wait for server response when downloading a file. If the request times out, a TimeoutError is raised. Setting a higher value is beneficial on machine with a slow connection. A smaller value makes the process fail quicker in case of complete network outage. Default to 10s. +Valeur entière pour définir le nombre de secondes durant lesquelles il faut attendre la réponse du serveur lors du téléchargement d'un fichier. Si la requête tiemout, une TimeoutError sera levée. Définir une valeur grande est bénéfique sur une machine qui a une connexion lente. Une valeur plus faible fait échouer le process plus vite dans le cas d'un réseau complexe. Par défaut, la valeur est de 10s. -## Boolean values +## Valeures booléennes -The following environment variables expect a boolean value. The variable will be considered -as `True` if its value is one of `{"1", "ON", "YES", "TRUE"}` (case-insensitive). Any other value -(or undefined) will be considered as `False`. +Les variables d'environnement suivantes attendes une valeur booléenne. La variable sera +considérées comme `True` si sa valeur fait partie de la liste`{"1", "ON", "YES", "TRUE"}`. +Toute autre valeur (ou undefined) sera considérée comme `False`. ### HF_HUB_OFFLINE -If set, no HTTP calls will me made when trying to fetch files. Only files that are already -cached will be accessed. This is useful in case your network is slow and you don't care -about having absolutely the latest version of a file. +Si définie, aucun appel HTTP ne sera fait lors de l'ajout de fichiers. Seuls les fichiers +qui sont déjà en cache seront ajoutés. C'est utile si votre réseau est lent et que vous +vous en fichez d'avoir absolument la dernière version d'un fichier. -**Note:** even if the latest version of a file is cached, calling `hf_hub_download` still triggers -a HTTP request to check that a new version is not available. Setting `HF_HUB_OFFLINE=1` will -skip this call which speeds up your loading time. +**Note:** Même si la dernière version d'un fichier est en cache, l'appel de `hf_hub_download` +lancera quand même une requête HTTP pour vérifier qu'une nouvelle version est disponible. +Définir `HF_HUB_OFFLINE=1` évitera cet appel ce qui peut accélérer votre temps de chargement. ### HF_HUB_DISABLE_IMPLICIT_TOKEN -Authentication is not mandatory for every requests to the Hub. For instance, requesting -details about `"gpt2"` model does not require to be authenticated. However, if a user is -[logged in](../package_reference/login), the default behavior will be to always send the token -in order to ease user experience (never get a HTTP 401 Unauthorized) when accessing private or gated repositories. For privacy, you can -disable this behavior by setting `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. In this case, -the token will be sent only for "write-access" calls (example: create a commit). +L'authentification n'est pas obligatoire pour toutes les requêtes vers le Hub. Par +exemple, demander des détails sur le modèle `"gpt2"` ne demande pas nécessairement +d'être authentifié. Cependant, si un utilisateur est [connecté](../package_reference/login), +le comportement par défaut sera de toujours envoyer le token pour faciliter l'expérience +utilisateur (cela évite d'avoir une erreur 401 Unauthorized) lors de l'accès de dépôt +privés ou protégé. Vous pouvez supprimer ce comportement en définissant `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. +Dans ce cas, le token ne sera envoyé que pour des appels de type "write-access" (par exemple, pour créer un commit). -**Note:** disabling implicit sending of token can have weird side effects. For example, -if you want to list all models on the Hub, your private models will not be listed. You -would need to explicitly pass `token=True` argument in your script. +**Note:** supprimer l'envoi implicit de token peut avoir des effets secondaires bizarres. +Par exemple, si vous voulez lister tous les modèles sur le Hub, vos modèles privés ne +seront pas listés. Vous auriez besoin d'un argument explicite `token=True` dans votre +script. ### HF_HUB_DISABLE_PROGRESS_BARS -For time consuming tasks, `huggingface_hub` displays a progress bar by default (using tqdm). -You can disable all the progress bars at once by setting `HF_HUB_DISABLE_PROGRESS_BARS=1`. +Pour les tâches longues, `huggingface_hub` affiche une bar de chargement par défaut (en utilisant tqdm). +Vous pouvez désactiver toutes les barres de progression d'un coup en définissant +`HF_HUB_DISABLE_PROGRESS_BARS=1`. ### HF_HUB_DISABLE_SYMLINKS_WARNING -If you are on a Windows machine, it is recommended to enable the developer mode or to run -`huggingface_hub` in admin mode. If not, `huggingface_hub` will not be able to create -symlinks in your cache system. You will be able to execute any script but your user experience -will be degraded as some huge files might end-up duplicated on your hard-drive. A warning -message is triggered to warn you about this behavior. Set `HF_HUB_DISABLE_SYMLINKS_WARNING=1`, -to disable this warning. +Si vous avez une machine Windows, il est recommandé d'activer le mode développeur ou de +faire tourner `huggingface_hub` en mode admin. Sinon, `huggingface_hub` ne ser pas capable +de créer des symlinks dans votre système de cache. Vous serez capables d'exécuter n'importe +quel script, mais votre expérience utilisateur sera moins bonne vu que certains gros fichiers +pourraient être dupliqués sur votre disque dur. Un message d'avertissement vous préviendra +de ce type de comportement. Définissez `HF_HUB_DISABLE_SYMLINKS_WARNING=1`, pour désactiver +cet avertissement. -For more details, see [cache limitations](../guides/manage-cache#limitations). +Pour plus de détails, consultez [les limitations du cache](../guides/manage-cache#limitations). ### HF_HUB_DISABLE_EXPERIMENTAL_WARNING -Some features of `huggingface_hub` are experimental. This means you can use them but we do not guarantee they will be -maintained in the future. In particular, we might update the API or behavior of such features without any deprecation -cycle. A warning message is triggered when using an experimental feature to warn you about it. If you're comfortable debugging any potential issues using an experimental feature, you can set `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` to disable the warning. +Certaines fonctionnalités de `huggingface_hub` sont expérimentales, cela signfie que vous pouvez les utliiser mais +nous ne garantissons pas qu'elles seront maintenues plus tard. En particulier, nous mettrons peut-être à jour les +API ou le comportement de telles fonctionnalités sans aucun cycle de deprecation. Un message d'avertissement sera +affiché lorsque vous utilisez une fonctionnalités expérimentale pour vous l'indiquer. Si vous n'êtes pas dérangé par +le fait de devoir debug toute erreur potentielle liée à l'usage d'une fonctionnalité expérimentale, vous pouvez +définir `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` pour désactiver l'avertissement. -If you are using an experimental feature, please let us know! Your feedback can help us design and improve it. +Si vous utilisez une fonctoinnalité expérimental, faites le nous savoir! Votre retour peut nous aider à l'améliorer. ### HF_HUB_DISABLE_TELEMETRY -By default, some data is collected by HF libraries (`transformers`, `datasets`, `gradio`,..) to monitor usage, debug issues and help prioritize features. -Each library defines its own policy (i.e. which usage to monitor) but the core implementation happens in `huggingface_hub` (see [`send_telemetry`]). +Par défaut, des données sont collectées par les librairies HF (`transformers`, `datasets`, `gradio`,..) pour gérer l'utilisation et les problèmes de débug et pour aider à définir les fonctionnalités prioritaires. Chaque librairie définit sa propre politique (i.e. les cas d'usage sur lesquels les données eront collectées), mais l'implémentation principale se passe dans `huggingface_hub` (consultez [`send_telemetry`]). -You can set `HF_HUB_DISABLE_TELEMETRY=1` as environment variable to globally disable telemetry. +Vous pouvez définir `HF_HUB_DISABLE_TELEMETRY=1` en tant que variable d'environnement pour désactiver la télémétrie. ### HF_HUB_ENABLE_HF_TRANSFER -Set to `True` for faster uploads and downloads from the Hub using `hf_transfer`. +Définissez cette valeur à `True` pour des upload et des téléchargements plus rapides depuis le Hub en utilisant `hf_transfer`. -By default, `huggingface_hub` uses the Python-based `requests.get` and `requests.post` functions. Although these are reliable and versatile, they may not be the most efficient choice for machines with high bandwidth. [`hf_transfer`](https://github.com/huggingface/hf_transfer) is a Rust-based package developed to maximize the bandwidth used by dividing large files into smaller parts and transferring them simultaneously using multiple threads. This approach can potentially double the transfer speed. To use `hf_transfer`, you need to install it separately [from PyPI](https://pypi.org/project/hf-transfer/) and set `HF_HUB_ENABLE_HF_TRANSFER=1` as an environment variable. +Par défaut, `huggingface_hub` utilise les fonctions basées sur Python `requests.get` et `requests.post`. Même si ces fonctions sont fiables et assez versatiles, elle pourrait ne pas être le choix le plus efficace pour les machines avec une bande passante large. [`hf_transfer`](https://github.com/huggingface/hf_transfer) est un package basé sur Rust développé pour maximiser la bande passante utilisée en divisant les gros fichier en des parties plus petites et les transférer toutes simultanément en utilisant plusieurs threads. Cette approche peut potentiellement doubler la vitesse de transfert. Pour utiliser `hf_transfer`, vous devez l'installer séparément [de PyPI](https://pypi.org/project/hf-transfer/) et définir `HF_HUB_ENABLE_HF_TRANSFER=1` en tant que variable d'environnement. -Please note that using `hf_transfer` comes with certain limitations. Since it is not purely Python-based, debugging errors may be challenging. Additionally, `hf_transfer` lacks several user-friendly features such as resumable downloads and proxies. These omissions are intentional to maintain the simplicity and speed of the Rust logic. Consequently, `hf_transfer` is not enabled by default in `huggingface_hub`. +N'oubliez pas que l'utilisation d'`hf_transfer` a certaines limitations. Vu qu'elle n'est pas purement basé sur Python, le debug d'erreurs peut s'avérer plus compliqué. De plus, `hf_transfer` n'est pas totues les fonctionnalités user-friendly telles que le téléchargement reprenables et les proxys. Ces omissions sont intentionnelles et permettent de maintenir la simplicité et la vitesse de la logique Rust. Par conséquent, `hf_transfer` n'est pas activée par défaut dans `huggingface_hub`. -## Deprecated environment variables +## Variables d'environnement deprecated -In order to standardize all environment variables within the Hugging Face ecosystem, some variables have been marked as deprecated. Although they remain functional, they no longer take precedence over their replacements. The following table outlines the deprecated variables and their corresponding alternatives: +Afin de standardiser toutes les variables d'environnement dans l'écosystème Hugging Face, certaines variable ont été marquée comme deprecated. Même si elle fonctionnent toujours, elles ne sont plus prioritaires par rapport à leur remplacements. La table suivante liste les variables d'environnement deprecated et leurs alternatives respectives: -| Deprecated Variable | Replacement | +| Variable deprecated | Alternative | | --- | --- | | `HUGGINGFACE_HUB_CACHE` | `HF_HUB_CACHE` | | `HUGGINGFACE_ASSETS_CACHE` | `HF_ASSETS_CACHE` | | `HUGGING_FACE_HUB_TOKEN` | `HF_TOKEN` | | `HUGGINGFACE_HUB_VERBOSITY` | `HF_HUB_VERBOSITY` | -## From external tools +## Depuis un outil extérieur -Some environment variables are not specific to `huggingface_hub` but are still taken into account when they are set. +Certaines variables d'environnement ne sont pas spécifiques à `huggingface_hub` mais sont tout de même prises en compte +lorsqu'elles sont définies. ### NO_COLOR -Boolean value. When set, `huggingface-cli` tool will not print any ANSI color. -See [no-color.org](https://no-color.org/). +Valeur booléenne, lorsque définie à `True`, l'outil `huggingface-cli` n'affichera +aucune couleur ANSI. +Consultez [no-color.org](https://no-color.org/). ### XDG_CACHE_HOME -Used only when `HF_HOME` is not set! +Utilisé uniqueemnt si `HF_HOME` n'est pas défini! -This is the default way to configure where [user-specific non-essential (cached) data should be written](https://wiki.archlinux.org/title/XDG_Base_Directory) -on linux machines. +C'est la manière par défaut de configurer l'endroit où [les données en cache non essentielles devraient être écrites](https://wiki.archlinux.org/title/XDG_Base_Directory) sur les machines linux. -If `HF_HOME` is not set, the default home will be `"$XDG_CACHE_HOME/huggingface"` instead -of `"~/.cache/huggingface"`. +Si `HF_HOME` n'est pas définie, le chemin par défaut sera `"$XDG_CACHE_HOME/huggingface"` +aulieu de `"~/.cache/huggingface"`. From f7ec79f4de05fc2fcf06659309a2efa0086f38bd Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 18 Dec 2023 17:14:19 +0100 Subject: [PATCH 021/129] Translated hf_api, login, mixins, repository, space_runtime and tensorboard in the package reference --- docs/source/fr/package_reference/hf_api.md | 33 ++++++++++--------- .../package_reference/inference_endpoints.md | 2 +- docs/source/fr/package_reference/login.md | 5 ++- docs/source/fr/package_reference/mixins.md | 8 ++--- .../source/fr/package_reference/repository.md | 16 ++++----- .../fr/package_reference/space_runtime.md | 17 +++++----- .../fr/package_reference/tensorboard.md | 19 ++++++----- 7 files changed, 52 insertions(+), 48 deletions(-) diff --git a/docs/source/fr/package_reference/hf_api.md b/docs/source/fr/package_reference/hf_api.md index eeb15c1830..8a90e20500 100644 --- a/docs/source/fr/package_reference/hf_api.md +++ b/docs/source/fr/package_reference/hf_api.md @@ -4,25 +4,26 @@ rendered properly in your Markdown viewer. # HfApi Client -Below is the documentation for the `HfApi` class, which serves as a Python wrapper for the Hugging Face Hub's API. +Ci dessous la documentation pour la classe `HfApi`, qui sert de wrapper Python pour l'API Hugging Face Hub. -All methods from the `HfApi` are also accessible from the package's root directly. Both approaches are detailed below. +Toutes les méthodes de `HfApi` sont aussi accessibles depuis la racine du package directement. Les deux approches sont détaillées ci-dessous. -Using the root method is more straightforward but the [`HfApi`] class gives you more flexibility. -In particular, you can pass a token that will be reused in all HTTP calls. This is different -than `huggingface-cli login` or [`login`] as the token is not persisted on the machine. -It is also possible to provide a different endpoint or configure a custom user-agent. +Utiliser la méthode du chemin racine est plus direct mais la classe [`HfApi`] donne plus de flexibilité. +En particulier, vous pouvez mettre un token qui va être réutilisé dans tous les appels HTTP. C'est +différent de la commande `huggingface-cli login` ou [`login`] vu que le token n'est pas enregistré +sur la machine. Il est aussi possible de fournir un endpoint différent ou de configurer un user-agent +personnalisé. ```python from huggingface_hub import HfApi, list_models -# Use root method +# Utilisez la méthode du chemin racine models = list_models() -# Or configure a HfApi client +# Ou configurez le client HfApi hf_api = HfApi( - endpoint="https://huggingface.co", # Can be a Private Hub endpoint. - token="hf_xxx", # Token is not persisted on the machine. + endpoint="https://huggingface.co", # Vous pouvez mettre un endpoint de Hub privéC. + token="hf_xxx", # Le token n'est pas sauvegardé sur la machine. ) models = hf_api.list_models() ``` @@ -97,7 +98,7 @@ models = hf_api.list_models() ## CommitOperation -Below are the supported values for [`CommitOperation`]: +Ci dessous les valeurs supportés pour [`CommitOperation`]: [[autodoc]] CommitOperationAdd @@ -111,16 +112,18 @@ Below are the supported values for [`CommitOperation`]: ## Token helper -`huggingface_hub` stores the authentication information locally so that it may be re-used in subsequent -methods. +`huggingface_hub` garde en mémoire l'information d'authentification en local pour qu'il puisse être réutilisé +dans les méthodes suivantes. -It does this using the [`HfFolder`] utility, which saves data at the root of the user. +La librairie fait ceci en utilisant l'utilitaire [`HfFolder`], qui sauvegarde de la donnée +à la racine de l'utilisateur. [[autodoc]] HfFolder ## Search helpers -Some helpers to filter repositories on the Hub are available in the `huggingface_hub` package. +Certains helpers pour filtrer les dépôts sur le Hub sont disponibles dans le package +`huggingface_hub`. ### DatasetFilter diff --git a/docs/source/fr/package_reference/inference_endpoints.md b/docs/source/fr/package_reference/inference_endpoints.md index b8300670d2..5dd22808c7 100644 --- a/docs/source/fr/package_reference/inference_endpoints.md +++ b/docs/source/fr/package_reference/inference_endpoints.md @@ -1,6 +1,6 @@ # Inference Endpoints -Inferrence Endpoints est une solution permettant de déployer facilement les modèles en production sur une infrastructure gérée par Hugging Face et capable d'autoscaling . Un Inference Endpoint peut être crée sur un modèle depuis le [Hub](https://huggingface.co/models). Cette page est +Inference Endpoints est une solution permettant de déployer facilement les modèles en production sur une infrastructure gérée par Hugging Face et capable d'autoscaling . Un Inference Endpoint peut être crée sur un modèle depuis le [Hub](https://huggingface.co/models). Cette page est une référence pour l'intégration d'`huggingface_hub` avec Inference Endpoints. Pour plus d'informations à propos du produit Inference Endpoints, consultez la [documentation officielle](https://huggingface.co/docs/inference-endpoints/index). diff --git a/docs/source/fr/package_reference/login.md b/docs/source/fr/package_reference/login.md index c100e3999b..2ebb7b70f1 100644 --- a/docs/source/fr/package_reference/login.md +++ b/docs/source/fr/package_reference/login.md @@ -4,9 +4,8 @@ rendered properly in your Markdown viewer. # Login and logout -The `huggingface_hub` library allows users to programmatically login and logout the -machine to the Hub. - +La librairie `huggingface_hub` permet aux utilisateur de se connecter et déconnecter +votre machine au Hub par le code. ## login [[autodoc]] login diff --git a/docs/source/fr/package_reference/mixins.md b/docs/source/fr/package_reference/mixins.md index 41480dfa80..9762068a1e 100644 --- a/docs/source/fr/package_reference/mixins.md +++ b/docs/source/fr/package_reference/mixins.md @@ -2,13 +2,13 @@ rendered properly in your Markdown viewer. --> -# Mixins & serialization methods +# Mixins & méthodes de sérialisation ## Mixins -The `huggingface_hub` library offers a range of mixins that can be used as a parent class for your objects, in order to -provide simple uploading and downloading functions. Check out our [integration guide](../guides/integrations) to learn -how to integrate any ML framework with the Hub. +La librairie `huggingface_hub` offre une liste de mixins qui peuvent être utilisés en tant que classes parentes pour vos +objets, afin d'avoir des fonctions upload et de téléchargements simples. Consultez notre [guide d'intégration](../guides/integrations) +pour apprendre à intégrer n'importe quel framework ML avec le Hub. ### Generic diff --git a/docs/source/fr/package_reference/repository.md b/docs/source/fr/package_reference/repository.md index 9964f94859..c8ebc43581 100644 --- a/docs/source/fr/package_reference/repository.md +++ b/docs/source/fr/package_reference/repository.md @@ -4,11 +4,11 @@ rendered properly in your Markdown viewer. # Managing local and online repositories -The `Repository` class is a helper class that wraps `git` and `git-lfs` commands. It provides tooling adapted -for managing repositories which can be very large. +La classe `Repository` est un helper autour des commandes `git` et `git-lfs`. Elle offre des outils adaptés +à la gestion de dépôts qui peuvent être très volumineux. -It is the recommended tool as soon as any `git` operation is involved, or when collaboration will be a point -of focus with the repository itself. +C'est l'outil recommandé dès que des opérations avec `git` sont faites, ou lorsque la collaboration sera un point +clef du dépôt. ## The Repository class @@ -33,15 +33,15 @@ of focus with the repository itself. [[autodoc]] huggingface_hub.repository.commits_to_push -## Following asynchronous commands +## Commandes asynchrones -The `Repository` utility offers several methods which can be launched asynchronously: +L'utilitaire `Repository` offre plusieurs méthodes qui peuvent tourner en asynchrone: - `git_push` - `git_pull` - `push_to_hub` -- The `commit` context manager +- Le manager de contexte `commit` -See below for utilities to manage such asynchronous methods. +Regardez ci-dessous les utilities pour gérer ce genre de méthodes asynchrones. [[autodoc]] Repository - commands_failed diff --git a/docs/source/fr/package_reference/space_runtime.md b/docs/source/fr/package_reference/space_runtime.md index 277bff8e7c..956570520e 100644 --- a/docs/source/fr/package_reference/space_runtime.md +++ b/docs/source/fr/package_reference/space_runtime.md @@ -2,17 +2,18 @@ rendered properly in your Markdown viewer. --> -# Managing your Space runtime +# Gérez votre temps d'exécution de votre espace -Check the [`HfApi`] documentation page for the reference of methods to manage your Space on the Hub. +Consultez la page de documentation d'[`HfApi`] pour les références des méthodes pour gérer votre espace +sur le Hub. -- Duplicate a Space: [`duplicate_space`] -- Fetch current runtime: [`get_space_runtime`] -- Manage secrets: [`add_space_secret`] and [`delete_space_secret`] -- Manage hardware: [`request_space_hardware`] -- Manage state: [`pause_space`], [`restart_space`], [`set_space_sleep_time`] +- Dupliquer un espace: [`duplicate_space`] +- Afficher les temps de calcul actuels: [`get_space_runtime`] +- Gérer les secrets: [`add_space_secret`] et [`delete_space_secret`] +- Gérer le hardware: [`request_space_hardware`] +- Gérer l'état: [`pause_space`], [`restart_space`], [`set_space_sleep_time`] -## Data structures +## Structures de données ### SpaceRuntime diff --git a/docs/source/fr/package_reference/tensorboard.md b/docs/source/fr/package_reference/tensorboard.md index 560f03a19f..1119df6a71 100644 --- a/docs/source/fr/package_reference/tensorboard.md +++ b/docs/source/fr/package_reference/tensorboard.md @@ -2,17 +2,18 @@ rendered properly in your Markdown viewer. --> -# TensorBoard logger +# Logger TensorBoard -TensorBoard is a visualization toolkit for machine learning experimentation. TensorBoard allows tracking and visualizing -metrics such as loss and accuracy, visualizing the model graph, viewing histograms, displaying images and much more. -TensorBoard is well integrated with the Hugging Face Hub. The Hub automatically detects TensorBoard traces (such as -`tfevents`) when pushed to the Hub which starts an instance to visualize them. To get more information about TensorBoard -integration on the Hub, check out [this guide](https://huggingface.co/docs/hub/tensorboard). +TensorBoard est un kit d'outils pour l'expérimentation avec les outils de machine learning. TensorBoard permet de traquer +et de visualiser les métriques telles que la fonction de perte la précision, visualiser le graphe, visualisers des +histogrammes, afficher des images et bien plus. TensorBoard est bien intégré avec le Hub Hugging Face. Le Hub détecte +automatiquement les traces de Tensorboard (telles que `tfevents`) lors d'un push vers le Hub qui lance une instance +pour les visualiser. Pour avoir plus d'informations sur l'intégration de TensorBoard avec le Hub, consultez [ce guide](https://huggingface.co/docs/hub/tensorboard). -To benefit from this integration, `huggingface_hub` provides a custom logger to push logs to the Hub. It works as a -drop-in replacement for [SummaryWriter](https://tensorboardx.readthedocs.io/en/latest/tensorboard.html) with no extra -code needed. Traces are still saved locally and a background job push them to the Hub at regular interval. +Pour bénéficier de cette intégration, `huggingface_hub` fournit un logger personnalisé pour push les logs vers le Hub. +Il fonctionne comme un remplacement de [SummaryWriter](https://tensorboardx.readthedocs.io/en/latest/tensorboard.html) +avec aucun code supplémentaire nécessaire. Les traces sont toujours enregistrées en local et sont push vers le Hub +à des intervalles réguliers en arrière plan. ## HFSummaryWriter From c04394933bae1543444e3932966415513834651a Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Tue, 19 Dec 2023 23:27:18 +0100 Subject: [PATCH 022/129] Finished the translation of package reference by translating utilities and webhooks servers --- .../fr/package_reference/tensorboard.md | 6 +- docs/source/fr/package_reference/utilities.md | 155 ++++++++++-------- .../fr/package_reference/webhooks_server.md | 39 +++-- 3 files changed, 108 insertions(+), 92 deletions(-) diff --git a/docs/source/fr/package_reference/tensorboard.md b/docs/source/fr/package_reference/tensorboard.md index 1119df6a71..04662ffd27 100644 --- a/docs/source/fr/package_reference/tensorboard.md +++ b/docs/source/fr/package_reference/tensorboard.md @@ -4,15 +4,15 @@ rendered properly in your Markdown viewer. # Logger TensorBoard -TensorBoard est un kit d'outils pour l'expérimentation avec les outils de machine learning. TensorBoard permet de traquer -et de visualiser les métriques telles que la fonction de perte la précision, visualiser le graphe, visualisers des +TensorBoard est un kit d'outils qui permet de tester des outils de machine learning. TensorBoard permet de traquer +et de visualiser les métriques telles que la fonction de perte la précision, visualiser des graphiques, visualisers des histogrammes, afficher des images et bien plus. TensorBoard est bien intégré avec le Hub Hugging Face. Le Hub détecte automatiquement les traces de Tensorboard (telles que `tfevents`) lors d'un push vers le Hub qui lance une instance pour les visualiser. Pour avoir plus d'informations sur l'intégration de TensorBoard avec le Hub, consultez [ce guide](https://huggingface.co/docs/hub/tensorboard). Pour bénéficier de cette intégration, `huggingface_hub` fournit un logger personnalisé pour push les logs vers le Hub. Il fonctionne comme un remplacement de [SummaryWriter](https://tensorboardx.readthedocs.io/en/latest/tensorboard.html) -avec aucun code supplémentaire nécessaire. Les traces sont toujours enregistrées en local et sont push vers le Hub +sans que vous n'ayez besoin de rajouter du code. Les traces sont toujours enregistrées en local et sont push vers le Hub à des intervalles réguliers en arrière plan. ## HFSummaryWriter diff --git a/docs/source/fr/package_reference/utilities.md b/docs/source/fr/package_reference/utilities.md index 93e73e6c7e..d6fcc68dee 100644 --- a/docs/source/fr/package_reference/utilities.md +++ b/docs/source/fr/package_reference/utilities.md @@ -2,18 +2,19 @@ rendered properly in your Markdown viewer. --> -# Utilities +# Utilitaires -## Configure logging +## Configurer la connexion -The `huggingface_hub` package exposes a `logging` utility to control the logging level of the package itself. -You can import it as such: +Le package `huggingface_hub` expose un utilitaire `logging` qui permet de contrôler le niveau d'authentification +du package. Vous pouvez l'importer ainsi: ```py from huggingface_hub import logging ``` -Then, you may define the verbosity in order to update the amount of logs you'll see: +Ensuite, vous pourrez définir la verbosité afin de changer la quantité de logs que vous +verez: ```python from huggingface_hub import logging @@ -26,16 +27,16 @@ logging.set_verbosity_debug() logging.set_verbosity(...) ``` -The levels should be understood as follows: +Les niveau de verbosité doivent être compris comme suit: -- `error`: only show critical logs about usage which may result in an error or unexpected behavior. -- `warning`: show logs that aren't critical but usage may result in unintended behavior. - Additionally, important informative logs may be shown. -- `info`: show most logs, including some verbose logging regarding what is happening under the hood. - If something is behaving in an unexpected manner, we recommend switching the verbosity level to this in order - to get more information. -- `debug`: show all logs, including some internal logs which may be used to track exactly what's happening - under the hood. +- `error`: ne montre que les logs critiques qui pourrait causer une erreur ou un comportement innatendu. +- `warning`: montre des logs qui ne sont pas critiques mais dont l'utilisation pourrait causer un comportement inattendu. +En plus de ça, des informations importantes pourraient être affichées. +- `info`: montre la plupart des logs, dont des informations de logging donnant des informations sur ce que fait la fonction en arrière plan. +Si quelque chose se comporte de manière innatendue, nous recommendons de passer le niveau de verbosité à `info` afin d'avoir plus +d'informations. +- `debug`: montre tous les logs, dont des logs internes qui pourraient utiliser pour suivre en détail tout ce qui se passe en +arrière plan. [[autodoc]] logging.get_verbosity [[autodoc]] logging.set_verbosity @@ -46,38 +47,41 @@ The levels should be understood as follows: [[autodoc]] logging.disable_propagation [[autodoc]] logging.enable_propagation -### Repo-specific helper methods +### Méthodes d'helper spécifiques au dépôt. -The methods exposed below are relevant when modifying modules from the `huggingface_hub` library itself. -Using these shouldn't be necessary if you use `huggingface_hub` and you don't modify them. +Les méthodes montrés ci-dessous sont pertinentes lors de la modification de modules de la librairie `huggingface_hub`. +Utiliser ces méthodes ne devrait pas être nécessaire si vous utilisez les méthodes`huggingface_hub` +et que vous ne les modifiez pas. [[autodoc]] logging.get_logger -## Configure progress bars +## Configurez la barre de progression -Progress bars are a useful tool to display information to the user while a long-running task is being executed (e.g. -when downloading or uploading files). `huggingface_hub` exposes a [`~utils.tqdm`] wrapper to display progress bars in a -consistent way across the library. +Les barres de progression sont utiles pour afficher des informations à l'utiliser lors de l'exécution d'une longue +tâche (i.e. lors du téléchargement ou de l'upload de fichiers). `huggingface_hub` met à disposition un wrapper +[`~utils.tqdm`] qui permet d'afficher constamment les barres de progressions pour toutes les fonctions de la +librairie. -By default, progress bars are enabled. You can disable them globally by setting `HF_HUB_DISABLE_PROGRESS_BARS` -environment variable. You can also enable/disable them using [`~utils.enable_progress_bars`] and -[`~utils.disable_progress_bars`]. If set, the environment variable has priority on the helpers. +Par défaut, les barres de progressions sont activées. Vous pouvez les désactiver en définissant la +variable d'environnement `HF_HUB_DISABLE_PROGRESS_BARS`. Vous pouvez aussi les activer/désactiver en +utilisant [`~utils.enable_progress_bars`] et [`~utils.disable_progress_bars`]. Si définie, la variable +d'environnement a la priorité sur les helpers. ```py >>> from huggingface_hub import snapshot_download >>> from huggingface_hub.utils import are_progress_bars_disabled, disable_progress_bars, enable_progress_bars ->>> # Disable progress bars globally +>>> # Supprimez toutes les barres de progression >>> disable_progress_bars() ->>> # Progress bar will not be shown ! +>>> # Les barres de progressions ne seront pas affichées ! >>> snapshot_download("gpt2") >>> are_progress_bars_disabled() True ->>> # Re-enable progress bars globally +>>> # Réactivez toutes les barres de progression >>> enable_progress_bars() ``` @@ -93,34 +97,35 @@ True [[autodoc]] huggingface_hub.utils.enable_progress_bars -## Configure HTTP backend +## Configurez un backend HTTPConfigure HTTP backend -In some environments, you might want to configure how HTTP calls are made, for example if you are using a proxy. -`huggingface_hub` let you configure this globally using [`configure_http_backend`]. All requests made to the Hub will -then use your settings. Under the hood, `huggingface_hub` uses `requests.Session` so you might want to refer to the -[`requests` documentation](https://requests.readthedocs.io/en/latest/user/advanced) to learn more about the available -parameters. +Dans certains environnements, vous aurez peut être envie de configurer la manière dont les appels HTTP sont faits, +par exemple, si vous utilisez un proxy. `huggingface_hub` vous permet de configurer ceci en utilisant [`configure_http_backend`]. +Toutes les requêtes faites au Hub utiliseront alors vos paramètres.En arrière-plan, `huggingface_hub` utilise +`requests.Session`, vous aurez donc peut être besoin de consultez la [documentation `requests`](https://requests.readthedocs.io/en/latest/user/advanced) +pour en savoir plus sur les paramètres disponibles. -Since `requests.Session` is not guaranteed to be thread-safe, `huggingface_hub` creates one session instance per thread. -Using sessions allows us to keep the connection open between HTTP calls and ultimately save time. If you are -integrating `huggingface_hub` in a third-party library and wants to make a custom call to the Hub, use [`get_session`] -to get a Session configured by your users (i.e. replace any `requests.get(...)` call by `get_session().get(...)`). +Vu que `requests.Session` n'est pas toujours à l'abri d'un problème de thread, `huggingface_hub` créé une seule +instance de session par thread. L'utilisation de ces sessions permet de garder la connexion ouverte entre les appels HTTP +afin de gagner du temps. Si vous êtes entrain d'intégrer `huggingface_hub` dans une autre librairie tiers et que vous +voulez faire des appels personnalisés vers le Hub, utilisez [`get_session`] pour obtenir une session configurée par +vos utilisateurs (i.e. remplacez tous les appels à `requests.get(...)` par `get_session().get(...)`). [[autodoc]] configure_http_backend [[autodoc]] get_session -## Handle HTTP errors +## Gérez les erreurs HTTP -`huggingface_hub` defines its own HTTP errors to refine the `HTTPError` raised by -`requests` with additional information sent back by the server. +`huggingface_hub` définit ses propres erreurs HTTP pour améliorer le `HTTPError` +levé par `requests` avec des informations supplémentaires envoyées par le serveur. ### Raise for status -[`~utils.hf_raise_for_status`] is meant to be the central method to "raise for status" from any -request made to the Hub. It wraps the base `requests.raise_for_status` to provide -additional information. Any `HTTPError` thrown is converted into a `HfHubHTTPError`. +[`~utils.hf_raise_for_status`] est la méthode centrale pour "raise for status" depuis n'importe quelle +reqête faite au Hub. C'est wrapper autour de `requests.raise_for_status` qui fournit des informations +supplémentaires. Toute `HTTPError` envoyée est convertie en `HfHubHTTPError`. ```py import requests @@ -130,25 +135,25 @@ response = requests.post(...) try: hf_raise_for_status(response) except HfHubHTTPError as e: - print(str(e)) # formatted message - e.request_id, e.server_message # details returned by server + print(str(e)) # message formaté + e.request_id, e.server_message # détails retourné par le serveur - # Complete the error message with additional information once it's raised + # complétez le message d'erreur avec des informations additionnelles une fois que l'erreur est levée e.append_to_message("\n`create_commit` expects the repository to exist.") raise ``` [[autodoc]] huggingface_hub.utils.hf_raise_for_status -### HTTP errors +### Erreurs HTTP -Here is a list of HTTP errors thrown in `huggingface_hub`. +Voici une liste des erreurs HTTP levée dans `huggingface_hub`. #### HfHubHTTPError -`HfHubHTTPError` is the parent class for any HF Hub HTTP error. It takes care of parsing -the server response and format the error message to provide as much information to the -user as possible. +`HfHubHTTPError` est la classe parente de toute erreur HTTP venant de HF Hub. Elle +va parser les réponses du serveur et formater le message d'erreur pour fournir le +plus d'informations possible à l'utilisateur. [[autodoc]] huggingface_hub.utils.HfHubHTTPError @@ -176,34 +181,40 @@ user as possible. [[autodoc]] huggingface_hub.utils.LocalEntryNotFoundError -## Telemetry +## Télémétrie -`huggingface_hub` includes an helper to send telemetry data. This information helps us debug issues and prioritize new features. -Users can disable telemetry collection at any time by setting the `HF_HUB_DISABLE_TELEMETRY=1` environment variable. -Telemetry is also disabled in offline mode (i.e. when setting HF_HUB_OFFLINE=1). +`huggingface_hub` inclus un helper pour envoyer de la donnée de télémétrie. Cette information nous aide à debugger des problèmes +et prioriser les nouvelles fonctionnalités à développer. Les utilisateurs peuvent desactiver la collecte télémetrique à n'importe +quel moment et définissant la variable d'environnement `HF_HUB_DISABLE_TELEMETRY=1`. La télémétrie est aussi desactivée en mode +hors ligne (i.e. en définissant `HF_HUB_OFFLINE=1`). -If you are maintainer of a third-party library, sending telemetry data is as simple as making a call to [`send_telemetry`]. -Data is sent in a separate thread to reduce as much as possible the impact for users. +Si vous êtes mainteneur d'une librairie tiercce, envoyer des données de télémetrie est aussi facile que de faire un appel +à [`send_telemetry`]. Les données sont envoyées dans un thread séparé pour réduire autant que possible l'impact sur +l'expérience utilisateur. [[autodoc]] utils.send_telemetry -## Validators +## Les validateurs -`huggingface_hub` includes custom validators to validate method arguments automatically. -Validation is inspired by the work done in [Pydantic](https://pydantic-docs.helpmanual.io/) -to validate type hints but with more limited features. +`huggingface_hub` offre des validateurs personnalisés pour valider la méthode des +arguements automatiquement. La validation est inspirée du travail fait dans +[Pydantic](https://pydantic-docs.helpmanual.io/) pour valider les hints mais +avec des fonctionnalités plus limitées. -### Generic decorator +### Décorateur générique -[`~utils.validate_hf_hub_args`] is a generic decorator to encapsulate -methods that have arguments following `huggingface_hub`'s naming. By default, all -arguments that has a validator implemented will be validated. +[`~utils.validate_hf_hub_args`] est un décorateur générique pour encapsuler +des méthodes qui ont des arguments qui ont le nom d'`huggingface_hub`. +Par défaut, tous les arguments qui ont un validateur implémenté seront +validés. -If an input is not valid, a [`~utils.HFValidationError`] is thrown. Only -the first non-valid value throws an error and stops the validation process. +Si une entrée n'est pas valide, une erreur [`~utils.HFValidationError`] +est levée. Seul la première valeur invalide déclenche une erreur et +interrompt le processus de validation. -Usage: + +Utilisation: ```py >>> from huggingface_hub.utils import validate_hf_hub_args @@ -244,10 +255,10 @@ UserWarning: Both `token` and `use_auth_token` are passed (...). `use_auth_token [[autodoc]] utils.HFValidationError -### Argument validators +### Validateurs d'arguments -Validators can also be used individually. Here is a list of all arguments that can be -validated. +Les validateurs peuvent aussi être utilisés individuellement. Voici une liste de tous +les arguments qui peuvent être validés. #### repo_id @@ -255,6 +266,6 @@ validated. #### smoothly_deprecate_use_auth_token -Not exactly a validator, but ran as well. +Pas vraiment un validateur, mais utilisé aussi. [[autodoc]] utils.smoothly_deprecate_use_auth_token diff --git a/docs/source/fr/package_reference/webhooks_server.md b/docs/source/fr/package_reference/webhooks_server.md index 3d6847a3e0..1b318d890d 100644 --- a/docs/source/fr/package_reference/webhooks_server.md +++ b/docs/source/fr/package_reference/webhooks_server.md @@ -2,32 +2,36 @@ rendered properly in your Markdown viewer. --> -# Webhooks Server +# Serveurs WebHooks -Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on specific repos or to -all repos belonging to particular users/organizations you're interested in following. To learn -more about webhooks on the Huggingface Hub, you can read the Webhooks [guide](https://huggingface.co/docs/hub/webhooks). +Les webhooks sont un pilier des fonctionnalités autour du MLOps. Ils vous permettent de suivre tous les nouveaux +changements sur des dépôts spécifiques ou sur tous les dépôts appartenants à des utilisateurs/organisations que +vous voulez suivre. Pour en apprendre plus sur les webhooks dans le Hub Huggingface, vous pouvez consulter +le [guide](https://huggingface.co/docs/hub/webhooks) consacré aux webhooks. -Check out this [guide](../guides/webhooks_server) for a step-by-step tutorial on how to setup your webhooks server and -deploy it as a Space. +Consultez ce [guide](../guides/webhooks_server) pour un tutoriel pas à pas sur comment mettre en place votre serveur +webhooks et le déployer en tant qu'espace. -This is an experimental feature. This means that we are still working on improving the API. Breaking changes might be -introduced in the future without prior notice. Make sure to pin the version of `huggingface_hub` in your requirements. -A warning is triggered when you use an experimental feature. You can disable it by setting `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` as an environment variable. +Ceci est une fonctionnalité expérimentale, ce qui signifie que nous travaillons toujours sur l'amélioration de l'API. +De gros changements pourraient être introduit dans le futur sans avertissement préalable. Faites en sorte +d'épingler la version d'`huggingface_hub` dans le requirements. Un avertissement est affiché lorsque vous utilisez +des fonctionnalités expérimentales. Vous pouvez le supprimer en définissant la variable d'environnement +`HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1`. -## Server +## Serveur -The server is a [Gradio](https://gradio.app/) app. It has a UI to display instructions for you or your users and an API -to listen to webhooks. Implementing a webhook endpoint is as simple as decorating a function. You can then debug it -by redirecting the Webhooks to your machine (using a Gradio tunnel) before deploying it to a Space. +Le serveur est une application [Gradio](https://gradio.app/). Il possède une interface pour afficher des instructions pour vous +ou vos utilisateurs et une API pour écouter les webhooks. Implémenter un endpoint de webhook est aussi simple que d'ajouter +un décorateur à une fonction. Vous pouvez ensuite le debugger en redirigeant le webhook vers votre machine (en utilisant +un tunnel Gradio) avant de le déployer sur un espace. ### WebhooksServer @@ -39,11 +43,12 @@ by redirecting the Webhooks to your machine (using a Gradio tunnel) before deplo ## Payload -[`WebhookPayload`] is the main data structure that contains the payload from Webhooks. This is -a `pydantic` class which makes it very easy to use with FastAPI. If you pass it as a parameter to a webhook endpoint, it -will be automatically validated and parsed as a Python object. +[`WebhookPayload`] est la structure de donnée principale qui contient le payload de webhooks. +C'est une classe `pydantic` ce qui la rend très facile à utiliser avec FastAPI. Si vous la +passez en tant que paramètre d'un endpoint webhook, il sera automatiquement validé et parsé en tant qu'objet Python. -For more information about webhooks payload, you can refer to the Webhooks Payload [guide](https://huggingface.co/docs/hub/webhooks#webhook-payloads). +Pour plus d'informations sur les payload webhooks, vous pouvez vous référer au [guide](https://huggingface.co/docs/hub/webhooks#webhook-payloads). +sur les payloads webhooks [[autodoc]] huggingface_hub.WebhookPayload From f2abc0eed9d2fd7d1795e637e622618a3e919fac Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Wed, 20 Dec 2023 17:21:34 +0100 Subject: [PATCH 023/129] Translated model-cards.md --- docs/source/fr/guides/model-cards.md | 155 +++++++++++++++------------ 1 file changed, 84 insertions(+), 71 deletions(-) diff --git a/docs/source/fr/guides/model-cards.md b/docs/source/fr/guides/model-cards.md index 3b2c0d2ebd..0c7818e516 100644 --- a/docs/source/fr/guides/model-cards.md +++ b/docs/source/fr/guides/model-cards.md @@ -2,21 +2,22 @@ rendered properly in your Markdown viewer. --> -# Create and share Model Cards +# Créer en partager des cartes de modèle -The `huggingface_hub` library provides a Python interface to create, share, and update Model Cards. -Visit [the dedicated documentation page](https://huggingface.co/docs/hub/models-cards) -for a deeper view of what Model Cards on the Hub are, and how they work under the hood. +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. -[New (beta)! Try our experimental Model Card Creator App](https://huggingface.co/spaces/huggingface/Model_Cards_Writing_Tool) +[`Nouveaux : Testez notre application de création de carte de modèle`](https://huggingface.co/spaces/huggingface/Model_Cards_Writing_Tool) -## Load a Model Card from the Hub +## Chargez une carte de modèle depuis le Hub -To load an existing card from the Hub, you can use the [`ModelCard.load`] function. Here, we'll load the card from [`nateraw/vit-base-beans`](https://huggingface.co/nateraw/vit-base-beans). +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 @@ -24,16 +25,17 @@ from huggingface_hub import ModelCard card = ModelCard.load('nateraw/vit-base-beans') ``` -This card has some helpful attributes that you may want to access/leverage: - - `card.data`: Returns a [`ModelCardData`] instance with the model card's metadata. Call `.to_dict()` on this instance to get the representation as a dictionary. - - `card.text`: Returns the text of the card, *excluding the metadata header*. - - `card.content`: Returns the text content of the card, *including the metadata header*. +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*. -## Create Model Cards +## Créez des cartes de modèle -### From Text +### Depuis le texte -To initialize a Model Card from text, just pass the text content of the card to the `ModelCard` on init. +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 = """ @@ -42,17 +44,19 @@ language: en license: mit --- -# My Model Card +# Ma carte de modèle """ card = ModelCard(content) card.data.to_dict() == {'language': 'en', 'license': 'mit'} # True ``` -Another way you might want to do this is with f-strings. In the following example, we: +Une autre manière que vous aurez peut-être besoin d'utiliser est celle utilisant les +f-strings. Dans l'exemple suivant nous: -- Use [`ModelCardData.to_yaml`] to convert metadata we defined to YAML so we can use it to insert the YAML block in the model card. -- Show how you might use a template variable via Python f-strings. +- 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') @@ -63,16 +67,16 @@ content = f""" { card_data.to_yaml() } --- -# My Model Card +# Ma carte de modèle -This model created by [@{example_template_var}](https://github.com/{example_template_var}) +Ce modèle créé par [@{example_template_var}](https://github.com/{example_template_var}) """ card = ModelCard(content) print(card) ``` -The above example would leave us with a card that looks like this: +L'exemple ci-dessus nous laisserait avec une carte qui ressemble à ça: ``` --- @@ -81,47 +85,48 @@ license: mit library: timm --- -# My Model Card +# Ma carte de modèle -This model created by [@nateraw](https://github.com/nateraw) +Ce modèle a été créé par [@nateraw](https://github.com/nateraw) ``` -### From a Jinja Template +### Depuis un template Jinja -If you have `Jinja2` installed, you can create Model Cards from a jinja template file. Let's see a basic example: +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 -# Define your jinja template +# Définissez votre template jinja template_text = """ --- {{ card_data }} --- -# Model Card for MyCoolModel +# Carte de modèle de MyCoolModel -This model does this and that. +Ce modèle fait ceci, il peut aussi faire cela... -This model was created by [@{{ author }}](https://hf.co/{{author}}). +Ce modèle a été créé par [@{{ author }}](https://hf.co/{{author}}). """.strip() -# Write the template to a file +# Écrivez le template vers un fichier Path('custom_template.md').write_text(template_text) -# Define card metadata +# Définissez la métadonnée de la carte card_data = ModelCardData(language='en', license='mit', library_name='keras') -# Create card from template, passing it any jinja template variables you want. -# In our case, we'll pass author +# 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) ``` -The resulting card's markdown looks like this: +Le markdown de la carte affiché ressemblera à ça: ``` --- @@ -130,14 +135,15 @@ license: mit library_name: keras --- -# Model Card for MyCoolModel +# Carte de modèle pour MyCoolModel -This model does this and that. +Ce modèle fait ceci et cela. -This model was created by [@nateraw](https://hf.co/nateraw). +Ce modèle a été créé par [@nateraw](https://hf.co/nateraw). ``` -If you update any card.data, it'll reflect in the card itself. +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' @@ -146,7 +152,8 @@ card.data.license = 'apache-2.0' print(card) ``` -Now, as you can see, the metadata header has been updated: +Maintenant, comme vous pouvez le voir, le header de métadonnée +a été mis à jour: ``` --- @@ -155,22 +162,23 @@ license: apache-2.0 library_name: timm --- -# Model Card for MyCoolModel +# Carte de modèle pour MyCoolModel -This model does this and that. +Ce modèle peut faire ceci et cela... -This model was created by [@nateraw](https://hf.co/nateraw). +Ce modèle a été créé par [@nateraw](https://hf.co/nateraw). ``` -As you update the card data, you can validate the card is still valid against the Hub by calling [`ModelCard.validate`]. This ensures that the card passes any validation rules set up on the Hugging Face Hub. +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. -### From the Default Template +### Depuis le template par défaut -Instead of using your own template, you can also use the [default template](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md), which is a fully featured model card with tons of sections you may want to fill out. Under the hood, it uses [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) to fill out a template file. +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. -Note that you will have to have Jinja2 installed to use `from_template`. You can do so with `pip install Jinja2`. +Notez que vous aurez besoin d'avoir Jinja2 installé pour utiliser `from_template`. Vous pouvez le faire avec +`pip install Jinja2`. @@ -187,11 +195,13 @@ card.save('my_model_card_2.md') print(card) ``` -## Share Model Cards +## Partagez une carte de modèle -If you're authenticated with the Hugging Face Hub (either by using `huggingface-cli login` or [`login`]), you can push cards to the Hub by simply calling [`ModelCard.push_to_hub`]. Let's take a look at how to do that... +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: -First, we'll create a new repo called 'hf-hub-modelcards-pr-test' under the authenticated user's namespace: +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 @@ -201,7 +211,7 @@ repo_id = f'{user}/hf-hub-modelcards-pr-test' url = create_repo(repo_id, exist_ok=True) ``` -Then, we'll create a card from the default template (same as the one defined in the section above): +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') @@ -214,41 +224,42 @@ card = ModelCard.from_template( ) ``` -Finally, we'll push that up to the hub +Enfin, nous pushong le tout sur le Hub ```python card.push_to_hub(repo_id) ``` -You can check out the resulting card [here](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/blob/main/README.md). +Vous pouvez vérifier la carte créé [ici](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/blob/main/README.md). -If you instead wanted to push a card as a pull request, you can just say `create_pr=True` when calling `push_to_hub`: +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) ``` -A resulting PR created from this command can be seen [here](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/discussions/3). +Une pull request créé de cette commande peut-être vue [ici](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/discussions/3). -## Update metadata +## Mettre à jour les métadonnées -In this section we will see what metadata are in repo cards and how to update them. +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` refers to a hash map (or key value) context that provides some high-level information about a model, dataset or Space. That information can include details such as the model's `pipeline type`, `model_id` or `model_description`. For more detail you can take a look to these guides: [Model Card](https://huggingface.co/docs/hub/model-cards#model-card-metadata), [Dataset Card](https://huggingface.co/docs/hub/datasets-cards#dataset-card-metadata) and [Spaces Settings](https://huggingface.co/docs/hub/spaces-settings#spaces-settings). -Now lets see some examples on how to update those metadata. +`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 espace. 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. -Let's start with a first example: +Commençons avec un premier exemple: ```python >>> from huggingface_hub import metadata_update >>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"}) ``` -With these two lines of code you will update the metadata to set a new `pipeline_tag`. +Avec ces deux lignes de code vous mettez à jour la métadonnée pour définir un nouveau `pipeline_tag`. -By default, you cannot update a key that is already existing on the card. If you want to do so, you must pass -`overwrite=True` explicitly: +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 @@ -256,22 +267,23 @@ By default, you cannot update a key that is already existing on the card. If you >>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True) ``` -It often happen that you want to suggest some changes to a repository -on which you don't have write permission. You can do that by creating a PR on that repo which will allow the owners to -review and merge your suggestions. +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) ``` -## Include Evaluation Results +## Inclure des résultats d'évaluation -To include evaluation results in the metadata `model-index`, you can pass an [`EvalResult`] or a list of `EvalResult` with your associated evaluation results. Under the hood it'll create the `model-index` when you call `card.data.to_dict()`. For more information on how this works, you can check out [this section of the Hub docs](https://huggingface.co/docs/hub/models-cards#evaluation-results). +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). -Note that using this function requires you to include the `model_name` attribute in [`ModelCardData`]. +Notez qu'utiliser cette fonction vous demande d'inclure l'attribut `model_name` dans [`ModelCardData`]. @@ -293,7 +305,7 @@ card = ModelCard.from_template(card_data) print(card.data) ``` -The resulting `card.data` should look like this: +Le `card.data` résultant devrait ressembler à ceci: ``` language: en @@ -311,7 +323,8 @@ model-index: value: 0.7 ``` -If you have more than one evaluation result you'd like to share, just pass a list of `EvalResult`: +Si vous avez plus d'un résultat d'évaluation que vous voulez partager, passez simplement une liste +d'`EvalResult`: ```python card_data = ModelCardData( @@ -339,7 +352,7 @@ card = ModelCard.from_template(card_data) card.data ``` -Which should leave you with the following `card.data`: +Ce qui devrait donner le `card.data` suivant: ``` language: en From 2aff74fd164c9be1c446407d51154d93358f06a7 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Wed, 27 Dec 2023 22:58:21 +0100 Subject: [PATCH 024/129] Translated collections.md --- docs/source/fr/guides/collections.md | 98 +++++++++++++++------------- 1 file changed, 51 insertions(+), 47 deletions(-) diff --git a/docs/source/fr/guides/collections.md b/docs/source/fr/guides/collections.md index 5dd408de09..98412867e6 100644 --- a/docs/source/fr/guides/collections.md +++ b/docs/source/fr/guides/collections.md @@ -4,19 +4,19 @@ rendered properly in your Markdown viewer. # Collections -A collection is a group of related items on the Hub (models, datasets, Spaces, papers) that are organized together on the same page. Collections are useful for creating your own portfolio, bookmarking content in categories, or presenting a curated list of items you want to share. Check out this [guide](https://huggingface.co/docs/hub/collections) to understand in more detail what collections are and how they look on the Hub. +Une collection est un groupe d'objets reliés entre eux sur le Hub (par exemple des modèles, des datases, des espaces 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. -You can directly manage collections in the browser, but in this guide, we will focus on how to manage it programmatically. +Vous pouvez gérer directement les collections depuis le navigateur, mais dans ce guide, nous nous concetrerons sur la gestion avec du code. -## Fetch a collection +## Afficher une collection -Use [`get_collection`] to fetch your collections or any public ones. You must have the collection's *slug* to retrieve a collection. A slug is an identifier for a collection based on the title and a unique ID. You can find the slug in the URL of the collection page. +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 de l'ID de la collection. Vous pouvez trouver le slug dans l'URL de la page dédiée à la collection.
-Let's fetch the collection with, `"TheBloke/recent-models-64f9a55bb3115b4f513ec026"`: +Affichons la collection qui a pour slug `"TheBloke/recent-models-64f9a55bb3115b4f513ec026"`: ```py >>> from huggingface_hub import get_collection @@ -44,30 +44,30 @@ CollectionItem( ) ``` -The [`Collection`] object returned by [`get_collection`] contains: -- high-level metadata: `slug`, `owner`, `title`, `description`, etc. -- a list of [`CollectionItem`] objects; each item represents a model, a dataset, a Space, or a paper. +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 espace ou un article. -All collection items are guaranteed to have: -- a unique `item_object_id`: this is the id of the collection item in the database -- an `item_id`: this is the id on the Hub of the underlying item (model, dataset, Space, paper); it is not necessarily unique, and only the `item_id`/`item_type` pair is unique -- an `item_type`: model, dataset, Space, paper -- the `position` of the item in the collection, which can be updated to reorganize your collection (see [`update_collection_item`] below) +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, espace 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, espace 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) -A `note` can also be attached to the item. This is useful to add additional information about the item (a comment, a link to a blog post, etc.). The attribute still has a `None` value if an item doesn't have a note. +Une note peut aussi être attachées à un objet. Ceci 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. -In addition to these base attributes, returned items can have additional attributes depending on their type: `author`, `private`, `lastModified`, `gated`, `title`, `likes`, `upvotes`, etc. None of these attributes are guaranteed to be returned. +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. -## List collections +## Lister les collections -We can also retrieve collections using [`list_collections`]. Collections can be filtered using some parameters. Let's list all the collections from the user [`teknium`](https://huggingface.co/teknium). +Nous pouvons 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") ``` -This returns an iterable of `Collection` objects. We can iterate over them to print, for example, the number of upvotes for each collection. +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: @@ -78,11 +78,12 @@ Number of upvotes: 5 -When listing collections, the item list per collection is truncated to 4 items maximum. To retrieve all items from a collection, you must use [`get_collection`]. +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`] -It is possible to do more advanced filtering. Let's get all collections containing the model [TheBloke/OpenHermes-2.5-Mistral-7B-GGUF](https://huggingface.co/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF), sorted by trending, and limit the count to 5. +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é 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: @@ -94,27 +95,29 @@ gnomealone/need-to-test-652007226c6ce4cdacf9c233 Crataco/favorite-7b-models-651944072b4fffcb41f8b568 ``` -Parameter `sort` must be one of `"last_modified"`, `"trending"` or `"upvotes"`. Parameter `item` accepts any particular item. For example: +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"` -For more details, please check out [`list_collections`] reference. +Pour plus de détails, consultez la référence à [`list_collections`]. -## Create a new collection +## Créer une nouvelle collection -Now that we know how to get a [`Collection`], let's create our own! Use [`create_collection`] with a title and description. To create a collection on an organization page, pass `namespace="my-cool-org"` when creating the collection. Finally, you can also create private collections by passing `private=True`. +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="Portfolio of models, papers and demos I presented at 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 serez maintenant capable de vous référer à cette collection en utilisant son `slug`. It will return a [`Collection`] object with the high-level metadata (title, description, owner, etc.) and an empty list of items. You will now be able to refer to this collection using it's `slug`. ```py @@ -128,13 +131,13 @@ It will return a [`Collection`] object with the high-level metadata (title, desc 'https://huggingface.co/collections/owner/iccv-2023-15e23b46cb98efca45' ``` -## Manage items in a collection +## Gérer des objets dans une collection -Now that we have a [`Collection`], we want to add items to it and organize them. +Maintenant que nous notre [`Collection`], nous allons y ajouter des objets et les organiser. -### Add items +### Ajouter des objets -Items have to be added one by one using [`add_collection_item`]. You only need to know the `collection_slug`, `item_id` and `item_type`. Optionally, you can also add a `note` to the item (500 characters maximum). +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 un `note` à l'objet (500 caractères max). ```py >>> from huggingface_hub import create_collection, add_collection_item @@ -151,23 +154,24 @@ Items have to be added one by one using [`add_collection_item`]. You only need t ... 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") # same item_id, different item_type +>>> add_collection_item(collection.slug, item_id="warp-ai/wuerstchen", item_type="space") # même item_id, mais l'item_type est différent ``` -If an item already exists in a collection (same `item_id`/`item_type` pair), an HTTP 409 error will be raised. You can choose to ignore this error by setting `exists_ok=True`. +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. -### Add a note to an existing item +### Ajouter une note à un objet de la collection -You can modify an existing item to add or modify the note attached to it using [`update_collection_item`]. Let's reuse the example above: +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 -# Fetch collection with newly added items +# 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) -# Add note the `lmsys-chat-1m` dataset +# Ajoute une note au dataset `lmsys-chat-1m` >>> update_collection_item( ... collection_slug=collection_slug, ... item_object_id=collection.items[2].item_object_id, @@ -175,20 +179,20 @@ You can modify an existing item to add or modify the note attached to it using [ ... ) ``` -### Reorder items +### Remettre en ordre les objets -Items in a collection are ordered. The order is determined by the `position` attribute of each item. By default, items are ordered by appending new items at the end of the collection. You can update the order using [`update_collection_item`] the same way you would add a note. +Les objets dans une collection sont rangés dans un ordre. L'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 -Let's reuse our example above: +Réutilisons notre exemple ci-dessus: ```py >>> from huggingface_hub import get_collection, update_collection_item -# Fetch collection +# Récupére la collection >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) -# Reorder to place the two `Wuerstchen` items together +# Change l'ordre pour placer les deux objets `Wuerstchen` ensemble >>> update_collection_item( ... collection_slug=collection_slug, ... item_object_id=collection.items[3].item_object_id, @@ -196,28 +200,28 @@ Let's reuse our example above: ... ) ``` -### Remove items +### Supprimer des objets -Finally, you can also remove an item using [`delete_collection_item`]. +Enfin, vous pouvez aussi supprimer un objet en utilisant [`delete_collection_item`]. ```py >>> from huggingface_hub import get_collection, update_collection_item -# Fetch collection +# Récupére la collection >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) -# Remove `coqui/xtts` Space from the list +# Supprimer l'espace `coqui/xtts` de la liste >>> delete_collection_item(collection_slug=collection_slug, item_object_id=collection.items[0].item_object_id) ``` -## Delete collection +## Supprimer une collection -A collection can be deleted using [`delete_collection`]. +Une collection peut être supprimée en utilisant [`delete_collection`]. -This is a non-revertible action. A deleted collection cannot be restored. +Cette action est irréversible. Une collection supprimée ne peut pas être restaurée. From 9189ef80fbfdfeaa6fa1f97185ca4aba1371507b Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Thu, 28 Dec 2023 17:46:06 +0100 Subject: [PATCH 025/129] translated community.md --- docs/source/fr/guides/community.md | 64 ++++++++++++++++-------------- 1 file changed, 34 insertions(+), 30 deletions(-) diff --git a/docs/source/fr/guides/community.md b/docs/source/fr/guides/community.md index 0baa34e4e5..373c70233c 100644 --- a/docs/source/fr/guides/community.md +++ b/docs/source/fr/guides/community.md @@ -2,15 +2,16 @@ rendered properly in your Markdown viewer. --> -# Interact with Discussions and Pull Requests +# Intéragisser avec les discussions et les pull requests -The `huggingface_hub` library provides a Python interface to interact with Pull Requests and Discussions on the Hub. -Visit [the dedicated documentation page](https://huggingface.co/docs/hub/repositories-pull-requests-discussions) -for a deeper view of what Discussions and Pull Requests on the Hub are, and how they work under the hood. +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. -## Retrieve Discussions and Pull Requests from the Hub +## Récupérer les discussions et les pull requests depuis le Hub -The `HfApi` class allows you to retrieve Discussions and Pull Requests on a given repo: +La classe `HfApi` vous permet de récupérer des discussions et des pulls requests d'un dépôt en particulier: ```python >>> from huggingface_hub import get_repo_discussions @@ -25,7 +26,8 @@ The `HfApi` class allows you to retrieve Discussions and Pull Requests on a give [...] ``` -`HfApi.get_repo_discussions` supports filtering by author, type (Pull Request or Discussion) and status (`open` or `closed`): +`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 @@ -40,16 +42,16 @@ The `HfApi` class allows you to retrieve Discussions and Pull Requests on a give # 19 - Add Flax weights by ArthurZ, pr: True ``` -`HfApi.get_repo_discussions` returns a [generator](https://docs.python.org/3.7/howto/functional.html#generators) that yields -[`Discussion`] objects. To get all the Discussions in a single list, run: +`HfApi.get_repo_discussions` retourne 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")) ``` -The [`Discussion`] object returned by [`HfApi.get_repo_discussions`] contains high-level overview of the -Discussion or Pull Request. You can also get more detailed information using [`HfApi.get_discussion_details`]: +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 @@ -75,22 +77,23 @@ DiscussionWithDetails( ) ``` -[`HfApi.get_discussion_details`] returns a [`DiscussionWithDetails`] object, which is a subclass of [`Discussion`] -with more detailed information about the Discussion or Pull Request. Information includes all the comments, status changes, -and renames of the Discussion via [`DiscussionWithDetails.events`]. +[`HfApi.get_discussion_details`] retourne un objet [`DiscuccionWithDetails`], qui est une sous-classe de [`Discussion`] +avec des informations plus détaillées sur la discussion ou la pull request. Les informations incluent tous les commentaires, +les changements de statut, et les changements de nom de la discussion via [`DiscussionWithDetails.events`]. -In case of a Pull Request, you can retrieve the raw git diff with [`DiscussionWithDetails.diff`]. All the commits of the -Pull Request are listed in [`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`]. -## Create and edit a Discussion or Pull Request programmatically +## Créer et changer une discussion ou une pull request par le code -The [`HfApi`] class also offers ways to create and edit Discussions and Pull Requests. -You will need an [access token](https://huggingface.co/docs/hub/security-tokens) to create and edit Discussions -or Pull Requests. +La classe [`HfApi`] fournit aussi des manière de 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 des discussions ou des pull requests. -The simplest way to propose changes on a repo on the Hub is via the [`create_commit`] API: just -set the `create_pr` parameter to `True`. This parameter is also available on other methods that wrap [`create_commit`]: +La manière la plus simple de proposer des changements sur un dépôt du Hub est d'utiliser l'API [`create_commit`]: +fixez 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`] @@ -108,8 +111,9 @@ set the `create_pr` parameter to `True`. This parameter is also available on oth ... ) ``` -You can also use [`HfApi.create_discussion`] (respectively [`HfApi.create_pull_request`]) to create a Discussion (respectively a Pull Request) on a repo. -Opening a Pull Request this way can be useful if you need to work on changes locally. Pull Requests opened this way will be in `"draft"` mode. +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 @@ -129,7 +133,7 @@ DiscussionWithDetails(...) DiscussionWithDetails(..., is_pull_request=True) ``` -Managing Pull Requests and Discussions can be done entirely with the [`HfApi`] class. For example: +La gestion des pull requests et des discussions peut être réalisée entièrement avec la classe [`HfApi`]. Par exemple: * [`comment_discussion`] to add comments * [`edit_discussion_comment`] to edit comments @@ -138,12 +142,12 @@ Managing Pull Requests and Discussions can be done entirely with the [`HfApi`] c * [`merge_pull_request`] to merge a Pull Request -Visit the [`HfApi`] documentation page for an exhaustive reference of all available methods. +Consultez la page de documentation [`HfApi`] pour une référence exhaustive de toutes les méthodes disponibles. -## Push changes to a Pull Request +## Push les changement vers une pull request -*Coming soon !* +*Arrive bientôt !* -## See also +## Voir aussi -For a more detailed reference, visit the [Discussions and Pull Requests](../package_reference/community) and the [hf_api](../package_reference/hf_api) documentation page. +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). From df129263aa3f0744c81c8af9f886fc8ea292993b Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Fri, 29 Dec 2023 22:35:29 +0100 Subject: [PATCH 026/129] Translated download.md, corrected an error in the english version and changed a n inacurrate translation in other files --- docs/source/en/guides/download.md | 2 +- docs/source/fr/guides/cli.md | 2 +- docs/source/fr/guides/community.md | 4 +- docs/source/fr/guides/download.md | 190 +++++++++++++++-------------- 4 files changed, 102 insertions(+), 96 deletions(-) diff --git a/docs/source/en/guides/download.md b/docs/source/en/guides/download.md index 459cdd7130..0665dd361e 100644 --- a/docs/source/en/guides/download.md +++ b/docs/source/en/guides/download.md @@ -191,7 +191,7 @@ If you are running on a machine with high bandwidth, you can increase your downl -Progress bars are supported in `hf_transfer` starting from version `0.1.4`. Consider upgrading (`pip install -U hf-transfer`) if you plan to enable faster downloads. +Progress bars are supported in `hf_transfer` starting from version `0.1.4`. Consider upgrading (`pip install -U hf_transfer`) if you plan to enable faster downloads. diff --git a/docs/source/fr/guides/cli.md b/docs/source/fr/guides/cli.md index 51a89a5fc2..5c96de0e27 100644 --- a/docs/source/fr/guides/cli.md +++ b/docs/source/fr/guides/cli.md @@ -128,7 +128,7 @@ Cette commande ne vous déconnectera pas si vous vous êtes connecté en utilisa Utilisez la commande `huggingface-cli download` pour télécharger des fichiers directement depuis le Hub. En interne, 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 -retourné dans le terminal. Dans les exemples ci-dessous, nous verrons les cas d'usage les plus communs. Pour afficher la liste des +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 diff --git a/docs/source/fr/guides/community.md b/docs/source/fr/guides/community.md index 373c70233c..21fee9742c 100644 --- a/docs/source/fr/guides/community.md +++ b/docs/source/fr/guides/community.md @@ -42,7 +42,7 @@ La classe `HfApi` vous permet de récupérer des discussions et des pulls reques # 19 - Add Flax weights by ArthurZ, pr: True ``` -`HfApi.get_repo_discussions` retourne un [générateur](https://docs.python.org/3.7/howto/functional.html#generators) qui prend +`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 @@ -77,7 +77,7 @@ DiscussionWithDetails( ) ``` -[`HfApi.get_discussion_details`] retourne un objet [`DiscuccionWithDetails`], qui est une sous-classe de [`Discussion`] +[`HfApi.get_discussion_details`] renvoie un objet [`DiscuccionWithDetails`], qui est une sous-classe de [`Discussion`] avec des informations plus détaillées sur la discussion ou la pull request. Les informations incluent tous les commentaires, les changements de statut, et les changements de nom de la discussion via [`DiscussionWithDetails.events`]. diff --git a/docs/source/fr/guides/download.md b/docs/source/fr/guides/download.md index 459cdd7130..f90a3b4910 100644 --- a/docs/source/fr/guides/download.md +++ b/docs/source/fr/guides/download.md @@ -2,180 +2,184 @@ rendered properly in your Markdown viewer. --> -# Download files from the Hub +# Télécharger des fichiers du Hub -The `huggingface_hub` library provides functions to download files from the repositories -stored on the Hub. You can use these functions independently or integrate them into your -own library, making it more convenient for your users to interact with the Hub. This -guide will show you how to: +La librairie `huggingface_hub` fournit des fonctions pour télécharger des fichiers depuis +les dépôts stockés sur le Hub. Vous pouvez utiliser ces fonctions directement ou les intégrer +dans votre propre librairie, pour rendre l'intéraction entre vos utilisateurs et le Hub +plus simple. Ce guide vous montrera comment: -* Download and cache a single file. -* Download and cache an entire repository. -* Download files to a local folder. +* Télécharger et mettre en cache un fichier +* Télécharger et mettre en cache un dépôt entier +* Télécharger des fichiers dans un dossier local -## Download a single file +## Télécharger un fichier -The [`hf_hub_download`] function is the main function for downloading files from the Hub. -It downloads the remote file, caches it on disk (in a version-aware way), and returns its local file path. +La fonction [`hf_hub_download`] est la fonction principale pour télécharger des fichiers du Hub. +Elle télécharge le fichier, le met en cache sur le disque (en prenant en compte les versions) +et retourne le chemin vers le fichier local téléchargé. -The returned filepath is a pointer to the HF local cache. Therefore, it is important to not modify the file to avoid -having a corrupted cache. If you are interested in getting to know more about how files are cached, please refer to our -[caching guide](./manage-cache). +Le chemin retourné est un pointeur vers le cache local HF. Par conséquent, il est important de ne pas modifier le fichier +pour éviter de corrompre le cache. Si vous voulez en apprendre plus sur la manière dont les fichiers sont mis en cache, +consultez notre [guide dédié au cache](./manage-cache). -### From latest version +### Télécharger la dernière version -Select the file to download using the `repo_id`, `repo_type` and `filename` parameters. By default, the file will -be considered as being part of a `model` repo. +Sélectionnez le fichier à télécharger en utilisant les paramètres `repo_id`, `repo_type` et `filename`. Par défaut, +le fichier sera considéré comme appartenant à un dépôt contenant des objets de type `model`. ```python >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") '/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' -# Download from a dataset +# Télécharger depuis un dataset >>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") '/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' ``` -### From specific version +### Télécharger une version spécifique -By default, the latest version from the `main` branch is downloaded. However, in some cases you want to download a file -at a particular version (e.g. from a specific branch, a PR, a tag or a commit hash). -To do so, use the `revision` parameter: +Par défaut, la dernière version de la branche `main` est téléchargée. Cependant, dans certains cas, vous aurez besoin +de télécharger un fichier ayant une version particulière (i.e. d'une branche spécifique, une pull request, un tag, +ou un hash de commit). +Pour ce faire, utilisez le paramètre `revision`: ```python -# Download from the `v1.0` tag +# Télécharger à partir de tag `v1.0` >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") -# Download from the `test-branch` branch +# Télécharger à partir de la branche `test-branch` >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") -# Download from Pull Request #3 +# Téléchargerà partir de la pull request #3 >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") -# Download from a specific commit hash +# Télécharger à partir d'un hash de commit spécifique >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") ``` -**Note:** When using the commit hash, it must be the full-length hash instead of a 7-character commit hash. +**Note:** Lorsque vous utilisez le hash de commit, vous devez renseigner le hash complet et pas le hash de commit de 7 caractères. -### Construct a download URL +### Construire un URL de téléchargement -In case you want to construct the URL used to download a file from a repo, you can use [`hf_hub_url`] which returns a URL. -Note that it is used internally by [`hf_hub_download`]. +Si vous voulez construire l'URL utilisé pour télécharger un fichier depuis un dépôt, vous pouvez utiliser [`hf_hub_url`] +qui renvoie un URL. Notez que cette méthode est utilisée en interne par [`hf_hub_download`]. -## Download an entire repository +## Télécharger un dépôt entier -[`snapshot_download`] downloads an entire repository at a given revision. It uses internally [`hf_hub_download`] which -means all downloaded files are also cached on your local disk. Downloads are made concurrently to speed-up the process. +[`snapshot_download`] télécharge un dépôt entier à une révision donnée. Cette méthode utilise en arrière-plan +[`hf_hub_download`] ce qui signifie que tous les fichiers téléchargés sont aussi mis en cache sur votre disque en local. +Les téléchargements sont faits en parallèle pour rendre le processus plus rapide. -To download a whole repository, just pass the `repo_id` and `repo_type`: +Pour télécharger un dépôt entier, passez simplement le `repo_id` et le `repo_type`: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp") '/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' -# Or from a dataset +# Ou depuis un dataset >>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") '/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' ``` -[`snapshot_download`] downloads the latest revision by default. If you want a specific repository revision, use the -`revision` parameter: +[`snapshot_download`] télécharge la dernière révision par défaut. Si vous voulez une révision spécifique, utilisez +le paramètre `revision`: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") ``` -### Filter files to download +### Filtrer les fichiers à télécharger -[`snapshot_download`] provides an easy way to download a repository. However, you don't always want to download the -entire content of a repository. For example, you might want to prevent downloading all `.bin` files if you know you'll -only use the `.safetensors` weights. You can do that using `allow_patterns` and `ignore_patterns` parameters. +[`snapshot_download`] offre une manière simple de télécharger un dépôt. Cependant, vous ne voudrait pas constamment +télécharger tout le contenu d'un dépôt. Par exemple, vous n'aurez peut-être pas envie de télécharger tous les fichiers +`.bin` si vous savez que vous utiliserez uniquement les poids du `.safetensors`. Vous pouvez faire ceci en utilisant +les paramètres `allow_patterns` et `ignore_patterns`. -These parameters accept either a single pattern or a list of patterns. Patterns are Standard Wildcards (globbing -patterns) as documented [here](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). The pattern matching is -based on [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). +Ces paramètres acceptent un pattern ou une liste de patterns. Les patterns sont des wildcards standard, comme précisé +[ici](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). Le matching de pattern utilise [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). -For example, you can use `allow_patterns` to only download JSON configuration files: +Par exemple, vous pouvez utiliser `allow_patterns` pour ne télécharger que les fichiers de configuration JSON: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json") ``` -On the other hand, `ignore_patterns` can exclude certain files from being downloaded. The -following example ignores the `.msgpack` and `.h5` file extensions: +A l'opposé, `ignore_patterns` empêche certains fichiers d'être téléchargés. L'exemple +suivant ignore les fichiers ayant pour extension `.msgpack` et `.h5`: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"]) ``` -Finally, you can combine both to precisely filter your download. Here is an example to download all json and markdown -files except `vocab.json`. +Enfin, vous pouvez combiner les deux pour filtrer avec précision vos téléchargements. voici un exemple pour télécharger +tous les markdowns json à l'exception de `vocab.json` ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json") ``` -## Download file(s) to local folder - -The recommended (and default) way to download files from the Hub is to use the [cache-system](./manage-cache). -You can define your cache location by setting `cache_dir` parameter (both in [`hf_hub_download`] and [`snapshot_download`]). - -However, in some cases you want to download files and move them to a specific folder. This is useful to get a workflow -closer to what `git` commands offer. You can do that using the `local_dir` and `local_dir_use_symlinks` parameters: -- `local_dir` must be a path to a folder on your system. The downloaded files will keep the same file structure as in the -repo. For example if `filename="data/train.csv"` and `local_dir="path/to/folder"`, then the returned filepath will be -`"path/to/folder/data/train.csv"`. -- `local_dir_use_symlinks` defines how the file must be saved in your local folder. - - The default behavior (`"auto"`) is to duplicate small files (<5MB) and use symlinks for bigger files. Symlinks allow - to optimize both bandwidth and disk usage. However manually editing a symlinked file might corrupt the cache, hence - the duplication for small files. The 5MB threshold can be configured with the `HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD` - environment variable. - - If `local_dir_use_symlinks=True` is set, all files are symlinked for an optimal disk space optimization. This is - for example useful when downloading a huge dataset with thousands of small files. - - Finally, if you don't want symlinks at all you can disable them (`local_dir_use_symlinks=False`). The cache directory - will still be used to check wether the file is already cached or not. If already cached, the file is **duplicated** - from the cache (i.e. saves bandwidth but increases disk usage). If the file is not already cached, it will be - downloaded and moved directly to the local dir. This means that if you need to reuse it somewhere else later, it - will be **re-downloaded**. - -Here is a table that summarizes the different options to help you choose the parameters that best suit your use case. +## Télécharger un ou plusieurs fichier(s) vers un dossier local + +La manière recommandée (et utilisée par défaut) pour télécharger des fichiers depuis les Hub est d'utiliser +le [cache-system](./manage-cache). Vous pouvez définir le chemin vers votre cache en définissant le +paramètre `cache_dir` (dans [`hf_hub_download`] et [`snapshot_download`]). + +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 une pratique utile pour créer un workflow plus proche de ce qu'on peut retrouver avec les commande `git`. Vous +pouvez faire ceci en utilisant les paramètres `local_dir` et `local_dir_use_symlinks`: +- `local_dir` doit être un chemin vers un dossier de votre système. Les fichiers téléchargés garderont la même structure +de fichier que dans le dépôt. Par exemple, si `filename="data/train.csv"` et `local_dir="path/to/folder"`, alors le +chemin renvoyé sera `"path/to/folder/data/train.csv"`. +- `local_dir_use_symlinks` définit comment le fichier doit être enregistré sur votre dossier local. + - Le comportement par défaut (`"auto"`), dupliquera les fichiers peu volumineux (<5MB) et utilise les symlinks pour + les fichiers plus gros. Les symlinks permettent d'optimiser à la fois la bande passante et l'utilisation du disque. + Cependant, éditer manuellement un fichier sous symlink pourrait corrompre le cache, d'où la duplication pour des + petits fichiers. Le seuil de 5MB peut être configuré avec la variable d'environnement`HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD`. + - Si `local_dir_use_symlinks=True` est définit, alors tous les fichiers seront sous symlink pour une utilisation + optimal de l'espace disque? C'est par exemple utile lors du téléchargement d'un dataset très volumineux contenant + des milliers de petits fichiers. + - Enfin, si vous ne voulez pas utiliser de symlink du tout, vous pouvez les désactier (`local_dir_use_symlinks=False`). + Le chemin du cache sera toujours utilisé afin de vérifier si le fichier est déjà en cache ou pas. Si ce dernier + n'est pas déjà en cache, il sera téléchargé et déplacé directement vers le chemin local. Ce qui signifie que si + vous avez besoin de le réutiliser ailleurs, il sera **retéléchargé** + +Voici un table qui résume les différentes options pour vous aider à choisir les paramètres qui collent le mieux à votre situation. -| Parameters | File already cached | Returned path | Can read path? | Can save to path? | Optimized bandwidth | Optimized disk usage | +| Paramètre | Fichier déjà en cahce | Chemin renvoyé | Peut-on lire le chemin? | Pouvez vous sauvegarder le chemin | Bande passante optimisée | Utilisation du disque optimisée | |---|:---:|:---:|:---:|:---:|:---:|:---:| -| `local_dir=None` | | symlink in cache | ✅ | ❌
_(save would corrupt the cache)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | file or symlink in folder | ✅ | ✅ _(for small files)_
⚠️ _(for big files do not resolve path before saving)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | symlink in folder | ✅ | ⚠️
_(do not resolve path before saving)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | No | file in folder | ✅ | ✅ | ❌
_(if re-run, file is re-downloaded)_ | ⚠️
(multiple copies if ran in multiple folders) | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | Yes | file in folder | ✅ | ✅ | ⚠️
_(file has to be cached first)_ | ❌
_(file is duplicated)_ | +| `local_dir=None` | | symlink en cache | ✅ | ❌
_(sauvegarder corromprait le cache)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | fichier ou symlink dans un dossier | ✅ | ✅ _(for small files)_
⚠️ _(for big files do not resolve path before saving)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | symlink dans un dossier | ✅ | ⚠️
_(do not resolve path before saving)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | Non | fichier dans un dossier | ✅ | ✅ | ❌
_(en cas de re-run, le fichier est retéléchargé)_ | ⚠️
(plusieurs copies si lancé dans plusieurs dossiers) | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | oui | fichier dans un dossier | ✅ | ✅ | ⚠️
_(le fichier doit être mis en cache d'abord)_ | ❌
_(le fichier est dupliqué)_ | -**Note:** if you are on a Windows machine, you need to enable developer mode or run `huggingface_hub` as admin to enable -symlinks. Check out the [cache limitations](../guides/manage-cache#limitations) section for more details. +**Note:** si vous utilisez une machien Windows, vous devez activer le mode développeur ou lancer `huggingface_hub` en tant qu'administrateur pour activer les syymlinks. Consultez la section [limitations du cache](../guides/manage-cache#limitations) -## Download from the CLI +## Télécharger depuis le CLI -You can use the `huggingface-cli download` command from the terminal to directly download files from the Hub. -Internally, it uses the same [`hf_hub_download`] and [`snapshot_download`] helpers described above and prints the -returned path to the terminal. +Vous pouvez utiliser la commande `huggingface-cli download` depuis un terminal pour télécharger directement des +fichiers du Hub. En interne, cette commande utilise les même helpers [`hf_hub_download`] et [`snapshot_download`] +décrits ci-dessus et affiche le chemin renvoyé dans le terminal. ```bash >>> huggingface-cli download gpt2 config.json /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` -You can download multiple files at once which displays a progress bar and returns the snapshot path in which the files -are located: +Vous pouvez télécharger plusieurs fichiers d'un coup ce qui affiche une barre de chargement et renvoie le chemin du +snapshot dans lequel les fichiers sont localisés! ```bash >>> huggingface-cli download gpt2 config.json model.safetensors @@ -183,20 +187,22 @@ Fetching 2 files: 100%|███████████████████ /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` -For more details about the CLI download command, please refer to the [CLI guide](./cli#huggingface-cli-download). +Pour plus de détails sur la commande download du CLI, veuillez consulter le [guide CLI](./cli#huggingface-cli-download). -## Faster downloads +## Téléchargements plus rapides -If you are running on a machine with high bandwidth, you can increase your download speed with [`hf_transfer`](https://github.com/huggingface/hf_transfer), a Rust-based library developed to speed up file transfers with the Hub. To enable it, install the package (`pip install hf_transfer`) and set `HF_HUB_ENABLE_HF_TRANSFER=1` as an environment variable. +Si vous tuilisez une machine avec une bande passante plus large, vous pouvez augmenter votre vitesse de téléchargement en utilisant [`hf_transfer`], +une librairie basée sur Rust développée pour accélérer le transfer de fichiers avec le Hub. Pour l'activer, installez le package (`pip install hf_transfer`) et définissez set `HF_HUB_ENABLE_HF_TRANSFER=1` en tant que variable d'environnement -Progress bars are supported in `hf_transfer` starting from version `0.1.4`. Consider upgrading (`pip install -U hf-transfer`) if you plan to enable faster downloads. +Les barres de chargement ne fonctionnent avec `hf_transfer` qu'à partir de la version `0.1.4`. Mettez à jour la version (`pip install -U hf_transfer`) +si vous comptez utiliser cette librairie. -`hf_transfer` is a power user tool! It is tested and production-ready, but it lacks user-friendly features like advanced error handling or proxies. For more details, please take a look at this [section](https://huggingface.co/docs/huggingface_hub/hf_transfer). +`hf_transfer` est un outil très puissant! Il a été testé et est prêt à être utilisé en production, mais il lui manque certaines 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). \ No newline at end of file From 621b58c6018292c049b1719ffd31019af683e9fa Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 30 Dec 2023 13:08:06 +0100 Subject: [PATCH 027/129] translated hf_file_system --- docs/source/fr/guides/hf_file_system.md | 55 +++++++++++++------------ 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/docs/source/fr/guides/hf_file_system.md b/docs/source/fr/guides/hf_file_system.md index 5c68232168..b28feea7f0 100644 --- a/docs/source/fr/guides/hf_file_system.md +++ b/docs/source/fr/guides/hf_file_system.md @@ -2,68 +2,69 @@ rendered properly in your Markdown viewer. --> -# Interact with the Hub through the Filesystem API +# Intéragissez avec le Hub à partir de l'API Filesystem -In addition to the [`HfApi`], the `huggingface_hub` library provides [`HfFileSystem`], a pythonic [fsspec-compatible](https://filesystem-spec.readthedocs.io/en/latest/) file interface to the Hugging Face Hub. The [`HfFileSystem`] builds of top of the [`HfApi`] and offers typical filesystem style operations like `cp`, `mv`, `ls`, `du`, `glob`, `get_file`, and `put_file`. +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`. -## Usage +## Utilisation ```python >>> from huggingface_hub import HfFileSystem >>> fs = HfFileSystem() ->>> # List all files in a directory +>>> # 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'] ->>> # List all ".csv" files in a repo +>>> # 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'] ->>> # Read a remote file +>>> # Lis un fichier distant >>> with fs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f: ... train_data = f.readlines() ->>> # Read the content of a remote file as a string +>>> # 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") ->>> # Write a remote file +>>> # 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") ``` -The optional `revision` argument can be passed to run an operation from a specific commit such as a branch, tag name, or a commit hash. +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 un hash de commit. -Unlike Python's built-in `open`, `fsspec`'s `open` defaults to binary mode, `"rb"`. This means you must explicitly set mode as `"r"` for reading and `"w"` for writing in text mode. Appending to a file (modes `"a"` and `"ab"`) is not supported yet. +A la différence des fonction native 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. -## Integrations +## Intégrations -The [`HfFileSystem`] can be used with any library that integrates `fsspec`, provided the URL follows the scheme: +[`HfFileSystem`] peut être utilisé avec toutes les librairies qui intègrent `fsspec`, tant que l'URL a le schéma suivant: ``` hf://[][@]/ ``` -The `repo_type_prefix` is `datasets/` for datasets, `spaces/` for spaces, and models don't need a prefix in the URL. +Le `repo_type_prefix` vaut `datasets/` pour les datasets, `spaces/` pour les espaces, et les modèles n'ont pas besoin de préfixe dans l'URL. -Some interesting integrations where [`HfFileSystem`] simplifies interacting with the Hub are listed below: +Ci-dessous quelques intégrations intéressantes où [`HfFileSystem`] simplifie l'intéraction avec le Hub: -* Reading/writing a [Pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#reading-writing-remote-files) DataFrame from/to a Hub repository: +* 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 - >>> # Read a remote CSV file into a dataframe + >>> # Lis un fichier CSV distant en renvoyant un dataframe >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv") - >>> # Write a dataframe to a remote CSV file + >>> # Enregistre un dataframe vers un fichier CSV distant >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv") ``` -The same workflow can also be used for [Dask](https://docs.dask.org/en/stable/how-to/connect-to-remote-data.html) and [Polars](https://pola-rs.github.io/polars/py-polars/html/reference/io.html) DataFrames. +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) -* Querying (remote) Hub files with [DuckDB](https://duckdb.org/docs/guides/python/filesystems): +* 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 @@ -71,12 +72,12 @@ The same workflow can also be used for [Dask](https://docs.dask.org/en/stable/ho >>> fs = HfFileSystem() >>> duckdb.register_filesystem(fs) - >>> # Query a remote file and get the result back as a dataframe + >>> # 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() ``` -* Using the Hub as an array store with [Zarr](https://zarr.readthedocs.io/en/stable/tutorial.html#io-with-fsspec): +* 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 @@ -84,26 +85,26 @@ The same workflow can also be used for [Dask](https://docs.dask.org/en/stable/ho >>> embeddings = np.random.randn(50000, 1000).astype("float32") - >>> # Write an array to a repo + >>> # É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 - >>> # Read an array from a repo + >>> # 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] ``` -## Authentication +## Authentification -In many cases, you must be logged in with a Hugging Face account to interact with the Hub. Refer to the [Login](../quick-start#login) section of the documentation to learn more about authentication methods on the Hub. +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'authentifications sur le Hub. -It is also possible to login programmatically by passing your `token` as an argument to [`HfFileSystem`]: +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) ``` -If you login this way, be careful not to accidentally leak the token when sharing your source code! +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! From f7f71909191f50dc35a86905005d640c24e3308d Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 1 Jan 2024 20:17:09 +0100 Subject: [PATCH 028/129] Translated inference_endpoints.md --- docs/source/fr/guides/inference_endpoints.md | 122 ++++++++++--------- 1 file changed, 62 insertions(+), 60 deletions(-) diff --git a/docs/source/fr/guides/inference_endpoints.md b/docs/source/fr/guides/inference_endpoints.md index 30b1113420..ff7b706eb9 100644 --- a/docs/source/fr/guides/inference_endpoints.md +++ b/docs/source/fr/guides/inference_endpoints.md @@ -1,14 +1,14 @@ # Inference Endpoints -Inference Endpoints provides a secure production solution to easily deploy any `transformers`, `sentence-transformers`, and `diffusers` models on a dedicated and autoscaling infrastructure managed by Hugging Face. An Inference Endpoint is built from a model from the [Hub](https://huggingface.co/models). -In this guide, we will learn how to programmatically manage Inference Endpoints with `huggingface_hub`. For more information about the Inference Endpoints product itself, check out its [official documentation](https://huggingface.co/docs/inference-endpoints/index). +Inference Endpoints fournit une solution viable pour la production et sécurisée pour déployer facilement n'importe quel modèle `transformers`, `sentence-transformers`, et `diffusers` sur une infrastructure dédiée et capable d'autoscaling gérée par Hugging Face. Un endpoint d'inférence 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). -This guide assumes `huggingface_hub` is correctly installed and that your machine is logged in. Check out the [Quick Start guide](https://huggingface.co/docs/huggingface_hub/quick-start#quickstart) if that's not the case yet. The minimal version supporting Inference Endpoints API is `v0.19.0`. +Ce guide postule 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`. -## Create an Inference Endpoint +## Créez un endpoint d'inférence -The first step is to create an Inference Endpoint using [`create_inference_endpoint`]: +La première étape pour créer un endpoint d'inférence est d'utiliser [`create_inference_endpoint`]: ```py >>> from huggingface_hub import create_inference_endpoint @@ -27,27 +27,27 @@ The first step is to create an Inference Endpoint using [`create_inference_endpo ... ) ``` -In this example, we created a `protected` Inference Endpoint named `"my-endpoint-name"`, to serve [gpt2](https://huggingface.co/gpt2) for `text-generation`. A `protected` Inference Endpoint means your token is required to access the API. We also need to provide additional information to configure the hardware requirements, such as vendor, region, accelerator, instance type, and size. You can check out the list of available resources [here](https://api.endpoints.huggingface.cloud/#/v2%3A%3Aprovider/list_vendors). Alternatively, you can create an Inference Endpoint manually using the [Web interface](https://ui.endpoints.huggingface.co/new) for convenience. Refer to this [guide](https://huggingface.co/docs/inference-endpoints/guides/advanced) for details on advanced settings and their usage. +Dans cet exemple, nous avons créé un endpoint d'inférence 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. Nous aurons aussi besoin de fournir des informations supplémentaires pour préciser le hardware nécessaire, tel 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 endpoint d'inférence 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. -The value returned by [`create_inference_endpoint`] is an [`InferenceEndpoint`] object: +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) ``` -It's a dataclass that holds information about the endpoint. You can access important attributes such as `name`, `repository`, `status`, `task`, `created_at`, `updated_at`, etc. If you need it, you can also access the raw response from the server with `endpoint.raw`. +C'est une dataclass qui a des informations sur l'endpoitn. 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`. -Once your Inference Endpoint is created, you can find it on your [personal dashboard](https://ui.endpoints.huggingface.co/). +Une fois que votre endpoint d'inférence 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) -#### Using a custom image +#### Utiliser une image personnalisée -By default the Inference Endpoint is built from a docker image provided by Hugging Face. However, it is possible to specify any docker image using the `custom_image` parameter. A common use case is to run LLMs using the [text-generation-inference](https://github.com/huggingface/text-generation-inference) framework. This can be done like this: +Par défaut, l'endpoint d'inférence est construit à partir d'une image docker fournie par Hugging Face. Cependant, i lest 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 -# Start an Inference Endpoint running Zephyr-7b-beta on TGI +# Créé un endpoint d'inférence 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", @@ -73,109 +73,111 @@ By default the Inference Endpoint is built from a docker image provided by Huggi ... ) ``` -The value to pass as `custom_image` is a dictionary containing a url to the docker container and configuration to run it. For more details about it, checkout the [Swagger documentation](https://api.endpoints.huggingface.cloud/#/v2%3A%3Aendpoint/create_endpoint). +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). -### Get or list existing Inference Endpoints +### Obtenir ou lister tous les endpoints d"inférence existants -In some cases, you might need to manage Inference Endpoints you created previously. If you know the name, you can fetch it using [`get_inference_endpoint`], which returns an [`InferenceEndpoint`] object. Alternatively, you can use [`list_inference_endpoints`] to retrieve a list of all Inference Endpoints. Both methods accept an optional `namespace` parameter. You can set the `namespace` to any organization you are a part of. Otherwise, it defaults to your username. +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 -# Get one +# Obtiens un endpoint >>> get_inference_endpoint("my-endpoint-name") InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) -# List all endpoints from an organization +# 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), ...] -# List all endpoints from all organizations the user belongs to +# 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), ...] ``` -## Check deployment status +## Vérifier le statu de déploiement -In the rest of this guide, we will assume that we have a [`InferenceEndpoint`] object called `endpoint`. You might have noticed that the endpoint has a `status` attribute of type [`InferenceEndpointStatus`]. When the Inference Endpoint is deployed and accessible, the status should be `"running"` and the `url` attribute is set: +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'endpoint d'inférence 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') ``` -Before reaching a `"running"` state, the Inference Endpoint typically goes through an `"initializing"` or `"pending"` phase. You can fetch the new state of the endpoint by running [`~InferenceEndpoint.fetch`]. Like every other method from [`InferenceEndpoint`] that makes a request to the server, the internal attributes of `endpoint` are mutated in place: +Avant d'atteindre l'état `"running"`, l'endpoint d'inférence 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 sur place: ```py >>> endpoint.fetch() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) ``` -Instead of fetching the Inference Endpoint status while waiting for it to run, you can directly call [`~InferenceEndpoint.wait`]. This helper takes as input a `timeout` and a `fetch_every` parameter (in seconds) and will block the thread until the Inference Endpoint is deployed. Default values are respectively `None` (no timeout) and `5` seconds. +Aulieu de récupérer le statut de l'endpoint d'inférence 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'endpoint d'inférence soit déployé. Les valeurs par défaut sont respectivement `None` (pas de timeout) et `5` secondes. ```py -# Pending endpoint +# Endpoint en attente >>> endpoint InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) -# Wait 10s => raises a InferenceEndpointTimeoutError +# 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. -# Wait more +# Attend plus >>> endpoint.wait() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') ``` -If `timeout` is set and the Inference Endpoint takes too much time to load, a [`InferenceEndpointTimeoutError`] timeout error is raised. +Si `timeout` est définit et que l'endpoint d'inférence prend trop de temps à charger, une erreur [`InferenceEndpointTimeouError`] est levée. -## Run inference +## Lancez des inférences -Once your Inference Endpoint is up and running, you can finally run inference on it! +Une fois que votre endpoint d'inférence est fonctionnel, vous pouvez enfin faire de l'inférence avec! -[`InferenceEndpoint`] has two properties `client` and `async_client` returning respectively an [`InferenceClient`] and an [`AsyncInferenceClient`] objects. +[`InferenceEndpoint`] a deux propriétés `client` et `async_client` qui renvoient respectivement des objets [`InferenceClient`] et [`AsyncInferenceClient`]. ```py -# Run text_generation task: +# Lancez 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' -# Or in an asyncio context: +# Ou dans un contexte asynchrone: >>> await endpoint.async_client.text_generation("I am") ``` -If the Inference Endpoint is not running, an [`InferenceEndpointError`] exception is raised: +Si l'endpoint d'inférence 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. ``` -For more details about how to use the [`InferenceClient`], check out the [Inference guide](../guides/inference). +Pour plus de détails sur l'utilisation d'[`InferenceClient`], consultez le [guide d'inférence](../guides/inference). -## Manage lifecycle +## Gérer les cycles de vie -Now that we saw how to create an Inference Endpoint and run inference on it, let's see how to manage its lifecycle. + +Maintenant que nous avons vu comment créer un endpoint d'inférence et faire de l'inférence avec, regardons comment gérer son cycle de vie. -In this section, we will see methods like [`~InferenceEndpoint.pause`], [`~InferenceEndpoint.resume`], [`~InferenceEndpoint.scale_to_zero`], [`~InferenceEndpoint.update`] and [`~InferenceEndpoint.delete`]. All of those methods are aliases added to [`InferenceEndpoint`] for convenience. If you prefer, you can also use the generic methods defined in `HfApi`: [`pause_inference_endpoint`], [`resume_inference_endpoint`], [`scale_to_zero_inference_endpoint`], [`update_inference_endpoint`], and [`delete_inference_endpoint`]. +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 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`], and [`delete_inference_endpoint`]. -### Pause or scale to zero +### Mettre en pause ou scale à zéro -To reduce costs when your Inference Endpoint is not in use, you can choose to either pause it using [`~InferenceEndpoint.pause`] or scale it to zero using [`~InferenceEndpoint.scale_to_zero`]. +Pour réduire les coûts lorsque votre endpoint d'inférence 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`]. -An Inference Endpoint that is *paused* or *scaled to zero* doesn't cost anything. The difference between those two is that a *paused* endpoint needs to be explicitly *resumed* using [`~InferenceEndpoint.resume`]. On the contrary, a *scaled to zero* endpoint will automatically start if an inference call is made to it, with an additional cold start delay. An Inference Endpoint can also be configured to scale to zero automatically after a certain period of inactivity. +Un endpoint d'inférence 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 endpoint d'inférence peut aussi être configuré pour scale à zero automatiquement après une certaine durée d'inactivité. ```py -# Pause and resume endpoint +# Met en pause et relance un endpoint >>> endpoint.pause() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='paused', url=None) >>> endpoint.resume() @@ -183,77 +185,77 @@ InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2 >>> endpoint.wait().client.text_generation(...) ... -# Scale to zero +# 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') -# Endpoint is not 'running' but still has a URL and will restart on first call. +# L'endpoint n'est pas en mode 'running' mais a tout de même un URL et sera relancé au premier call ``` -### Update model or hardware requirements +### Mettre à jour le modèle ou le hardware de l'endpoint -In some cases, you might also want to update your Inference Endpoint without creating a new one. You can either update the hosted model or the hardware requirements to run the model. You can do this using [`~InferenceEndpoint.update`]: +Dans certains cas, vous aurez besoin de mettre à jour votre endpoint d'inférence 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 faire ça en utilisant [`~InferenceEndpoint.update`]: ```py -# Change target model +# Change le modèle utilisé >>> endpoint.update(repository="gpt2-large") InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) -# Update number of replicas +# 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) -# Update to larger instance +# 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) ``` -### Delete the endpoint +### Supprimer un endpoint -Finally if you won't use the Inference Endpoint anymore, you can simply call [`~InferenceEndpoint.delete()`]. +Si vous n'utilisez plus un endpoint d'inférence, vous pouvez simplement appeler la méthode [`~InferenceEndpoint.delete()`]. -This is a non-revertible action that will completely remove the endpoint, including its configuration, logs and usage metrics. You cannot restore a deleted Inference Endpoint. +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 endpoint d'inférence supprimé. -## An end-to-end example +## Exemple de A à Z -A typical use case of Inference Endpoints is to process a batch of jobs at once to limit the infrastructure costs. You can automate this process using what we saw in this guide: +Un cas d'usage typique d'Hugging Face pour les endpoints d'inférence est des 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 -# Start endpoint + wait until initialized +# Lance un endpoint et attend qu'il soit initialisé >>> endpoint = create_inference_endpoint(name="batch-endpoint",...).wait() -# Run inference +# Fait des inféreces >>> client = endpoint.client >>> results = [client.text_generation(...) for job in jobs] -# Or with asyncio +# Ou bien avec asyncio >>> async_client = endpoint.async_client >>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs]) -# Pause endpoint +# Met en pause l'endpoint >>> endpoint.pause() ``` -Or if your Inference Endpoint already exists and is paused: +Ou si votre endpoint d'inférence existe et est en pause: ```py >>> import asyncio >>> from huggingface_hub import get_inference_endpoint -# Get endpoint + wait until initialized +# Récupère l'endpoint et attend son initialisation >>> endpoint = get_inference_endpoint("batch-endpoint").resume().wait() -# Run inference +# Fait des inféreces >>> async_client = endpoint.async_client >>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs]) -# Pause endpoint +# Met en pause l'endpoint >>> endpoint.pause() ``` \ No newline at end of file From 4a250a528b89f04619990ebbdf82292c53e7fe9a Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Tue, 2 Jan 2024 14:02:53 +0100 Subject: [PATCH 029/129] Translated inference.md --- docs/source/fr/guides/inference.md | 270 +++++++++++++++-------------- 1 file changed, 139 insertions(+), 131 deletions(-) diff --git a/docs/source/fr/guides/inference.md b/docs/source/fr/guides/inference.md index e2133aa39d..1196b95231 100644 --- a/docs/source/fr/guides/inference.md +++ b/docs/source/fr/guides/inference.md @@ -2,36 +2,37 @@ rendered properly in your Markdown viewer. --> -# Run Inference on servers - -Inference is the process of using a trained model to make predictions on new data. As this process can be compute-intensive, -running on a dedicated server can be an interesting option. The `huggingface_hub` library provides an easy way to call a -service that runs inference for hosted models. There are several services you can connect to: -- [Inference API](https://huggingface.co/docs/api-inference/index): a service that allows you to run accelerated inference -on Hugging Face's infrastructure for free. This service is a fast way to get started, test different models, and -prototype AI products. -- [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index): a product to easily deploy models to production. -Inference is run by Hugging Face in a dedicated, fully managed infrastructure on a cloud provider of your choice. - -These services can be called with the [`InferenceClient`] object. It acts as a replacement for the legacy -[`InferenceApi`] client, adding specific support for tasks and handling inference on both -[Inference API](https://huggingface.co/docs/api-inference/index) and [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index). -Learn how to migrate to the new client in the [Legacy InferenceAPI client](#legacy-inferenceapi-client) section. +# 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`] is a Python client making HTTP calls to our APIs. If you want to make the HTTP calls directly using -your preferred tool (curl, postman,...), please refer to the [Inference API](https://huggingface.co/docs/api-inference/index) -or to the [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) documentation pages. +[`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) -For web development, a [JS client](https://huggingface.co/docs/huggingface.js/inference/README) has been released. -If you are interested in game development, you might have a look at our [C# project](https://github.com/huggingface/unity-api). + +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). -## Getting started +## Commencer avec les inférences -Let's get started with a text-to-image task: +Commençons avec du text-to-image: ```python >>> from huggingface_hub import InferenceClient @@ -41,64 +42,67 @@ Let's get started with a text-to-image task: >>> image.save("astronaut.png") ``` -We initialized an [`InferenceClient`] with the default parameters. The only thing you need to know is the [task](#supported-tasks) you want -to perform. By default, the client will connect to the Inference API and select a model to complete the task. In our -example, we generated an image from a text prompt. The returned value is a `PIL.Image` object that can be saved to a -file. +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. -The API is designed to be simple. Not all parameters and options are available or described for the end user. Check out -[this page](https://huggingface.co/docs/api-inference/detailed_parameters) if you are interested in learning more about -all the parameters available for each task. +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. -### Using a specific model +### Utiliser un modèle spécifique -What if you want to use a specific model? You can specify it either as a parameter or directly at an instance level: +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 -# Initialize client for a specific model +# Initialise le client pour un modèle spécifique >>> client = InferenceClient(model="prompthero/openjourney-v4") >>> client.text_to_image(...) -# Or use a generic client but pass your model as an argument +# 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") ``` -There are more than 200k models on the Hugging Face Hub! Each task in the [`InferenceClient`] comes with a recommended -model. Be aware that the HF recommendation can change over time without prior notice. Therefore it is best to explicitly -set a model once you are decided. Also, in most cases you'll be interested in finding a model specific to _your_ needs. -Visit the [Models](https://huggingface.co/models) page on the Hub to explore your possibilities. +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. -### Using a specific URL +### Utiliser un URL spécifique -The examples we saw above use the free-hosted Inference API. This proves to be very useful for prototyping -and testing things quickly. Once you're ready to deploy your model to production, you'll need to use a dedicated infrastructure. -That's where [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) comes into play. It allows you to deploy -any model and expose it as a private API. Once deployed, you'll get a URL that you can connect to using exactly the same -code as before, changing only the `model` parameter: +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") -# or +# ou bien >>> client = InferenceClient() >>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") ``` -### Authentication +### Authentification -Calls made with the [`InferenceClient`] can be authenticated using a [User Access Token](https://huggingface.co/docs/hub/security-tokens). -By default, it will use the token saved on your machine if you are logged in (check out -[how to login](https://huggingface.co/docs/huggingface_hub/quick-start#login)). If you are not logged in, you can pass -your token as an instance parameter: +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 @@ -107,85 +111,88 @@ your token as an instance parameter: -Authentication is NOT mandatory when using the Inference API. However, authenticated users get a higher free-tier to -play with the service. Token is also mandatory if you want to run inference on your private models or on private -endpoints. +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. -## Supported tasks +## Tâches supportés -[`InferenceClient`]'s goal is to provide the easiest interface to run inference on Hugging Face models. It -has a simple API that supports the most common tasks. Here is a list of the currently supported tasks: +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: -| Domain | Task | Supported | Documentation | +| Domaine | Tâche | Supporté | Documentation | |--------|--------------------------------|--------------|------------------------------------| -| Audio | [Audio Classification](https://huggingface.co/tasks/audio-classification) | ✅ | [`~InferenceClient.audio_classification`] | -| | [Automatic Speech Recognition](https://huggingface.co/tasks/automatic-speech-recognition) | ✅ | [`~InferenceClient.automatic_speech_recognition`] | +| 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 | [Image Classification](https://huggingface.co/tasks/image-classification) | ✅ | [`~InferenceClient.image_classification`] | -| | [Image Segmentation](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`] | -| | [Object Detection](https://huggingface.co/tasks/object-detection) | ✅ | [`~InferenceClient.object_detection`] | -| | [Text-to-Image](https://huggingface.co/tasks/text-to-image) | ✅ | [`~InferenceClient.text_to_image`] | -| | [Zero-Shot-Image-Classification](https://huggingface.co/tasks/zero-shot-image-classification) | ✅ | [`~InferenceClient.zero_shot_image_classification`] | -| Multimodal | [Documentation Question Answering](https://huggingface.co/tasks/document-question-answering) | ✅ | [`~InferenceClient.document_question_answering`] -| | [Visual Question Answering](https://huggingface.co/tasks/visual-question-answering) | ✅ | [`~InferenceClient.visual_question_answering`] | -| NLP | [Conversational](https://huggingface.co/tasks/conversational) | ✅ | [`~InferenceClient.conversational`] | +| 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`] | -| | [Question Answering](https://huggingface.co/tasks/question-answering) | ✅ | [`~InferenceClient.question_answering`] -| | [Sentence Similarity](https://huggingface.co/tasks/sentence-similarity) | ✅ | [`~InferenceClient.sentence_similarity`] | -| | [Summarization](https://huggingface.co/tasks/summarization) | ✅ | [`~InferenceClient.summarization`] | -| | [Table Question Answering](https://huggingface.co/tasks/table-question-answering) | ✅ | [`~InferenceClient.table_question_answering`] | -| | [Text Classification](https://huggingface.co/tasks/text-classification) | ✅ | [`~InferenceClient.text_classification`] | -| | [Text Generation](https://huggingface.co/tasks/text-generation) | ✅ | [`~InferenceClient.text_generation`] | -| | [Token Classification](https://huggingface.co/tasks/token-classification) | ✅ | [`~InferenceClient.token_classification`] | -| | [Translation](https://huggingface.co/tasks/translation) | ✅ | [`~InferenceClient.translation`] | -| | [Zero Shot Classification](https://huggingface.co/tasks/zero-shot-classification) | ✅ | [`~InferenceClient.zero_shot_classification`] | -| Tabular | [Tabular Classification](https://huggingface.co/tasks/tabular-classification) | ✅ | [`~InferenceClient.tabular_classification`] | -| | [Tabular Regression](https://huggingface.co/tasks/tabular-regression) | ✅ | [`~InferenceClient.tabular_regression`] | +| | [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`] | -Check out the [Tasks](https://huggingface.co/tasks) page to learn more about each task, how to use them, and the -most popular models for each task. +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. -## Custom requests +## Requêtes personnalisées -However, it is not always possible to cover all use cases. For custom requests, the [`InferenceClient.post`] method -gives you the flexibility to send any request to the Inference API. For example, you can specify how to parse the inputs -and outputs. In the example below, the generated image is returned as raw bytes instead of parsing it as a `PIL Image`. -This can be helpful if you don't have `Pillow` installed in your setup and just care about the binary content of the -image. [`InferenceClient.post`] is also useful to handle tasks that are not yet officially supported. +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 # raw bytes +>>> response.content # bytes b'...' ``` -## Async client +## Client asynchrone -An async version of the client is also provided, based on `asyncio` and `aiohttp`. You can either install `aiohttp` -directly or use the `[inference]` extra: +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] -# or +# ou alors # pip install aiohttp ``` -After installation all async API endpoints are available via [`AsyncInferenceClient`]. Its initialization and APIs are -strictly the same as the sync-only version. +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 -# Code must be run in a asyncio concurrent context. +# Le code doit tourner dans un contexte asyncio # $ python -m asyncio >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() @@ -198,22 +205,23 @@ strictly the same as the sync-only version. a platform for sharing and discussing ML-related content. ``` -For more information about the `asyncio` module, please refer to the [official documentation](https://docs.python.org/3/library/asyncio.html). +Pour plus d'informations sur le module `asyncio`, consultez la [documentation officielle](https://docs.python.org/3/library/asyncio.html). -## Advanced tips +## Astuces avancées -In the above section, we saw the main aspects of [`InferenceClient`]. Let's dive into some more advanced tips. +Dans la section ci-dessus, nous avons vu les aspects principaux d' [`InferenceClient`]. Voyons maintenant les +astuces plus avanceées. ### Timeout -When doing inference, there are two main causes for a timeout: -- The inference process takes a long time to complete. -- The model is not available, for example when Inference API is loading it for the first time. +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`] has a global `timeout` parameter to handle those two aspects. By default, it is set to `None`, -meaning that the client will wait indefinitely for the inference to complete. If you want more control in your workflow, -you can set it to a specific value in seconds. If the timeout delay expires, an [`InferenceTimeoutError`] is raised. -You can catch it and handle it in your code: +[`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 @@ -224,15 +232,15 @@ You can catch it and handle it in your code: ... print("Inference timed out after 30s.") ``` -### Binary inputs +### Entrée binaires -Some tasks require binary inputs, for example, when dealing with images or audio files. In this case, [`InferenceClient`] -tries to be as permissive as possible and accept different types: -- raw `bytes` -- a file-like object, opened as binary (`with open("audio.flac", "rb") as f: ...`) -- a path (`str` or `Path`) pointing to a local file -- a URL (`str`) pointing to a remote file (e.g. `https://...`). In this case, the file will be downloaded locally before -sending it to the Inference API. +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 @@ -241,32 +249,32 @@ sending it to the Inference API. [{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...] ``` -## Legacy InferenceAPI client +## Client historique InferenceAPI -[`InferenceClient`] acts as a replacement for the legacy [`InferenceApi`] client. It adds specific support for tasks and -handles inference on both [Inference API](https://huggingface.co/docs/api-inference/index) and [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index). +[`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). -Here is a short guide to help you migrate from [`InferenceApi`] to [`InferenceClient`]. +Voici un guide très court qui vous aidera à migrer d'[`InferenceApi`] à [`InferenceClient`]. -### Initialization +### Initialisation -Change from +Remplacez ```python >>> from huggingface_hub import InferenceApi >>> inference = InferenceApi(repo_id="bert-base-uncased", token=API_TOKEN) ``` -to +par ```python >>> from huggingface_hub import InferenceClient >>> inference = InferenceClient(model="bert-base-uncased", token=API_TOKEN) ``` -### Run on a specific task +### Réaliser une tâche spécifique -Change from +Remplacez ```python >>> from huggingface_hub import InferenceApi @@ -274,7 +282,7 @@ Change from >>> inference(...) ``` -to +Par ```python >>> from huggingface_hub import InferenceClient @@ -284,14 +292,14 @@ to -This is the recommended way to adapt your code to [`InferenceClient`]. It lets you benefit from the task-specific -methods like `feature_extraction`. +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`. -### Run custom request +### Faire un requête personnalisée -Change from +Remplacez ```python >>> from huggingface_hub import InferenceApi @@ -300,7 +308,7 @@ Change from [{'sequence': 'the goal of life is life.', 'score': 0.10933292657136917, 'token': 2166, 'token_str': 'life'}] ``` -to +par ```python >>> from huggingface_hub import InferenceClient @@ -310,9 +318,9 @@ to [{'sequence': 'the goal of life is life.', 'score': 0.10933292657136917, 'token': 2166, 'token_str': 'life'}] ``` -### Run with parameters +### INférence avec des paramètres -Change from +Remplacez ```python >>> from huggingface_hub import InferenceApi @@ -323,7 +331,7 @@ Change from {'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]} ``` -to +par ```python >>> from huggingface_hub import InferenceClient From ea0137bc25bce25a6d6aa58059d4c4a13d3f1ab0 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Wed, 3 Jan 2024 14:05:54 +0100 Subject: [PATCH 030/129] translated repository.md --- docs/source/fr/guides/repository.md | 161 ++++++++++++++-------------- 1 file changed, 83 insertions(+), 78 deletions(-) diff --git a/docs/source/fr/guides/repository.md b/docs/source/fr/guides/repository.md index 787a01afb9..a9a5849318 100644 --- a/docs/source/fr/guides/repository.md +++ b/docs/source/fr/guides/repository.md @@ -2,41 +2,43 @@ rendered properly in your Markdown viewer. --> -# Create and manage a repository +# Créer et gérer un dépôt -The Hugging Face Hub is a collection of git repositories. [Git](https://git-scm.com/) is a widely used tool in software -development to easily version projects when working collaboratively. This guide will show you how to interact with the -repositories on the Hub, especially: +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: -- Create and delete a repository. -- Manage branches and tags. -- Rename your repository. -- Update your repository visibility. -- Manage a local copy of your repository. +- 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. -If you are used to working with platforms such as GitLab/GitHub/Bitbucket, your first instinct -might be to use `git` CLI to clone your repo (`git clone`), commit changes (`git add, git commit`) and push them -(`git push`). This is valid when using the Hugging Face Hub. However, software engineering and machine learning do -not share the same requirements and workflows. Model repositories might maintain large model weight files for different -frameworks and tools, so cloning the repository can lead to you maintaining large local folders with massive sizes. As -a result, it may be more efficient to use our custom HTTP methods. You can read our [Git vs HTTP paradigm](../concepts/git_vs_http) -explanation page for more details. +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. -If you want to create and manage a repository on the Hub, your machine must be logged in. If you are not, please refer to -[this section](../quick-start#login). In the rest of this guide, we will assume that your machine is logged in. +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. -## Repo creation and deletion +## Création et suppression d'un dépôt -The first step is to know how to create and delete repositories. You can only manage repositories that you own (under -your username namespace) or from organizations in which you have write permissions. +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. -### Create a repository +### Créer un dépôt -Create an empty repository with [`create_repo`] and give it a name with the `repo_id` parameter. The `repo_id` is your namespace followed by the repository name: `username_or_org/repo_name`. +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 @@ -44,7 +46,7 @@ Create an empty repository with [`create_repo`] and give it a name with the `rep 'https://huggingface.co/lysandre/test-model' ``` -By default, [`create_repo`] creates a model repository. But you can use the `repo_type` parameter to specify another repository type. For example, if you want to create a dataset repository: +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 @@ -52,30 +54,31 @@ By default, [`create_repo`] creates a model repository. But you can use the `rep 'https://huggingface.co/datasets/lysandre/test-dataset' ``` -When you create a repository, you can set your repository visibility with the `private` parameter. +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) ``` -If you want to change the repository visibility at a later time, you can use the [`update_repo_visibility`] function. +Si vous voulez changer la visibilité du dépôt plus tard, vous pouvez utiliser la fonction [`update_repo_visibility`]. -### Delete a repository +### Supprimer un dépôt -Delete a repository with [`delete_repo`]. Make sure you want to delete a repository because this is an irreversible process! +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! -Specify the `repo_id` of the repository you want to delete: +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") ``` -### Duplicate a repository (only for Spaces) +### Dupliquer un dépôt (uniquement pour les espaces) -In some cases, you want to copy someone else's repo to adapt it to your use case. -This is possible for Spaces using the [`duplicate_space`] method. It will duplicate the whole repository. -You will still need to configure your own settings (hardware, sleep-time, storage, variables and secrets). Check out our [Manage your Space](./manage-spaces) guide for more details. +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 espaces 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 espaces](./manage-spaces) pour plus de détails. ```py >>> from huggingface_hub import duplicate_space @@ -83,39 +86,40 @@ You will still need to configure your own settings (hardware, sleep-time, storag RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...) ``` -## Upload and download files +## Upload et téléchargement de fichiers -Now that you have created your repository, you are interested in pushing changes to it and downloading files from it. +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. -These 2 topics deserve their own guides. Please refer to the [upload](./upload) and the [download](./download) guides -to learn how to use your repository. +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 and tags +## Branches et tags -Git repositories often make use of branches to store different versions of a same repository. -Tags can also be used to flag a specific state of your repository, for example, when releasing a version. -More generally, branches and tags are referred as [git references](https://git-scm.com/book/en/v2/Git-Internals-Git-References). +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). -### Create branches and tags +### Créer des branches et de tags -You can create new branch and tags using [`create_branch`] and [`create_tag`]: +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 -# Create a branch on a Space repo from `main` branch +# Créé une branche sur le dépôt d'un espace basée sur la branche `main` >>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker") -# Create a tag on a Dataset repo from `v0.1-release` branch ->>> create_branch("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.") +# 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.") ``` -You can use the [`delete_branch`] and [`delete_tag`] functions in the same way to delete a branch or a tag. +Vous pouvez utiliser les fonctions [`delete_branch`] et [`deelte_tag`] de la même manière pour supprimer une branche ou un tag. -### List all branches and tags +### Lister toutes les branches et les tags -You can also list the existing git refs from a repository using [`list_repo_refs`]: +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 @@ -132,79 +136,80 @@ GitRefs( ) ``` -## Change repository settings +## Changer les paramètres de dépôt -Repositories come with some settings that you can configure. Most of the time, you will want to do that manually in the -repo settings page in your browser. You must have write access to a repo to configure it (either own it or being part of -an organization). In this section, we will see the settings that you can also configure programmatically using `huggingface_hub`. +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`. -Some settings are specific to Spaces (hardware, environment variables,...). To configure those, please refer to our [Manage your Spaces](../guides/manage-spaces) guide. +Certains paramètres sont spécifique aux espaces (hardware, variables d'environnement,...). Pour les configurern, consultez notre guide [Gérez vos espaces](../guides/manage-spaces) -### Update visibility +### Changer la visibilité -A repository can be public or private. A private repository is only visible to you or members of the organization in which the repository is located. Change a repository to private as shown in the following: +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) ``` -### Rename your repository +### Renommez votre dépôt -You can rename your repository on the Hub using [`move_repo`]. Using this method, you can also move the repo from a user to -an organization. When doing so, there are a [few limitations](https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo) -that you should be aware of. For example, you can't transfer your repo to another user. +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") ``` -## Manage a local copy of your repository +## Gérer une copie locale de votre dépôt -All the actions described above can be done using HTTP requests. However, in some cases you might be interested in having -a local copy of your repository and interact with it using the Git commands you are familiar with. +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à. -The [`Repository`] class allows you to interact with files and repositories on the Hub with functions similar to Git commands. It is a wrapper over Git and Git-LFS methods to use the Git commands you already know and love. Before starting, please make sure you have Git-LFS installed (see [here](https://git-lfs.github.com/) for installation instructions). +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`] is deprecated in favor of the http-based alternatives implemented in [`HfApi`]. Given its large adoption in legacy code, the complete removal of [`Repository`] will only happen in release `v1.0`. For more details, please read [this explanation page](./concepts/git_vs_http). +[`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). -### Use a local repository +### Utiliser un dépôt local -Instantiate a [`Repository`] object with a path to a local repository: +Instanciez un objet [`Repository`] avec un chemin vers un dépôt local: ```py >>> from huggingface_hub import Repository >>> repo = Repository(local_dir="//") ``` -### Clone +### Cloner -The `clone_from` parameter clones a repository from a Hugging Face repository ID to a local directory specified by the `local_dir` argument: +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` can also clone a repository using a URL: +`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") ``` -You can combine the `clone_from` parameter with [`create_repo`] to create and clone a repository: +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) ``` -You can also configure a Git username and email to a cloned repository by specifying the `git_user` and `git_email` parameters when you clone a repository. When users commit to that repository, Git will be aware of the commit author. +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( @@ -217,26 +222,26 @@ You can also configure a Git username and email to a cloned repository by specif ... ) ``` -### Branch +### Branche -Branches are important for collaboration and experimentation without impacting your current files and code. Switch between branches with [`~Repository.git_checkout`]. For example, if you want to switch from `branch1` to `branch2`: +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='branch1') ->>> repo.git_checkout("branch2") +>>> repo = Repository(local_dir="huggingface-hub", clone_from="/", revision='branche1') +>>> repo.git_checkout("branche2") ``` ### Pull -[`~Repository.git_pull`] allows you to update a current local branch with changes from a remote repository: +[`~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() ``` -Set `rebase=True` if you want your local commits to occur after your branch is updated with the new commits from the remote: +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) From f52121541c4da392a2bf35cac618df013d18bf44 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Wed, 3 Jan 2024 19:00:44 +0100 Subject: [PATCH 031/129] Translated search.md --- docs/source/fr/guides/search.md | 39 ++++++++++++++++----------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/docs/source/fr/guides/search.md b/docs/source/fr/guides/search.md index 6f25d02296..bb443b6540 100644 --- a/docs/source/fr/guides/search.md +++ b/docs/source/fr/guides/search.md @@ -2,14 +2,14 @@ rendered properly in your Markdown viewer. --> -# Search the Hub +# Faites des recherches dans le Hub -In this tutorial, you will learn how to search models, datasets and spaces on the Hub using `huggingface_hub`. +Dans ce tutoriel, vous apprendrez à chercher des modèles, des datasets et des espaces du Hub en utilisant `huggingface_hub`. -## How to list repositories ? +## Comment lister les dépôts ? -`huggingface_hub` library includes an HTTP client [`HfApi`] to interact with the Hub. -Among other things, it can list models, datasets and spaces stored on the Hub: +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 espaces enregistrés sur le Hub: ```py >>> from huggingface_hub import HfApi @@ -17,26 +17,26 @@ Among other things, it can list models, datasets and spaces stored on the Hub: >>> models = api.list_models() ``` -The output of [`list_models`] is an iterator over the models stored on the Hub. +La sortie de [`list_models`] est un itérateur sur les modèles stockés dans le Hub. -Similarly, you can use [`list_datasets`] to list datasets and [`list_spaces`] to list Spaces. +De la même manière, vous pouvez utiliser [`list_datasets`] pour lister les datasets et [`list_spaces`] pour lister les espaces. -## How to filter repositories ? +## Comment filtrer des dépôts ? -Listing repositories is great but now you might want to filter your search. -The list helpers have several attributes like: +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` - ... -Two of these parameters are intuitive (`author` and `search`), but what about that `filter`? -`filter` takes as input a [`ModelFilter`] object (or [`DatasetFilter`]). You can instantiate -it by specifying which models you want to filter. +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. -Let's see an example to get all models on the Hub that does image classification, have been -trained on the imagenet dataset and that runs with PyTorch. That can be done with a single -[`ModelFilter`]. Attributes are combined as "logical AND". +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( @@ -48,8 +48,8 @@ models = hf_api.list_models( ) ``` -While filtering, you can also sort the models and take only the top results. For example, -the following example fetches the top 5 most downloaded datasets on the Hub: +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)) @@ -65,6 +65,5 @@ the following example fetches the top 5 most downloaded datasets on the Hub: -To explore available filter on the Hub, visit [models](https://huggingface.co/models) and [datasets](https://huggingface.co/datasets) pages -in your browser, search for some parameters and look at the values in the URL. +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. From 8ab86fb9c9989f21a54a43052606561a9d365241 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Wed, 3 Jan 2024 21:10:28 +0100 Subject: [PATCH 032/129] Translated webhooks_server.md --- docs/source/fr/guides/webhooks_server.md | 172 +++++++++--------- .../fr/package_reference/webhooks_server.md | 2 +- 2 files changed, 90 insertions(+), 84 deletions(-) diff --git a/docs/source/fr/guides/webhooks_server.md b/docs/source/fr/guides/webhooks_server.md index 1545c22938..61796a5a43 100644 --- a/docs/source/fr/guides/webhooks_server.md +++ b/docs/source/fr/guides/webhooks_server.md @@ -2,38 +2,40 @@ rendered properly in your Markdown viewer. --> -# Webhooks Server +# Serveurs Webhooks -Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on specific repos or to -all repos belonging to particular users/organizations you're interested in following. This guide will explain how to -leverage `huggingface_hub` to create a server listening to webhooks and deploy it to a Space. It assumes you are -familiar with the concept of webhooks on the Huggingface Hub. To learn more about webhooks themselves, you can read -this [guide](https://huggingface.co/docs/hub/webhooks) first. +Les webhooks sont un pilier des fonctionnalités MLOps. Ils vous permettent de suivre tous les nouveaux +changements sur des dépôts spécifiques ou sur tous les dépôts appartenants à des utilisateurs/organisations que +vous voulez suivre. Ce guide vous expliquera comment utiliser `hugginface_hub` pour créer un serveur écoutant des +webhooks et le déployer sur un espacce. Il postule que vous êtes familier avec le concept de webhooks sur le Hub Hugging Face. +Pour en apprendre plus sur les webhooks, vous pouvez consulter le +[guide](https://huggingface.co/docs/hub/webhooks) d'abord. -The base class that we will use in this guide is [`WebhooksServer`]. It is a class for easily configuring a server that -can receive webhooks from the Huggingface Hub. The server is based on a [Gradio](https://gradio.app/) app. It has a UI -to display instructions for you or your users and an API to listen to webhooks. +La classe de base que nous utiliserons dans ce guide est [`WebhooksServer`]. C'est une classe qui permet de configurer +facilement un serveur qui peut recevoir des webhooks du Hub Huggingface. Le serveur est basé sur une application +[Gradio](https://gradio.app/). Il a une interface pour afficher des instruction pour vous ou vos utilisateurs et une API +pour écouter les webhooks. -To see a running example of a webhook server, check out the [Spaces CI Bot](https://huggingface.co/spaces/spaces-ci-bot/webhook) -one. It is a Space that launches ephemeral environments when a PR is opened on a Space. +Pour voir un exemple fonctionnel de serveur webhooj, consultez l'[espace bot CI](https://huggingface.co/spaces/spaces-ci-bot/webhook). +C'est un espace qui lance des environnements éphémères lorsqu'une pull request est ouverte sur un espace. -This is an [experimental feature](../package_reference/environment_variables#hfhubdisableexperimentalwarning). This -means that we are still working on improving the API. Breaking changes might be introduced in the future without prior -notice. Make sure to pin the version of `huggingface_hub` in your requirements. +C'est une [fonctionnalité expérimentale](../package_reference/environment_variables#hfhubdisableexperimentalwarning), +ce qui signifie que nous travaillons toujours sur l'amélioration de l'API. De nouveaux changement pourront être introduit +dans les future sans avertissement préalable. Assurez vous d'épingler la version d'`hugginface_hub` dans vos requirements. -## Create an endpoint +## Créer un endpoint -Implementing a webhook endpoint is as simple as decorating a function. Let's see a first example to explain the main -concepts: +Implémenter un endpoint webhook est aussi facile que d'ajouter des décorateurs à une fonction. Voyons un premier +exemple afin de clarifier les concepts principaux: ```python # app.py @@ -42,11 +44,12 @@ from huggingface_hub import webhook_endpoint, WebhookPayload @webhook_endpoint async def trigger_training(payload: WebhookPayload) -> None: if payload.repo.type == "dataset" and payload.event.action == "update": - # Trigger a training job if a dataset is updated + # Lance une tâche d'entrainement si votre dataset est mis à jour ... ``` -Save this snippet in a file called `'app.py'` and run it with `'python app.py'`. You should see a message like this: +Enregistrez ce snippet de code dans un fichier appelé `'app.py'` et lancez le avec `'python app.py'`. Vous devriez +voir un message de ce type: ```text Webhook secret is not defined. This means your webhook endpoints will be open to everyone. @@ -63,71 +66,73 @@ Webhooks are correctly setup and ready to use: Go to https://huggingface.co/settings/webhooks to setup your webhooks. ``` -Good job! You just launched a webhook server! Let's break down what happened exactly: - -1. By decorating a function with [`webhook_endpoint`], a [`WebhooksServer`] object has been created in the background. -As you can see, this server is a Gradio app running on http://127.0.0.1:7860. If you open this URL in your browser, you -will see a landing page with instructions about the registered webhooks. -2. A Gradio app is a FastAPI server under the hood. A new POST route `/webhooks/trigger_training` has been added to it. -This is the route that will listen to webhooks and run the `trigger_training` function when triggered. FastAPI will -automatically parse the payload and pass it to the function as a [`WebhookPayload`] object. This is a `pydantic` object -that contains all the information about the event that triggered the webhook. -3. The Gradio app also opened a tunnel to receive requests from the internet. This is the interesting part: you can -configure a Webhook on https://huggingface.co/settings/webhooks pointing to your local machine. This is useful for -debugging your webhook server and quickly iterating before deploying it to a Space. -4. Finally, the logs also tell you that your server is currently not secured by a secret. This is not problematic for -local debugging but is to keep in mind for later. +Bien joué! Vous venez de créer un serveur webhook! Décomposons ce qui vient de se passer exactement: + +1. En décorant une fonction avec [`webhook_endpoint`], un objet [`WebhooksServer`] a été créé en arrière plan. +Comme vous pouvez le voir, ce serveur est une application Gradio qui tourne sur http://127.0.0.1:7860. Si vous ouvrez +cet URL dans votre navigateur, vous verez une page d'accueil avec des informations sur les webhooks en question. +2. En arrière plan, une application Gradio n'est rien de plus qu'un serveur FastAPI . Une nouvelle route POST `/webhooks/trigger_training` +y a été ajoutée. C'est cette route qui écoutera les webhooks et lancera la fonction `trigger_training` lors de son activation. +FastAPI parsera automatiquement le paquet et le passera à la fonction en tant qu'objet [`WebhookPayload`]. C'est un objet +`pydantic` qui contient toutes les informations sur l'événement qui a activé le webhook. +3. L'application Gradio a aussi ouvert un tunnel pour recevoir des requêtes d'internet. C'est la partie intéressante: +vous pouvez configurer un webhooj sur https://huggingface.co/settings/webhooks qui pointe vers votre machine. C'est utile +pour debugger votre serveur webhook et rapidement itérer avant de le déployer dans un espace. +4. Enfin, les logs vous disent aussi que votre serveur n'est pas sécurisé par un secret. Ce n'est pas problématique pour +le debugging en local mais c'est à garder dans un coin de la tête pour plus tard. -By default, the server is started at the end of your script. If you are running it in a notebook, you can start the -server manually by calling `decorated_function.run()`. Since a unique server is used, you only have to start the server -once even if you have multiple endpoints. +Par défaut, le serveur est lancé à la fin de votre script. Si vous l'utilisez dans un notebook, vous pouvez lancer serveur +manuellement en appelant `decorated_function.run()`. Vu qu'un unique serveur est utilisé, vous aurez uniquement besoin de +lancer le serveur une fois même si vous avez plusieurs endpoints. -## Configure a Webhook +## Configurer un webhook -Now that you have a webhook server running, you want to configure a Webhook to start receiving messages. -Go to https://huggingface.co/settings/webhooks, click on "Add a new webhook" and configure your Webhook. Set the target -repositories you want to watch and the Webhook URL, here `https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training`. +Maintenant que vous avez un serveur webhook qui tourne, vous aurez surement besoin de configure un webhook +pour commencer à recevoir des messages. Allez sur https://huggingface.co/settings/webhooks, cliquez sur +"Ajouter un nouveau webhook" et configurez votre webhook. Définissez les dépôts cibles que vous voulez +surveiller et l'URL du webhook, ici `https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training`.
-And that's it! You can now trigger that webhook by updating the target repository (e.g. push a commit). Check the -Activity tab of your Webhook to see the events that have been triggered. Now that you have a working setup, you can -test it and quickly iterate. If you modify your code and restart the server, your public URL might change. Make sure -to update the webhook configuration on the Hub if needed. +Et voilà! Vous pouvez maintenant activer cce webhook en mettant à jour le dépôt cible (i.e. push un commit). Consultez +la table d'activité de votre webhook pour voir les événements passés. Maintenant que vous avez un setup qui fonctionne, +vous pouvez le tester et itérer rapidement. Si vous modifiez votre code et relancez le serveur, votre URL public pourrait +changer. Assurez vous de mettre à jour la configuration du webhook dans le HUb si besoin. -## Deploy to a Space +## Déployer vers un espace -Now that you have a working webhook server, the goal is to deploy it to a Space. Go to https://huggingface.co/new-space -to create a Space. Give it a name, select the Gradio SDK and click on "Create Space". Upload your code to the Space -in a file called `app.py`. Your Space will start automatically! For more details about Spaces, please refer to this -[guide](https://huggingface.co/docs/hub/spaces-overview). +Maintenant que vous avez un serveur webhook fonctionnel, le but est de le déplyer sur un espace. Allez sur +https://huggingface.co/new-space pour créer un espace. Donnez lui un nom, sélectionnez le SDK Gradio et cliquer sur +"Créer un espace" (ou "Create Space" en anglais). Uploadez votre code dans l'espace dans un fichier appelé `app.py`. +Votre espace sera lancé automatiquement! Pour plus de détails sur les espaces, consultez ce [guide](https://huggingface.co/docs/hub/spaces-overview). -Your webhook server is now running on a public Space. If most cases, you will want to secure it with a secret. Go to -your Space settings > Section "Repository secrets" > "Add a secret". Set the `WEBHOOK_SECRET` environment variable to -the value of your choice. Go back to the [Webhooks settings](https://huggingface.co/settings/webhooks) and set the -secret in the webhook configuration. Now, only requests with the correct secret will be accepted by your server. +Votre serveur webhook tourne maintenant sur un espace public. Dans la plupart de cas, vous aurez besoin de le sécuriser +avec un secret. Allez dans les paramètres de votre espace > Section "Repository secrets" > "Add a secret". Définissez +la variable d'environnement `WEBHOOK_SECRET` en choisissant la valeur que vous voulez. Retournez dans les +[réglages webhooks](https://huggingface.co/settings/webhooks) et définissez le secret dans la configuration du webhook. +Maintenant, seules les requêtes avec le bon secret seront acceptées par votre serveur. -And this is it! Your Space is now ready to receive webhooks from the Hub. Please keep in mind that if you run the Space -on a free 'cpu-basic' hardware, it will be shut down after 48 hours of inactivity. If you need a permanent Space, you -should consider setting to an [upgraded hardware](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs). +Et c'est out! Votre espace est maintenant prêt à recevoir des webhooks du Hub. Gardez à l'esprit que si vous faites +tourner l'espace sur le hardware gratuit 'cpu-basic', il sera éteint après 48 heures d'inactivité. Si vous avez besoin d'un +espace permanent, vous devriez peut-être considérer l'amélioration vers un [hardware amélioré](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs). -## Advanced usage +## Utilisation avancée -The guide above explained the quickest way to setup a [`WebhooksServer`]. In this section, we will see how to customize -it further. +Le guide ci dessus expliquait la manière la plus rapide d'initialiser un [`WebhookServer`]. Dans cette section, nous verrons +comment le personnaliser plus en détails. -### Multiple endpoints +### Endpoints multilpes -You can register multiple endpoints on the same server. For example, you might want to have one endpoint to trigger -a training job and another one to trigger a model evaluation. You can do this by adding multiple `@webhook_endpoint` -decorators: +Vous pouvez avoir plusieurs endpoints sur le même serveur. Par exemple, vous aurez peut-être envie d'avoir un endpoint +qui lance un entrainement de modèle et un autre qui lance une évaluation de modèle. Vous pouvez faire ça en ajoutant +plusieurs décorateurs `@webhook_endpoint`: ```python # app.py @@ -136,17 +141,17 @@ from huggingface_hub import webhook_endpoint, WebhookPayload @webhook_endpoint async def trigger_training(payload: WebhookPayload) -> None: if payload.repo.type == "dataset" and payload.event.action == "update": - # Trigger a training job if a dataset is updated + # Lance une tâche d'entrainement si votre dataset est mis à jour ... @webhook_endpoint async def trigger_evaluation(payload: WebhookPayload) -> None: if payload.repo.type == "model" and payload.event.action == "update": - # Trigger an evaluation job if a model is updated + # Lance un tâche d'évaluation si un modèle est mis à jour ... ``` -Which will create two endpoints: +Ce qui créera deux endpoints: ```text (...) @@ -155,13 +160,13 @@ Webhooks are correctly setup and ready to use: - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation ``` -### Custom server +### Serveur personnalisé -To get more flexibility, you can also create a [`WebhooksServer`] object directly. This is useful if you want to -customize the landing page of your server. You can do this by passing a [Gradio UI](https://gradio.app/docs/#blocks) -that will overwrite the default one. For example, you can add instructions for your users or add a form to manually -trigger the webhooks. When creating a [`WebhooksServer`], you can register new webhooks using the -[`~WebhooksServer.add_webhook`] decorator. +Pour plus de flexibilité, vous pouvez aussi créer un objet [`WebhooksServer`] directement. C'est utile si vous +voulez customiser la page d'acceuil de votre serveur. Vous pouvez le faire en passant une [UI Gradio](https://gradio.app/docs/#blocks) +qui va overwrite linterface par défaut. Par exemple, vous pouvez ajouter des instructions pour vos utilisateurs +ou ajouter un formulaire pour avtiver les webhooks manuellement. Lors de la création d'un [`WebhooksServer`], vous +pouvez créer de nouveaux webhooks en utilisant le décorateur [`~WebhooksServer.add_webhook`]. Here is a complete example: @@ -170,30 +175,31 @@ import gradio as gr from fastapi import Request from huggingface_hub import WebhooksServer, WebhookPayload -# 1. Define UI +# 1. Déifnition de l'interface with gr.Blocks() as ui: ... -# 2. Create WebhooksServer with custom UI and secret +# 2. Création d'un WebhooksServer avec une interface personnalisée et un secret app = WebhooksServer(ui=ui, webhook_secret="my_secret_key") -# 3. Register webhook with explicit name +# 3. Ajout d'un webhook avec un nom explicite @app.add_webhook("/say_hello") async def hello(payload: WebhookPayload): return {"message": "hello"} -# 4. Register webhook with implicit name +# 4. Ajout d'un webhook avec un nom implicite @app.add_webhook async def goodbye(payload: WebhookPayload): return {"message": "goodbye"} -# 5. Start server (optional) +# 5. Lancement du server (optionnel)) app.run() ``` -1. We define a custom UI using Gradio blocks. This UI will be displayed on the landing page of the server. -2. We create a [`WebhooksServer`] object with a custom UI and a secret. The secret is optional and can be set with -the `WEBHOOK_SECRET` environment variable. -3. We register a webhook with an explicit name. This will create an endpoint at `/webhooks/say_hello`. -4. We register a webhook with an implicit name. This will create an endpoint at `/webhooks/goodbye`. -5. We start the server. This is optional as your server will automatically be started at the end of the script. \ No newline at end of file +1. Nous définissons une interface personnalisée en utilisant des block Gradio. Cette interface sera affichée +sur la page d'accueil du serveur. +2. Nous créons un objet [`WebhooksServer`] avec une interface personnalisée et un secret. Le secret est optionnel et +peut être définit avec la variable d'environnement `WEBHOOK_SECRET`. +3. Nous créons un webhook avec un nom explicite. Ceci créera un endpoint à `/webhooks/say_hello`. +4. Nous créons un webhook avec un nom implicite. Ceci créera un endpoint à `/webhoojs/goodbye`. +5. Nous lançons le serveur. C'est optionnel car votre serveur sera automatiquement lancé à la fin du script. \ No newline at end of file diff --git a/docs/source/fr/package_reference/webhooks_server.md b/docs/source/fr/package_reference/webhooks_server.md index 1b318d890d..422a1ec328 100644 --- a/docs/source/fr/package_reference/webhooks_server.md +++ b/docs/source/fr/package_reference/webhooks_server.md @@ -4,7 +4,7 @@ rendered properly in your Markdown viewer. # Serveurs WebHooks -Les webhooks sont un pilier des fonctionnalités autour du MLOps. Ils vous permettent de suivre tous les nouveaux +Les webhooks sont un pilier des fonctionnalités MLOps. Ils vous permettent de suivre tous les nouveaux changements sur des dépôts spécifiques ou sur tous les dépôts appartenants à des utilisateurs/organisations que vous voulez suivre. Pour en apprendre plus sur les webhooks dans le Hub Huggingface, vous pouvez consulter le [guide](https://huggingface.co/docs/hub/webhooks) consacré aux webhooks. From c420deb033f8ca4a0fed04359f84f5cf9e725d4a Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Thu, 4 Jan 2024 13:09:58 +0100 Subject: [PATCH 033/129] corrected webhooks --- docs/source/fr/guides/webhooks_server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/webhooks_server.md b/docs/source/fr/guides/webhooks_server.md index 61796a5a43..8f40d3b77b 100644 --- a/docs/source/fr/guides/webhooks_server.md +++ b/docs/source/fr/guides/webhooks_server.md @@ -192,7 +192,7 @@ async def hello(payload: WebhookPayload): async def goodbye(payload: WebhookPayload): return {"message": "goodbye"} -# 5. Lancement du server (optionnel)) +# 5. Lancement du serveur (optionnel) app.run() ``` From ca05e4e67eb18d336ae61db0429eecfb4aa05435 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Thu, 4 Jan 2024 17:31:21 +0100 Subject: [PATCH 034/129] Translated upload.md --- docs/source/fr/guides/upload.md | 479 +++++++++++++++++--------------- 1 file changed, 248 insertions(+), 231 deletions(-) diff --git a/docs/source/fr/guides/upload.md b/docs/source/fr/guides/upload.md index 19226fa541..165449f009 100644 --- a/docs/source/fr/guides/upload.md +++ b/docs/source/fr/guides/upload.md @@ -2,46 +2,46 @@ rendered properly in your Markdown viewer. --> -# Upload files to the Hub +# Upload des fichiers vers le Hub -Sharing your files and work is an important aspect of the Hub. The `huggingface_hub` offers several options for uploading your files to the Hub. You can use these functions independently or integrate them into your library, making it more convenient for your users to interact with the Hub. This guide will show you how to push files: +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: -- without using Git. -- that are very large with [Git LFS](https://git-lfs.github.com/). -- with the `commit` context manager. -- with the [`~Repository.push_to_hub`] function. +- 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`]. -Whenever you want to upload files to the Hub, you need to log in to your Hugging Face account: +Lorsque vous voulez upload des fichiers sur le HUb, vous devez vous connecter à votre compte Hugging Face: -- Log in to your Hugging Face account with the following command: +- Connectez vous à votre compte Hugging Face avec la commande suivante: ```bash huggingface-cli login - # or using an environment variable + # Ou en utilisant une variable d\'environnement huggingface-cli login --token $HUGGINGFACE_TOKEN ``` -- Alternatively, you can programmatically login using [`login`] in a notebook or a script: +- Sinon, vous pouvez vous connecter par le code en utilisant [`login`] dans un notebook ou un script: ```python >>> from huggingface_hub import login >>> login() ``` - If ran in a Jupyter or Colaboratory notebook, [`login`] will launch a widget from - which you can enter your Hugging Face access token. Otherwise, a message will be - prompted in the terminal. + 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. - It is also possible to login programmatically without the widget by directly passing - the token to [`login`]. If you do so, be careful when sharing your notebook. It is - best practice to load the token from a secure vault instead of saving it in plain in - your Colaboratory notebook. + 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 a file +## Upload un fichier -Once you've created a repository with [`create_repo`], you can upload a file to your repository using [`upload_file`]. +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`]. -Specify the path of the file to upload, where you want to upload the file to in the repository, and the name of the repository you want to add the file to. Depending on your repository type, you can optionally set the repository type as a `dataset`, `model`, or `space`. +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 @@ -54,18 +54,18 @@ Specify the path of the file to upload, where you want to upload the file to in ... ) ``` -## Upload a folder +## Upload un dossier -Use the [`upload_folder`] function to upload a local folder to an existing repository. Specify the path of the local folder -to upload, where you want to upload the folder to in the repository, and the name of the repository you want to add the -folder to. Depending on your repository type, you can optionally set the repository type as a `dataset`, `model`, or `space`. +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 all the content from the local folder to your remote Space. -# By default, files are uploaded at the root of the repo +# Upload tout le contenu du fichier local vers votre espace 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", @@ -73,46 +73,46 @@ folder to. Depending on your repository type, you can optionally set the reposit ... ) ``` -By default, the `.gitignore` file will be taken into account to know which files should be committed or not. By default we check if a `.gitignore` file is present in a commit, and if not, we check if it exists on the Hub. Please be aware that only a `.gitignore` file present at the root of the directory with be used. We do not check for `.gitignore` files in subdirectories. +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. -If you don't want to use an hardcoded `.gitignore` file, you can use the `allow_patterns` and `ignore_patterns` arguments to filter which files to upload. These parameters accept either a single pattern or a list of patterns. Patterns are Standard Wildcards (globbing patterns) as documented [here](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). If both `allow_patterns` and `ignore_patterns` are provided, both constraints apply. +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. -Beside the `.gitignore` file and allow/ignore patterns, any `.git/` folder present in any subdirectory will be ignored. +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 to a specific 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 all text logs +... ignore_patterns="**/logs/*.txt", # Ignore tous les logs en .txt ... ) ``` -You can also use the `delete_patterns` argument to specify files you want to delete from the repo in the same commit. -This can prove useful if you want to clean a remote folder before pushing files in it and you don't know which files -already exists. +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à. -The example below uploads the local `./logs` folder to the remote `/experiment/logs/` folder. Only txt files are uploaded -but before that, all previous logs on the repo on deleted. All of this in a single commit. +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 all local text files -... delete_patterns="*.txt", # Delete all remote text files before +... allow_patterns="*.txt", # Upload tous les fichiers textes locaux +... delete_patterns="*.txt", # Supprime tous les fichiers textes distants avant d'upload ... ) ``` -## Upload from the CLI +## Upload depuis le CLI -You can use the `huggingface-cli upload` command from the terminal to directly upload files to the Hub. Internally it uses the same [`upload_file`] and [`upload_folder`] helpers described above. +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. -You can either upload a single file or an entire folder: +Vous pouvez upload un unique fichier ou un dossier entier: ```bash -# Usage: huggingface-cli upload [repo_id] [local_path] [path_in_repo] +# 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 @@ -120,30 +120,32 @@ https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors https://huggingface.co/Wauplin/my-cool-model/tree/main ``` -`local_path` and `path_in_repo` are optional and can be implicitly inferred. If `local_path` is not set, the tool will -check if a local folder or file has the same name as the `repo_id`. If that's the case, its content will be uploaded. -Otherwise, an exception is raised asking the user to explicitly set `local_path`. In any case, if `path_in_repo` is not -set, files are uploaded at the root of the repo. +`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. -For more details about the CLI upload command, please refer to the [CLI guide](./cli#huggingface-cli-upload). +Pour plus de détails sur la commande uplaod du CLI, consultez le[guide CLI](./cli#huggingface-cli-upload). -## Advanced features +## Fonctionnalités avancées -In most cases, you won't need more than [`upload_file`] and [`upload_folder`] to upload your files to the Hub. -However, `huggingface_hub` has more advanced features to make things easier. Let's have a look at them! +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. -### Non-blocking uploads +### Uploads non bloquants -In some cases, you want to push data without blocking your main thread. This is particularly useful to upload logs and -artifacts while continuing a training. To do so, you can use the `run_as_future` argument in both [`upload_file`] and -[`upload_folder`]. This will return a [`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#future-objects) -object that you can use to check the status of the upload. +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 in the background (non-blocking action) +>>> 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, @@ -152,20 +154,21 @@ object that you can use to check the status of the upload. Future(...) >>> future.done() False ->>> future.result() # Wait for the upload to complete (blocking action) +>>> future.result() # Attend que l'upload soit finie (action bloquante) ... ``` -Background jobs are queued when using `run_as_future=True`. This means that you are guaranteed that the jobs will be -executed in the correct order. +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. -Even though background jobs are mostly useful to upload data/create commits, you can queue any method you like using -[`run_as_future`]. For instance, you can use it to create a repo and then upload data to it in the background. The -built-in `run_as_future` argument in upload methods is just an alias around it. +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 @@ -181,24 +184,25 @@ Future(...) Future(...) ``` -### Upload a folder by chunks +### Upload un dossier par morceaux -[`upload_folder`] makes it easy to upload an entire folder to the Hub. However, for large folders (thousands of files or -hundreds of GB), it can still be challenging. If you have a folder with a lot of files, you might want to upload -it in several commits. If you experience an error or a connection issue during the upload, you would not have to resume -the process from the beginning. +[`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. -To upload a folder in multiple commits, just pass `multi_commits=True` as argument. Under the hood, `huggingface_hub` -will list the files to upload/delete and split them in several commits. The "strategy" (i.e. how to split the commits) -is based on the number and size of the files to upload. A PR is open on the Hub to push all the commits. Once the PR is -ready, the commits are squashed into a single commit. If the process is interrupted before completing, you can rerun -your script to resume the upload. The created PR will be automatically detected and the upload will resume from where -it stopped. It is recommended to pass `multi_commits_verbose=True` to get a better understanding of the upload and its -progress. +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. -The example below will upload the checkpoints folder to a dataset in multiple commits. A PR will be created on the Hub -and merged automatically once the upload is complete. If you prefer the PR to stay open and review it manually, you can -pass `create_pr=True`. +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( @@ -210,26 +214,25 @@ pass `create_pr=True`. ... ) ``` -If you want a better control on the upload strategy (i.e. the commits that are created), you can have a look at the -low-level [`plan_multi_commits`] and [`create_commits_on_pr`] methods. +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` is still an experimental feature. Its API and behavior is subject to change in the future without prior -notice. +`multi_commits` est toujours une fonctionnalité expérimentale. Son API et son comportement pourraient changer dans le futur +sans avertissement préalable. -### Scheduled uploads +### Uploads planifiées -The Hugging Face Hub makes it easy to save and version data. However, there are some limitations when updating the same file thousands of times. For instance, you might want to save logs of a training process or user -feedback on a deployed Space. In these cases, uploading the data as a dataset on the Hub makes sense, but it can be hard to do properly. The main reason is that you don't want to version every update of your data because it'll make the git repository unusable. The [`CommitScheduler`] class offers a solution to this problem. +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 espace 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. -The idea is to run a background job that regularly pushes a local folder to the Hub. Let's assume you have a -Gradio Space that takes as input some text and generates two translations of it. Then, the user can select their preferred translation. For each run, you want to save the input, output, and user preference to analyze the results. This is a -perfect use case for [`CommitScheduler`]; you want to save data to the Hub (potentially millions of user feedback), but -you don't _need_ to save in real-time each user's input. Instead, you can save the data locally in a JSON file and -upload it every 10 minutes. For example: +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 espace 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 @@ -238,11 +241,11 @@ upload it every 10 minutes. For example: >>> import gradio as gr >>> from huggingface_hub import CommitScheduler -# Define the file where to save the data. Use UUID to make sure not to overwrite existing data from a previous run. +# 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 -# Schedule regular uploads. Remote repo and local folder are created if they don't already exist. +# 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", @@ -251,7 +254,7 @@ upload it every 10 minutes. For example: ... every=10, ... ) -# Define the function that will be called when the user submits its feedback (to be called in Gradio) +# 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. @@ -261,112 +264,117 @@ upload it every 10 minutes. For example: ... f.write(json.dumps({"input": input_text, "output_1": output_1, "output_2": output_2, "user_choice": user_choice})) ... f.write("\n") -# Start Gradio +# Lancement de Gradio >>> with gr.Blocks() as demo: ->>> ... # define Gradio demo + use `save_feedback` +>>> ... # Définition de la démo Gradio, ne pas oublier d'utiliser `save_feedback` >>> demo.launch() ``` -And that's it! User input/outputs and feedback will be available as a dataset on the Hub. By using a unique JSON file name, you are guaranteed you won't overwrite data from a previous run or data from another -Spaces/replicas pushing concurrently to the same repository. +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. -For more details about the [`CommitScheduler`], here is what you need to know: +Pour plus de détails sur le [`CommitScheduler`], voici ce que vous devez savoir: - **append-only:** - It is assumed that you will only add content to the folder. You must only append data to existing files or create - new files. Deleting or overwriting a file might corrupt your repository. -- **git history**: - The scheduler will commit the folder every `every` minutes. To avoid polluting the git repository too much, it is - recommended to set a minimal value of 5 minutes. Besides, the scheduler is designed to avoid empty commits. If no - new content is detected in the folder, the scheduled commit is dropped. -- **errors:** - The scheduler run as background thread. It is started when you instantiate the class and never stops. In particular, - if an error occurs during the upload (example: connection issue), the scheduler will silently ignore it and retry - at the next scheduled commit. -- **thread-safety:** - In most cases it is safe to assume that you can write to a file without having to worry about a lock file. The - scheduler will not crash or be corrupted if you write content to the folder while it's uploading. In practice, - _it is possible_ that concurrency issues happen for heavy-loaded apps. In this case, we advice to use the - `scheduler.lock` lock to ensure thread-safety. The lock is blocked only when the scheduler scans the folder for - changes, not when it uploads data. You can safely assume that it will not affect the user experience on your Space. + 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 espace. #### Space persistence demo -Persisting data from a Space to a Dataset on the Hub is the main use case for [`CommitScheduler`]. Depending on the use -case, you might want to structure your data differently. The structure has to be robust to concurrent users and -restarts which often implies generating UUIDs. Besides robustness, you should upload data in a format readable by the 🤗 Datasets library for later reuse. We created a [Space](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) -that demonstrates how to save several different data formats (you may need to adapt it for your own specific needs). +Faire persister des données d'un espace 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 [espace](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). -#### Custom uploads +#### Uploads personnalisées -[`CommitScheduler`] assumes your data is append-only and should be uploading "as is". However, you -might want to customize the way data is uploaded. You can do that by creating a class inheriting from [`CommitScheduler`] -and overwrite the `push_to_hub` method (feel free to overwrite it any way you want). You are guaranteed it will -be called every `every` minutes in a background thread. You don't have to worry about concurrency and errors but you -must be careful about other aspects, such as pushing empty commits or duplicated data. +[`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. -In the (simplified) example below, we overwrite `push_to_hub` to zip all PNG files in a single archive to avoid -overloading the repo on the Hub: +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. List PNG files + # 1. Liste les fichiers PNG png_files = list(self.folder_path.glob("*.png")) if len(png_files) == 0: - return None # return early if nothing to commit + return None # return directement si rien à commit - # 2. Zip png files in a single archive + # 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 archive + # 3. Upload l'archive self.api.upload_file(..., path_or_fileobj=archive_path) - # 4. Delete local png files to avoid re-uploading them later + # 4. Supprime les fichiers PNG locaux pour éviter de les ré-upload plus tard for png_file in png_files: png_file.unlink() ``` -When you overwrite `push_to_hub`, you have access to the attributes of [`CommitScheduler`] and especially: -- [`HfApi`] client: `api` -- Folder parameters: `folder_path` and `path_in_repo` -- Repo parameters: `repo_id`, `repo_type`, `revision` -- The thread lock: `lock` +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` -For more examples of custom schedulers, check out our [demo Space](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) -containing different implementations depending on your use cases. +Pour plus d'exemples de planififcateurs personnalisés, consultez notre +[espace de démos](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) contenant différentes implementations +dépendant de votre cas d'usage. ### create_commit -The [`upload_file`] and [`upload_folder`] functions are high-level APIs that are generally convenient to use. We recommend -trying these functions first if you don't need to work at a lower level. However, if you want to work at a commit-level, -you can use the [`create_commit`] function directly. +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`]. -There are three types of operations supported by [`create_commit`]: +Il y a trois types d'opérations supportées par [`create_commit`]: -- [`CommitOperationAdd`] uploads a file to the Hub. If the file already exists, the file contents are overwritten. This operation accepts two arguments: +- [`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. - - `path_in_repo`: the repository path to upload a file to. - - `path_or_fileobj`: either a path to a file on your filesystem or a file-like object. This is the content of the file to upload to the Hub. +- [`CommitOperationDelete`] supprime un fichier ou un dossier d'un dépôt. Cette opération accepte `path_in_repo` en argument. -- [`CommitOperationDelete`] removes a file or a folder from a repository. This operation accepts `path_in_repo` as an argument. +- [`CommitOperationCopy`] copie un fichier d'un dépôt. Cette opération prend en entré trois arguments: -- [`CommitOperationCopy`] copies a file within a repository. This operation accepts three 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. - - `src_path_in_repo`: the repository path of the file to copy. - - `path_in_repo`: the repository path where the file should be copied. - - `src_revision`: optional - the revision of the file to copy if your want to copy a file from a different branch/revision. +Par exmeple, si vous voulez upload deux fichiers et supprimer dossier: -For example, if you want to upload two files and delete a file in a Hub repository: - -1. Use the appropriate `CommitOperation` to add or delete a file and to delete a folder: +1. Utilisez la bonne `CommitOperation` pour ajouter ou supprimer un fichier en supprimer un dossier: ```py >>> from huggingface_hub import HfApi, CommitOperationAdd, CommitOperationDelete @@ -380,7 +388,7 @@ For example, if you want to upload two files and delete a file in a Hub reposito ... ] ``` -2. Pass your operations to [`create_commit`]: +2. Passez vos opérations à [`create_commit`]: ```py >>> api.create_commit( @@ -390,112 +398,120 @@ For example, if you want to upload two files and delete a file in a Hub reposito ... ) ``` -In addition to [`upload_file`] and [`upload_folder`], the following functions also use [`create_commit`] under the hood: +En plus d'[`upload_file`] et [`upload_folder`], les fonctions suivante utilisent aussi [`create_commit`] en arrière plan: -- [`delete_file`] deletes a single file from a repository on the Hub. -- [`delete_folder`] deletes an entire folder from a repository on the Hub. -- [`metadata_update`] updates a repository's metadata. +- [`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. -For more detailed information, take a look at the [`HfApi`] reference. +Pour plus d'informations, consultez la référence [`HfApi`]. -### Preupload LFS files before commit +### Preupload des fichier LFS avant le commit -In some cases, you might want to upload huge files to S3 **before** making the commit call. For example, if you are -committing a dataset in several shards that are generated in-memory, you would need to upload the shards one by one -to avoid an out-of-memory issue. A solution is to upload each shard as a separate commit on the repo. While being -perfectly valid, this solution has the drawback of potentially messing the git history by generating tens of commits. -To overcome this issue, you can upload your files one by one to S3 and then create a single commit at the end. This -is possible using [`preupload_lfs_files`] in combination with [`create_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`]. -This is a power-user method. Directly using [`upload_file`], [`upload_folder`] or [`create_commit`] instead of handling -the low-level logic of pre-uploading files is the way to go in the vast majority of cases. The main caveat of -[`preupload_lfs_files`] is that until the commit is actually made, the upload files are not accessible on the repo on -the Hub. If you have a question, feel free to ping us on our Discord or in a GitHub issue. +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. -Here is a simple example illustrating how to pre-upload files: +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 = [] # List of all `CommitOperationAdd` objects that will be generated +>>> operations = [] # Liste de toutes les objets `CommitOperationsAdd` qui seront générés >>> for i in range(5): -... content = ... # generate binary content +... 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) ->>> # Create commit +>>> # Créé un commit >>> create_commit(repo_id, operations=operations, commit_message="Commit all shards") ``` -First, we create the [`CommitOperationAdd`] objects one by one. In a real-world example, those would contain the -generated shards. Each file is uploaded before generating the next one. During the [`preupload_lfs_files`] step, **the -`CommitOperationAdd` object is mutated**. You should only use it to pass it directly to [`create_commit`]. The main -update of the object is that **the binary content is removed** from it, meaning that it will be garbage-collected if -you don't store another reference to it. This is expected as we don't want to keep in memory the content that is -already uploaded. Finally we create the commit by passing all the operations to [`create_commit`]. You can pass -additional operations (add, delete or copy) that have not been processed yet and they will be handled correctly. - -## Tips and tricks for large uploads - -There are some limitations to be aware of when dealing with a large amount of data in your repo. Given the time it takes to stream the data, -getting an upload/push to fail at the end of the process or encountering a degraded experience, be it on hf.co or when working locally, can be very annoying. - -Check out our [Repository limitations and recommendations](https://huggingface.co/docs/hub/repositories-recommendations) guide for best practices on how to structure your repositories on the Hub. Next, let's move on with some practical tips to make your upload process as smooth as possible. - -- **Start small**: We recommend starting with a small amount of data to test your upload script. It's easier to iterate -on a script when failing takes only a little time. -- **Expect failures**: Streaming large amounts of data is challenging. You don't know what can happen, but it's always -best to consider that something will fail at least once -no matter if it's due to your machine, your connection, or our -servers. For example, if you plan to upload a large number of files, it's best to keep track locally of which files you -already uploaded before uploading the next batch. You are ensured that an LFS file that is already committed will never -be re-uploaded twice but checking it client-side can still save some time. -- **Use `hf_transfer`**: this is a Rust-based [library](https://github.com/huggingface/hf_transfer) meant to speed up -uploads on machines with very high bandwidth. To use it, you must install it (`pip install hf_transfer`) and enable it -by setting `HF_HUB_ENABLE_HF_TRANSFER=1` as an environment variable. You can then use `huggingface_hub` normally. -Disclaimer: this is a power user tool. It is tested and production-ready but lacks user-friendly features like advanced error handling or proxies. For more details, please refer to this [section](https://huggingface.co/docs/huggingface_hub/hf_transfer). +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). -Progress bars are supported in `hf_transfer` starting from version `0.1.4`. Consider upgrading (`pip install -U hf-transfer`) if you plan to enable faster uploads. +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. -## (legacy) Upload files with Git LFS +## (approche historique) Uploadez des fichiers avec Git LFS -All the methods described above use the Hub's API to upload files. This is the recommended way to upload files to the Hub. -However, we also provide [`Repository`], a wrapper around the git tool to manage a local repository. +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. -Although [`Repository`] is not formally deprecated, we recommend using the HTTP-based methods described above instead. -For more details about this recommendation, please have a look at [this guide](../concepts/git_vs_http) explaining the -core differences between HTTP-based and Git-based approaches. +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 automatically handles files larger than 10MB. But for very large files (>5GB), you need to install a custom transfer agent for Git LFS: +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 ``` -You should install this for each repository that has a very large file. Once installed, you'll be able to push files larger than 5GB. +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. -### commit context manager +### Gestionnaire de contexte de commit -The `commit` context manager handles four of the most common Git commands: pull, add, commit, and push. `git-lfs` automatically tracks any file larger than 10MB. In the following example, the `commit` context manager: +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. Pulls from the `text-files` repository. -2. Adds a change made to `file.txt`. -3. Commits the change. -4. Pushes the change to the `text-files` repository. +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 @@ -504,7 +520,8 @@ The `commit` context manager handles four of the most common Git commands: pull, ... f.write(json.dumps({"hey": 8})) ``` -Here is another example of how to use the `commit` context manager to save and upload a file to a repository: +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 @@ -513,66 +530,66 @@ Here is another example of how to use the `commit` context manager to save and u ... torch.save(model.state_dict(), "model.pt") ``` -Set `blocking=False` if you would like to push your commits asynchronously. Non-blocking behavior is helpful when you want to continue running your script while your commits are being pushed. +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) ``` -You can check the status of your push with the `command_queue` method: +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 ``` -Refer to the table below for the possible statuses: +Référez vous à la table ci dessous pour la liste de statuts possibles: -| Status | Description | +| Statut | Description | | -------- | ------------------------------------ | -| -1 | The push is ongoing. | -| 0 | The push has completed successfully. | -| Non-zero | An error has occurred. | +| -1 | Le push est en cours | +| 0 | Le push s'est fini sans erreurs. | +| Non-zero | Il y a eu une erreur. | -When `blocking=False`, commands are tracked, and your script will only exit when all pushes are completed, even if other errors occur in your script. Some additional useful commands for checking the status of a push include: +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 -# Inspect an error. +# Inspecte une erreur >>> last_command.stderr -# Check whether a push is completed or ongoing. +# Vérifie si un push est fini ou en cours >>> last_command.is_done -# Check whether a push command has errored. +# Vérifie si une commande push a donné une erreur >>> last_command.failed ``` ### push_to_hub -The [`Repository`] class has a [`~Repository.push_to_hub`] function to add files, make a commit, and push them to a repository. Unlike the `commit` context manager, you'll need to pull from a repository first before calling [`~Repository.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`]. -For example, if you've already cloned a repository from the Hub, then you can initialize the `repo` from the local directory: +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") ``` -Update your local clone with [`~Repository.git_pull`] and then push your file to the Hub: +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") ``` -However, if you aren't ready to push a file yet, you can use [`~Repository.git_add`] and [`~Repository.git_commit`] to only add and commit your file: +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 :)") ``` -When you're ready, push the file to your repository with [`~Repository.git_push`]: +Une fois que vous êtes prêt, push le fichier vers votre dépôt avec [`~Repository.git_push`]: ```py >>> repo.git_push() From a16687272c714ae067458211b705b22686f559ac Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 8 Jan 2024 00:45:50 +0100 Subject: [PATCH 035/129] Added "fr" to .github/workflow --- .github/workflows/build_documentation.yaml | 2 +- .github/workflows/build_pr_documentation.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build_documentation.yaml b/.github/workflows/build_documentation.yaml index 775716b0e6..6b7103ad21 100644 --- a/.github/workflows/build_documentation.yaml +++ b/.github/workflows/build_documentation.yaml @@ -13,6 +13,6 @@ jobs: with: commit_sha: ${{ github.sha }} package: huggingface_hub - languages: en de hi ko + languages: en de hi ko fr secrets: hf_token: ${{ secrets.HF_DOC_BUILD_PUSH }} diff --git a/.github/workflows/build_pr_documentation.yaml b/.github/workflows/build_pr_documentation.yaml index 02b48ff447..0791c2292f 100644 --- a/.github/workflows/build_pr_documentation.yaml +++ b/.github/workflows/build_pr_documentation.yaml @@ -14,4 +14,4 @@ jobs: commit_sha: ${{ github.event.pull_request.head.sha }} pr_number: ${{ github.event.number }} package: huggingface_hub - languages: en de hi ko + languages: en de hi ko fr From a6bff362ac31ed54045ad2daa5ad8978e0c62f75 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 8 Jan 2024 00:48:22 +0100 Subject: [PATCH 036/129] Deleted redirects as it is not needed --- docs/source/fr/_redirects.yml | 14 -------------- 1 file changed, 14 deletions(-) delete mode 100644 docs/source/fr/_redirects.yml diff --git a/docs/source/fr/_redirects.yml b/docs/source/fr/_redirects.yml deleted file mode 100644 index 6ab1ffef13..0000000000 --- a/docs/source/fr/_redirects.yml +++ /dev/null @@ -1,14 +0,0 @@ -# Move "how-to" pages to the guides/ folder -how-to-cache: guides/manage-cache -how-to-discussions-and-pull-requests: guides/community -how-to-downstream: guides/download -how-to-inference: guides/inference -how-to-manage: guides/repository -how-to-model-cards: guides/model-cards -how-to-upstream: guides/upload -search-the-hub: guides/search -guides/manage_spaces: guides/manage-spaces -package_reference/inference_api: package_reference/inference_client - -# Alias for hf-transfer description -hf_transfer: package_reference/environment_variables#hfhubenablehftransfer \ No newline at end of file From 69460568ff0a467ce29da27ad0d6b14889847200 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 8 Jan 2024 00:50:32 +0100 Subject: [PATCH 037/129] Corrected toctree.yml --- docs/source/fr/_toctree.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index d055e2adfc..2cefbdddc6 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -6,7 +6,7 @@ title: Quickstart - local: installation title: Installation -- title: "Guides et instructions" +- title: "Guides" sections: - local: guides/overview title: Vue d'ensemble @@ -33,13 +33,13 @@ - local: guides/manage-cache title: Cache - local: guides/model-cards - title: Carte de modèle + title: Model cards - local: guides/manage-spaces - title: Gérez votre espace + title: Gérez vos Spaces - local: guides/integrations title: Intégrer une librairie - local: guides/webhooks_server - title: Serveur Webhook + title: Webhooks - title: "Guides conceptuels" sections: - local: concepts/git_vs_http From c1af8c0ba50a874fda53cc2e10441957b28a9af3 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 8 Jan 2024 00:51:42 +0100 Subject: [PATCH 038/129] Corrected errors o quick-start.md --- docs/source/fr/quick-start.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/source/fr/quick-start.md b/docs/source/fr/quick-start.md index bf3cfb7821..3e1b2649a7 100644 --- a/docs/source/fr/quick-start.md +++ b/docs/source/fr/quick-start.md @@ -8,7 +8,7 @@ Le [Hub Hugging Face](https://huggingface.co/) est le meilleur endroit pour part modèles de machine learning, des démos, des datasets et des métriques. La librairie `huggingface_hub` vous aide à intéragir avec le Hub sans sortir de votre environnement de développement. Vous pouvez: créer et gérer des dépôts facilement, télécharger et upload des -fichiers, et obtenir des modèles et des metadata depuis le Hub. +fichiers, et obtenir des modèles et des métadonnées depuis le Hub. ## Installation @@ -22,9 +22,9 @@ Pour plus de détails, vérifiez le guide d'[installation](installation) ## Télécharger des fichiers -Les dépôts sur le Hub sont sous controle de version Git, et les utilisateurs peuvent +Les dépôts sur le Hub utilisent le versioning Git, les utilisateurs peuvent télécharger un fichier, ou un dépôt entier. Vous pouvez utiliser la fonction [`hf_hub_download`] -pour télécharger des fichiers. Cette fonction télécharger et mettra dans le cache un fichier +pour télécharger des fichiers. Cette fonction téléchargera et mettra dans le cache un fichier sur votre disque local. La prochaine fois que vous aurez besoin de ce fichier, il sera chargé depuis votre cache de façon à ce que vous n'ayez pas besoin de le retélécharger. @@ -39,7 +39,7 @@ modèle [Pegasus](https://huggingface.co/google/pegasus-xsum): Pour télécharger une version spécifique du fichier, utilisez le paramètre `revision` afin de spécifier le nom de la branche, le tag ou le hash de commit. Si vous décidez d'utiliser -le hash de commit, ce doit être le hash entier et pas le hash court de 7 caractères: +le hash de commit, vous devez renseigner le hash entier et pas le hash court de 7 caractères: ```py >>> from huggingface_hub import hf_hub_download @@ -71,7 +71,7 @@ huggingface-cli login huggingface-cli login --token $HUGGINGFACE_TOKEN ``` -Alternativement, vous pouvez vous connecter en utilisant [`login`] dans un notebook ou +Sinon, vous pouvez vous connecter en utilisant [`login`] dans un notebook ou un script: ```py @@ -86,13 +86,13 @@ de charger le token depuis un trousseau sécurisé aulieu de l'enregistrer en cl codebase/notebook. Vous ne pouvez être connecté qu'à un seul compte à la fois. Si vous connectez votre machine à un autre compte, -vous serez déconnectés du premier compte. Vérifiez toujours le compte que vous utilisez avec la commande +vous serez déconnecté du premier compte. Vérifiez toujours le compte que vous utilisez avec la commande `huggingface-cli whoami`. Si vous voulez gérer plusieurs compte dans le même script, vous pouvez passer votre token à chaque appel de méthode. C'est aussi utile si vous ne voulez pas sauvegarder de token sur votre machine. -une fois que vous êtes connectés, toutes les requêtes vers le Hub (même les méthodes qui ne nécessite pas explicitement +Une fois que vous êtes connectés, toutes les requêtes vers le Hub (même les méthodes qui ne nécessite pas explicitement d'authentification) utiliseront votre token d'authentification par défaut. Si vous voulez supprimer l'utilisation implicite de votre token, vous devez définir la variable d'environnement `HF_HUB_DISABLE_IMPLICIT_TOKEN`. @@ -100,7 +100,7 @@ de votre token, vous devez définir la variable d'environnement `HF_HUB_DISABLE_ ## Créer un dépôt -Une fois que vous avez créer votre compte et que vous vous êtes connectés, +Une fois que vous avez créé votre compte et que vous vous êtes connectés, vous pouvez créer un dépôt avec la fonction [`create_repo`]: ```py @@ -147,17 +147,17 @@ Vous devez spécifier: ``` Pour upload plus d'un fichier à la fois, consultez le guide [upload](./guides/upload) -qui vous expliqueras plusieurs méthodes pour upload des fichiers (avec ou sans Git). +qui détaille plusieurs méthodes pour upload des fichiers (avec ou sans Git). ## Prochaines étapes -La librairie `huggingface_hub` offre une manière simple aux utilisateurs pour qu'ils puissent -intéragir avec le Hub via Python. Pour en apprendre plus sur comment gérer vos fichiers -et vos dépôts sur le Hub, nous vous recommandons de lire notre [how-to guides](./guides/overview) +La librairie `huggingface_hub` permet à ses utilisateurs d'intéragir facilementavec le Hub via +Python. Pour en apprendre plus sur comment gérer vos fichiers +et vos dépôts sur le Hub, nous vous recommandons de lire notre [guide conceptuel](./guides/overview) pour : - [Gérer votre dépôt](./guides/repository). -- [Télécharger](./guides/download) des fichiers depuis le HUb. +- [Télécharger](./guides/download) des fichiers depuis le Hub. - [Upload](./guides/upload) des fichiers vers le Hub. - [Faire des recherches dans le Hub](./guides/search) pour votre modèle ou dataset. - [Accédder à l'API d'inférence](./guides/inference) pour faire des inférences rapides. \ No newline at end of file From 5569ed9c9f145648683f35e6f67300f61effb63d Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Mon, 8 Jan 2024 14:42:43 +0100 Subject: [PATCH 039/129] Corrected installation.md --- docs/source/fr/installation.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index e10ab06b17..6bfcfba9f2 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -140,18 +140,17 @@ Task: text-generation ## Les limitations Windows -Afin de démocratiser le machine learning pour tous, nous avons construit `huggingface_hub` -de façon à avoir une librairie cross-platform et en particulier, une librairie qui marche -sur tous les systèmes d'exploitation. Toutefois il y a certains cas où -`huggingface_hub` est plus limité lorsqu'il tourne sur Windows. Ci-dessous une liste exhaustive -des problèmes connus. N'hésitez pas à nous signaler si vous rencontrez un problème -sans documentation en ouvrant une [issue sur Github](https://github.com/huggingface/huggingface_hub/issues/new/choose). +Afin de démocratiser le machine learning pour tous, nous avons développé `huggingface_hub` +de manière cross-platform et en particulier, pour qu'elle fonctionne sur un maximum de systèmes d'exploitation différents. +Toutefois, `huggingface_hub` connaît dans certains cas des limiations sur Windows. +Nous avons listés ci-dessous les problèmes connus. N'hésitez pas à nous signaler si vous rencontrez un problème +non documenté en ouvrant une [issue sur Github](https://github.com/huggingface/huggingface_hub/issues/new/choose). - Le cache de `huggingface_hub` a besoin des symlinks pour mettre en cache les fichiers installé depuis le Hub. -Sur windows, vous devez activer le mode développeur pour lancer votre script en tant qu'administrateur -afin d'activer les symlinks. S'il ne sont pas activés, le système de cache fonctionnera toujours mais -de manière suboptimale. Consultez les [limitations du cache](./guides/manage-cache#limitations) pour plus de détails. -- Les chemins de fichiers sur le Hub peuvent avoir des caractères spéciaux (par exemple `"path/to?/my/file"`). +Sur windows, vous devez activer le mode développeur pour lancer ou lancer votre script en tant qu'administrateur +afin de faire fonctionner les symlinks. S'ils ne sont pas activés, le système de cache fonctionnera toujours mais +de manière sous-optimale. Consultez les [limitations du cache](./guides/manage-cache#limitations) pour plus de détails. +- Les noms de fichiers sur le Hub peuvent avoir des caractères spéciaux (par exemple `"path/to?/my/file"`). Windows est plus restrictif sur les [caractères spéciaux](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) ce qui rend ces fichiers ininstallables sur Windows. Heureusement c'est un cas assez rare. Contactez le propriétaire du dépôt si vous pensez que c'est une erreur ou contactez nous From 913454f6fb7d44aa7736ccc6d99b840c2f862a02 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Wed, 10 Jan 2024 13:52:49 +0100 Subject: [PATCH 040/129] Changed the translation of the product "space" in the whole documentation. --- docs/source/fr/concepts/git_vs_http.md | 2 +- docs/source/fr/guides/cli.md | 16 +-- docs/source/fr/guides/collections.md | 10 +- docs/source/fr/guides/hf_file_system.md | 2 +- docs/source/fr/guides/manage-cache.md | 2 +- docs/source/fr/guides/manage-spaces.md | 98 +++++++++---------- docs/source/fr/guides/model-cards.md | 2 +- docs/source/fr/guides/overview.md | 8 +- docs/source/fr/guides/repository.md | 10 +- docs/source/fr/guides/search.md | 6 +- docs/source/fr/guides/upload.md | 14 +-- docs/source/fr/guides/webhooks_server.md | 28 +++--- docs/source/fr/package_reference/cards.md | 2 +- .../fr/package_reference/collections.md | 2 +- .../environment_variables.md | 2 +- .../fr/package_reference/space_runtime.md | 6 +- .../fr/package_reference/webhooks_server.md | 4 +- 17 files changed, 107 insertions(+), 107 deletions(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index d038138c22..9903fe9128 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -5,7 +5,7 @@ rendered properly in your Markdown viewer. # Paradigme Git vs HTTP La librairie `huggingface_hub` est une librairie qui permet d'intéragir avec le Hub Hugging Face, -qui est une collection de dépots Git (modèles, datasets ou espaces). +qui est une collection de dépots Git (modèles, datasets ou spaces). Il y a deux manières principales pour accéder au Hub en utilisant `huggingface_hub`. La première approche, basée sur Git, appelée approche "git-based", est rendue possible par la classe [`Repository`]. diff --git a/docs/source/fr/guides/cli.md b/docs/source/fr/guides/cli.md index 5c96de0e27..7cfa787959 100644 --- a/docs/source/fr/guides/cli.md +++ b/docs/source/fr/guides/cli.md @@ -186,9 +186,9 @@ Fetching 8 files: 100%|███████████████████ /home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7b ``` -### Télécharger un dataset où un espace +### Télécharger un dataset ou un space -Les exemples ci-dessus montrent comment télécharger des fichiers depuis un dépôt. Pour télécharger un dataset ou un espace, utilisez +Les exemples ci-dessus montrent comment télécharger des fichiers depuis un dépôt. Pour télécharger un dataset ou un space, utilisez l'option `--repo-type`: ```bash @@ -321,17 +321,17 @@ 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 l'espace local en supprimant les fichiers distant et en uploadant tous les fichiers sauf ceux dans `/logs`: +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 distant et en uploadant tous les fichiers sauf ceux dans `/logs`: ```bash -# Synchronisation de l'espace 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 de l'espace local avec le Hub" +# 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 espace +### Upload vers un dataset ou un space -Pour upload vers un dataset ou un espace, utilisez l'option `--repo-type`: +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 @@ -410,7 +410,7 @@ 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 savoir 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`: +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 diff --git a/docs/source/fr/guides/collections.md b/docs/source/fr/guides/collections.md index 98412867e6..e65b4d4a74 100644 --- a/docs/source/fr/guides/collections.md +++ b/docs/source/fr/guides/collections.md @@ -4,7 +4,7 @@ rendered properly in your Markdown viewer. # Collections -Une collection est un groupe d'objets reliés entre eux sur le Hub (par exemple des modèles, des datases, des espaces 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. +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 la gestion avec du code. @@ -46,12 +46,12 @@ CollectionItem( 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 espace ou un article. +- 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, espace 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, espace ou article +- 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ées à un objet. Ceci 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. @@ -211,7 +211,7 @@ Enfin, vous pouvez aussi supprimer un objet en utilisant [`delete_collection_ite >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) -# Supprimer l'espace `coqui/xtts` de la liste +# Supprimer le space `coqui/xtts` de la liste >>> delete_collection_item(collection_slug=collection_slug, item_object_id=collection.items[0].item_object_id) ``` diff --git a/docs/source/fr/guides/hf_file_system.md b/docs/source/fr/guides/hf_file_system.md index b28feea7f0..4c55a4229c 100644 --- a/docs/source/fr/guides/hf_file_system.md +++ b/docs/source/fr/guides/hf_file_system.md @@ -46,7 +46,7 @@ A la différence des fonction native de Python `open`, la fonction `open` de `fs hf://[][@]/ ``` -Le `repo_type_prefix` vaut `datasets/` pour les datasets, `spaces/` pour les espaces, et les modèles n'ont pas besoin de préfixe dans l'URL. +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: diff --git a/docs/source/fr/guides/manage-cache.md b/docs/source/fr/guides/manage-cache.md index fb96c3c24b..0e37bbc3ea 100644 --- a/docs/source/fr/guides/manage-cache.md +++ b/docs/source/fr/guides/manage-cache.md @@ -22,7 +22,7 @@ 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 espaces ont tous la même racine. Chacun de ces dépôts contient +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: diff --git a/docs/source/fr/guides/manage-spaces.md b/docs/source/fr/guides/manage-spaces.md index 75975e3ad5..520b593ce3 100644 --- a/docs/source/fr/guides/manage-spaces.md +++ b/docs/source/fr/guides/manage-spaces.md @@ -2,18 +2,18 @@ rendered properly in your Markdown viewer. --> -# Gérez votre espace +# Gérez votre space -Dans ce guide, nous allons voir comment gérer le temps de calcul sur votre espace, +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 espace sur le Hub. +Voici un exemple de A à Z pour créer et mettre en place un space sur le Hub. -**1. Créez un espace sur le Hub.** +**1. Créez un space sur le Hub.** ```py >>> from huggingface_hub import HfApi @@ -24,10 +24,10 @@ Voici un exemple de A à Z pour créer et mettre en place un espace sur le Hub. >>> api.create_repo(repo_id=repo_id, repo_type="space", space_sdk="gradio") ``` -**1. (bis) Dupliquez un espace.** +**1. (bis) Dupliquez un space.** -Ceci peut-être utile si vous voulez construire depuis un espace existant aulieu de commencer à zéro. -C'est aussi utile si vous voulez controler la configuration et les paramètres d'un espace publique. +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 @@ -36,7 +36,7 @@ Consultez [`duplicate_space`] pour plus de détails. **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 espace: +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/") @@ -48,10 +48,10 @@ meilleur hardware. **3. Configurez des secrets et des variables** -Votre espace aura peut-être besoin d'une clef secrète, un token ou de 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 espace. +une fois généré depuis votre space. ```py >>> api.add_space_secret(repo_id=repo_id, key="HF_TOKEN", value="hf_api_***") @@ -65,19 +65,19 @@ Les secrets et les variables peuvent supprimés aussi: ``` -Depuis votre espace, les secrets sont définissables en tant que variables +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 espace (secrets ou hardware) relancera votre +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 de l'espace!** +**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 espace: +Les secrets et les variables peuvent être défini lors de la création ou la duplication d'un space: ```py >>> api.create_repo( @@ -99,9 +99,9 @@ Les secrets et les variables peuvent être défini lors de la création ou la du **4. Configurez le hardware** -Par défaut, votre espace tournera sur un CPU gratuitement. Vous pouvez améliorer le +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 espace. Consultez [la doc](https://huggingface.co/docs/hub/spaces-gpus) +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 @@ -113,9 +113,9 @@ pour plus de détails. >>> 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 espace doit +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 espace tourne pour vérifier que votre demande a été réalisée. +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) @@ -127,14 +127,14 @@ hardware votre espace tourne pour vérifier que votre demande a été réalisée "t4-medium" ``` -Vous avez maintenant un espace totalement configuré. Une fois que vous avez fini avec les +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 espace!** +**Bonus: demandez du hardware lors de la création ou la duplication d'un space!** -Les nouvel hardware sera automatiquement assigné à votre espace une fois qu'il +Les nouvel hardware sera automatiquement assigné à votre space une fois qu'il a été construit. ```py @@ -156,44 +156,44 @@ a été construit. ... ) ``` -**5. Mettez en pause et relancez votre espace** +**5. Mettez en pause et relancez votre space** -Par défaut, si votre espace tourne sur un hardware amélioré, il ne sera jamais arrêté. Toutefois pour éviter de vous +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 espace en pause sera inactif tant que le propriétaire de l'espace ne l'a pas relancé, +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 -# Mettez en pause votre espace pour éviter de payer +# Met en pause le space pour éviter de payer >>> api.pause_space(repo_id=repo_id) # (...) -# Relancez le quand vous en avez besoin +# 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 espace. Si votre espace est inactif pour une durée +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 espace le relancera. Vous pouvez définir un timeout en utilisant [`set_space_sleep_time`]. +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 -# Mettez votre espace en pause après une heure d'inactivité +# 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 espace -se mettre en pause automatiquement aprèss 48h d'inactivité. +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 espace une fois construit. +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 espace!** +**Bonus: définissez un temps de timeout lors de la création ou de la duplication d'un space!** ```py >>> api.create_repo( @@ -212,9 +212,9 @@ Le hardware amélioré sera automatiquement assigné à votre espace une fois co ... ) ``` -**6. Ajoutez du stockage persistant à votre espace** +**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 de l'espace. Ceci signifie que +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. @@ -228,11 +228,11 @@ Vous pouvez aussi supprimer votre stockage, mais vous perdrez toute la donnée d >>> api.delete_space_storage(repo_id=repo_id) ``` -Note: Vous ne pouvez pas diminuer le niveau de stockage de votre espace une fois qu'il a été +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 de l'espace!** +**Bonus: demandez du stockage lors de la création ou la duplication du space!** ```py >>> api.create_repo( @@ -249,16 +249,16 @@ donné. Pour ce faire, vous devez d'abord supprimer le stockage ... ) ``` -## Avancé: améliorez votre espace pour un durée déterminée! +## Avancé: améliorez votre space pour un durée déterminée! -Les espaces ont un grand nombre de cas d'application. Parfois, vous aurez -peut-être envie de faire un tourner un espace pendant une durée déterminée sur un hardware -spécifique, faire quelque chose puis éteindre l'espace. dans cette section, nous explorerons -les avantgaes des espaces pour finetune un modèle sur demande. C'est la seule manière de +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 espace pour finetune un modèle. C'est une aplication Gradio qui +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. @@ -267,9 +267,9 @@ prend en entrée l'id d'un modèle et l'id d'un dataset. Le workflow est le suiv 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 espace +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 espace, +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". @@ -288,16 +288,16 @@ pour vous assurer que vous êtes le seul utilisateur. ```py -# Un espace aura besoin de votre token pour demander du hardware: définissez le en temps que secret! +# 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 de l'espace +# 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 de l'espace, vérifiez si une tâche est programmée. Si oui, finetunez le modèle. Si non, +# 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: @@ -310,7 +310,7 @@ if task is None: gr.Interface(fn=gradio_fn, ...).launch() else: runtime = api.get_space_runtime(repo_id=TRAINING_SPACE_ID) - # Vérifiez si l'espace est chargé avec un GPU. + # 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) diff --git a/docs/source/fr/guides/model-cards.md b/docs/source/fr/guides/model-cards.md index 0c7818e516..74bcdcfaf0 100644 --- a/docs/source/fr/guides/model-cards.md +++ b/docs/source/fr/guides/model-cards.md @@ -246,7 +246,7 @@ Une pull request créé de cette commande peut-être vue [ici](https://huggingfa 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 espace. 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. +`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: diff --git a/docs/source/fr/guides/overview.md b/docs/source/fr/guides/overview.md index 2661c8128b..6c1e10fbae 100644 --- a/docs/source/fr/guides/overview.md +++ b/docs/source/fr/guides/overview.md @@ -42,7 +42,7 @@ Consultez ces guides pour apprendre à utiliser `huggingface_hub` pour résoudre
Recherche

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

@@ -103,9 +103,9 @@ Consultez ces guides pour apprendre à utiliser `huggingface_hub` pour résoudre
- Gérez votre espace + Gérez votre space

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

@@ -123,7 +123,7 @@ Consultez ces guides pour apprendre à utiliser `huggingface_hub` pour résoudre
Serveurs WebHooks

- Comment créer un serveur pour recevoir des webhooks et le dépployer en tant qu'espace? + 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 index a9a5849318..db635a310d 100644 --- a/docs/source/fr/guides/repository.md +++ b/docs/source/fr/guides/repository.md @@ -73,12 +73,12 @@ Précisez le `repo_id` du dépôt que vous voulez supprimer: >>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset") ``` -### Dupliquer un dépôt (uniquement pour les espaces) +### 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 espaces en utilisant la méthode [`duplicate_space`]. Elle dupliquera le dépôt entier. +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 espaces](./manage-spaces) pour plus de détails. +Consultez notre guide [gérez vos spaces](./manage-spaces) pour plus de détails. ```py >>> from huggingface_hub import duplicate_space @@ -108,7 +108,7 @@ Vous pouvez créer de nouvelles branches et de nouveaux tags en utilisant [`crea ```py >>> from huggingface_hub import create_branch, create_tag -# Créé une branche sur le dépôt d'un espace basée sur la branche `main` +# 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` @@ -143,7 +143,7 @@ dans la page de paramètre du dépôt dans votre navigateur. Vous devez avoir la 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 espaces (hardware, variables d'environnement,...). Pour les configurern, consultez notre guide [Gérez vos espaces](../guides/manage-spaces) +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é diff --git a/docs/source/fr/guides/search.md b/docs/source/fr/guides/search.md index bb443b6540..6df3dda91f 100644 --- a/docs/source/fr/guides/search.md +++ b/docs/source/fr/guides/search.md @@ -4,12 +4,12 @@ rendered properly in your Markdown viewer. # Faites des recherches dans le Hub -Dans ce tutoriel, vous apprendrez à chercher des modèles, des datasets et des espaces du Hub en utilisant `huggingface_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 espaces enregistrés sur 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 @@ -19,7 +19,7 @@ Ce client peut, entre autres, lister les modèles, les dataset et les espaces en 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 espaces. +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 ? diff --git a/docs/source/fr/guides/upload.md b/docs/source/fr/guides/upload.md index 165449f009..c3af60ff4a 100644 --- a/docs/source/fr/guides/upload.md +++ b/docs/source/fr/guides/upload.md @@ -64,7 +64,7 @@ votre type de dépôt, vous pouvez facultativement définir le type de dépôt >>> from huggingface_hub import HfApi >>> api = HfApi() -# Upload tout le contenu du fichier local vers votre espace distant +# 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", @@ -226,10 +226,10 @@ 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 espace 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. +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 espace 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. +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: @@ -291,15 +291,15 @@ Pour plus de détails sur le [`CommitScheduler`], voici ce que vous devez savoir 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 espace. + 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 espace vers un dataset sur le Hub est le cas d'usage le plus courant pour [`CommitScheduler`]. +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 [espace](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) +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). @@ -347,7 +347,7 @@ Lorsque vous modifier `push_to_hub` en faisant un overwrite, vous avez accès au Pour plus d'exemples de planififcateurs personnalisés, consultez notre -[espace de démos](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) contenant différentes implementations +[space de démo](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) contenant différentes implementations dépendant de votre cas d'usage. diff --git a/docs/source/fr/guides/webhooks_server.md b/docs/source/fr/guides/webhooks_server.md index 8f40d3b77b..250f0ac5b7 100644 --- a/docs/source/fr/guides/webhooks_server.md +++ b/docs/source/fr/guides/webhooks_server.md @@ -18,8 +18,8 @@ pour écouter les webhooks. -Pour voir un exemple fonctionnel de serveur webhooj, consultez l'[espace bot CI](https://huggingface.co/spaces/spaces-ci-bot/webhook). -C'est un espace qui lance des environnements éphémères lorsqu'une pull request est ouverte sur un espace. +Pour voir un exemple fonctionnel de serveur webhook, consultez le [space bot CI](https://huggingface.co/spaces/spaces-ci-bot/webhook). +C'est un space qui lance des environnements éphémères lorsqu'une pull request est ouverte sur un space. @@ -77,7 +77,7 @@ FastAPI parsera automatiquement le paquet et le passera à la fonction en tant q `pydantic` qui contient toutes les informations sur l'événement qui a activé le webhook. 3. L'application Gradio a aussi ouvert un tunnel pour recevoir des requêtes d'internet. C'est la partie intéressante: vous pouvez configurer un webhooj sur https://huggingface.co/settings/webhooks qui pointe vers votre machine. C'est utile -pour debugger votre serveur webhook et rapidement itérer avant de le déployer dans un espace. +pour debugger votre serveur webhook et rapidement itérer avant de le déployer dans un space. 4. Enfin, les logs vous disent aussi que votre serveur n'est pas sécurisé par un secret. Ce n'est pas problématique pour le debugging en local mais c'est à garder dans un coin de la tête pour plus tard. @@ -104,24 +104,24 @@ surveiller et l'URL du webhook, ici `https://1fadb0f52d8bf825fc.gradio.live/webh Et voilà! Vous pouvez maintenant activer cce webhook en mettant à jour le dépôt cible (i.e. push un commit). Consultez la table d'activité de votre webhook pour voir les événements passés. Maintenant que vous avez un setup qui fonctionne, vous pouvez le tester et itérer rapidement. Si vous modifiez votre code et relancez le serveur, votre URL public pourrait -changer. Assurez vous de mettre à jour la configuration du webhook dans le HUb si besoin. +changer. Assurez vous de mettre à jour la configuration du webhook dans le Hub si besoin. -## Déployer vers un espace +## Déployer vers un space -Maintenant que vous avez un serveur webhook fonctionnel, le but est de le déplyer sur un espace. Allez sur -https://huggingface.co/new-space pour créer un espace. Donnez lui un nom, sélectionnez le SDK Gradio et cliquer sur -"Créer un espace" (ou "Create Space" en anglais). Uploadez votre code dans l'espace dans un fichier appelé `app.py`. -Votre espace sera lancé automatiquement! Pour plus de détails sur les espaces, consultez ce [guide](https://huggingface.co/docs/hub/spaces-overview). +Maintenant que vous avez un serveur webhook fonctionnel, le but est de le déployer sur un space. Allez sur +https://huggingface.co/new-space pour créer un space. Donnez lui un nom, sélectionnez le SDK Gradio et cliquer sur +"Créer un space" (ou "Create Space" en anglais). Uploadez votre code dans le space dans un fichier appelé `app.py`. +Votre space sera lancé automatiquement! Pour plus de détails sur les spaces, consultez ce [guide](https://huggingface.co/docs/hub/spaces-overview). -Votre serveur webhook tourne maintenant sur un espace public. Dans la plupart de cas, vous aurez besoin de le sécuriser -avec un secret. Allez dans les paramètres de votre espace > Section "Repository secrets" > "Add a secret". Définissez +Votre serveur webhook tourne maintenant sur un space public. Dans la plupart de cas, vous aurez besoin de le sécuriser +avec un secret. Allez dans les paramètres de votre space > Section "Repository secrets" > "Add a secret". Définissez la variable d'environnement `WEBHOOK_SECRET` en choisissant la valeur que vous voulez. Retournez dans les [réglages webhooks](https://huggingface.co/settings/webhooks) et définissez le secret dans la configuration du webhook. Maintenant, seules les requêtes avec le bon secret seront acceptées par votre serveur. -Et c'est out! Votre espace est maintenant prêt à recevoir des webhooks du Hub. Gardez à l'esprit que si vous faites -tourner l'espace sur le hardware gratuit 'cpu-basic', il sera éteint après 48 heures d'inactivité. Si vous avez besoin d'un -espace permanent, vous devriez peut-être considérer l'amélioration vers un [hardware amélioré](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs). +Et c'est tout! Votre space est maintenant prêt à recevoir des webhooks du Hub. Gardez à l'esprit que si vous faites +tourner le space sur le hardware gratuit 'cpu-basic', il sera éteint après 48 heures d'inactivité. Si vous avez besoin d'un +space permanent, vous devriez peut-être considérer l'amélioration vers un [hardware amélioré](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs). ## Utilisation avancée diff --git a/docs/source/fr/package_reference/cards.md b/docs/source/fr/package_reference/cards.md index 71bc71fa2b..98dfb25a8f 100644 --- a/docs/source/fr/package_reference/cards.md +++ b/docs/source/fr/package_reference/cards.md @@ -46,7 +46,7 @@ Dataset cards are also known as Data Cards in the ML Community. [[autodoc]] DatasetCardData -## Cartes d'espace +## Cartes de Space ### SpaceCard diff --git a/docs/source/fr/package_reference/collections.md b/docs/source/fr/package_reference/collections.md index ed9e79cb71..5745528280 100644 --- a/docs/source/fr/package_reference/collections.md +++ b/docs/source/fr/package_reference/collections.md @@ -5,7 +5,7 @@ rendered properly in your Markdown viewer. # Gérer les collections Consultez la page de documentation [`HfApi`] pour les références des méthodes qui vous permettront -de gérer votre espace sur le Hub. +de gérer votre space sur le Hub. - Afficher le contenu d'une collection: [`get_collection`] - Créer une nouvelle collection: [`create_collection`] diff --git a/docs/source/fr/package_reference/environment_variables.md b/docs/source/fr/package_reference/environment_variables.md index 418545806a..ad76eeb227 100644 --- a/docs/source/fr/package_reference/environment_variables.md +++ b/docs/source/fr/package_reference/environment_variables.md @@ -35,7 +35,7 @@ est définie. ### HF_HUB_CACHE Pour configurer le chemin vers lequels les dépôts du Hub seront mis en cache en local -(modèles, datasets et espaces). +(modèles, datasets et spaces). Par défaut, ce sera `"$HF_HOME/hub"` (i.e. `"~/.cache/huggingface/hub"` par défaut). diff --git a/docs/source/fr/package_reference/space_runtime.md b/docs/source/fr/package_reference/space_runtime.md index 956570520e..96bb480b7c 100644 --- a/docs/source/fr/package_reference/space_runtime.md +++ b/docs/source/fr/package_reference/space_runtime.md @@ -2,12 +2,12 @@ rendered properly in your Markdown viewer. --> -# Gérez votre temps d'exécution de votre espace +# Gérez le temps d'exécution de votre space -Consultez la page de documentation d'[`HfApi`] pour les références des méthodes pour gérer votre espace +Consultez la page de documentation d'[`HfApi`] pour les références des méthodes pour gérer votre space sur le Hub. -- Dupliquer un espace: [`duplicate_space`] +- Dupliquer un space: [`duplicate_space`] - Afficher les temps de calcul actuels: [`get_space_runtime`] - Gérer les secrets: [`add_space_secret`] et [`delete_space_secret`] - Gérer le hardware: [`request_space_hardware`] diff --git a/docs/source/fr/package_reference/webhooks_server.md b/docs/source/fr/package_reference/webhooks_server.md index 422a1ec328..0ae7e5dc74 100644 --- a/docs/source/fr/package_reference/webhooks_server.md +++ b/docs/source/fr/package_reference/webhooks_server.md @@ -12,7 +12,7 @@ le [guide](https://huggingface.co/docs/hub/webhooks) consacré aux webhooks. Consultez ce [guide](../guides/webhooks_server) pour un tutoriel pas à pas sur comment mettre en place votre serveur -webhooks et le déployer en tant qu'espace. +webhooks et le déployer en tant que space. @@ -31,7 +31,7 @@ des fonctionnalités expérimentales. Vous pouvez le supprimer en définissant l Le serveur est une application [Gradio](https://gradio.app/). Il possède une interface pour afficher des instructions pour vous ou vos utilisateurs et une API pour écouter les webhooks. Implémenter un endpoint de webhook est aussi simple que d'ajouter un décorateur à une fonction. Vous pouvez ensuite le debugger en redirigeant le webhook vers votre machine (en utilisant -un tunnel Gradio) avant de le déployer sur un espace. +un tunnel Gradio) avant de le déployer sur un space. ### WebhooksServer From 4187a373b6d50f9645f17be69942daf933a1f912 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Fri, 2 Feb 2024 10:26:12 +0100 Subject: [PATCH 041/129] Corrected git_vs_http --- docs/source/fr/concepts/git_vs_http.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index 9903fe9128..09c6ef5e31 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -4,12 +4,12 @@ rendered properly in your Markdown viewer. # Paradigme Git vs HTTP -La librairie `huggingface_hub` est une librairie qui permet d'intéragir avec le Hub Hugging Face, +`huggingface_hub` est une librairie qui permet d'intéragir avec le Hub Hugging Face, qui est une collection de dépots Git (modèles, datasets ou spaces). Il y a deux manières principales pour accéder au Hub en utilisant `huggingface_hub`. La première approche, basée sur Git, appelée approche "git-based", est rendue possible par la classe [`Repository`]. -Cette méthode utilise un wrapper autour de la commande `git` avec des fonctionnalités supplémentaires conçues pour intéragir avec le Hub. La deuxième option, appelée approche "HTTP-based" , nécessite de faire des requêtes HTTP en utilisant le client [`HfApi`]. Éxaminions +Cette méthode utilise un wrapper autour de la commande `git` avec des fonctionnalités supplémentaires conçues pour intéragir avec le Hub. La deuxième option, appelée approche "HTTP-based" , consiste à faire des requêtes HTTP en utilisant le client [`HfApi`]. Éxaminions les avantages et les inconvénients de ces deux méthodes. ## Repository: L'approche hstorique basée sur git @@ -23,11 +23,11 @@ méthodes en arrière-plan, ce qui la rend utile pour upload des données pendan L'avantage principal de l'utilisation de [`Repository`] est que cette méthode permet de garder une copie en local de tout le dépot Git sur votre machine. Cela peut aussi devenir un désavantage, -car cette copie locale doit être mise à jour et maintenue constamment. C'est une manière de procéder +car cette copie locale doit être mise à jour et maintenue constamment. C'est une méthode analogue au développement de logiciel classique où chaque développeur maintient sa propre copie locale et push les changement lorsqu'il travaille sur une fonctionnalité. Toutefois, dans le contexte du machine learning, elle n'est pas toujours pertinente car -les utilisateurs ont parfois uniquement besoin d'avoir +les utilisateurs ont parfois juste besoin d'avoir les poids des modèles pour l'inférence ou de convertir ces poids d'un format à un autre sans avoir à cloner tout le dépôt. @@ -41,7 +41,7 @@ la suppression complète de [`Repository`] ne sera faite que pour la version `v1 ## HfApi: Un client HTTP flexible et pratique La classe [`HfApi`] a été développée afin de fournir une alternative aux dépôts git locaux, -qui peuvent être encombrant à maintenir, en particulier lors de l'utilisation de gros modèles ou de datasets volumineux. +qui peuvent être peu pratiques à maintenir, en particulier lors de l'utilisation de gros modèles ou de datasets volumineux. La classe [`HfApi`] offre les mêmes fonctionnalités que les approches basées sur Git, telles que le téléchargement et le push de fichier ainsi que la création de branches et de tags, mais sans avoir besoin d'un fichier local qui doit être constamment synchronisé. @@ -50,20 +50,20 @@ En plus des fonctionnalités déjà fournies par `git`, La classe [`HfApi`] offr additionnelles, telles que la capacité de gérer des dépôts, le téléchargement des fichiers en utilisant le cache pour une réutilisation plus efficace, la recherche dans le Hub pour trouver des dépôts et des métadonnées, l'accès aux fonctionnalités de communautés telles que, les dicussions, -les pull requests, les commentaires, et la configuration d'espaces hardwares et de secrets. +les pull requests, les commentaires, et la configuration de spaces et de secrets. ## Quelle méthode utiliser et quand ? -En général, **L'approche basée sur l'HTTP est la méthode recommandée** pour l'utilisation d'`huggingface_hub`. -[`HfApi`] permet de pull et push des changements, travailler avec les pull requests, les tags et les branches, l'intréaction avec les discussions -et bien plus encore. Depuis la sortie `0.16`, les méthodes basées sur l'HTTP peuvent aussi tourner en arrière plan, ce qui était le +En général, **L'approche basée sur HTTP est la méthode recommandée** pour l'utilisation d'`huggingface_hub`. +[`HfApi`] permet de pull et push des changements, de travailler avec les pull requests, les tags et les branches, d'intéragir avec les discussions +et bien plus encore. Depuis la sortie `0.16`, les méthodes basées sur HTTP peuvent aussi tourner en arrière plan, ce qui était le dernier gros avantage de la classe [`Repository`] sur [`HfApi`]. Toutefois, certaines commandes restent indisponibles en utilisant [`HfApi`]. -Peut être que certaines ne le seront jamais, mais nous essayons toujours de réduire le fossé entre les deux approches. +Peut être que certaines ne le seront jamais, mais nous essayons toujours de réduire le fossé entre ces deux approches. Si votre cas d'usage n'est pas couvert, nous serions ravis de vous aider. Pour cela, ouvrez [une issue sur Github](https://github.com/huggingface/huggingface_hub)! Nous sommes prêt à entendre tout type de retour nous permettant de construire l'écosystème 🤗 avec les utilisateurs et pour les utilisateurs. Cette préférence pour l'approche basé sur [`HfApi`] au détriment de celle basée sur [`Repository`] ne signifie pas que le versioning git disparaitra -du Hub Hugging Face. Il sera toujours possible d'utiliser les commandes `git` en local lorsque cela a du sens. \ No newline at end of file +du Hub Hugging Face. Il sera toujours possible d'utiliser les commandes `git` en local lorsque c'est pertinent. \ No newline at end of file From 561798448bc14811a2efffc6c559e691724e506b Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Fri, 2 Feb 2024 11:08:17 +0100 Subject: [PATCH 042/129] Corrected CLI.md --- docs/source/fr/guides/cli.md | 45 +++++++++++++++++------------------- 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/docs/source/fr/guides/cli.md b/docs/source/fr/guides/cli.md index 7cfa787959..f18e3fe743 100644 --- a/docs/source/fr/guides/cli.md +++ b/docs/source/fr/guides/cli.md @@ -5,7 +5,7 @@ rendered properly in your Markdown viewer. # 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 et download des fichiers, etc. +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. @@ -20,8 +20,7 @@ Tout d'abord, installons le CLI: -Dans les snippet ci dessus, nous avons aussi installé les dépendances `[cli]` pour rendre l'expérience utilisateur meilleure, en particulier lors de -l'utilisation de la commande `delete-cache`. +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`. @@ -56,15 +55,14 @@ tel que `command not found: huggingface-cli`, veuillez vous référer au guide 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 pour upload des fichiers en utilisant le +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 (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) depuis vos [paramètres](https://huggingface.co/settings/tokens). Ce token est utilisé pour authentifier votre identité au Hub. +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 : @@ -93,7 +91,7 @@ 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 mettre votre token directement depuis +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. @@ -120,13 +118,13 @@ Si vous n'êtes pas connecté, un message d'erreur sera renvoyé. ## huggingface-cli logout -Cette commande vous déconecte. En pratique, elle supprime le token enregistré sur votre machine. +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 interne, cette commande utilise +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: @@ -137,7 +135,7 @@ huggingface-cli download --help ### Télécharger un fichier -Pour télécharger un unique fichier d'un dépôt, mettez simplement le repo_id et le nom du fichier ainsi : +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 @@ -146,11 +144,11 @@ downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/waupli /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 sur votre machine locale. +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 spécifier que l'id du dépôt: +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 @@ -162,7 +160,7 @@ Fetching 23 files: 0%| | 0/23 [ ### Télécharger plusieurs fichiers -Vous pouvez aussi télécharger un sous ensemble des fichiers d'un dépôt en une seule commande. Vous pouvez faire ceci de deux manières. Si vous avez +Vous pouvez aussi télécharger un sous ensemble des fichiers d'un dépôt en une seule commande. Vous pouvez le faire de deux manières. Si vous avez déjà une liste précise des fichiers à télécharger, vous pouvez simplement les mettre un par un: ```bash @@ -213,7 +211,7 @@ nom de la branche ou tag), utilisez l'option `revision`: ### 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 les déplacer dans un dossier spécifique. C'est utile pour avoir un fonctionnement similaire à celui de git. Vous pouvez faire ceci en utilisant l'option `--local_dir`. +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`. @@ -260,7 +258,7 @@ et des barres de progression. Si vous ne voulez pas de ce type de message, utili ## huggingface-cli upload -Utilisez la commande `huggingface-cli upload` pour uploader des fichiers directement dans le Hub. En interne, cette commande utilise les mêmes helpers +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: @@ -276,7 +274,7 @@ L'utilisation par défaut de cette commande est: # Utilisation: huggingface-cli upload [repo_id] [local_path] [path_in_repo] ``` -Pour upload le chemin courant dans la racine du dépôts, utilisez: +Pour upload le chemin actuel à la racine du dépôt, utilisez: ```bash >>> huggingface-cli upload mon-super-modele . . @@ -304,8 +302,7 @@ 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: +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 @@ -321,7 +318,7 @@ 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 distant et en uploadant tous les fichiers sauf ceux dans `/logs`: +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) @@ -357,7 +354,7 @@ Par défaut, les fichiers sont upload vers la branche `main`. Si vous voulez upl ... ``` -**Note:** Si `revision` n'existe pas et que `--create-pr` n'est pas utilisé, une branche sera créé automatiquement à partir de la branche `main`. +**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 @@ -371,7 +368,7 @@ 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, ça peut-être utile 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`: +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 @@ -401,7 +398,7 @@ 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é. Ceci peut-être utile si vous voulez utiliser l'output d'une autre commande dans un script. +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 @@ -427,11 +424,11 @@ 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, veuillez vous référer au guide [Gérez votre cache](./manage-cache#scan-cache-from-the-terminal). +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. C'est utile pour 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 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 From 48c4612289c16a4ff2e943fba1b3a1c9f9b580e5 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Fri, 2 Feb 2024 13:06:30 +0100 Subject: [PATCH 043/129] Corrected collections.md --- docs/source/fr/guides/collections.md | 29 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/source/fr/guides/collections.md b/docs/source/fr/guides/collections.md index e65b4d4a74..c83cb5e4f7 100644 --- a/docs/source/fr/guides/collections.md +++ b/docs/source/fr/guides/collections.md @@ -6,11 +6,11 @@ rendered properly in your Markdown viewer. 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 la gestion avec du code. +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 de l'ID de la collection. Vous pouvez trouver le slug dans l'URL de la page dédiée à la 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.
@@ -54,13 +54,13 @@ Chaque objet d'une collection aura forcément: - 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ées à un objet. Ceci 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. +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 -Nous pouvons 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). +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 @@ -82,7 +82,7 @@ Lorsque vous listez des collections, la liste d'objet est tronquée à 4 objets -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é par popularité, et en limitant au nombre de 5, le nombre de collections affichées. +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): @@ -117,8 +117,7 @@ Maintenant que nous savons comment avoir une [`Collection`], créons la nôtre! ... ) ``` -Un objet [`Collection`] sera retourné avec les métadonnées (titre, description, propriétaire, etc.) et une liste vide d'objets. Vous serez maintenant capable de vous référer à cette collection en utilisant son `slug`. -It will return a [`Collection`] object with the high-level metadata (title, description, owner, etc.) and an empty list of items. You will now be able to refer to this collection using it's `slug`. +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 @@ -133,11 +132,11 @@ It will return a [`Collection`] object with the high-level metadata (title, desc ## Gérer des objets dans une collection -Maintenant que nous notre [`Collection`], nous allons y ajouter des objets et les organiser. +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 un `note` à l'objet (500 caractères max). +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 @@ -167,7 +166,7 @@ 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 +# 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) @@ -181,18 +180,18 @@ Réutilisons l'exemple ci-dessus: ### Remettre en ordre les objets -Les objets dans une collection sont rangés dans un ordre. L'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 +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 +# Récupère la collection >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) -# Change l'ordre pour placer les deux objets `Wuerstchen` ensemble +# 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, @@ -207,11 +206,11 @@ Enfin, vous pouvez aussi supprimer un objet en utilisant [`delete_collection_ite ```py >>> from huggingface_hub import get_collection, update_collection_item -# Récupére la collection +# Récupère la collection >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) -# Supprimer le space `coqui/xtts` de la liste +# Supprime le space `coqui/xtts` de la liste >>> delete_collection_item(collection_slug=collection_slug, item_object_id=collection.items[0].item_object_id) ``` From 7efb7012edee6e7871cb19e01e703d06b7edfab0 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 3 Feb 2024 09:02:26 +0100 Subject: [PATCH 044/129] Corrected community.md --- docs/source/fr/guides/community.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/source/fr/guides/community.md b/docs/source/fr/guides/community.md index 21fee9742c..8afcbebe97 100644 --- a/docs/source/fr/guides/community.md +++ b/docs/source/fr/guides/community.md @@ -2,7 +2,7 @@ rendered properly in your Markdown viewer. --> -# Intéragisser avec les discussions et les pull requests +# 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) @@ -11,7 +11,7 @@ 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 en particulier: +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 @@ -78,7 +78,7 @@ DiscussionWithDetails( ``` [`HfApi.get_discussion_details`] renvoie un objet [`DiscuccionWithDetails`], qui est une sous-classe de [`Discussion`] -avec des informations plus détaillées sur la discussion ou la pull request. Les informations incluent tous les commentaires, +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 @@ -87,12 +87,12 @@ 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 manière de créer et d'éditer des discussions et +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 des discussions ou des pull requests. +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`]: -fixez simplement le paramètre `create_pr` à `True`. Ce paramètre est aussi disponible avec d'autres méthodes +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`] @@ -133,13 +133,13 @@ DiscussionWithDetails(...) 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: +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`] to add comments - * [`edit_discussion_comment`] to edit comments - * [`rename_discussion`] to rename a Discussion or Pull Request - * [`change_discussion_status`] to open or close a Discussion / Pull Request - * [`merge_pull_request`] to merge a Pull Request + * [`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. From de03384c9e05d43e5ad0dc3642384d1e678028ad Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 3 Feb 2024 09:25:22 +0100 Subject: [PATCH 045/129] Corrected download.md --- docs/source/fr/guides/download.md | 54 +++++++++++++++---------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/source/fr/guides/download.md b/docs/source/fr/guides/download.md index f90a3b4910..9dae248d92 100644 --- a/docs/source/fr/guides/download.md +++ b/docs/source/fr/guides/download.md @@ -37,7 +37,7 @@ le fichier sera considéré comme appartenant à un dépôt contenant des objets >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") '/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' -# Télécharger depuis un dataset +# Télécharge un dataset >>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") '/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' ``` @@ -50,25 +50,25 @@ ou un hash de commit). Pour ce faire, utilisez le paramètre `revision`: ```python -# Télécharger à partir de tag `v1.0` +# Télécharge à partir du tag `v1.0` >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") -# Télécharger à partir de la branche `test-branch` +# Télécharge à partir de la branche `test-branch` >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") -# Téléchargerà partir de la pull request #3 +# Télécharge à partir de la pull request #3 >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") -# Télécharger à partir d'un hash de commit spécifique +# Télécharge à partir d'un hash de commit spécifique >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") ``` -**Note:** Lorsque vous utilisez le hash de commit, vous devez renseigner le hash complet et pas le hash de commit de 7 caractères. +**Note:** Lorsque vous utilisez le hash de commit, vous devez renseigner le hash complet et pas le hash de commit à 7 caractères. -### Construire un URL de téléchargement +### Générer un URL de téléchargement -Si vous voulez construire l'URL utilisé pour télécharger un fichier depuis un dépôt, vous pouvez utiliser [`hf_hub_url`] -qui renvoie un URL. Notez que cette méthode est utilisée en interne par [`hf_hub_download`]. +Si vous voulez générer l'URL utilisé pour télécharger un fichier depuis un dépôt, vous pouvez utiliser [`hf_hub_url`] +qui renvoie un URL. Notez que cette méthode est utilisée en arrière plan par [`hf_hub_download`]. ## Télécharger un dépôt entier @@ -83,7 +83,7 @@ Pour télécharger un dépôt entier, passez simplement le `repo_id` et le `repo >>> snapshot_download(repo_id="lysandre/arxiv-nlp") '/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' -# Ou depuis un dataset +# Ou pour un dataset >>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") '/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' ``` @@ -98,12 +98,12 @@ le paramètre `revision`: ### Filtrer les fichiers à télécharger -[`snapshot_download`] offre une manière simple de télécharger un dépôt. Cependant, vous ne voudrait pas constamment -télécharger tout le contenu d'un dépôt. Par exemple, vous n'aurez peut-être pas envie de télécharger tous les fichiers -`.bin` si vous savez que vous utiliserez uniquement les poids du `.safetensors`. Vous pouvez faire ceci en utilisant -les paramètres `allow_patterns` et `ignore_patterns`. +[`snapshot_download`] offre une manière simple de télécharger un dépôt. Cependant, vous ne voudrez peut être pas +télécharger tout le contenu d'un dépôt à chaque fois. Par exemple, vous n'aurez peut-être pas envie de télécharger +tous les fichiers `.bin` si vous savez que vous utiliserez uniquement les poids du `.safetensors`. Vous pouvez +faire ceci en utilisant les paramètres `allow_patterns` et `ignore_patterns`. -Ces paramètres acceptent un pattern ou une liste de patterns. Les patterns sont des wildcards standard, comme précisé +Ces paramètres acceptent un pattern ou une liste de patterns. Les patterns sont des wildcards standards, comme précisé [ici](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). Le matching de pattern utilise [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). Par exemple, vous pouvez utiliser `allow_patterns` pour ne télécharger que les fichiers de configuration JSON: @@ -122,7 +122,7 @@ suivant ignore les fichiers ayant pour extension `.msgpack` et `.h5`: ``` Enfin, vous pouvez combiner les deux pour filtrer avec précision vos téléchargements. voici un exemple pour télécharger -tous les markdowns json à l'exception de `vocab.json` +tous les fichiers en .md et en .json à l'exception de `vocab.json` ```python >>> from huggingface_hub import snapshot_download @@ -141,27 +141,27 @@ pouvez faire ceci en utilisant les paramètres `local_dir` et `local_dir_use_sym - `local_dir` doit être un chemin vers un dossier de votre système. Les fichiers téléchargés garderont la même structure de fichier que dans le dépôt. Par exemple, si `filename="data/train.csv"` et `local_dir="path/to/folder"`, alors le chemin renvoyé sera `"path/to/folder/data/train.csv"`. -- `local_dir_use_symlinks` définit comment le fichier doit être enregistré sur votre dossier local. - - Le comportement par défaut (`"auto"`), dupliquera les fichiers peu volumineux (<5MB) et utilise les symlinks pour +- `local_dir_use_symlinks` renseigne comment le fichier doit être enregistré sur votre dossier local. + - Le comportement par défaut (`"auto"`), dupliquera les fichiers peu volumineux (<5MB) et utilisera les symlinks pour les fichiers plus gros. Les symlinks permettent d'optimiser à la fois la bande passante et l'utilisation du disque. Cependant, éditer manuellement un fichier sous symlink pourrait corrompre le cache, d'où la duplication pour des petits fichiers. Le seuil de 5MB peut être configuré avec la variable d'environnement`HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD`. - - Si `local_dir_use_symlinks=True` est définit, alors tous les fichiers seront sous symlink pour une utilisation - optimal de l'espace disque? C'est par exemple utile lors du téléchargement d'un dataset très volumineux contenant + - Si `local_dir_use_symlinks=True` est passé, alors tous les fichiers seront sous symlink pour une utilisation + optimal de l'espace disque. C'est par exemple utile lors du téléchargement d'un dataset très volumineux contenant des milliers de petits fichiers. - Enfin, si vous ne voulez pas utiliser de symlink du tout, vous pouvez les désactier (`local_dir_use_symlinks=False`). Le chemin du cache sera toujours utilisé afin de vérifier si le fichier est déjà en cache ou pas. Si ce dernier n'est pas déjà en cache, il sera téléchargé et déplacé directement vers le chemin local. Ce qui signifie que si vous avez besoin de le réutiliser ailleurs, il sera **retéléchargé** -Voici un table qui résume les différentes options pour vous aider à choisir les paramètres qui collent le mieux à votre situation. +Voici une table qui résume les différentes options pour vous aider à choisir les paramètres qui collent le mieux à votre situation. -| Paramètre | Fichier déjà en cahce | Chemin renvoyé | Peut-on lire le chemin? | Pouvez vous sauvegarder le chemin | Bande passante optimisée | Utilisation du disque optimisée | +| Paramètre | Fichier déjà en cahce | Chemin renvoyé | Peut-on lire le chemin | Pouvez vous sauvegarder le chemin | Bande passante optimisée | Utilisation du disque optimisée | |---|:---:|:---:|:---:|:---:|:---:|:---:| | `local_dir=None` | | symlink en cache | ✅ | ❌
_(sauvegarder corromprait le cache)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | fichier ou symlink dans un dossier | ✅ | ✅ _(for small files)_
⚠️ _(for big files do not resolve path before saving)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | symlink dans un dossier | ✅ | ⚠️
_(do not resolve path before saving)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | fichier ou symlink dans un dossier | ✅ | ✅ _(pour les petits fichiers)_
⚠️ _(pour les gros fichiers, ne resolve pas le path avant l'enregistrement)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | symlink dans un dossier | ✅ | ⚠️
_(ne resolve pas le paht avant l'enregistrement)_ | ✅ | ✅ | | `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | Non | fichier dans un dossier | ✅ | ✅ | ❌
_(en cas de re-run, le fichier est retéléchargé)_ | ⚠️
(plusieurs copies si lancé dans plusieurs dossiers) | | `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | oui | fichier dans un dossier | ✅ | ✅ | ⚠️
_(le fichier doit être mis en cache d'abord)_ | ❌
_(le fichier est dupliqué)_ | @@ -178,8 +178,8 @@ décrits ci-dessus et affiche le chemin renvoyé dans le terminal. /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` -Vous pouvez télécharger plusieurs fichiers d'un coup ce qui affiche une barre de chargement et renvoie le chemin du -snapshot dans lequel les fichiers sont localisés! +Vous pouvez télécharger plusieurs fichiers d'un coup, ce qui affiche une barre de chargement et renvoie le chemin de +la snapshot dans lequel les fichiers sont localisés. ```bash >>> huggingface-cli download gpt2 config.json model.safetensors @@ -191,7 +191,7 @@ Pour plus de détails sur la commande download du CLI, veuillez consulter le [gu ## Téléchargements plus rapides -Si vous tuilisez une machine avec une bande passante plus large, vous pouvez augmenter votre vitesse de téléchargement en utilisant [`hf_transfer`], +Si vous utilisez une machine avec une bande passante plus large, vous pouvez augmenter votre vitesse de téléchargement en utilisant [`hf_transfer`], une librairie basée sur Rust développée pour accélérer le transfer de fichiers avec le Hub. Pour l'activer, installez le package (`pip install hf_transfer`) et définissez set `HF_HUB_ENABLE_HF_TRANSFER=1` en tant que variable d'environnement From 353fa2399c8c56b94a374ae7cc7a117ee1639c5a Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 3 Feb 2024 09:32:09 +0100 Subject: [PATCH 046/129] Corrected hf_file_system --- docs/source/fr/guides/hf_file_system.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/fr/guides/hf_file_system.md b/docs/source/fr/guides/hf_file_system.md index 4c55a4229c..749ddc43ff 100644 --- a/docs/source/fr/guides/hf_file_system.md +++ b/docs/source/fr/guides/hf_file_system.md @@ -2,7 +2,7 @@ rendered properly in your Markdown viewer. --> -# Intéragissez avec le Hub à partir de l'API Filesystem +# 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`. @@ -34,9 +34,9 @@ En plus d'[`HfApi`], la librairie `huggingface_hub` fournit [`HfFileSystem`], un ... 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 un hash de commit. +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. -A la différence des fonction native 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. +À 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 @@ -98,7 +98,7 @@ Un workflow similaire peut-être utilisé pour les dataframes [Dask](https://doc ## 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'authentifications sur le Hub. +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`]: From 1fad9bd669e201765ee9cf01a1adb2ba4fa4361f Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:12:17 +0100 Subject: [PATCH 047/129] Correction of docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index 09c6ef5e31..a9c245c135 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -49,7 +49,7 @@ avoir besoin d'un fichier local qui doit être constamment synchronisé. En plus des fonctionnalités déjà fournies par `git`, La classe [`HfApi`] offre des fonctionnalités additionnelles, telles que la capacité de gérer des dépôts, le téléchargement des fichiers en utilisant le cache pour une réutilisation plus efficace, la recherche dans le Hub pour trouver -des dépôts et des métadonnées, l'accès aux fonctionnalités de communautés telles que, les dicussions, +des dépôts et des métadonnées, l'accès aux fonctionnalités communautaires telles que, les discussions, les pull requests, les commentaires, et la configuration de spaces et de secrets. ## Quelle méthode utiliser et quand ? From 5089a9a0ff979dde69045a316e6fc41467e266b3 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Fri, 9 Feb 2024 10:24:20 +0100 Subject: [PATCH 048/129] Corrected git vs http and index.md --- docs/source/fr/concepts/git_vs_http.md | 137 ++++++++++++------------- docs/source/fr/index.md | 120 +++++++++++----------- 2 files changed, 128 insertions(+), 129 deletions(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index 09c6ef5e31..fc21a09d04 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -1,69 +1,68 @@ - - -# Paradigme Git vs HTTP - -`huggingface_hub` est une librairie qui permet d'intéragir avec le Hub Hugging Face, -qui est une collection de dépots Git (modèles, datasets ou spaces). -Il y a deux manières principales pour accéder au Hub en utilisant `huggingface_hub`. - -La première approche, basée sur Git, appelée approche "git-based", est rendue possible par la classe [`Repository`]. -Cette méthode utilise un wrapper autour de la commande `git` avec des fonctionnalités supplémentaires conçues pour intéragir avec le Hub. La deuxième option, appelée approche "HTTP-based" , consiste à faire des requêtes HTTP en utilisant le client [`HfApi`]. Éxaminions -les avantages et les inconvénients de ces deux méthodes. - -## Repository: L'approche hstorique basée sur git - -Au début, `huggingface_hub` était principalement construit autour de la classe [`Repository`]. Elle fournit des -wrappers Python pour les commandes `git` usuelles, telles que `"git add"`, `"git commit"`, `"git push"`, -`"git tag"`, `"git checkout"`, etc. - -Cette librairie permet aussi de définir les données d'identification et de suivre les fichiers volumineux, qui sont souvent utilisés dans les dépôts Git de machine learning. De plus, la librairie vous permet d'exécuter ses -méthodes en arrière-plan, ce qui la rend utile pour upload des données pendant l'entrainement des modèles. - -L'avantage principal de l'utilisation de [`Repository`] est que cette méthode permet de garder une -copie en local de tout le dépot Git sur votre machine. Cela peut aussi devenir un désavantage, -car cette copie locale doit être mise à jour et maintenue constamment. C'est une méthode -analogue au développement de logiciel classique où chaque développeur maintient sa propre copie locale -et push les changement lorsqu'il travaille sur une fonctionnalité. -Toutefois, dans le contexte du machine learning, elle n'est pas toujours pertinente car -les utilisateurs ont parfois juste besoin d'avoir -les poids des modèles pour l'inférence ou de convertir ces poids d'un format à un autre sans avoir à cloner -tout le dépôt. - - - -[`Repository`] est maintenant deprecated et remplacé par les alternatives basées sur l'HTTP. Étant donné son adoption massive par les utilisateurs, -la suppression complète de [`Repository`] ne sera faite que pour la version `v1.0`. - - - -## HfApi: Un client HTTP flexible et pratique - -La classe [`HfApi`] a été développée afin de fournir une alternative aux dépôts git locaux, -qui peuvent être peu pratiques à maintenir, en particulier lors de l'utilisation de gros modèles ou de datasets volumineux. -La classe [`HfApi`] offre les mêmes fonctionnalités que les approches basées sur Git, -telles que le téléchargement et le push de fichier ainsi que la création de branches et de tags, mais sans -avoir besoin d'un fichier local qui doit être constamment synchronisé. - -En plus des fonctionnalités déjà fournies par `git`, La classe [`HfApi`] offre des fonctionnalités -additionnelles, telles que la capacité de gérer des dépôts, le téléchargement des fichiers -en utilisant le cache pour une réutilisation plus efficace, la recherche dans le Hub pour trouver -des dépôts et des métadonnées, l'accès aux fonctionnalités de communautés telles que, les dicussions, -les pull requests, les commentaires, et la configuration de spaces et de secrets. - -## Quelle méthode utiliser et quand ? - -En général, **L'approche basée sur HTTP est la méthode recommandée** pour l'utilisation d'`huggingface_hub`. -[`HfApi`] permet de pull et push des changements, de travailler avec les pull requests, les tags et les branches, d'intéragir avec les discussions -et bien plus encore. Depuis la sortie `0.16`, les méthodes basées sur HTTP peuvent aussi tourner en arrière plan, ce qui était le -dernier gros avantage de la classe [`Repository`] sur [`HfApi`]. - -Toutefois, certaines commandes restent indisponibles en utilisant [`HfApi`]. -Peut être que certaines ne le seront jamais, mais nous essayons toujours de réduire le fossé entre ces deux approches. -Si votre cas d'usage n'est pas couvert, nous serions ravis de vous aider. Pour cela, ouvrez -[une issue sur Github](https://github.com/huggingface/huggingface_hub)! Nous sommes prêt à entendre tout type de retour nous permettant de construire -l'écosystème 🤗 avec les utilisateurs et pour les utilisateurs. - -Cette préférence pour l'approche basé sur [`HfApi`] au détriment de celle basée sur [`Repository`] ne signifie pas que le versioning git disparaitra -du Hub Hugging Face. Il sera toujours possible d'utiliser les commandes `git` en local lorsque c'est pertinent. \ No newline at end of file + + +# Paradigme Git vs HTTP + +`huggingface_hub` est une librairie qui permet d'intéragir avec le Hub Hugging Face, +qui est une collection de dépots Git (modèles, datasets ou spaces). +Il y a deux manières principales pour accéder au Hub en utilisant `huggingface_hub`. + +La première approche, basée sur Git, appelée approche "git-based", est rendue possible par la classe [`Repository`]. +Cette méthode utilise un wrapper autour de la commande `git` avec des fonctionnalités supplémentaires conçues pour intéragir avec le Hub. La deuxième option, appelée approche "HTTP-based" , consiste à faire des requêtes HTTP en utilisant le client [`HfApi`]. Éxaminions +les avantages et les inconvénients de ces deux méthodes. + +## Repository: L'approche hstorique basée sur git + +Au début, `huggingface_hub` était principalement construit autour de la classe [`Repository`]. Elle fournit des +wrappers Python pour les commandes `git` usuelles, telles que `"git add"`, `"git commit"`, `"git push"`, +`"git tag"`, `"git checkout"`, etc. + +Cette librairie permet aussi de définir les données d'identification et de suivre les fichiers volumineux, qui sont souvent utilisés dans les dépôts Git de machine learning. De plus, la librairie vous permet d'exécuter ses +méthodes en arrière-plan, ce qui la rend utile pour upload des données pendant l'entrainement des modèles. + +L'avantage principal de l'utilisation de [`Repository`] est que cette méthode permet de garder une +copie en local de tout le dépot Git sur votre machine. Cela peut aussi devenir un désavantage, +car cette copie locale doit être mise à jour et maintenue constamment. C'est une méthode +analogue au développement de logiciel classique où chaque développeur maintient sa propre copie locale +et push les changement lorsqu'il travaille sur une fonctionnalité. +Toutefois, dans le contexte du machine learning, elle n'est pas toujours pertinente car +les utilisateurs ont parfois juste besoin d'avoir +les poids des modèles pour l'inférence ou de convertir ces poids d'un format à un autre sans avoir à cloner +tout le dépôt. + + + +[`Repository`] est maintenant deprecated et remplacé par les alternatives basées sur l'HTTP. Étant donné son adoption massive par les utilisateurs, +la suppression complète de [`Repository`] ne sera faite que pour la version `v1.0`. + + + +## HfApi: Un client HTTP flexible et pratique + +La classe [`HfApi`] a été développée afin de fournir une alternative aux dépôts git locaux, +qui peuvent être peu pratiques à maintenir, en particulier lors de l'utilisation de gros modèles ou de datasets volumineux. +La classe [`HfApi`] offre les mêmes fonctionnalités que les approches basées sur Git, +telles que le téléchargement et le push de fichier ainsi que la création de branches et de tags, mais sans +avoir besoin d'un fichier local qui doit être constamment synchronisé. + +En plus des fonctionnalités déjà fournies par `git`, La classe [`HfApi`] offre des fonctionnalités +additionnelles, telles que la capacité de gérer des dépôts, le téléchargement des fichiers +dans le cache (permettant une réutilisation), la recherche dans le Hub pour trouver +des dépôts et des métadonnées, l'accès aux fonctionnalités de communautés telles que, les dicussions, +les pull requests et les commentaires. + +## Quelle méthode utiliser et quand ? + +En général, **l'approche HTTP est la méthode recommandée** pour utiliser `huggingface_hub` +[`HfApi`] permet de pull et push des changements, de travailler avec les pull requests, les tags et les branches, d'intéragir avec les discussions +et bien plus encore. Depuis la version `0.16`, les méthodes HTTP-based peuvent aussi être exécutées en arrière-plan, ce qui constituait le +dernier gros avantage de la classe [`Repository`]. + +Toutefois, certaines commandes restent indisponibles en utilisant [`HfApi`]. +Peut être que certaines ne le seront jamais, mais nous essayons toujours de réduire le fossé entre ces deux approches. +Si votre cas d'usage n'est pas couvert, nous serions ravis de vous aider. Pour cela, ouvrez +[une issue sur Github](https://github.com/huggingface/huggingface_hub)! Nous écoutons tous les retours nous permettant de construire +l'écosystème 🤗 avec les utilisateurs et pour les utilisateurs. + +Cette préférence pour l'approche basée sur [`HfApi`] plutôt que [`Repository`] ne signifie pas que les dépôts stopperons d'être versionnés avec git sur le Hugging Face Hub. Il sera toujours possible d'utiliser les commandes `git` en local lorsque nécessaire. \ No newline at end of file diff --git a/docs/source/fr/index.md b/docs/source/fr/index.md index 15ea3b9c8b..353297fb98 100644 --- a/docs/source/fr/index.md +++ b/docs/source/fr/index.md @@ -1,61 +1,61 @@ - - -# La librairie client 🤗 Hub - -La librairie `huggingface_hub` vous permet d'intéragir avec le -[Hub Hugging Face](https://hf.co), une plateforme de machine learning -pour les créateurs et les collaborateurs. Découvrez des modèles pré- -entrainés et des datasets pour vos projets ou jouez avec des centraines -d'applications machine learning hébergées sur le Hub. Vous pouvez aussi -créer et partager vos propres modèles et datasets avec la communauté. -La librairie `huggingface_hub` offre une manière simple de faire toutes -ces choses avec Python. - -Lisez le [guide de démarrage rapide](quick-start) pour vous lancer avec la librairie -`huggingface_hub`. Vous apprendrez à télécharger des fichiers depuis le Hub, -à créer un dépôt et upload des fichiers dans le Hub. Continuez à lire pour -apprendre le management de dépôt sur le Hub 🤗, comment intéragir avec les discussions -ou même comment accéder à l'API d'inférence. - -
-
- - -
Vue d'ensemble
-

Guides pratiques pour vous aider à atteindre un but en particulier. Regardez ces guides pour apprendre à utiliser huggingface_hub pour résoudre des problèmes concrets.

- - - -
Références
-

Description exhaustive et technique des classes et méthodes huggingface_hub.

- - - -
Guides conceptuels
-

Explications haut niveau permettant d'avoir une meilleure compréhension de la philosophie huggingface_hub.

- - -
-
- - - -## Contributions - -Toutes les contributions à `huggingface_hub` sont les bienvenues, nous les valorisons toutes -à la même hauteur. 🤗 Hormis l'ajout ou la correction de problèmes dans le code, vous -pouvez aussi aider à améliorer la documentation en vérifiant qu'elle est exacte et -à jour, répondre à des questions sur des issues, et demander de nouvelles fonctionnalités -qui amélioreront la librairie. Regardez le [guide de contributions](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) -pour en savoir plus sur comment lancer une nouvelle issue ou une demande de nouvelle -fonctionnalité, comment faire un pull request et comment tester vos contributions pour -vérifier que tout fonctionne comme prévu. - -Les contributeurs doivent aussi respecter notre [code de conduite](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) + + +# Un client pour le Hugging Face Hub + +La librairie `huggingface_hub` vous permet d'interagir avec le +[Hugging Face Hub](https://hf.co), une plateforme de machine learning +pour créer et collaborer. Découvrez des modèles pré- +entrainés et des datasets pour vos projets ou jouez avec des centraines +d'applications hébergées sur le Hub. Vous pouvez aussi +créer et partager vos propres modèles et datasets avec la communauté. +La librairie `huggingface_hub` offre une manière simple de faire toutes +ces choses avec Python. + +Lisez le [guide de démarrage rapide](quick-start) pour vous lancer avec la librairie +`huggingface_hub`. Vous apprendrez à télécharger des fichiers depuis le Hub, +à créer un dépôt et upload des fichiers dans le Hub. Continuez à lire pour +apprendre le management de dépôt sur le Hub 🤗, comment intéragir avec les discussions +ou même comment accéder à l'API d'inférence. + +
+
+ + +
Vue d'ensemble
+

Guides pratiques pour vous aider à atteindre un but en particulier. Regardez ces guides pour apprendre à utiliser huggingface_hub pour résoudre des problèmes concrets.

+ + + +
Références
+

Description exhaustive et technique des classes et méthodes huggingface_hub.

+ + + +
Guides conceptuels
+

Explications haut niveau permettant d'avoir une meilleure compréhension de la philosophie huggingface_hub.

+ + +
+
+ + + +## Contributions + +Toutes les contributions à `huggingface_hub` sont les bienvenues, nous les valorisons toutes +à la même hauteur. 🤗 Hormis l'ajout ou la correction de problèmes dans le code, vous +pouvez aussi aider à améliorer la documentation en vérifiant qu'elle est exacte et +à jour, répondre à des questions sur des issues, et demander de nouvelles fonctionnalités +qui amélioreront la librairie. Regardez le [guide de contributions](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) +pour en savoir plus sur comment lancer une nouvelle issue ou une demande de nouvelle +fonctionnalité, comment faire un pull request et comment tester vos contributions pour +vérifier que tout fonctionne comme prévu. + +Les contributeurs doivent aussi respecter notre [code de conduite](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) pour créer un espace collaboratif inclusif et bienveillant pour tout le monde. \ No newline at end of file From 82c8a79ebf399a1dca0ac9a0297fb6fbb4956c6b Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Fri, 9 Feb 2024 10:34:04 +0100 Subject: [PATCH 049/129] Finished correcting index.md --- docs/source/fr/index.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/source/fr/index.md b/docs/source/fr/index.md index 353297fb98..7c9da35536 100644 --- a/docs/source/fr/index.md +++ b/docs/source/fr/index.md @@ -13,10 +13,10 @@ créer et partager vos propres modèles et datasets avec la communauté. La librairie `huggingface_hub` offre une manière simple de faire toutes ces choses avec Python. -Lisez le [guide de démarrage rapide](quick-start) pour vous lancer avec la librairie +Lisez le [guide d'introduction rapide](quick-start) pour vous lancer avec la librairie `huggingface_hub`. Vous apprendrez à télécharger des fichiers depuis le Hub, -à créer un dépôt et upload des fichiers dans le Hub. Continuez à lire pour -apprendre le management de dépôt sur le Hub 🤗, comment intéragir avec les discussions +à créer un dépôt et upload des fichiers vers le Hub. Continuez à lire pour +apprendre le management de dépôt sur le Hub, comment interagir avec les discussions ou même comment accéder à l'API d'inférence.
@@ -24,17 +24,17 @@ ou même comment accéder à l'API d'inférence.
Vue d'ensemble
-

Guides pratiques pour vous aider à atteindre un but en particulier. Regardez ces guides pour apprendre à utiliser huggingface_hub pour résoudre des problèmes concrets.

+

Guides pratiques pour vous aider à atteindre un but en particulier. Lisez ces guides pour apprendre comment utiliser huggingface_hub pour résoudre des problèmes concrets.
Références
-

Description exhaustive et technique des classes et méthodes huggingface_hub.

+

Description exhaustive des classes et méthodes présentes dans huggingface_hub.
Guides conceptuels
-

Explications haut niveau permettant d'avoir une meilleure compréhension de la philosophie huggingface_hub.

+

Explications permettant d'avoir une meilleure compréhension de la philosophie derrière huggingface_hub.
@@ -48,14 +48,13 @@ ou même comment accéder à l'API d'inférence. ## Contributions -Toutes les contributions à `huggingface_hub` sont les bienvenues, nous les valorisons toutes -à la même hauteur. 🤗 Hormis l'ajout ou la correction de problèmes dans le code, vous -pouvez aussi aider à améliorer la documentation en vérifiant qu'elle est exacte et +Toutes les contributions au projet `huggingface_hub` sont les bienvenues et valorisées à la même hauteur. +🤗 En plus de l'ajout ou de la correction de bug dans le code, vous +pouvez également aider à améliorer la documentation en vérifiant qu'elle est exacte et à jour, répondre à des questions sur des issues, et demander de nouvelles fonctionnalités -qui amélioreront la librairie. Regardez le [guide de contributions](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) +qui amélioreront la librairie. Regardez le [guide de contribution](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) pour en savoir plus sur comment lancer une nouvelle issue ou une demande de nouvelle fonctionnalité, comment faire un pull request et comment tester vos contributions pour vérifier que tout fonctionne comme prévu. -Les contributeurs doivent aussi respecter notre [code de conduite](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) -pour créer un espace collaboratif inclusif et bienveillant pour tout le monde. \ No newline at end of file +Les contributeurs doivent aussi respecter notre [code de conduite](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) (en anglais) pour créer un espace collaboratif inclusif et bienveillant envers tout le monde. \ No newline at end of file From 499cd8c675a09ffa359a7e45cdde7f42111f77f7 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:34:27 +0100 Subject: [PATCH 050/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 6bfcfba9f2..9f0aab04e9 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -4,7 +4,7 @@ rendered properly in your Markdown viewer. # Installation -Avant de commmencer l'installation, vous allez avoir besoin de préparer votre environnement +Avant de commmencer, vous allez avoir besoin de préparer votre environnement en installant les packages appropriés. `huggingface_hub` est testée sur **Python 3.8+**. From 565547695f9c61be77fdeb56966037fd5461e890 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:34:48 +0100 Subject: [PATCH 051/129] Update docs/source/fr/_toctree.yml Co-authored-by: Lucain --- docs/source/fr/_toctree.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index 2cefbdddc6..a7845481c0 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -3,7 +3,7 @@ - local: index title: Home - local: quick-start - title: Quickstart + title: Introduction rapide - local: installation title: Installation - title: "Guides" From 3e50bad32d5a3e9a796b1720438d7e7a23dd8c13 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:37:39 +0100 Subject: [PATCH 052/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 9f0aab04e9..8cbf657244 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -12,7 +12,7 @@ en installant les packages appropriés. ## Installation avec pip Il est fortement recommandé d'installer `huggingface_hub` dans un [environnement virtuel](https://docs.python.org/3/library/venv.html). -Si vous êtes familier avec les environnements virtuels Python, regardez plutôt ce [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Un environnement virtuel sera utile lorsque vous devrez gérer des projets différents +Si vous n'êtes pas familier avec les environnements virtuels Python, suivez ce [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Un environnement virtuel sera utile lorsque vous devrez gérer des plusieurs projets en parallèle et éviter les problèmes de compatibilité entre les différetnes dépendances. Commencez par créer un environnement virtuel dans le chemin de votre projet: From afbf7db46de6681cd54e9132fa8de948618c31fa Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:38:07 +0100 Subject: [PATCH 053/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 8cbf657244..0063ae4072 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -13,7 +13,7 @@ en installant les packages appropriés. Il est fortement recommandé d'installer `huggingface_hub` dans un [environnement virtuel](https://docs.python.org/3/library/venv.html). Si vous n'êtes pas familier avec les environnements virtuels Python, suivez ce [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Un environnement virtuel sera utile lorsque vous devrez gérer des plusieurs projets en parallèle -et éviter les problèmes de compatibilité entre les différetnes dépendances. +afin d'éviter les problèmes de compatibilité entre les différentes dépendances. Commencez par créer un environnement virtuel dans le chemin de votre projet: From 1625548665a085e555f799b2a4dcf62ee3c55efb Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:38:41 +0100 Subject: [PATCH 054/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 0063ae4072..29c5bc2f24 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -15,7 +15,7 @@ Il est fortement recommandé d'installer `huggingface_hub` dans un [environnemen Si vous n'êtes pas familier avec les environnements virtuels Python, suivez ce [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Un environnement virtuel sera utile lorsque vous devrez gérer des plusieurs projets en parallèle afin d'éviter les problèmes de compatibilité entre les différentes dépendances. -Commencez par créer un environnement virtuel dans le chemin de votre projet: +Commencez par créer un environnement virtuel à l'emplacement de votre projet: ```bash python -m venv .env From dd882606d49e9fe5add1ab779152efa6e0ca3a3b Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:39:11 +0100 Subject: [PATCH 055/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 29c5bc2f24..9ff885515b 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -39,7 +39,7 @@ Maintenant, vous êtes prêts à installer `hugginface_hub` [depuis PyPi](https: pip install --upgrade huggingface_hub ``` -Une fois l'installation finie, [vérifiez](#check-installation) que tout marche correctement. +Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement. ### Installation des dépendances optionnelles From 175918837186811b245fe2118d51a710f5a084d6 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:39:34 +0100 Subject: [PATCH 056/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 9ff885515b..1aec2e9e45 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -63,7 +63,7 @@ Voici une liste des dépendances optionnelles dans `huggingface_hub`: -### Installation depuis la source +### Installation depuis le code source Dans certains cas, il est intéressant d'installer `huggingface_hub` directement depuis le code source. Ceci vous permet d'utiliser la version `main`, contenant les dernières mises à jour, plutôt que From 28daada41581cb027fe6b34d538d4f089cbe7fea Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:40:10 +0100 Subject: [PATCH 057/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 1aec2e9e45..1f140155c8 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -68,8 +68,8 @@ Voici une liste des dépendances optionnelles dans `huggingface_hub`: Dans certains cas, il est intéressant d'installer `huggingface_hub` directement depuis le code source. Ceci vous permet d'utiliser la version `main`, contenant les dernières mises à jour, plutôt que d'utiliser la dernière version stable. La version `main` est utile pour rester à jour sur les -derniers développements, par exemple si un bug est réglé depuis la dernière sortie officielle -mais que la nouvelle sortie n'a pas encore été faite. +derniers développements, par exemple si un bug est corrigé depuis la dernière version officielle +mais que la nouvelle version n'a pas encore été faite. Toutefois, cela signifie que la version `main` pourrait ne pas être stable. Nous travaillons afin de rendre la version `main` optionnelle, et la pluspart des problèmes sont résolus From 06dc88f553cbe58034cdf22b59b1457591525a8e Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:40:41 +0100 Subject: [PATCH 058/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 1f140155c8..380f3ccd57 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -71,10 +71,10 @@ d'utiliser la dernière version stable. La version `main` est utile pour rester derniers développements, par exemple si un bug est corrigé depuis la dernière version officielle mais que la nouvelle version n'a pas encore été faite. -Toutefois, cela signifie que la version `main` pourrait ne pas être stable. Nous travaillons -afin de rendre la version `main` optionnelle, et la pluspart des problèmes sont résolus -en quelques heure ou en une journée. Si vous avez un problème, ouvrez une issue afin que -nous puissions la régler encore plus vite ! +Toutefois, cela signifie que la version `main` peut ne pas être stable. Nous travaillons +afin de rendre la version `main` aussi stable que possible, et la plupart des problèmes sont résolus +en quelques heures ou jours. Si vous avez un problème, ouvrez une issue afin que +nous puissions la régler au plus vite ! ```bash pip install git+https://github.com/huggingface/huggingface_hub From 8cf7df030b478fc27bd65a79bcf3da101914a07b Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:41:03 +0100 Subject: [PATCH 059/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 380f3ccd57..75002a6630 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -80,9 +80,7 @@ nous puissions la régler au plus vite ! pip install git+https://github.com/huggingface/huggingface_hub ``` -Lorsque vous faites l'installation depuis le code source, vous pouvez aussi préciser une -branche spécifique. C'est utile si vous voulez tester une nouvelle fonctionnalité ou un -nouveau bug-fix qui n'a pas encore été merge: +Lorsque vous installez depuis le code source, vous pouvez préciser la branche depuis laquelle installer. Cela permet de tester une nouvelle fonctionnalité ou un bug-fix qui n'a pas encore été merge: ```bash pip install git+https://github.com/huggingface/huggingface_hub@ma-branche From 3cb34a5071f26bac3bfab7d0286762b7945d400f Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:41:42 +0100 Subject: [PATCH 060/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 75002a6630..5deb6c3ddc 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -86,7 +86,7 @@ Lorsque vous installez depuis le code source, vous pouvez préciser la branche d pip install git+https://github.com/huggingface/huggingface_hub@ma-branche ``` -Une fois finie, [vérifiez l'installation](#check-installation). +Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement. ### Installation éditable From 925b655d7f3091de11f8f2d35f129b640fc4c896 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:42:13 +0100 Subject: [PATCH 061/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 5deb6c3ddc..60a3f4c1a0 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -90,8 +90,8 @@ Une fois l'installation terminée, rendez-vous à la section [vérification](#ve ### Installation éditable -L'installation depuis le code source vous permet de mettre en place une [installation éditable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). Cette installation est plus avancée et sert surtout si vous comptez contribuer à `huggingface_hub` -et que vous avez besoin de tester des changements dans le code. Vous devez cloner une copie locale de `huggingface_hub` sur votre machine. +L'installation depuis le code source vous permet de mettre en place une [installation éditable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). Cette installation sert surtout si vous comptez contribuer à `huggingface_hub` +et que vous avez besoin de tester rapidement des changements dans le code. Pour cela, vous devez cloner le projet `huggingface_hub` sur votre machine. ```bash #D'abord, clonez le dépôt en local From 07d3824ec3f055aa0af84c10f354f64bde3270cc Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:42:46 +0100 Subject: [PATCH 062/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index 60a3f4c1a0..e7344b8566 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -94,7 +94,7 @@ L'installation depuis le code source vous permet de mettre en place une [install et que vous avez besoin de tester rapidement des changements dans le code. Pour cela, vous devez cloner le projet `huggingface_hub` sur votre machine. ```bash -#D'abord, clonez le dépôt en local +# Commencez par cloner le dépôt en local git clone https://github.com/huggingface/huggingface_hub.git # Ensuite, installez avec le flag -e From ad44254a0405365a54dbb7b9c63e43c3591db6cf Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:43:19 +0100 Subject: [PATCH 063/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index e7344b8566..bf15bcbe4a 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -117,7 +117,7 @@ Si vous avez plutôt l'habitude d'utiliser conda, vous pouvez installer `hugging conda install -c conda-forge huggingface_hub ``` -Une fois finie, [vérifiez l'installation](#check-installation). +Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement. ## Vérification de l'installation From e366b2c7aeaaf205ca75aa38e9e179c9f6b16bb4 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:43:45 +0100 Subject: [PATCH 064/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index bf15bcbe4a..bdb687506e 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -97,7 +97,7 @@ et que vous avez besoin de tester rapidement des changements dans le code. Pour # Commencez par cloner le dépôt en local git clone https://github.com/huggingface/huggingface_hub.git -# Ensuite, installez avec le flag -e +# Ensuite, installez-le avec le flag -e cd huggingface_hub pip install -e . ``` From 6d37e1c1330c891f134fc36e30714c981119a160 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 9 Feb 2024 10:44:11 +0100 Subject: [PATCH 065/129] Update docs/source/fr/installation.md Co-authored-by: Lucain --- docs/source/fr/installation.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/fr/installation.md b/docs/source/fr/installation.md index bdb687506e..49e07429a5 100644 --- a/docs/source/fr/installation.md +++ b/docs/source/fr/installation.md @@ -102,7 +102,6 @@ cd huggingface_hub pip install -e . ``` -Ces commandes lieront le dossier dans lequel vous avez cloné le dépôt et vos chemins de librairies Python. Python regardera maintenant à l'intérieur du dossier dans lequel vous avez cloné le dépôt en plus des chemins de librairie classiques. Par exemple, si vos packages Python sont installés dans `./.venv/lib/python3.11/site-packages/`, Python regardera aussi dans le dossier que vous avez From e5b6dedce5bd7bb3927c6377d45d30307a92d7b0 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Fri, 9 Feb 2024 10:45:06 +0100 Subject: [PATCH 066/129] Finished correcting index.md --- docs/source/fr/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/source/fr/index.md b/docs/source/fr/index.md index 7c9da35536..0443d38744 100644 --- a/docs/source/fr/index.md +++ b/docs/source/fr/index.md @@ -53,8 +53,7 @@ Toutes les contributions au projet `huggingface_hub` sont les bienvenues et valo pouvez également aider à améliorer la documentation en vérifiant qu'elle est exacte et à jour, répondre à des questions sur des issues, et demander de nouvelles fonctionnalités qui amélioreront la librairie. Regardez le [guide de contribution](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) -pour en savoir plus sur comment lancer une nouvelle issue ou une demande de nouvelle -fonctionnalité, comment faire un pull request et comment tester vos contributions pour -vérifier que tout fonctionne comme prévu. +pour en savoir plus sur comment commencer à travailler sur une issue, comment faire une pull request et comment tester vos contributions pour +vérifier que vos modifications fonctionnent comme prévu. Les contributeurs doivent aussi respecter notre [code de conduite](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) (en anglais) pour créer un espace collaboratif inclusif et bienveillant envers tout le monde. \ No newline at end of file From 3c754778cbfacf008142fa9aceefa34736fdd65c Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Tue, 13 Feb 2024 10:29:48 +0100 Subject: [PATCH 067/129] Corrected inference endpoint, a lot of mistakes might have to look at it again --- docs/source/fr/guides/inference_endpoints.md | 62 ++++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/source/fr/guides/inference_endpoints.md b/docs/source/fr/guides/inference_endpoints.md index ff7b706eb9..9783c30282 100644 --- a/docs/source/fr/guides/inference_endpoints.md +++ b/docs/source/fr/guides/inference_endpoints.md @@ -1,14 +1,14 @@ # Inference Endpoints -Inference Endpoints fournit une solution viable pour la production et sécurisée pour déployer facilement n'importe quel modèle `transformers`, `sentence-transformers`, et `diffusers` sur une infrastructure dédiée et capable d'autoscaling gérée par Hugging Face. Un endpoint d'inférence est construit à partir d'un modèle du [Hub](https://huggingface.co/models). +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 postule 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`. +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 endpoint d'inférence +## Créez un inference endpoint -La première étape pour créer un endpoint d'inférence est d'utiliser [`create_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 @@ -27,7 +27,7 @@ La première étape pour créer un endpoint d'inférence est d'utiliser [`create ... ) ``` -Dans cet exemple, nous avons créé un endpoint d'inférence 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. Nous aurons aussi besoin de fournir des informations supplémentaires pour préciser le hardware nécessaire, tel 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 endpoint d'inférence 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. +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`]: @@ -36,18 +36,18 @@ La valeur renvoyée par [`create_inference_endpoint`] est un objet [`InferenceEn InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) ``` -C'est une dataclass qui a des informations sur l'endpoitn. 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`. +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 endpoint d'inférence est créé, vous pouvez le retrouver sur votre [dashboard personnel](https://ui.endpoints.huggingface.co/). +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'endpoint d'inférence est construit à partir d'une image docker fournie par Hugging Face. Cependant, i lest 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: +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 endpoint d'inférence utilisant le modèle Zephyr-7b-beta sur une TGI +# 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", @@ -77,12 +77,12 @@ La valeur à passer dans `custom_image` est un dictionnaire contenant un url ver ### 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. +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 -# Obtiens un endpoint +# Obtient un endpoint >>> get_inference_endpoint("my-endpoint-name") InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) @@ -95,24 +95,24 @@ InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2 [InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...] ``` -## Vérifier le statu de déploiement +## 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'endpoint d'inférence est déployé et accessible, le statut est `"running"` et l'attribut `url` est défini: +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'endpoint d'inférence 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 sur place: +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'endpoint d'inférence 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'endpoint d'inférence soit déployé. Les valeurs par défaut sont respectivement `None` (pas de timeout) et `5` secondes. +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 @@ -124,21 +124,21 @@ InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2 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 +# 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'endpoint d'inférence prend trop de temps à charger, une erreur [`InferenceEndpointTimeouError`] est levée. +Si `timeout` est définit et que l'inference endpoint prend trop de temps à charger, une erreur [`InferenceEndpointTimeouError`] est levée. -## Lancez des inférences +## Lancer des inférences -Une fois que votre endpoint d'inférence est fonctionnel, vous pouvez enfin faire de l'inférence avec! +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 -# Lancez un tâche de génération de texte: +# 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' @@ -146,7 +146,7 @@ Une fois que votre endpoint d'inférence est fonctionnel, vous pouvez enfin fair >>> await endpoint.async_client.text_generation("I am") ``` -Si l'endpoint d'inférence n'est pas opérationnel, une exception [`InferenceEndpointError`] est levée: +Si l'inference endpoint n'est pas opérationnel, une exception [`InferenceEndpointError`] est levée: ```py >>> endpoint.client @@ -158,21 +158,21 @@ Pour plus de détails sur l'utilisation d'[`InferenceClient`], consultez le [gui ## Gérer les cycles de vie -Maintenant que nous avons vu comment créer un endpoint d'inférence et faire de l'inférence avec, regardons comment gérer son cycle 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 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`], and [`delete_inference_endpoint`]. +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 endpoint d'inférence 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`]. +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 endpoint d'inférence 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 endpoint d'inférence peut aussi être configuré pour scale à zero automatiquement après une certaine durée d'inactivité. +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é. @@ -193,7 +193,7 @@ InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2 ### Mettre à jour le modèle ou le hardware de l'endpoint -Dans certains cas, vous aurez besoin de mettre à jour votre endpoint d'inférence 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 faire ça en utilisant [`~InferenceEndpoint.update`]: +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é @@ -211,18 +211,18 @@ InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2 ### Supprimer un endpoint -Si vous n'utilisez plus un endpoint d'inférence, vous pouvez simplement appeler la méthode [`~InferenceEndpoint.delete()`]. +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 endpoint d'inférence supprimé. +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 des 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: +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 @@ -243,7 +243,7 @@ Un cas d'usage typique d'Hugging Face pour les endpoints d'inférence est des g >>> endpoint.pause() ``` -Ou si votre endpoint d'inférence existe et est en pause: +Ou si votre inference endpoint existe et est en pause: ```py >>> import asyncio From 5637113f476bbe964b4a07af7a9c46564c2b104a Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:11:18 +0100 Subject: [PATCH 068/129] Update docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index 55f3fddd09..f1c71a21c2 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -2,7 +2,7 @@ rendered properly in your Markdown viewer. --> -# Paradigme Git vs HTTP +# Git ou HTTP? `huggingface_hub` est une librairie qui permet d'intéragir avec le Hub Hugging Face, qui est une collection de dépots Git (modèles, datasets ou spaces). From a7356166d238a6a14b0ceeb4a43646bb64374adb Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:12:43 +0100 Subject: [PATCH 069/129] Update docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index f1c71a21c2..a2e520d800 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -14,7 +14,7 @@ les avantages et les inconvénients de ces deux méthodes. ## Repository: L'approche hstorique basée sur git -Au début, `huggingface_hub` était principalement construit autour de la classe [`Repository`]. Elle fournit des +Initialement, `huggingface_hub` était principalement construite autour de la classe [`Repository`]. Elle fournit des wrappers Python pour les commandes `git` usuelles, telles que `"git add"`, `"git commit"`, `"git push"`, `"git tag"`, `"git checkout"`, etc. From 8a578f2cf43a1378e605208077760f0d66a4408b Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:13:05 +0100 Subject: [PATCH 070/129] Update docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index a2e520d800..2b856506c0 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -21,7 +21,7 @@ wrappers Python pour les commandes `git` usuelles, telles que `"git add"`, `"git Cette librairie permet aussi de définir les données d'identification et de suivre les fichiers volumineux, qui sont souvent utilisés dans les dépôts Git de machine learning. De plus, la librairie vous permet d'exécuter ses méthodes en arrière-plan, ce qui la rend utile pour upload des données pendant l'entrainement des modèles. -L'avantage principal de l'utilisation de [`Repository`] est que cette méthode permet de garder une +L'avantage principal de [`Repository`] est que cette méthode permet de garder une copie en local de tout le dépot Git sur votre machine. Cela peut aussi devenir un désavantage, car cette copie locale doit être mise à jour et maintenue constamment. C'est une méthode analogue au développement de logiciel classique où chaque développeur maintient sa propre copie locale From 8782aed2de11e0d6391a0146b73d243bde7ef923 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:13:26 +0100 Subject: [PATCH 071/129] Update docs/source/fr/_toctree.yml Co-authored-by: Lucain --- docs/source/fr/_toctree.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index a7845481c0..d676eb361a 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -40,7 +40,7 @@ title: Intégrer une librairie - local: guides/webhooks_server title: Webhooks -- title: "Guides conceptuels" +- title: "Concepts" sections: - local: concepts/git_vs_http title: Le paradigme Git vs HTTP From d38bf37ce353891e53604be4161dbea9ab69ab6d Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:13:38 +0100 Subject: [PATCH 072/129] Update docs/source/fr/_toctree.yml Co-authored-by: Lucain --- docs/source/fr/_toctree.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index d676eb361a..a34226774d 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -43,7 +43,7 @@ - title: "Concepts" sections: - local: concepts/git_vs_http - title: Le paradigme Git vs HTTP + title: Git ou HTTP? - title: "Référence" sections: - local: package_reference/overview From 64e18b7d7fafe64bbda88fc6be9aaa1c6ec5f728 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:15:56 +0100 Subject: [PATCH 073/129] Update docs/source/fr/_toctree.yml Co-authored-by: Lucain --- docs/source/fr/_toctree.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index a34226774d..e47658bb06 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -55,7 +55,7 @@ - local: package_reference/repository title: Gérer les dépôts locaux et en ligne - local: package_reference/hf_api - title: API Hugging Face Hub + title: Hugging Face Hub API - local: package_reference/file_download title: Téléchargement des fichiers - local: package_reference/mixins From 8423a9ef5c8d48440e4b64f8714168bc81754919 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:16:09 +0100 Subject: [PATCH 074/129] Update docs/source/fr/_toctree.yml Co-authored-by: Lucain --- docs/source/fr/_toctree.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index e47658bb06..1fc41a555d 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -61,7 +61,7 @@ - local: package_reference/mixins title: Mixins & méthodes de sérialisations - local: package_reference/inference_client - title: Client d'inférence + title: Inference Client - local: package_reference/inference_endpoints title: Inference Endpoints - local: package_reference/hf_file_system From c6181504673e50118be384f0c0e58b20633b8813 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:16:28 +0100 Subject: [PATCH 075/129] Update docs/source/fr/_toctree.yml Co-authored-by: Lucain --- docs/source/fr/_toctree.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index 1fc41a555d..abe488a2c2 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -71,7 +71,7 @@ - local: package_reference/community title: Discussions et Pull Requests - local: package_reference/cache - title: Référence au système de cache + title: Système de cache - local: package_reference/cards title: Repo Cards et données des Repo Card - local: package_reference/space_runtime From 8666812728b3021f8c3e8f7641a7c5e82ec63dd3 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:16:41 +0100 Subject: [PATCH 076/129] Update docs/source/fr/_toctree.yml Co-authored-by: Lucain --- docs/source/fr/_toctree.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index abe488a2c2..cbaac84120 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -73,7 +73,7 @@ - local: package_reference/cache title: Système de cache - local: package_reference/cards - title: Repo Cards et données des Repo Card + title: Repo Cards et metadata - local: package_reference/space_runtime title: Space runtime - local: package_reference/collections From 7cdefa2e7601fbc3995044d9c5bf45bc43c64d5b Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:16:57 +0100 Subject: [PATCH 077/129] Update docs/source/fr/_toctree.yml Co-authored-by: Lucain --- docs/source/fr/_toctree.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index cbaac84120..c80a02b0ef 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -81,4 +81,4 @@ - local: package_reference/tensorboard title: Logger Tensorboard - local: package_reference/webhooks_server - title: Serveur Webhook \ No newline at end of file + title: Webhooks \ No newline at end of file From 2b19af224b4f6c990b9a222db2ecdb1527ddbb93 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:17:40 +0100 Subject: [PATCH 078/129] Update docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index 2b856506c0..cf62624d2d 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -22,7 +22,7 @@ Cette librairie permet aussi de définir les données d'identification et de sui méthodes en arrière-plan, ce qui la rend utile pour upload des données pendant l'entrainement des modèles. L'avantage principal de [`Repository`] est que cette méthode permet de garder une -copie en local de tout le dépot Git sur votre machine. Cela peut aussi devenir un désavantage, +copie en local du dépot Git sur votre machine. Cela peut aussi devenir un désavantage, car cette copie locale doit être mise à jour et maintenue constamment. C'est une méthode analogue au développement de logiciel classique où chaque développeur maintient sa propre copie locale et push les changement lorsqu'il travaille sur une fonctionnalité. From 8924212cdb30def2d3769de780991d98d518537a Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:17:55 +0100 Subject: [PATCH 079/129] Update docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index cf62624d2d..c7bc12dc8b 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -25,7 +25,7 @@ L'avantage principal de [`Repository`] est que cette méthode permet de garder u copie en local du dépot Git sur votre machine. Cela peut aussi devenir un désavantage, car cette copie locale doit être mise à jour et maintenue constamment. C'est une méthode analogue au développement de logiciel classique où chaque développeur maintient sa propre copie locale -et push les changement lorsqu'il travaille sur une fonctionnalité. +et push les changements lorsqu'il travaille sur une nouvelle fonctionnalité. Toutefois, dans le contexte du machine learning, elle n'est pas toujours pertinente car les utilisateurs ont parfois juste besoin d'avoir les poids des modèles pour l'inférence ou de convertir ces poids d'un format à un autre sans avoir à cloner From 24753442b0dc51fbeba155b02a141b7d7ebfc60c Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:18:12 +0100 Subject: [PATCH 080/129] Update docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index c7bc12dc8b..07de8b3338 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -33,7 +33,7 @@ tout le dépôt. -[`Repository`] est maintenant deprecated et remplacé par les alternatives basées sur l'HTTP. Étant donné son adoption massive par les utilisateurs, +[`Repository`] est maintenant obsolète et remplacée par les alternatives basées sur des requêtes HTTP. Étant donné son adoption massive par les utilisateurs, la suppression complète de [`Repository`] ne sera faite que pour la version `v1.0`. From 8ce66cf4a5227c835e0dfb90920dc1818cf274b3 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:18:32 +0100 Subject: [PATCH 081/129] Update docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index 07de8b3338..ab8b27be4a 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -38,7 +38,7 @@ la suppression complète de [`Repository`] ne sera faite que pour la version `v1 -## HfApi: Un client HTTP flexible et pratique +## HfApi: Un client HTTP plus flexible La classe [`HfApi`] a été développée afin de fournir une alternative aux dépôts git locaux, qui peuvent être peu pratiques à maintenir, en particulier lors de l'utilisation de gros modèles ou de datasets volumineux. From bdd7733b5490489c8dc00976c28eb37bcc2240d0 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:18:49 +0100 Subject: [PATCH 082/129] Update docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index ab8b27be4a..0768c708e0 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -43,7 +43,7 @@ la suppression complète de [`Repository`] ne sera faite que pour la version `v1 La classe [`HfApi`] a été développée afin de fournir une alternative aux dépôts git locaux, qui peuvent être peu pratiques à maintenir, en particulier lors de l'utilisation de gros modèles ou de datasets volumineux. La classe [`HfApi`] offre les mêmes fonctionnalités que les approches basées sur Git, -telles que le téléchargement et le push de fichier ainsi que la création de branches et de tags, mais sans +telles que le téléchargement et le push de fichiers ainsi que la création de branches et de tags, mais sans avoir besoin d'un fichier local qui doit être constamment synchronisé. En plus des fonctionnalités déjà fournies par `git`, La classe [`HfApi`] offre des fonctionnalités From 5ea15ead6eaf624bbc56c173d082c5f6d138e6f2 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:19:06 +0100 Subject: [PATCH 083/129] Update docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index 0768c708e0..7b97f64ef2 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -47,7 +47,7 @@ telles que le téléchargement et le push de fichiers ainsi que la création de avoir besoin d'un fichier local qui doit être constamment synchronisé. En plus des fonctionnalités déjà fournies par `git`, La classe [`HfApi`] offre des fonctionnalités -additionnelles, telles que la capacité de gérer des dépôts, le téléchargement des fichiers +additionnelles, telles que la capacité à gérer des dépôts, le téléchargement des fichiers dans le cache (permettant une réutilisation), la recherche dans le Hub pour trouver des dépôts et des métadonnées, l'accès aux fonctionnalités de communautés telles que, les dicussions, les pull requests et les commentaires. From fc853623e57ede953cf86e7e345cc8859065d9b9 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 16 Feb 2024 19:19:26 +0100 Subject: [PATCH 084/129] Update docs/source/fr/concepts/git_vs_http.md Co-authored-by: Lucain --- docs/source/fr/concepts/git_vs_http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/concepts/git_vs_http.md b/docs/source/fr/concepts/git_vs_http.md index 7b97f64ef2..e5dc04a6fe 100644 --- a/docs/source/fr/concepts/git_vs_http.md +++ b/docs/source/fr/concepts/git_vs_http.md @@ -49,7 +49,7 @@ avoir besoin d'un fichier local qui doit être constamment synchronisé. En plus des fonctionnalités déjà fournies par `git`, La classe [`HfApi`] offre des fonctionnalités additionnelles, telles que la capacité à gérer des dépôts, le téléchargement des fichiers dans le cache (permettant une réutilisation), la recherche dans le Hub pour trouver -des dépôts et des métadonnées, l'accès aux fonctionnalités de communautés telles que, les dicussions, +des dépôts et des métadonnées, l'accès aux fonctionnalités communautaires telles que, les discussions, les pull requests et les commentaires. ## Quelle méthode utiliser et quand ? From 34c49a7cbe74faf605621d6e96ee016a62beaa65 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 8 Jun 2024 00:21:35 +0200 Subject: [PATCH 085/129] Deleted files --- docs/source/fr/guides/cli.md | 478 --------------- docs/source/fr/guides/collections.md | 230 ------- docs/source/fr/guides/community.md | 153 ----- docs/source/fr/guides/download.md | 208 ------- docs/source/fr/guides/hf_file_system.md | 110 ---- docs/source/fr/guides/inference_endpoints.md | 261 -------- docs/source/fr/guides/integrations.md | 290 --------- docs/source/fr/guides/manage-cache.md | 569 ------------------ docs/source/fr/guides/manage-spaces.md | 379 ------------ docs/source/fr/guides/model-cards.md | 373 ------------ docs/source/fr/guides/overview.md | 131 ---- docs/source/fr/guides/repository.md | 248 -------- docs/source/fr/guides/search.md | 69 --- docs/source/fr/guides/upload.md | 596 ------------------- docs/source/fr/guides/webhooks_server.md | 205 ------- 15 files changed, 4300 deletions(-) delete mode 100644 docs/source/fr/guides/cli.md delete mode 100644 docs/source/fr/guides/collections.md delete mode 100644 docs/source/fr/guides/community.md delete mode 100644 docs/source/fr/guides/download.md delete mode 100644 docs/source/fr/guides/hf_file_system.md delete mode 100644 docs/source/fr/guides/inference_endpoints.md delete mode 100644 docs/source/fr/guides/integrations.md delete mode 100644 docs/source/fr/guides/manage-cache.md delete mode 100644 docs/source/fr/guides/manage-spaces.md delete mode 100644 docs/source/fr/guides/model-cards.md delete mode 100644 docs/source/fr/guides/overview.md delete mode 100644 docs/source/fr/guides/repository.md delete mode 100644 docs/source/fr/guides/search.md delete mode 100644 docs/source/fr/guides/upload.md delete mode 100644 docs/source/fr/guides/webhooks_server.md 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/download.md b/docs/source/fr/guides/download.md deleted file mode 100644 index 9dae248d92..0000000000 --- a/docs/source/fr/guides/download.md +++ /dev/null @@ -1,208 +0,0 @@ - - -# Télécharger des fichiers du Hub - -La librairie `huggingface_hub` fournit des fonctions pour télécharger des fichiers depuis -les dépôts stockés sur le Hub. Vous pouvez utiliser ces fonctions directement ou les intégrer -dans votre propre librairie, pour rendre l'intéraction entre vos utilisateurs et le Hub -plus simple. Ce guide vous montrera comment: - -* Télécharger et mettre en cache un fichier -* Télécharger et mettre en cache un dépôt entier -* Télécharger des fichiers dans un dossier local - -## Télécharger un fichier - -La fonction [`hf_hub_download`] est la fonction principale pour télécharger des fichiers du Hub. -Elle télécharge le fichier, le met en cache sur le disque (en prenant en compte les versions) -et retourne le chemin vers le fichier local téléchargé. - - - -Le chemin retourné est un pointeur vers le cache local HF. Par conséquent, il est important de ne pas modifier le fichier -pour éviter de corrompre le cache. Si vous voulez en apprendre plus sur la manière dont les fichiers sont mis en cache, -consultez notre [guide dédié au cache](./manage-cache). - - - -### Télécharger la dernière version - -Sélectionnez le fichier à télécharger en utilisant les paramètres `repo_id`, `repo_type` et `filename`. Par défaut, -le fichier sera considéré comme appartenant à un dépôt contenant des objets de type `model`. - -```python ->>> from huggingface_hub import hf_hub_download ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") -'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' - -# Télécharge un dataset ->>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") -'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' -``` - -### Télécharger une version spécifique - -Par défaut, la dernière version de la branche `main` est téléchargée. Cependant, dans certains cas, vous aurez besoin -de télécharger un fichier ayant une version particulière (i.e. d'une branche spécifique, une pull request, un tag, -ou un hash de commit). -Pour ce faire, utilisez le paramètre `revision`: - -```python -# Télécharge à partir du tag `v1.0` ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") - -# Télécharge à partir de la branche `test-branch` ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") - -# Télécharge à partir de la pull request #3 ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") - -# Télécharge à partir d'un hash de commit spécifique ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") -``` - -**Note:** Lorsque vous utilisez le hash de commit, vous devez renseigner le hash complet et pas le hash de commit à 7 caractères. - -### Générer un URL de téléchargement - -Si vous voulez générer l'URL utilisé pour télécharger un fichier depuis un dépôt, vous pouvez utiliser [`hf_hub_url`] -qui renvoie un URL. Notez que cette méthode est utilisée en arrière plan par [`hf_hub_download`]. - -## Télécharger un dépôt entier - -[`snapshot_download`] télécharge un dépôt entier à une révision donnée. Cette méthode utilise en arrière-plan -[`hf_hub_download`] ce qui signifie que tous les fichiers téléchargés sont aussi mis en cache sur votre disque en local. -Les téléchargements sont faits en parallèle pour rendre le processus plus rapide. - -Pour télécharger un dépôt entier, passez simplement le `repo_id` et le `repo_type`: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp") -'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' - -# Ou pour un dataset ->>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") -'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' -``` - -[`snapshot_download`] télécharge la dernière révision par défaut. Si vous voulez une révision spécifique, utilisez -le paramètre `revision`: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") -``` - -### Filtrer les fichiers à télécharger - -[`snapshot_download`] offre une manière simple de télécharger un dépôt. Cependant, vous ne voudrez peut être pas -télécharger tout le contenu d'un dépôt à chaque fois. Par exemple, vous n'aurez peut-être pas envie de télécharger -tous les fichiers `.bin` si vous savez que vous utiliserez uniquement les poids du `.safetensors`. Vous pouvez -faire ceci en utilisant les paramètres `allow_patterns` et `ignore_patterns`. - -Ces paramètres acceptent un pattern ou une liste de patterns. Les patterns sont des wildcards standards, comme précisé -[ici](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). Le matching de pattern utilise [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). - -Par exemple, vous pouvez utiliser `allow_patterns` pour ne télécharger que les fichiers de configuration JSON: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json") -``` - -A l'opposé, `ignore_patterns` empêche certains fichiers d'être téléchargés. L'exemple -suivant ignore les fichiers ayant pour extension `.msgpack` et `.h5`: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"]) -``` - -Enfin, vous pouvez combiner les deux pour filtrer avec précision vos téléchargements. voici un exemple pour télécharger -tous les fichiers en .md et en .json à l'exception de `vocab.json` - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json") -``` - -## Télécharger un ou plusieurs fichier(s) vers un dossier local - -La manière recommandée (et utilisée par défaut) pour télécharger des fichiers depuis les Hub est d'utiliser -le [cache-system](./manage-cache). Vous pouvez définir le chemin vers votre cache en définissant le -paramètre `cache_dir` (dans [`hf_hub_download`] et [`snapshot_download`]). - -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 une pratique utile pour créer un workflow plus proche de ce qu'on peut retrouver avec les commande `git`. Vous -pouvez faire ceci en utilisant les paramètres `local_dir` et `local_dir_use_symlinks`: -- `local_dir` doit être un chemin vers un dossier de votre système. Les fichiers téléchargés garderont la même structure -de fichier que dans le dépôt. Par exemple, si `filename="data/train.csv"` et `local_dir="path/to/folder"`, alors le -chemin renvoyé sera `"path/to/folder/data/train.csv"`. -- `local_dir_use_symlinks` renseigne comment le fichier doit être enregistré sur votre dossier local. - - Le comportement par défaut (`"auto"`), dupliquera les fichiers peu volumineux (<5MB) et utilisera les symlinks pour - les fichiers plus gros. Les symlinks permettent d'optimiser à la fois la bande passante et l'utilisation du disque. - Cependant, éditer manuellement un fichier sous symlink pourrait corrompre le cache, d'où la duplication pour des - petits fichiers. Le seuil de 5MB peut être configuré avec la variable d'environnement`HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD`. - - Si `local_dir_use_symlinks=True` est passé, alors tous les fichiers seront sous symlink pour une utilisation - optimal de l'espace disque. C'est par exemple utile lors du téléchargement d'un dataset très volumineux contenant - des milliers de petits fichiers. - - Enfin, si vous ne voulez pas utiliser de symlink du tout, vous pouvez les désactier (`local_dir_use_symlinks=False`). - Le chemin du cache sera toujours utilisé afin de vérifier si le fichier est déjà en cache ou pas. Si ce dernier - n'est pas déjà en cache, il sera téléchargé et déplacé directement vers le chemin local. Ce qui signifie que si - vous avez besoin de le réutiliser ailleurs, il sera **retéléchargé** - -Voici une table qui résume les différentes options pour vous aider à choisir les paramètres qui collent le mieux à votre situation. - - -| Paramètre | Fichier déjà en cahce | Chemin renvoyé | Peut-on lire le chemin | Pouvez vous sauvegarder le chemin | Bande passante optimisée | Utilisation du disque optimisée | -|---|:---:|:---:|:---:|:---:|:---:|:---:| -| `local_dir=None` | | symlink en cache | ✅ | ❌
_(sauvegarder corromprait le cache)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | fichier ou symlink dans un dossier | ✅ | ✅ _(pour les petits fichiers)_
⚠️ _(pour les gros fichiers, ne resolve pas le path avant l'enregistrement)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | symlink dans un dossier | ✅ | ⚠️
_(ne resolve pas le paht avant l'enregistrement)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | Non | fichier dans un dossier | ✅ | ✅ | ❌
_(en cas de re-run, le fichier est retéléchargé)_ | ⚠️
(plusieurs copies si lancé dans plusieurs dossiers) | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | oui | fichier dans un dossier | ✅ | ✅ | ⚠️
_(le fichier doit être mis en cache d'abord)_ | ❌
_(le fichier est dupliqué)_ | - -**Note:** si vous utilisez une machien Windows, vous devez activer le mode développeur ou lancer `huggingface_hub` en tant qu'administrateur pour activer les syymlinks. Consultez la section [limitations du cache](../guides/manage-cache#limitations) - -## Télécharger depuis le CLI - -Vous pouvez utiliser la commande `huggingface-cli download` depuis un terminal pour télécharger directement des -fichiers du Hub. En interne, cette commande utilise les même helpers [`hf_hub_download`] et [`snapshot_download`] -décrits ci-dessus et affiche le chemin renvoyé dans le terminal. - -```bash ->>> huggingface-cli download gpt2 config.json -/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json -``` - -Vous pouvez télécharger plusieurs fichiers d'un coup, ce qui affiche une barre de chargement et renvoie le chemin de -la snapshot dans lequel les fichiers sont localisés. - -```bash ->>> huggingface-cli download gpt2 config.json model.safetensors -Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s] -/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 -``` - -Pour plus de détails sur la commande download du CLI, veuillez consulter le [guide CLI](./cli#huggingface-cli-download). - -## Téléchargements plus rapides - -Si vous utilisez une machine avec une bande passante plus large, vous pouvez augmenter votre vitesse de téléchargement en utilisant [`hf_transfer`], -une librairie basée sur Rust développée pour accélérer le transfer de fichiers avec le Hub. Pour l'activer, installez le package (`pip install hf_transfer`) et définissez set `HF_HUB_ENABLE_HF_TRANSFER=1` en tant que variable d'environnement - - - -Les barres de chargement ne fonctionnent avec `hf_transfer` qu'à partir de la version `0.1.4`. Mettez à jour la version (`pip install -U hf_transfer`) -si vous comptez utiliser cette librairie. - - - - - -`hf_transfer` est un outil très puissant! Il a été testé et est prêt à être utilisé en production, mais il lui manque certaines 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). - - \ No newline at end of file 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_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() -``` diff --git a/docs/source/fr/guides/webhooks_server.md b/docs/source/fr/guides/webhooks_server.md deleted file mode 100644 index 250f0ac5b7..0000000000 --- a/docs/source/fr/guides/webhooks_server.md +++ /dev/null @@ -1,205 +0,0 @@ - - -# Serveurs Webhooks - -Les webhooks sont un pilier des fonctionnalités MLOps. Ils vous permettent de suivre tous les nouveaux -changements sur des dépôts spécifiques ou sur tous les dépôts appartenants à des utilisateurs/organisations que -vous voulez suivre. Ce guide vous expliquera comment utiliser `hugginface_hub` pour créer un serveur écoutant des -webhooks et le déployer sur un espacce. Il postule que vous êtes familier avec le concept de webhooks sur le Hub Hugging Face. -Pour en apprendre plus sur les webhooks, vous pouvez consulter le -[guide](https://huggingface.co/docs/hub/webhooks) d'abord. - -La classe de base que nous utiliserons dans ce guide est [`WebhooksServer`]. C'est une classe qui permet de configurer -facilement un serveur qui peut recevoir des webhooks du Hub Huggingface. Le serveur est basé sur une application -[Gradio](https://gradio.app/). Il a une interface pour afficher des instruction pour vous ou vos utilisateurs et une API -pour écouter les webhooks. - - - -Pour voir un exemple fonctionnel de serveur webhook, consultez le [space bot CI](https://huggingface.co/spaces/spaces-ci-bot/webhook). -C'est un space qui lance des environnements éphémères lorsqu'une pull request est ouverte sur un space. - - - - - -C'est une [fonctionnalité expérimentale](../package_reference/environment_variables#hfhubdisableexperimentalwarning), -ce qui signifie que nous travaillons toujours sur l'amélioration de l'API. De nouveaux changement pourront être introduit -dans les future sans avertissement préalable. Assurez vous d'épingler la version d'`hugginface_hub` dans vos requirements. - - - - -## Créer un endpoint - -Implémenter un endpoint webhook est aussi facile que d'ajouter des décorateurs à une fonction. Voyons un premier -exemple afin de clarifier les concepts principaux: - -```python -# app.py -from huggingface_hub import webhook_endpoint, WebhookPayload - -@webhook_endpoint -async def trigger_training(payload: WebhookPayload) -> None: - if payload.repo.type == "dataset" and payload.event.action == "update": - # Lance une tâche d'entrainement si votre dataset est mis à jour - ... -``` - -Enregistrez ce snippet de code dans un fichier appelé `'app.py'` et lancez le avec `'python app.py'`. Vous devriez -voir un message de ce type: - -```text -Webhook secret is not defined. This means your webhook endpoints will be open to everyone. -To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: - `app = WebhooksServer(webhook_secret='my_secret', ...)` -For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret. -Running on local URL: http://127.0.0.1:7860 -Running on public URL: https://1fadb0f52d8bf825fc.gradio.live - -This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces - -Webhooks are correctly setup and ready to use: - - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training -Go to https://huggingface.co/settings/webhooks to setup your webhooks. -``` - -Bien joué! Vous venez de créer un serveur webhook! Décomposons ce qui vient de se passer exactement: - -1. En décorant une fonction avec [`webhook_endpoint`], un objet [`WebhooksServer`] a été créé en arrière plan. -Comme vous pouvez le voir, ce serveur est une application Gradio qui tourne sur http://127.0.0.1:7860. Si vous ouvrez -cet URL dans votre navigateur, vous verez une page d'accueil avec des informations sur les webhooks en question. -2. En arrière plan, une application Gradio n'est rien de plus qu'un serveur FastAPI . Une nouvelle route POST `/webhooks/trigger_training` -y a été ajoutée. C'est cette route qui écoutera les webhooks et lancera la fonction `trigger_training` lors de son activation. -FastAPI parsera automatiquement le paquet et le passera à la fonction en tant qu'objet [`WebhookPayload`]. C'est un objet -`pydantic` qui contient toutes les informations sur l'événement qui a activé le webhook. -3. L'application Gradio a aussi ouvert un tunnel pour recevoir des requêtes d'internet. C'est la partie intéressante: -vous pouvez configurer un webhooj sur https://huggingface.co/settings/webhooks qui pointe vers votre machine. C'est utile -pour debugger votre serveur webhook et rapidement itérer avant de le déployer dans un space. -4. Enfin, les logs vous disent aussi que votre serveur n'est pas sécurisé par un secret. Ce n'est pas problématique pour -le debugging en local mais c'est à garder dans un coin de la tête pour plus tard. - - - -Par défaut, le serveur est lancé à la fin de votre script. Si vous l'utilisez dans un notebook, vous pouvez lancer serveur -manuellement en appelant `decorated_function.run()`. Vu qu'un unique serveur est utilisé, vous aurez uniquement besoin de -lancer le serveur une fois même si vous avez plusieurs endpoints. - - - - -## Configurer un webhook - -Maintenant que vous avez un serveur webhook qui tourne, vous aurez surement besoin de configure un webhook -pour commencer à recevoir des messages. Allez sur https://huggingface.co/settings/webhooks, cliquez sur -"Ajouter un nouveau webhook" et configurez votre webhook. Définissez les dépôts cibles que vous voulez -surveiller et l'URL du webhook, ici `https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training`. - -
- -
- -Et voilà! Vous pouvez maintenant activer cce webhook en mettant à jour le dépôt cible (i.e. push un commit). Consultez -la table d'activité de votre webhook pour voir les événements passés. Maintenant que vous avez un setup qui fonctionne, -vous pouvez le tester et itérer rapidement. Si vous modifiez votre code et relancez le serveur, votre URL public pourrait -changer. Assurez vous de mettre à jour la configuration du webhook dans le Hub si besoin. - -## Déployer vers un space - -Maintenant que vous avez un serveur webhook fonctionnel, le but est de le déployer sur un space. Allez sur -https://huggingface.co/new-space pour créer un space. Donnez lui un nom, sélectionnez le SDK Gradio et cliquer sur -"Créer un space" (ou "Create Space" en anglais). Uploadez votre code dans le space dans un fichier appelé `app.py`. -Votre space sera lancé automatiquement! Pour plus de détails sur les spaces, consultez ce [guide](https://huggingface.co/docs/hub/spaces-overview). - -Votre serveur webhook tourne maintenant sur un space public. Dans la plupart de cas, vous aurez besoin de le sécuriser -avec un secret. Allez dans les paramètres de votre space > Section "Repository secrets" > "Add a secret". Définissez -la variable d'environnement `WEBHOOK_SECRET` en choisissant la valeur que vous voulez. Retournez dans les -[réglages webhooks](https://huggingface.co/settings/webhooks) et définissez le secret dans la configuration du webhook. -Maintenant, seules les requêtes avec le bon secret seront acceptées par votre serveur. - -Et c'est tout! Votre space est maintenant prêt à recevoir des webhooks du Hub. Gardez à l'esprit que si vous faites -tourner le space sur le hardware gratuit 'cpu-basic', il sera éteint après 48 heures d'inactivité. Si vous avez besoin d'un -space permanent, vous devriez peut-être considérer l'amélioration vers un [hardware amélioré](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs). - -## Utilisation avancée - -Le guide ci dessus expliquait la manière la plus rapide d'initialiser un [`WebhookServer`]. Dans cette section, nous verrons -comment le personnaliser plus en détails. - -### Endpoints multilpes - -Vous pouvez avoir plusieurs endpoints sur le même serveur. Par exemple, vous aurez peut-être envie d'avoir un endpoint -qui lance un entrainement de modèle et un autre qui lance une évaluation de modèle. Vous pouvez faire ça en ajoutant -plusieurs décorateurs `@webhook_endpoint`: - -```python -# app.py -from huggingface_hub import webhook_endpoint, WebhookPayload - -@webhook_endpoint -async def trigger_training(payload: WebhookPayload) -> None: - if payload.repo.type == "dataset" and payload.event.action == "update": - # Lance une tâche d'entrainement si votre dataset est mis à jour - ... - -@webhook_endpoint -async def trigger_evaluation(payload: WebhookPayload) -> None: - if payload.repo.type == "model" and payload.event.action == "update": - # Lance un tâche d'évaluation si un modèle est mis à jour - ... -``` - -Ce qui créera deux endpoints: - -```text -(...) -Webhooks are correctly setup and ready to use: - - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training - - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation -``` - -### Serveur personnalisé - -Pour plus de flexibilité, vous pouvez aussi créer un objet [`WebhooksServer`] directement. C'est utile si vous -voulez customiser la page d'acceuil de votre serveur. Vous pouvez le faire en passant une [UI Gradio](https://gradio.app/docs/#blocks) -qui va overwrite linterface par défaut. Par exemple, vous pouvez ajouter des instructions pour vos utilisateurs -ou ajouter un formulaire pour avtiver les webhooks manuellement. Lors de la création d'un [`WebhooksServer`], vous -pouvez créer de nouveaux webhooks en utilisant le décorateur [`~WebhooksServer.add_webhook`]. - -Here is a complete example: - -```python -import gradio as gr -from fastapi import Request -from huggingface_hub import WebhooksServer, WebhookPayload - -# 1. Déifnition de l'interface -with gr.Blocks() as ui: - ... - -# 2. Création d'un WebhooksServer avec une interface personnalisée et un secret -app = WebhooksServer(ui=ui, webhook_secret="my_secret_key") - -# 3. Ajout d'un webhook avec un nom explicite -@app.add_webhook("/say_hello") -async def hello(payload: WebhookPayload): - return {"message": "hello"} - -# 4. Ajout d'un webhook avec un nom implicite -@app.add_webhook -async def goodbye(payload: WebhookPayload): - return {"message": "goodbye"} - -# 5. Lancement du serveur (optionnel) -app.run() -``` - -1. Nous définissons une interface personnalisée en utilisant des block Gradio. Cette interface sera affichée -sur la page d'accueil du serveur. -2. Nous créons un objet [`WebhooksServer`] avec une interface personnalisée et un secret. Le secret est optionnel et -peut être définit avec la variable d'environnement `WEBHOOK_SECRET`. -3. Nous créons un webhook avec un nom explicite. Ceci créera un endpoint à `/webhooks/say_hello`. -4. Nous créons un webhook avec un nom implicite. Ceci créera un endpoint à `/webhoojs/goodbye`. -5. Nous lançons le serveur. C'est optionnel car votre serveur sera automatiquement lancé à la fin du script. \ No newline at end of file From 63b0dd27f5da9eadbe484e3ca4782b6c2868cc34 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 8 Jun 2024 00:22:25 +0200 Subject: [PATCH 086/129] Revert "Deleted files" This reverts commit 34c49a7cbe74faf605621d6e96ee016a62beaa65. --- docs/source/fr/guides/cli.md | 478 +++++++++++++++ docs/source/fr/guides/collections.md | 230 +++++++ docs/source/fr/guides/community.md | 153 +++++ docs/source/fr/guides/download.md | 208 +++++++ docs/source/fr/guides/hf_file_system.md | 110 ++++ docs/source/fr/guides/inference_endpoints.md | 261 ++++++++ docs/source/fr/guides/integrations.md | 290 +++++++++ docs/source/fr/guides/manage-cache.md | 569 ++++++++++++++++++ docs/source/fr/guides/manage-spaces.md | 379 ++++++++++++ docs/source/fr/guides/model-cards.md | 373 ++++++++++++ docs/source/fr/guides/overview.md | 131 ++++ docs/source/fr/guides/repository.md | 248 ++++++++ docs/source/fr/guides/search.md | 69 +++ docs/source/fr/guides/upload.md | 596 +++++++++++++++++++ docs/source/fr/guides/webhooks_server.md | 205 +++++++ 15 files changed, 4300 insertions(+) create mode 100644 docs/source/fr/guides/cli.md create mode 100644 docs/source/fr/guides/collections.md create mode 100644 docs/source/fr/guides/community.md create mode 100644 docs/source/fr/guides/download.md create mode 100644 docs/source/fr/guides/hf_file_system.md create mode 100644 docs/source/fr/guides/inference_endpoints.md create mode 100644 docs/source/fr/guides/integrations.md create mode 100644 docs/source/fr/guides/manage-cache.md create mode 100644 docs/source/fr/guides/manage-spaces.md create mode 100644 docs/source/fr/guides/model-cards.md create mode 100644 docs/source/fr/guides/overview.md create mode 100644 docs/source/fr/guides/repository.md create mode 100644 docs/source/fr/guides/search.md create mode 100644 docs/source/fr/guides/upload.md create mode 100644 docs/source/fr/guides/webhooks_server.md diff --git a/docs/source/fr/guides/cli.md b/docs/source/fr/guides/cli.md new file mode 100644 index 0000000000..f18e3fe743 --- /dev/null +++ b/docs/source/fr/guides/cli.md @@ -0,0 +1,478 @@ + + +# 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 new file mode 100644 index 0000000000..c83cb5e4f7 --- /dev/null +++ b/docs/source/fr/guides/collections.md @@ -0,0 +1,230 @@ + + +# 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 new file mode 100644 index 0000000000..8afcbebe97 --- /dev/null +++ b/docs/source/fr/guides/community.md @@ -0,0 +1,153 @@ + + +# 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/download.md b/docs/source/fr/guides/download.md new file mode 100644 index 0000000000..9dae248d92 --- /dev/null +++ b/docs/source/fr/guides/download.md @@ -0,0 +1,208 @@ + + +# Télécharger des fichiers du Hub + +La librairie `huggingface_hub` fournit des fonctions pour télécharger des fichiers depuis +les dépôts stockés sur le Hub. Vous pouvez utiliser ces fonctions directement ou les intégrer +dans votre propre librairie, pour rendre l'intéraction entre vos utilisateurs et le Hub +plus simple. Ce guide vous montrera comment: + +* Télécharger et mettre en cache un fichier +* Télécharger et mettre en cache un dépôt entier +* Télécharger des fichiers dans un dossier local + +## Télécharger un fichier + +La fonction [`hf_hub_download`] est la fonction principale pour télécharger des fichiers du Hub. +Elle télécharge le fichier, le met en cache sur le disque (en prenant en compte les versions) +et retourne le chemin vers le fichier local téléchargé. + + + +Le chemin retourné est un pointeur vers le cache local HF. Par conséquent, il est important de ne pas modifier le fichier +pour éviter de corrompre le cache. Si vous voulez en apprendre plus sur la manière dont les fichiers sont mis en cache, +consultez notre [guide dédié au cache](./manage-cache). + + + +### Télécharger la dernière version + +Sélectionnez le fichier à télécharger en utilisant les paramètres `repo_id`, `repo_type` et `filename`. Par défaut, +le fichier sera considéré comme appartenant à un dépôt contenant des objets de type `model`. + +```python +>>> from huggingface_hub import hf_hub_download +>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") +'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' + +# Télécharge un dataset +>>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") +'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' +``` + +### Télécharger une version spécifique + +Par défaut, la dernière version de la branche `main` est téléchargée. Cependant, dans certains cas, vous aurez besoin +de télécharger un fichier ayant une version particulière (i.e. d'une branche spécifique, une pull request, un tag, +ou un hash de commit). +Pour ce faire, utilisez le paramètre `revision`: + +```python +# Télécharge à partir du tag `v1.0` +>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") + +# Télécharge à partir de la branche `test-branch` +>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") + +# Télécharge à partir de la pull request #3 +>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") + +# Télécharge à partir d'un hash de commit spécifique +>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") +``` + +**Note:** Lorsque vous utilisez le hash de commit, vous devez renseigner le hash complet et pas le hash de commit à 7 caractères. + +### Générer un URL de téléchargement + +Si vous voulez générer l'URL utilisé pour télécharger un fichier depuis un dépôt, vous pouvez utiliser [`hf_hub_url`] +qui renvoie un URL. Notez que cette méthode est utilisée en arrière plan par [`hf_hub_download`]. + +## Télécharger un dépôt entier + +[`snapshot_download`] télécharge un dépôt entier à une révision donnée. Cette méthode utilise en arrière-plan +[`hf_hub_download`] ce qui signifie que tous les fichiers téléchargés sont aussi mis en cache sur votre disque en local. +Les téléchargements sont faits en parallèle pour rendre le processus plus rapide. + +Pour télécharger un dépôt entier, passez simplement le `repo_id` et le `repo_type`: + +```python +>>> from huggingface_hub import snapshot_download +>>> snapshot_download(repo_id="lysandre/arxiv-nlp") +'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' + +# Ou pour un dataset +>>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") +'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' +``` + +[`snapshot_download`] télécharge la dernière révision par défaut. Si vous voulez une révision spécifique, utilisez +le paramètre `revision`: + +```python +>>> from huggingface_hub import snapshot_download +>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") +``` + +### Filtrer les fichiers à télécharger + +[`snapshot_download`] offre une manière simple de télécharger un dépôt. Cependant, vous ne voudrez peut être pas +télécharger tout le contenu d'un dépôt à chaque fois. Par exemple, vous n'aurez peut-être pas envie de télécharger +tous les fichiers `.bin` si vous savez que vous utiliserez uniquement les poids du `.safetensors`. Vous pouvez +faire ceci en utilisant les paramètres `allow_patterns` et `ignore_patterns`. + +Ces paramètres acceptent un pattern ou une liste de patterns. Les patterns sont des wildcards standards, comme précisé +[ici](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). Le matching de pattern utilise [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). + +Par exemple, vous pouvez utiliser `allow_patterns` pour ne télécharger que les fichiers de configuration JSON: + +```python +>>> from huggingface_hub import snapshot_download +>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json") +``` + +A l'opposé, `ignore_patterns` empêche certains fichiers d'être téléchargés. L'exemple +suivant ignore les fichiers ayant pour extension `.msgpack` et `.h5`: + +```python +>>> from huggingface_hub import snapshot_download +>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"]) +``` + +Enfin, vous pouvez combiner les deux pour filtrer avec précision vos téléchargements. voici un exemple pour télécharger +tous les fichiers en .md et en .json à l'exception de `vocab.json` + +```python +>>> from huggingface_hub import snapshot_download +>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json") +``` + +## Télécharger un ou plusieurs fichier(s) vers un dossier local + +La manière recommandée (et utilisée par défaut) pour télécharger des fichiers depuis les Hub est d'utiliser +le [cache-system](./manage-cache). Vous pouvez définir le chemin vers votre cache en définissant le +paramètre `cache_dir` (dans [`hf_hub_download`] et [`snapshot_download`]). + +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 une pratique utile pour créer un workflow plus proche de ce qu'on peut retrouver avec les commande `git`. Vous +pouvez faire ceci en utilisant les paramètres `local_dir` et `local_dir_use_symlinks`: +- `local_dir` doit être un chemin vers un dossier de votre système. Les fichiers téléchargés garderont la même structure +de fichier que dans le dépôt. Par exemple, si `filename="data/train.csv"` et `local_dir="path/to/folder"`, alors le +chemin renvoyé sera `"path/to/folder/data/train.csv"`. +- `local_dir_use_symlinks` renseigne comment le fichier doit être enregistré sur votre dossier local. + - Le comportement par défaut (`"auto"`), dupliquera les fichiers peu volumineux (<5MB) et utilisera les symlinks pour + les fichiers plus gros. Les symlinks permettent d'optimiser à la fois la bande passante et l'utilisation du disque. + Cependant, éditer manuellement un fichier sous symlink pourrait corrompre le cache, d'où la duplication pour des + petits fichiers. Le seuil de 5MB peut être configuré avec la variable d'environnement`HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD`. + - Si `local_dir_use_symlinks=True` est passé, alors tous les fichiers seront sous symlink pour une utilisation + optimal de l'espace disque. C'est par exemple utile lors du téléchargement d'un dataset très volumineux contenant + des milliers de petits fichiers. + - Enfin, si vous ne voulez pas utiliser de symlink du tout, vous pouvez les désactier (`local_dir_use_symlinks=False`). + Le chemin du cache sera toujours utilisé afin de vérifier si le fichier est déjà en cache ou pas. Si ce dernier + n'est pas déjà en cache, il sera téléchargé et déplacé directement vers le chemin local. Ce qui signifie que si + vous avez besoin de le réutiliser ailleurs, il sera **retéléchargé** + +Voici une table qui résume les différentes options pour vous aider à choisir les paramètres qui collent le mieux à votre situation. + + +| Paramètre | Fichier déjà en cahce | Chemin renvoyé | Peut-on lire le chemin | Pouvez vous sauvegarder le chemin | Bande passante optimisée | Utilisation du disque optimisée | +|---|:---:|:---:|:---:|:---:|:---:|:---:| +| `local_dir=None` | | symlink en cache | ✅ | ❌
_(sauvegarder corromprait le cache)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | fichier ou symlink dans un dossier | ✅ | ✅ _(pour les petits fichiers)_
⚠️ _(pour les gros fichiers, ne resolve pas le path avant l'enregistrement)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | symlink dans un dossier | ✅ | ⚠️
_(ne resolve pas le paht avant l'enregistrement)_ | ✅ | ✅ | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | Non | fichier dans un dossier | ✅ | ✅ | ❌
_(en cas de re-run, le fichier est retéléchargé)_ | ⚠️
(plusieurs copies si lancé dans plusieurs dossiers) | +| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | oui | fichier dans un dossier | ✅ | ✅ | ⚠️
_(le fichier doit être mis en cache d'abord)_ | ❌
_(le fichier est dupliqué)_ | + +**Note:** si vous utilisez une machien Windows, vous devez activer le mode développeur ou lancer `huggingface_hub` en tant qu'administrateur pour activer les syymlinks. Consultez la section [limitations du cache](../guides/manage-cache#limitations) + +## Télécharger depuis le CLI + +Vous pouvez utiliser la commande `huggingface-cli download` depuis un terminal pour télécharger directement des +fichiers du Hub. En interne, cette commande utilise les même helpers [`hf_hub_download`] et [`snapshot_download`] +décrits ci-dessus et affiche le chemin renvoyé dans le terminal. + +```bash +>>> huggingface-cli download gpt2 config.json +/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json +``` + +Vous pouvez télécharger plusieurs fichiers d'un coup, ce qui affiche une barre de chargement et renvoie le chemin de +la snapshot dans lequel les fichiers sont localisés. + +```bash +>>> huggingface-cli download gpt2 config.json model.safetensors +Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s] +/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 +``` + +Pour plus de détails sur la commande download du CLI, veuillez consulter le [guide CLI](./cli#huggingface-cli-download). + +## Téléchargements plus rapides + +Si vous utilisez une machine avec une bande passante plus large, vous pouvez augmenter votre vitesse de téléchargement en utilisant [`hf_transfer`], +une librairie basée sur Rust développée pour accélérer le transfer de fichiers avec le Hub. Pour l'activer, installez le package (`pip install hf_transfer`) et définissez set `HF_HUB_ENABLE_HF_TRANSFER=1` en tant que variable d'environnement + + + +Les barres de chargement ne fonctionnent avec `hf_transfer` qu'à partir de la version `0.1.4`. Mettez à jour la version (`pip install -U hf_transfer`) +si vous comptez utiliser cette librairie. + + + + + +`hf_transfer` est un outil très puissant! Il a été testé et est prêt à être utilisé en production, mais il lui manque certaines 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). + + \ No newline at end of file diff --git a/docs/source/fr/guides/hf_file_system.md b/docs/source/fr/guides/hf_file_system.md new file mode 100644 index 0000000000..749ddc43ff --- /dev/null +++ b/docs/source/fr/guides/hf_file_system.md @@ -0,0 +1,110 @@ + + +# 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_endpoints.md b/docs/source/fr/guides/inference_endpoints.md new file mode 100644 index 0000000000..9783c30282 --- /dev/null +++ b/docs/source/fr/guides/inference_endpoints.md @@ -0,0 +1,261 @@ +# 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 new file mode 100644 index 0000000000..3a8b6a93d9 --- /dev/null +++ b/docs/source/fr/guides/integrations.md @@ -0,0 +1,290 @@ + + +# 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 new file mode 100644 index 0000000000..0e37bbc3ea --- /dev/null +++ b/docs/source/fr/guides/manage-cache.md @@ -0,0 +1,569 @@ + + +# 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 new file mode 100644 index 0000000000..520b593ce3 --- /dev/null +++ b/docs/source/fr/guides/manage-spaces.md @@ -0,0 +1,379 @@ + + +# 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 new file mode 100644 index 0000000000..74bcdcfaf0 --- /dev/null +++ b/docs/source/fr/guides/model-cards.md @@ -0,0 +1,373 @@ + + +# 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 new file mode 100644 index 0000000000..6c1e10fbae --- /dev/null +++ b/docs/source/fr/guides/overview.md @@ -0,0 +1,131 @@ + + +# 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 new file mode 100644 index 0000000000..db635a310d --- /dev/null +++ b/docs/source/fr/guides/repository.md @@ -0,0 +1,248 @@ + + +# 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 new file mode 100644 index 0000000000..6df3dda91f --- /dev/null +++ b/docs/source/fr/guides/search.md @@ -0,0 +1,69 @@ + + +# 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 new file mode 100644 index 0000000000..c3af60ff4a --- /dev/null +++ b/docs/source/fr/guides/upload.md @@ -0,0 +1,596 @@ + + +# 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() +``` diff --git a/docs/source/fr/guides/webhooks_server.md b/docs/source/fr/guides/webhooks_server.md new file mode 100644 index 0000000000..250f0ac5b7 --- /dev/null +++ b/docs/source/fr/guides/webhooks_server.md @@ -0,0 +1,205 @@ + + +# Serveurs Webhooks + +Les webhooks sont un pilier des fonctionnalités MLOps. Ils vous permettent de suivre tous les nouveaux +changements sur des dépôts spécifiques ou sur tous les dépôts appartenants à des utilisateurs/organisations que +vous voulez suivre. Ce guide vous expliquera comment utiliser `hugginface_hub` pour créer un serveur écoutant des +webhooks et le déployer sur un espacce. Il postule que vous êtes familier avec le concept de webhooks sur le Hub Hugging Face. +Pour en apprendre plus sur les webhooks, vous pouvez consulter le +[guide](https://huggingface.co/docs/hub/webhooks) d'abord. + +La classe de base que nous utiliserons dans ce guide est [`WebhooksServer`]. C'est une classe qui permet de configurer +facilement un serveur qui peut recevoir des webhooks du Hub Huggingface. Le serveur est basé sur une application +[Gradio](https://gradio.app/). Il a une interface pour afficher des instruction pour vous ou vos utilisateurs et une API +pour écouter les webhooks. + + + +Pour voir un exemple fonctionnel de serveur webhook, consultez le [space bot CI](https://huggingface.co/spaces/spaces-ci-bot/webhook). +C'est un space qui lance des environnements éphémères lorsqu'une pull request est ouverte sur un space. + + + + + +C'est une [fonctionnalité expérimentale](../package_reference/environment_variables#hfhubdisableexperimentalwarning), +ce qui signifie que nous travaillons toujours sur l'amélioration de l'API. De nouveaux changement pourront être introduit +dans les future sans avertissement préalable. Assurez vous d'épingler la version d'`hugginface_hub` dans vos requirements. + + + + +## Créer un endpoint + +Implémenter un endpoint webhook est aussi facile que d'ajouter des décorateurs à une fonction. Voyons un premier +exemple afin de clarifier les concepts principaux: + +```python +# app.py +from huggingface_hub import webhook_endpoint, WebhookPayload + +@webhook_endpoint +async def trigger_training(payload: WebhookPayload) -> None: + if payload.repo.type == "dataset" and payload.event.action == "update": + # Lance une tâche d'entrainement si votre dataset est mis à jour + ... +``` + +Enregistrez ce snippet de code dans un fichier appelé `'app.py'` et lancez le avec `'python app.py'`. Vous devriez +voir un message de ce type: + +```text +Webhook secret is not defined. This means your webhook endpoints will be open to everyone. +To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: + `app = WebhooksServer(webhook_secret='my_secret', ...)` +For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret. +Running on local URL: http://127.0.0.1:7860 +Running on public URL: https://1fadb0f52d8bf825fc.gradio.live + +This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces + +Webhooks are correctly setup and ready to use: + - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training +Go to https://huggingface.co/settings/webhooks to setup your webhooks. +``` + +Bien joué! Vous venez de créer un serveur webhook! Décomposons ce qui vient de se passer exactement: + +1. En décorant une fonction avec [`webhook_endpoint`], un objet [`WebhooksServer`] a été créé en arrière plan. +Comme vous pouvez le voir, ce serveur est une application Gradio qui tourne sur http://127.0.0.1:7860. Si vous ouvrez +cet URL dans votre navigateur, vous verez une page d'accueil avec des informations sur les webhooks en question. +2. En arrière plan, une application Gradio n'est rien de plus qu'un serveur FastAPI . Une nouvelle route POST `/webhooks/trigger_training` +y a été ajoutée. C'est cette route qui écoutera les webhooks et lancera la fonction `trigger_training` lors de son activation. +FastAPI parsera automatiquement le paquet et le passera à la fonction en tant qu'objet [`WebhookPayload`]. C'est un objet +`pydantic` qui contient toutes les informations sur l'événement qui a activé le webhook. +3. L'application Gradio a aussi ouvert un tunnel pour recevoir des requêtes d'internet. C'est la partie intéressante: +vous pouvez configurer un webhooj sur https://huggingface.co/settings/webhooks qui pointe vers votre machine. C'est utile +pour debugger votre serveur webhook et rapidement itérer avant de le déployer dans un space. +4. Enfin, les logs vous disent aussi que votre serveur n'est pas sécurisé par un secret. Ce n'est pas problématique pour +le debugging en local mais c'est à garder dans un coin de la tête pour plus tard. + + + +Par défaut, le serveur est lancé à la fin de votre script. Si vous l'utilisez dans un notebook, vous pouvez lancer serveur +manuellement en appelant `decorated_function.run()`. Vu qu'un unique serveur est utilisé, vous aurez uniquement besoin de +lancer le serveur une fois même si vous avez plusieurs endpoints. + + + + +## Configurer un webhook + +Maintenant que vous avez un serveur webhook qui tourne, vous aurez surement besoin de configure un webhook +pour commencer à recevoir des messages. Allez sur https://huggingface.co/settings/webhooks, cliquez sur +"Ajouter un nouveau webhook" et configurez votre webhook. Définissez les dépôts cibles que vous voulez +surveiller et l'URL du webhook, ici `https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training`. + +
+ +
+ +Et voilà! Vous pouvez maintenant activer cce webhook en mettant à jour le dépôt cible (i.e. push un commit). Consultez +la table d'activité de votre webhook pour voir les événements passés. Maintenant que vous avez un setup qui fonctionne, +vous pouvez le tester et itérer rapidement. Si vous modifiez votre code et relancez le serveur, votre URL public pourrait +changer. Assurez vous de mettre à jour la configuration du webhook dans le Hub si besoin. + +## Déployer vers un space + +Maintenant que vous avez un serveur webhook fonctionnel, le but est de le déployer sur un space. Allez sur +https://huggingface.co/new-space pour créer un space. Donnez lui un nom, sélectionnez le SDK Gradio et cliquer sur +"Créer un space" (ou "Create Space" en anglais). Uploadez votre code dans le space dans un fichier appelé `app.py`. +Votre space sera lancé automatiquement! Pour plus de détails sur les spaces, consultez ce [guide](https://huggingface.co/docs/hub/spaces-overview). + +Votre serveur webhook tourne maintenant sur un space public. Dans la plupart de cas, vous aurez besoin de le sécuriser +avec un secret. Allez dans les paramètres de votre space > Section "Repository secrets" > "Add a secret". Définissez +la variable d'environnement `WEBHOOK_SECRET` en choisissant la valeur que vous voulez. Retournez dans les +[réglages webhooks](https://huggingface.co/settings/webhooks) et définissez le secret dans la configuration du webhook. +Maintenant, seules les requêtes avec le bon secret seront acceptées par votre serveur. + +Et c'est tout! Votre space est maintenant prêt à recevoir des webhooks du Hub. Gardez à l'esprit que si vous faites +tourner le space sur le hardware gratuit 'cpu-basic', il sera éteint après 48 heures d'inactivité. Si vous avez besoin d'un +space permanent, vous devriez peut-être considérer l'amélioration vers un [hardware amélioré](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs). + +## Utilisation avancée + +Le guide ci dessus expliquait la manière la plus rapide d'initialiser un [`WebhookServer`]. Dans cette section, nous verrons +comment le personnaliser plus en détails. + +### Endpoints multilpes + +Vous pouvez avoir plusieurs endpoints sur le même serveur. Par exemple, vous aurez peut-être envie d'avoir un endpoint +qui lance un entrainement de modèle et un autre qui lance une évaluation de modèle. Vous pouvez faire ça en ajoutant +plusieurs décorateurs `@webhook_endpoint`: + +```python +# app.py +from huggingface_hub import webhook_endpoint, WebhookPayload + +@webhook_endpoint +async def trigger_training(payload: WebhookPayload) -> None: + if payload.repo.type == "dataset" and payload.event.action == "update": + # Lance une tâche d'entrainement si votre dataset est mis à jour + ... + +@webhook_endpoint +async def trigger_evaluation(payload: WebhookPayload) -> None: + if payload.repo.type == "model" and payload.event.action == "update": + # Lance un tâche d'évaluation si un modèle est mis à jour + ... +``` + +Ce qui créera deux endpoints: + +```text +(...) +Webhooks are correctly setup and ready to use: + - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training + - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation +``` + +### Serveur personnalisé + +Pour plus de flexibilité, vous pouvez aussi créer un objet [`WebhooksServer`] directement. C'est utile si vous +voulez customiser la page d'acceuil de votre serveur. Vous pouvez le faire en passant une [UI Gradio](https://gradio.app/docs/#blocks) +qui va overwrite linterface par défaut. Par exemple, vous pouvez ajouter des instructions pour vos utilisateurs +ou ajouter un formulaire pour avtiver les webhooks manuellement. Lors de la création d'un [`WebhooksServer`], vous +pouvez créer de nouveaux webhooks en utilisant le décorateur [`~WebhooksServer.add_webhook`]. + +Here is a complete example: + +```python +import gradio as gr +from fastapi import Request +from huggingface_hub import WebhooksServer, WebhookPayload + +# 1. Déifnition de l'interface +with gr.Blocks() as ui: + ... + +# 2. Création d'un WebhooksServer avec une interface personnalisée et un secret +app = WebhooksServer(ui=ui, webhook_secret="my_secret_key") + +# 3. Ajout d'un webhook avec un nom explicite +@app.add_webhook("/say_hello") +async def hello(payload: WebhookPayload): + return {"message": "hello"} + +# 4. Ajout d'un webhook avec un nom implicite +@app.add_webhook +async def goodbye(payload: WebhookPayload): + return {"message": "goodbye"} + +# 5. Lancement du serveur (optionnel) +app.run() +``` + +1. Nous définissons une interface personnalisée en utilisant des block Gradio. Cette interface sera affichée +sur la page d'accueil du serveur. +2. Nous créons un objet [`WebhooksServer`] avec une interface personnalisée et un secret. Le secret est optionnel et +peut être définit avec la variable d'environnement `WEBHOOK_SECRET`. +3. Nous créons un webhook avec un nom explicite. Ceci créera un endpoint à `/webhooks/say_hello`. +4. Nous créons un webhook avec un nom implicite. Ceci créera un endpoint à `/webhoojs/goodbye`. +5. Nous lançons le serveur. C'est optionnel car votre serveur sera automatiquement lancé à la fin du script. \ No newline at end of file From a5f0d54a92cbf4b4dd46db5a4aed9cb1ef321761 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 8 Jun 2024 00:27:55 +0200 Subject: [PATCH 087/129] Deleted files --- docs/source/fr/guides/cli.md | 478 --------------- docs/source/fr/guides/collections.md | 230 ------- docs/source/fr/guides/community.md | 153 ----- docs/source/fr/guides/download.md | 208 ------- docs/source/fr/guides/hf_file_system.md | 110 ---- docs/source/fr/guides/inference.md | 344 ----------- docs/source/fr/guides/inference_endpoints.md | 261 -------- docs/source/fr/guides/manage-cache.md | 569 ------------------ docs/source/fr/guides/manage-spaces.md | 379 ------------ docs/source/fr/guides/model-cards.md | 373 ------------ docs/source/fr/guides/overview.md | 131 ---- docs/source/fr/guides/repository.md | 248 -------- docs/source/fr/guides/search.md | 69 --- docs/source/fr/guides/upload.md | 596 ------------------- docs/source/fr/guides/webhooks_server.md | 205 ------- 15 files changed, 4354 deletions(-) delete mode 100644 docs/source/fr/guides/cli.md delete mode 100644 docs/source/fr/guides/collections.md delete mode 100644 docs/source/fr/guides/community.md delete mode 100644 docs/source/fr/guides/download.md delete mode 100644 docs/source/fr/guides/hf_file_system.md delete mode 100644 docs/source/fr/guides/inference.md delete mode 100644 docs/source/fr/guides/inference_endpoints.md delete mode 100644 docs/source/fr/guides/manage-cache.md delete mode 100644 docs/source/fr/guides/manage-spaces.md delete mode 100644 docs/source/fr/guides/model-cards.md delete mode 100644 docs/source/fr/guides/overview.md delete mode 100644 docs/source/fr/guides/repository.md delete mode 100644 docs/source/fr/guides/search.md delete mode 100644 docs/source/fr/guides/upload.md delete mode 100644 docs/source/fr/guides/webhooks_server.md 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/download.md b/docs/source/fr/guides/download.md deleted file mode 100644 index 9dae248d92..0000000000 --- a/docs/source/fr/guides/download.md +++ /dev/null @@ -1,208 +0,0 @@ - - -# Télécharger des fichiers du Hub - -La librairie `huggingface_hub` fournit des fonctions pour télécharger des fichiers depuis -les dépôts stockés sur le Hub. Vous pouvez utiliser ces fonctions directement ou les intégrer -dans votre propre librairie, pour rendre l'intéraction entre vos utilisateurs et le Hub -plus simple. Ce guide vous montrera comment: - -* Télécharger et mettre en cache un fichier -* Télécharger et mettre en cache un dépôt entier -* Télécharger des fichiers dans un dossier local - -## Télécharger un fichier - -La fonction [`hf_hub_download`] est la fonction principale pour télécharger des fichiers du Hub. -Elle télécharge le fichier, le met en cache sur le disque (en prenant en compte les versions) -et retourne le chemin vers le fichier local téléchargé. - - - -Le chemin retourné est un pointeur vers le cache local HF. Par conséquent, il est important de ne pas modifier le fichier -pour éviter de corrompre le cache. Si vous voulez en apprendre plus sur la manière dont les fichiers sont mis en cache, -consultez notre [guide dédié au cache](./manage-cache). - - - -### Télécharger la dernière version - -Sélectionnez le fichier à télécharger en utilisant les paramètres `repo_id`, `repo_type` et `filename`. Par défaut, -le fichier sera considéré comme appartenant à un dépôt contenant des objets de type `model`. - -```python ->>> from huggingface_hub import hf_hub_download ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") -'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' - -# Télécharge un dataset ->>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") -'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' -``` - -### Télécharger une version spécifique - -Par défaut, la dernière version de la branche `main` est téléchargée. Cependant, dans certains cas, vous aurez besoin -de télécharger un fichier ayant une version particulière (i.e. d'une branche spécifique, une pull request, un tag, -ou un hash de commit). -Pour ce faire, utilisez le paramètre `revision`: - -```python -# Télécharge à partir du tag `v1.0` ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") - -# Télécharge à partir de la branche `test-branch` ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") - -# Télécharge à partir de la pull request #3 ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") - -# Télécharge à partir d'un hash de commit spécifique ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") -``` - -**Note:** Lorsque vous utilisez le hash de commit, vous devez renseigner le hash complet et pas le hash de commit à 7 caractères. - -### Générer un URL de téléchargement - -Si vous voulez générer l'URL utilisé pour télécharger un fichier depuis un dépôt, vous pouvez utiliser [`hf_hub_url`] -qui renvoie un URL. Notez que cette méthode est utilisée en arrière plan par [`hf_hub_download`]. - -## Télécharger un dépôt entier - -[`snapshot_download`] télécharge un dépôt entier à une révision donnée. Cette méthode utilise en arrière-plan -[`hf_hub_download`] ce qui signifie que tous les fichiers téléchargés sont aussi mis en cache sur votre disque en local. -Les téléchargements sont faits en parallèle pour rendre le processus plus rapide. - -Pour télécharger un dépôt entier, passez simplement le `repo_id` et le `repo_type`: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp") -'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' - -# Ou pour un dataset ->>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") -'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' -``` - -[`snapshot_download`] télécharge la dernière révision par défaut. Si vous voulez une révision spécifique, utilisez -le paramètre `revision`: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") -``` - -### Filtrer les fichiers à télécharger - -[`snapshot_download`] offre une manière simple de télécharger un dépôt. Cependant, vous ne voudrez peut être pas -télécharger tout le contenu d'un dépôt à chaque fois. Par exemple, vous n'aurez peut-être pas envie de télécharger -tous les fichiers `.bin` si vous savez que vous utiliserez uniquement les poids du `.safetensors`. Vous pouvez -faire ceci en utilisant les paramètres `allow_patterns` et `ignore_patterns`. - -Ces paramètres acceptent un pattern ou une liste de patterns. Les patterns sont des wildcards standards, comme précisé -[ici](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). Le matching de pattern utilise [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). - -Par exemple, vous pouvez utiliser `allow_patterns` pour ne télécharger que les fichiers de configuration JSON: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json") -``` - -A l'opposé, `ignore_patterns` empêche certains fichiers d'être téléchargés. L'exemple -suivant ignore les fichiers ayant pour extension `.msgpack` et `.h5`: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"]) -``` - -Enfin, vous pouvez combiner les deux pour filtrer avec précision vos téléchargements. voici un exemple pour télécharger -tous les fichiers en .md et en .json à l'exception de `vocab.json` - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json") -``` - -## Télécharger un ou plusieurs fichier(s) vers un dossier local - -La manière recommandée (et utilisée par défaut) pour télécharger des fichiers depuis les Hub est d'utiliser -le [cache-system](./manage-cache). Vous pouvez définir le chemin vers votre cache en définissant le -paramètre `cache_dir` (dans [`hf_hub_download`] et [`snapshot_download`]). - -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 une pratique utile pour créer un workflow plus proche de ce qu'on peut retrouver avec les commande `git`. Vous -pouvez faire ceci en utilisant les paramètres `local_dir` et `local_dir_use_symlinks`: -- `local_dir` doit être un chemin vers un dossier de votre système. Les fichiers téléchargés garderont la même structure -de fichier que dans le dépôt. Par exemple, si `filename="data/train.csv"` et `local_dir="path/to/folder"`, alors le -chemin renvoyé sera `"path/to/folder/data/train.csv"`. -- `local_dir_use_symlinks` renseigne comment le fichier doit être enregistré sur votre dossier local. - - Le comportement par défaut (`"auto"`), dupliquera les fichiers peu volumineux (<5MB) et utilisera les symlinks pour - les fichiers plus gros. Les symlinks permettent d'optimiser à la fois la bande passante et l'utilisation du disque. - Cependant, éditer manuellement un fichier sous symlink pourrait corrompre le cache, d'où la duplication pour des - petits fichiers. Le seuil de 5MB peut être configuré avec la variable d'environnement`HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD`. - - Si `local_dir_use_symlinks=True` est passé, alors tous les fichiers seront sous symlink pour une utilisation - optimal de l'espace disque. C'est par exemple utile lors du téléchargement d'un dataset très volumineux contenant - des milliers de petits fichiers. - - Enfin, si vous ne voulez pas utiliser de symlink du tout, vous pouvez les désactier (`local_dir_use_symlinks=False`). - Le chemin du cache sera toujours utilisé afin de vérifier si le fichier est déjà en cache ou pas. Si ce dernier - n'est pas déjà en cache, il sera téléchargé et déplacé directement vers le chemin local. Ce qui signifie que si - vous avez besoin de le réutiliser ailleurs, il sera **retéléchargé** - -Voici une table qui résume les différentes options pour vous aider à choisir les paramètres qui collent le mieux à votre situation. - - -| Paramètre | Fichier déjà en cahce | Chemin renvoyé | Peut-on lire le chemin | Pouvez vous sauvegarder le chemin | Bande passante optimisée | Utilisation du disque optimisée | -|---|:---:|:---:|:---:|:---:|:---:|:---:| -| `local_dir=None` | | symlink en cache | ✅ | ❌
_(sauvegarder corromprait le cache)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | fichier ou symlink dans un dossier | ✅ | ✅ _(pour les petits fichiers)_
⚠️ _(pour les gros fichiers, ne resolve pas le path avant l'enregistrement)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | symlink dans un dossier | ✅ | ⚠️
_(ne resolve pas le paht avant l'enregistrement)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | Non | fichier dans un dossier | ✅ | ✅ | ❌
_(en cas de re-run, le fichier est retéléchargé)_ | ⚠️
(plusieurs copies si lancé dans plusieurs dossiers) | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | oui | fichier dans un dossier | ✅ | ✅ | ⚠️
_(le fichier doit être mis en cache d'abord)_ | ❌
_(le fichier est dupliqué)_ | - -**Note:** si vous utilisez une machien Windows, vous devez activer le mode développeur ou lancer `huggingface_hub` en tant qu'administrateur pour activer les syymlinks. Consultez la section [limitations du cache](../guides/manage-cache#limitations) - -## Télécharger depuis le CLI - -Vous pouvez utiliser la commande `huggingface-cli download` depuis un terminal pour télécharger directement des -fichiers du Hub. En interne, cette commande utilise les même helpers [`hf_hub_download`] et [`snapshot_download`] -décrits ci-dessus et affiche le chemin renvoyé dans le terminal. - -```bash ->>> huggingface-cli download gpt2 config.json -/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json -``` - -Vous pouvez télécharger plusieurs fichiers d'un coup, ce qui affiche une barre de chargement et renvoie le chemin de -la snapshot dans lequel les fichiers sont localisés. - -```bash ->>> huggingface-cli download gpt2 config.json model.safetensors -Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s] -/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 -``` - -Pour plus de détails sur la commande download du CLI, veuillez consulter le [guide CLI](./cli#huggingface-cli-download). - -## Téléchargements plus rapides - -Si vous utilisez une machine avec une bande passante plus large, vous pouvez augmenter votre vitesse de téléchargement en utilisant [`hf_transfer`], -une librairie basée sur Rust développée pour accélérer le transfer de fichiers avec le Hub. Pour l'activer, installez le package (`pip install hf_transfer`) et définissez set `HF_HUB_ENABLE_HF_TRANSFER=1` en tant que variable d'environnement - - - -Les barres de chargement ne fonctionnent avec `hf_transfer` qu'à partir de la version `0.1.4`. Mettez à jour la version (`pip install -U hf_transfer`) -si vous comptez utiliser cette librairie. - - - - - -`hf_transfer` est un outil très puissant! Il a été testé et est prêt à être utilisé en production, mais il lui manque certaines 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). - - \ No newline at end of file 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/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() -``` diff --git a/docs/source/fr/guides/webhooks_server.md b/docs/source/fr/guides/webhooks_server.md deleted file mode 100644 index 250f0ac5b7..0000000000 --- a/docs/source/fr/guides/webhooks_server.md +++ /dev/null @@ -1,205 +0,0 @@ - - -# Serveurs Webhooks - -Les webhooks sont un pilier des fonctionnalités MLOps. Ils vous permettent de suivre tous les nouveaux -changements sur des dépôts spécifiques ou sur tous les dépôts appartenants à des utilisateurs/organisations que -vous voulez suivre. Ce guide vous expliquera comment utiliser `hugginface_hub` pour créer un serveur écoutant des -webhooks et le déployer sur un espacce. Il postule que vous êtes familier avec le concept de webhooks sur le Hub Hugging Face. -Pour en apprendre plus sur les webhooks, vous pouvez consulter le -[guide](https://huggingface.co/docs/hub/webhooks) d'abord. - -La classe de base que nous utiliserons dans ce guide est [`WebhooksServer`]. C'est une classe qui permet de configurer -facilement un serveur qui peut recevoir des webhooks du Hub Huggingface. Le serveur est basé sur une application -[Gradio](https://gradio.app/). Il a une interface pour afficher des instruction pour vous ou vos utilisateurs et une API -pour écouter les webhooks. - - - -Pour voir un exemple fonctionnel de serveur webhook, consultez le [space bot CI](https://huggingface.co/spaces/spaces-ci-bot/webhook). -C'est un space qui lance des environnements éphémères lorsqu'une pull request est ouverte sur un space. - - - - - -C'est une [fonctionnalité expérimentale](../package_reference/environment_variables#hfhubdisableexperimentalwarning), -ce qui signifie que nous travaillons toujours sur l'amélioration de l'API. De nouveaux changement pourront être introduit -dans les future sans avertissement préalable. Assurez vous d'épingler la version d'`hugginface_hub` dans vos requirements. - - - - -## Créer un endpoint - -Implémenter un endpoint webhook est aussi facile que d'ajouter des décorateurs à une fonction. Voyons un premier -exemple afin de clarifier les concepts principaux: - -```python -# app.py -from huggingface_hub import webhook_endpoint, WebhookPayload - -@webhook_endpoint -async def trigger_training(payload: WebhookPayload) -> None: - if payload.repo.type == "dataset" and payload.event.action == "update": - # Lance une tâche d'entrainement si votre dataset est mis à jour - ... -``` - -Enregistrez ce snippet de code dans un fichier appelé `'app.py'` et lancez le avec `'python app.py'`. Vous devriez -voir un message de ce type: - -```text -Webhook secret is not defined. This means your webhook endpoints will be open to everyone. -To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: - `app = WebhooksServer(webhook_secret='my_secret', ...)` -For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret. -Running on local URL: http://127.0.0.1:7860 -Running on public URL: https://1fadb0f52d8bf825fc.gradio.live - -This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces - -Webhooks are correctly setup and ready to use: - - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training -Go to https://huggingface.co/settings/webhooks to setup your webhooks. -``` - -Bien joué! Vous venez de créer un serveur webhook! Décomposons ce qui vient de se passer exactement: - -1. En décorant une fonction avec [`webhook_endpoint`], un objet [`WebhooksServer`] a été créé en arrière plan. -Comme vous pouvez le voir, ce serveur est une application Gradio qui tourne sur http://127.0.0.1:7860. Si vous ouvrez -cet URL dans votre navigateur, vous verez une page d'accueil avec des informations sur les webhooks en question. -2. En arrière plan, une application Gradio n'est rien de plus qu'un serveur FastAPI . Une nouvelle route POST `/webhooks/trigger_training` -y a été ajoutée. C'est cette route qui écoutera les webhooks et lancera la fonction `trigger_training` lors de son activation. -FastAPI parsera automatiquement le paquet et le passera à la fonction en tant qu'objet [`WebhookPayload`]. C'est un objet -`pydantic` qui contient toutes les informations sur l'événement qui a activé le webhook. -3. L'application Gradio a aussi ouvert un tunnel pour recevoir des requêtes d'internet. C'est la partie intéressante: -vous pouvez configurer un webhooj sur https://huggingface.co/settings/webhooks qui pointe vers votre machine. C'est utile -pour debugger votre serveur webhook et rapidement itérer avant de le déployer dans un space. -4. Enfin, les logs vous disent aussi que votre serveur n'est pas sécurisé par un secret. Ce n'est pas problématique pour -le debugging en local mais c'est à garder dans un coin de la tête pour plus tard. - - - -Par défaut, le serveur est lancé à la fin de votre script. Si vous l'utilisez dans un notebook, vous pouvez lancer serveur -manuellement en appelant `decorated_function.run()`. Vu qu'un unique serveur est utilisé, vous aurez uniquement besoin de -lancer le serveur une fois même si vous avez plusieurs endpoints. - - - - -## Configurer un webhook - -Maintenant que vous avez un serveur webhook qui tourne, vous aurez surement besoin de configure un webhook -pour commencer à recevoir des messages. Allez sur https://huggingface.co/settings/webhooks, cliquez sur -"Ajouter un nouveau webhook" et configurez votre webhook. Définissez les dépôts cibles que vous voulez -surveiller et l'URL du webhook, ici `https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training`. - -
- -
- -Et voilà! Vous pouvez maintenant activer cce webhook en mettant à jour le dépôt cible (i.e. push un commit). Consultez -la table d'activité de votre webhook pour voir les événements passés. Maintenant que vous avez un setup qui fonctionne, -vous pouvez le tester et itérer rapidement. Si vous modifiez votre code et relancez le serveur, votre URL public pourrait -changer. Assurez vous de mettre à jour la configuration du webhook dans le Hub si besoin. - -## Déployer vers un space - -Maintenant que vous avez un serveur webhook fonctionnel, le but est de le déployer sur un space. Allez sur -https://huggingface.co/new-space pour créer un space. Donnez lui un nom, sélectionnez le SDK Gradio et cliquer sur -"Créer un space" (ou "Create Space" en anglais). Uploadez votre code dans le space dans un fichier appelé `app.py`. -Votre space sera lancé automatiquement! Pour plus de détails sur les spaces, consultez ce [guide](https://huggingface.co/docs/hub/spaces-overview). - -Votre serveur webhook tourne maintenant sur un space public. Dans la plupart de cas, vous aurez besoin de le sécuriser -avec un secret. Allez dans les paramètres de votre space > Section "Repository secrets" > "Add a secret". Définissez -la variable d'environnement `WEBHOOK_SECRET` en choisissant la valeur que vous voulez. Retournez dans les -[réglages webhooks](https://huggingface.co/settings/webhooks) et définissez le secret dans la configuration du webhook. -Maintenant, seules les requêtes avec le bon secret seront acceptées par votre serveur. - -Et c'est tout! Votre space est maintenant prêt à recevoir des webhooks du Hub. Gardez à l'esprit que si vous faites -tourner le space sur le hardware gratuit 'cpu-basic', il sera éteint après 48 heures d'inactivité. Si vous avez besoin d'un -space permanent, vous devriez peut-être considérer l'amélioration vers un [hardware amélioré](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs). - -## Utilisation avancée - -Le guide ci dessus expliquait la manière la plus rapide d'initialiser un [`WebhookServer`]. Dans cette section, nous verrons -comment le personnaliser plus en détails. - -### Endpoints multilpes - -Vous pouvez avoir plusieurs endpoints sur le même serveur. Par exemple, vous aurez peut-être envie d'avoir un endpoint -qui lance un entrainement de modèle et un autre qui lance une évaluation de modèle. Vous pouvez faire ça en ajoutant -plusieurs décorateurs `@webhook_endpoint`: - -```python -# app.py -from huggingface_hub import webhook_endpoint, WebhookPayload - -@webhook_endpoint -async def trigger_training(payload: WebhookPayload) -> None: - if payload.repo.type == "dataset" and payload.event.action == "update": - # Lance une tâche d'entrainement si votre dataset est mis à jour - ... - -@webhook_endpoint -async def trigger_evaluation(payload: WebhookPayload) -> None: - if payload.repo.type == "model" and payload.event.action == "update": - # Lance un tâche d'évaluation si un modèle est mis à jour - ... -``` - -Ce qui créera deux endpoints: - -```text -(...) -Webhooks are correctly setup and ready to use: - - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training - - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation -``` - -### Serveur personnalisé - -Pour plus de flexibilité, vous pouvez aussi créer un objet [`WebhooksServer`] directement. C'est utile si vous -voulez customiser la page d'acceuil de votre serveur. Vous pouvez le faire en passant une [UI Gradio](https://gradio.app/docs/#blocks) -qui va overwrite linterface par défaut. Par exemple, vous pouvez ajouter des instructions pour vos utilisateurs -ou ajouter un formulaire pour avtiver les webhooks manuellement. Lors de la création d'un [`WebhooksServer`], vous -pouvez créer de nouveaux webhooks en utilisant le décorateur [`~WebhooksServer.add_webhook`]. - -Here is a complete example: - -```python -import gradio as gr -from fastapi import Request -from huggingface_hub import WebhooksServer, WebhookPayload - -# 1. Déifnition de l'interface -with gr.Blocks() as ui: - ... - -# 2. Création d'un WebhooksServer avec une interface personnalisée et un secret -app = WebhooksServer(ui=ui, webhook_secret="my_secret_key") - -# 3. Ajout d'un webhook avec un nom explicite -@app.add_webhook("/say_hello") -async def hello(payload: WebhookPayload): - return {"message": "hello"} - -# 4. Ajout d'un webhook avec un nom implicite -@app.add_webhook -async def goodbye(payload: WebhookPayload): - return {"message": "goodbye"} - -# 5. Lancement du serveur (optionnel) -app.run() -``` - -1. Nous définissons une interface personnalisée en utilisant des block Gradio. Cette interface sera affichée -sur la page d'accueil du serveur. -2. Nous créons un objet [`WebhooksServer`] avec une interface personnalisée et un secret. Le secret est optionnel et -peut être définit avec la variable d'environnement `WEBHOOK_SECRET`. -3. Nous créons un webhook avec un nom explicite. Ceci créera un endpoint à `/webhooks/say_hello`. -4. Nous créons un webhook avec un nom implicite. Ceci créera un endpoint à `/webhoojs/goodbye`. -5. Nous lançons le serveur. C'est optionnel car votre serveur sera automatiquement lancé à la fin du script. \ No newline at end of file From 44f2734c6a47d01d7be25cf4c1435723b18add30 Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Sat, 8 Jun 2024 00:27:55 +0200 Subject: [PATCH 088/129] Deleted files --- docs/source/fr/guides/cli.md | 478 --------------- docs/source/fr/guides/collections.md | 230 ------- docs/source/fr/guides/community.md | 153 ----- docs/source/fr/guides/download.md | 208 ------- docs/source/fr/guides/hf_file_system.md | 110 ---- docs/source/fr/guides/inference.md | 344 ----------- docs/source/fr/guides/inference_endpoints.md | 261 -------- docs/source/fr/guides/manage-cache.md | 569 ------------------ docs/source/fr/guides/manage-spaces.md | 379 ------------ docs/source/fr/guides/model-cards.md | 373 ------------ docs/source/fr/guides/overview.md | 131 ---- docs/source/fr/guides/repository.md | 248 -------- docs/source/fr/guides/search.md | 69 --- docs/source/fr/guides/upload.md | 596 ------------------- docs/source/fr/guides/webhooks_server.md | 205 ------- 15 files changed, 4354 deletions(-) delete mode 100644 docs/source/fr/guides/cli.md delete mode 100644 docs/source/fr/guides/collections.md delete mode 100644 docs/source/fr/guides/community.md delete mode 100644 docs/source/fr/guides/download.md delete mode 100644 docs/source/fr/guides/hf_file_system.md delete mode 100644 docs/source/fr/guides/inference.md delete mode 100644 docs/source/fr/guides/inference_endpoints.md delete mode 100644 docs/source/fr/guides/manage-cache.md delete mode 100644 docs/source/fr/guides/manage-spaces.md delete mode 100644 docs/source/fr/guides/model-cards.md delete mode 100644 docs/source/fr/guides/overview.md delete mode 100644 docs/source/fr/guides/repository.md delete mode 100644 docs/source/fr/guides/search.md delete mode 100644 docs/source/fr/guides/upload.md delete mode 100644 docs/source/fr/guides/webhooks_server.md 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/download.md b/docs/source/fr/guides/download.md deleted file mode 100644 index 9dae248d92..0000000000 --- a/docs/source/fr/guides/download.md +++ /dev/null @@ -1,208 +0,0 @@ - - -# Télécharger des fichiers du Hub - -La librairie `huggingface_hub` fournit des fonctions pour télécharger des fichiers depuis -les dépôts stockés sur le Hub. Vous pouvez utiliser ces fonctions directement ou les intégrer -dans votre propre librairie, pour rendre l'intéraction entre vos utilisateurs et le Hub -plus simple. Ce guide vous montrera comment: - -* Télécharger et mettre en cache un fichier -* Télécharger et mettre en cache un dépôt entier -* Télécharger des fichiers dans un dossier local - -## Télécharger un fichier - -La fonction [`hf_hub_download`] est la fonction principale pour télécharger des fichiers du Hub. -Elle télécharge le fichier, le met en cache sur le disque (en prenant en compte les versions) -et retourne le chemin vers le fichier local téléchargé. - - - -Le chemin retourné est un pointeur vers le cache local HF. Par conséquent, il est important de ne pas modifier le fichier -pour éviter de corrompre le cache. Si vous voulez en apprendre plus sur la manière dont les fichiers sont mis en cache, -consultez notre [guide dédié au cache](./manage-cache). - - - -### Télécharger la dernière version - -Sélectionnez le fichier à télécharger en utilisant les paramètres `repo_id`, `repo_type` et `filename`. Par défaut, -le fichier sera considéré comme appartenant à un dépôt contenant des objets de type `model`. - -```python ->>> from huggingface_hub import hf_hub_download ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") -'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' - -# Télécharge un dataset ->>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") -'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' -``` - -### Télécharger une version spécifique - -Par défaut, la dernière version de la branche `main` est téléchargée. Cependant, dans certains cas, vous aurez besoin -de télécharger un fichier ayant une version particulière (i.e. d'une branche spécifique, une pull request, un tag, -ou un hash de commit). -Pour ce faire, utilisez le paramètre `revision`: - -```python -# Télécharge à partir du tag `v1.0` ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") - -# Télécharge à partir de la branche `test-branch` ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") - -# Télécharge à partir de la pull request #3 ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") - -# Télécharge à partir d'un hash de commit spécifique ->>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") -``` - -**Note:** Lorsque vous utilisez le hash de commit, vous devez renseigner le hash complet et pas le hash de commit à 7 caractères. - -### Générer un URL de téléchargement - -Si vous voulez générer l'URL utilisé pour télécharger un fichier depuis un dépôt, vous pouvez utiliser [`hf_hub_url`] -qui renvoie un URL. Notez que cette méthode est utilisée en arrière plan par [`hf_hub_download`]. - -## Télécharger un dépôt entier - -[`snapshot_download`] télécharge un dépôt entier à une révision donnée. Cette méthode utilise en arrière-plan -[`hf_hub_download`] ce qui signifie que tous les fichiers téléchargés sont aussi mis en cache sur votre disque en local. -Les téléchargements sont faits en parallèle pour rendre le processus plus rapide. - -Pour télécharger un dépôt entier, passez simplement le `repo_id` et le `repo_type`: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp") -'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' - -# Ou pour un dataset ->>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") -'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' -``` - -[`snapshot_download`] télécharge la dernière révision par défaut. Si vous voulez une révision spécifique, utilisez -le paramètre `revision`: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") -``` - -### Filtrer les fichiers à télécharger - -[`snapshot_download`] offre une manière simple de télécharger un dépôt. Cependant, vous ne voudrez peut être pas -télécharger tout le contenu d'un dépôt à chaque fois. Par exemple, vous n'aurez peut-être pas envie de télécharger -tous les fichiers `.bin` si vous savez que vous utiliserez uniquement les poids du `.safetensors`. Vous pouvez -faire ceci en utilisant les paramètres `allow_patterns` et `ignore_patterns`. - -Ces paramètres acceptent un pattern ou une liste de patterns. Les patterns sont des wildcards standards, comme précisé -[ici](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). Le matching de pattern utilise [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). - -Par exemple, vous pouvez utiliser `allow_patterns` pour ne télécharger que les fichiers de configuration JSON: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json") -``` - -A l'opposé, `ignore_patterns` empêche certains fichiers d'être téléchargés. L'exemple -suivant ignore les fichiers ayant pour extension `.msgpack` et `.h5`: - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"]) -``` - -Enfin, vous pouvez combiner les deux pour filtrer avec précision vos téléchargements. voici un exemple pour télécharger -tous les fichiers en .md et en .json à l'exception de `vocab.json` - -```python ->>> from huggingface_hub import snapshot_download ->>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json") -``` - -## Télécharger un ou plusieurs fichier(s) vers un dossier local - -La manière recommandée (et utilisée par défaut) pour télécharger des fichiers depuis les Hub est d'utiliser -le [cache-system](./manage-cache). Vous pouvez définir le chemin vers votre cache en définissant le -paramètre `cache_dir` (dans [`hf_hub_download`] et [`snapshot_download`]). - -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 une pratique utile pour créer un workflow plus proche de ce qu'on peut retrouver avec les commande `git`. Vous -pouvez faire ceci en utilisant les paramètres `local_dir` et `local_dir_use_symlinks`: -- `local_dir` doit être un chemin vers un dossier de votre système. Les fichiers téléchargés garderont la même structure -de fichier que dans le dépôt. Par exemple, si `filename="data/train.csv"` et `local_dir="path/to/folder"`, alors le -chemin renvoyé sera `"path/to/folder/data/train.csv"`. -- `local_dir_use_symlinks` renseigne comment le fichier doit être enregistré sur votre dossier local. - - Le comportement par défaut (`"auto"`), dupliquera les fichiers peu volumineux (<5MB) et utilisera les symlinks pour - les fichiers plus gros. Les symlinks permettent d'optimiser à la fois la bande passante et l'utilisation du disque. - Cependant, éditer manuellement un fichier sous symlink pourrait corrompre le cache, d'où la duplication pour des - petits fichiers. Le seuil de 5MB peut être configuré avec la variable d'environnement`HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD`. - - Si `local_dir_use_symlinks=True` est passé, alors tous les fichiers seront sous symlink pour une utilisation - optimal de l'espace disque. C'est par exemple utile lors du téléchargement d'un dataset très volumineux contenant - des milliers de petits fichiers. - - Enfin, si vous ne voulez pas utiliser de symlink du tout, vous pouvez les désactier (`local_dir_use_symlinks=False`). - Le chemin du cache sera toujours utilisé afin de vérifier si le fichier est déjà en cache ou pas. Si ce dernier - n'est pas déjà en cache, il sera téléchargé et déplacé directement vers le chemin local. Ce qui signifie que si - vous avez besoin de le réutiliser ailleurs, il sera **retéléchargé** - -Voici une table qui résume les différentes options pour vous aider à choisir les paramètres qui collent le mieux à votre situation. - - -| Paramètre | Fichier déjà en cahce | Chemin renvoyé | Peut-on lire le chemin | Pouvez vous sauvegarder le chemin | Bande passante optimisée | Utilisation du disque optimisée | -|---|:---:|:---:|:---:|:---:|:---:|:---:| -| `local_dir=None` | | symlink en cache | ✅ | ❌
_(sauvegarder corromprait le cache)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | fichier ou symlink dans un dossier | ✅ | ✅ _(pour les petits fichiers)_
⚠️ _(pour les gros fichiers, ne resolve pas le path avant l'enregistrement)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | symlink dans un dossier | ✅ | ⚠️
_(ne resolve pas le paht avant l'enregistrement)_ | ✅ | ✅ | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | Non | fichier dans un dossier | ✅ | ✅ | ❌
_(en cas de re-run, le fichier est retéléchargé)_ | ⚠️
(plusieurs copies si lancé dans plusieurs dossiers) | -| `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | oui | fichier dans un dossier | ✅ | ✅ | ⚠️
_(le fichier doit être mis en cache d'abord)_ | ❌
_(le fichier est dupliqué)_ | - -**Note:** si vous utilisez une machien Windows, vous devez activer le mode développeur ou lancer `huggingface_hub` en tant qu'administrateur pour activer les syymlinks. Consultez la section [limitations du cache](../guides/manage-cache#limitations) - -## Télécharger depuis le CLI - -Vous pouvez utiliser la commande `huggingface-cli download` depuis un terminal pour télécharger directement des -fichiers du Hub. En interne, cette commande utilise les même helpers [`hf_hub_download`] et [`snapshot_download`] -décrits ci-dessus et affiche le chemin renvoyé dans le terminal. - -```bash ->>> huggingface-cli download gpt2 config.json -/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json -``` - -Vous pouvez télécharger plusieurs fichiers d'un coup, ce qui affiche une barre de chargement et renvoie le chemin de -la snapshot dans lequel les fichiers sont localisés. - -```bash ->>> huggingface-cli download gpt2 config.json model.safetensors -Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s] -/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 -``` - -Pour plus de détails sur la commande download du CLI, veuillez consulter le [guide CLI](./cli#huggingface-cli-download). - -## Téléchargements plus rapides - -Si vous utilisez une machine avec une bande passante plus large, vous pouvez augmenter votre vitesse de téléchargement en utilisant [`hf_transfer`], -une librairie basée sur Rust développée pour accélérer le transfer de fichiers avec le Hub. Pour l'activer, installez le package (`pip install hf_transfer`) et définissez set `HF_HUB_ENABLE_HF_TRANSFER=1` en tant que variable d'environnement - - - -Les barres de chargement ne fonctionnent avec `hf_transfer` qu'à partir de la version `0.1.4`. Mettez à jour la version (`pip install -U hf_transfer`) -si vous comptez utiliser cette librairie. - - - - - -`hf_transfer` est un outil très puissant! Il a été testé et est prêt à être utilisé en production, mais il lui manque certaines 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). - - \ No newline at end of file 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/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() -``` diff --git a/docs/source/fr/guides/webhooks_server.md b/docs/source/fr/guides/webhooks_server.md deleted file mode 100644 index 250f0ac5b7..0000000000 --- a/docs/source/fr/guides/webhooks_server.md +++ /dev/null @@ -1,205 +0,0 @@ - - -# Serveurs Webhooks - -Les webhooks sont un pilier des fonctionnalités MLOps. Ils vous permettent de suivre tous les nouveaux -changements sur des dépôts spécifiques ou sur tous les dépôts appartenants à des utilisateurs/organisations que -vous voulez suivre. Ce guide vous expliquera comment utiliser `hugginface_hub` pour créer un serveur écoutant des -webhooks et le déployer sur un espacce. Il postule que vous êtes familier avec le concept de webhooks sur le Hub Hugging Face. -Pour en apprendre plus sur les webhooks, vous pouvez consulter le -[guide](https://huggingface.co/docs/hub/webhooks) d'abord. - -La classe de base que nous utiliserons dans ce guide est [`WebhooksServer`]. C'est une classe qui permet de configurer -facilement un serveur qui peut recevoir des webhooks du Hub Huggingface. Le serveur est basé sur une application -[Gradio](https://gradio.app/). Il a une interface pour afficher des instruction pour vous ou vos utilisateurs et une API -pour écouter les webhooks. - - - -Pour voir un exemple fonctionnel de serveur webhook, consultez le [space bot CI](https://huggingface.co/spaces/spaces-ci-bot/webhook). -C'est un space qui lance des environnements éphémères lorsqu'une pull request est ouverte sur un space. - - - - - -C'est une [fonctionnalité expérimentale](../package_reference/environment_variables#hfhubdisableexperimentalwarning), -ce qui signifie que nous travaillons toujours sur l'amélioration de l'API. De nouveaux changement pourront être introduit -dans les future sans avertissement préalable. Assurez vous d'épingler la version d'`hugginface_hub` dans vos requirements. - - - - -## Créer un endpoint - -Implémenter un endpoint webhook est aussi facile que d'ajouter des décorateurs à une fonction. Voyons un premier -exemple afin de clarifier les concepts principaux: - -```python -# app.py -from huggingface_hub import webhook_endpoint, WebhookPayload - -@webhook_endpoint -async def trigger_training(payload: WebhookPayload) -> None: - if payload.repo.type == "dataset" and payload.event.action == "update": - # Lance une tâche d'entrainement si votre dataset est mis à jour - ... -``` - -Enregistrez ce snippet de code dans un fichier appelé `'app.py'` et lancez le avec `'python app.py'`. Vous devriez -voir un message de ce type: - -```text -Webhook secret is not defined. This means your webhook endpoints will be open to everyone. -To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: - `app = WebhooksServer(webhook_secret='my_secret', ...)` -For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret. -Running on local URL: http://127.0.0.1:7860 -Running on public URL: https://1fadb0f52d8bf825fc.gradio.live - -This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces - -Webhooks are correctly setup and ready to use: - - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training -Go to https://huggingface.co/settings/webhooks to setup your webhooks. -``` - -Bien joué! Vous venez de créer un serveur webhook! Décomposons ce qui vient de se passer exactement: - -1. En décorant une fonction avec [`webhook_endpoint`], un objet [`WebhooksServer`] a été créé en arrière plan. -Comme vous pouvez le voir, ce serveur est une application Gradio qui tourne sur http://127.0.0.1:7860. Si vous ouvrez -cet URL dans votre navigateur, vous verez une page d'accueil avec des informations sur les webhooks en question. -2. En arrière plan, une application Gradio n'est rien de plus qu'un serveur FastAPI . Une nouvelle route POST `/webhooks/trigger_training` -y a été ajoutée. C'est cette route qui écoutera les webhooks et lancera la fonction `trigger_training` lors de son activation. -FastAPI parsera automatiquement le paquet et le passera à la fonction en tant qu'objet [`WebhookPayload`]. C'est un objet -`pydantic` qui contient toutes les informations sur l'événement qui a activé le webhook. -3. L'application Gradio a aussi ouvert un tunnel pour recevoir des requêtes d'internet. C'est la partie intéressante: -vous pouvez configurer un webhooj sur https://huggingface.co/settings/webhooks qui pointe vers votre machine. C'est utile -pour debugger votre serveur webhook et rapidement itérer avant de le déployer dans un space. -4. Enfin, les logs vous disent aussi que votre serveur n'est pas sécurisé par un secret. Ce n'est pas problématique pour -le debugging en local mais c'est à garder dans un coin de la tête pour plus tard. - - - -Par défaut, le serveur est lancé à la fin de votre script. Si vous l'utilisez dans un notebook, vous pouvez lancer serveur -manuellement en appelant `decorated_function.run()`. Vu qu'un unique serveur est utilisé, vous aurez uniquement besoin de -lancer le serveur une fois même si vous avez plusieurs endpoints. - - - - -## Configurer un webhook - -Maintenant que vous avez un serveur webhook qui tourne, vous aurez surement besoin de configure un webhook -pour commencer à recevoir des messages. Allez sur https://huggingface.co/settings/webhooks, cliquez sur -"Ajouter un nouveau webhook" et configurez votre webhook. Définissez les dépôts cibles que vous voulez -surveiller et l'URL du webhook, ici `https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training`. - -
- -
- -Et voilà! Vous pouvez maintenant activer cce webhook en mettant à jour le dépôt cible (i.e. push un commit). Consultez -la table d'activité de votre webhook pour voir les événements passés. Maintenant que vous avez un setup qui fonctionne, -vous pouvez le tester et itérer rapidement. Si vous modifiez votre code et relancez le serveur, votre URL public pourrait -changer. Assurez vous de mettre à jour la configuration du webhook dans le Hub si besoin. - -## Déployer vers un space - -Maintenant que vous avez un serveur webhook fonctionnel, le but est de le déployer sur un space. Allez sur -https://huggingface.co/new-space pour créer un space. Donnez lui un nom, sélectionnez le SDK Gradio et cliquer sur -"Créer un space" (ou "Create Space" en anglais). Uploadez votre code dans le space dans un fichier appelé `app.py`. -Votre space sera lancé automatiquement! Pour plus de détails sur les spaces, consultez ce [guide](https://huggingface.co/docs/hub/spaces-overview). - -Votre serveur webhook tourne maintenant sur un space public. Dans la plupart de cas, vous aurez besoin de le sécuriser -avec un secret. Allez dans les paramètres de votre space > Section "Repository secrets" > "Add a secret". Définissez -la variable d'environnement `WEBHOOK_SECRET` en choisissant la valeur que vous voulez. Retournez dans les -[réglages webhooks](https://huggingface.co/settings/webhooks) et définissez le secret dans la configuration du webhook. -Maintenant, seules les requêtes avec le bon secret seront acceptées par votre serveur. - -Et c'est tout! Votre space est maintenant prêt à recevoir des webhooks du Hub. Gardez à l'esprit que si vous faites -tourner le space sur le hardware gratuit 'cpu-basic', il sera éteint après 48 heures d'inactivité. Si vous avez besoin d'un -space permanent, vous devriez peut-être considérer l'amélioration vers un [hardware amélioré](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs). - -## Utilisation avancée - -Le guide ci dessus expliquait la manière la plus rapide d'initialiser un [`WebhookServer`]. Dans cette section, nous verrons -comment le personnaliser plus en détails. - -### Endpoints multilpes - -Vous pouvez avoir plusieurs endpoints sur le même serveur. Par exemple, vous aurez peut-être envie d'avoir un endpoint -qui lance un entrainement de modèle et un autre qui lance une évaluation de modèle. Vous pouvez faire ça en ajoutant -plusieurs décorateurs `@webhook_endpoint`: - -```python -# app.py -from huggingface_hub import webhook_endpoint, WebhookPayload - -@webhook_endpoint -async def trigger_training(payload: WebhookPayload) -> None: - if payload.repo.type == "dataset" and payload.event.action == "update": - # Lance une tâche d'entrainement si votre dataset est mis à jour - ... - -@webhook_endpoint -async def trigger_evaluation(payload: WebhookPayload) -> None: - if payload.repo.type == "model" and payload.event.action == "update": - # Lance un tâche d'évaluation si un modèle est mis à jour - ... -``` - -Ce qui créera deux endpoints: - -```text -(...) -Webhooks are correctly setup and ready to use: - - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training - - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation -``` - -### Serveur personnalisé - -Pour plus de flexibilité, vous pouvez aussi créer un objet [`WebhooksServer`] directement. C'est utile si vous -voulez customiser la page d'acceuil de votre serveur. Vous pouvez le faire en passant une [UI Gradio](https://gradio.app/docs/#blocks) -qui va overwrite linterface par défaut. Par exemple, vous pouvez ajouter des instructions pour vos utilisateurs -ou ajouter un formulaire pour avtiver les webhooks manuellement. Lors de la création d'un [`WebhooksServer`], vous -pouvez créer de nouveaux webhooks en utilisant le décorateur [`~WebhooksServer.add_webhook`]. - -Here is a complete example: - -```python -import gradio as gr -from fastapi import Request -from huggingface_hub import WebhooksServer, WebhookPayload - -# 1. Déifnition de l'interface -with gr.Blocks() as ui: - ... - -# 2. Création d'un WebhooksServer avec une interface personnalisée et un secret -app = WebhooksServer(ui=ui, webhook_secret="my_secret_key") - -# 3. Ajout d'un webhook avec un nom explicite -@app.add_webhook("/say_hello") -async def hello(payload: WebhookPayload): - return {"message": "hello"} - -# 4. Ajout d'un webhook avec un nom implicite -@app.add_webhook -async def goodbye(payload: WebhookPayload): - return {"message": "goodbye"} - -# 5. Lancement du serveur (optionnel) -app.run() -``` - -1. Nous définissons une interface personnalisée en utilisant des block Gradio. Cette interface sera affichée -sur la page d'accueil du serveur. -2. Nous créons un objet [`WebhooksServer`] avec une interface personnalisée et un secret. Le secret est optionnel et -peut être définit avec la variable d'environnement `WEBHOOK_SECRET`. -3. Nous créons un webhook avec un nom explicite. Ceci créera un endpoint à `/webhooks/say_hello`. -4. Nous créons un webhook avec un nom implicite. Ceci créera un endpoint à `/webhoojs/goodbye`. -5. Nous lançons le serveur. C'est optionnel car votre serveur sera automatiquement lancé à la fin du script. \ No newline at end of file From ce1d18fee692e68108d2fb297f17ff5dc4393e5e Mon Sep 17 00:00:00 2001 From: JibrilEl Date: Wed, 12 Jun 2024 16:08:34 +0200 Subject: [PATCH 089/129] Delete files --- docs/source/fr/package_reference/cache.md | 61 ---- docs/source/fr/package_reference/cards.md | 79 ----- .../fr/package_reference/collections.md | 25 -- docs/source/fr/package_reference/community.md | 34 --- .../environment_variables.md | 186 ------------ .../fr/package_reference/file_download.md | 38 --- docs/source/fr/package_reference/hf_api.md | 135 --------- .../fr/package_reference/hf_file_system.md | 16 -- .../fr/package_reference/inference_client.md | 112 -------- .../package_reference/inference_endpoints.md | 45 --- docs/source/fr/package_reference/login.md | 23 -- docs/source/fr/package_reference/mixins.md | 41 --- docs/source/fr/package_reference/overview.md | 7 - .../source/fr/package_reference/repository.md | 51 ---- .../fr/package_reference/space_runtime.md | 38 --- .../fr/package_reference/tensorboard.md | 20 -- docs/source/fr/package_reference/utilities.md | 271 ------------------ .../fr/package_reference/webhooks_server.md | 89 ------ 18 files changed, 1271 deletions(-) delete mode 100644 docs/source/fr/package_reference/cache.md delete mode 100644 docs/source/fr/package_reference/cards.md delete mode 100644 docs/source/fr/package_reference/collections.md delete mode 100644 docs/source/fr/package_reference/community.md delete mode 100644 docs/source/fr/package_reference/environment_variables.md delete mode 100644 docs/source/fr/package_reference/file_download.md delete mode 100644 docs/source/fr/package_reference/hf_api.md delete mode 100644 docs/source/fr/package_reference/hf_file_system.md delete mode 100644 docs/source/fr/package_reference/inference_client.md delete mode 100644 docs/source/fr/package_reference/inference_endpoints.md delete mode 100644 docs/source/fr/package_reference/login.md delete mode 100644 docs/source/fr/package_reference/mixins.md delete mode 100644 docs/source/fr/package_reference/overview.md delete mode 100644 docs/source/fr/package_reference/repository.md delete mode 100644 docs/source/fr/package_reference/space_runtime.md delete mode 100644 docs/source/fr/package_reference/tensorboard.md delete mode 100644 docs/source/fr/package_reference/utilities.md delete mode 100644 docs/source/fr/package_reference/webhooks_server.md diff --git a/docs/source/fr/package_reference/cache.md b/docs/source/fr/package_reference/cache.md deleted file mode 100644 index 502156ef66..0000000000 --- a/docs/source/fr/package_reference/cache.md +++ /dev/null @@ -1,61 +0,0 @@ - - -# Référence au système cache - -Le système de caching a été mis à jour dans la version v0.8.0 pour devenir un système -cache central et partagé par toutes les librairies dépendant du Hub. Consultez le -[guide système cache](../guides/manage-cache) pour une présentation détaillée du -cache à HF. - -## Les Helpers - -### try_to_load_from_cache - -[[autodoc]] huggingface_hub.try_to_load_from_cache - -### cached_assets_path - -[[autodoc]] huggingface_hub.cached_assets_path - -### scan_cache_dir - -[[autodoc]] huggingface_hub.scan_cache_dir - -## Structures de données - -Toutes les structures sont construites et retournées par [`scan_cache_dir`] -et sont immuables. - -### HFCacheInfo - -[[autodoc]] huggingface_hub.HFCacheInfo - -### CachedRepoInfo - -[[autodoc]] huggingface_hub.CachedRepoInfo - - size_on_disk_str - - refs - -### CachedRevisionInfo - -[[autodoc]] huggingface_hub.CachedRevisionInfo - - size_on_disk_str - - nb_files - -### CachedFileInfo - -[[autodoc]] huggingface_hub.CachedFileInfo - - size_on_disk_str - -### DeleteCacheStrategy - -[[autodoc]] huggingface_hub.DeleteCacheStrategy - - expected_freed_size_str - -## Exceptions - -### CorruptedCacheException - -[[autodoc]] huggingface_hub.CorruptedCacheException \ No newline at end of file diff --git a/docs/source/fr/package_reference/cards.md b/docs/source/fr/package_reference/cards.md deleted file mode 100644 index 98dfb25a8f..0000000000 --- a/docs/source/fr/package_reference/cards.md +++ /dev/null @@ -1,79 +0,0 @@ - - -# Cartes de dépôts - -La librairie `huggingface_hub` fournit une interface Python pour créer, partager et mettre à jour les -cartes de modèles ou de dataset. Consultez la [page de documentation dédiée](https://huggingface.co/docs/hub/models-cards) -Pour une vue plus profonde de ce que son les cartes de modèle sur le Hub et de comment elles fonctionnent -en arrière plan. Vous pouvez aussi consulter notre [guide de cartes de modèle](../how-to-model-cards) -pour avoir une intuition de la manière dont vous pourriez les utiliser dans vos projets. - -## Carte de dépôt - -L'objet `RepoCard` est la classe parent de [`ModelCard`], [`DatasetCard`] et `SpaceCard`. - -[[autodoc]] huggingface_hub.repocard.RepoCard - - __init__ - - all - -## Donnée de cartes - -L'objet [`CardData`] est la classe parent de [`ModelCardData`] et [`DatasetCardData`]. - -[[autodoc]] huggingface_hub.repocard_data.CardData - -## Cartes de modèles - -### ModelCard - -[[autodoc]] ModelCard - -### ModelCardData - -[[autodoc]] ModelCardData - -## Dataset Cards - -Dataset cards are also known as Data Cards in the ML Community. - -### DatasetCard - -[[autodoc]] DatasetCard - -### DatasetCardData - -[[autodoc]] DatasetCardData - -## Cartes de Space - -### SpaceCard - -[[autodoc]] SpaceCard - -### SpaceCardData - -[[autodoc]] SpaceCardData - -## Utilities - -### EvalResult - -[[autodoc]] EvalResult - -### model_index_to_eval_results - -[[autodoc]] huggingface_hub.repocard_data.model_index_to_eval_results - -### eval_results_to_model_index - -[[autodoc]] huggingface_hub.repocard_data.eval_results_to_model_index - -### metadata_eval_result - -[[autodoc]] huggingface_hub.repocard.metadata_eval_result - -### metadata_update - -[[autodoc]] huggingface_hub.repocard.metadata_update \ No newline at end of file diff --git a/docs/source/fr/package_reference/collections.md b/docs/source/fr/package_reference/collections.md deleted file mode 100644 index 5745528280..0000000000 --- a/docs/source/fr/package_reference/collections.md +++ /dev/null @@ -1,25 +0,0 @@ - - -# Gérer les collections - -Consultez la page de documentation [`HfApi`] pour les références des méthodes qui vous permettront -de gérer votre space sur le Hub. - -- Afficher le contenu d'une collection: [`get_collection`] -- Créer une nouvelle collection: [`create_collection`] -- Mettre à jour une collection: [`update_collection_metadata`] -- Supprimer une collection: [`delete_collection`] -- Ajouter un item à une collection: [`add_collection_item`] -- Mettre à jour un item dans une collection: [`update_collection_item`] -- Supprimer un item d'une collection: [`delete_collection_item`] - - -### Collection - -[[autodoc]] Collection - -### CollectionItem - -[[autodoc]] CollectionItem \ No newline at end of file diff --git a/docs/source/fr/package_reference/community.md b/docs/source/fr/package_reference/community.md deleted file mode 100644 index 38e9065ff8..0000000000 --- a/docs/source/fr/package_reference/community.md +++ /dev/null @@ -1,34 +0,0 @@ - - -# Interagir avec les dicussions et les pull requests - -Consultez la page de documentation [`HfApi`] pour les références des méthodes permettant l'intéraction -avec des pull requests et des discussions sur le Hub. - -- [`get_repo_discussions`] -- [`get_discussion_details`] -- [`create_discussion`] -- [`create_pull_request`] -- [`rename_discussion`] -- [`comment_discussion`] -- [`edit_discussion_comment`] -- [`change_discussion_status`] -- [`merge_pull_request`] - -## Structure des données - -[[autodoc]] Discussion - -[[autodoc]] DiscussionWithDetails - -[[autodoc]] DiscussionEvent - -[[autodoc]] DiscussionComment - -[[autodoc]] DiscussionStatusChange - -[[autodoc]] DiscussionCommit - -[[autodoc]] DiscussionTitleChange diff --git a/docs/source/fr/package_reference/environment_variables.md b/docs/source/fr/package_reference/environment_variables.md deleted file mode 100644 index ad76eeb227..0000000000 --- a/docs/source/fr/package_reference/environment_variables.md +++ /dev/null @@ -1,186 +0,0 @@ - - -# Variables d'environnement - -`huggingface_hub` peut être configuré en utilisant des variables d'environnement. - -Si vous n'êtes pas familier avec le principe de variable d'environnement, voici des -articles assez générique sur ces dernières [sur macOS et Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) -et sur [Windows](https://phoenixnap.com/kb/windows-set-environment-variable). - -Cette page vous guidera à travers toutes les variables d'environnement spécifiques à -`huggingface_hub` et leur signification. - -## Les variables génériques - -### HF_INFERENCE_ENDPOINT - -Pour configurer l'url de base de l'api d'inférence, vous aurez peut-être besoin de définir -cette variable si votre organisation pointe vers un gateway d'API plutôt que directement vers -l'API d'inférence. - -Par défaut, l'endpoint sera `"https://api-inference.huggingface.com"`. - -### HF_HOME - -Pour configurer le chemin vers lequel `huggingface_hub` enregistrera de la donnée par -défaut. En particulier, votre token d'authentification et le cache seront enregistrés -dans ce dossier. - -Par défaut, ce chemin sera `"~/.cache/huggingface"` sauf si [XDG_CACHE_HOME](#xdgcachehome) -est définie. - -### HF_HUB_CACHE - -Pour configurer le chemin vers lequels les dépôts du Hub seront mis en cache en local -(modèles, datasets et spaces). - -Par défaut, ce sera `"$HF_HOME/hub"` (i.e. `"~/.cache/huggingface/hub"` par défaut). - -### HF_ASSETS_CACHE - -Pour configurer le chemin vers lequel les [assets](../guides/manage-cache#caching-assets) créés -par des librairies seront mis en cache en local. Ces assets peuvent être de la donnée pré-traitée, -des fichiers téléchargés depuis GitHub, des logs,... - -Par défaut, le chemin sera `"$HF_HOME/assets"` (i.e. `"~/.cache/huggingface/assets"` par défaut). - -### HF_TOKEN - -Pour configurer le token d'authentification qui permet de vous authentifier sur le Hub. -Si définie, cette valeur écrasera le token enregistré sur la machine (dans `"$HF_HOME/token"`). - -Consultez [la référence aux connexions](../package_reference/login) pour plus de détails. - -### HF_HUB_VERBOSITY - -Définissez le niveau de verbosité du logger `huggingface_hub`. La variable doit -être choisie parmi `{"debug", "info", "warning", "error", "critical"}`. - -Par défaut, la variable sera `"warning"`. - -Pour plus de détails, consultez [la référence aux connexions](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity). - -### HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD - -Valeur entière définissant en dessous de quelle taille un fichier est considéré comme "petit". Lors du téléchargement -de fichiers vers un chemin local, les petits fichiers seront dupliqués pour faciliter l'expérience utilisateur là où -les fichiers plus gros n'auront qu'un symlink vers eux pour conserver de l'espace sur le disque. - -Pour plus de détails, consultez le [guide de téléchargement](../guides/download#download-files-to-local-folder). - -### HF_HUB_ETAG_TIMEOUT - -Valeur entière définissant le nombre de secondes pendant lesquelles il faut attendre la réponse du serveur lors de l'affichage des dernières metadonnées depuis un dépôt avant de télécharger un fichier. En cas de timeout, alors, par défaut, `huggingface_hub` se limitera aux fichiers en cache en local. Définir une valeur plus faible accélère le workflow pour des machines avec une connexion lente qui ont déjà des fichiers en cache. Une plus grande valeur garanti l'appel aux métadonnées pour réussir dans plus de cas. Par défaut, la valeur est de 10s. - -### HF_HUB_DOWNLOAD_TIMEOUT - -Valeur entière pour définir le nombre de secondes durant lesquelles il faut attendre la réponse du serveur lors du téléchargement d'un fichier. Si la requête tiemout, une TimeoutError sera levée. Définir une valeur grande est bénéfique sur une machine qui a une connexion lente. Une valeur plus faible fait échouer le process plus vite dans le cas d'un réseau complexe. Par défaut, la valeur est de 10s. - -## Valeures booléennes - -Les variables d'environnement suivantes attendes une valeur booléenne. La variable sera -considérées comme `True` si sa valeur fait partie de la liste`{"1", "ON", "YES", "TRUE"}`. -Toute autre valeur (ou undefined) sera considérée comme `False`. - -### HF_HUB_OFFLINE - -Si définie, aucun appel HTTP ne sera fait lors de l'ajout de fichiers. Seuls les fichiers -qui sont déjà en cache seront ajoutés. C'est utile si votre réseau est lent et que vous -vous en fichez d'avoir absolument la dernière version d'un fichier. - -**Note:** Même si la dernière version d'un fichier est en cache, l'appel de `hf_hub_download` -lancera quand même une requête HTTP pour vérifier qu'une nouvelle version est disponible. -Définir `HF_HUB_OFFLINE=1` évitera cet appel ce qui peut accélérer votre temps de chargement. - -### HF_HUB_DISABLE_IMPLICIT_TOKEN - -L'authentification n'est pas obligatoire pour toutes les requêtes vers le Hub. Par -exemple, demander des détails sur le modèle `"gpt2"` ne demande pas nécessairement -d'être authentifié. Cependant, si un utilisateur est [connecté](../package_reference/login), -le comportement par défaut sera de toujours envoyer le token pour faciliter l'expérience -utilisateur (cela évite d'avoir une erreur 401 Unauthorized) lors de l'accès de dépôt -privés ou protégé. Vous pouvez supprimer ce comportement en définissant `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. -Dans ce cas, le token ne sera envoyé que pour des appels de type "write-access" (par exemple, pour créer un commit). - -**Note:** supprimer l'envoi implicit de token peut avoir des effets secondaires bizarres. -Par exemple, si vous voulez lister tous les modèles sur le Hub, vos modèles privés ne -seront pas listés. Vous auriez besoin d'un argument explicite `token=True` dans votre -script. - -### HF_HUB_DISABLE_PROGRESS_BARS - -Pour les tâches longues, `huggingface_hub` affiche une bar de chargement par défaut (en utilisant tqdm). -Vous pouvez désactiver toutes les barres de progression d'un coup en définissant -`HF_HUB_DISABLE_PROGRESS_BARS=1`. - -### HF_HUB_DISABLE_SYMLINKS_WARNING - -Si vous avez une machine Windows, il est recommandé d'activer le mode développeur ou de -faire tourner `huggingface_hub` en mode admin. Sinon, `huggingface_hub` ne ser pas capable -de créer des symlinks dans votre système de cache. Vous serez capables d'exécuter n'importe -quel script, mais votre expérience utilisateur sera moins bonne vu que certains gros fichiers -pourraient être dupliqués sur votre disque dur. Un message d'avertissement vous préviendra -de ce type de comportement. Définissez `HF_HUB_DISABLE_SYMLINKS_WARNING=1`, pour désactiver -cet avertissement. - -Pour plus de détails, consultez [les limitations du cache](../guides/manage-cache#limitations). - -### HF_HUB_DISABLE_EXPERIMENTAL_WARNING - -Certaines fonctionnalités de `huggingface_hub` sont expérimentales, cela signfie que vous pouvez les utliiser mais -nous ne garantissons pas qu'elles seront maintenues plus tard. En particulier, nous mettrons peut-être à jour les -API ou le comportement de telles fonctionnalités sans aucun cycle de deprecation. Un message d'avertissement sera -affiché lorsque vous utilisez une fonctionnalités expérimentale pour vous l'indiquer. Si vous n'êtes pas dérangé par -le fait de devoir debug toute erreur potentielle liée à l'usage d'une fonctionnalité expérimentale, vous pouvez -définir `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` pour désactiver l'avertissement. - -Si vous utilisez une fonctoinnalité expérimental, faites le nous savoir! Votre retour peut nous aider à l'améliorer. - -### HF_HUB_DISABLE_TELEMETRY - -Par défaut, des données sont collectées par les librairies HF (`transformers`, `datasets`, `gradio`,..) pour gérer l'utilisation et les problèmes de débug et pour aider à définir les fonctionnalités prioritaires. Chaque librairie définit sa propre politique (i.e. les cas d'usage sur lesquels les données eront collectées), mais l'implémentation principale se passe dans `huggingface_hub` (consultez [`send_telemetry`]). - -Vous pouvez définir `HF_HUB_DISABLE_TELEMETRY=1` en tant que variable d'environnement pour désactiver la télémétrie. - -### HF_HUB_ENABLE_HF_TRANSFER - -Définissez cette valeur à `True` pour des upload et des téléchargements plus rapides depuis le Hub en utilisant `hf_transfer`. - -Par défaut, `huggingface_hub` utilise les fonctions basées sur Python `requests.get` et `requests.post`. Même si ces fonctions sont fiables et assez versatiles, elle pourrait ne pas être le choix le plus efficace pour les machines avec une bande passante large. [`hf_transfer`](https://github.com/huggingface/hf_transfer) est un package basé sur Rust développé pour maximiser la bande passante utilisée en divisant les gros fichier en des parties plus petites et les transférer toutes simultanément en utilisant plusieurs threads. Cette approche peut potentiellement doubler la vitesse de transfert. Pour utiliser `hf_transfer`, vous devez l'installer séparément [de PyPI](https://pypi.org/project/hf-transfer/) et définir `HF_HUB_ENABLE_HF_TRANSFER=1` en tant que variable d'environnement. - -N'oubliez pas que l'utilisation d'`hf_transfer` a certaines limitations. Vu qu'elle n'est pas purement basé sur Python, le debug d'erreurs peut s'avérer plus compliqué. De plus, `hf_transfer` n'est pas totues les fonctionnalités user-friendly telles que le téléchargement reprenables et les proxys. Ces omissions sont intentionnelles et permettent de maintenir la simplicité et la vitesse de la logique Rust. Par conséquent, `hf_transfer` n'est pas activée par défaut dans `huggingface_hub`. - -## Variables d'environnement deprecated - -Afin de standardiser toutes les variables d'environnement dans l'écosystème Hugging Face, certaines variable ont été marquée comme deprecated. Même si elle fonctionnent toujours, elles ne sont plus prioritaires par rapport à leur remplacements. La table suivante liste les variables d'environnement deprecated et leurs alternatives respectives: - - -| Variable deprecated | Alternative | -| --- | --- | -| `HUGGINGFACE_HUB_CACHE` | `HF_HUB_CACHE` | -| `HUGGINGFACE_ASSETS_CACHE` | `HF_ASSETS_CACHE` | -| `HUGGING_FACE_HUB_TOKEN` | `HF_TOKEN` | -| `HUGGINGFACE_HUB_VERBOSITY` | `HF_HUB_VERBOSITY` | - -## Depuis un outil extérieur - -Certaines variables d'environnement ne sont pas spécifiques à `huggingface_hub` mais sont tout de même prises en compte -lorsqu'elles sont définies. - -### NO_COLOR - -Valeur booléenne, lorsque définie à `True`, l'outil `huggingface-cli` n'affichera -aucune couleur ANSI. -Consultez [no-color.org](https://no-color.org/). - -### XDG_CACHE_HOME - -Utilisé uniqueemnt si `HF_HOME` n'est pas défini! - -C'est la manière par défaut de configurer l'endroit où [les données en cache non essentielles devraient être écrites](https://wiki.archlinux.org/title/XDG_Base_Directory) sur les machines linux. - -Si `HF_HOME` n'est pas définie, le chemin par défaut sera `"$XDG_CACHE_HOME/huggingface"` -aulieu de `"~/.cache/huggingface"`. diff --git a/docs/source/fr/package_reference/file_download.md b/docs/source/fr/package_reference/file_download.md deleted file mode 100644 index 97050065c6..0000000000 --- a/docs/source/fr/package_reference/file_download.md +++ /dev/null @@ -1,38 +0,0 @@ - - -# Téléchargement des fichiers - -## Télécharger un unique fichier - -### hf_hub_download - -[[autodoc]] huggingface_hub.hf_hub_download - -### hf_hub_url - -[[autodoc]] huggingface_hub.hf_hub_url - -## Télécharger un instantané du dépôt - -[[autodoc]] huggingface_hub.snapshot_download - -## Obtenir une métadonnée sur un fichier - -### get_hf_file_metadata - -[[autodoc]] huggingface_hub.get_hf_file_metadata - -### HfFileMetadata - -[[autodoc]] huggingface_hub.HfFileMetadata - -## Utilisation du cache - -Le méthodes affichées ci dessus sont faites pour fonctionner avec un système de cache -ce qui évite de retélécharger des fichiers. Le système de cache a été mis à jour dans -la version v0.8.0 afin d'être le système de cache central partagé dans toutes les -librairies dépendant du Hub. - -Consultez le [guide cache-system](../guides/manage-cache) pour une présentation détaillée du caching à HF. \ No newline at end of file diff --git a/docs/source/fr/package_reference/hf_api.md b/docs/source/fr/package_reference/hf_api.md deleted file mode 100644 index 8a90e20500..0000000000 --- a/docs/source/fr/package_reference/hf_api.md +++ /dev/null @@ -1,135 +0,0 @@ - - -# HfApi Client - -Ci dessous la documentation pour la classe `HfApi`, qui sert de wrapper Python pour l'API Hugging Face Hub. - -Toutes les méthodes de `HfApi` sont aussi accessibles depuis la racine du package directement. Les deux approches sont détaillées ci-dessous. - -Utiliser la méthode du chemin racine est plus direct mais la classe [`HfApi`] donne plus de flexibilité. -En particulier, vous pouvez mettre un token qui va être réutilisé dans tous les appels HTTP. C'est -différent de la commande `huggingface-cli login` ou [`login`] vu que le token n'est pas enregistré -sur la machine. Il est aussi possible de fournir un endpoint différent ou de configurer un user-agent -personnalisé. - -```python -from huggingface_hub import HfApi, list_models - -# Utilisez la méthode du chemin racine -models = list_models() - -# Ou configurez le client HfApi -hf_api = HfApi( - endpoint="https://huggingface.co", # Vous pouvez mettre un endpoint de Hub privéC. - token="hf_xxx", # Le token n'est pas sauvegardé sur la machine. -) -models = hf_api.list_models() -``` - -## HfApi - -[[autodoc]] HfApi - -[[autodoc]] plan_multi_commits - -## API Dataclasses - -### CommitInfo - -[[autodoc]] huggingface_hub.hf_api.CommitInfo - -### DatasetInfo - -[[autodoc]] huggingface_hub.hf_api.DatasetInfo - -### GitRefInfo - -[[autodoc]] huggingface_hub.hf_api.GitRefInfo - -### GitCommitInfo - -[[autodoc]] huggingface_hub.hf_api.GitCommitInfo - -### GitRefs - -[[autodoc]] huggingface_hub.hf_api.GitRefs - -### ModelInfo - -[[autodoc]] huggingface_hub.hf_api.ModelInfo - -### RepoSibling - -[[autodoc]] huggingface_hub.hf_api.RepoSibling - -### RepoFile - -[[autodoc]] huggingface_hub.hf_api.RepoFile - -### RepoUrl - -[[autodoc]] huggingface_hub.hf_api.RepoUrl - -### SafetensorsRepoMetadata - -[[autodoc]] huggingface_hub.utils.SafetensorsRepoMetadata - -### SafetensorsFileMetadata - -[[autodoc]] huggingface_hub.utils.SafetensorsFileMetadata - -### SpaceInfo - -[[autodoc]] huggingface_hub.hf_api.SpaceInfo - -### TensorInfo - -[[autodoc]] huggingface_hub.utils.TensorInfo - -### User - -[[autodoc]] huggingface_hub.hf_api.User - -### UserLikes - -[[autodoc]] huggingface_hub.hf_api.UserLikes - -## CommitOperation - -Ci dessous les valeurs supportés pour [`CommitOperation`]: - -[[autodoc]] CommitOperationAdd - -[[autodoc]] CommitOperationDelete - -[[autodoc]] CommitOperationCopy - -## CommitScheduler - -[[autodoc]] CommitScheduler - -## Token helper - -`huggingface_hub` garde en mémoire l'information d'authentification en local pour qu'il puisse être réutilisé -dans les méthodes suivantes. - -La librairie fait ceci en utilisant l'utilitaire [`HfFolder`], qui sauvegarde de la donnée -à la racine de l'utilisateur. - -[[autodoc]] HfFolder - -## Search helpers - -Certains helpers pour filtrer les dépôts sur le Hub sont disponibles dans le package -`huggingface_hub`. - -### DatasetFilter - -[[autodoc]] DatasetFilter - -### ModelFilter - -[[autodoc]] ModelFilter - diff --git a/docs/source/fr/package_reference/hf_file_system.md b/docs/source/fr/package_reference/hf_file_system.md deleted file mode 100644 index e36c6393fa..0000000000 --- a/docs/source/fr/package_reference/hf_file_system.md +++ /dev/null @@ -1,16 +0,0 @@ - - -# L'API FileSystem - -La classe `HfFileSystem` offre une interface Python pour le Hub Hugging Face basée sur [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/). - -## HfFileSystem - -`HfFileSystem` est basé sur [fsspec](https://filesystem-spec.readthedocs.io/en/latest/), donc cette classe est compatible avec la plupart des API offertes par fsspec. Pour plus de détails, consultez [notre guide](../guides/hf_file_system) et les [Références](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem) de l'API fsspec. - -[[autodoc]] HfFileSystem - - __init__ - - resolve_path - - ls diff --git a/docs/source/fr/package_reference/inference_client.md b/docs/source/fr/package_reference/inference_client.md deleted file mode 100644 index 8932918377..0000000000 --- a/docs/source/fr/package_reference/inference_client.md +++ /dev/null @@ -1,112 +0,0 @@ - - -# Inférence - -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`]. Consultez [ce guide](../guides/inference) pour plus -d'informations sur le mode d'utilisation. - -## Client d'inférence - -[[autodoc]] InferenceClient - -## Client d'inférence asynchrone - -Une version asychrone du client basée sur `asyncio` et `aihttp` est aussi fournie. -Pour l'utiliser, vous pouvez soit installer `aiohttp` directement ou utiliser l'extra `[inference]`: - -```sh -pip install --upgrade huggingface_hub[inference] -# or -# pip install aiohttp -``` - -[[autodoc]] AsyncInferenceClient - -## InferenceTimeoutError - -[[autodoc]] InferenceTimeoutError - -## Types retournés - -Pour la plupart des tâches, la valeur retournée a un type intégré (string, list, image...). Voici une liste de types plus complexes. - -### ClassificationOutput - -[[autodoc]] huggingface_hub.inference._types.ClassificationOutput - -### ConversationalOutputConversation - -[[autodoc]] huggingface_hub.inference._types.ConversationalOutputConversation - -### ConversationalOutput - -[[autodoc]] huggingface_hub.inference._types.ConversationalOutput - -### ImageSegmentationOutput - -[[autodoc]] huggingface_hub.inference._types.ImageSegmentationOutput - -### ModelStatus - -[[autodoc]] huggingface_hub.inference._common.ModelStatus - -### TokenClassificationOutput - -[[autodoc]] huggingface_hub.inference._types.TokenClassificationOutput - -### Types pour la génération de texte - -La tâche [`~InferenceClient.text_generation`] a un meilleur support que d'autres tâches dans `InferenceClient`. -Les inputs des utilisateurs et les outputs des serveurs sont validés en utilisant [Pydantic](https://docs.pydantic.dev/latest/) -si ce package est installé. Par conséquent, nous vous recommandons de l'installer (`pip install pydantic`) pour -une meilleure expérience. - -Vous pouvez trouver ci-dessous, les dataclasses utilisées pour valider des données et en particulier -[`~huggingface_hub.inference._text_generation.TextGenerationParameters`] (input) -[`~huggingface_hub.inference._text_generation.TextGenerationResponse`] (output) et -[`~huggingface_hub.inference._text_generation.TextGenerationStreamResponse`] (streaming output). - -[[autodoc]] huggingface_hub.inference._text_generation.TextGenerationParameters - -[[autodoc]] huggingface_hub.inference._text_generation.TextGenerationResponse - -[[autodoc]] huggingface_hub.inference._text_generation.TextGenerationStreamResponse - -[[autodoc]] huggingface_hub.inference._text_generation.InputToken - -[[autodoc]] huggingface_hub.inference._text_generation.Token - -[[autodoc]] huggingface_hub.inference._text_generation.FinishReason - -[[autodoc]] huggingface_hub.inference._text_generation.BestOfSequence - -[[autodoc]] huggingface_hub.inference._text_generation.Details - -[[autodoc]] huggingface_hub.inference._text_generation.StreamDetails - -## InferenceAPI - -[`InferenceAPI`] est la méthode historique pour appeler l'API d'inférence. L'interface est plus simpliste et -demande une conaissance des paramètres d'entrées et du format de sortie de chacune des tâches. Cette interface -ne peut pas se connecter à d'autres services tels que Inference Endpoints or AWS SageMaker. [`InferenceAPI`] sera -bientôt deprecated, ainsi, nous recommendons l'utilisation de [`InferenceClient`] quand c'est possible. -Consultez [ce guide](../guides/inference#legacy-inferenceapi-client) pour apprendre comment passer -d'[`InferenceAPI`] à [`InferenceClient`] dans vos scripts. - -[[autodoc]] InferenceApi - - __init__ - - __call__ - - all - diff --git a/docs/source/fr/package_reference/inference_endpoints.md b/docs/source/fr/package_reference/inference_endpoints.md deleted file mode 100644 index 5dd22808c7..0000000000 --- a/docs/source/fr/package_reference/inference_endpoints.md +++ /dev/null @@ -1,45 +0,0 @@ -# Inference Endpoints - -Inference Endpoints est une solution permettant de déployer facilement les modèles en production sur une infrastructure gérée par Hugging Face et capable d'autoscaling . Un Inference Endpoint peut être crée sur un modèle depuis le [Hub](https://huggingface.co/models). Cette page est -une référence pour l'intégration d'`huggingface_hub` avec Inference Endpoints. Pour plus d'informations à propos du produit Inference Endpoints, consultez la [documentation officielle](https://huggingface.co/docs/inference-endpoints/index). - - - -Consultez ce [guide](../guides/inference_endpoints) pour apprendre à utiliser `huggingface_hub` pour gérer votre Inference Enpoints depuis le code. - - - -Inference Endpoints peut être entièrement géré depuis une API. Les endpoints sont consultables via [Swagger](https://api.endpoints.huggingface.cloud/). -La classe [`InferenceEndpoint`] est un simple wrapper autour de cette API. - -## Méthodes - -Un sous ensemble des fonctionnalités de l'Inference Endpoint sont implémentées dans [`HfApi`]: - -- [`get_inference_endpoint`] et [`list_inference_endpoints`] pour obtenir de l'information sur vos Inference Endpoints -- [`create_inference_endpoint`], [`update_inference_endpoint`] et [`delete_inference_endpoint`] pour déployer et gérer les Inference Endpoints -- [`pause_inference_endpoint`] et [`resume_inference_endpoint`] pour mettre en pause et relancer un Inference Enpoint -- [`scale_to_zero_inference_endpoint`] pour scale à la main l'Inference Endpoint à 0 replicas - -## InferenceEndpoint - -La dataclass principale est [`InferenceEndpoint`]. Elle contient des informations sur un `InferenceEndpoint` déployé, notamment sa configuration et son -état actuel. Une fois déployé, vous pouvez faire des inférences sur l'enpoint en utilisant les propriétés [`InferenceEndpoint.client`] et [`InferenceEndpoint.async_client`] qui retournent respectivement un objet [`InferenceClient`] et [`AsyncInferenceClient`] - -[[autodoc]] InferenceEndpoint - - from_raw - - client - - async_client - - all - -## InferenceEndpointStatus - -[[autodoc]] InferenceEndpointStatus - -## InferenceEndpointType - -[[autodoc]] InferenceEndpointType - -## InferenceEndpointError - -[[autodoc]] InferenceEndpointError \ No newline at end of file diff --git a/docs/source/fr/package_reference/login.md b/docs/source/fr/package_reference/login.md deleted file mode 100644 index 2ebb7b70f1..0000000000 --- a/docs/source/fr/package_reference/login.md +++ /dev/null @@ -1,23 +0,0 @@ - - -# Login and logout - -La librairie `huggingface_hub` permet aux utilisateur de se connecter et déconnecter -votre machine au Hub par le code. -## login - -[[autodoc]] login - -## interpreter_login - -[[autodoc]] interpreter_login - -## notebook_login - -[[autodoc]] notebook_login - -## logout - -[[autodoc]] logout diff --git a/docs/source/fr/package_reference/mixins.md b/docs/source/fr/package_reference/mixins.md deleted file mode 100644 index 9762068a1e..0000000000 --- a/docs/source/fr/package_reference/mixins.md +++ /dev/null @@ -1,41 +0,0 @@ - - -# Mixins & méthodes de sérialisation - -## Mixins - -La librairie `huggingface_hub` offre une liste de mixins qui peuvent être utilisés en tant que classes parentes pour vos -objets, afin d'avoir des fonctions upload et de téléchargements simples. Consultez notre [guide d'intégration](../guides/integrations) -pour apprendre à intégrer n'importe quel framework ML avec le Hub. - -### Generic - -[[autodoc]] ModelHubMixin - - all - - _save_pretrained - - _from_pretrained - -### PyTorch - -[[autodoc]] PyTorchModelHubMixin - -### Keras - -[[autodoc]] KerasModelHubMixin - -[[autodoc]] from_pretrained_keras - -[[autodoc]] push_to_hub_keras - -[[autodoc]] save_pretrained_keras - -### Fastai - -[[autodoc]] from_pretrained_fastai - -[[autodoc]] push_to_hub_fastai - - - diff --git a/docs/source/fr/package_reference/overview.md b/docs/source/fr/package_reference/overview.md deleted file mode 100644 index c9f66d28c5..0000000000 --- a/docs/source/fr/package_reference/overview.md +++ /dev/null @@ -1,7 +0,0 @@ - - -# Vue d'ensemble - -Cette section contiens une description technique et exhaustive des classes `huggingface_hub` et des méthodes. \ No newline at end of file diff --git a/docs/source/fr/package_reference/repository.md b/docs/source/fr/package_reference/repository.md deleted file mode 100644 index c8ebc43581..0000000000 --- a/docs/source/fr/package_reference/repository.md +++ /dev/null @@ -1,51 +0,0 @@ - - -# Managing local and online repositories - -La classe `Repository` est un helper autour des commandes `git` et `git-lfs`. Elle offre des outils adaptés -à la gestion de dépôts qui peuvent être très volumineux. - -C'est l'outil recommandé dès que des opérations avec `git` sont faites, ou lorsque la collaboration sera un point -clef du dépôt. - -## The Repository class - -[[autodoc]] Repository - - __init__ - - current_branch - - all - -## Helper methods - -[[autodoc]] huggingface_hub.repository.is_git_repo - -[[autodoc]] huggingface_hub.repository.is_local_clone - -[[autodoc]] huggingface_hub.repository.is_tracked_with_lfs - -[[autodoc]] huggingface_hub.repository.is_git_ignored - -[[autodoc]] huggingface_hub.repository.files_to_be_staged - -[[autodoc]] huggingface_hub.repository.is_tracked_upstream - -[[autodoc]] huggingface_hub.repository.commits_to_push - -## Commandes asynchrones - -L'utilitaire `Repository` offre plusieurs méthodes qui peuvent tourner en asynchrone: -- `git_push` -- `git_pull` -- `push_to_hub` -- Le manager de contexte `commit` - -Regardez ci-dessous les utilities pour gérer ce genre de méthodes asynchrones. - -[[autodoc]] Repository - - commands_failed - - commands_in_progress - - wait_for_commands - -[[autodoc]] huggingface_hub.repository.CommandInProgress \ No newline at end of file diff --git a/docs/source/fr/package_reference/space_runtime.md b/docs/source/fr/package_reference/space_runtime.md deleted file mode 100644 index 96bb480b7c..0000000000 --- a/docs/source/fr/package_reference/space_runtime.md +++ /dev/null @@ -1,38 +0,0 @@ - - -# Gérez le temps d'exécution de votre space - -Consultez la page de documentation d'[`HfApi`] pour les références des méthodes pour gérer votre space -sur le Hub. - -- Dupliquer un space: [`duplicate_space`] -- Afficher les temps de calcul actuels: [`get_space_runtime`] -- Gérer les secrets: [`add_space_secret`] et [`delete_space_secret`] -- Gérer le hardware: [`request_space_hardware`] -- Gérer l'état: [`pause_space`], [`restart_space`], [`set_space_sleep_time`] - -## Structures de données - -### SpaceRuntime - -[[autodoc]] SpaceRuntime - -### SpaceHardware - -[[autodoc]] SpaceHardware - -### SpaceStage - -[[autodoc]] SpaceStage - -### SpaceStorage - -[[autodoc]] SpaceStorage - -### SpaceVariable - -[[autodoc]] SpaceVariable - - diff --git a/docs/source/fr/package_reference/tensorboard.md b/docs/source/fr/package_reference/tensorboard.md deleted file mode 100644 index 04662ffd27..0000000000 --- a/docs/source/fr/package_reference/tensorboard.md +++ /dev/null @@ -1,20 +0,0 @@ - - -# Logger TensorBoard - -TensorBoard est un kit d'outils qui permet de tester des outils de machine learning. TensorBoard permet de traquer -et de visualiser les métriques telles que la fonction de perte la précision, visualiser des graphiques, visualisers des -histogrammes, afficher des images et bien plus. TensorBoard est bien intégré avec le Hub Hugging Face. Le Hub détecte -automatiquement les traces de Tensorboard (telles que `tfevents`) lors d'un push vers le Hub qui lance une instance -pour les visualiser. Pour avoir plus d'informations sur l'intégration de TensorBoard avec le Hub, consultez [ce guide](https://huggingface.co/docs/hub/tensorboard). - -Pour bénéficier de cette intégration, `huggingface_hub` fournit un logger personnalisé pour push les logs vers le Hub. -Il fonctionne comme un remplacement de [SummaryWriter](https://tensorboardx.readthedocs.io/en/latest/tensorboard.html) -sans que vous n'ayez besoin de rajouter du code. Les traces sont toujours enregistrées en local et sont push vers le Hub -à des intervalles réguliers en arrière plan. - -## HFSummaryWriter - -[[autodoc]] HFSummaryWriter \ No newline at end of file diff --git a/docs/source/fr/package_reference/utilities.md b/docs/source/fr/package_reference/utilities.md deleted file mode 100644 index d6fcc68dee..0000000000 --- a/docs/source/fr/package_reference/utilities.md +++ /dev/null @@ -1,271 +0,0 @@ - - -# Utilitaires - -## Configurer la connexion - -Le package `huggingface_hub` expose un utilitaire `logging` qui permet de contrôler le niveau d'authentification -du package. Vous pouvez l'importer ainsi: - -```py -from huggingface_hub import logging -``` - -Ensuite, vous pourrez définir la verbosité afin de changer la quantité de logs que vous -verez: - -```python -from huggingface_hub import logging - -logging.set_verbosity_error() -logging.set_verbosity_warning() -logging.set_verbosity_info() -logging.set_verbosity_debug() - -logging.set_verbosity(...) -``` - -Les niveau de verbosité doivent être compris comme suit: - -- `error`: ne montre que les logs critiques qui pourrait causer une erreur ou un comportement innatendu. -- `warning`: montre des logs qui ne sont pas critiques mais dont l'utilisation pourrait causer un comportement inattendu. -En plus de ça, des informations importantes pourraient être affichées. -- `info`: montre la plupart des logs, dont des informations de logging donnant des informations sur ce que fait la fonction en arrière plan. -Si quelque chose se comporte de manière innatendue, nous recommendons de passer le niveau de verbosité à `info` afin d'avoir plus -d'informations. -- `debug`: montre tous les logs, dont des logs internes qui pourraient utiliser pour suivre en détail tout ce qui se passe en -arrière plan. - -[[autodoc]] logging.get_verbosity -[[autodoc]] logging.set_verbosity -[[autodoc]] logging.set_verbosity_info -[[autodoc]] logging.set_verbosity_debug -[[autodoc]] logging.set_verbosity_warning -[[autodoc]] logging.set_verbosity_error -[[autodoc]] logging.disable_propagation -[[autodoc]] logging.enable_propagation - -### Méthodes d'helper spécifiques au dépôt. - -Les méthodes montrés ci-dessous sont pertinentes lors de la modification de modules de la librairie `huggingface_hub`. -Utiliser ces méthodes ne devrait pas être nécessaire si vous utilisez les méthodes`huggingface_hub` -et que vous ne les modifiez pas. - -[[autodoc]] logging.get_logger - -## Configurez la barre de progression - -Les barres de progression sont utiles pour afficher des informations à l'utiliser lors de l'exécution d'une longue -tâche (i.e. lors du téléchargement ou de l'upload de fichiers). `huggingface_hub` met à disposition un wrapper -[`~utils.tqdm`] qui permet d'afficher constamment les barres de progressions pour toutes les fonctions de la -librairie. - -Par défaut, les barres de progressions sont activées. Vous pouvez les désactiver en définissant la -variable d'environnement `HF_HUB_DISABLE_PROGRESS_BARS`. Vous pouvez aussi les activer/désactiver en -utilisant [`~utils.enable_progress_bars`] et [`~utils.disable_progress_bars`]. Si définie, la variable -d'environnement a la priorité sur les helpers. - - -```py ->>> from huggingface_hub import snapshot_download ->>> from huggingface_hub.utils import are_progress_bars_disabled, disable_progress_bars, enable_progress_bars - ->>> # Supprimez toutes les barres de progression ->>> disable_progress_bars() - ->>> # Les barres de progressions ne seront pas affichées ! ->>> snapshot_download("gpt2") - ->>> are_progress_bars_disabled() -True - ->>> # Réactivez toutes les barres de progression ->>> enable_progress_bars() -``` - -### are_progress_bars_disabled - -[[autodoc]] huggingface_hub.utils.are_progress_bars_disabled - -### disable_progress_bars - -[[autodoc]] huggingface_hub.utils.disable_progress_bars - -### enable_progress_bars - -[[autodoc]] huggingface_hub.utils.enable_progress_bars - -## Configurez un backend HTTPConfigure HTTP backend - -Dans certains environnements, vous aurez peut être envie de configurer la manière dont les appels HTTP sont faits, -par exemple, si vous utilisez un proxy. `huggingface_hub` vous permet de configurer ceci en utilisant [`configure_http_backend`]. -Toutes les requêtes faites au Hub utiliseront alors vos paramètres.En arrière-plan, `huggingface_hub` utilise -`requests.Session`, vous aurez donc peut être besoin de consultez la [documentation `requests`](https://requests.readthedocs.io/en/latest/user/advanced) -pour en savoir plus sur les paramètres disponibles. - -Vu que `requests.Session` n'est pas toujours à l'abri d'un problème de thread, `huggingface_hub` créé une seule -instance de session par thread. L'utilisation de ces sessions permet de garder la connexion ouverte entre les appels HTTP -afin de gagner du temps. Si vous êtes entrain d'intégrer `huggingface_hub` dans une autre librairie tiers et que vous -voulez faire des appels personnalisés vers le Hub, utilisez [`get_session`] pour obtenir une session configurée par -vos utilisateurs (i.e. remplacez tous les appels à `requests.get(...)` par `get_session().get(...)`). - -[[autodoc]] configure_http_backend - -[[autodoc]] get_session - - -## Gérez les erreurs HTTP - -`huggingface_hub` définit ses propres erreurs HTTP pour améliorer le `HTTPError` -levé par `requests` avec des informations supplémentaires envoyées par le serveur. - -### Raise for status - -[`~utils.hf_raise_for_status`] est la méthode centrale pour "raise for status" depuis n'importe quelle -reqête faite au Hub. C'est wrapper autour de `requests.raise_for_status` qui fournit des informations -supplémentaires. Toute `HTTPError` envoyée est convertie en `HfHubHTTPError`. - -```py -import requests -from huggingface_hub.utils import hf_raise_for_status, HfHubHTTPError - -response = requests.post(...) -try: - hf_raise_for_status(response) -except HfHubHTTPError as e: - print(str(e)) # message formaté - e.request_id, e.server_message # détails retourné par le serveur - - # complétez le message d'erreur avec des informations additionnelles une fois que l'erreur est levée - e.append_to_message("\n`create_commit` expects the repository to exist.") - raise -``` - -[[autodoc]] huggingface_hub.utils.hf_raise_for_status - -### Erreurs HTTP - -Voici une liste des erreurs HTTP levée dans `huggingface_hub`. - -#### HfHubHTTPError - -`HfHubHTTPError` est la classe parente de toute erreur HTTP venant de HF Hub. Elle -va parser les réponses du serveur et formater le message d'erreur pour fournir le -plus d'informations possible à l'utilisateur. - -[[autodoc]] huggingface_hub.utils.HfHubHTTPError - -#### RepositoryNotFoundError - -[[autodoc]] huggingface_hub.utils.RepositoryNotFoundError - -#### GatedRepoError - -[[autodoc]] huggingface_hub.utils.GatedRepoError - -#### RevisionNotFoundError - -[[autodoc]] huggingface_hub.utils.RevisionNotFoundError - -#### EntryNotFoundError - -[[autodoc]] huggingface_hub.utils.EntryNotFoundError - -#### BadRequestError - -[[autodoc]] huggingface_hub.utils.BadRequestError - -#### LocalEntryNotFoundError - -[[autodoc]] huggingface_hub.utils.LocalEntryNotFoundError - -## Télémétrie - -`huggingface_hub` inclus un helper pour envoyer de la donnée de télémétrie. Cette information nous aide à debugger des problèmes -et prioriser les nouvelles fonctionnalités à développer. Les utilisateurs peuvent desactiver la collecte télémetrique à n'importe -quel moment et définissant la variable d'environnement `HF_HUB_DISABLE_TELEMETRY=1`. La télémétrie est aussi desactivée en mode -hors ligne (i.e. en définissant `HF_HUB_OFFLINE=1`). - -Si vous êtes mainteneur d'une librairie tiercce, envoyer des données de télémetrie est aussi facile que de faire un appel -à [`send_telemetry`]. Les données sont envoyées dans un thread séparé pour réduire autant que possible l'impact sur -l'expérience utilisateur. - -[[autodoc]] utils.send_telemetry - - -## Les validateurs - -`huggingface_hub` offre des validateurs personnalisés pour valider la méthode des -arguements automatiquement. La validation est inspirée du travail fait dans -[Pydantic](https://pydantic-docs.helpmanual.io/) pour valider les hints mais -avec des fonctionnalités plus limitées. - -### Décorateur générique - -[`~utils.validate_hf_hub_args`] est un décorateur générique pour encapsuler -des méthodes qui ont des arguments qui ont le nom d'`huggingface_hub`. -Par défaut, tous les arguments qui ont un validateur implémenté seront -validés. - -Si une entrée n'est pas valide, une erreur [`~utils.HFValidationError`] -est levée. Seul la première valeur invalide déclenche une erreur et -interrompt le processus de validation. - - -Utilisation: - -```py ->>> from huggingface_hub.utils import validate_hf_hub_args - ->>> @validate_hf_hub_args -... def my_cool_method(repo_id: str): -... print(repo_id) - ->>> my_cool_method(repo_id="valid_repo_id") -valid_repo_id - ->>> my_cool_method("other..repo..id") -huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'. - ->>> my_cool_method(repo_id="other..repo..id") -huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'. - ->>> @validate_hf_hub_args -... def my_cool_auth_method(token: str): -... print(token) - ->>> my_cool_auth_method(token="a token") -"a token" - ->>> my_cool_auth_method(use_auth_token="a use_auth_token") -"a use_auth_token" - ->>> my_cool_auth_method(token="a token", use_auth_token="a use_auth_token") -UserWarning: Both `token` and `use_auth_token` are passed (...). `use_auth_token` value will be ignored. -"a token" -``` - -#### validate_hf_hub_args - -[[autodoc]] utils.validate_hf_hub_args - -#### HFValidationError - -[[autodoc]] utils.HFValidationError - -### Validateurs d'arguments - -Les validateurs peuvent aussi être utilisés individuellement. Voici une liste de tous -les arguments qui peuvent être validés. - -#### repo_id - -[[autodoc]] utils.validate_repo_id - -#### smoothly_deprecate_use_auth_token - -Pas vraiment un validateur, mais utilisé aussi. - -[[autodoc]] utils.smoothly_deprecate_use_auth_token diff --git a/docs/source/fr/package_reference/webhooks_server.md b/docs/source/fr/package_reference/webhooks_server.md deleted file mode 100644 index 0ae7e5dc74..0000000000 --- a/docs/source/fr/package_reference/webhooks_server.md +++ /dev/null @@ -1,89 +0,0 @@ - - -# Serveurs WebHooks - -Les webhooks sont un pilier des fonctionnalités MLOps. Ils vous permettent de suivre tous les nouveaux -changements sur des dépôts spécifiques ou sur tous les dépôts appartenants à des utilisateurs/organisations que -vous voulez suivre. Pour en apprendre plus sur les webhooks dans le Hub Huggingface, vous pouvez consulter -le [guide](https://huggingface.co/docs/hub/webhooks) consacré aux webhooks. - - - -Consultez ce [guide](../guides/webhooks_server) pour un tutoriel pas à pas sur comment mettre en place votre serveur -webhooks et le déployer en tant que space. - - - - - -Ceci est une fonctionnalité expérimentale, ce qui signifie que nous travaillons toujours sur l'amélioration de l'API. -De gros changements pourraient être introduit dans le futur sans avertissement préalable. Faites en sorte -d'épingler la version d'`huggingface_hub` dans le requirements. Un avertissement est affiché lorsque vous utilisez -des fonctionnalités expérimentales. Vous pouvez le supprimer en définissant la variable d'environnement -`HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1`. - - - -## Serveur - -Le serveur est une application [Gradio](https://gradio.app/). Il possède une interface pour afficher des instructions pour vous -ou vos utilisateurs et une API pour écouter les webhooks. Implémenter un endpoint de webhook est aussi simple que d'ajouter -un décorateur à une fonction. Vous pouvez ensuite le debugger en redirigeant le webhook vers votre machine (en utilisant -un tunnel Gradio) avant de le déployer sur un space. - -### WebhooksServer - -[[autodoc]] huggingface_hub.WebhooksServer - -### @webhook_endpoint - -[[autodoc]] huggingface_hub.webhook_endpoint - -## Payload - -[`WebhookPayload`] est la structure de donnée principale qui contient le payload de webhooks. -C'est une classe `pydantic` ce qui la rend très facile à utiliser avec FastAPI. Si vous la -passez en tant que paramètre d'un endpoint webhook, il sera automatiquement validé et parsé en tant qu'objet Python. - -Pour plus d'informations sur les payload webhooks, vous pouvez vous référer au [guide](https://huggingface.co/docs/hub/webhooks#webhook-payloads). -sur les payloads webhooks - -[[autodoc]] huggingface_hub.WebhookPayload - -### WebhookPayload - -[[autodoc]] huggingface_hub.WebhookPayload - -### WebhookPayloadComment - -[[autodoc]] huggingface_hub.WebhookPayloadComment - -### WebhookPayloadDiscussion - -[[autodoc]] huggingface_hub.WebhookPayloadDiscussion - -### WebhookPayloadDiscussionChanges - -[[autodoc]] huggingface_hub.WebhookPayloadDiscussionChanges - -### WebhookPayloadEvent - -[[autodoc]] huggingface_hub.WebhookPayloadEvent - -### WebhookPayloadMovedTo - -[[autodoc]] huggingface_hub.WebhookPayloadMovedTo - -### WebhookPayloadRepo - -[[autodoc]] huggingface_hub.WebhookPayloadRepo - -### WebhookPayloadUrl - -[[autodoc]] huggingface_hub.WebhookPayloadUrl - -### WebhookPayloadWebhook - -[[autodoc]] huggingface_hub.WebhookPayloadWebhook From 33485b4896ef14e2a918bd073d677851fcd1ac94 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:34:21 +0200 Subject: [PATCH 090/129] Update docs/source/fr/_toctree.yml Co-authored-by: Lucain --- docs/source/fr/_toctree.yml | 75 +------------------------------------ 1 file changed, 2 insertions(+), 73 deletions(-) diff --git a/docs/source/fr/_toctree.yml b/docs/source/fr/_toctree.yml index 6eaf8f07a8..62137bd951 100644 --- a/docs/source/fr/_toctree.yml +++ b/docs/source/fr/_toctree.yml @@ -10,77 +10,6 @@ sections: - local: concepts/git_vs_http title: Git ou HTTP? - - local: guides/overview - title: Vue d'ensemble - - local: guides/download - title: Télécharger des fichiers - - local: guides/upload - title: Upload des fichiers - - local: guides/cli - title: Utiliser le CLI - - local: guides/hf_file_system - title: HfFileSystem - - local: guides/repository - title: Dépôts - - local: guides/search - title: Rechercher - - local: guides/inference - title: Inférence - - local: guides/inference_endpoints - title: Inference Endpoints - - local: guides/community - title: Community Tab - - local: guides/collections - title: Collections - - local: guides/manage-cache - title: Cache - - local: guides/model-cards - title: Model cards - - local: guides/manage-spaces - title: Gérez vos Spaces +- title: "Guides" - local: guides/integrations - title: Intégrer une librairie - - local: guides/webhooks_server - title: Webhooks -- title: "Concepts" - sections: - - local: concepts/git_vs_http - title: Git ou HTTP? -- title: "Référence" - sections: - - local: package_reference/overview - title: Vue d'ensemble - - local: package_reference/login - title: Connexion et déconnexion - - local: package_reference/environment_variables - title: Variables d'environnement - - local: package_reference/repository - title: Gérer les dépôts locaux et en ligne - - local: package_reference/hf_api - title: Hugging Face Hub API - - local: package_reference/file_download - title: Téléchargement des fichiers - - local: package_reference/mixins - title: Mixins & méthodes de sérialisations - - local: package_reference/inference_client - title: Inference Client - - local: package_reference/inference_endpoints - title: Inference Endpoints - - local: package_reference/hf_file_system - title: HfFileSystem - - local: package_reference/utilities - title: Utilitaires - - local: package_reference/community - title: Discussions et Pull Requests - - local: package_reference/cache - title: Système de cache - - local: package_reference/cards - title: Repo Cards et metadata - - local: package_reference/space_runtime - title: Space runtime - - local: package_reference/collections - title: Collections - - local: package_reference/tensorboard - title: Logger Tensorboard - - local: package_reference/webhooks_server - title: Webhooks \ No newline at end of file + title: Intégrer dans une librarie \ No newline at end of file From 016a0c70b0fbedbca03d7def00e9d6cdb1b3079c Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:34:31 +0200 Subject: [PATCH 091/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 3a8b6a93d9..0de0e780d3 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -160,7 +160,7 @@ 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: +Voici comment n'importe quel utilisateur peut charger/enregistrer un modèle Pytorch depuis/vers le Hub: ```python >>> import torch From d1e45f789cd39f1d74758afe1fffc2703527a11e Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:34:37 +0200 Subject: [PATCH 092/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 0de0e780d3..a7d73b9786 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -190,7 +190,7 @@ Voici comment n'importe quel utilisateur peut charger/enregistrer un modèle Pyt #### 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). +L'implémentation est très succincte (voir [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`: From 4ed79792af286ca1b9fe0d174ef4da7719ed857b Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:34:43 +0200 Subject: [PATCH 093/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index a7d73b9786..9622500e2e 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -276,9 +276,9 @@ Et c'est fini ! Votre librairie permet maintenant aux utilisateurs d'upload et d ## 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, +Résumons rapidement les deux approches que nous avons vu avec leurs avantages et leurs défauts. Le tableau ci-dessous +est purement indicatif. Votre framework aura peut-êre des spécifités à prendre en compte. Ce guide +est ici 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 ! From 24c00ae43428a1973ae788af0967e721e4ee4f2b Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:34:53 +0200 Subject: [PATCH 094/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 9622500e2e..5343615e68 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -151,7 +151,7 @@ devez implémenter. Ainsi, pour intégrer votre librairie, vous devez : 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é. +bien documentées et que les annotations de typage sont spécifiées. ### Un exemple concret: PyTorch From 0e5791893d895821e98c777e40e897b73d35f7cc Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:35:02 +0200 Subject: [PATCH 095/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 5343615e68..0486b32cd7 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -145,7 +145,7 @@ devez implémenter. Ainsi, pour intégrer votre librairie, vous devez : [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. + Cette méthode doit télécharger un ou plusieurs fichier(s) et le(s) 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, From 2f0af2a6167827b52b31c03bf9da185b41572fd7 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:35:13 +0200 Subject: [PATCH 096/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 0486b32cd7..b0abbf7923 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -4,7 +4,7 @@ rendered properly in your Markdown viewer. # 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. +Le Hugging Face Hub facilite l'hébergement et le partage de modèles et de jeux de données. 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 From ac2ddaeccf5ab7b34b85b1aa69e44d0fea8ceb1b Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:35:19 +0200 Subject: [PATCH 097/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index b0abbf7923..eb128363e6 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -5,10 +5,7 @@ rendered properly in your Markdown viewer. # Intégrez n'importe quel framework de ML avec le Hub Le Hugging Face Hub facilite l'hébergement et le partage de modèles et de jeux de données. -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. +Des [dizaines de librairies](https://huggingface.co/docs/hub/models-libraries) sont intégrées à cet écosysteme. La communauté travaille constamment à en intégrer de nouvelles et contribue ainsi à faciliter la collaboration dans le milieu du machine learning. La librairie `huggingface_hub` joue un rôle clé dans ce processus puisqu'elle permet d'interagir avec le Hub depuis n'importe quel script Python. 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 From 5cbd2a5f92be6bbae5d2a46816caa98a9a9fe72a Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:35:30 +0200 Subject: [PATCH 098/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index eb128363e6..9221525fd9 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -2,7 +2,7 @@ rendered properly in your Markdown viewer. --> -# Intégrez n'importe quel framework de ML avec le Hub +# Intégrez votre framework de ML avec le Hub Le Hugging Face Hub facilite l'hébergement et le partage de modèles et de jeux de données. Des [dizaines de librairies](https://huggingface.co/docs/hub/models-libraries) sont intégrées à cet écosysteme. La communauté travaille constamment à en intégrer de nouvelles et contribue ainsi à faciliter la collaboration dans le milieu du machine learning. La librairie `huggingface_hub` joue un rôle clé dans ce processus puisqu'elle permet d'interagir avec le Hub depuis n'importe quel script Python. From 7820f8bc8f7ddd318868fc1c81c428e079257f7d Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:35:35 +0200 Subject: [PATCH 099/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 9221525fd9..cc60ea89b8 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -7,7 +7,7 @@ rendered properly in your Markdown viewer. Le Hugging Face Hub facilite l'hébergement et le partage de modèles et de jeux de données. Des [dizaines de librairies](https://huggingface.co/docs/hub/models-libraries) sont intégrées à cet écosysteme. La communauté travaille constamment à en intégrer de nouvelles et contribue ainsi à faciliter la collaboration dans le milieu du machine learning. La librairie `huggingface_hub` joue un rôle clé dans ce processus puisqu'elle permet d'interagir avec le Hub depuis n'importe quel script Python. -Il y a quatre manière principales d'intégrer une librairie avec le Hub: +Il existe quatre façons principales d'intégrer une bibliothèque au 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 From 9c9671b2ce7cb1c051c3e28dc7a610eca62d0414 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:35:54 +0200 Subject: [PATCH 100/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index cc60ea89b8..0d58794c03 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -8,10 +8,7 @@ Le Hugging Face Hub facilite l'hébergement et le partage de modèles et de jeux Des [dizaines de librairies](https://huggingface.co/docs/hub/models-libraries) sont intégrées à cet écosysteme. La communauté travaille constamment à en intégrer de nouvelles et contribue ainsi à faciliter la collaboration dans le milieu du machine learning. La librairie `huggingface_hub` joue un rôle clé dans ce processus puisqu'elle permet d'interagir avec le Hub depuis n'importe quel script Python. Il existe quatre façons principales d'intégrer une bibliothèque au 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()`. +1. **Push to Hub** implémente une méthode pour upload un modèle sur le Hub. Cela inclut les paramètres du modèle, sa fiche descriptive (appelée [Model Card](https://huggingface.co/docs/huggingface_hub/how-to-model-cards)) et toute autre information pertinente lié au 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()`. From eae1ecccc409e095459b865d5212dfc262793b27 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:36:14 +0200 Subject: [PATCH 101/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 0d58794c03..100d5522c7 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -9,9 +9,7 @@ Des [dizaines de librairies](https://huggingface.co/docs/hub/models-libraries) s Il existe quatre façons principales d'intégrer une bibliothèque au Hub : 1. **Push to Hub** implémente une méthode pour upload un modèle sur le Hub. Cela inclut les paramètres du modèle, sa fiche descriptive (appelée [Model Card](https://huggingface.co/docs/huggingface_hub/how-to-model-cards)) et toute autre information pertinente lié au 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()`. +2. **Download from Hub** implémente une méthode pour charger un modèle depuis le Hub. La méthode doit télécharger la configuration et les poids du modèle puis instancier celui-ci. 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. From e86816e1c5360f1d95bcf73ef70ff6014df930a5 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:36:30 +0200 Subject: [PATCH 102/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 100d5522c7..da2bdd1baa 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -11,8 +11,7 @@ Il existe quatre façons principales d'intégrer une bibliothèque au Hub : 1. **Push to Hub** implémente une méthode pour upload un modèle sur le Hub. Cela inclut les paramètres du modèle, sa fiche descriptive (appelée [Model Card](https://huggingface.co/docs/huggingface_hub/how-to-model-cards)) et toute autre information pertinente lié au 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èle depuis le Hub. La méthode doit télécharger la configuration et les poids du modèle puis instancier celui-ci. 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. +4. **Widgets** affiche un widget sur la page d'accueil de votre modèle dans le Hub. Les widgets permettent aux utilisateurs de rapidement tester 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 From 3ba71e34d26ee4bc31e1cd7e7169cdc8ef1f38d4 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:36:56 +0200 Subject: [PATCH 103/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index da2bdd1baa..11d5011d59 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -87,7 +87,7 @@ upload des poids à la volée, maintenir les poids localement, etc.) consultez l ### 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, +d'Hugging Face sont habitués à utiliser des certaines 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 From edd4c6480a8c821f6db442a90da6ba880bbce2d7 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:37:12 +0200 Subject: [PATCH 104/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 11d5011d59..bc9efd4b01 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -13,10 +13,7 @@ Il existe quatre façons principales d'intégrer une bibliothèque au 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'accueil de votre modèle dans le Hub. Les widgets permettent aux utilisateurs de rapidement tester 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. +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 leurs avantages et leurs inconvénients. 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, et 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 From 6de4850566db9a8ba2ea5d92c458598739635ce0 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:37:26 +0200 Subject: [PATCH 105/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index bc9efd4b01..de46393109 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -15,9 +15,7 @@ Il existe quatre façons principales d'intégrer une bibliothèque au Hub : 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 leurs avantages et leurs inconvénients. 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, et 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). +Si l'Inference API et les 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 être listée [dans la documentation officielle](https://huggingface.co/docs/hub/models-libraries). ## Une approche flexible: les helpers From 81f499b2280be41e0b3b4da5ea2f62a80cb9c497 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:37:45 +0200 Subject: [PATCH 106/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index de46393109..613cef6bf1 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -22,8 +22,8 @@ Si l'Inference API et les Widgets vous intéressent, vous pouvez suivre [ce guid 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`]). +et [télécharger des fichiers](./download) pour en savoir plus sur la manière de faire. Par example, c'est de cette manière que l'intégration +de FastAI est implémentée (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 6900c722931243961d1a05936b0c69260fddc029 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:38:03 +0200 Subject: [PATCH 107/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 613cef6bf1..e5f0e51401 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -29,7 +29,7 @@ L'implémentation peut varier entre différentes librairies, mais le workflow es ### from_pretrained -Voici comment une méthode `from_pretrained` fonctionne d'habitude: +Voici un exemple classique pour implémenter la méthode `from_pretrained`: ```python def from_pretrained(model_id: str) -> MyModelClass: From 359181c5a836000529a7182ab5f6ebfe85266ae6 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:38:18 +0200 Subject: [PATCH 108/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index e5f0e51401..1d424973a6 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -33,7 +33,7 @@ Voici un exemple classique pour implémenter la méthode `from_pretrained`: ```python def from_pretrained(model_id: str) -> MyModelClass: - # Téléchargement du modèles depuis le Hub + # Téléchargement des paramètres depuis le Hub cached_model = hf_hub_download( repo_id=repo_id, filename="model.pkl", From fab861f571b927826f2fc24bf137c153e25537f6 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:38:32 +0200 Subject: [PATCH 109/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 1d424973a6..275f733413 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -41,7 +41,7 @@ def from_pretrained(model_id: str) -> MyModelClass: library_version=get_fastai_version(), ) - # Chargement du modèle + # Instanciation du modèle return load_model(cached_model) ``` From b3281a2749b46d8ad062fc087e7842f3f93d732a Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:38:44 +0200 Subject: [PATCH 110/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 275f733413..c2acf45e31 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -47,7 +47,7 @@ def from_pretrained(model_id: str) -> MyModelClass: ### 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. +La méthode `push_to_hub` demande souvent un peu plus de complexité pour gérer la création du dépôt git, générer la model card et enregistrer les paramètres. Une approche commune est de sauvegarder tous ces fichiers dans un dossier temporaire, les upload et ensuite les supprimer. ```python From d4e9e9589db62760152b9340469acb2e0f3967e7 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:38:56 +0200 Subject: [PATCH 111/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index c2acf45e31..95625811a5 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -48,7 +48,7 @@ def from_pretrained(model_id: str) -> MyModelClass: ### 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 git, générer la model card et enregistrer les paramètres. -Une approche commune est de sauvegarder tous ces fichiers dans un dossier temporaire, les upload et ensuite les supprimer. +Une approche commune est de sauvegarder tous ces fichiers dans un dossier temporaire, les transférer sur le Hub avant de les supprimer localement. ```python def push_to_hub(model: MyModelClass, repo_name: str) -> None: From 487dbfafb3b230183363d9fc132aa12c9e911343 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:39:09 +0200 Subject: [PATCH 112/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 95625811a5..84d10a30a4 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -55,7 +55,7 @@ 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) + repo_id = api.create_repo(repo_name, exist_ok=True).repo_id # Sauvegardez tous les fichiers dans un chemin temporaire, et pushez les en un seul commit with TemporaryDirectory() as tmpdir: From 89bfa57d8bad0dd6f3a474b8019a138d56d775c1 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:39:22 +0200 Subject: [PATCH 113/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 84d10a30a4..d74d51ce64 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -64,7 +64,7 @@ def push_to_hub(model: MyModelClass, repo_name: str) -> None: # Sauvegardez les poids save_model(model, tmpdir / "model.safetensors") - # Générez le chemin du modèle + # Générez la model card card = generate_model_card(model) (tmpdir / "README.md").write_text(card) From a101bab6d71088ccca2220d0f51ef91195fbbc95 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:39:36 +0200 Subject: [PATCH 114/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index d74d51ce64..ee42db6e82 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -77,7 +77,7 @@ def push_to_hub(model: MyModelClass, repo_name: str) -> None: ``` 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) +upload des poids à la volée, maintenir les poids localement, etc.) consultez le guide [upload des fichiers](./upload). ### Limitations From 251e8e9be101169cb5f5c4b5929992ff64596289 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:43:17 +0200 Subject: [PATCH 115/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index ee42db6e82..9273e002c2 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -94,7 +94,7 @@ 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` +- `branch`: push vers une branche au lieu de push sur `main` - `allow_patterns`/`ignore_patterns`: filtre les fichiers à upload - `token` - `api_endpoint` From 6cb7f012a9cf2ba1802333c07c9115a46167402a Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:43:30 +0200 Subject: [PATCH 116/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 9273e002c2..cbdca1b55e 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -83,7 +83,7 @@ upload des poids à la volée, maintenir les poids localement, etc.) consultez l 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 certaines 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: +lors du chargement de fichiers depuis le Hub, il est commun de passer des 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 From 61514fe907a24670026dc342d5249987d15e25ee Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:43:42 +0200 Subject: [PATCH 117/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index cbdca1b55e..819f2e13c0 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -86,7 +86,7 @@ d'Hugging Face sont habitués à utiliser des certaines fonctionnalités lorsqu' lors du chargement de fichiers depuis le Hub, il est commun de passer des 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 +- `cache_dir`: pour paramétrer la mise en cache des fichiers - `force_download`/`resume_download`/`local_files_only`: pour réutiliser le cache ou pas - `api_endpoint`/`proxies`: pour configurer la session HTTP From 74d17c9e61f02f29b47fa107fb1cc8c93cd16cba Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:44:05 +0200 Subject: [PATCH 118/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 819f2e13c0..8e1b96e2f6 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -87,7 +87,7 @@ lors du chargement de fichiers depuis le Hub, il est commun de passer des param - `token`: pour télécharger depuis un dépôt privé - `revision`: pour télécharger depuis une branche spécifique - `cache_dir`: pour paramétrer la mise en cache des fichiers -- `force_download`/`resume_download`/`local_files_only`: pour réutiliser le cache ou pas +- `force_download`: pour désactiver le cache - `api_endpoint`/`proxies`: pour configurer la session HTTP Lorsque vous pushez des modèles, des paramètres similaires sont utilisables: From e1b6419b7d9529d6133bd5e73613fa089a4e28f9 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:44:33 +0200 Subject: [PATCH 119/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 8e1b96e2f6..cbb1debe2d 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -93,7 +93,7 @@ lors du chargement de fichiers depuis le Hub, il est commun de passer des param 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` +- `create_pr`: créé un pull request au lieu de push vers `main` - `branch`: push vers une branche au lieu de push sur `main` - `allow_patterns`/`ignore_patterns`: filtre les fichiers à upload - `token` From 80fc05f33759fc3e892228dd54c1937f676ce8f4 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:44:59 +0200 Subject: [PATCH 120/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index cbb1debe2d..24a95e1d12 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -102,8 +102,7 @@ Lorsque vous pushez des modèles, des paramètres similaires sont utilisables: 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**. +Supporter ces paramètres implique aussi plus de documentation à maintenir de votre côté. Dans la prochaine section, nous allons voir comment dépasser ces limitations. ## Une approche plus complexe: class inheritance From 7ca5c0b629a1d9a708abf7946a4c146f1c9e80a5 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:45:35 +0200 Subject: [PATCH 121/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 24a95e1d12..812317b68f 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -104,7 +104,7 @@ Tous ces paramètres peuvent être ajoutés aux implémentations vues ci dessus Toutefois, si un paramètre change ou qu'une nouvelle fonctionnalité est ajoutée, vous devrez mettre à jour votre package. Supporter ces paramètres implique aussi plus de documentation à maintenir de votre côté. Dans la prochaine section, nous allons voir comment dépasser ces limitations. -## Une approche plus complexe: class inheritance +## Une approche plus complexe: l'héritage de classe 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`). From 7b0a5986e558a082ac6fdd8a8c0656bf85e80c13 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:45:59 +0200 Subject: [PATCH 122/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 812317b68f..e7c4043e1d 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -106,7 +106,7 @@ Supporter ces paramètres implique aussi plus de documentation à maintenir de v ## Une approche plus complexe: l'héritage de classe -Comme vu ci dessus, il y a deux méthodes principales à inclure dans votre librairie pour l'intégrer avec le Hub: +Comme vu ci-dessus, deux méthodes principales sont à 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 ! From 5519c3fef2dd2a98873fc4f9436202ec1e7ea4df Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:46:25 +0200 Subject: [PATCH 123/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index e7c4043e1d..13b1c0c47d 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -108,7 +108,7 @@ Supporter ces paramètres implique aussi plus de documentation à maintenir de v Comme vu ci-dessus, deux méthodes principales sont à 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 +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 From e2d53303872f458affd00c0425afd7389217250c Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:46:51 +0200 Subject: [PATCH 124/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 13b1c0c47d..ce08baefde 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -111,7 +111,7 @@ la méthode permettant d'upload des fichiers (`push_to_hub`) et celle pour tél 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 +Dans beaucoup de cas, une librairie définit déjà les modèles comme des classes 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. From f4873f3f459b4806eff45e810f35e538e4eb54ac Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:47:26 +0200 Subject: [PATCH 125/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index ce08baefde..f4119b7d1c 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -113,7 +113,7 @@ un outil qui utilise l'héritage de classe. Regardons comment ça marche ! Dans beaucoup de cas, une librairie définit déjà les modèles comme des classes 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) +cette classe pour inclure les fonctionnalités upload et download en utilisant les mixins. Une [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. From 9f0f1e9f0c5b8dffa7261ee34a49084500faae31 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:47:52 +0200 Subject: [PATCH 126/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index f4119b7d1c..27192ed6e9 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -129,7 +129,7 @@ devez implémenter. Ainsi, pour intégrer votre librairie, vous devez : 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é. + - [`~ModelHubMixin._from_pretrained`]: **méthode de classe** prenant en entrée un `model_id` et qui retourne un modèle instancié. Cette méthode doit télécharger un ou plusieurs fichier(s) et le(s) charger. 3. Fini! From dc497294768458688166612a0dbfe906cede77b7 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:48:19 +0200 Subject: [PATCH 127/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 27192ed6e9..45557525f3 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -114,7 +114,7 @@ un outil qui utilise l'héritage de classe. Regardons comment ça marche ! Dans beaucoup de cas, une librairie définit déjà les modèles comme des classes 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. Une [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. +est une classe qui est faite pour étendre une classe existante avec une liste de fonctionnalités spécifiques en utilisant l'héritage de classe. `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 From b4297c43dc245c3e9f3f41f05d136c303312cc6c Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:48:42 +0200 Subject: [PATCH 128/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 45557525f3..83e1811184 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -122,7 +122,7 @@ sont les méthodes que vos utilisateurs appeleront pour charger/enregistrer des [`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`]. +1. Faire 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, From 12c6274aecc90105ebfdcc2c0b447b89c86c1413 Mon Sep 17 00:00:00 2001 From: JibrilEl <141321154+JibrilEl@users.noreply.github.com> Date: Fri, 21 Jun 2024 16:49:06 +0200 Subject: [PATCH 129/129] Update docs/source/fr/guides/integrations.md Co-authored-by: Lucain --- docs/source/fr/guides/integrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/fr/guides/integrations.md b/docs/source/fr/guides/integrations.md index 83e1811184..5813707f90 100644 --- a/docs/source/fr/guides/integrations.md +++ b/docs/source/fr/guides/integrations.md @@ -126,7 +126,7 @@ devez implémenter. Ainsi, pour intégrer votre librairie, vous devez : 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 + et logs d'entrainement. 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 retourne un modèle instancié.