Skip to main content

Gradio Notebooks

Gradio Notebook is a notebook component for generative AI that offers the fastest way to create a Hugging Face space in < 10 lines of code, and a familiar notebook interface for interacting with any combination of text, image and audio models in a single space.

You can:

  • Use any combination of text, image, or audio models in a single space, and even chain models together.
  • Experiment with models using a pre-built notebook UI, which is a familiar, intuitive interface for multimodal interaction.
  • Share space outputs with friends via a shareable URL.
  • Download your space config (prompts and model settings) as an aiconfig JSON file, and use it in your application via the AIConfig SDK.

5-minute Video Tutorial​

Examples​

notebook

Start here if you are a ...​

Features​

Demo

Gradio Notebook Structure​

Gradio Notebooks are inspired by Jupyter notebooks. Each Notebook is made up of prompt cells. The prompt is associated with a model and we run that model’s inference API call whenever the run button is clicked.

notebook

Parameters​

Parameters are variables that you can define and pass into any cell within your notebook. You can set both global parameters and local parameters.

For example, the prompt "A large, friendly {{animal}} wearing a {{color}} hat" generates the following images for different parameters:

notebook

Global Parameters​

You can set global parameters for your entire notebook. Click on Global Parameters on the top of your notebook and set your global parameters that can be used in any cell of the notebook.

Parameters

Local Parameters​

You can set local parameters that only apply to the cell you are in. Click on the cell sidebar and Local Parameters. Note: Local parameters will override the global parameters if they have the same name.

notebook

Model Chaining​

You can reference the output from one cell in another cell. This allows you to create complex, interconnected workflows within your notebook.

The image_gen prompt below uses the output of the prompt_1 using handlebars syntax (e.g {{prompt_1.output}})

Chaining

Download​

Click the download button on the top right to download the aiconfig.json file to captures the current state of your Space. Here’s an example Space and corresponding aiconfig.json file:

Reasons for Downloading:

  1. Save your changes to your Space
  • Refreshing your Space does not save changes. You need to upload the downloaded aiconfig.json file to your Space repo to lock in the state. Make sure you name your aiconfig.json file as my_app.aiconfig.json - it’s referenced in app.py.
  1. Build apps inspired by your Space
  • HuggingFace Spaces offer cool demos, but building an app with the tested models and prompts is challenging. However, by downloading the aiconfig.json file, you can use the prompts (and models) from your Space in your code with the AIConfig SDK.

Share Notebook​

Click the share button on the top right to get a link to a read-only copy of your Space to share with the rest of the world!

Sharing

For Space creators​

Quickstart​

  1. Create a new Space
  2. Design your Space
  3. Save your changes

1. Create a new Space​

Duplicate the Gradio Notebook Quickstart Space. Click the ⋮ symbol at the top right of the work space, then click “Duplicate this Space” and follow the instructions.

[manual] Create from scratch​

2. Design your Space​

Use the Gradio Notebook UI in your Space to set up models and prompts.

  • Click on the '+' symbol to add a new cell
  • Select the model for your cell by first choosing a Hugging Face Task. Each task has a default model associated with it, but you can override it by clicking the right side of the cell and changing the “model” field. The model you change to needs to be available on the Hugging Face Inference API - check the model card on Hugging Face.
  • Check out the Features section
warning

Edits/changes won’t save automatically and refreshing the page will lose your edits.

3. Save your changes and rebuild your space​

  • Click the download button on the top right. This captures the current state of your Space and downloads it as a <filename>.aiconfig.json file onto your computer (note that there are two periods in the filename).
  • Rename the downloaded file to my_app.aiconfig.json.
  • Replace the my_app.aiconfig.json in the Space repo with the one you just downloaded.

Anyone who now visits your Space will see the state represented by my_app.aiconfig.json.

Supported Models​

Inference API​

Gradio Notebooks support models which use the Hugging Face Inference API. Hugging Face Tasks that are supported:

Local Models​

Local models associated with most of the above tasks are also supported via Hugging Face Transformers and Diffusers library.

danger

Using local models will download the models to your Space, using up Space resources, even if the Space user is not an owner of the Space. Downloading the models will also require a significant wait when running a cell if they have not already been downloaded to your Space. Please be aware of these considerations when using local models. We are working on changing this behavior.

These local parsers can be used by adding them to the ModelParserRegistry for your Space. To do so:

  • add a model_parsers.py file in your Space repo
  • in the file, import the relevant model parser from aiconfig_extension_hugging_face
  • register the model parser in a register_model_parsers function

See https://huggingface.co/spaces/lastmileai/gradio_notebook_local_model/blob/main/model_parsers.py for an example model_parsers.py file. You can copy this file to your own Space and uncomment the desired local parsers.

Once the model_parsers.py file is created, simply reference it in app.py:

import gradio as gr
from gradio_notebook import GradioNotebook

with gr.Blocks() as demo:
    GradioNotebook(parsers_path="./model_parsers.py")

demo.queue().launch()

If a parsers_path is not specified for the GradioNotebook component, it will look for a model_parsers.py by default.

Gradio Notebook API​

Gradio Notebooks is built on top of the AIConfig specification which saves prompts, models settings and outputs in an aiconfig.json format. You can learn more about AIConfig here.

AIConfig comes with a Python & Node SDK that lets you use an AIConfig file in application code. Simply download the AIConfig from a Gradio Notebook Space, and use the AIConfig SDK to use that AIConfig in your application.

Build apps inspired by Spaces​​

You can easily build generative apps inspired by your work in Gradio Notebook Spaces! Both Space creators and Space viewers can download the aiconfig.json file to capture the state of their Space.

Use the aiconfig.json file in your code with the AIConfig SDK in 2 lines:

config = AIConfigRuntime.load('my_app.aiconfig.json')
model_output = await config.run('prompt_name')

AIConfig is an open-source framework. Message us on Discord if you have any feedback or questions!

Telemetry​

We track event logging for error diagnostics and feature improvements, but no personal information is logged. We also do not log prompt inputs or outputs. We collect metadata to gauge aggregated metrics such as:

  • number of Spaces created with Gradio Notebook components
  • number of viewers and notebook interactions
  • number of shares and downloads
  • errors

Please visit our open-source codebase to see more details.

Community & Support​

AIConfig is an open-source framework, we welcome your feedback and questions! Join our growing community for help, ideas, and discussions on AI.