Flowise: подключение к SpeShu.AI

Flowise — open-source конструктор LLM-приложений: вы соединяете ноды на холсте (модель, промпт, память, загрузчик документов, инструменты) и получаете готовый сценарий с REST-эндпоинтом. На SpeShu.AI его направляют, когда нужно собрать работающий чат или агентный сценарий визуально и сразу получить API для фронтенда, не переписывая пайплайн на Python.

Важны ровно две вещи: base URL https://speshu.ai/api/v1 и API-ключ. Flowise работает через OpenAI-совместимые эндпоинты, поэтому подключение почти всегда сводится к смене адреса. В Flowise это путь «OpenAI-совместимый провайдер» — узел ChatOpenAI с полем Base Path; отдельный плагин или SDK для этого не нужен.

Установка

Flowise — Node.js-приложение. Подходит любой из двух способов.

npx -y flowise@latest start

UI откроется на http://localhost:3000. Состояние (флоу, ключи, индексы) лежит в каталоге ~/.flowise — примонтируйте его как volume, иначе контейнер потеряет настройки при пересоздании.

docker run -d --name flowise \
  -p 3000:3000 \
  -v flowise:/root/.flowise \
  -e OPENAI_API_KEY=sk-ваш-ключ \
  flowiseai/flowise

Получите ключ и идентификатор модели

Ключ

Ключ создаётся на speshu.ai/profile и показывается один раз.

export SPESHU_API_KEY="sk-ваш-ключ"

Идентификатор модели

Идентификаторы текстовых моделей не зашивайте в код: состав каталога меняется, и устаревший идентификатор падает с 404 model_not_found. Возьмите его из каталога и положите в переменную.

export SPESHU_MODEL=$(curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[0].id')
echo "$SPESHU_MODEL"

Скопируйте значение в поле Model Name узла ChatOpenAI. Если Flowise разворачивается в Docker, к внешнему API он ходит по внутренней сети. Используйте тот же https://speshu.ai/api/v1, если DNS и маршрут из контейнера доступны; иначе — адрес внутреннего прокси. Формат ответа — в разделе Каталог моделей.

Эндпоинт каталога не требует ключа. Передавайте его только ради ваших тарифных цен: без заголовка придут публичные цены.

Настройка узла ChatOpenAI

Создайте Chatflow, перетащите ноду ChatOpenAI и заполните три поля:

Поле в UI	Значение
Base Path	`https://speshu.ai/api/v1`
API Key	ваш ключ (`sk-…`)
Model Name	значение `$SPESHU_MODEL`, скопированное из каталога

Подключите ноду к входу Chat Input, а её выход — к выходу Chat Output. Сохраните флоу и нажмите Test в панели предпросмотра: если в поле ответа появился текст, подключение работает.

В Base Path нужен именно https://speshu.ai/api/v1. Без суффикса /v1 Flowise соберёт адрес …/api/v1 сам и получит 404; с завершающим слэшем некоторые версии Flowise склеят путь с двойным слэшем, который принимают не все клиенты. Пишите значение без слэша на конце.

Дополнительно в секции Additional Configuration доступны параметры генерации — Temperature, Max Tokens, Top P. Ставьте их там, а не в промпте: Flowise передаёт их в тело запроса, и значения совпадают с полями запроса чата.

Первый работающий пример

Готовый флоу публикуется по адресу /api/v1/prediction/{chatflow_id} — это эндпоинт самого Flowise, не SpeShu.AI.

curl -s -X POST \
  "http://localhost:3000/api/v1/prediction/$CHATFLOW_ID" \
  -H "Content-Type: application/json" \
  -d '{"question": "Назови три правила для надёжного пароля."}' \
  | jq -r '.text'

Python

import os

import requests

flowise = os.environ["FLOWISE_URL"]          # http://localhost:3000
chatflow_id = os.environ["CHATFLOW_ID"]      # id сохранённого Chatflow

response = requests.post(
    f"{flowise}/api/v1/prediction/{chatflow_id}",
    json={"question": "Назови три правила для надёжного пароля."},
    timeout=300,
)
response.raise_for_status()
print(response.json()["text"])

Поле ответа Flowise — text, а не choices: это обёртка над OpenAI-ответом. Само списание видно не в нём, а в логах Flowise; если нужно считать расход программно, запрашивайте напрямую POST /api/v1/chat/completions — там сумма лежит в usage.cost.total_cost, в рублях. Разбор — в разделе Учёт средств.

Потоковая передача

Добавьте на вход ноды Chat Input переключатель Streaming — он ставит stream: true в upstream-запрос, а ответ отдаёт через SSE. Формат кадров и момент списания разобраны в гайде Потоковая передача.

curl -N -s -X POST \
  "http://localhost:3000/api/v1/prediction/$CHATFLOW_ID?stream=true" \
  -H "Content-Type: application/json" \
  -d '{"question": "Напиши три абзаца про океан."}'

Сервер SpeShu.AI не пишет поле event: в SSE-кадры — все события безымянные и приходят по data:. Если после включения Streaming вы видите пустой ответ при HTTP-статусе 200, дело в парсере, который ждёт event:, а не в подключении.

Вызов функций и структурированный вывод

Обе возможности включаются на уровне нод, а не на уровне API:

Tools — подключите ноду Tool (или Custom Tool) и соедините её с моделью. Flowise сам собирает tools[] и выполняет вызов; схема аргументов берётся из описания ноды. Полный цикл — в гайде Вызов функций.
Structured output — нода Structured Output Parser в связке с промптом, описывающим JSON-схему, включает response_format с json_schema. Примеры — в гайде Структурированный вывод.
Vision — модель из каталога с поддержкой зрения принимает изображения; нода ChatOpenAI отдаёт их без изменений. Не все модели это умеют — сверяйтесь по Моделям и ценам.

Генерация медиа

У Flowise нет встроенной ноды под медиа-задачи SpeShu.AI, но есть Custom Tool — произвольный HTTP-вызов. Через неё можно создать задачу:

{
  "name": "generate_image",
  "description": "Создаёт изображение по описанию. Возвращает id задачи.",
  "method": "POST",
  "url": "https://speshu.ai/api/v1/async/media/tasks",
  "headers": [{ "name": "Authorization", "value": "Bearer sk-ваш-ключ" }],
  "body": "{\"model\": \"nano-banana-2\", \"input\": {\"prompt\": \"{{args.prompt}}\"}}"
}

Идентификаторы медиа-моделей публичны и стабильны, поэтому литерал здесь допустим; полный список — в Каталоге медиа-моделей.

Модель в примере отвечает мгновенно, а результат приходит по опросу: инструмент вернёт taskId, а не картинку. Деньги списываются при создании задачи, поэтому не отправляйте создание повторно вслепую — используйте Idempotency-Key. Формат ответа и цикл ожидания — в разделе Создание задачи.

Эмбеддинги: чего SpeShu.AI не умеет

В API нет эндпоинта /embeddings. Ноды OpenAI Embeddings и Embeddings в Flowise по умолчанию ходят в https://api.openai.com и получат отказ — либо попытаются использовать ваш ключ SpeShu.AI и получат 404. Эмбеддинги придётся брать у отдельного провайдера.

Два честных варианта: (а) Отдельный провайдер для эмбеддингов. SpeShu.AI остаётся генератором, векторизация уходит другому сервису:

В ноде Embeddings укажите Base Path и API Key стороннего провайдера — это отдельная конфигурация, не ключ SpeShu.AI:

{
  "basePath": "https://<другой-провайдер>/v1",
  "apiKey": "sk-другой-провайдер",
  "modelName": "<embedding-модель другого провайдера>"
}

Нода ChatOpenAI продолжает смотреть в https://speshu.ai/api/v1.
При пересборке индекса эмбеддинг считается один раз; при каждом запросе оплачивается только генерация в SpeShu.AI.

Не меняйте векторное пространство на ходу: по индексу, построенному на эмбеддингах одной модели, нельзя искать эмбеддингами другой. Смена модели означает полную переиндексацию.

(б) Без эмбеддингов. Уберите ноды документов, сплиттера и векторного хранилища и оставьте прямую цепочку Chat Input → ChatOpenAI → Chat Output. Flowise остаётся полноценным инструментом: память, промпты, инструменты, поток и публикация API работают, поиск по базе знаний — нет.

Частые проблемы

404 на запросе, хотя ключ рабочий

Проверьте Base Path: должно быть https://speshu.ai/api/v1, без завершающего слэша и без повторного /api/v1. Внутри контейнера используйте внутренний адрес сервиса, а не публичный домен.

404 model_not_found в логе ноды

Идентификатор в поле Model Name устарел или скопирован с префиксом провайдера. Возьмите его заново из GET /api/v1/models и вставьте как есть. Если поле предлагает выпадающий список — обновите его, иначе UI подставит старое значение.

401 invalid_api_key при нажатии Test

В поле API Key попал ключ с кавычками, переносом строки или от другого сервиса. Отладочная проверка: echo "$SPESHU_API_KEY" | wc -c — в значении должен быть префикс sk- и ничего лишнего.

Включил Streaming — ответ пустой

Парсер ждёт поле event:, которого сервер не пишет. Разбор кадров — в гайде Потоковая передача; в curl добавьте -N, иначе вывод буферизуется.

Ноды эмбеддингов падают при индексации

Эндпоинта /embeddings у SpeShu.AI нет. Переведите эмбеддинги на отдельного провайдера или уберите ветку RAG — как описано выше.

Ответ пришёл, но не видно, сколько списано

Flowise отдаёт поле text и прячет тело ответа провайдера. Сумма доступна в usage.cost.total_cost (рубли) при прямом обращении к POST /api/v1/chat/completions или через эндпоинт баланса.

Всё остальное

Коды ошибок, форматы и цикл повторов — на странице Ошибки. Таймауты и квоты — в разделе Лимиты.

Что дальше

Модели и цены

Каталог текстовых и медиа-моделей

Потоковая передача

SSE, [DONE] и кадр со списанием

Вызов функций

Полный цикл вызова инструмента

Ошибки

Коды и что с ними делать

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Установка

Получите ключ и идентификатор модели

Настройка узла ChatOpenAI

Первый работающий пример

Потоковая передача

Вызов функций и структурированный вывод

Генерация медиа

Эмбеддинги: чего SpeShu.AI не умеет

Частые проблемы

Что дальше

Модели и цены

Потоковая передача

Вызов функций

Ошибки

​Установка

​Получите ключ и идентификатор модели

​Настройка узла ChatOpenAI

​Первый работающий пример

​Потоковая передача

​Вызов функций и структурированный вывод

​Генерация медиа

​Эмбеддинги: чего SpeShu.AI не умеет

​Частые проблемы

​Что дальше

Модели и цены

Потоковая передача

Вызов функций

Ошибки

Установка

Получите ключ и идентификатор модели

Настройка узла ChatOpenAI

Первый работающий пример

Потоковая передача

Вызов функций и структурированный вывод

Генерация медиа

Эмбеддинги: чего SpeShu.AI не умеет

Частые проблемы

Что дальше