Gradio

Егор Горбань — Data Engineer

Gradio: Overview

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.

Типы приложений

gr.Blocks - кастомное приложение: базовый класс;
Интерфейсы
- gr.Interface - input-output интерфейс;
- gr.ChatInterface - чат-интерфейс;
- gr.TabbedInterface - приложение, разделённое на несколько tab-секций. То есть несколько приложений внутри одного;

Каждое приложение в Gradio - это экземпляр класса Blocks или класса-наследника Blocks.
Класс Blocks можно использовать для создания кастомных приложений, подобных тем что мы рассматривали в Streamlit, то есть это любой сколько угодно сложный набор компонентов, которые могут быть связаны между собой, например один компонент триггерит другой, вывод одного компонента является вводом для другого, и так далее.
Есть несколько типов специальных приложений, находящихся во фреймворке. Они называются интерфейсами и являются наследниками класса Blocks.
1. Interface - Это класс, который предоставляет возможность для создания input-output блоков, то есть такая обёртка над питоновской функцией = что-то загружаем в функцию и что-то из неё получаем в интерактивном режиме.
2. ChatInterface - Это специальный класс позволяющий создавать только чаты, то есть возможность для ввода, отображение истории и под капотом будет какая-то функция, принимающая текстовый input пользователя и возвращающая некоторый ответ
3. Сюда же можно отнести таб-интерфейс, по сути это надстройка, позволяющая объединять несколько приложений в рамках одного, разделяя их на секции, при это каждая секция - это отдельное приложение.
В целом вы можете создать свой класс, отнаследовавшись от Blocks, но в большинстве случаев этого делать не нужно.

Интерфейс

Запуск любого приложения: gradio <filename.py> или python <filename.py>

gr.Interface — input-output приложение, позволяющее в интерактивном режиме взаимодействовать с пользователем.

import gradio as gr
import pandas as pd

df = pd.read_csv("examples/data/sales.csv")


def get_sample_dataframe(
    sample_size,
):
    return df.sample(sample_size)


demo = gr.Interface(
    fn=get_sample_dataframe,
    inputs=["number"], # inputs=[gr.Number()],
    outputs=["dataframe"], # outputs=[gr.DataFrame()],
)
demo.launch()

Запустить приложение можно либо через команду gradio, либо напрямую через python - разница в том, что в первом случае gradio будет отслеживать изменения и автоматически перезапускать приложение.

Рассмотрим пример базового приложения. Потом более детально рассмотрим разные объекты, которыми мы можем пользоваться, сейчас просто поговорим об общей структуре.

Основной объект здесь - это объект класса gradio.Interface;
Мы создаём объект этого класса, называем его demo, и потом вызываем метод launch, который отрисовывает нам этот объект;
в качестве параметра fn передаём функцию, над которой хотим сделать визуальную обёртку;
в качестве input - набор аргументов этой функции с указанием типа, каждый элемент списка это определенный компонент градио;
В качестве output - набор возвращаемых значений функции.

Приложение будет работать в интерактивном режиме.

Интерфейс: Data Flow

input —>
1. preprocessing - преобразование к объекту Python
2. function prosessing
3. postprocessing - преобразование к объекту HTML
—> output
Например gr.Image может быть картинкой (np.ndarray), путём до файла с картинкой (str), списком путей до файлов (list[str]).

Рассмотрим data-flow для приложения интерфейс.

Объект, который вводит пользователь автоматически препроцессится для преобразования к машинному формату. Затем он преобразуется вашей функцией, которую вы передали как параметр fn. Затем результата выполнения постпроцессится, и результат отображается на экране.

Пре- и постпроцессинг используется автоматически, чтобы преобразовать данные из тех что загружает пользователь в те, что мы можем использовать в коде. Например картинка при препроцессинге по умолчанию преобразуется в numpy array, и обратно массив, которая возвращает функция автоматически преобразуется в картинку, которая показывается пользователю как output. Препроцессинг также позволяет особо не волноваться о типе возвращаемого функцией значения, например если мы указали в output картинку, то из функции мы можем вернуть как саму картинку в виде массива или объекта PIL, так и путь до файла, или даже список путей - тогда отобразится галерея изображений.

Интерфейс: специальные возможности

можно указать, каким образом препроцессить input

demo = gr.Interface(
    fn=your_func,
    inputs=[gr.Image(type="pil"), gr.DataFrame(type='polars')],
    outputs=["dataframe"],
)

input/output могут отсутствовать

gr.Interface(
    fn=predict,
    inputs=None,
    outputs=["str"],
)

Интерфейс: специальные возможности

можно добавить примеры для тестирования интерфейса

gr.Interface(
    fn=predict,
    inputs=gr.Image(type="pil"),
    outputs=gr.Label(num_top_classes=3),
    examples=["lion.jpg", "cheetah.jpg"]
)

Рассмотрим дополнительные возможности класса Interface, которые позволяют создавать разные типы приложений.

С помощью аргумента type мы можем указать, как именно мы хотим получить input от пользователя, то есть какого типа будет входящая переменная для функции. Так например gradio позволяет преобразовывать картинку загруженную пользователь в объект Pil класса Pillow, что позволит не кастовать ничего самостоятельно.
Можем добавить разные примеры для тестирования. Например у нас есть интерфейс, который принимает изображение и возвращает топ-3 предсказания для описания объекта на изображении. Мы можем добавить две картинки в качестве примера , чтобы пользователь мог выбрать их в качестве input и протестировать интерфейс.
Вообще в целом довольно много паираметров, которые можно передать в конструктор, не только examples, но в основном там параметры позволяющие кастомизировать внешний вид интерфейса
могут отсутствовать input/output. Например приложение не зависит от пользовательского инпута, а просто раз в минуту генерирует цитаты. Или наоборот, input есть, например загрузка audio,а всё что делает приложение - сохраняет аудио в базу данных.

Чат-интерфейс

gr.ChatInterface - приложение-чат

input —
1. message: str
2. history: list[tuple[str, str]]
output — ret_val: str

import random

import gradio as gr


def magic_answer(message, history):
    return random.choice(["Yes", "No"])


demo = gr.ChatInterface(magic_answer)
demo.launch()

Перейдем к следующему типу приложений: ChatInterface. Рассмотрим пример приложения с чатами. Здесь похожая история с обёрткой над функцией, но ситуация немного упростилась - больше не надо писать типы input и output компонентов. Input - это всегда два компонента: текущее сообщение пользователя и история переписки, в виде массива, каждый элемент которого - пара “сообщение пользователя - ответ программы”. Output - всегда в строковом формате - ответ программы на новое сообщение пользователя. Также этот интерфейс предоставляет три кнопки - повтор последнего сообщения, удаление последнего сообщения вместе с ответом программы и очистка всего чата.

В качестве примера рассмотрим приложение, которое просто рандомно отвечает “да” или “нет” на сообщения пользователя.

`gr.Blocks`

Наконец рассмотрим более общий класс, который позволяет создать практически сколь угодно сложное приложение, подобно тому как мы строили приложения с помощью Streamlit.

import gradio as gr
def update(name):
    return f"Welcome to Gradio, {name}!"

with gr.Blocks() as demo:
    # Отформатированный текст
    gr.Markdown("Start typing _below_ and then click **Run** to see the output.")

    # Вёрстка: компоновка элементов в строку
    with gr.Row():
        # текстовое поле
        inp = gr.Textbox(placeholder="What is your name?")
        # текстовый ввод
        out = gr.Textbox()

    # Кнопка
    btn = gr.Button("Run")

    # действие при нажатии на кнопку
    btn.click(fn=update, inputs=inp, outputs=out)

demo.launch()

`gr.Blocks` - Data Flow

свободный flow — зависит от вашей фантазии

общие возможности:

кнопочка к которой прикреплено событие

with gr.Blocks() as demo:
    ...
    def update(inp_item):
        ...

    inp = ... # компонент
    out = ... # компонент

    btn = gr.Button("Act")
    btn.click(fn=update, inputs=inp, outputs=out)

real-time change

    with gr.Blocks() as demo:
        ...
        def update(inp_item):
            ...

        inp = ... # компонент
        out = ... # компонент

        inp.change(update, inp, out)

интерактивность

text_area = gr.Textbox(..., interactive=True)

flow в общем свободный - можно составлять приложение из доступных компонентов
самое простое что мы уже видели - навесить событие на кнопку. В данном случае при нажатии она вызывает функцию update, передавая значение компоненты inp в качестве аргумента функции, и после завершения работы функции перезаписывает полученным значением значение компонента out.
Другая возможность: навесить событие на изменение компонента, тогда при изменении его содержимого, другой компонент будет меняться.
По умолчанию компоненты которые используются для инпута интерактивны, то есть могут меняться пользователем, а компоненты для output неинтерактивны, то есть только отображают контент. Это можно изменить, поставив флаг interactive.

Компоненты

List of components
Custom Components
Демонстрация контента: Label, DataFrame, Code, Chatbot, Image, Video, BarPlot, etc
Виджеты: Radio, Slider, UploadButton, etc

Компоненты

AnnotatedImage: картинки с аннотациями объектов

Компоненты

MultimodalTextbox - поле ввода, в которое можно загружать мульти-медиа
Model3D - 3D модель в формате .obj, .glb, .stl, .gltf, .splat, .ply

Переменные состояния

Состояние: глобальное и локальное (в пределах сессии)

Global State — переменные в global scope.

Определение в глобальной области видимости.
Синглтон для всех пользователей.

Пример

import gradio as gr

global_list = []

def add_item(item):
    global_list.append(item)
    return global_list

demo = gr.Interface(add_item, gr.Textbox(), gr.JSON(label="All items"))
demo.launch()

Рассмотрим как использовать состояние сессии.

В отличие от Streamlit, в Gradio есть ещё глобальное состояние, оно достигается с помощью использования переменных в глобальном окружении. Хотя в целом в терминах градио это можно считать cached_resource
В качестве примера рассмотрим ситуацию когда у нас в global scope находится изменяемый объект, в данном случае список
Причем здесь нужно обратить внимание, что переменные общие для всех пользователей, поэтому если несколько пользователей будут изменять значение изменяемой глобальной переменной, например добавлять в список какие-то элементы, то список будет обновлён у всех пользователей.

Переменные состояния

Session State — переменные сессии.

Доступ через gr.State().
Синглтон для сессии
Для интерфейсов доступна только одна переменная, для Blocks — сколько угодно
Пример для gr.Interface (history — обращение к singleton)

import gradio as gr

def store_message(message: str, history: list[str]):
    output = {
        "Current messages": message,
        "Previous messages": history[::-1]
    }
    history.append(message)
    return output, history

demo = gr.Interface(
    fn=store_message, 
    inputs=["textbox", gr.State(value=[])], 
    outputs=["json", gr.State()]
)

demo.launch()

Также есть и обычные переменные со временем жизни в одну сессию, они доступны через объект gr.State
Для интерфейсов доступна только одна переменная, для Blocks — сколько угодно
Давайте рассмотрим пример приложения интерфейс с сохранением истории сообщений - что-то отдаленно напоминающее чат инфтерфейс
В качестве второго аргумента функции мы передаём объект gr.State(), указав начальное значение, которое используется при инициализации, – пустой список. Далее мы работаем с этим объектом внутри функции как с обычным питоновским списком, в частности вызываем метод append. И возвращаем этот объект, а в outputs маппим это значение опять же с переменной gr.State(). Gradio понимает что это один и тот же объект, и таким образом обновляет значение этой singleton-переменной, то есть при следующем вызове в функцию попадет уже не пустой список, а список с одним элементом, потом с двумя и так далее.

Переменные состояния

Пример для gr.Blocks

with gr.Blocks() as demo:
    words_singleton = gr.State(set()) # переменная сессии
    with gr.Row() as row:
        with gr.Column():
            input_letter = gr.Textbox(label="Enter word")
            btn = gr.Button("Add word")
        with gr.Column():
            session_words_box = gr.Textbox(label="Current words")

    def add_word(word, session_words):
        session_words.add(word)
        return [
            session_words, # присвоится синглтон-переменной `words_singleton`
            ", ".join(session_words),
        ]

    btn.click(
        add_word,
        [input_letter, words_singleton],
        [
            words_singleton, # обновляем синглтон-переменную через первый retval функции
            session_words_box
        ],
    )
demo.launch()

Рассмотрим также пример для Блоков – здесь мы можем сколько угодно переменных создать также через gr.State, но мы уже присваиваем это значение какой-то переменной и работаем дальше с ней как с ссылкой на singleton.
У нас есть функция add-word, которую мы навешиваем на кнопку
И в качестве второй переменной инпута мы как раз используем words_singleton в качестве аргумента, работаем с этим аргументом внутри функции, возвращаем его и подхватываем output’ом, обновляем singleton таким образом.
Пока мы не перезагрузим страницу, эта переменная будет накапливать все добавленные слова

Streaming

streaming outputs
- Вместо функции в интерфейсе используется генератор.
- Тогда значение будет перезаписываться по мере того как будут поступать новые yield-values
- Например: можно стримить вывод ML-модели.
```
import time
import gradio as gr


def magic_answer(message):
    for i in range(len(message)):
        time.sleep(0.1)
        yield message[: i + 1]


demo = gr.Interface(magic_answer, inputs=["text"], outputs=["text"])
demo.launch()
```

streaming inputs

Некоторые компоненты могут работать в “интерактивном режиме”

demo = gr.Interface(
    ...
    inputs = [
        ...
        gr.Audio(
            sources=[gr.Microphone()],
            streaming=True,
        ),
        ...
    ],
    ...
)

Есть два вида стриминга: output стриминг и input стриминг
Рассмотрим сначала output-стриминг: это может быть актуально например когда модель долго генерирует ответ и вы не хотите заставлять пользователя ждать. Тогда можно yield’ить то, что нагенерировано на текущий момент, и пользователь будет видеть процесс набора ответа, как например происходит в ChatGPT.
Это достигается с помощью того, что мы передаём в интерфейс не функцию, а генератор - тогда output будет перезаписываться вновь приходящими значениями.
В качестве примера рассмотрим приложение, где пользователь вводит сообщение, а мы просто возвращаем сообщение, но печатаем его по буквам с маленькой задержкой
input streaming - некоторые компоненты могут работать в “интерактивном режиме”, например Audio - для отправки аудиозаписи с микрофона, или Image - для отправки кадров с видеокамеры.
Это достигается с помощью аргумента streaming. Например у нас один из входящих параметров - аудио, мы можем с помощью этого аргумента стримить аудио с микрофона
input streaming позволяет строить с помощью Gradio так называемые Реактивные интерфейсы

Reactive interfaces

Реактивный интерфейс - интерфейс который реагирует на изменение пользовательского ввода и позволяет “на лету” обновлять приложение и генерировать вывод не по нажатию кнопки “Submit”, а при изменении input.

live=True

demo = gr.Interface(
    ...
    live=True, # Reactive interface
    ...
)

Пример: Automatic Speech Recognition (тут больше примеров).

# libs are required: numpy, torch, torchaudio, transformers

import gradio as gr
import numpy as np
from transformers import pipeline

transcriber = pipeline("automatic-speech-recognition", model="openai/whisper-base.en")

def transcribe(stream, new_chunk):
    sr, y = new_chunk
    left_ch = y[:, 0].astype(np.float32) # костыль для получения одноканального аудио
    left_ch /= np.max(np.abs(left_ch))
    if stream is not None:
        stream = np.concatenate([stream, left_ch])
    else:
        stream = left_ch
    return stream, transcriber({"sampling_rate": sr, "raw": stream})["text"]

demo = gr.Interface(
    transcribe,
    [gr.State(), gr.Audio(sources=[gr.Microphone()], streaming=True)],
    [gr.State(), gr.Textbox()],
    live=True,
)

demo.launch()

Реактивное приложение - приложение, которое реагирует на изменение пользовательского ввода, и при изменении вызывает функцию и обновляет output. Не нужно нажимать кнопку “Submit”, чтобы функция запустилась.

В качестве примера давайте рассмотрим приложение, которое генерирует текст распознавания речи realtime, получая стриминг голоса с пользовательского микрофона
Здесь стримится аудио с микрофона пользователя, и чанки склеиваются в один стрим. Стрим это инстанс переменной gr.State, то есть в пределах одной сессии у нас будет сохраняться значение этой переменной — это позволяет накапливать всю аудиодорожку в одну переменную для передачи её модельке.
Обратите внимание на streaming=True и live=True, этого достаточно чтобы построить реактивный интерфейс. Live=True позволяет обновлять аутпут на лету, а streaming=True позволяет отправлять input итеративно , стримить; без этого нам нужно было бы остановить запись, чтобы аудио завершилось, сохранилось, и только тогда реактивный интерфейс смог бы отреагировать на изменения.

Дополнительные возможности

Что можно делать с gr.Interface кроме launch?

gr.Interface.load — позволяет триггерить блок кода при запуске приложения
gr.load — позволяет загружать hugging-face модели из Serverless Inference API
```
import gradio as gr

demo = gr.load("Helsinki-NLP/opus-mt-en-es", src="models")
demo.launch()
```
gr.Interface.from_pipeline — конструирует интерфейс на основе transformers.Pipeline или diffusers.DiffusionPipeline. Подробнее
```
import gradio as gr
from transformers import pipeline

pipe = pipeline("image-classification")
gr.Interface.from_pipeline(pipe).launch()
```
gr.Interface.integrate - позволяет интегрироваться со сторонними ML-сервисами

Кроме обычного запуска интерфейса, gradio предоставляет ещё дополнительные возможности 1. Самое простое - это передать какую-то функцию, которая выполнится только при старте приложение, например это может быть настройка дефолтных значений, загрузка модели и прочих переменных, которые вы например не хотите выносить в глобальную область видимости 2. Есть ещё похожий метод, можно перепутать gr.load - без интерфейса. Этот метод тоже полезный, он позволяет загружать модели из API huggingface и автоматически конструирует приложение-интерфейс для взаимодействия с этой моделью 3. Похожая история с методом from_pipeline, который позволяет делать то же самое для пайплайнов из бибилиотек transformers.Pipeline и diffusers.DiffusionPipeline. 4. Также есть полезный метод Integrate, который позволяет интегрировать ваше приложение в сторонний ML-сервис: Comet, ONNX, Wandb - подробные гайды можно прочитать по ссылкам.

Развёртывание

demo.launch(share=True)

Выводы:

Подходит для создания интерфейсов для ML-моделей
Позволяет интерактивно взаимодействовать с пользователем
Подходит для создания чатботов
Есть интеграции с HuggingFace, transformers.pipeline, MlFlow и т.д.

Gradio

Gradio: Overview

Типы приложений

Интерфейс

Интерфейс: Data Flow

Интерфейс: специальные возможности

Интерфейс: специальные возможности

Чат-интерфейс

gr.Blocks

gr.Blocks - Data Flow

Компоненты

Компоненты

Компоненты

Переменные состояния

Переменные состояния

Переменные состояния

Streaming

Reactive interfaces

Дополнительные возможности

Развёртывание

Выводы:

`gr.Blocks`

`gr.Blocks` - Data Flow