You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# How to integrate downstream utilities in your library
3
+
The `huggingface_hub` library provides functions to download files from the repositories
4
+
stored on the Hub. You can use these functions independently or integrate them into your
5
+
own library, making it more convenient for your users to interact with the Hub. This
6
+
guide will show you how to:
6
7
7
-
Utilities that allow your library to download files from the Hub are referred to as *downstream* utilities. This guide introduces additional downstream utilities you can integrate with your library, or use separately on their own. You will learn how to:
8
-
9
-
* Retrieve a URL to download.
10
-
* Download a file and cache it on your disk.
8
+
* Specify a file to download from the Hub.
9
+
* Download and cache a file on your disk.
11
10
* Download all the files in a repository.
12
11
13
-
## hf_hub_url
14
-
15
-
Use [`hf_hub_url`] to retrieve the URL of a specific file to download by providing a `filename`.
[`cached_download`] is useful for downloading and caching a file on your local disk. Once stored in your cache, you don't have to redownload the file the next time you use it. [`cached_download`] is a hands-free solution for staying up to date with new file versions. When a downloaded file is updated in the remote repository, [`cached_download`] will automatically download and store it for you.
52
+
[`cached_download`] is used to download and cache a file on your local disk. Once a file
53
+
is stored in your cache, you don't have to redownload it the next time you use it.
54
+
[`cached_download`] is a hands-free solution for staying up to date with new file
55
+
versions. When a downloaded file is updated in the remote repository,
56
+
[`cached_download`] will automatically download and store it.
49
57
50
-
Begin by retrieving your file URL with [`hf_hub_url`], and then pass the specified URL to [`cached_download`] to download the file:
58
+
Begin by retrieving the file URL with [`hf_hub_url`], and then pass the specified URL to
[`hf_hub_url`] and [`cached_download`] work hand in hand to download a file. This is precisely how [`hf_hub_download`] from the tutorial works! [`hf_hub_download`] is simply a wrapper that calls both [`hf_hub_url`] and [`cached_download`].
68
+
[`hf_hub_url`] and [`cached_download`] work hand-in-hand to download a file. This is
69
+
such a standard workflow that [`hf_hub_download`] is a wrapper that calls both of these
[`snapshot_download`] downloads an entire repository at a given revision. Like [`cached_download`], all downloaded files are cached on your local disk. However, even if only a single file is updated, the entire repository will be redownloaded.
79
+
[`snapshot_download`] downloads an entire repository at a given revision. Like
80
+
[`cached_download`], all downloaded files are cached on your local disk. However, even
81
+
if only a single file is updated, the entire repository will be redownloaded.
69
82
70
83
Download a whole repository as shown in the following:
71
84
@@ -75,20 +88,27 @@ Download a whole repository as shown in the following:
[`snapshot_download`] downloads the latest revision by default. If you want a specific repository revision, use the `revision` parameter as shown with [`hf_hub_url`].
91
+
[`snapshot_download`] downloads the latest revision by default. If you want a specific
92
+
repository revision, use the `revision` parameter:
In general, it is usually better to manually download files with [`hf_hub_download`] (if you already know the file name) to avoid re-downloading an entire repository. [`snapshot_download`] is helpful when your library's downloading utility is a helper, and unaware of which files need to be downloaded.
99
+
In general, it is usually better to download files with [`hf_hub_download`] - if you
100
+
already know the file name - to avoid redownloading an entire repository.
101
+
[`snapshot_download`] is helpful when you are unaware of which files to download.
102
+
103
+
However, you don't always want to download the contents of an entire repository with
104
+
[`snapshot_download`]. Even if you don't know the file name, you can download specific
105
+
files if you know the file type with `allow_regex` and `ignore_regex`. Use the
106
+
`allow_regex` and `ignore_regex` arguments to specify which files to download. These
107
+
parameters accept either a single regex or a list of regexes.
86
108
87
-
However, you don't want to always download the contents of an entire repository with [`snapshot_download`]. Even if you don't know the file name and only know the file type, you can download specific files with `allow_regex` and `ignore_regex`.
88
-
Use the `allow_regex` and `ignore_regex` arguments to specify
89
-
which files to download.
90
-
`allow_regex` and `ignore_regex` accept either a single regex or a list of regexes.
91
-
The regex matching is based on [`fnmatch`](https://docs.python.org/3/library/fnmatch.html) which means it provides support for Unix shell-style wildcards.
109
+
The regex matching is based on
110
+
[`fnmatch`](https://docs.python.org/3/library/fnmatch.html), which provides support for
111
+
Unix shell-style wildcards.
92
112
93
113
For example, you can use `allow_regex` to only download JSON configuration files:
94
114
@@ -97,17 +117,17 @@ For example, you can use `allow_regex` to only download JSON configuration files
On the other hand, `ignore_regex` can be used to exclude certain files from being downloaded. The following example ignores the `.msgpack` and `.h5` file extensions:
101
-
or `.h5` extensions, you could make use of `ignore_regex`:
120
+
On the other hand, `ignore_regex` can exclude certain files from being downloaded. The
121
+
following example ignores the `.msgpack` and `.h5` file extensions:
Copy file name to clipboardExpand all lines: docs/source/how-to-inference.mdx
+12-9Lines changed: 12 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,23 @@
1
-
---
2
-
title: How to programmatically access the Inference API
3
-
---
1
+
# Access the Inference API
4
2
5
-
# How to programmatically access the Inference API
3
+
The Inference API provides fast inference for your hosted models. The Inference API can be accessed via usual HTTP requests with your favorite programming language, but the `huggingface_hub` library has a client wrapper to access the Inference API programmatically. This guide will show you how to make calls to the Inference API with the `huggingface_hub` library.
6
4
7
-
The Inference API provides fast inference for your hosted models. The Inference API can be accessed via usual HTTP requests with your favorite programming languages, but the `huggingface_hub` library has a client wrapper to access the Inference API programmatically. This guide will show you how to make calls to the Inference API with the `huggingface_hub` library.
5
+
<Tip>
8
6
9
-
**If you want to make the HTTP calls directly, please refer to [Accelerated Inference API Documentation](https://api-inference.huggingface.co/docs/python/html/index.html) or to the sample snippets visible on every supported model page.**
7
+
If you want to make the HTTP calls directly, please refer to [Accelerated Inference API Documentation](https://api-inference.huggingface.co/docs/python/html/index.html) or to the sample snippets visible on every supported model page.
8
+
9
+
</Tip>
10
10
11
11
12
12
13
-
Begin by creating an instance of the `InferenceApi` with a specific model repository ID. You can find your `API_TOKEN` under Settings from your Hugging Face account. The `API_TOKEN` will allow you to send requests to the Inference API.
13
+
Begin by creating an instance of the [`InferenceApi`] with the model repository ID of the model you want to use. You can find your `API_TOKEN` under Settings from your Hugging Face account. The `API_TOKEN` will allow you to send requests to the Inference API.
The pipeline is determined from the metadata in the model card and configuration files (see [here](https://huggingface.co/docs/hub/main#how-is-a-models-type-of-inference-api-and-widget-determined) for more details). For example, when using the [bert-base-uncased](https://huggingface.co/bert-base-uncased) model, the Inference API can automatically infer that this model should be used for a `fill-mask` task.
20
+
The metadata in the model card and configuration files (see [here](https://huggingface.co/docs/hub/main#how-is-a-models-type-of-inference-api-and-widget-determined) for more details) determines the pipeline type. For example, when using the [bert-base-uncased](https://huggingface.co/bert-base-uncased) model, the Inference API can automatically infer that this model should be used for a `fill-mask` task.
@@ -48,5 +48,8 @@ Some tasks may require additional parameters (see [here](https://api-inference.h
48
48
Some models may support multiple tasks. The `sentence-transformers` models can complete both `sentence-similarity` and `feature-extraction` tasks. Specify which task you want to perform with the `task` parameter:
0 commit comments