ISPsystem показала, как подключить любой ИИ-ассистент к SaaS за один файл-адаптер

Зачем вообще нужна архитектура адаптеров?

Денис, фронтенд-разработчик ISPsystem, описал задачу так: заранее неизвестно, какую языковую модель выберет клиент. DeepSeek, OpenAI-совместимый провайдер, локальная модель с открытыми весами (open weights), каждая требует своего формата API-запросов. Писать отдельный модуль под каждого провайдера дорого и хрупко.

Решение: паттерн «адаптер». Описывается единый интерфейс с тремя обязательными методами. Любая новая интеграция реализует этот интерфейс, а ядро платформы ничего не знает о деталях конкретного провайдера. Это классический подход из разработки, но в контексте ИИ-ассистентов он особенно полезен, потому что рынок моделей меняется каждый квартал.

Что понадобится

• Платформа BILLmanager или любой SaaS-проект на TypeScript/Node.js, куда вы встраиваете ИИ-ассистента
• API-ключ хотя бы одного провайдера языковых моделей (DeepSeek, OpenAI-совместимый сервис или локальная модель)
• Базовое знание TypeScript: интерфейсы, async-генераторы, промисы
• Примерно 2 часа на первый рабочий адаптер и подключение потоковых ответов

Как устроен интерфейс адаптера?

Интерфейс AiAdapter содержит четыре элемента. Обязательны три:

• getName возвращает имя адаптера
• getCompletion отправляет запрос и получает полный ответ целиком
• getCompletionStream делает то же самое, но возвращает поток: текст приходит по частям, как в чате ChatGPT

Четвёртый метод, getAdditionalParamsScheme, необязательный. Он возвращает объект-заглушку с параметрами, которые поддерживает конкретный провайдер: температура генерации, максимальное количество токенов (token, минимальная единица текста, которую обрабатывает модель), top_p и другие.

export interface AiAdapter {
  readonly getName: () => string;
  readonly getCompletion: (
    params: AdapterCompletionParams,
  ) => Promise<ModelResponse>;
  readonly getCompletionStream: (
    params: AdapterCompletionParams,
  ) => AsyncIterable<ModelStreamEvent>;
  readonly getAdditionalParamsScheme?: () => IJsonObject;
}

Параметры вызова собраны в AdapterCompletionParams: API-ключ, история сообщений, адрес API, название модели, системный промпт (system prompt, инструкция, которая задаёт поведение модели до начала диалога) и additionalParams для произвольных настроек провайдера.

Отдельно стоит выделить abortSignal. Это механизм отмены: если пользователь остановил генерацию, сигнал прерывает запрос к провайдеру. Без него «брошенные» запросы продолжали бы тратить токены.

Как передавать потоковый ответ?

Команда ISPsystem выбрала SSE (Server-Sent Events, технология односторонней передачи данных от сервера к клиенту) вместо WebSocket. Логика простая: поток идёт только в одну сторону, от сервера к пользователю, и SSE реализуется проще.

Адаптер отдаёт четыре типа событий:

• text_delta: кусочек текста
• completed: генерация закончена, внутри полный ответ и количество потраченных токенов
• failed: ошибка
• tool_call: модель вызвала внешний инструмент

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

Пошаговая инструкция: пишем адаптер для DeepSeek

1. Установите официальный пакет openai (DeepSeek использует OpenAI-совместимый API):

npm install openai

1. Создайте файл адаптера и реализуйте интерфейс AiAdapter. Метод getCompletionStream это async-генератор, он отдаёт события по мере получения данных от провайдера.

2. Внутри генератора создайте клиент, передайте ему API-ключ и URL, вызовите chat.completions.create с параметром stream: true.

3. Накапливайте текст в переменной accumulatedText. Каждый фрагмент отдавайте через yield { type: 'text_delta', delta }.

4. Завершите поток событием completed, передав полный текст и количество токенов:

yield {
  type: 'completed',
  response: {
    outputText: accumulatedText,
    totalTokens,
    output: [{
      role: 'assistant',
      content: [{ type: 'text', text: accumulatedText }],
      status: 'completed',
    }],
  },
};

1. Не забудьте передать abortSignal в параметры запроса к клиенту, чтобы отмена работала корректно.

2. Опишите схему дополнительных параметров через getAdditionalParamsScheme, чтобы интерфейс платформы мог показать пользователю, какие настройки доступны.

Что с этого вам прямо сейчас?

Разработчику SaaS-платформы. Паттерн адаптера из BILLmanager можно перенести в любой продукт на TypeScript. Интерфейс из четырёх методов позволяет менять провайдера без рефакторинга ядра. Если ваш продукт уже работает с одной моделью, оберните текущую интеграцию в адаптер, и добавление второго провайдера станет задачей на день, а не на спринт.

Автору Дзена и контент-маркетологу. Архитектурные разборы от российских команд, это формат, который стабильно собирает сохранения. Если вы пишете о технологиях, подобный кейс можно разобрать для своей аудитории, показав, как конкретная компания из РФ решает ту же задачу, что и мировые SaaS-гиганты.

Предпринимателю. Прежде чем заказывать «интеграцию с ИИ» у подрядчика, попросите показать архитектуру адаптеров. Если её нет, смена модели через полгода обойдётся в отдельный бюджет. BILLmanager доступен в России, документация на русском.

Архитектура «один интерфейс, много адаптеров» не нова, но в контексте языковых моделей она становится не просто удобной, а необходимой: рынок провайдеров меняется быстрее, чем любой SaaS-продукт успевает обновлять код.