max-yandexgpt: YandexGPT в мессенджере MAX за 5 строк кода

Patriot-solution

Max мессенджер появился недавно, и пока экосистема вокруг него только формируется. YandexGPT - мощная языковая модель с OpenAI-совместимым API. Казалось бы, собрать из этого бота - задача на вечер. На практике оказалось, что готового инструмента, который бы связал эти две вещи, просто нет.

Я написал max-yandexgpt - Python-фреймворк, который позволяет запустить AI-бота в Max мессенджере с YandexGPT за 5 строк кода. Со стримингом ответов, выбором модели и нормальной конфигурацией.

В этой статье расскажу, как он устроен и зачем.

Что получается на выходе

from max_yandexgpt import MaxYandexGPT

bot = MaxYandexGPT(
    max_token="ВАШ_ТОКЕН_MAX",
    yandex_api_key="ВАШ_КЛЮЧ_YANDEXGPT",
    yandex_folder_id="ВАШ_FOLDER_ID",
)
bot.run()

Это рабочий бот. Он принимает сообщения в Max, отправляет их в YandexGPT, и отдаёт ответ пользователю, со стримингом по умолчанию. То есть бот сначала отправляет placeholder, а потом обновляет сообщение по мере генерации текста. Выглядит как ChatGPT-интерфейс прямо в мессенджере.

Зачем это нужно

Max - новый мессенджер, и разработчики только начинают осваивать его API. YandexGPT - это Yandex Cloud Foundation Models с OpenAI-совместимым эндпоинтом. По отдельности документация есть, но связки между ними нет: нужно самому разбираться с авторизацией, форматом model URI, стримингом через SSE, редактированием сообщений в Max.

max-yandexgpt берёт это на себя. Под капотом - два компонента:

1. maxapi - клиент Max мессенджера (диспетчер, хэндлеры, polling)

2. openai SDK - для запросов к YandexGPT через OpenAI-совместимый API Yandex Cloud

Разработчику остаётся только указать токены и запустить.

Архитектура

Фреймворк состоит из трёх модулей:

config.py - конфигурация. Dataclass с валидацией: токены, модель, system prompt, температура, max_tokens, параметры стриминга. Поддерживает переменные окружения (MAX_TOKEN, YANDEX_API_KEY, YANDEX_FOLDER_ID), что бы не хардкодить секреты.

llm.py - клиент YandexGPT. Использует AsyncOpenAI из официального OpenAI SDK, но с кастомным base_url:

YANDEX_BASE_URL = "https://ai.api.cloud.yandex.net/v1"

self._client = AsyncOpenAI(
    api_key=config.yandex_api_key,
    base_url=YANDEX_BASE_URL,
)

Model URI формируется как gpt://{folder_id}/{model_name}- это специфика Yandex Cloud. Два режима: complete() для синхронных запросов и stream() асинхронный генератор, который yield’ит текстовые дельты.

bot.py - основной класс MaxYandexGPT. Связывает Max и YandexGPT: регистрирует хэндлеры через maxapi.Dispatcher, маршрутизирует входящие сообщения и управляет стримингом.

Стриминг работает так:

1. Бот получает сообщение от пользователя

2. Отправляет placeholder "..."

3. Запрашивает YandexGPT в streaming-режиме

4. По мере поступления дельт - редактирует сообщение в Max

5. Rate-limit на редактирование: не чаще чем раз в stream_interval секунд (по умолчанию 1.0)

6. Финальное сообщение - полный ответ без placeholder

Весь бот асинхронный asyncio от начала до конца.

Модели

Поддерживаются все актуальные модели YandexGPT:

Переключение — один параметр:

bot = MaxYandexGPT(
    max_token="...",
    yandex_api_key="...",
    yandex_folder_id="...",
    model="yandexgpt-5.1/latest",
)

Настройка

Полный набор параметров:

bot = MaxYandexGPT(
    max_token="...",
    yandex_api_key="...",
    yandex_folder_id="...",
    system_prompt="Ты — полезный ассистент.",
    stream=True,           # стриминг включён по умолчанию
    temperature=0.3,
    max_tokens=2000,
)

Или через переменные окружения для продакшена:

bot = MaxYandexGPT()  # читает из MAX_TOKEN, YANDEX_API_KEY, YANDEX_FOLDER_ID
bot.run()

Установка и запуск

pip install max-yandexgpt

Что нужно:

1. Python 3.11+

2. Токен бота Max мессенджера, создаётся на max.ru

3. API-ключ YandexGPT + folder ID через Yandex Cloud Console

Исходный код

Проект открытый, MIT-лицензия:

• GitHub

• GitVerse

• PyPI

Буду рад фидбеку, issues на GitHub открыты.