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
* ✨ reorganize spaces docs
* let's try to remove some 🤗s
* first section
* re-add changelog
there are links to it from other places in the website so we shouldn't remove it @stevhliu
* final tweaks
Co-authored-by: Julien Chaumond <[email protected]>
@@ -10,128 +10,70 @@ Spaces are a simple way to host ML demo apps directly on your profile or your or
10
10
11
11
We support two awesome SDKs that let you build cool apps in Python in a matter of minutes: **[Streamlit](https://streamlit.io/)** and **[Gradio](https://gradio.app/)**.
**To get started**, simply click on [New Space](https://huggingface.co/new-space) in the top navigation menu, create a new repo of type `Space`, and pick your SDK.
16
14
17
15
Under the hood, Spaces stores your code inside a git repository, just like the model and dataset repositories. Thanks to this, the same tools you're already used to (`git` and `git-lfs`) also work for Spaces.
18
16
19
-
## Should I use Streamlit or Gradio?
20
-
21
-
We recommend you try both because they're really awesome! 😎
22
-
23
-
Streamlit's documentation is at https://docs.streamlit.io/ and Gradio's doc is at https://gradio.app/getting_started.
24
-
25
-
In the default environment, we're currently running version `"1.0.0"` of Streamlit and the latest version of Gradio.
17
+
The default Spaces environment comes with several pre-installed dependencies:
26
18
27
-
See [Configuration](#configuration) section for more infos on SDK versions.
28
-
29
-
Our 2 cents:
30
-
31
-
-**Gradio** is great if you want to build a super-easy-to-use interface to run a model from just the list of its inputs and its outputs. The Gradio team wrote a great [tutorial on our blog about building GUIs for Hugging Face models](https://huggingface.co/blog/gradio).
32
-
-**Streamlit** gives you more freedom to build a full-featured Web app from Python, in a _reactive_ way (meaning that code gets re-run when the state of the app changes). We wrote a short [blog post](https://huggingface.co/blog/streamlit-spaces) about using models and datasets with Spaces using Streamlit.
33
-
34
-
You can also take a look at some sample apps on the [Spaces directory](https://huggingface.co/spaces) to make up your mind.
35
-
36
-
[](https://huggingface.co/spaces)
19
+
*[`huggingface_hub`](https://github.com/huggingface/huggingface_hub) allows you to download models from the Hub and programmatically access the Inference API from your Space. If you choose to instantiate the model in your app with our Inference API, you can benefit from the built-in acceleration optimizations. This option also consumes less computing resources, which is always nice for the environment! 🌎
37
20
38
-
If Streamlit and Gradio don't suit your needs, please get in touch with us. We're working on providing mechanisms to run **custom apps** with custom Python server code and a unified set of frontend JS code. Docker image serving is also on the works. If this sounds interesting, [reach out to us]((#how-can-i-contact-you)).
21
+
Refer to this [page](https://huggingface.co/docs/hub/how-to-inference) for more information on how to programmatically access the Inference API.
39
22
40
-
## What are the pre-installed dependencies in the default environment?
23
+
*[`requests`](https://docs.python-requests.org/en/master/) is useful for calling third-party APIs from your app.
41
24
42
-
In addition to the Streamlit or Gradio SDK, the environment we run your app in includes the following Python libraries out-of-the-box:
25
+
*[`datasets`](https://github.com/huggingface/datasets) allows you to fetch or display datasets from inside your app easily.
43
26
44
-
-[`huggingface_hub`](https://github.com/huggingface/huggingface_hub), so you can download files (such as models) from the Hub, query the hf.co API, etc.
27
+
Each Spaces environment is limited to 16GB RAM and 8 CPU cores. Organization [subscribers](https://huggingface.co/pricing) (Lab, Startup, and Enterprise) can access Spaces with one T4 GPU on a case-by-case basis. Please email us at **website at huggingface.co** or let us know on [Twitter](https://twitter.com/huggingface) if you need one.
45
28
46
-
**You can also use this to call our Accelerated Inference API from your Space**. If your app instantiates a model to run inference on, consider calling the Inference API instead, because you'll then leverage the acceleration optimizations we already built. This will also consuming less computing resources, which is always nice 🌎. See this [page](/docs/hub/how-to-inference) for more information on how to programmatically access the Inference API.
29
+
## Streamlit and Gradio
47
30
48
-
-[`requests`](https://docs.python-requests.org/en/master/) the famous HTTP request library, useful if you want to call a third-party API from your app.
49
-
-[`datasets`](https://github.com/huggingface/datasets) so that you can easily fetch or display data from inside your app.
31
+
Spaces support [Streamlit](https://streamlit.io/) and [Gradio](https://gradio.app/) for quickly building apps in Python. The default environment runs version `"1.0.0"` of Streamlit and the latest version of Gradio. We recommend you try both because they're really awesome! Here are some of our thoughts on Streamlit and Gradio:
50
32
51
-
## How can I install other dependencies?
33
+
***Gradio** provides an easy and intuitive interface for running a model from a list of inputs, and displaying the outputs. For more details, take a look at this [tutorial](https://huggingface.co/blog/gradio) from the Gradio team about building GUIs for Hugging Face models.
52
34
53
-
If you need any other Python package, you can simply add a `requirements.txt` at the root of your repo.
35
+
***Streamlit** gives users more freedom to build a full-featured web app with Python in a *reactive* way. Your code is rerun each time the state of the app changes. Streamlit is also great for data visualization and supports several charting libraries such as Bokeh, Plotly, and Altair. Read our [blog post](https://huggingface.co/blog/streamlit-spaces) about building and hosting Streamlit apps in Spaces.
54
36
55
-
A custom environment will be created on the fly by the Spaces runtime engine.
37
+
💡 If you need want to learn more about Streamlit and Gradio, refer to the [Streamlit documentation](https://docs.streamlit.io/) and [Gradio documentation](https://gradio.app/getting_started).
56
38
57
-
We also support Debian dependencies: add a `packages.txt` file at the root of your repo and list all your dependencies, one per line (each line will go through `apt-get install`)
39
+
For more inspiration, take a look at some of the sample apps in the [Spaces directory](https://huggingface.co/spaces) to get a better idea of what Streamlit and Gradio can do.
58
40
59
-
## What are the RAM and CPU or GPU limitations?
41
+
[](https://huggingface.co/spaces)
60
42
61
-
Each environment is currently limited to 16GB RAM and 8 CPU cores.
43
+
## Using Spaces
62
44
63
-
For Pro or Organization (Lab or Startup plan) subscribers, Spaces can have one T4 GPU on a case-by-case basis, [contact us](#how-can-i-contact-you) if you need one.
45
+
Create a Space by clicking on [New Space](https://huggingface.co/new-space) under your profile picture in the top navigation bar. Next, create a repository of type `Space`, and then you can select whether you want to use Streamlit or Gradio.
We deploy a containerized version of your code on our Infra, each time you commit. As a sidenote, we have many cool infra challenges to solve, if you'd like to help us, please consider [reaching out](#how-can-i-contact-you)!
49
+
### Install other dependencies
68
50
69
-
## Secret management
51
+
If you need other Python packages to run your app, add it to a **requirements.txt** file at the root of your repository. Spaces runtime engine will create a custom environment on-the-fly.
70
52
71
-
If your app needs any secret keys or tokens to run, you do not want to hardcode them inside your code! Instead, head over to the settings page of your Space repo, and you'll be able to input key/secret pairs.
53
+
Debian dependencies are also supported. Add a **package.txt** file at the root of your repository, and list all your dependencies in it. Each dependency should be on a separate line, and each line will be read and installed by `apt-get install`.
72
54
73
-
Secrets will be exposed to your app using the [Streamlit Secrets](https://blog.streamlit.io/secrets-in-sharing-apps/) feature if it's a Streamlit app, or as environment variables in other cases.
55
+
### Manage secrets
74
56
57
+
If your app requires secret keys or tokens, don't hard-code them inside your app! Instead, go to the **Settings** page of your Space repository and enter your secrets there. The secrets will be exposed to your app with [Streamlit Secrets Management](https://blog.streamlit.io/secrets-in-sharing-apps/) if you use Streamlit, and as environment variables in other cases.
75
58
76
-
## I am having issues with Streamlit versions!
59
+
77
60
78
-
The Streamlit version is not configured in the `requirements.txt` file, but rather in the README metadata config through the `sdk_version` setting. Not all Streamlit versions are supported. Refer to the [reference section](#reference) for more information about which versions are supported.
61
+
### Custom HTML
79
62
80
-
## Can I use my own HTML instead of Streamlit or Gradio?
63
+
Spaces also accommodate custom HTML for your app instead of using Streamlit or Gradio. Set `sdk: static` inside the `YAML` block at the top of your Spaces **README.md** file. Then you can place your HTML code within an **index.html** file.
81
64
82
-
Although we strongly encourage you to use Streamlit and Gradio, you can also use your own HTML
83
-
code by defining `sdk: static` and having the HTML within an `index.html` file. Here are some examples:
65
+
Here are some examples of Spaces using custom HTML:
84
66
85
-
*[Smarter NPC](https://huggingface.co/spaces/mishig/smarter_npc): Display a PlayCanvas project with an iframe.
67
+
*[Smarter NPC](https://huggingface.co/spaces/mishig/smarter_npc): Display a PlayCanvas project with an iframe in Spaces.
86
68
*[Huggingfab](https://huggingface.co/spaces/pierreant-p/huggingfab): Display a Sketchfab model in Spaces.
87
69
88
-
Please [get in touch](#how-can-i-contact-you) if you have an idea for cool static Spaces.
89
-
90
-
91
-
## Building an organization card
92
-
93
-
Create an organization card to help users learn more about what your organization is working on and how users can use your libraries, models, datasets, and Spaces. Build an organization card by creating a static README Space with HTML. As an example, take a look at the [Amazon](https://huggingface.co/spaces/amazon/README/blob/main/README.md) and [spaCy](https://huggingface.co/spaces/spacy/README/blob/main/README.md) organization cards.
Streamlit has built-in support for Bokeh with the `st.bokeh_chart` component.
102
-
103
-
## How should I link my Spaces demo in my GitHub repo?
70
+
💌 Feel free to [contact us](#contact) if you are interested in building custom apps without Streamlit or Gradio. Our team is working on creating mechanisms for running custom apps with Python server code with a unified set of frontend JS code and serving Docker images.
104
71
105
-
We have a badge that you can use, just replace the linked url with the correct one:
72
+
### Configure Spaces settings
106
73
107
-
[](https://huggingface.co/spaces/your_user/your_space)
74
+
Configure your Space's appearance and other settings inside the `YAML` block at the top of the **README.md** file at the root of the repository. For example, if you want to create a Space with Gradio named `Demo Space` with a yellow to orange gradient thumbnail:
108
75
109
-
```
110
-
[](https://huggingface.co/spaces/your_user/your_space)
111
-
```
112
-
113
-
## Can I use the Spaces logo to link to my app from my website?
In the past few years, our team, in collaboration with other research groups, has built a number of demo apps for some cool new models or methods (PPLM, RAG, zero-shot, ExBERT, etc.).
122
-
123
-
We host [widgets](https://huggingface-widgets.netlify.app/) for every model on the Hub, but in some cases (for instance if you want to compare two models) there is a need for a demo app that can't simply be implemented in a widget, so we needed something more flexible.
124
-
125
-
This project's goal is to build an extensible way for users and organizations to host demos/apps on huggingface.co in a more productized and scalable way.
126
-
127
-
## Configuration
128
-
129
-
All the settings of your Space are stored inside a YAML block on top of the `README.md` file at the root of the repository.
130
-
131
-
To modify those settings, you can edit this file, either by pushing to the repo via command-line, or directly on the hub
132
-
133
-
Sample `README.md` file :
134
-
```Markdown
76
+
```yaml
135
77
---
136
78
title: Demo Space
137
79
emoji: 🤗
@@ -143,45 +85,38 @@ pinned: false
143
85
---
144
86
```
145
87
146
-
### Reference
88
+
For additional settings, refer to the [Reference](#reference) section.
147
89
148
-
**`title`** : _string_
149
-
Display title for the Space
90
+
### Organization card
150
91
151
-
**`emoji`** : _string_
152
-
Space emoji (emoji-only character allowed)
92
+
Create an organization card to help users learn more about what your organization is working on and how users can use your libraries, models, datasets, and Spaces. Build an organization card by setting `sdk: static` to create a static **README** Space with HTML. As an example, take a look at:
153
93
154
-
**`colorFrom`** : _string_
155
-
Color for Thumbnail gradient (red, yellow, green, blue, indigo, purple, pink, gray)
Color for Thumbnail gradient (red, yellow, green, blue, indigo, purple, pink, gray)
97
+
### Manage app with Github Actions
159
98
160
-
**`sdk`** : _string_
161
-
Can be either `gradio`, `streamlit` or `static`
99
+
Keep your app in sync with your Github repository with Github Actions. For files larger than 10MB, Spaces requires Git-LFS. If you don't want to use Git-LFS, you may need to review your files and check your history. Use a tool like [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/) to remove any large files from your history. BFG Repo-Cleaner will keep a local copy of your repository as a backup.
162
100
163
-
**`sdk_version`** : _string_
164
-
Only applicable for `streamlit` SDK. Currently available versions are :
First, you should setup your GitHub repository and Spaces app together. Add your Spaces app as an additional remote to your existing Git repository.
166
102
167
-
**`app_file`** : _string_
168
-
Path to your main application file (which contains either `gradio` or `streamlit` Python code).
169
-
Path is relative to the root of the repository.
103
+
```bash
104
+
git remote add space https://huggingface.co/spaces/FULL_SPACE_NAME
105
+
```
170
106
171
-
**`pinned`** : _boolean_
172
-
Whether the Space stays on top of your list.
107
+
Then force push to sync everything for the first time:
173
108
174
-
## How can I manage my app through Github
109
+
```bash
110
+
git push --force space main
111
+
```
175
112
176
-
Keep your app in sync with your GitHub repository with GitHub Actions:
113
+
Next, setup a GitHub Action to push your main branch to Spaces. In the example below:
177
114
178
-
- We require Git LFS for files above 10MB so you may need to review your files if you don't want to use Git LFS. This includes your history. You can use handy tools such as [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/) to remove the large files from your history (keep a local copy of your repository for backup).
179
-
- Set your GitHub repository and your Spaces app initially in sync: to add your Spaces app as an additional remote to your existing git repository, you can use the command `git remote add space https://huggingface.co/spaces/FULL_SPACE_NAME`. You can then force-push to sync everything for the first time: `git push --force space main`
180
-
- Set up a GitHub Action to push your GitHub main branch automatically to Spaces: replace `HF_USERNAME` with your Hugging Face username, `FULL_SPACE_NAME` with your Spaces name, and [create a Github secret](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-an-environment)`HF_TOKEN` containing your Hugging Face API token.
115
+
* Replace `HF_USERNAME` with your username and `FULL_SPACE_NAME` with your Space name.
116
+
* Create a [Github secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-an-environment) with your `HF_TOKEN`. You can find your Hugging Face API token under **API Tokens** on your Hugging Face profile.
181
117
182
118
```yaml
183
119
name: Sync to Hugging Face hub
184
-
185
120
on:
186
121
push:
187
122
branches: [main]
@@ -202,11 +137,11 @@ jobs:
202
137
run: git push https://HF_USERNAME:[email protected]/spaces/FULL_SPACE_NAME main
203
138
```
204
139
205
-
- Create an action so file sizes are automatically checked on any new PR
140
+
Finally, create an Action that automatically checks the file size of any new pull request:
141
+
206
142
207
143
```yaml
208
144
name: Check file size
209
-
210
145
on: # or directly `on: [push]` to run the action on every push on any branch
filesizelimit: 10485760# = 10MB, so we can sync to HF spaces
225
-
159
+
filesizelimit: 10485760# this is 10MB so we can sync to HF Spaces
226
160
```
227
161
228
-
## How can I contact you?
162
+
## Troubleshoot
163
+
164
+
Issues may occur when you use an unsupported Streamlit version. The Streamlit version is not configured in the **requirements.txt** file but rather in the `YAML` settings through the `sdk_version` setting. Not all Streamlit versions are supported. Check that you are using a supported version of Streamlit. Refer to the [reference section](#reference) for more information about supported versions.
165
+
166
+
## Contact
229
167
230
168
Feel free to ask questions on the [forum](https://discuss.huggingface.co/) if it's suitable for the community.
231
169
232
170
If you're interested in infra challenges, custom demos, GPUs, or something else, please reach out to us by sending an email to **website at huggingface.co**.
233
171
234
-
You can also tag us [on Twitter](https://twitter.com/huggingface)!
172
+
You can also tag us [on Twitter](https://twitter.com/huggingface)! 🤗
173
+
174
+
---
175
+
176
+
## Reference
177
+
178
+
**`title`** : _string_
179
+
Display title for the Space.
180
+
181
+
**`emoji`** : _string_
182
+
Space emoji (emoji-only character allowed).
183
+
184
+
**`colorFrom`** : _string_
185
+
Color for Thumbnail gradient (red, yellow, green, blue, indigo, purple, pink, gray).
186
+
187
+
**`colorTo`** : _string_
188
+
Color for Thumbnail gradient (red, yellow, green, blue, indigo, purple, pink, gray).
189
+
190
+
**`sdk`** : _string_
191
+
Can be either `gradio`, `streamlit` or `static`.
192
+
193
+
**`sdk_version`** : _string_
194
+
Only applicable for `streamlit` SDK. Currently available versions are :
0 commit comments