mirror/gradio
2
0
Fork 0
mirror of https://github.com/gradio-app/gradio.git synced 2025-03-31 12:20:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

Rewriting parts of the README and getting started guides for 4.0 (#6767)

Browse Source 
* doc rewrite

* changes

* changes

* tip

* changes

* notebook

* add changeset

* history

* add

* quickstart done

* readme

* changes

* quickstart

* changes

* reorder

* link

* changes

* changes

* changes

* quickstart done

* readme

* quickstart

* quickstart'

* moving around

* spaces

* readme

* guides

* guides

* links

* readme

* readme

* readme

* readme

* readme

* readme

* readme

* readme

* readme

* readme

* email address

* add changeset

* shorten quickstart

* readme

* Update README.md

* readme

* changes

* Update guides/01_getting-started/01_quickstart.md

Co-authored-by: Ali Abdalla <ali.si3luwa@gmail.com>

* Update guides/01_getting-started/01_quickstart.md

Co-authored-by: Ali Abdalla <ali.si3luwa@gmail.com>

* Update guides/01_getting-started/01_quickstart.md

Co-authored-by: Ali Abdalla <ali.si3luwa@gmail.com>

* changes

* changes

* remove gr.Interface.load

* guides

* changes

* more changes

* changes

* sharing

* concurrency

* changes

* changes

* components

* key features

* event listeners

* features

* notebook

* test

* guides

* changes

* changes

* changes

* transitions

* readme links

* links

* links

* guides

* new gif

* add gif

* update gif

* Update guides/02_building-interfaces/01_more-on-examples.md

* Update guides/03_building-with-blocks/01_blocks-and-event-listeners.md

* Update guides/01_getting-started/01_quickstart.md

Co-authored-by: Ali Abdalla <ali.si3luwa@gmail.com>

* Update guides/01_getting-started/02_key-features.md

Co-authored-by: Ali Abdalla <ali.si3luwa@gmail.com>

* Update guides/01_getting-started/02_key-features.md

Co-authored-by: Ali Abdalla <ali.si3luwa@gmail.com>

* Update guides/02_building-interfaces/00_the-interface-class.md

Co-authored-by: Ali Abdalla <ali.si3luwa@gmail.com>

* Update guides/01_getting-started/01_quickstart.md

Co-authored-by: Hannah <hannahblair@users.noreply.github.com>

* Update guides/01_getting-started/02_key-features.md

Co-authored-by: Hannah <hannahblair@users.noreply.github.com>

* Update guides/01_getting-started/02_key-features.md

Co-authored-by: Hannah <hannahblair@users.noreply.github.com>

* changes

* replace space

* changes

---------

Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>
Co-authored-by: Ali Abdalla <ali.si3luwa@gmail.com>
Co-authored-by: Hannah <hannahblair@users.noreply.github.com>
This commit is contained in:
Abubakar Abid 2023-12-20 11:07:48 -08:00 committed by GitHub
parent e528f98b88
commit 7bb561a294
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
48 changed files with 688 additions and 1294 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
.changeset/quick-chairs-check.md Normal file
View File

@ -0,0 +1,7 @@
---
"gradio": patch
"gradio_client": patch
"website": patch
---
fix:Rewriting parts of the README and getting started guides for 4.0

320
README.md
View File

@ -3,7 +3,6 @@
<div align="center">
[<img src="readme_files/gradio.svg" alt="gradio" width=400>](https://gradio.app)<br>
<em>Build & share delightful machine learning apps easily</em>
[![gradio-backend](https://github.com/gradio-app/gradio/actions/workflows/backend.yml/badge.svg)](https://github.com/gradio-app/gradio/actions/workflows/backend.yml)
[![gradio-ui](https://github.com/gradio-app/gradio/actions/workflows/ui.yml/badge.svg)](https://github.com/gradio-app/gradio/actions/workflows/ui.yml)
@ -23,42 +22,90 @@
# Gradio: Build Machine Learning Web Apps — in Python
Gradio is an open-source Python library that is used to build machine learning and data science demos and web applications.
With Gradio, you can quickly create a beautiful user interface around your machine learning models or data science workflow and let people "try it out" by dragging-and-dropping in their own images,
pasting text, recording their own voice, and interacting with your demo, all through the browser.
![Interface montage](readme_files/header-image.jpg)
Gradio is an open-source Python package that allows you to quickly **build** a demo or web application for your machine learning model, API, or any arbitary Python function. You can then **share** a link to your demo or web application in just a few seconds using Gradio's built-in sharing features. *No JavaScript, CSS, or web hosting experience needed!*
Gradio is useful for:
<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/gradio-guides/lcm-screenshot-3.gif" style="padding-bottom: 10px">
- **Demoing** your machine learning models for clients/collaborators/users/students.
It just takes a few lines of Python to create a beautiful demo like the one above, so let's get started 💫
- **Deploying** your models quickly with automatic shareable links and getting feedback on model performance.
### Installation
- **Debugging** your model interactively during development using built-in input manipulation tools tools.
**Prerequisite**: Gradio requires [Python 3.8 or higher](https://www.python.org/downloads/)
## Quickstart
**Prerequisite**: Gradio requires Python 3.8 or higher, that's all!
We recommend installing Gradio using `pip`, which is included by default in Python. Run this in your terminal or command prompt:
### What Does Gradio Do?
One of the _best ways to share_ your machine learning model, API, or data science workflow with others is to create an **interactive app** that allows your users or colleagues to try out the demo in their browsers.
Gradio allows you to **build demos and share them, all in Python.** And usually in just a few lines of code! So let's get started.
### Hello, World
To get Gradio running with a simple "Hello, World" example, follow these three steps:
1\. Install Gradio using pip:
```bash
```
pip install gradio
```
2\. Run the code below as a Python script or in a Jupyter Notebook (or [Google Colab](https://colab.research.google.com/drive/18ODkJvyxHutTN0P5APWyGFO_xwNcgHDZ?usp=sharing)):
> [!TIP]
> it is best to install Gradio in a virtual environment. Detailed installation instructions for all common operating systems <a href="https://www.gradio.app/main/guides/installing-gradio-in-a-virtual-environment">are provided here</a>.
### Building Your First Demo
You can run Gradio in your favorite code editor, Jupyter notebook, Google Colab, or anywhere else you write Python. Let's write your first Gradio app:
```python
import gradio as gr
def greet(name, intensity):
return "Hello " * intensity + name + "!"
demo = gr.Interface(
fn=greet,
inputs=["text", "slider"],
outputs=["text"],
)
demo.launch()
```
> [!TIP]
> We shorten the imported name from <code>gradio</code> to <code>gr</code> for better readability of code. This is a widely adopted convention that you should follow so that anyone working with your code can easily understand it.
Now, run your code. If you've written the Python code in a file named, for example, `app.py`, then you would run `python app.py` from the terminal.
The demo below will open in a browser on [http://localhost:7860](http://localhost:7860) if running from a file. If you are running within a notebook, the demo will appear embedded within the notebook.
![`hello_world_4` demo](demo/hello_world_4/screenshot.gif)
Type your name in the textbox on the left, drag the slider, and then press the Submit button. You should see a friendly greeting on the right.
> [!TIP]
> When developing locally, you can run your Gradio app in <strong>hot reload mode</strong>, which automatically reloads the Gradio app whenever you make changes to the file. To do this, simply type in <code>gradio</code> before the name of the file instead of <code>python</code>. In the example above, you would type: `gradio app.py` in your terminal. Learn more about hot reloading in the <a href="https://www.gradio.app/guides/developing-faster-with-reload-mode">Hot Reloading Guide</a>.
**Understanding the `Interface` Class**
You'll notice that in order to make your first demo, you created an instance of the `gr.Interface` class. The `Interface` class is designed to create demos for machine learning models which accept one or more inputs, and return one or more outputs.
The `Interface` class has three core arguments:
- `fn`: the function to wrap a user interface (UI) around
- `inputs`: the Gradio component(s) to use for the input. The number of components should match the number of arguments in your function.
- `outputs`: the Gradio component(s) to use for the output. The number of components should match the number of return values from your function.
The `fn` argument is very flexible -- you can pass *any* Python function that you want to wrap with a UI. In the example above, we saw a relatively simple function, but the function could be anything from a music generator to a tax calculator to the prediction function of a pretrained machine learning model.
The `input` and `output` arguments take one or more Gradio components. As we'll see, Gradio includes more than [30 built-in components](https://www.gradio.app/docs/components) (such as the `gr.Textbox()`, `gr.Image()`, and `gr.HTML()` components) that are designed for machine learning applications.
> [!TIP]
> For the `inputs` and `outputs` arguments, you can pass in the name of these components as a string (`"textbox"`) or an instance of the class (`gr.Textbox()`).
If your function accepts more than one argument, as is the case above, pass a list of input components to `inputs`, with each input component corresponding to one of the arguments of the function, in order. The same holds true if your function returns more than one value: simply pass in a list of components to `outputs`. This flexibility makes the `Interface` class a very powerful way to create demos.
We'll dive deeper into the `gr.Interface` on our series on [building Interfaces](https://www.gradio.app/main/guides/the-interface-class).
### Sharing Your Demo
What good is a beautiful demo if you can't share it? Gradio lets you easily share a machine learning demo without having to worry about the hassle of hosting on a web server. Simply set `share=True` in `launch()`, and a publicly accessible URL will be created for your demo. Let's revisit our example demo, but change the last line as follows:
```python
import gradio as gr
@ -66,233 +113,62 @@ import gradio as gr
def greet(name):
return "Hello " + name + "!"
demo = gr.Interface(fn=greet, inputs="text", outputs="text")
demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox")
demo.launch()
demo.launch(share=True) # Share your demo with just 1 extra parameter 🚀
```
When you run this code, a public URL will be generated for your demo in a matter of seconds, something like:
We shorten the imported name to `gr` for better readability of code using Gradio. This is a widely adopted convention that you should follow so that anyone working with your code can easily understand it.
👉 &nbsp; `https://a23dsf231adb.gradio.live`
3\. The demo below will appear automatically within the Jupyter Notebook, or pop in a browser on [http://localhost:7860](http://localhost:7860) if running from a script:
Now, anyone around the world can try your Gradio demo from their browser, while the machine learning model and all computation continues to run locally on your computer.
![`hello_world` demo](demo/hello_world/screenshot.gif)
To learn more about sharing your demo, read our dedicated guide on [sharing your Gradio application](https://www.gradio.app/guides/sharing-your-app).
When developing locally, if you want to run the code as a Python script, you can use the Gradio CLI to launch the application **in reload mode**, which will provide seamless and fast development. Learn more about reloading in the [Auto-Reloading Guide](https://gradio.app/developing-faster-with-reload-mode/).
```bash
gradio app.py
```
### An Overview of Gradio
Note: you can also do `python app.py`, but it won't provide the automatic reload mechanism.
So far, we've been discussing the `Interface` class, which is a high-level class that lets to build demos quickly with Gradio. But what else does Gradio do?
### The `Interface` Class
#### Chatbots with `gr.ChatInterface`
You'll notice that in order to make the demo, we created a `gr.Interface`. This `Interface` class can wrap any Python function with a user interface. In the example above, we saw a simple text-based function, but the function could be anything from music generator to a tax calculator to the prediction function of a pretrained machine learning model.
Gradio includes another high-level class, `gr.ChatInterface`, which is specifically designed to create Chatbot UIs. Similar to `Interface`, you supply a function and Gradio creates a fully working Chatbot UI. If you're interested in creating a chatbot, you can jump straight [our dedicated guide on `gr.ChatInterface`](https://www.gradio.app/guides/creating-a-chatbot-fast).
The core `Interface` class is initialized with three required parameters:
#### Custom Demos with `gr.Blocks`
- `fn`: the function to wrap a UI around
- `inputs`: which component(s) to use for the input (e.g. `"text"`, `"image"` or `"audio"`)
- `outputs`: which component(s) to use for the output (e.g. `"text"`, `"image"` or `"label"`)
Gradio also offers a low-level approach for designing web apps with more flexible layouts and data flows with the `gr.Blocks` class. Blocks allows you to do things like control where components appear on the page, handle complex data flows (e.g. outputs can serve as inputs to other functions), and update properties/visibility of components based on user interaction — still all in Python.
Let's take a closer look at these components used to provide input and output.
You can build very custom and complex applications using `gr.Blocks()`. For example, the popular image generation [Automatic1111 Web UI](https://github.com/AUTOMATIC1111/stable-diffusion-webui) is built using Gradio Blocks. We dive deeper into the `gr.Blocks` on our series on [building with Blocks](https://www.gradio.app/guides/blocks-and-event-listeners).
### Components Attributes
We saw some simple `Textbox` components in the previous examples, but what if you want to change how the UI components look or behave?
#### The Gradio Python & JavaScript Ecosystem
Let's say you want to customize the input text field — for example, you wanted it to be larger and have a text placeholder. If we use the actual class for `Textbox` instead of using the string shortcut, you have access to much more customizability through component attributes.
That's the gist of the core `gradio` Python library, but Gradio is actually so much more! Its an entire ecosystem of Python and JavaScript libraries that let you build machine learning applications, or query them programmatically, in Python or JavaScript. Here are other related parts of the Gradio ecosystem:
```python
import gradio as gr
* [Gradio Python Client](https://www.gradio.app/guides/getting-started-with-the-python-client) (`gradio_client`): query any Gradio app programmatically in Python.
* [Gradio JavaScript Client](https://www.gradio.app/guides/getting-started-with-the-js-client) (`@gradio/client`): query any Gradio app programmatically in JavaScript.
* [Gradio-Lite](https://www.gradio.app/guides/gradio-lite) (`@gradio/lite`): write Gradio apps in Python that run entirely in the browser (no server needed!), thanks to Pyodide.
* [Hugging Face Spaces](https://huggingface.co/spaces): the most popular place to host Gradio applications — for free!
def greet(name):
return "Hello " + name + "!"
### What's Next?
demo = gr.Interface(
fn=greet,
inputs=gr.Textbox(lines=2, placeholder="Name Here..."),
outputs="text",
)
demo.launch()
```
Keep learning about Gradio sequentially using the Gradio Guides, which include explanations as well as example code and embedded interactive demos. Next up: [key features about Gradio demos](https://www.gradio.app/guides/key-features).
![`hello_world_2` demo](demo/hello_world_2/screenshot.gif)
Or, if you already know the basics and are looking for something specific, you can search the more [technical API documentation](https://www.gradio.app/docs/).
### Multiple Input and Output Components
Suppose you had a more complex function, with multiple inputs and outputs. In the example below, we define a function that takes a string, boolean, and number, and returns a string and number. Take a look how you pass a list of input and output components.
```python
import gradio as gr
def greet(name, is_morning, temperature):
salutation = "Good morning" if is_morning else "Good evening"
greeting = f"{salutation} {name}. It is {temperature} degrees today"
celsius = (temperature - 32) * 5 / 9
return greeting, round(celsius, 2)
## Questions?
demo = gr.Interface(
fn=greet,
inputs=["text", "checkbox", gr.Slider(0, 100)],
outputs=["text", "number"],
)
demo.launch()
```
![`hello_world_3` demo](demo/hello_world_3/screenshot.gif)
You simply wrap the components in a list. Each component in the `inputs` list corresponds to one of the parameters of the function, in order. Each component in the `outputs` list corresponds to one of the values returned by the function, again in order.
### An Image Example
Gradio supports many types of components, such as `Image`, `DataFrame`, `Video`, or `Label`. Let's try an image-to-image function to get a feel for these!
```python
import numpy as np
import gradio as gr
def sepia(input_img):
sepia_filter = np.array([
[0.393, 0.769, 0.189],
[0.349, 0.686, 0.168],
[0.272, 0.534, 0.131]
])
sepia_img = input_img.dot(sepia_filter.T)
sepia_img /= sepia_img.max()
return sepia_img
demo = gr.Interface(sepia, gr.Image(width=200, height=200), "image")
demo.launch()
```
![`sepia_filter` demo](demo/sepia_filter/screenshot.gif)
When using the `Image` component as input, your function will receive a NumPy array with the shape `(height, width, 3)`, where the last dimension represents the RGB values. We'll return an image as well in the form of a NumPy array.
You can also set the datatype used by the component with the `type=` keyword argument. For example, if you wanted your function to take a file path to an image instead of a NumPy array, the input `Image` component could be written as:
```python
gr.Image(type="filepath", shape=...)
```
Also note that our input `Image` component comes with an edit button 🖉, which allows for cropping and zooming into images. Manipulating images in this way can help reveal biases or hidden flaws in a machine learning model!
You can read more about the many components and how to use them in the [Gradio docs](https://gradio.app/docs).
### Chatbots
Gradio includes a high-level class, `gr.ChatInterface`, which is similar to `gr.Interface`, but is specifically designed for chatbot UIs. The `gr.ChatInterface` class also wraps a function but this function must have a specific signature. The function should take two arguments: `message` and then `history` (the arguments can be named anything, but must be in this order)
- `message`: a `str` representing the user's input
- `history`: a `list` of `list` representing the conversations up until that point. Each inner list consists of two `str` representing a pair: `[user input, bot response]`.
Your function should return a single string response, which is the bot's response to the particular user input `message`.
Other than that, `gr.ChatInterface` has no required parameters (though several are available for customization of the UI).
Here's a toy example:
```python
import random
import gradio as gr
def random_response(message, history):
return random.choice(["Yes", "No"])
demo = gr.ChatInterface(random_response)
demo.launch()
```
![`chatinterface_random_response` demo](demo/chatinterface_random_response/screenshot.gif)
You can [read more about `gr.ChatInterface` here](https://gradio.app/guides/creating-a-chatbot-fast).
### Blocks: More Flexibility and Control
Gradio offers two approaches to build apps:
1\. **Interface** and **ChatInterface**, which provide a high-level abstraction for creating demos that we've been discussing so far.
2\. **Blocks**, a low-level API for designing web apps with more flexible layouts and data flows. Blocks allows you to do things like feature multiple data flows and demos, control where components appear on the page, handle complex data flows (e.g. outputs can serve as inputs to other functions), and update properties/visibility of components based on user interaction — still all in Python. If this customizability is what you need, try `Blocks` instead!
### Hello, Blocks
Let's take a look at a simple example. Note how the API here differs from `Interface`.
```python
import gradio as gr
def greet(name):
return "Hello " + name + "!"
with gr.Blocks() as demo:
name = gr.Textbox(label="Name")
output = gr.Textbox(label="Output Box")
greet_btn = gr.Button("Greet")
greet_btn.click(fn=greet, inputs=name, outputs=output, api_name="greet")
demo.launch()
```
![`hello_blocks` demo](demo/hello_blocks/screenshot.gif)
Things to note:
- `Blocks` are made with a `with` clause, and any component created inside this clause is automatically added to the app.
- Components appear vertically in the app in the order they are created. (Later we will cover customizing layouts!)
- A `Button` was created, and then a `click` event-listener was added to this button. The API for this should look familiar! Like an `Interface`, the `click` method takes a Python function, input components, and output components.
### More Complexity
Here's an app to give you a taste of what's possible with `Blocks`:
```python
import numpy as np
import gradio as gr
def flip_text(x):
return x[::-1]
def flip_image(x):
return np.fliplr(x)
with gr.Blocks() as demo:
gr.Markdown("Flip text or image files using this demo.")
with gr.Tab("Flip Text"):
text_input = gr.Textbox()
text_output = gr.Textbox()
text_button = gr.Button("Flip")
with gr.Tab("Flip Image"):
with gr.Row():
image_input = gr.Image()
image_output = gr.Image()
image_button = gr.Button("Flip")
with gr.Accordion("Open for More!"):
gr.Markdown("Look at me...")
text_button.click(flip_text, inputs=text_input, outputs=text_output)
image_button.click(flip_image, inputs=image_input, outputs=image_output)
demo.launch()
```
![`blocks_flipper` demo](demo/blocks_flipper/screenshot.gif)
A lot more going on here! We'll cover how to create complex `Blocks` apps like this in the [building with blocks](https://gradio.app/blocks-and-event-listeners) section for you.
Congrats, you're now familiar with the basics of Gradio! 🥳 Go to our [next guide](https://gradio.app/key_features) to learn more about the key features of Gradio.
If you'd like to report a bug or have a feature request, please create an [issue on GitHub](https://github.com/gradio-app/gradio/issues/new/choose). For general questions about usage, we are available on [our Discord server](https://discord.com/invite/feTf9x3ZSB) and happy to help.
If you like Gradio, please leave us a ⭐ on GitHub!
## Open Source Stack
Gradio is built with many wonderful open-source libraries, please support them as well!
Gradio is built on top of many wonderful open-source libraries!
[<img src="readme_files/huggingface_mini.svg" alt="huggingface" height=40>](https://huggingface.co)
[<img src="readme_files/python.svg" alt="python" height=40>](https://www.python.org)

2
client/python/gradio_client/utils.py
View File

@ -255,7 +255,7 @@ def probe_url(possible_url: str) -> bool:
"""
Probe the given URL to see if it responds with a 200 status code (to HEAD, then to GET).
"""
headers = {"User-Agent": "gradio (https://gradio.app/; team@gradio.app)"}
headers = {"User-Agent": "gradio (https://gradio.app/; gradio-team@huggingface.co)"}
try:
with httpx.Client() as client:
head_request = client.head(possible_url, headers=headers)

14
client/python/pyproject.toml
View File

@ -9,13 +9,13 @@ description = "Python library for easily interacting with trained machine learni
license = "Apache-2.0"
requires-python = ">=3.8"
authors = [
{ name = "Abubakar Abid", email = "team@gradio.app" },
{ name = "Ali Abid", email = "team@gradio.app" },
{ name = "Ali Abdalla", email = "team@gradio.app" },
{ name = "Dawood Khan", email = "team@gradio.app" },
{ name = "Ahsen Khaliq", email = "team@gradio.app" },
{ name = "Pete Allen", email = "team@gradio.app" },
{ name = "Freddy Boulton", email = "team@gradio.app" },
{ name = "Abubakar Abid", email = "gradio-team@huggingface.co" },
{ name = "Ali Abid", email = "gradio-team@huggingface.co" },
{ name = "Ali Abdalla", email = "gradio-team@huggingface.co" },
{ name = "Dawood Khan", email = "gradio-team@huggingface.co" },
{ name = "Ahsen Khaliq", email = "gradio-team@huggingface.co" },
{ name = "Pete Allen", email = "gradio-team@huggingface.co" },
{ name = "Freddy Boulton", email = "gradio-team@huggingface.co" },
]
keywords = ["machine learning", "client", "API"]

2
demo/fake_diffusion/run.ipynb
View File

@ -1 +1 @@
{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: fake_diffusion\n", "### This demo uses a fake model to showcase iterative output. The Image output will update every time a generator is returned until the final image.\n", " "]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio numpy "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "import numpy as np\n", "import time\n", "\n", "# define core fn, which returns a generator {steps} times before returning the image\n", "def fake_diffusion(steps):\n", " for _ in range(steps):\n", " time.sleep(1)\n", " image = np.random.random((600, 600, 3))\n", " yield image\n", " image = np.ones((1000,1000,3), np.uint8)\n", " image[:] = [255, 124, 0]\n", " yield image\n", "\n", "\n", "demo = gr.Interface(fake_diffusion, inputs=gr.Slider(1, 10, 3), outputs=\"image\")\n", "\n", "# define queue - required for generators\n", "demo.queue()\n", "\n", "demo.launch()\n"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}
{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: fake_diffusion\n", "### This demo uses a fake model to showcase iterative output. The Image output will update every time a generator is returned until the final image.\n", " "]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio numpy "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "import numpy as np\n", "import time\n", "\n", "def fake_diffusion(steps):\n", " for i in range(steps):\n", " time.sleep(1)\n", " image = np.random.random((600, 600, 3))\n", " yield image\n", " image = np.ones((1000,1000,3), np.uint8)\n", " image[:] = [255, 124, 0]\n", " yield image\n", "\n", "\n", "demo = gr.Interface(fake_diffusion, inputs=gr.Slider(1, 10, 3), outputs=\"image\")\n", "\n", "if __name__ == \"__main__\":\n", " demo.launch()\n"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}

9
demo/fake_diffusion/run.py
View File

@ -2,9 +2,8 @@ import gradio as gr
import numpy as np
import time
# define core fn, which returns a generator {steps} times before returning the image
def fake_diffusion(steps):
for _ in range(steps):
for i in range(steps):
time.sleep(1)
image = np.random.random((600, 600, 3))
yield image
@ -15,7 +14,5 @@ def fake_diffusion(steps):
demo = gr.Interface(fake_diffusion, inputs=gr.Slider(1, 10, 3), outputs="image")
# define queue - required for generators
demo.queue()
demo.launch()
if __name__ == "__main__":
demo.launch()

2
demo/hello_blocks/run.ipynb
View File

@ -1 +1 @@
{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: hello_blocks"]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "\n", "\n", "def greet(name):\n", " return \"Hello \" + name + \"!\"\n", "\n", "\n", "with gr.Blocks() as demo:\n", " name = gr.Textbox(label=\"Name\")\n", " output = gr.Textbox(label=\"Output Box\")\n", " greet_btn = gr.Button(\"Greet\")\n", " greet_btn.click(fn=greet, inputs=name, outputs=output, api_name=\"greet\")\n", "\n", "if __name__ == \"__main__\":\n", " demo.launch()\n"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}
{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: hello_blocks"]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "\n", "def greet(name):\n", " return \"Hello \" + name + \"!\"\n", "\n", "with gr.Blocks() as demo:\n", " name = gr.Textbox(label=\"Name\")\n", " output = gr.Textbox(label=\"Output Box\")\n", " greet_btn = gr.Button(\"Greet\")\n", " greet_btn.click(fn=greet, inputs=name, outputs=output, api_name=\"greet\")\n", "\n", "if __name__ == \"__main__\":\n", " demo.launch()"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}

4
demo/hello_blocks/run.py
View File

@ -1,10 +1,8 @@
import gradio as gr
def greet(name):
return "Hello " + name + "!"
with gr.Blocks() as demo:
name = gr.Textbox(label="Name")
output = gr.Textbox(label="Output Box")
@ -12,4 +10,4 @@ with gr.Blocks() as demo:
greet_btn.click(fn=greet, inputs=name, outputs=output, api_name="greet")
if __name__ == "__main__":
demo.launch()
demo.launch()

2
demo/hello_world/run.ipynb
View File

@ -1 +1 @@
{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: hello_world\n", "### The simplest possible Gradio demo. It wraps a 'Hello {name}!' function in an Interface that accepts and returns text.\n", " "]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "\n", "def greet(name):\n", " return \"Hello \" + name + \"!\"\n", "\n", "demo = gr.Interface(fn=greet, inputs=\"text\", outputs=\"text\")\n", " \n", "if __name__ == \"__main__\":\n", " demo.launch(show_api=False) "]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}
{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: hello_world\n", "### The simplest possible Gradio demo. It wraps a 'Hello {name}!' function in an Interface that accepts and returns text.\n", " "]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "\n", "def greet(name):\n", " return \"Hello \" + name + \"!\"\n", "\n", "demo = gr.Interface(fn=greet, inputs=\"textbox\", outputs=\"textbox\")\n", " \n", "if __name__ == \"__main__\":\n", " demo.launch() "]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}

4
demo/hello_world/run.py
View File

@ -3,7 +3,7 @@ import gradio as gr
def greet(name):
return "Hello " + name + "!"
demo = gr.Interface(fn=greet, inputs="text", outputs="text")
demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox")
if __name__ == "__main__":
demo.launch(show_api=False)
demo.launch()

2
demo/hello_world_2/run.ipynb
View File

@ -1 +1 @@
{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: hello_world_2"]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "\n", "def greet(name):\n", " return \"Hello \" + name + \"!\"\n", "\n", "demo = gr.Interface(\n", " fn=greet,\n", " inputs=gr.Textbox(lines=2, placeholder=\"Name Here...\"),\n", " outputs=\"text\",\n", ")\n", "if __name__ == \"__main__\":\n", " demo.launch()\n"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}
{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: hello_world_2"]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "\n", "def greet(name, intensity):\n", " return \"Hello \" * intensity + name + \"!\"\n", "\n", "demo = gr.Interface(\n", " fn=greet,\n", " inputs=[\"text\", gr.Slider(value=2, minimum=1, maximum=10)],\n", " outputs=[gr.Textbox(label=\"greeting\", lines=3)],\n", ")\n", "\n", "if __name__ == \"__main__\":\n", " demo.launch()\n"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}

9
demo/hello_world_2/run.py
View File

@ -1,12 +1,13 @@
import gradio as gr
def greet(name):
return "Hello " + name + "!"
def greet(name, intensity):
return "Hello " * intensity + name + "!"
demo = gr.Interface(
fn=greet,
inputs=gr.Textbox(lines=2, placeholder="Name Here..."),
outputs="text",
inputs=["text", gr.Slider(value=2, minimum=1, maximum=10)],
outputs=[gr.Textbox(label="greeting", lines=3)],
)
if __name__ == "__main__":
demo.launch()

1
demo/hello_world_4/run.ipynb Normal file
View File

@ -0,0 +1 @@
{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: hello_world_4"]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "\n", "def greet(name, intensity):\n", " return \"Hello \" * intensity + name + \"!\"\n", "\n", "demo = gr.Interface(\n", " fn=greet,\n", " inputs=[\"text\", \"slider\"],\n", " outputs=[\"text\"],\n", ")\n", "\n", "if __name__ == \"__main__\":\n", " demo.launch()\n"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}

13
demo/hello_world_4/run.py Normal file
View File

@ -0,0 +1,13 @@
import gradio as gr
def greet(name, intensity):
return "Hello " * intensity + name + "!"
demo = gr.Interface(
fn=greet,
inputs=["text", "slider"],
outputs=["text"],
)
if __name__ == "__main__":
demo.launch()

BIN
demo/hello_world_4/screenshot.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 MiB

2
gradio/utils.py
View File

@ -586,7 +586,7 @@ def append_unique_suffix(name: str, list_of_names: list[str]):
def validate_url(possible_url: str) -> bool:
headers = {"User-Agent": "gradio (https://gradio.app/; team@gradio.app)"}
headers = {"User-Agent": "gradio (https://gradio.app/; gradio-team@huggingface.co)"}
try:
head_request = httpx.head(possible_url, headers=headers, follow_redirects=True)
# some URLs, such as AWS S3 presigned URLs, return a 405 or a 403 for HEAD requests

132
guides/01_getting-started/01_quickstart.md
View File

@ -1,136 +1,118 @@
# Quickstart
**Prerequisite**: Gradio requires Python 3.8 or higher, that's all!
Gradio is an open-source Python package that allows you to quickly **build** a demo or web application for your machine learning model, API, or any arbitary Python function. You can then **share** a link to your demo or web application in just a few seconds using Gradio's built-in sharing features. *No JavaScript, CSS, or web hosting experience needed!*
## What Does Gradio Do?
<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/gradio-guides/lcm-screenshot-3.gif" style="padding-bottom: 10px">
One of the _best ways to share_ your machine learning model, API, or data science workflow with others is to create an **interactive app** that allows your users or colleagues to try out the demo in their browsers.
It just takes a few lines of Python to create a beautiful demo like the one above, so let's get started 💫
Gradio allows you to **build demos and share them, all in Python.** And usually in just a few lines of code! So let's get started.
## Installation
## Hello, World
**Prerequisite**: Gradio requires [Python 3.8 or higher](https://www.python.org/downloads/)
To get Gradio running with a simple "Hello, World" example, follow these three steps:
1\. Install Gradio using pip:
We recommend installing Gradio using `pip`, which is included by default in Python. Run this in your terminal or command prompt:
```bash
pip install gradio
```
2\. Run the code below as a Python script or in a Jupyter Notebook (or [Google Colab](https://colab.research.google.com/drive/18ODkJvyxHutTN0P5APWyGFO_xwNcgHDZ?usp=sharing)):
$code_hello_world
Tip: it is best to install Gradio in a virtual environment. Detailed installation instructions for all common operating systems <a href="https://www.gradio.app/main/guides/installing-gradio-in-a-virtual-environment">are provided here</a>.
We shorten the imported name to `gr` for better readability of code using Gradio. This is a widely adopted convention that you should follow so that anyone working with your code can easily understand it.
## Building Your First Demo
3\. The demo below will appear automatically within the Jupyter Notebook, or pop in a browser on [http://localhost:7860](http://localhost:7860) if running from a script:
You can run Gradio in your favorite code editor, Jupyter notebook, Google Colab, or anywhere else you write Python. Let's write your first Gradio app:
$demo_hello_world
When developing locally, if you want to run the code as a Python script, you can use the Gradio CLI to launch the application **in reload mode**, which will provide seamless and fast development. Learn more about reloading in the [Auto-Reloading Guide](https://gradio.app/developing-faster-with-reload-mode/).
$code_hello_world_4
```bash
gradio app.py
```
Note: you can also do `python app.py`, but it won't provide the automatic reload mechanism.
Tip: We shorten the imported name from <code>gradio</code> to <code>gr</code> for better readability of code. This is a widely adopted convention that you should follow so that anyone working with your code can easily understand it.
## The `Interface` Class
Now, run your code. If you've written the Python code in a file named, for example, `app.py`, then you would run `python app.py` from the terminal.
You'll notice that in order to make the demo, we created a `gr.Interface`. This `Interface` class can wrap any Python function with a user interface. In the example above, we saw a simple text-based function, but the function could be anything from music generator to a tax calculator to the prediction function of a pretrained machine learning model.
The demo below will open in a browser on [http://localhost:7860](http://localhost:7860) if running from a file. If you are running within a notebook, the demo will appear embedded within the notebook.
The core `Interface` class is initialized with three required parameters:
$demo_hello_world_4
- `fn`: the function to wrap a UI around
- `inputs`: which component(s) to use for the input (e.g. `"text"`, `"image"` or `"audio"`)
- `outputs`: which component(s) to use for the output (e.g. `"text"`, `"image"` or `"label"`)
Type your name in the textbox on the left, drag the slider, and then press the Submit button. You should see a friendly greeting on the right.
Let's take a closer look at these components used to provide input and output.
Tip: When developing locally, you can run your Gradio app in <strong>hot reload mode</strong>, which automatically reloads the Gradio app whenever you make changes to the file. To do this, simply type in <code>gradio</code> before the name of the file instead of <code>python</code>. In the example above, you would type: `gradio app.py` in your terminal. Learn more about hot reloading in the <a href="https://www.gradio.app/guides/developing-faster-with-reload-mode">Hot Reloading Guide</a>.
## Components Attributes
We saw some simple `Textbox` components in the previous examples, but what if you want to change how the UI components look or behave?
**Understanding the `Interface` Class**
Let's say you want to customize the input text field — for example, you wanted it to be larger and have a text placeholder. If we use the actual class for `Textbox` instead of using the string shortcut, you have access to much more customizability through component attributes.
You'll notice that in order to make your first demo, you created an instance of the `gr.Interface` class. The `Interface` class is designed to create demos for machine learning models which accept one or more inputs, and return one or more outputs.
$code_hello_world_2
$demo_hello_world_2
The `Interface` class has three core arguments:
## Multiple Input and Output Components
- `fn`: the function to wrap a user interface (UI) around
- `inputs`: the Gradio component(s) to use for the input. The number of components should match the number of arguments in your function.
- `outputs`: the Gradio component(s) to use for the output. The number of components should match the number of return values from your function.
Suppose you had a more complex function, with multiple inputs and outputs. In the example below, we define a function that takes a string, boolean, and number, and returns a string and number. Take a look how you pass a list of input and output components.
The `fn` argument is very flexible -- you can pass *any* Python function that you want to wrap with a UI. In the example above, we saw a relatively simple function, but the function could be anything from a music generator to a tax calculator to the prediction function of a pretrained machine learning model.
$code_hello_world_3
$demo_hello_world_3
The `input` and `output` arguments take one or more Gradio components. As we'll see, Gradio includes more than [30 built-in components](https://www.gradio.app/docs/components) (such as the `gr.Textbox()`, `gr.Image()`, and `gr.HTML()` components) that are designed for machine learning applications.
You simply wrap the components in a list. Each component in the `inputs` list corresponds to one of the parameters of the function, in order. Each component in the `outputs` list corresponds to one of the values returned by the function, again in order.
Tip: For the `inputs` and `outputs` arguments, you can pass in the name of these components as a string (`"textbox"`) or an instance of the class (`gr.Textbox()`).
## An Image Example
If your function accepts more than one argument, as is the case above, pass a list of input components to `inputs`, with each input component corresponding to one of the arguments of the function, in order. The same holds true if your function returns more than one value: simply pass in a list of components to `outputs`. This flexibility makes the `Interface` class a very powerful way to create demos.
Gradio supports many types of components, such as `Image`, `DataFrame`, `Video`, or `Label`. Let's try an image-to-image function to get a feel for these!
We'll dive deeper into the `gr.Interface` on our series on [building Interfaces](https://www.gradio.app/main/guides/the-interface-class).
$code_sepia_filter
$demo_sepia_filter
## Sharing Your Demo
When using the `Image` component as input, your function will receive a NumPy array with the shape `(height, width, 3)`, where the last dimension represents the RGB values. We'll return an image as well in the form of a NumPy array.
You can also set the datatype used by the component with the `type=` keyword argument. For example, if you wanted your function to take a file path to an image instead of a NumPy array, the input `Image` component could be written as:
What good is a beautiful demo if you can't share it? Gradio lets you easily share a machine learning demo without having to worry about the hassle of hosting on a web server. Simply set `share=True` in `launch()`, and a publicly accessible URL will be created for your demo. Let's revisit our example demo, but change the last line as follows:
```python
gr.Image(type="filepath", shape=...)
import gradio as gr
def greet(name):
return "Hello " + name + "!"
demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox")
demo.launch(share=True) # Share your demo with just 1 extra parameter 🚀
```
Also note that our input `Image` component comes with an edit button 🖉, which allows for cropping and zooming into images. Manipulating images in this way can help reveal biases or hidden flaws in a machine learning model!
When you run this code, a public URL will be generated for your demo in a matter of seconds, something like:
You can read more about the many components and how to use them in the [Gradio docs](https://gradio.app/docs).
👉 &nbsp; `https://a23dsf231adb.gradio.live`
## Chatbots
Now, anyone around the world can try your Gradio demo from their browser, while the machine learning model and all computation continues to run locally on your computer.
Gradio includes a high-level class, `gr.ChatInterface`, which is similar to `gr.Interface`, but is specifically designed for chatbot UIs. The `gr.ChatInterface` class also wraps a function but this function must have a specific signature. The function should take two arguments: `message` and then `history` (the arguments can be named anything, but must be in this order)
To learn more about sharing your demo, read our dedicated guide on [sharing your Gradio application](https://www.gradio.app/guides/sharing-your-app).
- `message`: a `str` representing the user's input
- `history`: a `list` of `list` representing the conversations up until that point. Each inner list consists of two `str` representing a pair: `[user input, bot response]`.
Your function should return a single string response, which is the bot's response to the particular user input `message`.
## An Overview of Gradio
Other than that, `gr.ChatInterface` has no required parameters (though several are available for customization of the UI).
So far, we've been discussing the `Interface` class, which is a high-level class that lets to build demos quickly with Gradio. But what else does Gradio do?
Here's a toy example:
### Chatbots with `gr.ChatInterface`
$code_chatinterface_random_response
$demo_chatinterface_random_response
Gradio includes another high-level class, `gr.ChatInterface`, which is specifically designed to create Chatbot UIs. Similar to `Interface`, you supply a function and Gradio creates a fully working Chatbot UI. If you're interested in creating a chatbot, you can jump straight to [our dedicated guide on `gr.ChatInterface`](https://www.gradio.app/guides/creating-a-chatbot-fast).
You can [read more about `gr.ChatInterface` here](https://gradio.app/guides/creating-a-chatbot-fast).
### Custom Demos with `gr.Blocks`
## Blocks: More Flexibility and Control
Gradio also offers a low-level approach for designing web apps with more flexible layouts and data flows with the `gr.Blocks` class. Blocks allows you to do things like control where components appear on the page, handle complex data flows (e.g. outputs can serve as inputs to other functions), and update properties/visibility of components based on user interaction — still all in Python.
Gradio offers two approaches to build apps:
You can build very custom and complex applications using `gr.Blocks()`. For example, the popular image generation [Automatic1111 Web UI](https://github.com/AUTOMATIC1111/stable-diffusion-webui) is built using Gradio Blocks. We dive deeper into the `gr.Blocks` on our series on [building with Blocks](https://www.gradio.app/guides/blocks-and-event-listeners).
1\. **Interface** and **ChatInterface**, which provide a high-level abstraction for creating demos that we've been discussing so far.
2\. **Blocks**, a low-level API for designing web apps with more flexible layouts and data flows. Blocks allows you to do things like feature multiple data flows and demos, control where components appear on the page, handle complex data flows (e.g. outputs can serve as inputs to other functions), and update properties/visibility of components based on user interaction — still all in Python. If this customizability is what you need, try `Blocks` instead!
### The Gradio Python & JavaScript Ecosystem
## Hello, Blocks
That's the gist of the core `gradio` Python library, but Gradio is actually so much more! Its an entire ecosystem of Python and JavaScript libraries that let you build machine learning applications, or query them programmatically, in Python or JavaScript. Here are other related parts of the Gradio ecosystem:
Let's take a look at a simple example. Note how the API here differs from `Interface`.
* [Gradio Python Client](https://www.gradio.app/guides/getting-started-with-the-python-client) (`gradio_client`): query any Gradio app programmatically in Python.
* [Gradio JavaScript Client](https://www.gradio.app/guides/getting-started-with-the-js-client) (`@gradio/client`): query any Gradio app programmatically in JavaScript.
* [Gradio-Lite](https://www.gradio.app/guides/gradio-lite) (`@gradio/lite`): write Gradio apps in Python that run entirely in the browser (no server needed!), thanks to Pyodide.
* [Hugging Face Spaces](https://huggingface.co/spaces): the most popular place to host Gradio applications — for free!
$code_hello_blocks
$demo_hello_blocks
## What's Next?
Things to note:
Keep learning about Gradio sequentially using the Gradio Guides, which include explanations as well as example code and embedded interactive demos. Next up: [key features about Gradio demos](https://www.gradio.app/guides/key-features).
- `Blocks` are made with a `with` clause, and any component created inside this clause is automatically added to the app.
- Components appear vertically in the app in the order they are created. (Later we will cover customizing layouts!)
- A `Button` was created, and then a `click` event-listener was added to this button. The API for this should look familiar! Like an `Interface`, the `click` method takes a Python function, input components, and output components.
Or, if you already know the basics and are looking for something specific, you can search the more [technical API documentation](https://www.gradio.app/docs/).
## More Complexity
Here's an app to give you a taste of what's possible with `Blocks`:
$code_blocks_flipper
$demo_blocks_flipper
A lot more going on here! We'll cover how to create complex `Blocks` apps like this in the [building with blocks](https://gradio.app/blocks-and-event-listeners) section for you.
Congrats, you're now familiar with the basics of Gradio! 🥳 Go to our [next guide](https://gradio.app/key_features) to learn more about the key features of Gradio.

309
guides/01_getting-started/02_key-features.md
View File

@ -1,35 +1,99 @@
# Key Features
Let's go through some of the most popular features of Gradio! Here are Gradio's key features:
Let's go through some of the key features of Gradio. This guide is intended to be a high-level overview of various things that you should be aware of as you build your demo. Where appropriate, we link to more detailed guides on specific topics.
1. [Adding example inputs](#example-inputs)
2. [Passing custom error messages](#alerts)
3. [Adding descriptive content](#descriptive-content)
4. [Setting up flagging](#flagging)
5. [Preprocessing and postprocessing](#preprocessing-and-postprocessing)
6. [Styling demos](#styling)
7. [Queuing users](#queuing)
8. [Iterative outputs](#iterative-outputs)
9. [Progress bars](#progress-bars)
10. [Batch functions](#batch-functions)
11. [Running on collaborative notebooks](#colab-notebooks)
1. [Components](#components)
2. [Queuing](#queuing)
3. [Streaming outputs](#streaming-outputs)
4. [Streaming inputs](#streaming-inputs)
5. [Alert modals](#alert-modals)
6. [Styling](#styling)
7. [Progress bars](#progress-bars)
8. [Batch functions](#batch-functions)
## Example Inputs
## Components
You can provide example data that a user can easily load into `Interface`. This can be helpful to demonstrate the types of inputs the model expects, as well as to provide a way to explore your dataset in conjunction with your model. To load example data, you can provide a **nested list** to the `examples=` keyword argument of the Interface constructor. Each sublist within the outer list represents a data sample, and each element within the sublist represents an input for each input component. The format of example data for each component is specified in the [Docs](https://gradio.app/docs#components).
Gradio includes more than 30 pre-built components (as well as many user-built _custom components_) that can be used as inputs or outputs in your demo with a single line of code. These components correspond to common data types in machine learning and data science, e.g. the `gr.Image` component is designed to handle input or output images, the `gr.Label` component displays classification labels and probabilities, the `gr.Plot` component displays various kinds of plots, and so on.
$code_calculator
$demo_calculator
Each component includes various constructor attributes that control the properties of the component. For example, you can control the number of lines in a `gr.Textbox` using the `lines` argument (which takes a positive integer) in its constructor. Or you can control the way that a user can provide an image in the `gr.Image` component using the `sources` parameter (which takes a list like `["webcam", "upload"]`).
You can load a large dataset into the examples to browse and interact with the dataset through Gradio. The examples will be automatically paginated (you can configure this through the `examples_per_page` argument of `Interface`).
**Static and Interactive Components**
Continue learning about examples in the [More On Examples](https://gradio.app/guides/more-on-examples) guide.
Every component has a _static_ version that is designed to *display* data, and most components also have an _interactive_ version designed to let users input or modify the data. Typically, you don't need to think about this distinction, because when you build a Gradio demo, Gradio automatically figures out whether the component should be static or interactive based on whether it is being used as an input or output. However, you can set this manually using the `interactive` argument that every component supports.
## Alerts
**Preprocessing and Postprocessing**
You wish to pass custom error messages to the user. To do so, raise a `gr.Error("custom message")` to display an error message. If you try to divide by zero in the calculator demo above, a popup modal will display the custom error message. Learn more about Error in the [docs](https://gradio.app/docs#error).
When a component is used as an input, Gradio automatically handles the _preprocessing_ needed to convert the data from a type sent by the user's browser (such as an uploaded image) to a form that can be accepted by your function (such as a `numpy` array).
You can also issue `gr.Warning("message")` and `gr.Info("message")` by having them as standalone lines in your function, which will immediately display modals while continuing the execution of your function. Queueing needs to be enabled for this to work.
Similarly, when a component is used as an output, Gradio automatically handles the _postprocessing_ needed to convert the data from what is returned by your function (such as a list of image paths) to a form that can be displayed in the user's browser (a gallery of images).
Consider an example demo with three input components (`gr.Textbox`, `gr.Number`, and `gr.Image`) and two outputs (`gr.Number` and `gr.Gallery`) that serve as a UI for your image-to-image generation model. Below is a diagram of what our preprocessing will send to the model and what our postprocessing will require from it.
![](https://github.com/gradio-app/gradio/blob/main/guides/assets/dataflow.svg?raw=true)
In this image, the following preprocessing steps happen to send the data from the browser to your function:
* The text in the textbox is converted to a Python `str` (essentially no preprocessing)
* The number in the number input in converted to a Python `float` (essentially no preprocessing)
* Most importantly, ihe image supplied by the user is converted to a `numpy.array` representation of the RGB values in the image
Images are converted to NumPy arrays because they are a common format for machine learning workflows. You can control the _preprocessing_ using the component's parameters when constructing the component. For example, if you instantiate the `Image` component with the following parameters, it will preprocess the image to the `PIL` format instead:
```py
img = gr.Image(type="pil")
```
Postprocessing is even simpler! Gradio automatically recognizes the format of the returned data (e.g. does the user's function return a `numpy` array or a `str` filepath for the `gr.Image` component?) and postprocesses it appropriately into a format that can be displayed by the browser.
So in the image above, the following postprocessing steps happen to send the data returned from a user's function to the browser:
* The `float` is displayed as a number and displayed directly to the user
* The list of string filepaths (`list[str]`) is interpreted as a list of image filepaths and displayed as a gallery in the browser
Take a look at the [Docs](https://gradio.app/docs) to see all the parameters for each Gradio component.
## Queuing
Every Gradio app comes with a built-in queuing system that can scale to thousands of concurrent users. You can configure the queue by using `queue()` method which is supported by the `gr.Interface`, `gr.Blocks`, and `gr.ChatInterface` classes.
For example, you can control the number of requests processed at a single time by setting the `default_concurrency_limit` parameter of `queue()`, e.g.
```python
demo = gr.Interface(...).queue(default_concurrency_limit=5)
demo.launch()
```
This limits the number of requests processed for this event listener at a single time to 5. By default, the `default_concurrency_limit` is actually set to `1`, which means that when many users are using your app, only a single user's request will be processed at a time. This is because many machine learning functions consume a significant amount of memory and so it is only suitable to have a single user using the demo at a time. However, you can change this parameter in your demo easily.
See the [docs on queueing](/docs/interface#interface-queue) for more details on configuring the queuing parameters.
## Streaming outputs
In some cases, you may want to stream a sequence of outputs rather than show a single output at once. For example, you might have an image generation model and you want to show the image that is generated at each step, leading up to the final image. Or you might have a chatbot which streams its response one token at a time instead of returning it all at once.
In such cases, you can supply a **generator** function into Gradio instead of a regular function. Creating generators in Python is very simple: instead of a single `return` value, a function should `yield` a series of values instead. Usually the `yield` statement is put in some kind of loop. Here's an example of an generator that simply counts up to a given number:
```python
def my_generator(x):
for i in range(x):
yield i
```
You supply a generator into Gradio the same way as you would a regular function. For example, here's a a (fake) image generation model that generates noise for several steps before outputting an image using the `gr.Interface` class:
$code_fake_diffusion
$demo_fake_diffusion
Note that we've added a `time.sleep(1)` in the iterator to create an artificial pause between steps so that you are able to observe the steps of the iterator (in a real image generation model, this probably wouldn't be necessary).
## Streaming inputs
Similarly, Gradio can handle streaming inputs, e.g. a live audio stream that can gets transcribed to text in real time, or an image generation model that reruns every time a user types a letter in a textbox. This is covered in more details in our guide on building [reactive Interfaces](/guides/reactive-interfaces).
## Alert modals
You may wish to raise alerts to the user. To do so, raise a `gr.Error("custom message")` to display an error message. You can also issue `gr.Warning("message")` and `gr.Info("message")` by having them as standalone lines in your function, which will immediately display modals while continuing the execution of your function. Queueing needs to be enabled for this to work.
Note below how the `gr.Error` has to be raised, while the `gr.Warning` and `gr.Info` are single lines.
@ -43,95 +107,7 @@ def start_process(name):
raise gr.Error("Process failed")
```
## Descriptive Content
In the previous example, you may have noticed the `title=` and `description=` keyword arguments in the `Interface` constructor that helps users understand your app.
There are three arguments in the `Interface` constructor to specify where this content should go:
- `title`: which accepts text and can display it at the very top of interface, and also becomes the page title.
- `description`: which accepts text, markdown or HTML and places it right under the title.
- `article`: which also accepts text, markdown or HTML and places it below the interface.
![annotated](https://github.com/gradio-app/gradio/blob/main/guides/assets/annotated.png?raw=true)
If you're using the `Blocks` API instead, you can insert text, markdown, or HTML anywhere using the `gr.Markdown(...)` or `gr.HTML(...)` components, with descriptive content inside the `Component` constructor.
Another useful keyword argument is `label=`, which is present in every `Component`. This modifies the label text at the top of each `Component`. You can also add the `info=` keyword argument to form elements like `Textbox` or `Radio` to provide further information on their usage.
```python
gr.Number(label='Age', info='In years, must be greater than 0')
```
## Flagging
By default, an `Interface` will have "Flag" button. When a user testing your `Interface` sees input with interesting output, such as erroneous or unexpected model behaviour, they can flag the input for you to review. Within the directory provided by the `flagging_dir=` argument to the `Interface` constructor, a CSV file will log the flagged inputs. If the interface involves file data, such as for Image and Audio components, folders will be created to store those flagged data as well.
For example, with the calculator interface shown above, we would have the flagged data stored in the flagged directory shown below:
```directory
+-- calculator.py
+-- flagged/
| +-- logs.csv
```
_flagged/logs.csv_
```csv
num1,operation,num2,Output
5,add,7,12
6,subtract,1.5,4.5
```
With the sepia interface shown earlier, we would have the flagged data stored in the flagged directory shown below:
```directory
+-- sepia.py
+-- flagged/
| +-- logs.csv
| +-- im/
| | +-- 0.png
| | +-- 1.png
| +-- Output/
| | +-- 0.png
| | +-- 1.png
```
_flagged/logs.csv_
```csv
im,Output
im/0.png,Output/0.png
im/1.png,Output/1.png
```
If you wish for the user to provide a reason for flagging, you can pass a list of strings to the `flagging_options` argument of Interface. Users will have to select one of the strings when flagging, which will be saved as an additional column to the CSV.
## Preprocessing and Postprocessing
![](https://github.com/gradio-app/gradio/blob/main/guides/assets/dataflow.svg?raw=true)
As you've seen, Gradio includes components that can handle a variety of different data types, such as images, audio, and video. Most components can be used both as inputs or outputs.
When a component is used as an input, Gradio automatically handles the _preprocessing_ needed to convert the data from a type sent by the user's browser (such as a base64 representation of a webcam snapshot) to a form that can be accepted by your function (such as a `numpy` array).
Similarly, when a component is used as an output, Gradio automatically handles the _postprocessing_ needed to convert the data from what is returned by your function (such as a list of image paths) to a form that can be displayed in the user's browser (such as a `Gallery` of images in base64 format).
You can control the _preprocessing_ using the parameters when constructing the image component. For example, here if you instantiate the `Image` component with the following parameters, it will convert the image to the `PIL` type and reshape it to be `(100, 100)` no matter the original size that it was submitted as:
```py
img = gr.Image(shape=(100, 100), type="pil")
```
In contrast, here we keep the original size of the image, but invert the colors before converting it to a numpy array:
```py
img = gr.Image(invert_colors=True, type="numpy")
```
Postprocessing is a lot easier! Gradio automatically recognizes the format of the returned data (e.g. is the `Image` a `numpy` array or a `str` filepath?) and postprocesses it into a format that can be displayed by the browser.
Take a look at the [Docs](https://gradio.app/docs) to see all the preprocessing-related parameters for each Component.
## Styling
@ -141,93 +117,21 @@ Gradio themes are the easiest way to customize the look and feel of your app. Yo
demo = gr.Interface(..., theme=gr.themes.Monochrome())
```
Gradio comes with a set of prebuilt themes which you can load from `gr.themes.*`. You can extend these themes or create your own themes from scratch - see the [Theming guide](https://gradio.app/guides/theming-guide) for more details.
Gradio comes with a set of prebuilt themes which you can load from `gr.themes.*`. You can extend these themes or create your own themes from scratch - see the [theming guide](https://gradio.app/guides/theming-guide) for more details.
For additional styling ability, you can pass any CSS to your app using the `css=` kwarg.
The base class for the Gradio app is `gradio-container`, so here's an example that changes the background color of the Gradio app:
For additional styling ability, you can pass any CSS (as well as custom JavaScript) to your Gradio application. This is discussed in more detail in our [custom JS and CSS guide](/guides/custom-CSS-and-JS).
```python
with gr.Interface(css=".gradio-container {background-color: red}") as demo:
...
```
## Queuing
## Progress bars
If your app expects heavy traffic, use the `queue()` method to control processing rate. This will queue up calls so only a certain number of requests are processed at a single time. Queueing uses websockets, which also prevent network timeouts, so you should use queueing if the inference time of your function is long (> 1min).
With `Interface`:
```python
demo = gr.Interface(...).queue()
demo.launch()
```
With `Blocks`:
```python
with gr.Blocks() as demo:
#...
demo.queue()
demo.launch()
```
You can control the number of requests processed at a single time as such:
```python
with gr.Blocks() as demo:
btn = gr.Button("Run")
btn.click(..., concurrency_limit=2)
```
This limits the number of requests processed for this event listener at a single time to 2.
See the [Docs on queueing](/docs/#queue) on configuring other queuing parameters.
To specify only certain functions for queueing in Blocks:
```python
with gr.Blocks() as demo2:
num1 = gr.Number()
num2 = gr.Number()
output = gr.Number()
gr.Button("Add").click(
lambda a, b: a + b, [num1, num2], output)
gr.Button("Multiply").click(
lambda a, b: a * b, [num1, num2], output, queue=True)
demo2.launch()
```
## Iterative Outputs
In some cases, you may want to stream a sequence of outputs rather than show a single output at once. For example, you might have an image generation model and you want to show the image that is generated at each step, leading up to the final image. Or you might have a chatbot which streams its response one word at a time instead of returning it all at once.
In such cases, you can supply a **generator** function into Gradio instead of a regular function. Creating generators in Python is very simple: instead of a single `return` value, a function should `yield` a series of values instead. Usually the `yield` statement is put in some kind of loop. Here's an example of an generator that simply counts up to a given number:
```python
def my_generator(x):
for i in range(x):
yield i
```
You supply a generator into Gradio the same way as you would a regular function. For example, here's a a (fake) image generation model that generates noise for several steps before outputting an image:
$code_fake_diffusion
$demo_fake_diffusion
Note that we've added a `time.sleep(1)` in the iterator to create an artificial pause between steps so that you are able to observe the steps of the iterator (in a real image generation model, this probably wouldn't be necessary).
Supplying a generator into Gradio **requires** you to enable queuing in the underlying Interface or Blocks (see the queuing section above).
## Progress Bars
Gradio supports the ability to create a custom Progress Bars so that you have customizability and control over the progress update that you show to the user. In order to enable this, simply add an argument to your method that has a default value of a `gr.Progress` instance. Then you can update the progress levels by calling this instance directly with a float between 0 and 1, or using the `tqdm()` method of the `Progress` instance to track progress over an iterable, as shown below. Queueing must be enabled for progress updates.
Gradio supports the ability to create custom Progress Bars so that you have customizability and control over the progress update that you show to the user. In order to enable this, simply add an argument to your method that has a default value of a `gr.Progress` instance. Then you can update the progress levels by calling this instance directly with a float between 0 and 1, or using the `tqdm()` method of the `Progress` instance to track progress over an iterable, as shown below.
$code_progress_simple
$demo_progress_simple
If you use the `tqdm` library, you can even report progress updates automatically from any `tqdm.tqdm` that already exists within your function by setting the default argument as `gr.Progress(track_tqdm=True)`!
## Batch Functions
## Batch functions
Gradio supports the ability to pass _batch_ functions. Batch functions are just
functions which take in a list of inputs and return a list of predictions.
@ -246,22 +150,24 @@ def trim_words(words, lens):
return [trimmed_words]
```
The advantage of using batched functions is that if you enable queuing, the Gradio
server can automatically _batch_ incoming requests and process them in parallel,
potentially speeding up your demo. Here's what the Gradio code looks like (notice
the `batch=True` and `max_batch_size=16` -- both of these parameters can be passed
into event triggers or into the `Interface` class)
The advantage of using batched functions is that if you enable queuing, the Gradio server can automatically _batch_ incoming requests and process them in parallel,
potentially speeding up your demo. Here's what the Gradio code looks like (notice the `batch=True` and `max_batch_size=16`)
With `Interface`:
With the `gr.Interface` class:
```python
demo = gr.Interface(trim_words, ["textbox", "number"], ["output"],
batch=True, max_batch_size=16)
demo.queue()
demo = gr.Interface(
fn=trim_words,
inputs=["textbox", "number"],
outputs=["output"],
batch=True,
max_batch_size=16
)
demo.launch()
```
With `Blocks`:
With the `gr.Blocks` class:
```py
import gradio as gr
@ -276,18 +182,11 @@ with gr.Blocks() as demo:
event = run.click(trim_words, [word, leng], output, batch=True, max_batch_size=16)
demo.queue()
demo.launch()
```
In the example above, 16 requests could be processed in parallel (for a total inference
time of 5 seconds), instead of each request being processed separately (for a total
inference time of 80 seconds). Many Hugging Face `transformers` and `diffusers` models
work very naturally with Gradio's batch mode: here's [an example demo using diffusers to
In the example above, 16 requests could be processed in parallel (for a total inference time of 5 seconds), instead of each request being processed separately (for a total
inference time of 80 seconds). Many Hugging Face `transformers` and `diffusers` models work very naturally with Gradio's batch mode: here's [an example demo using diffusers to
generate images in batches](https://github.com/gradio-app/gradio/blob/main/demo/diffusers_with_batching/run.py)
Note: using batch functions with Gradio **requires** you to enable queuing in the underlying Interface or Blocks (see the queuing section above).
## Colab Notebooks
Gradio is able to run anywhere you run Python, including local jupyter notebooks as well as collaborative notebooks, such as [Google Colab](https://colab.research.google.com/). In the case of local jupyter notebooks and Google Colab notbooks, Gradio runs on a local server which you can interact with in your browser. (Note: for Google Colab, this is accomplished by [service worker tunneling](https://github.com/tensorflow/tensorboard/blob/master/docs/design/colab_integration.md), which requires cookies to be enabled in your browser.) For other remote notebooks, Gradio will also run on a server, but you will need to use [SSH tunneling](https://coderwall.com/p/ohk6cg/remote-access-to-ipython-notebooks-via-ssh) to view the app in your local browser. Often a simpler options is to use Gradio's built-in public links, [discussed in the next Guide](https://gradio.app/guides/sharing-your-app/#sharing-demos).

51
guides/01_getting-started/03_sharing-your-app.md
View File

@ -5,48 +5,53 @@ How to share your Gradio app:
1. [Sharing demos with the share parameter](#sharing-demos)
2. [Hosting on HF Spaces](#hosting-on-hf-spaces)
3. [Embedding hosted spaces](#embedding-hosted-spaces)
4. [Embedding with web components](#embedding-with-web-components)
5. [Using the API page](#api-page)
6. [Adding authentication to the page](#authentication)
7. [Accessing network requests](#accessing-the-network-request-directly)
8. [Mounting within FastAPI](#mounting-within-another-fast-api-app)
9. [Security and file access](#security-and-file-access)
4. [Using the API page](#api-page)
5. [Authentication](#authentication)
6. [Accessing network requests](#accessing-the-network-request-directly)
7. [Mounting within FastAPI](#mounting-within-another-fast-api-app)
8. [Security and file access](#security-and-file-access)
## Sharing Demos
Gradio demos can be easily shared publicly by setting `share=True` in the `launch()` method. Like this:
```python
demo.launch(share=True)
import gradio as gr
def greet(name):
return "Hello " + name + "!"
demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox")
demo.launch(share=True) # Share your demo with just 1 extra parameter 🚀
```
This generates a public, shareable link that you can send to anybody! When you send this link, the user on the other side can try out the model in their browser. Because the processing happens on your device (as long as your device stays on!), you don't have to worry about any packaging any dependencies. A share link usually looks something like this: **https://07ff8706ab.gradio.live**. Although the link is served through the Gradio Share Servers, these servers are only a proxy for your local server, and do not store any data sent through your app.
Keep in mind that share links are publicly accessible, meaning that anyone can use your model for prediction! Therefore, make sure not to expose any sensitive information through the functions you write, or allow any critical changes to occur on your device. If you set `share=False` (the default, except in colab notebooks), only a local link is created, which can be shared by [port-forwarding](https://www.ssh.com/ssh/tunneling/example) with specific users.
This generates a public, shareable link that you can send to anybody! When you send this link, the user on the other side can try out the model in their browser. Because the processing happens on your device (as long as your device stays on), you don't have to worry about any packaging any dependencies.
![sharing](https://github.com/gradio-app/gradio/blob/main/guides/assets/sharing.svg?raw=true)
Share links expire after 72 hours. (Note: it is [also possible to set up your own Share Server](https://github.com/huggingface/frp/) to overcome this restriction.)
A share link usually looks something like this: **https://07ff8706ab.gradio.live**. Although the link is served through the Gradio Share Servers, these servers are only a proxy for your local server, and do not store any data sent through your app. Share links expire after 72 hours. (it is [also possible to set up your own Share Server](https://github.com/huggingface/frp/) on your own cloud server to overcome this restriction.)
Tip: Keep in mind that share links are publicly accessible, meaning that anyone can use your model for prediction! Therefore, make sure not to expose any sensitive information through the functions you write, or allow any critical changes to occur on your device. Or you can [add authentication to your Gradio app](#authentication) as discussed below.
Note that by default, `share=False`, which means that your server is only running locally. (This is the default, except in Google Colab notebooks, where share links are automatically created). As an alternative to using share links, you can use use [SSH port-forwarding](https://www.ssh.com/ssh/tunneling/example) to share your local server with specific users.
## Hosting on HF Spaces
If you'd like to have a permanent link to your Gradio demo on the internet, use Hugging Face Spaces. [Hugging Face Spaces](http://huggingface.co/spaces/) provides the infrastructure to permanently host your machine learning model for free!
After you have [created a free Hugging Face account](https://huggingface.co/join), you have three methods to deploy your Gradio app to Hugging Face Spaces:
After you have [created a free Hugging Face account](https://huggingface.co/join), you have two methods to deploy your Gradio app to Hugging Face Spaces:
1. From terminal: run `gradio deploy` in your app directory. The CLI will gather some basic metadata and then launch your app. To update your space, you can re-run this command or enable the Github Actions option to automatically update the Spaces on `git push`.
2. From your browser: Drag and drop a folder containing your Gradio model and all related files [here](https://huggingface.co/new-space).
3. Connect Spaces with your Git repository and Spaces will pull the Gradio app from there. See [this guide how to host on Hugging Face Spaces](https://huggingface.co/blog/gradio-spaces) for more information.
2. From your browser: Drag and drop a folder containing your Gradio model and all related files [here](https://huggingface.co/new-space). See [this guide how to host on Hugging Face Spaces](https://huggingface.co/blog/gradio-spaces) for more information, or watch the embedded video:
<video autoplay muted loop>
<source src="https://github.com/gradio-app/gradio/blob/main/guides/assets/hf_demo.mp4?raw=true" type="video/mp4" />
</video>
Note: Some components, like `gr.Image`, will display a "Share" button only on Spaces, so that users can share the generated output to the Discussions page of the Space easily. You can disable this with `show_share_button`, such as `gr.Image(show_share_button=False)`.
![Image with show_share_button=True](https://github.com/gradio-app/gradio/blob/main/guides/assets/share_icon.png?raw=true)
## Embedding Hosted Spaces
@ -163,7 +168,6 @@ btn.click(add, [num1, num2], output, api_name="addition")
This will add and document the endpoint `/api/addition/` to the automatically generated API page. Otherwise, your API endpoints will appear as "unnamed" endpoints.
_Note_: For Gradio apps in which [queueing is enabled](https://gradio.app/guides/key-features#queuing), users can bypass the queue if they make a POST request to your API endpoint. To disable this behavior, set `api_open=False` in the `queue()` method. To disable the API page altogether, set `show_api=False` in `.launch()`.
## Authentication
@ -229,7 +233,9 @@ with gr.Blocks() as demo:
When the user clicks on the login button, they get redirected in a new page to authorize your Space.
![Allow Space app](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/gradio-guides/oauth_sign_in.png)
<center>
<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/gradio-guides/oauth_sign_in.png" style="width:300px; max-width:80%">
</center>
Users can revoke access to their profile at any time in their [settings](https://huggingface.co/settings/connected-applications).
@ -270,16 +276,17 @@ $code_custom_path
Note that this approach also allows you run your Gradio apps on custom paths (`http://localhost:8000/gradio` in the example above).
## Security and File Access
Sharing your Gradio app with others (by hosting it on Spaces, on your own server, or through temporary share links) **exposes** certain files on the host machine to users of your Gradio app.
In particular, Gradio apps ALLOW users to access to three kinds of files:
- **Temporary files created by Gradio.** These are files that are created by Gradio as part of running your prediction function. For example, if your prediction function returns a video file, then Gradio will save that video to a temporary cache on your device and then send the path to the file to the front end. You can customize the location of cache files created by Gradio by setting the environment variable `GRADIO_TEMP_DIR` to an absolute path, such as `/home/usr/scripts/project/temp/`.
- **Temporary files created by Gradio.** These are files that are created by Gradio as part of running your prediction function. For example, if your prediction function returns a video file, then Gradio will save that video to a temporary cache on your device and then send the path to the file to the front end. You can customize the location of temporary cache files created by Gradio by setting the environment variable `GRADIO_TEMP_DIR` to an absolute path, such as `/home/usr/scripts/project/temp/`.
- **Cached examples created by Gradio.** These are files that are created by Gradio as part of caching examples for faster runtimes, if you set `cache_examples=True` in `gr.Interface()` or in `gr.Examples()`. These files are saved in the `gradio_cached_examples/` subdirectory within your app's working directory.
- **Cached examples created by Gradio.** These are files that are created by Gradio as part of caching examples for faster runtimes, if you set `cache_examples=True` in `gr.Interface()` or in `gr.Examples()`. By default, these files are saved in the `gradio_cached_examples/` subdirectory within your app's working directory. You can customize the location of cached example files created by Gradio by setting the environment variable `GRADIO_EXAMPLES_CACHE` to an absolute path or a path relative to your working directory.
- **Files that you explicitly allow via the `allowed_paths` parameter in `launch()`**. This parameter allows you to pass in a list of additional directories or exact filepaths you'd like to allow users to have access to. (By default, this parameter is an empty list).

130
guides/02_building-interfaces/00_the-interface-class.md Normal file
View File

@ -0,0 +1,130 @@
# The `Interface` class
As mentioned in the [Quickstart](/main/guides/quickstart), the `gr.Interface` class is a high-level abstraction in Gradio that allows you to quickly create a demo for any Python function simply by specifying the input types and the output types. Revisiting our first demo:
$code_hello_world_4
We see that the `Interface` class is initialized with three required parameters:
- `fn`: the function to wrap a user interface (UI) around
- `inputs`: which Gradio component(s) to use for the input. The number of components should match the number of arguments in your function.
- `outputs`: which Gradio component(s) to use for the output. The number of components should match the number of return values from your function.
Let's take a closer look at these components used to provide input and output.
## Components Attributes
We used the default versions of the `gr.Textbox` and `gr.Slider`, but what if you want to change how the UI components look or behave?
Let's say you want to customize the slider to have values from 1 to 10, with a default of 2. And you wanted to customize the output text field — you want it to be larger and have a label.
If you use the actual class for `gr.Textbox` and `gr.Slider` instead of using the string shortcut, you have access to much more customizability through component attributes.
$code_hello_world_2
$demo_hello_world_2
## Multiple Input and Output Components
Suppose you had a more complex function, with multiple outputs as well. In the example below, we define a function that takes a string, boolean, and number, and returns a string and number.
$code_hello_world_3
$demo_hello_world_3
Just as each component in the `inputs` list corresponds to one of the parameters of the function, in order, each component in the `outputs` list corresponds to one of the values returned by the function, in order.
## An Image Example
Gradio supports many types of components, such as `Image`, `DataFrame`, `Video`, or `Label`. Let's try an image-to-image function to get a feel for these!
$code_sepia_filter
$demo_sepia_filter
When using the `Image` component as input, your function will receive a NumPy array with the shape `(height, width, 3)`, where the last dimension represents the RGB values. We'll return an image as well in the form of a NumPy array.
You can also set the datatype used by the component with the `type=` keyword argument. For example, if you wanted your function to take a file path to an image instead of a NumPy array, the input `Image` component could be written as:
```python
gr.Image(type="filepath", shape=...)
```
Also note that our input `Image` component comes with an edit button 🖉, which allows for cropping and zooming into images. Manipulating images in this way can help reveal biases or hidden flaws in a machine learning model!
You can read more about the many components and how to use them in the [Gradio docs](https://gradio.app/docs).
## Example Inputs
You can provide example data that a user can easily load into `Interface`. This can be helpful to demonstrate the types of inputs the model expects, as well as to provide a way to explore your dataset in conjunction with your model. To load example data, you can provide a **nested list** to the `examples=` keyword argument of the Interface constructor. Each sublist within the outer list represents a data sample, and each element within the sublist represents an input for each input component. The format of example data for each component is specified in the [Docs](https://gradio.app/docs#components).
$code_calculator
$demo_calculator
You can load a large dataset into the examples to browse and interact with the dataset through Gradio. The examples will be automatically paginated (you can configure this through the `examples_per_page` argument of `Interface`).
Continue learning about examples in the [More On Examples](https://gradio.app/guides/more-on-examples) guide.
## Descriptive Content
In the previous example, you may have noticed the `title=` and `description=` keyword arguments in the `Interface` constructor that helps users understand your app.
There are three arguments in the `Interface` constructor to specify where this content should go:
- `title`: which accepts text and can display it at the very top of interface, and also becomes the page title.
- `description`: which accepts text, markdown or HTML and places it right under the title.
- `article`: which also accepts text, markdown or HTML and places it below the interface.
![annotated](https://github.com/gradio-app/gradio/blob/main/guides/assets/annotated.png?raw=true)
If you're using the `Blocks` API instead, you can insert text, markdown, or HTML anywhere using the `gr.Markdown(...)` or `gr.HTML(...)` components, with descriptive content inside the `Component` constructor.
Another useful keyword argument is `label=`, which is present in every `Component`. This modifies the label text at the top of each `Component`. You can also add the `info=` keyword argument to form elements like `Textbox` or `Radio` to provide further information on their usage.
```python
gr.Number(label='Age', info='In years, must be greater than 0')
```
## Flagging
By default, an `Interface` will have "Flag" button. When a user testing your `Interface` sees input with interesting output, such as erroneous or unexpected model behaviour, they can flag the input for you to review. Within the directory provided by the `flagging_dir=` argument to the `Interface` constructor, a CSV file will log the flagged inputs. If the interface involves file data, such as for Image and Audio components, folders will be created to store those flagged data as well.
For example, with the calculator interface shown above, we would have the flagged data stored in the flagged directory shown below:
```directory
+-- calculator.py
+-- flagged/
| +-- logs.csv
```
_flagged/logs.csv_
```csv
num1,operation,num2,Output
5,add,7,12
6,subtract,1.5,4.5
```
With the sepia interface shown earlier, we would have the flagged data stored in the flagged directory shown below:
```directory
+-- sepia.py
+-- flagged/
| +-- logs.csv
| +-- im/
| | +-- 0.png
| | +-- 1.png
| +-- Output/
| | +-- 0.png
| | +-- 1.png
```
_flagged/logs.csv_
```csv
im,Output
im/0.png,Output/0.png
im/1.png,Output/1.png
```
If you wish for the user to provide a reason for flagging, you can pass a list of strings to the `flagging_options` argument of Interface. Users will have to select one of the strings when flagging, which will be saved as an additional column to the CSV.

2
guides/02_building-interfaces/03_more-on-examples.md → guides/02_building-interfaces/01_more-on-examples.md
View File

@ -1,6 +1,6 @@
# More on Examples
This guide covers what more you can do with Examples: Loading examples from a directory, providing partial examples, and caching. If Examples is new to you, check out the intro in the [Key Features](/guides/key-features/#example-inputs) guide.
In the [previous Guide](/main/guides/the-interface-class), we discussed how to provide example inputs for your demo to make it easier for users to try it out. Here, we dive into more details.
## Providing Examples

0
guides/02_building-interfaces/05_four-kinds-of-interfaces.md → guides/02_building-interfaces/02_four-kinds-of-interfaces.md
View File

6
guides/02_building-interfaces/01_interface-state.md → guides/02_building-interfaces/03_interface-state.md
View File

@ -1,10 +1,10 @@
# Interface State
This guide covers how State is handled in Gradio. Learn the difference between Global and Session states, and how to use both.
So far, we've assumed that your demos are *stateless*: that they do not persist information beyond a single function call. What if you want to modify the behavior of your demo based on previous interactions with the demo? There are two approaches in Gradio: *global state* and *session state*.
## Global State
Your function may use data that persists beyond a single function call. If the data is something accessible to all function calls and all users, you can create a variable outside the function call and access it inside the function. For example, you may load a large model outside the function and use it inside the function so that every function call does not need to reload the model.
If the state is something that should be accessible to all function calls and all users, you can create a variable outside the function call and access it inside the function. For example, you may load a large model outside the function and use it inside the function so that every function call does not need to reload the model.
$code_score_tracker
@ -12,7 +12,7 @@ In the code above, the `scores` array is shared between all users. If multiple u
## Session State
Another type of data persistence Gradio supports is session **state**, where data persists across multiple submits within a page session. However, data is _not_ shared between different users of your model. To store data in a session state, you need to do three things:
Another type of data persistence Gradio supports is session state, where data persists across multiple submits within a page session. However, data is _not_ shared between different users of your model. To store data in a session state, you need to do three things:
1. Pass in an extra parameter into your function, which represents the state of the interface.
2. At the end of the function, return the updated value of the state as an extra return value.

32
guides/02_building-interfaces/04_advanced-interface-features.md
View File

@ -1,32 +0,0 @@
# Advanced Interface Features
## Loading Hugging Face Models and Spaces
Gradio integrates nicely with the [Hugging Face Hub](https://hf.co), allowing you to load models and Spaces with just one line of code. To use this, simply use the `load()` method in the `Interface` class. So:
- To load any model from the Hugging Face Hub and create an interface around it, you pass `"model/"` or `"huggingface/"` followed by the model name, like these examples:
```python
gr.Interface.load("huggingface/gpt2").launch();
```
```python
gr.Interface.load("huggingface/EleutherAI/gpt-j-6B",
inputs=gr.Textbox(lines=5, label="Input Text") # customizes the input component
).launch()
```
- To load any Space from the Hugging Face Hub and recreate it locally (so that you can customize the inputs and outputs for example), you pass `"spaces/"` followed by the model name:
```python
gr.Interface.load("spaces/eugenesiow/remove-bg",
inputs="webcam",
title="Remove your webcam background!").launch()
```
One of the great things about loading Hugging Face models or spaces using Gradio is that you can then immediately use the resulting `Interface` object just like function in your Python code (this works for every type of model/space: text, images, audio, video, and even multimodal models):
```python
io = gr.Interface.load("models/EleutherAI/gpt-neo-2.7B")
io("It was the best of times") # outputs model completion
```

4
guides/02_building-interfaces/02_reactive-interfaces.md → guides/02_building-interfaces/04_reactive-interfaces.md
View File

@ -1,6 +1,6 @@
# Reactive Interfaces
This guide covers how to get Gradio interfaces to refresh automatically or continuously stream data.
Finally, we cover how to get Gradio demos to refresh automatically or continuously stream data.
## Live Interfaces
@ -24,3 +24,5 @@ $code_stream_frames
Streaming can also be done in an output component. A `gr.Audio(streaming=True)` output component can take a stream of audio data yielded piece-wise by a generator function and combines them into a single audio file.
$code_stream_audio_out
For a more detailed example, see our guide on performing [automatic speech recognition](/guides/real-time-speech-recognition) with Gradio.

3
guides/03_building-with-blocks/01_blocks-and-event-listeners.md
View File

@ -1,6 +1,7 @@
# Blocks and Event Listeners
We took a quick look at Blocks in the [Quickstart](https://gradio.app/guides/quickstart/#blocks-more-flexibility-and-control). Let's dive deeper. This guide will cover the how Blocks are structured, event listeners and their types, running events continuously, updating configurations, and using dictionaries vs lists.
We briefly descirbed the Blocks class in the [Quickstart](/main/guides/quickstart#custom-demos-with-gr-blocks) as a way to build custom demos. Let's dive deeper.
## Blocks Structure

8
guides/04_chatbots/01_creating-a-chatbot-fast.md
View File

@ -84,7 +84,7 @@ def slow_echo(message, history):
time.sleep(0.3)
yield "You typed: " + message[: i+1]
gr.ChatInterface(slow_echo).queue().launch()
gr.ChatInterface(slow_echo).launch()
```
Notice that we've [enabled queuing](/guides/key-features#queuing), which is required to use generator functions. While the response is streaming, the "Submit" button turns into a "Stop" button that can be used to stop the generator function. You can customize the appearance and behavior of the "Stop" button using the `stop_btn` parameter.
@ -154,7 +154,7 @@ with gr.Blocks() as demo:
echo, additional_inputs=[system_prompt, slider]
)
demo.queue().launch()
demo.launch()
```
If you need to create something even more custom, then its best to construct the chatbot UI using the low-level `gr.Blocks()` API. We have [a dedicated guide for that here](/guides/creating-a-custom-chatbot-with-blocks).
@ -223,7 +223,7 @@ def predict(message, history):
partial_message = partial_message + chunk['choices'][0]['delta']['content']
yield partial_message
gr.ChatInterface(predict).queue().launch()
gr.ChatInterface(predict).launch()
```
## Example using a local, open-source LLM with Hugging Face
@ -279,7 +279,7 @@ def predict(message, history):
yield partial_message
gr.ChatInterface(predict).queue().launch()
gr.ChatInterface(predict).launch()
```
With those examples, you should be all set to create your own Gradio Chatbot demos soon! For building even more custom Chatbot applications, check out [a dedicated guide](/guides/creating-a-custom-chatbot-with-blocks) using the low-level `gr.Blocks()` API.

160
guides/06_integrating-other-frameworks/01_using-hugging-face-integrations.md
View File

@ -1,21 +1,90 @@
# Using Hugging Face Integrations
Related spaces: https://huggingface.co/spaces/gradio/helsinki_translation_en_es
Related spaces: https://huggingface.co/spaces/gradio/en2es
Tags: HUB, SPACES, EMBED
Contributed by <a href="https://huggingface.co/osanseviero">Omar Sanseviero</a> 🦙
## Introduction
The Hugging Face Hub is a central platform that has over 190,000 [models](https://huggingface.co/models), 32,000 [datasets](https://huggingface.co/datasets) and 40,000 [demos](https://huggingface.co/spaces), also known as Spaces. Although Hugging Face is famous for its 🤗 transformers and diffusers libraries, the Hub also supports dozens of ML libraries, such as PyTorch, TensorFlow, spaCy, and many others across a variety of domains, from computer vision to reinforcement learning.
The Hugging Face Hub is a central platform that has hundreds of thousands of [models](https://huggingface.co/models), [datasets](https://huggingface.co/datasets) and [demos](https://huggingface.co/spaces) (also known as Spaces).
Gradio has multiple features that make it extremely easy to leverage existing models and Spaces on the Hub. This guide walks through these features.
## Using regular inference with `pipeline`
First, let's build a simple interface that translates text from English to Spanish. Between the over a thousand models shared by the University of Helsinki, there is an [existing model](https://huggingface.co/Helsinki-NLP/opus-mt-en-es), `opus-mt-en-es`, that does precisely this!
## Demos with the Hugging Face Inference API
The 🤗 transformers library has a very easy-to-use abstraction, [`pipeline()`](https://huggingface.co/docs/transformers/v4.16.2/en/main_classes/pipelines#transformers.pipeline) that handles most of the complex code to offer a simple API for common tasks. By specifying the task and an (optional) model, you can use an existing model with few lines:
Hugging Face has a free service called the [Inference API](https://huggingface.co/inference-api), which allows you to send HTTP requests to models in the Hub. For transformers or diffusers-based models, the API can be 2 to 10 times faster than running the inference yourself. The API is free (rate limited), and you can switch to dedicated [Inference Endpoints](https://huggingface.co/pricing) when you want to use it in production. Gradio integrates directly with the Hugging Face Inference API so that you can create a demo simply by specifying a model's name (e.g. `Helsinki-NLP/opus-mt-en-es`), like this:
```python
import gradio as gr
demo = gr.load("Helsinki-NLP/opus-mt-en-es", src="models")
demo.launch()
```
For any Hugging Face model supported in the Inference API, Gradio automatically infers the expected input and output and make the underlying server calls, so you don't have to worry about defining the prediction function.
Notice that we just put specify the model name and state that the `src` should be `models` (Hugging Face's Model Hub). There is no need to install any dependencies (except `gradio`) since you are not loading the model on your computer.
You might notice that the first inference takes about 20 seconds. This happens since the Inference API is loading the model in the server. You get some benefits afterward:
- The inference will be much faster.
- The server caches your requests.
- You get built-in automatic scaling.
## Hosting your Gradio demos on Spaces
[Hugging Face Spaces](https://hf.co/spaces) allows anyone to host their Gradio demos freely, and uploading your Gradio demos take a couple of minutes. You can head to [hf.co/new-space](https://huggingface.co/new-space), select the Gradio SDK, create an `app.py` file, and voila! You have a demo you can share with anyone else. To learn more, read [this guide how to host on Hugging Face Spaces using the website](https://huggingface.co/blog/gradio-spaces).
Alternatively, you can create a Space programmatically, making use of the [huggingface_hub client library](https://huggingface.co/docs/huggingface_hub/index) library. Here's an example:
```python
from huggingface_hub import (
create_repo,
get_full_repo_name,
upload_file,
)
create_repo(name=target_space_name, token=hf_token, repo_type="space", space_sdk="gradio")
repo_name = get_full_repo_name(model_id=target_space_name, token=hf_token)
file_url = upload_file(
path_or_fileobj="file.txt",
path_in_repo="app.py",
repo_id=repo_name,
repo_type="space",
token=hf_token,
)
```
Here, `create_repo` creates a gradio repo with the target name under a specific account using that account's Write Token. `repo_name` gets the full repo name of the related repo. Finally `upload_file` uploads a file inside the repo with the name `app.py`.
## Loading demos from Spaces
You can also use and remix existing Gradio demos on Hugging Face Spaces. For example, you could take two existing Gradio demos on Spaces and put them as separate tabs and create a new demo. You can run this new demo locally, or upload it to Spaces, allowing endless possibilities to remix and create new demos!
Here's an example that does exactly that:
```python
import gradio as gr
with gr.Blocks() as demo:
with gr.Tab("Translate to Spanish"):
gr.load("gradio/en2es", src="spaces")
with gr.Tab("Translate to French"):
gr.load("abidlabs/en2fr", src="spaces")
demo.launch()
```
Notice that we use `gr.load()`, the same method we used to load models using the Inference API. However, here we specify that the `src` is `spaces` (Hugging Face Spaces).
Note: loading a Space in this way may result in slight differences from the original Space. In particular, any attributes that apply to the entire Blocks, such as the theme or custom CSS/JS, will not be loaded. You can copy these properties from the Space you are loading into your own `Blocks` object.
## Demos with the `Pipeline` in `transformers`
Hugging Face's popular `transformers` library has a very easy-to-use abstraction, [`pipeline()`](https://huggingface.co/docs/transformers/v4.16.2/en/main_classes/pipelines#transformers.pipeline) that handles most of the complex code to offer a simple API for common tasks. By specifying the task and an (optional) model, you can build a demo around an existing model with few lines of Python:
```python
import gradio as gr
@ -50,87 +119,16 @@ demo.launch()
The previous code produces the following interface, which you can try right here in your browser:
<gradio-app space="Helsinki-NLP/opus-mt-en-es"></gradio-app>
<gradio-app space="gradio/en2es"></gradio-app>
## Using Hugging Face Inference API
Hugging Face has a free service called the [Inference API](https://huggingface.co/inference-api), which allows you to send HTTP requests to models in the Hub. For transformers or diffusers-based models, the API can be 2 to 10 times faster than running the inference yourself. The API is free (rate limited), and you can switch to dedicated [Inference Endpoints](https://huggingface.co/pricing) when you want to use it in production.
Let's try the same demo as above but using the Inference API instead of loading the model yourself. Given a Hugging Face model supported in the Inference API, Gradio can automatically infer the expected input and output and make the underlying server calls, so you don't have to worry about defining the prediction function. Here is what the code would look like!
```python
import gradio as gr
demo = gr.load("Helsinki-NLP/opus-mt-en-es", src="models")
demo.launch()
```
Notice that we just put specify the model name and state that the `src` should be `models` (Hugging Face's Model Hub). There is no need to install any dependencies (except `gradio`) since you are not loading the model on your computer.
You might notice that the first inference takes about 20 seconds. This happens since the Inference API is loading the model in the server. You get some benefits afterward:
- The inference will be much faster.
- The server caches your requests.
- You get built-in automatic scaling.
## Hosting your Gradio demos
[Hugging Face Spaces](https://hf.co/spaces) allows anyone to host their Gradio demos freely, and uploading your Gradio demos take a couple of minutes. You can head to [hf.co/new-space](https://huggingface.co/new-space), select the Gradio SDK, create an `app.py` file, and voila! You have a demo you can share with anyone else. To learn more, read [this guide how to host on Hugging Face Spaces using the website](https://huggingface.co/blog/gradio-spaces).
Alternatively, you can create a Space programmatically, making use of the [huggingface_hub client library](https://huggingface.co/docs/huggingface_hub/index) library. Here's an example:
```python
from huggingface_hub import (
create_repo,
get_full_repo_name,
upload_file,
)
create_repo(name=target_space_name, token=hf_token, repo_type="space", space_sdk="gradio")
repo_name = get_full_repo_name(model_id=target_space_name, token=hf_token)
file_url = upload_file(
path_or_fileobj="file.txt",
path_in_repo="app.py",
repo_id=repo_name,
repo_type="space",
token=hf_token,
)
```
Here, `create_repo` creates a gradio repo with the target name under a specific account using that account's Write Token. `repo_name` gets the full repo name of the related repo. Finally `upload_file` uploads a file inside the repo with the name `app.py`.
## Embedding your Space demo on other websites
Throughout this guide, you've seen many embedded Gradio demos. You can also do this on own website! The first step is to create a Hugging Face Space with the demo you want to showcase. Then, [follow the steps here to embed the Space on your website](/guides/sharing-your-app/#embedding-hosted-spaces).
## Loading demos from Spaces
You can also use and remix existing Gradio demos on Hugging Face Spaces. For example, you could take two existing Gradio demos and put them as separate tabs and create a new demo. You can run this new demo locally, or upload it to Spaces, allowing endless possibilities to remix and create new demos!
Here's an example that does exactly that:
```python
import gradio as gr
with gr.Blocks() as demo:
with gr.Tab("Translate to Spanish"):
gr.load("gradio/helsinki_translation_en_es", src="spaces")
with gr.Tab("Translate to French"):
gr.load("abidlabs/en2fr", src="spaces")
demo.launch()
```
Notice that we use `gr.load()`, the same method we used to load models using the Inference API. However, here we specify that the `src` is `spaces` (Hugging Face Spaces).
## Recap
That's it! Let's recap the various ways Gradio and Hugging Face work together:
1. You can convert a `transformers` pipeline into a Gradio demo using `from_pipeline()`
2. You can build a demo around the Inference API without having to load the model easily using `gr.load()`
3. You host your Gradio demo on Hugging Face Spaces, either using the GUI or entirely in Python.
4. You can embed Gradio demos that are hosted on Hugging Face Spaces onto your own website.
5. You can load demos from Hugging Face Spaces to remix and create new Gradio demos using `gr.load()`.
1. You can build a demo around the Inference API without having to load the model easily using `gr.load()`.
2. You host your Gradio demo on Hugging Face Spaces, either using the GUI or entirely in Python.
3. You can load demos from Hugging Face Spaces to remix and create new Gradio demos using `gr.load()`.
4. You can convert a `transformers` pipeline into a Gradio demo using `from_pipeline()`.
🤗

2
guides/07_tabular-data-science-and-plots/using-gradio-for-tabular-workflows.md
View File

@ -95,7 +95,7 @@ import gradio as gr
title = "Supersoaker Defective Product Prediction"
description = "This model predicts Supersoaker production line failures. Drag and drop any slice from dataset or edit values as you wish in below dataframe component."
gr.Interface.load("huggingface/scikit-learn/tabular-playground", title=title, description=description).launch()
gr.load("huggingface/scikit-learn/tabular-playground", title=title, description=description).launch()
```
<gradio-app space="gradio/gradio-skops-integration"></gradio-app>

0
guides/08_client-libraries/01_getting-started-with-the-python-client.md → guides/08_gradio-clients-and-lite/01_getting-started-with-the-python-client.md
View File

0
guides/08_client-libraries/02_getting-started-with-the-js-client.md → guides/08_gradio-clients-and-lite/02_getting-started-with-the-js-client.md
View File

0
guides/08_client-libraries/fastapi-app-with-the-gradio-client.md → guides/08_gradio-clients-and-lite/fastapi-app-with-the-gradio-client.md
View File

0
guides/08_client-libraries/gradio-and-llm-agents.md → guides/08_gradio-clients-and-lite/gradio-and-llm-agents.md
View File

0
guides/09_other-tutorials/gradio-lite.md → guides/08_gradio-clients-and-lite/gradio-lite.md
View File

194
guides/09_other-tutorials/custom-interpretations-with-blocks.md
View File

@ -1,194 +0,0 @@
# Custom Machine Learning Interpretations with Blocks
Tags: INTERPRETATION, SENTIMENT ANALYSIS
**Prerequisite**: This Guide requires you to know about Blocks and the interpretation feature of Interfaces.
Make sure to [read the Guide to Blocks first](https://gradio.app/guides/quickstart/#blocks-more-flexibility-and-control) as well as the
interpretation section of the [Advanced Interface Features Guide](/advanced-interface-features#interpreting-your-predictions).
## Introduction
If you have experience working with the Interface class, then you know that interpreting the prediction of your machine learning model
is as easy as setting the `interpretation` parameter to either "default" or "shap".
You may be wondering if it is possible to add the same interpretation functionality to an app built with the Blocks API.
Not only is it possible, but the flexibility of Blocks lets you display the interpretation output in ways that are
impossible to do with Interfaces!
This guide will show how to:
1. Recreate the behavior of Interfaces's interpretation feature in a Blocks app.
2. Customize how interpretations are displayed in a Blocks app.
Let's get started!
## Setting up the Blocks app
Let's build a sentiment classification app with the Blocks API.
This app will take text as input and output the probability that this text expresses either negative or positive sentiment.
We'll have a single input `Textbox` and a single output `Label` component.
Below is the code for the app as well as the app itself.
```python
import gradio as gr
from transformers import pipeline
sentiment_classifier = pipeline("text-classification", return_all_scores=True)
def classifier(text):
pred = sentiment_classifier(text)
return {p["label"]: p["score"] for p in pred[0]}
with gr.Blocks() as demo:
with gr.Row():
with gr.Column():
input_text = gr.Textbox(label="Input Text")
with gr.Row():
classify = gr.Button("Classify Sentiment")
with gr.Column():
label = gr.Label(label="Predicted Sentiment")
classify.click(classifier, input_text, label)
demo.launch()
```
<gradio-app space="freddyaboulton/sentiment-classification"> </gradio-app>
## Adding interpretations to the app
Our goal is to present to our users how the words in the input contribute to the model's prediction.
This will help our users understand how the model works and also evaluate its effectiveness.
For example, we should expect our model to identify the words "happy" and "love" with positive sentiment - if not it's a sign we made a mistake in training it!
For each word in the input, we will compute a score of how much the model's prediction of positive sentiment is changed by that word.
Once we have those `(word, score)` pairs we can use gradio to visualize them for the user.
The [shap](https://shap.readthedocs.io/en/stable/index.html) library will help us compute the `(word, score)` pairs and
gradio will take care of displaying the output to the user.
The following code computes the `(word, score)` pairs:
```python
def interpretation_function(text):
explainer = shap.Explainer(sentiment_classifier)
shap_values = explainer([text])
# Dimensions are (batch size, text size, number of classes)
# Since we care about positive sentiment, use index 1
scores = list(zip(shap_values.data[0], shap_values.values[0, :, 1]))
# Scores contains (word, score) pairs
# Format expected by gr.components.Interpretation
return {"original": text, "interpretation": scores}
```
Now, all we have to do is add a button that runs this function when clicked.
To display the interpretation, we will use `gr.components.Interpretation`.
This will color each word in the input either red or blue.
Red if it contributes to positive sentiment and blue if it contributes to negative sentiment.
This is how `Interface` displays the interpretation output for text.
```python
with gr.Blocks() as demo:
with gr.Row():
with gr.Column():
input_text = gr.Textbox(label="Input Text")
with gr.Row():
classify = gr.Button("Classify Sentiment")
interpret = gr.Button("Interpret")
with gr.Column():
label = gr.Label(label="Predicted Sentiment")
with gr.Column():
interpretation = gr.components.Interpretation(input_text)
classify.click(classifier, input_text, label)
interpret.click(interpretation_function, input_text, interpretation)
demo.launch()
```
<gradio-app space="freddyaboulton/sentiment-classification-interpretation"> </gradio-app>
## Customizing how the interpretation is displayed
The `gr.components.Interpretation` component does a good job of showing how individual words contribute to the sentiment prediction,
but what if we also wanted to display the score themselves along with the words?
One way to do this would be to generate a bar plot where the words are on the horizontal axis and the bar height corresponds
to the shap score.
We can do this by modifying our `interpretation_function` to additionally return a matplotlib bar plot.
We will display it with the `gr.Plot` component in a separate tab.
This is how the interpretation function will look:
```python
def interpretation_function(text):
explainer = shap.Explainer(sentiment_classifier)
shap_values = explainer([text])
# Dimensions are (batch size, text size, number of classes)
# Since we care about positive sentiment, use index 1
scores = list(zip(shap_values.data[0], shap_values.values[0, :, 1]))
scores_desc = sorted(scores, key=lambda t: t[1])[::-1]
# Filter out empty string added by shap
scores_desc = [t for t in scores_desc if t[0] != ""]
fig_m = plt.figure()
# Select top 5 words that contribute to positive sentiment
plt.bar(x=[s[0] for s in scores_desc[:5]],
height=[s[1] for s in scores_desc[:5]])
plt.title("Top words contributing to positive sentiment")
plt.ylabel("Shap Value")
plt.xlabel("Word")
return {"original": text, "interpretation": scores}, fig_m
```
And this is how the app code will look:
```python
with gr.Blocks() as demo:
with gr.Row():
with gr.Column():
input_text = gr.Textbox(label="Input Text")
with gr.Row():
classify = gr.Button("Classify Sentiment")
interpret = gr.Button("Interpret")
with gr.Column():
label = gr.Label(label="Predicted Sentiment")
with gr.Column():
with gr.Tabs():
with gr.TabItem("Display interpretation with built-in component"):
interpretation = gr.components.Interpretation(input_text)
with gr.TabItem("Display interpretation with plot"):
interpretation_plot = gr.Plot()
classify.click(classifier, input_text, label)
interpret.click(interpretation_function, input_text, [interpretation, interpretation_plot])
demo.launch()
```
You can see the demo below!
<gradio-app space="freddyaboulton/sentiment-classification-interpretation-tabs"> </gradio-app>
## Beyond Sentiment Classification
Although we have focused on sentiment classification so far, you can add interpretations to almost any machine learning model.
The output must be an `gr.Image` or `gr.Label` but the input can be almost anything (`gr.Number`, `gr.Slider`, `gr.Radio`, `gr.Image`).
Here is a demo built with blocks of interpretations for an image classification model:
<gradio-app space="freddyaboulton/image-classification-interpretation-blocks"> </gradio-app>
## Closing remarks
We did a deep dive 🤿 into how interpretations work and how you can add them to your Blocks app.
We also showed how the Blocks API gives you the power to control how the interpretation is visualized in your app.
Adding interpretations is a helpful way to make your users understand and gain trust in your model.
Now you have all the tools you need to add them to all of your apps!

100
guides/09_other-tutorials/installing-gradio-in-a-virtual-environment.md Normal file
View File

@ -0,0 +1,100 @@
# Installing Gradio in a Virtual Environment
Tags: INSTALLATION
In this guide, we will describe step-by-step how to install `gradio` within a virtual environment. This guide will cover both Windows and MacOS/Linux systems.
## Virtual Environments
A virtual environment in Python is a self-contained directory that holds a Python installation for a particular version of Python, along with a number of additional packages. This environment is isolated from the main Python installation and other virtual environments. Each environment can have its own independent set of installed Python packages, which allows you to maintain different versions of libraries for different projects without conflicts.
Using virtual environments ensures that you can work on multiple Python projects on the same machine without any conflicts. This is particularly useful when different projects require different versions of the same library. It also simplifies dependency management and enhances reproducibility, as you can easily share the requirements of your project with others.
## Installing Gradio on Windows
To install Gradio on a Windows system in a virtual environment, follow these steps:
1. **Install Python**: Ensure you have Python 3.8 or higher installed. You can download it from [python.org](https://www.python.org/). You can verify the installation by running `python --version` or `python3 --version` in Command Prompt.
2. **Create a Virtual Environment**:
Open Command Prompt and navigate to your project directory. Then create a virtual environment using the following command:
```bash
python -m venv gradio-env
```
This command creates a new directory `gradio-env` in your project folder, containing a fresh Python installation.
3. **Activate the Virtual Environment**:
To activate the virtual environment, run:
```bash
.\gradio-env\Scripts\activate
```
Your command prompt should now indicate that you are working inside `gradio-env`. Note: you can choose a different name than `gradio-env` for your virtual environment in this step.
4. **Install Gradio**:
Now, you can install Gradio using pip:
```bash
pip install gradio
```
5. **Verification**:
To verify the installation, run `python` and then type:
```python
import gradio as gr
print(gr.__version__)
```
This will display the installed version of Gradio.
## Installing Gradio on MacOS/Linux
The installation steps on MacOS and Linux are similar to Windows but with some differences in commands.
1. **Install Python**:
Python usually comes pre-installed on MacOS and most Linux distributions. You can verify the installation by running `python --version` in the terminal (note that depending on how Python is installed, you might have to use `python3` instead of `python` throughout these steps).
Ensure you have Python 3.8 or higher installed. If you do not have it installed, you can download it from [python.org](https://www.python.org/).
2. **Create a Virtual Environment**:
Open Terminal and navigate to your project directory. Then create a virtual environment using:
```bash
python -m venv gradio-env
```
Note: you can choose a different name than `gradio-env` for your virtual environment in this step.
3. **Activate the Virtual Environment**:
To activate the virtual environment on MacOS/Linux, use:
```bash
source gradio-env/bin/activate
```
4. **Install Gradio**:
With the virtual environment activated, install Gradio using pip:
```bash
pip install gradio
```
5. **Verification**:
To verify the installation, run `python` and then type:
```python
import gradio as gr
print(gr.__version__)
```
This will display the installed version of Gradio.
By following these steps, you can successfully install Gradio in a virtual environment on your operating system, ensuring a clean and managed workspace for your Python projects.

97
guides/cn/02_building-interfaces/04_advanced-interface-features.md
View File

@ -1,97 +0,0 @@
# 高级接口特性
在[接口 Interface](https://gradio.app/docs#interface)类上还有更多内容需要介绍。本指南涵盖了所有高级特性：使用[解释器 Interpretation](https://gradio.app/docs#interpretation)，自定义样式，从[Hugging Face Hub](https://hf.co)加载模型，以及使用[并行 Parallel](https://gradio.app/docs#parallel)和[串行 Series](https://gradio.app/docs#series)。
## 解释您的预测
大多数模型都是黑盒模型，函数的内部逻辑对最终用户来说是隐藏的。为了鼓励透明度，我们通过在 `Interface` 类中简单地将 `interpretation` 关键字设置为 `default`，使得为模型添加解释非常容易。这样，您的用户就可以了解到哪些输入部分对输出结果负责。请看下面的简单界面示例，它展示了一个图像分类器，还包括解释功能：
$code_image_classifier_interpretation
除了 `default`，Gradio 还包括了基于[Shapley-based interpretation](https://christophm.github.io/interpretable-ml-book/shap.html)，它提供了更准确的解释，尽管运行时间通常较慢。要使用它，只需将 `interpretation` 参数设置为 `"shap"`（注意：还要确保安装了 Python 包 `shap`）。您还可以选择修改 `num_shap` 参数，该参数控制准确性和运行时间之间的权衡（增加此值通常会增加准确性）。下面是一个示例：
```python
gr.Interface(fn=classify_image, inputs=image, outputs=label, interpretation="shap", num_shap=5).launch()
```
这适用于任何函数，即使在内部，模型是复杂的神经网络或其他黑盒模型。如果使用 Gradio 的 `default` 或 `shap` 解释，输出组件必须是 `Label`。支持所有常见的输入组件。下面是一个包含文本输入的示例。
$code_gender_sentence_default_interpretation
那么在幕后发生了什么？使用这些解释方法，Gradio 会使用修改后的输入的多个版本进行多次预测。根据结果，您将看到界面自动将增加类别可能性的文本部分（或图像等）以红色突出显示。颜色的强度对应于输入部分的重要性。减少类别置信度的部分以蓝色突出显示。
您还可以编写自己的解释函数。下面的演示在前一个演示中添加了自定义解释。此函数将使用与主封装函数相同的输入。该解释函数的输出将用于突出显示每个输入组件的输入-因此函数必须返回一个列表，其中元素的数量与输入组件的数量相对应。要查看每个输入组件的解释格式，请查阅文档。
$code_gender_sentence_custom_interpretation
在[文档](https://gradio.app/docs#interpretation)中了解更多关于解释的信息。
## 自定义样式
如果您希望对演示的任何方面都有更精细的控制，还可以编写自己的 CSS 或通过 `Interface` 类的 `css` 参数传递 CSS 文件的文件路径。
```python
gr.Interface(..., css="body {background-color: red}")
```
如果您希望在 CSS 中引用外部文件，请在文件路径（可以是相对路径或绝对路径）之前加上 `"file="`，例如：
```python
gr.Interface(..., css="body {background-image: url('file=clouds.jpg')}")
```
**警告**：不能保证自定义 CSS 能够在 Gradio 的不同版本之间正常工作，因为 Gradio 的 HTML DOM 可能会发生更改。我们建议尽量少使用自定义 CSS，而尽可能使用[主题 Themes](/theming-guide/)。
## 加载 Hugging Face 模型和 Spaces
Gradio 与[Hugging Face Hub](https://hf.co)完美集成，只需一行代码即可加载模型和 Spaces。要使用它，只需在 `Interface` 类中使用 `load()` 方法。所以：
- 要从 Hugging Face Hub 加载任何模型并围绕它创建一个界面，您需要传递 `"model/"` 或 `"huggingface/"`，后面跟着模型名称，就像这些示例一样：
```python
gr.Interface.load("huggingface/gpt2").launch();
```
```python
gr.Interface.load("huggingface/EleutherAI/gpt-j-6B",
inputs=gr.Textbox(lines=5, label="Input Text") # customizes the input component
).launch()
```
- 要从 Hugging Face Hub 加载任何 Space 并在本地重新创建它（这样您可以自定义输入和输出），您需要传递 `"spaces/"`，后面跟着模型名称：
```python
gr.Interface.load("spaces/eugenesiow/remove-bg", inputs="webcam", title="Remove your webcam background!").launch()
```
使用 Gradio 使用加载 Hugging Face 模型或 spaces 的一个很棒的功能是，您可以立即像 Python 代码中的函数一样使用生成的 `Interface` 对象（这适用于每种类型的模型 / 空间：文本，图像，音频，视频，甚至是多模态模型）：
```python
io = gr.Interface.load("models/EleutherAI/gpt-neo-2.7B")
io("It was the best of times") # outputs model completion
```
## 并行和串行放置接口
Gradio 还可以使用 `gradio.Parallel` 和 `gradio.Series` 类非常容易地混合接口。`Parallel` 允许您将两个相似的模型（如果它们具有相同的输入类型）并行放置以比较模型预测：
```python
generator1 = gr.Interface.load("huggingface/gpt2")
generator2 = gr.Interface.load("huggingface/EleutherAI/gpt-neo-2.7B")
generator3 = gr.Interface.load("huggingface/EleutherAI/gpt-j-6B")
gr.Parallel(generator1, generator2, generator3).launch()
```
`Series` 允许您将模型和 spaces 串行放置，将一个模型的输出传输到下一个模型的输入。
```python
generator = gr.Interface.load("huggingface/gpt2")
translator = gr.Interface.load("huggingface/t5-small")
gr.Series(generator, translator).launch() # this demo generates text, then translates it to German, and outputs the final result.
```
当然，您还可以在适当的情况下同时使用 `Parallel` 和 `Series`！
在[文档](https://gradio.app/docs#parallel)中了解有关并行和串行 (`Parallel` 和 `Series`) 的更多信息。

0
guides/cn/02_building-interfaces/05_four-kinds-of-interfaces.md → guides/cn/02_building-interfaces/04_four-kinds-of-interfaces.md
View File

2
guides/cn/05_tabular-data-science-and-plots/using-gradio-for-tabular-workflows.md
View File

@ -95,7 +95,7 @@ import gradio as gr
title = "Supersoaker产品缺陷预测"
description = "该模型预测Supersoaker生产线故障。在下面的数据帧组件中，您可以拖放数据集的任意切片或自行编辑值。"
gr.Interface.load("huggingface/scikit-learn/tabular-playground", title=title, description=description).launch()
gr.load("huggingface/scikit-learn/tabular-playground", title=title, description=description).launch()
```
<gradio-app space="gradio/gradio-skops-integration"></gradio-app>

181
guides/cn/07_other-tutorials/custom-interpretations-with-blocks.md
View File

@ -1,181 +0,0 @@
# 使用 Blocks 进行自定义机器学习解释
Tags: INTERPRETATION, SENTIMENT ANALYSIS
**前提条件**: 此指南要求您了解 Blocks 和界面的解释功能。请确保[首先阅读 Blocks 指南](https://gradio.app/quickstart/#blocks-more-flexibility-and-control)以及[高级界面功能指南](/advanced-interface-features#interpreting-your-predictions)的解释部分。
## 简介
如果您有使用界面类的经验，那么您就知道解释机器学习模型的预测有多么容易，只需要将 `interpretation` 参数设置为 "default" 或 "shap" 即可。
您可能想知道是否可以将同样的解释功能添加到使用 Blocks API 构建的应用程序中。不仅可以做到，而且 Blocks 的灵活性还可以以不可能使用界面来显示解释的方式！
本指南将展示如何：
1. 在 Blocks 应用程序中重新创建界面的解释功能的行为。
2. 自定义 Blocks 应用程序中的解释显示方式。
让我们开始吧！
## 设置 Blocks 应用程序
让我们使用 Blocks API 构建一款情感分类应用程序。该应用程序将以文本作为输入，并输出此文本表达负面或正面情感的概率。我们会有一个单独的输入 `Textbox` 和一个单独的输出 `Label` 组件。以下是应用程序的代码以及应用程序本身。
```python
import gradio as gr
from transformers import pipeline
sentiment_classifier = pipeline("text-classification", return_all_scores=True)
def classifier(text):
pred = sentiment_classifier(text)
return {p["label"]: p["score"] for p in pred[0]}
with gr.Blocks() as demo:
with gr.Row():
with gr.Column():
input_text = gr.Textbox(label="Input Text")
with gr.Row():
classify = gr.Button("Classify Sentiment")
with gr.Column():
label = gr.Label(label="Predicted Sentiment")
classify.click(classifier, input_text, label)
demo.launch()
```
<gradio-app space="freddyaboulton/sentiment-classification"> </gradio-app>
## 向应用程序添加解释
我们的目标是向用户呈现输入中的单词如何 contributed 到模型的预测。
这将帮助用户理解模型的工作方式，并评估其有效性。
例如，我们应该期望我们的模型能够将“happy”和“love”这些词与积极的情感联系起来；如果模型没有联系起来，那么这意味着我们在训练过程中出现了错误！
对于输入中的每个单词，我们将计算模型预测的积极情感如何受该单词的影响。
一旦我们有了这些 `(word, score)` 对，我们就可以使用 Gradio 将其可视化给用户。
[shap](https://shap.readthedocs.io/en/stable/index.html) 库将帮助我们计算 `(word, score)` 对，而 Gradio 将负责将输出显示给用户。
以下代码计算 `(word, score)` 对：
```python
def interpretation_function(text):
explainer = shap.Explainer(sentiment_classifier)
shap_values = explainer([text])
# Dimensions are (batch size, text size, number of classes)
# Since we care about positive sentiment, use index 1
scores = list(zip(shap_values.data[0], shap_values.values[0, :, 1]))
# Scores contains (word, score) pairs
# Format expected by gr.components.Interpretation
return {"original": text, "interpretation": scores}
```
现在，我们所要做的就是添加一个按钮，在单击后运行此函数。
为了显示解释，我们将使用 `gr.components.Interpretation`。
这将使输入中的每个单词变成红色或蓝色。
如果它有助于积极情感，则为红色，如果它有助于负面情感，则为蓝色。
这就是界面如何显示文本的解释输出。
```python
with gr.Blocks() as demo:
with gr.Row():
with gr.Column():
input_text = gr.Textbox(label="Input Text")
with gr.Row():
classify = gr.Button("Classify Sentiment")
interpret = gr.Button("Interpret")
with gr.Column():
label = gr.Label(label="Predicted Sentiment")
with gr.Column():
interpretation = gr.components.Interpretation(input_text)
classify.click(classifier, input_text, label)
interpret.click(interpretation_function, input_text, interpretation)
demo.launch()
```
<gradio-app space="freddyaboulton/sentiment-classification-interpretation"> </gradio-app>
## 自定义解释的显示方式
`gr.components.Interpretation` 组件以很好的方式显示单个单词如何 contributed 到情感预测，但是如果我们还想显示分数本身，怎么办呢？
一种方法是生成一个条形图，其中单词在水平轴上，条形高度对应 shap 得分。
我们可以通过修改我们的 `interpretation_function` 来执行此操作，以同时返回一个 matplotlib 条形图。我们将在单独的选项卡中使用 'gr.Plot' 组件显示它。
这是解释函数的外观：
```python
def interpretation_function(text):
explainer = shap.Explainer(sentiment_classifier)
shap_values = explainer([text])
# Dimensions are (batch size, text size, number of classes)
# Since we care about positive sentiment, use index 1
scores = list(zip(shap_values.data[0], shap_values.values[0, :, 1]))
scores_desc = sorted(scores, key=lambda t: t[1])[::-1]
# Filter out empty string added by shap
scores_desc = [t for t in scores_desc if t[0] != ""]
fig_m = plt.figure()
# Select top 5 words that contribute to positive sentiment
plt.bar(x=[s[0] for s in scores_desc[:5]],
height=[s[1] for s in scores_desc[:5]])
plt.title("Top words contributing to positive sentiment")
plt.ylabel("Shap Value")
plt.xlabel("Word")
return {"original": text, "interpretation": scores}, fig_m
```
以下是应用程序代码：
```python
with gr.Blocks() as demo:
with gr.Row():
with gr.Column():
input_text = gr.Textbox(label="Input Text")
with gr.Row():
classify = gr.Button("Classify Sentiment")
interpret = gr.Button("Interpret")
with gr.Column():
label = gr.Label(label="Predicted Sentiment")
with gr.Column():
with gr.Tabs():
with gr.TabItem("Display interpretation with built-in component"):
interpretation = gr.components.Interpretation(input_text)
with gr.TabItem("Display interpretation with plot"):
interpretation_plot = gr.Plot()
classify.click(classifier, input_text, label)
interpret.click(interpretation_function, input_text, [interpretation, interpretation_plot])
demo.launch()
```
demo 在这里 !
<gradio-app space="freddyaboulton/sentiment-classification-interpretation-tabs"> </gradio-app>
## Beyond Sentiment Classification （超越情感分类）
尽管到目前为止我们已经集中讨论了情感分类，但几乎可以为任何机器学习模型添加解释。
输出必须是 `gr.Image` 或 `gr.Label`，但输入几乎可以是任何内容 (`gr.Number`, `gr.Slider`, `gr.Radio`, `gr.Image`)。
这是一个使用 Blocks 构建的图像分类模型解释演示：
<gradio-app space="freddyaboulton/image-classification-interpretation-blocks"> </gradio-app>
## 结语
我们深入地探讨了解释的工作原理以及如何将其添加到您的 Blocks 应用程序中。
我们还展示了 Blocks API 如何让您控制解释在应用程序中的可视化方式。
添加解释是使您的用户了解和信任您的模型的有用方式。现在，您拥有了将其添加到所有应用程序所需的所有工具！

110
guides/cn/07_other-tutorials/setting-up-a-demo-for-maximum-performance.md
View File

@ -1,110 +0,0 @@
# 最佳性能的演示 (Maximum Performance)
Tags: QUEUE, PERFORMANCE
假设您的 Gradio 演示在社交媒体上迅速走红-有很多用户同时尝试，您希望为用户提供最佳体验，换句话说就是尽量减少每个用户等待队列中查看他们的预测结果的时间。
如何配置您的 Gradio 演示以处理最大流量？在本指南中，我们将深入介绍 Gradio 的 `.queue()` 方法以及其他相关配置的一些参数，并讨论如何设置这些参数，以便您可以同时为大量用户提供服务，并使延迟保持最小。
这是一份高级指南，请确保您已经了解 Gradio 的基础知识，例如[如何创建和启动 Gradio 界面](https://gradio.app/quickstart/)。本指南中的大部分信息对于您是将演示托管在[Hugging Face Spaces](https://hf.space)还是在自己的服务器上都是相关的。
## 启用 Gradio 的队列系统
默认情况下，Gradio 演示不使用队列，而是通过 POST 请求将预测请求发送到托管 Gradio 服务器和 Python 代码的服务器。然而，常规 POST 请求有两个重要的限制：
(1) 它们会超时-大多数浏览器在 POST 请求在很短的时间（例如 1 分钟）内没有响应时会引发超时错误。
如果推理功能运行时间超过 1 分钟，或者当同时有很多人尝试您的演示时，增加了延迟。
(2) 它们不允许 Gradio 演示和 Gradio 服务器之间的双向通信。这意味着，例如，您无法实时获得您的预测完成所需的预计时间。
为了解决这些限制，任何 Gradio 应用都可以通过在 Interface 或 Blocks 启动之前添加 `.queue()` 来转换为使用 **websockets**。以下是一个示例：
```py
app = gr.Interface(lambda x:x, "image", "image")
app.queue() # <-- Sets up a queue with default parameters
app.launch()
```
在上面的演示 `app` 中，预测现在将通过 websocket 发送。
与 POST 请求不同，websocket 不会超时并且允许双向通信。在 Gradio 服务器上，设置了一个 **queue 队列**，它将每个到达的请求添加到列表中。当一个工作线程可用时，第一个可用的请求将传递给工作线程用于预测。预测完成后，队列通过 websocket 将预测结果发送回调用该预测的特定 Gradio 用户。
注意：如果您将 Gradio 应用程序托管在[Hugging Face Spaces](https://hf.space)，队列已经 **enabled by default 默认启用**。您仍然可以手动调用 `.queue()` 方法以配置下面描述的队列参数。
## 队列参数 （Queuing Parameters）
有几个参数可用于配置队列，并帮助减少延迟。让我们逐个介绍。
### `concurrency_count` 参数
我们将首先探讨 `queue()` 的 `concurrency_count` 参数。该参数用于设置在 Gradio 服务器中将并行处理请求的工作线程数。默认情况下，此参数设置为 `1`，但增加此参数可以**线性增加服务器处理请求的能力**。
那为什么不将此参数设置得更高呢？请记住，由于请求是并行处理的，每个请求将消耗内存用于存储处理的数据和权重。这意味着，如果您将 `concurrency_count` 设置得过高，可能会导致内存溢出错误。如果 `concurrency_count` 过高，也可能出现不断切换不同工作线程的成本导致收益递减的情况。
**推荐**：将 `concurrency_count` 参数增加到能够获得性能提升或达到机器内存限制为止。您可以[在此处了解有关 Hugging Face Spaces 机器规格的信息](https://huggingface.co/docs/hub/spaces-overview)。
_注_：还有第二个参数可控制 Gradio 能够生成的*总*线程数，无论是否启用队列。这是 `launch()` 方法中的 `max_threads` 参数。当您增加 `queue()` 中的 `concurrency_count` 参数时，此参数也会自动增加。然而，在某些情况下，您可能希望手动增加此参数，例如，如果未启用队列。
### `max_size` 参数
减少等待时间的更直接的方法是防止过多的人加入队列。您可以使用 `queue()` 的 `max_size` 参数设置队列处理的最大请求数。如果请求在队列已经达到最大大小时到达，它将被拒绝加入队列，并且用户将收到一个错误提示，指示队列已满，请重试。默认情况下，`max_size=None`，表示没有限制可以加入队列的用户数量。
矛盾地，设置 `max_size` 通常可以改善用户体验，因为它可以防止用户因等待时间过长而被打消兴趣。对您的演示更感兴趣和投入的用户将继续尝试加入队列，并且能够更快地获得他们的结果。
**推荐**：为了获得更好的用户体验，请设置一个合理的 `max_size`，该值基于用户对预测所愿意等待多长时间的预期。
### `max_batch_size` 参数
增加 Gradio 演示的并行性的另一种方法是编写能够接受**批次**输入的函数。大多数深度学习模型可以比处理单个样本更高效地处理批次样本。
如果您编写的函数可以处理一批样本，Gradio 将自动将传入的请求批量处理并作为批量样本传递给您的函数。您需要将 `batch` 设置为 `True`（默认为 `False`），并根据函数能够处理的最大样本数设置 `max_batch_size`（默认为 `4`）。这两个参数可以传递给 `gr.Interface()` 或 Blocks 中的事件，例如 `.click()`。
虽然设置批次在概念上与使工作线程并行处理请求类似，但对于深度学习模型而言，它通常比设置 `concurrency_count` 更快。缺点是您可能需要稍微调整函数以接受批次样本而不是单个样本。
以下是一个不接受批次输入的函数的示例-它一次处理一个输入：
```py
import time
def trim_words(word, length):
return word[:int(length)]
```
这是相同函数的重写版本，接受一批样本：
```py
import time
def trim_words(words, lengths):
trimmed_words = []
for w, l in zip(words, lengths):
trimmed_words.append(w[:int(l)])
return [trimmed_words]
```
# Setup 安装和设置
**建议**：如果可能的话，请编写接受样本批次的函数，然后将 `batch` 设置为 `True`，并根据计算机的内存限制将 `max_batch_size` 设置得尽可能高。如果将 `max_batch_size` 设置为尽可能高，很可能需要将 `concurrency_count` 重新设置为 `1`，因为您将没有足够的内存来同时运行多个工作线程。
### `api_open` 参数
在创建 Gradio 演示时，您可能希望将所有流量限制为通过用户界面而不是通过自动为您的 Gradio 演示创建的[编程 API](/sharing_your_app/#api-page)进行。这一点很重要，因为当人们通过编程 API 进行请求时，可能会绕过正在等待队列中的用户并降低这些用户的体验。
**建议**：在演示中将 `queue()` 中的 `api_open` 参数设置为 `False`，以防止程序化请求。
### 升级硬件（GPU，TPU 等）
如果您已经完成了以上所有步骤，但您的演示仍然不够快，您可以升级模型运行的硬件。将模型从 CPU 上运行切换到 GPU 上运行，深度学习模型的推理时间通常会提高 10 倍到 50 倍。
在 Hugging Face Spaces 上升级硬件非常简单。只需单击自己的 Space 中的 "Settings" 选项卡，然后选择所需的 Space 硬件。
![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/spaces-gpu-settings.png)
虽然您可能需要调整部分机器学习推理代码以在 GPU 上运行（如果您使用 PyTorch，[这里有一个方便的指南](https://cnvrg.io/pytorch-cuda/)），但 Gradio 对于硬件选择是完全无感知的，无论您是使用 CPU、GPU、TPU 还是其他任何硬件，都可以正常工作！
注意：您的 GPU 内存与 CPU 内存不同，因此如果您升级了硬件，您可能需要调整上面描述的`concurrency_count` 参数的值。
## 结论
祝贺您！您已经了解如何设置 Gradio 演示以获得最佳性能。祝您在下一个病毒式演示中好运！

2
js/_website/generate_jsons/src/guides/__init__.py
View File

@ -87,7 +87,7 @@ for guide_folder in guide_folders:
guide_content = re.sub(
r"(\n\nTip: )(.*?)(?=\n\n|$)",
lambda x: f"<p class='tip'>💡 {x.group(2)}</p>",
lambda x: f"<p class='tip'><strong>✍️ Tip:</strong> {x.group(2)}</p>",
guide_content,
)

4
js/_website/src/lib/assets/style.css
View File

@ -198,6 +198,10 @@ code.language-bash {
@apply bg-gradient-to-br from-orange-50 to-white border-orange-50 border-l-2 border-l-orange-300 text-orange-700 p-4 px-6;
}
.tip strong {
@apply text-orange-700;
}
.tip code {
@apply text-orange-700;
}

6
js/_website/vercel.json
View File

@ -90,7 +90,11 @@
},
{
"source": "/advanced-interface-features",
"destination": "/guides/advanced-interface-features"
"destination": "/guides/using-hugging-face-integrations"
},
{
"source": "guides/advanced-interface-features",
"destination": "guides/using-hugging-face-integrations"
},
{
"source": "/key-features",

17
pyproject.toml
View File

@ -13,14 +13,15 @@ description = "Python library for easily interacting with trained machine learni
license = "Apache-2.0"
requires-python = ">=3.8"
authors = [
{ name = "Abubakar Abid", email = "team@gradio.app" },
{ name = "Ali Abid", email = "team@gradio.app" },
{ name = "Ali Abdalla", email = "team@gradio.app" },
{ name = "Dawood Khan", email = "team@gradio.app" },
{ name = "Ahsen Khaliq", email = "team@gradio.app" },
{ name = "Pete Allen", email = "team@gradio.app" },
{ name = "Ömer Faruk Özdemir", email = "team@gradio.app" },
{ name = "Freddy A Boulton", email = "team@gradio.app" },
{ name = "Abubakar Abid", email = "gradio-team@huggingface.co" },
{ name = "Ali Abid", email = "gradio-team@huggingface.co" },
{ name = "Ali Abdalla", email = "gradio-team@huggingface.co" },
{ name = "Dawood Khan", email = "gradio-team@huggingface.co" },
{ name = "Ahsen Khaliq", email = "gradio-team@huggingface.co" },
{ name = "Pete Allen", email = "gradio-team@huggingface.co" },
{ name = "Ömer Faruk Özdemir", email = "gradio-team@huggingface.co" },
{ name = "Freddy A Boulton", email = "gradio-team@huggingface.co" },
{ name = "Hannah Blair", email = "gradio-team@huggingface.co" },
]
keywords = ["machine learning", "reproducibility", "visualization"]

24
readme_template.md
View File

@ -1,7 +1,6 @@
<div align="center">
[<img src="readme_files/gradio.svg" alt="gradio" width=400>](https://gradio.app)<br>
<em>Build & share delightful machine learning apps easily</em>
[![gradio-backend](https://github.com/gradio-app/gradio/actions/workflows/backend.yml/badge.svg)](https://github.com/gradio-app/gradio/actions/workflows/backend.yml)
[![gradio-ui](https://github.com/gradio-app/gradio/actions/workflows/ui.yml/badge.svg)](https://github.com/gradio-app/gradio/actions/workflows/ui.yml)
@ -21,26 +20,17 @@
# Gradio: Build Machine Learning Web Apps — in Python
Gradio is an open-source Python library that is used to build machine learning and data science demos and web applications.
With Gradio, you can quickly create a beautiful user interface around your machine learning models or data science workflow and let people "try it out" by dragging-and-dropping in their own images,
pasting text, recording their own voice, and interacting with your demo, all through the browser.
![Interface montage](readme_files/header-image.jpg)
Gradio is useful for:
- **Demoing** your machine learning models for clients/collaborators/users/students.
- **Deploying** your models quickly with automatic shareable links and getting feedback on model performance.
- **Debugging** your model interactively during development using built-in input manipulation tools.
$getting_started
## Questions?
If you'd like to report a bug or have a feature request, please create an [issue on GitHub](https://github.com/gradio-app/gradio/issues/new/choose). For general questions about usage, we are available on [our Discord server](https://discord.com/invite/feTf9x3ZSB) and happy to help.
If you like Gradio, please leave us a ⭐ on GitHub!
## Open Source Stack
Gradio is built with many wonderful open-source libraries, please support them as well!
Gradio is built on top of many wonderful open-source libraries!
[<img src="readme_files/huggingface_mini.svg" alt="huggingface" height=40>](https://huggingface.co)
[<img src="readme_files/python.svg" alt="python" height=40>](https://www.python.org)

2
render_readme.py
View File

@ -8,6 +8,8 @@ GETTING_STARTED_TEMPLATE_FILEPATH = "guides/01_getting-started/01_quickstart.md"
readme_template = Path(README_TEMPLATE_FILEPATH).read_text()
getting_started_template = Path(GETTING_STARTED_TEMPLATE_FILEPATH).read_text()
getting_started_template = getting_started_template.replace("# Quickstart", "")
getting_started_template = getting_started_template.replace("Tip:", "> [!TIP]\n >")
# Extract all the code and demo tags from the getting started template
code_tags = re.findall(r"\$code_([^\s]+)", getting_started_template)

11
scripts/launch_website.sh
View File

@ -3,13 +3,8 @@
cd "$(dirname ${0})/.."
source scripts/helpers.sh
npm_required
pnpm_required
echo "Building the website..."
set -e
cd website/homepage
LATEST_COMMIT=$(git log -1 --format="%H")
npm install
npm run build --url=https://gradio-main-build.s3.amazonaws.com/$LATEST_COMMIT/
cd build
python -m http.server
cd js/_website
pnpm dev