GigaChat, YandexGPT, Yandex 360 API: подводные камни, о которых не пишут в документации

Мы подключили GigaChat, YandexGPT и Yandex 360 (Диск, Календарь, Почта, Телемост) к нашему рабочему пайплайну. Всё заработало — но по дороге собрали коллекцию граблей, которые нигде толком не задокументированы. Вот они.

GigaChat: сберовский SSL и зомби-процессы

GigaChat API несовместим с форматом OpenAI из коробки. Для интеграции нужен прокси — мы использовали gpt2giga (Python).

Подключение

pip3 install gpt2giga
 
export GIGACHAT_CREDS=$(echo -n "CLIENT_ID:CLIENT_SECRET" | base64)
 
gpt2giga \
  --gigachat.credentials $GIGACHAT_CREDS \
  --gigachat.scope GIGACHAT_API_PERS \
  --gigachat.verify-ssl-certs false \
  --proxy.port 8443

Credentials берутся на developers.sber.ru → приложение GigaChat API → Client ID + Client Secret. Scope GIGACHAT_API_PERS — бесплатный персональный доступ.

Грабли

1. --verify-ssl-certs false обязателен. Сбер использует собственный корневой сертификат, которого нет в стандартном CA-бандле. Без этого флага — ошибка SSL на каждый запрос. Документация об этом упоминает мельком.

2. Зомби-процессы gpt2giga. Прокси периодически уходит в defunct-состояние, занимая порт. Процесс висит, но запросы не обрабатывает. Единственное решение:

fuser -k 8443/tcp && kill -9 $(pgrep -f gpt2giga)

Если используете в проде — нужен health check и автоматический перезапуск.

3. Credentials видны в ps aux. CLI-аргументы --gigachat.credentials отображаются в списке процессов. Любой пользователь на сервере может их прочитать. Альтернатива — переменные окружения или конфиг-файл.

4. HTTP 307 на /v1/models. Эндпоинт списка моделей возвращает redirect. Стандартный fetch без follow redirects получит пустой ответ. Используйте curl -L или настройте клиент на автоматические редиректы.

5. 402 Payment Required. Бесплатная квота заканчивается быстрее, чем кажется — лимит на токены, не на запросы. Активное тестирование за день съедает месячный лимит.

Что в итоге работает

Все три модели (Lite, Pro, Max) через прокси отвечают корректно. Pro — оптимальный баланс: 32K контекст, адекватное качество на русском. Для задач, где важна скорость — Lite. Max оправдан только для длинных документов.

YandexGPT: IAM-разрешения — это не роли

YandexGPT тоже несовместим с OpenAI API. Мы написали свой прокси на Node.js (без зависимостей, 150 строк), который транслирует запросы OpenAI → YandexGPT.

Подключение

# Создаём сервис-аккаунт
yc iam service-account create --name my-sa
 
# Генерируем API-ключ
SA_ID=$(yc iam service-account get my-sa --format json | jq -r .id)
yc iam api-key create --service-account-id $SA_ID
 
# Назначаем роль на FOLDER (не на сервис-аккаунт!)
yc resource-manager folder add-access-binding <FOLDER_ID> \
  --role ai.editor \
  --subject serviceAccount:$SA_ID

Грабли

1. Добавить разрешения на SA ≠ назначить роль на folder. Это главная ошибка, на которую мы потратили больше всего времени. В Яндекс Cloud есть два разных механизма:

• Разрешения на сервис-аккаунт — кто может управлять самим SA
• Роли на folder — что SA может делать с ресурсами

YandexGPT проверяет роль ai.editor на уровне folder. Если вы добавили разрешение на сервис-аккаунт вместо Access Binding на folder — получите 403 без внятной ошибки. Документация Яндекса описывает оба механизма, но не предупреждает о различии в контексте AI API.

2. FOLDER_ID обязателен. В отличие от OpenAI, где вы просто передаёте API-ключ, YandexGPT требует x-folder-id в каждом запросе. Забыли — получите 403.

3. Модели именуются иначе. Нет gpt-4 или claude-sonnet. Модели называются yandexgpt, yandexgpt-lite, yandexgpt-32k. Маппинг нужно делать вручную.

Результат

YandexGPT отвечает быстрее GigaChat (~0.8 сек vs ~1.2 сек на простых запросах). Качество на русском — сопоставимое. Контекст у базовой модели всего 8K (vs 32K у GigaChat Pro), но есть yandexgpt-32k.

Yandex 360: CalDAV, IMAP и заблокированные порты

Yandex 360 — это Диск, Календарь, Почта и Телемост. У каждого сервиса свой способ интеграции, и ни один из них не использует единый REST API.

OAuth

Все сервисы работают через OAuth. Создаём приложение на oauth.yandex.ru:

Redirect URI для CLI/ботов: https://oauth.yandex.ru/verification_code

Диск — работает просто

REST API, стандартные CRUD-операции. Из нюансов — загрузка файлов двухэтапная: сначала получаешь upload URL, потом PUT на него. Не как S3.

# Информация о диске
curl -H "Authorization: OAuth $TOKEN" \
  https://cloud-api.yandex.net/v1/disk/
 
# Список файлов
curl -H "Authorization: OAuth $TOKEN" \
  "https://cloud-api.yandex.net/v1/disk/resources?path=/"

Календарь — CalDAV, не REST

У Яндекс Календаря нет HTTP REST API. Только CalDAV — протокол из 2007 года. Это XML-based WebDAV-расширение, где каждое событие — файл .ics.

Что нужно знать:

• Auto-discovery логина через https://login.yandex.ru/info — CalDAV-пути содержат email
• Правильный путь: /calendars/{login}@yandex.ru/events-{id}/{uid}.ics — если пишете на /calendars/events/, получите 404
• PROPFIND для списка календарей — не GET, а специальный HTTP-метод
• Timezone: нужен блок VTIMEZONE в ICS, иначе время сдвинется

Почта — IMAP/SMTP

HTTP API для почты нет. Только IMAP (порт 993) и SMTP (порт 465). Работает локально, но на облачных платформах (Railway, Render, Fly.io) порты 25/465/587/993 заблокированы по умолчанию из-за антиспам-политик.

Если вам нужна интеграция почты на PaaS — это тупик. Либо VPS, либо сторонний email API.

Телемост — требует платную подписку

OAuth scope telemost-api:conferences.create подключается, но на бесплатных аккаунтах возвращает 403. Нужна платная подписка Yandex 360.

Сводка: что реально работает

Если вам нужна интеграция с российскими AI-сервисами

Мы уже прошли через все эти подводные камни. Если планируете подключать GigaChat, YandexGPT или Yandex 360 к своему продукту — можем помочь. Пишите, обсудим задачу.