Перейти к основному содержимому

Потоковые API

Потоковые API обеспечивают непрерывный поток данных по долгоживущему HTTP-соединению, что позволяет получать обновления в реальном времени для вашего приложения.

В отличие от REST API, которые передают данные в ответ на конкретные запросы, потоковые API предназначены для поддержания открытого соединения между клиентом и сервером с непрерывной отправкой данных по мере их поступления. Это особенно полезно для приложений, требующих обновлений в реальном времени, таких как результаты спортивных матчей в прямом эфире, тикеры фондового рынка, чат-приложения и уведомления в реальном времени.

Это снижает задержки и улучшает пользовательский опыт за счет предоставления немедленной обратной связи. Наиболее распространенный протокол для потоковых API — это события, отправляемые сервером (SSE), но в зависимости от требований приложения можно использовать и другие, такие как WebSockets.

Различия между REST API и потоковыми API​

Основное различие между REST API и потоковыми API заключается в методах передачи данных:

  • REST API:

    • Модель запрос/ответ: Клиент отправляет запрос, а сервер отвечает данными.
    • Жизненный цикл соединения: Каждый запрос/ответ является независимым, и сервер закрывает соединение после отправки ответа.
    • Сфера применения: Подходит для приложений, где данные не изменяются часто и обновления в реальном времени не критичны.
    • Пример ответа:
    {  
      "event": "match_score",
      "data": {
        "team1": "Red Dragons",
        "team2": "Silver Sharks",
        "score": "2-1"
      }
    }

  • Потоковые API (события, отправляемые сервером):

    • Непрерывный поток данных: Сервер поддерживает открытое соединение и непрерывно отправляет данные клиенту по мере их поступления.
    • Жизненный цикл соединения: Соединение остается открытым, что позволяет серверу отправлять новые данные клиенту без необходимости запроса со стороны клиента.
    • Сфера применения: Идеально для приложений, требующих обновлений в реальном времени, таких как результаты спортивных матчей в прямом эфире, уведомления в реальном времени и чат-приложения в прямом эфире.
    • Пример ответа:
    event: match_score
    data: {"team1": "Red Dragons", "team2": "Silver Sharks", "score": "2-1"}

    event: match_score
    data: {"team1": "Red Dragons", "team2": "Silver Sharks", "score": "3-1"}

    event: match_score
    data: {"team1": "Red Dragons", "team2": "Silver Sharks", "score": "3-2"}

Пример: Резюме обзора ИИ​

Давайте разберем, как использовать потоковые API в FlutterFlow, на примере приложения, которое позволяет пользователям просматривать резюме обзоров продуктов, сгенерированное ИИ. При загрузке страницы приложение отображает резюме ИИ в реальном времени, позволяя пользователям наблюдать за процессом анализа по мере его генерации.

Итоговое приложение выглядит так:

Шаги по созданию приложения следующие:

  1. Создание интерфейса
  2. Создание API
  3. Создание переменных состояния страницы
  4. Запуск и разбор ответа API
  5. Извлечение данных для диаграммы

1. Создание интерфейса​

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

  • Виджет Text: Отображает резюме обзоров, сгенерированное ИИ, и список положительных и отрицательных моментов, упомянутых в обзорах.
  • Виджет Chart (столбчатая диаграмма)`: Визуальное представление распределения настроений (положительное, нейтральное, отрицательное) в виде столбчатой диаграммы.

streaming-api-example-demo.png

2. Создание API​

Для создания этого приложения мы будем использовать API Chat Completion от OpenAI, чтобы генерировать резюме на основе предоставленных обзоров. Перед тем как строить что-либо, связанное с API в вашем приложении, важно создать и протестировать API, чтобы убедиться в их корректной работе. Поэтому давайте создадим и протестируем API Chat Completion в нашем проекте.

После создания откройте Расширенные настройки и включите переключатель Process Streaming Response.

Вот как это сделать:

3. Создание переменных состояния страницы​

В этом примере для хранения и отображения результата сгенерированного резюме ИИ вам понадобятся две переменные.

  1. summary: Эта переменная будет содержать полный текст резюме, включая общее настроение обзоров, ключевые моменты, упомянутые клиентами, и списки плюсов и минусов. Она инициализируется пустой строкой и позже обновляется текстом, сгенерированным ИИ.
  2. sentimentValues: Эта переменная будет хранить значения распределения настроений. Это список типа double, представляющий количество положительных, нейтральных и отрицательных обзоров. Обратите внимание, что эти значения будут использоваться для предоставления Bar Values в столбчатой диаграмме. Она инициализируется тремя нулями и позже обновляется фактическими счетчиками положительных, нейтральных и отрицательных обзоров. streaming-page-state.png

4. Запуск и извлечение данных из ответа API​

Вы можете запустить потоковое API так же, как и любое другое обычное API. Однако метод извлечения и разбора данных отличается от стандартного API. В отличие от непотоковых API, где вы получаете ответ в переменной выходных данных действия, потоковое API предоставляет данные через следующие действия ответа:

  • onMessage: Это действие срабатывает каждый раз, когда от потокового API поступает новый фрагмент данных. Вы можете использовать это действие для обновления интерфейса или выполнения любой логики с поступающими данными в реальном времени.
  • onError: Это действие срабатывает при ошибке в потоковом соединении. Вы можете использовать это действие для корректной обработки ошибок, например, отображения сообщения об ошибке пользователю или попытки переподключения.
  • onClose: Это действие срабатывает при закрытии потокового соединения. Вы можете использовать это действие для выполнения задач очистки или уведомления пользователя о завершении потока.

При получении данных вы можете получить доступ к телу ответа через OnMessage > Set Variable menu > Action Parameters > OnMessageInput. Затем используйте Response Stream Message Options для извлечения данных.

В этом конкретном примере мы используем опцию Server Sent Event Stream Data JSON и затем применяем этот путь JSON $['choices'][0]['delta']['content'] для получения данных истории.

Вот как это сделать:

5. Извлечение данных для диаграммы​

API возвращает подробное резюме в виде текста, но для отображения счетчиков положительных, нейтральных и отрицательных обзоров на диаграмме вам нужно извлечь эти данные из текста. Для этого вы можете написать простую пользовательскую функцию. После завершения потока передайте полный текст в пользовательскую функцию для извлечения соответствующих данных и сохраните вывод в переменной состояния страницы sentimentValues, которую мы создали ранее.

Вот как это сделать:

подсказка
  • После сохранения sentimentValues рекомендуется удалить те же точки данных из сгенерированного текста обзора, чтобы избежать избыточности.
  • Аналогично вы можете извлечь другие данные, такие как 'плюсы' и 'минусы', и отобразить их по своему усмотрению.

Опции сообщений потокового ответа​

При работе с событиями, отправляемыми сервером (SSE), в FlutterFlow важно понимать, как обрабатывать различные компоненты сообщений событий. FlutterFlow предоставляет несколько опций, которые захватывают разные части SSE. Вот они:

JSON данных события, отправляемого сервером (тип: JSON)​

Это поле захватывает результат разбора JSON. Например:

event: chat

data: {"response": "hello", "version": 7}

id: 2

JSON данных события, отправляемого сервером, будет таким:

{
  "response": "hello",
  "version": 7
}

Обратите внимание, что если данные не в формате JSON, оно будет null:

event: ping

data: Server time is 2024-06-28T11:52:56+00:00

id: 2

JSON данных события, отправляемого сервером, будет null.

Текст данных события, отправляемого сервером (тип: String)​

Это поле содержит только текст поля "data" из SSE. Если есть несколько записей "data", они объединяются новой строкой. Например, из события:

event: ping

data: Server time is 2024-06-28T11:52:56+00:00

id: 2

Текст данных события, отправляемого сервером, будет: Server time is 2024-06-28T11:52:56+00:00

А из события:

event: journalEntry

data: Today I went to the park.

data: For Lunch I had a sandwich.

id: 3

Текст данных события, отправляемого сервером, будет:

Today I went to the park.

For Lunch I had a sandwich.

Имя события, отправляемого сервером (тип: String)​

Это поле содержит текст поля "event" из SSE. Например:

event: ping

data: Server time is 2024-06-28T11:52:56+00:00

id: 2

Имя события, отправляемого сервером, будет ping.

ID события, отправляемого сервером (тип: Integer)​

Это поле содержит текст поля "id" из SSE, обычно используется для отслеживания последнего отправленного элемента с сервера. Например:

event: ping

data: Server time is 2024-06-28T11:52:56+00:00

id: 2

ID события, отправляемого сервером, будет 2.

Retry события, отправляемого сервером (тип: String?)​

Это поле содержит поле "retry" из SSE, обычно используется для передачи клиенту информации о времени попытки переподключения к серверу.

Текст сообщения (тип: String)​

Это включает все сообщение события, отправляемого сервером (SSE), включая новые строки и поля ('data', 'event', 'id', 'retry'). Например:

event: ping

data: Server time is 2024-06-28T11:52:56+00:00

id: 2

Часто задаваемые вопросы​

Почему отображается 'null'?

Значение "null" появляется в поле JSON данных события, отправляемого сервером, когда данные не в формате JSON.

Например, следующие данные события не в формате JSON:

event: ping
data: Server time is 2024-06-28T11:52:56+00:00
id: 2

JSON данных события, отправляемого сервером, будет null, поскольку данные нельзя разобрать как JSON.

Вы можете исправить это, используя следующее выражение внутри Inline Function для обработки случая null:

responseData ?? ''

Это выражение гарантирует, что если responseData равно null, то вернется пустая строка.