Как навык Алисы запоминает пользователя: state и база данных

Как навык Алисы запоминает пользователя: session_state, application_state, user_state и база данных

Разбираемся, где хранить данные пользователя в навыке Яндекс.Алисы, чем отличаются три уровня хранилища платформы и когда без собственной базы данных не обойтись.

Почти любой навык сложнее «вопрос — ответ» должен что-то помнить: на каком шаге сценария пользователь, сколько очков набрал в игре, как его зовут, что он заказал в прошлый раз. Алиса умеет хранить такие данные сама — без сервера баз данных, прямо в запросах и ответах. Но у встроенного хранилища три уровня с разным временем жизни и жёсткий лимит объёма. Разберём, как это устроено, что выбрать под свою задачу и как работать с состоянием на TypeScript.

Как Алиса передаёт состояние

Навык не хранит связь с пользователем между запросами: каждая реплика — отдельный HTTP-запрос. Поэтому хранилище Алисы работает «по кругу»: навык возвращает данные в ответе, а платформа присылает их обратно в поле state следующего запроса. Чтобы это заработало, использование хранилища нужно включить в настройках навыка в консоли Яндекс.Диалогов.

Три уровня хранилища

Общее ограничение — объём: на каждый уровень приходится около 1 КБ данных. Этого хватает на номер шага, счёт и пару флагов, но не на историю заказов или список избранного.

Как работать с состоянием в umbot

В фреймворке umbot вам не нужно помнить названия полей и собирать их в ответ. Включите локальное хранилище в конфигурации — и работайте с обычным объектом userData:

import { Bot } from 'umbot';
import { AlisaAdapter } from 'umbot/plugins';

const bot = new Bot()
    .use(new AlisaAdapter())
    .setAppConfig({ isLocalStorage: true }); // хранить userData в хранилище Алисы

bot.addCommand('quiz_start', ['начать викторину', 'играть'], (_, bc) => {
    bc.userData.score = 0;
    bc.userData.question = 1;
    bc.text = 'Вопрос 1. Столица Австралии?';
    bc.buttons.addBtn('Сидней').addBtn('Канберра');
    bc.thisIntentName = 'quiz_answer';
});

bot.addStep('quiz_answer', (bc) => {
    if (bc.userCommand?.includes('канберра')) {
        bc.userData.score = Number(bc.userData.score) + 1;
    }
    bc.text = `Ваш счёт: ${bc.userData.score}.`;
    bc.thisIntentName = null;
});

bot.start('0.0.0.0', 3000);

Всё, что вы положили в userData, фреймворк сам отправит в хранилище Алисы и восстановит из следующего запроса. Текущий шаг сценария (thisIntentName) хранится там же. Уровень выбирается по тому, что прислала платформа, в порядке приоритета: пользователь → приложение → сессия, то есть данные живут так долго, как это позволяет конкретный запрос.

Три правила, о которые спотыкаются

• Удаление поля. delete bc.userData.foo не сработает: платформа вернёт старое значение, потому что его никто не перезаписал. Чтобы очистить поле, присвойте null.
• Превышение лимита. Если данные больше лимита или не сериализуются в JSON, поле состояния не отправляется, а прежнее значение на стороне Алисы остаётся. umbot пишет об этом ошибку в лог — следите за ним.
• Платформа не прислала state. Например, использование хранилища не включено в консоли. Тогда umbot переключается на сессию в памяти процесса: навык продолжит работать, но данные пропадут при перезапуске сервера и не будут общими для нескольких экземпляров. Во время отладки обращайте внимание на предупреждение об этом в логе.
• Незаконченный шаг из прошлой сессии. Если данные живут дольше сессии (уровни приложения и пользователя), вместе с ними сохраняется и текущий шаг сценария. Пользователь, бросивший викторину вчера, сегодня при запуске навыка попадёт сразу в ответ на вопрос. Чтобы начинать заново, в обработчике шага проверяйте начало сессии:

  bot.addStep('quiz_answer', (bc) => {
      if (bc.messageId === 0) {
          return false; // новая сессия — шаг пропускается, диалог начинается сначала
      }
      // ...обычная логика шага
  });

Когда нужна своя база данных

Встроенного хранилища не хватает, если:

• данных больше 1 КБ: история, корзина, избранное, длинные тексты;
• данные нужны вне навыка: в CRM, админке, аналитике — хранилище Алисы видит только сам навык в момент запроса;
• навык работает ещё и в мессенджерах: у Telegram, VK и MAX своего хранилища нет, и состояние нужно держать на вашей стороне;
• нужно, чтобы данные гарантированно пережили смену устройства без входа в аккаунт.

В umbot база подключается одним адаптером:

import { MongoAdapter } from 'umbot/plugins';

bot.use(new MongoAdapter({ host: 'mongodb://localhost:27017', database: 'skill' }));
bot.setAppConfig({ isLocalStorage: false }); // userData — только из БД

Для небольших проектов на одном сервере есть FileAdapter — хранение в файлах без отдельного сервера БД. Для serverless и нескольких экземпляров приложения файловое хранение не подходит: файловая система облачных функций доступна лишь на чтение, а у каждого экземпляра она своя — нужна внешняя база или хранилище платформы.

Гибридный вариант: БД и хранилище платформы одновременно

Иногда удобно разделить данные: долгоживущие (профиль, история) — в базе, короткоживущие (шаг текущего разговора) — в хранилище Алисы. Для этого подключают БД и оставляют isLocalStorage: true: тогда userData берётся из базы, а отдельный объект bc.state — из хранилища платформы. Подход используется редко, но хорош для навыков, где на каждый запрос не хочется ходить в базу ради номера шага.

Как выбрать: короткая шпаргалка

Как проверить, что состояние сохраняется

Удобнее всего — локально, без публикации. Консольный режим BotTest с опцией isShowStorage показывает после каждой реплики, что навык запомнил о пользователе, а в автотестах состояние из ответа передаётся в следующий вызов simulate() — так же, как это делает Алиса. Подробно — в статье как тестировать навык Алисы без публикации.

Частые вопросы

Можно ли узнать, что это тот же пользователь, в новой сессии? Да, если пользователь вошёл в аккаунт Яндекса: у него есть постоянный идентификатор и хранилище пользовательского уровня. Без входа данные привязаны к устройству.

Надёжно ли хранить в state важные данные? Для служебных данных диалога — да. Для того, что нельзя терять (оплаты, заказы), нужна своя база: хранилище платформы вы не можете ни выгрузить, ни восстановить.

Работает ли то же самое в Марусе? У Маруси похожая модель хранилища; в umbot код с userData остаётся тем же, различия берёт на себя адаптер.

Куда дальше

• GUIDE по фреймворку — сценарии хранения, сессия в памяти, правила сохранения.
• Навык Алисы на TypeScript с нуля — шаги диалога, формы и кнопки.
• Навык Алисы на serverless — где хранить состояние, если сервера нет.