From 6ae54c3198c8eb4cb4b702819e7b04209fafc426 Mon Sep 17 00:00:00 2001 From: Steven Date: Thu, 21 Apr 2022 13:17:45 -0700 Subject: [PATCH 1/3] =?UTF-8?q?=20=F0=9F=93=9D=20first=20draft=20of=20quic?= =?UTF-8?q?k=20start?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/source/_toctree.yml | 4 ++ docs/source/quick-start.mdx | 96 +++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 docs/source/quick-start.mdx diff --git a/docs/source/_toctree.yml b/docs/source/_toctree.yml index 4498c05cf2..834ee5fc8f 100644 --- a/docs/source/_toctree.yml +++ b/docs/source/_toctree.yml @@ -1,6 +1,10 @@ - sections: - local: index title: 🤗 Hugging Face Hub Python Wrapper + - local: quick-start + title: Quick start + title: "Get started" +- sections: - local: how-to-downstream title: How to download files from the hub - local: how-to-upstream diff --git a/docs/source/quick-start.mdx b/docs/source/quick-start.mdx new file mode 100644 index 0000000000..a406b4a291 --- /dev/null +++ b/docs/source/quick-start.mdx @@ -0,0 +1,96 @@ +# Quick start + +The Hugging Face Hub is the go-to place for sharing machine learning models, datasets, and metrics. To help you get the most out of the Hub, we created the `huggingface_hub` library so you can interact with the Hub without leaving your development environment. You can create and manage repositories easily and download and upload files from the Hub. + +## Install the Hub library + +To get started, you should install the `huggingface_hub` library. The library provides functions that make interacting with the Hub simple. Run the following command to install the library: + +```bash +>>> pip install huggingface_hub +``` + +## Download files from the Hub + +Repositories store versioned model and dataset files anyone can download. You can use the [`hf_hub_url`] 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") +``` + +Finally, you can choose where to cache a file with the `cache_dir` parameter: + +```py +>>> from huggingface_hub import hf_hub_download +>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json", cache_dir="/my/cool/cache") +``` + +## Create a repository + +To create and share files to the Hub, you need to have a Hugging Face account. [Create an account]((https://huggingface.co/join)) if you don't already have one, and then sign in to find your [User Access Token](https://huggingface.co/docs/hub/security#user-access-tokens) in your Settings. The User Access Token is used to authenticate your identity to the Hub. + +1. Log in to your Hugging Face account with the following command: + +```bash +huggingface-cli login +``` + +Or if you prefer to work from a Jupyter or Colaboratory notebook, then login with [`notebook_login`]: + +```py +>>> from huggingface_hub import notebook_login +>>> notebook_login() +``` + +2. Enter your User Access Token to authenticate your identity to the Hub. + +After you've created an account, create a repository with the [`create_repo`] function: + +```py +>>> from huggingface_hub import create_repo +>>> create_repo(repo_name="super-cool-model") +``` + +If you want your repository to be private, then: + +```py +>>> from huggingface_hub import create_repo +>>> create_repo(repo_name="super-cool-model", private=True) +``` + +Private repositories will not be visible to anyone except yourself. + +## Share files to the Hub + +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 upload_file +>>> 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 this [guide](how-to-upstream) which will introduce you to the [`Repository`] class and other methods for uploading files. + +## 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 for how to: + +- [Create and manage repositories](how-to-manage). +- [Download](how-to-downstream) files from the Hub. +- [Upload](how-to-upstream) files to the Hub. +- [Search the Hub](searching-the-hub) for your desired model or dataset. +- [Access the Inference API](how-to-inference) for fast inference. \ No newline at end of file From 17d7aa3efcc278d6c4449156665002c9e85cbd4e Mon Sep 17 00:00:00 2001 From: Steven Date: Fri, 22 Apr 2022 16:22:26 -0700 Subject: [PATCH 2/3] =?UTF-8?q?=20=F0=9F=96=8D=20apply=20adrin=20review=20?= =?UTF-8?q?part=201?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/source/quick-start.mdx | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/source/quick-start.mdx b/docs/source/quick-start.mdx index a406b4a291..2cd2f226e7 100644 --- a/docs/source/quick-start.mdx +++ b/docs/source/quick-start.mdx @@ -1,18 +1,26 @@ # Quick start -The Hugging Face Hub is the go-to place for sharing machine learning models, datasets, and metrics. To help you get the most out of the Hub, we created the `huggingface_hub` library so you can interact with the Hub without leaving your development environment. You can create and manage repositories easily and download and upload files from the Hub. +The Hugging Face Hub is the go-to place for sharing machine learning models, spaces, datasets, and metrics. `huggingface_hub` library helps you interact with the Hub without leaving your development environment. You can create and manage repositories easily and download and upload files from the Hub. ## Install the Hub library -To get started, you should install the `huggingface_hub` library. The library provides functions that make interacting with the Hub simple. Run the following command to install the library: +To get started, you should install the `huggingface_hub` library. The library provides functionalities that make interacting with the Hub simple. You can install the library with `pip` or `conda`. + +With `pip`: + +```bash +pip install huggingface_hub +``` + +With `conda`: ```bash ->>> pip install huggingface_hub +conda install -c conda-forge huggingface_hub ``` ## Download files from the Hub -Repositories store versioned model and dataset files anyone can download. You can use the [`hf_hub_url`] 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. +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: @@ -25,20 +33,25 @@ To download a specific version of the file, use the `revision` parameter to spec ```py >>> from huggingface_hub import hf_hub_download ->>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json", revision="4d33b01d79672f27f001f6abade33f22d993b151") +>>> hf_hub_download( +... repo_id="google/pegasus-xsum", +... filename="config.json", +... revision="4d33b01d79672f27f001f6abade33f22d993b151" +... ) ``` -Finally, you can choose where to cache a file with the `cache_dir` parameter: - -```py ->>> from huggingface_hub import hf_hub_download ->>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json", cache_dir="/my/cool/cache") -``` +For more details and options, see the API reference for [`hf_hub_download`]. ## Create a repository To create and share files to the Hub, you need to have a Hugging Face account. [Create an account]((https://huggingface.co/join)) if you don't already have one, and then sign in to find your [User Access Token](https://huggingface.co/docs/hub/security#user-access-tokens) in your Settings. The User Access Token is used to authenticate your identity to the Hub. + + +You can also provide your token to our functions and methods. This way you don't need to store your token anywhere. + + + 1. Log in to your Hugging Face account with the following command: ```bash From 7d31091fc0af12d42ecd0a439280785c96e784e4 Mon Sep 17 00:00:00 2001 From: Steven Date: Mon, 25 Apr 2022 09:43:51 -0700 Subject: [PATCH 3/3] =?UTF-8?q?=20=F0=9F=96=8D=20apply=20all=20the=20revie?= =?UTF-8?q?ws?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/source/_toctree.yml | 20 ++++++------ docs/source/quick-start.mdx | 62 +++++++++++++++++++++++++++---------- 2 files changed, 55 insertions(+), 27 deletions(-) diff --git a/docs/source/_toctree.yml b/docs/source/_toctree.yml index 834ee5fc8f..453084d627 100644 --- a/docs/source/_toctree.yml +++ b/docs/source/_toctree.yml @@ -15,15 +15,15 @@ title: How to programmatically access the Inference API title: "Guides" - sections: - - local: package_reference/repository - title: Managing local and online repositories - - local: package_reference/hf_api - title: Hugging Face Hub API - - local: package_reference/file_download - title: Downloading files - - local: package_reference/mixins - title: Mixins & serialization methods - - local: package_reference/logging - title: Logging + - local: package_reference/repository + title: Managing local and online repositories + - local: package_reference/hf_api + title: Hugging Face Hub API + - local: package_reference/file_download + title: Downloading files + - local: package_reference/mixins + title: Mixins & serialization methods + - local: package_reference/logging + title: Logging title: "Reference" diff --git a/docs/source/quick-start.mdx b/docs/source/quick-start.mdx index 2cd2f226e7..f69da9de79 100644 --- a/docs/source/quick-start.mdx +++ b/docs/source/quick-start.mdx @@ -1,10 +1,15 @@ # Quick start -The Hugging Face Hub is the go-to place for sharing machine learning models, spaces, datasets, and metrics. `huggingface_hub` library helps you interact with the Hub without leaving your development environment. You can create and manage repositories easily and download and upload files from the Hub. +The [Hugging Face Hub](https://hf.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. ## Install the Hub library -To get started, you should install the `huggingface_hub` library. The library provides functionalities that make interacting with the Hub simple. You can install the library with `pip` or `conda`. +To get started, you should install the `huggingface_hub` library. You can install the +library with `pip` or `conda`. With `pip`: @@ -20,16 +25,23 @@ conda install -c conda-forge huggingface_hub ## Download files from the Hub -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. +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: +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: +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 @@ -44,11 +56,15 @@ For more details and options, see the API reference for [`hf_hub_download`]. ## Create a repository -To create and share files to the Hub, you need to have a Hugging Face account. [Create an account]((https://huggingface.co/join)) if you don't already have one, and then sign in to find your [User Access Token](https://huggingface.co/docs/hub/security#user-access-tokens) in your Settings. The User Access Token is used to authenticate your identity to the Hub. +To create and share files to the Hub, you need to have a Hugging Face account. [Create +an account](https://hf.co/join) if you don't already have one, and then sign in to find +your [User Access Token](https://huggingface.co/docs/hub/security#user-access-tokens) in +your Settings. The User Access Token is used to authenticate your identity to the Hub. -You can also provide your token to our functions and methods. This way you don't need to store your token anywhere. +You can also provide your token to our functions and methods. This way you don't need to +store your token anywhere. @@ -58,7 +74,8 @@ You can also provide your token to our functions and methods. This way you don't huggingface-cli login ``` -Or if you prefer to work from a Jupyter or Colaboratory notebook, then login with [`notebook_login`]: +Or if you prefer to work from a Jupyter or Colaboratory notebook, then login with +[`notebook_login`]: ```py >>> from huggingface_hub import notebook_login @@ -70,37 +87,48 @@ Or if you prefer to work from a Jupyter or Colaboratory notebook, then login wit After you've created an account, create a repository with the [`create_repo`] function: ```py ->>> from huggingface_hub import create_repo ->>> create_repo(repo_name="super-cool-model") +>>> 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 create_repo ->>> create_repo(repo_name="super-cool-model", private=True) +>>> 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. ## Share files to the Hub -Use the [`upload_file`] function to add a file to your newly created repository. You need to specify: +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 upload_file ->>> upload_file(path_or_fileobj="/home/lysandre/dummy-test/README.md", path_in_repo="README.md", repo_id="lysandre/test-model") +>>> 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 this [guide](how-to-upstream) which will introduce you to the [`Repository`] class and other methods for uploading files. +To upload more than one file at a time, take a look at this [guide](how-to-upstream) +which will introduce you to the [`Repository`] class and other methods for uploading +files. ## 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 for how to: +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 for how to: - [Create and manage repositories](how-to-manage). - [Download](how-to-downstream) files from the Hub.