Как подключить gigachat к n8n

Как подключить GigaChat к n8n: Полное руководство по интеграции

Интеграция GigaChat, российской нейросетевой модели от Сбера, в платформу автоматизации n8n позволяет создавать мощные рабочие процессы (workflows), сочетающие возможности генеративного ИИ с гибкостью автоматизации. Данное руководство детально описывает процесс подключения, настройки и использования GigaChat в n8n.

Предварительные требования и подготовка

Перед началом интеграции необходимо обеспечить выполнение следующих условий:

Установленный и запущенный экземпляр n8n. Это может быть n8n.cloud, настольное приложение (n8n Desktop) или самодеплоинстая версия (n8n self-hosted).
Учетная запись в GigaChat. Необходима регистрация на платформе GigaChat для разработчиков.
Полученные ключи доступа (API-ключи). После регистрации и подтверждения прав доступа вам будут предоставлены учетные данные для работы с API.
Базовое понимание интерфейса n8n: умение создавать workflows, добавлять ноды (ноды) и соединять их.

Шаг 1: Получение учетных данных GigaChat API

Для аутентификации в API GigaChat требуется два основных компонента:

Client ID и Client Secret: Эти данные используются для получения временного Access Token. Они создаются в личном кабинете разработчика GigaChat.
Scope (область доступа): Обычно требуется указать GIGACHAT_API_PERS для доступа к основному API.

Процесс получения:

Авторизуйтесь в SberAI Studio.
Перейдите в раздел «Мои приложения» и создайте новое приложение, если его нет.
В настройках приложения найдите раздел «API-ключи» или «Учетные данные».
Скопируйте и сохраните в надежном месте значения Client ID и Client Secret.

Шаг 2: Настройка Credentials (учетных данных) в n8n

n8n позволяет централизованно хранить и переиспользовать учетные данные для разных нод. Поскольку нативной (встроенной) ноды для GigaChat в стандартной поставке n8n нет, мы будем использовать универсальные ноды для работы с HTTP-запросами.

Откройте ваш n8n.
Перейдите в раздел Credentials (значок ключа в левом боковом меню).
Нажмите Add Credential.
Выберите тип учетных данных: HTTP Request (Custom) или OAuth2 API. Для GigaChat предпочтительнее использовать OAuth2, так как это соответствует механизму авторизации платформы.

Настройка OAuth2 Credential для GigaChat

Заполните поля в форме создания учетных данных OAuth2 следующим образом:

Поле в n8n	Значение для GigaChat	Комментарий
Grant Type	Client Credentials	Стандартный поток для machine-to-machine аутентификации.
Client ID	Ваш Client ID из личного кабинета	Вставьте скопированную строку.
Client Secret	Ваш Client Secret из личного кабинета	Вставьте скопированную строку.
Access Token URL	https://ngw.devices.sberbank.ru:9443/api/v2/oauth	URL для получения Access Token. Может быть обновлен в документации GigaChat.
Scope	GIGACHAT_API_PERS	Область доступа для персонального API.
Auth URI	Оставьте пустым	Не требуется для grant type Client Credentials.
Authentication	Header	Параметры аутентификации передаются в заголовке.

После заполнения нажмите Save и протестируйте подключение, если такая опция доступна. n8n должен успешно получить Access Token от серверов GigaChat.

Шаг 3: Создание Workflow и добавление нод

Теперь создадим простой workflow, который отправляет запрос к GigaChat и получает ответ.

Создайте новый workflow.
Добавьте ноду HTTP Request (можно найти через поиск нод). Эту ноду мы настроим для получения Access Token. Хотя учетные данные OAuth2 могут автоматически обновлять токен, иногда требуется явный запрос.
Добавьте вторую ноду HTTP Request. Она будет использоваться для отправки промпта (запроса) к модели GigaChat.
Соедините ноды между собой.

Настройка первой ноды HTTP Request (для получения токена)

Эта нода может быть полезной для отладки или для явного контроля над токеном.

Method: POST
URL: https://ngw.devices.sberbank.ru:9443/api/v2/oauth
Authentication: Basic Auth
Username: Ваш Client ID
Password: Ваш Client Secret
Headers: Добавьте заголовок: Content-Type: application/x-www-form-urlencoded
Body Parameters: Добавьте параметр scope со значением GIGACHAT_API_PERS.

При выполнении эта нода вернет JSON-объект, содержащий поле access_token. Его нужно будет передать в следующую ноду.

Настройка второй ноды HTTP Request (основной запрос к GigaChat)

Это ключевая нода для взаимодействия с моделью. Настройте ее согласно официальной документации GigaChat API (эндпоинт чат-завершения).

Method: POST
URL: https://gigachat.devices.sberbank.ru/api/v1/chat/completions
Authentication: Generic Credential Type. В поле «Value» вставьте выражение: {{ $node['Первая нода'].json['access_token'] }} (замените «Первая нода» на имя вашей первой ноды). Префикс должен быть «Bearer». Или выберите созданное ранее OAuth2 Credential.
Headers:
- Content-Type: application/json
- Accept: application/json
Body: Выберите режим «JSON». Вставьте структуру запроса. Пример:

{
  "model": "GigaChat", // Или конкретная версия модели, например "GigaChat-Plus"
  "messages": [
    {
      "role": "user",
      "content": "Привет! Напиши краткий план статьи про интеграцию ИИ."
    }
  ],
  "temperature": 0.7,
  "max_tokens": 512
}

Шаг 4: Обработка и использование ответа

После выполнения второй ноды HTTP Request, ответ от API GigaChat будет доступен в ее выходных данных. Ответ имеет структуру, аналогичную OpenAI API.

Добавьте ноду Set или Function для извлечения нужных данных из ответа.
Чтобы получить текст ответа модели, используйте выражение в следующих нодах: {{ $node['Вторая нода'].json['choices'][0]['message']['content'] }}.
Этот текст можно далее отправлять по электронной почте (нода Email), сохранять в Google Sheets, базу данных, отправлять в Telegram и т.д.

Шаг 5: Расширенные настройки и параметры запроса

API GigaChat поддерживает множество параметров для тонкой настройки генерации. Вот основные из них, которые можно добавлять в JSON-тело запроса:

Параметр	Тип	Описание	Пример значения
model	string	Идентификатор модели. Например, «GigaChat», «GigaChat-Plus».	«GigaChat»
messages	array	Массив сообщений в диалоге. Обязательное поле.	[{«role»: «user», «content»: «…»}]
temperature	number	Креативность ответов (от 0.0 до 1.0). Чем ниже, тем более детерминированным будет ответ.	0.7
max_tokens	integer	Максимальное количество токенов в генерируемом ответе.	1024
top_p	number	Альтернатива temperature, метод ядерной выборки.	0.9
stream	boolean	Включение потоковой передачи ответа. Для n8n обычно false.	false
repetition_penalty	number	Штраф за повторения (значение больше 1 уменьшает повторения).	1.1

Шаг 6: Создание кастомной ноды GigaChat (опционально)

Для постоянного и удобного использования вы можете создать собственную ноду для n8n. Это требует знаний JavaScript/TypeScript и понимания структуры нод n8n. Основные шаги:

Создайте новый проект ноды, используя команду n8n-node-dev.
Определите свойства ноды: поля ввода, credentials, операции.
Реализуйте метод execute, который будет формировать HTTP-запрос к API GigaChat, используя переданные учетные данные и параметры (промпт, модель, temperature и т.д.).
Упакуйте ноду и установите ее в свою инсталляцию n8n.

Это избавит от необходимости каждый раз вручную настраивать HTTP Request ноды.

Часто задаваемые вопросы (FAQ)

Вопрос 1: Где взять актуальные URL для API GigaChat?

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

Вопрос 2: Почему запрос завершается с ошибкой 401 (Unauthorized)?

Ответ: Наиболее частые причины:

Неверные или устаревшие Client ID / Client Secret.
Истек срок действия Access Token, а механизм автоматического обновления в n8n не сработал. Попробуйте пересоздать учетные данные.
Не указан или неверно указан scope в запросе на получение токена.
Access Token передается без префикса «Bearer» в заголовке Authorization.

Вопрос 3: Можно ли использовать GigaChat в n8n бесплатно?

Ответ: У GigaChat есть тарифные планы, включающие бесплатный пакет запросов (обычно с ограниченным количеством токенов в месяц). Детали тарификации необходимо уточнять на официальном сайте продукта. В n8n никаких дополнительных платежей за использование интеграции не взимается.

Вопрос 4: Как обрабатывать длинные ответы или ограничения по токенам?

Ответ: Следите за параметром max_tokens в запросе. Если ответ обрывается, увеличьте это значение (в рамках лимитов модели). Для обработки очень длинных текстов можно реализовать логику разбиения входного промпта и агрегации ответов через несколько нод Function или Code в n8n.

Вопрос 5: Чем интеграция через HTTP Request отличается от кастомной ноды?

Ответ:

Критерий	HTTP Request нода	Кастомная нода
Удобство	Требует ручной настройки тела запроса, заголовков каждый раз.	Предоставляет интуитивный интерфейс с полями «Промпт», «Модель», «Температура».
Переиспользование	Можно клонировать ноду или использовать шаблоны.	Нода доступна в палитре, готова к использованию в любом workflow.
Сложность настройки	Низкая (для базового использования).	Высокая (требуется разработка).
Гибкость	Абсолютная (можно настроить любой запрос).	Ограничена заложенной разработчиком функциональностью.

Вопрос 6: Как добавить контекст диалога (историю сообщений) в запрос?

Ответ: Для этого необходимо правильно формировать массив messages в JSON-теле запроса. В него нужно включать не только последнее сообщение пользователя (role: "user"), но и предыдущие ответы модели (role: "assistant") и пользователя. Пример:

"messages": [
  {"role": "user", "content": "Привет"},
  {"role": "assistant", "content": "Здравствуйте! Чем могу помочь?"},
  {"role": "user", "content": "Напомни наш последний разговор."}
]

В n8n это можно организовать, сохраняя историю в переменных (например, в памяти n8n или внешнем хранилище) и динамически формируя этот массив в ноде Function или Code перед отправкой HTTP-запроса.

Заключение

Интеграция GigaChat с n8n через HTTP Request ноды предоставляет мощный и гибкий инструмент для автоматизации задач с использованием передовых возможностей генеративного ИИ. Несмотря на необходимость ручной настройки запросов, этот подход позволяет полностью контролировать взаимодействие с API. Для частого использования целесообразно рассмотреть разработку кастомной ноды, что значительно упростит создание и поддержку workflows. Ключевыми факторами успешной интеграции являются корректные учетные данные, актуальные параметры API из документации и правильная обработка токена аутентификации. Данная связка открывает широкие возможности для автоматизации генерации текстов, анализа контента, создания чат-ботов и многих других бизнес-процессов.