diff --git a/docs/assets/hub/icon-space.svg b/docs/assets/hub/icon-space.svg new file mode 100644 index 0000000000..62423193f1 --- /dev/null +++ b/docs/assets/hub/icon-space.svg @@ -0,0 +1,46 @@ + \ No newline at end of file diff --git a/docs/assets/hub/new-space.gif b/docs/assets/hub/new-space.gif new file mode 100644 index 0000000000..a856331858 Binary files /dev/null and b/docs/assets/hub/new-space.gif differ diff --git a/docs/hub/_sections.yml b/docs/hub/_sections.yml index bdcf1efd7a..06e8a23363 100644 --- a/docs/hub/_sections.yml +++ b/docs/hub/_sections.yml @@ -18,3 +18,6 @@ - local: endpoints title: Hub API Endpoints + +- local: spaces + title: Spaces documentation (beta) diff --git a/docs/hub/endpoints.md b/docs/hub/endpoints.md index 2455efb443..c93de91cda 100644 --- a/docs/hub/endpoints.md +++ b/docs/hub/endpoints.md @@ -5,7 +5,7 @@ title: Hugging Face Hub Endpoints # Hugging Face Hub API Endpoints -We have open endpoints that you can use to retrieve information from the Hub as well as perform certain actions such as creating model repos. We offer a wrapper Python library, [`huggingface_hub`](https://github.com/huggingface/huggingface_hub), that allows easy access to these endpoints. We also provide a webhook to receive real-time incremental info about models. Enjoy! +We have open endpoints that you can use to retrieve information from the Hub as well as perform certain actions such as creating model repos. We offer a wrapper Python library, [`huggingface_hub`](https://github.com/huggingface/huggingface_hub), that allows easy access to these endpoints. We also provide a [webhook](#webhook) to receive real-time incremental info about models. Enjoy! ## Endpoints table diff --git a/docs/hub/spaces.md b/docs/hub/spaces.md new file mode 100644 index 0000000000..62c3d7e1ff --- /dev/null +++ b/docs/hub/spaces.md @@ -0,0 +1,95 @@ +--- +title: Documentation for Spaces +--- + +

How to get started with Spaces

+ +> ⚠️ This feature is currently in private beta, reach out to [julien-c](https://huggingface.co/julien-c) if you'd like to try it out ⚠️ + +## What are Spaces? + +Spaces are a simple way to host a ML demo app, directly on your user profile or your organization’s hf.co profile. + +We support two awesome SDKs that let you build cool apps in Python: **[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: + +![/docs/assets/hub/new-space.gif](/docs/assets/hub/new-space.gif) + +Under the hood, we are storing your code inside a hf.co-hosted git repository, similar to what we're doing for models and datasets. So the same tools you're already used to (`git` and `git-lfs`) will also work for Spaces. + +We then deploy a containerized version of your code on our Infra, each time you commit. More details below! + + + +## Should I use Streamlit or Gradio? + +We recommend you try both as they're both really awesome! 😎 + +Streamlit's documentation is at https://docs.streamlit.io/, and Gradio's doc is https://gradio.app/docs. + +In the default environment, we're currently running version `"0.79.0"` of Streamlit and version `"2.0.9"` of Gradio. + +Our 2 cents: +- **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). +- **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). + +You can also take a look at some sample apps on the [Spaces directory](https://huggingface.co/spaces) (⚠️ Note: not live yet!) to make up your mind. + + + +Finally, we've been thinking of providing a way to run **custom apps**, for instance Python server code for the backend + a unified set of widgets/frontend JS code, or even custom Docker image serving. Do get in touch if you would like to build something more custom. + + +## What are the pre-installed dependencies in the default environment? + +In addition to the Streamlit or Gradio SDK, the environment we run your app in includes the following Python libraries out-of-the-box: +- [`huggingface_hub`](https://github.com/huggingface/huggingface_hub), so you can list models, query the hf.co API, etc. **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, and it's also consuming less computing resources, which is always nice 🌎. + +- [`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. +- [`datasets`](https://github.com/huggingface/datasets) so that you can easily fetch or display data from inside your app. + +## How can I install other dependencies? + +If you need any other Python package, you can simply add a `requirements.txt` at the root of your repo. + +A custom environment will be created on the fly by the Spaces runtime engine. + +We do not support installing `apt-get` dependencies yet, but it's on our roadmap. + +## What are the RAM and CPU or GPU limitations? + +Each environment is currently limited to 16GB RAM and 8 CPU cores. + +Some Spaces can have one T4 GPU on a case-by-case basis, contact us if you need one. + +## How does it work? + +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 🙂. + +## Secret management + +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 for your Space repo and you'll be able to input key/secret pairs. + +Those 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 env variables in other cases. + +## Streamlit advanced features + +We support those Streamlit features transparently: +- `st.experimental_get_query_params()` and `st.experimental_set_query_params(**parameter)` to manage app state in the url +- if something doesn't work, please reach out. + +## Can I use the Spaces logo to link to my app from my website? + +Yes that would be great, here's the logo in SVG: + + + + +## Why did you build this? + +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.). + +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. + +This project's goal is to experiment with an extensible way for users and organizations to host demos/apps on huggingface.co, in a more productized/scalable way than we’ve done in the past.