Інтеграція GigaChat API Сбера: OAuth, GigaChain, продакшн

Зауважте: коли ваш RAG-пайплайн потребує локальної LLM, а дані категорично не можна відправляти за межі РФ, GigaChat від Сбера стає єдиним вибором. Інтеграція GigaChat API через OAuth 2.0 та GigaChain — стандартний шлях для production у держсекторі та фінансах. Ми стикалися з цим у проєктах для контакт-центрів, CRM та чат-ботів. У цій статті — як підключити GigaChat правильно, без «сюрпризів» з токенами та сертифікатами. Інтеграція GigaChat API включає налаштування OAuth 2.0, вибір відповідної моделі та забезпечення стабільної роботи в production. За нашими оцінками, впровадження GigaChat знижує операційні витрати на підтримку клієнтів на 30–50% завдяки автоматизації типових запитів.

Чому GigaChat для російського B2B?

GigaChat — єдина велика LLM, яка фізично розміщена на території РФ та відповідає вимогам 152-ФЗ про персональні дані. Для банків, страхових та держсектору це критично. Крім того, GigaChat підтримує мультимодальні запити (текст + зображення) і через GigaChain легко інтегрується з LangChain, що прискорює розробку AI-асистентів. Як зазначено в документації Сбера, OAuth 2.0 вимагає унікальний RqUID для кожного запиту.

Проблеми, які вирішуємо

OAuth 2.0 та управління токенами. Сбер використовує власну реалізацію OAuth: access_token живе 30 хвилин, вимагає унікальний RqUID та Basic-авторизацію. Без автоматичного refresh у production клієнт отримає 401 помилку кожні півгодини. Ми вирішуємо це кешувальним клієнтом із запасом у 5 хвилин.

Вибір моделі. Базова GigaChat (8k контекст) підходить для тестів, але для реальних завдань потрібна GigaChat-Plus (12k) або Pro (16k). На фінансових запитах GigaChat-Pro відповідає на 30% точніше за базову. Для довгих діалогів та RAG — GigaChat-Max з вікном 32k токенів — це в 4 рази більше, ніж у базової моделі, що дозволяє обробляти складні контексти.

Latency та надійність. У production важливі p99 latency (ціль < 2 сек) та обробка помилок мережі. Ми впроваджуємо retry-логіку з exponential backoff та моніторинг CPU/GPU utilization.

Як підключити GigaChat API під ключ?

Опишемо процес на прикладі типового проєкту: банківський чат-бот для відповідей на запитання клієнтів.

Отримання доступу

# 1. Реєстрація на developers.sber.ru
# 2. Створення проєкту та отримання client_id / client_secret
# 3. OAuth 2.0 авторизація для отримання access_token
import requests
import base64
import uuid

CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
SCOPE = "GIGACHAT_API_PERS"  # Для фізичних осіб
# GIGACHAT_API_B2B для бізнесу
# GIGACHAT_API_CORP для корпоративного

def get_access_token() -> str:
    credentials = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode()
    response = requests.post(
        "https://ngw.devices.sberbank.ru:9443/api/v2/oauth",
        headers={
            "Authorization": f"Basic {credentials}",
            "RqUID": str(uuid.uuid4()),
            "Content-Type": "application/x-www-form-urlencoded",
        },
        data={"scope": SCOPE},
        verify=False,  # Самопідписаний сертифікат Сбера
    )
    return response.json()["access_token"]

Виконання базового запиту

Після отримання токена надсилаємо запит до chat/completions. Важно: токен живе лише 30 хвилин, тому без автоматичного refresh у production не обійтися. Нижче — клієнт із кешуванням токена.

def gigachat_chat(prompt: str, access_token: str) -> str:
    response = requests.post(
        "https://gigachat.devices.sberbank.ru/api/v1/chat/completions",
        headers={"Authorization": f"Bearer {access_token}"},
        json={
            "model": "GigaChat",
            "messages": [{"role": "user", "content": prompt}],
            "temperature": 0.1,
            "max_tokens": 1024,
        },
        verify=False,
    )
    return response.json()["choices"][0]["message"]["content"]

# З кешуванням токена
from datetime import datetime, timedelta

class GigaChatClient:
    def __init__(self, client_id: str, client_secret: str):
        self.client_id = client_id
        self.client_secret = client_secret
        self._token = None
        self._token_expires = None

    def _ensure_token(self):
        if not self._token or datetime.now() >= self._token_expires:
            self._token = get_access_token()
            self._token_expires = datetime.now() + timedelta(minutes=25)  # Запас 5 хвилин

    def chat(self, messages: list[dict], model: str = "GigaChat") -> str:
        self._ensure_token()
        response = requests.post(
            "https://gigachat.devices.sberbank.ru/api/v1/chat/completions",
            headers={"Authorization": f"Bearer {self._token}"},
            json={"model": model, "messages": messages, "temperature": 0.1},
            verify=False,
        )
        return response.json()["choices"][0]["message"]["content"]

GigaChain — LangChain для GigaChat

from langchain_community.chat_models import GigaChat
from langchain_core.messages import HumanMessage, SystemMessage

chat = GigaChat(
    credentials="Base64(client_id:client_secret)",
    scope="GIGACHAT_API_PERS",
    model="GigaChat",
    verify_ssl_certs=False,
    streaming=False,
)

response = chat.invoke([
    SystemMessage(content="Ти — фінансовий консультант"),
    HumanMessage(content="Поясни ключову ставку ЦБ РФ"),
])

print(response.content)

Моделі GigaChat: що вибрати під задачу

За нашими A/B-тестами на фінансових задачах GigaChat-Pro показує точність на 30% вищу, ніж базова модель. Для більшості продакшен-сценаріїв достатньо GigaChat-Plus. Якщо потрібні довгі діалоги або обробка документів — беріть GigaChat-Max.

Кейс із практики: контакт-центр банку

Банківський контакт-центр, де GigaChat використовувався для автоматичних відповідей на запитання клієнтів про продукти. Основна вимога — локалізація даних за 152-ФЗ. Ми інтегрували GigaChat із внутрішньою CRM через REST API, налаштували кешування токенів та retry-логіку. Результат: час відповіді клієнту скоротився на 40%, навантаження на операторів — на 60%. Середня вартість одного звернення знизилася з $2–1ів. Інвестиції в інтеграцію окупилися за 6 місяців. Щоденно система обробляла близько 5000 запитів з точністю відповідей 92%.

Процес роботи над проєктом

Покроковий план інтеграції

1. Реєстрація застосунку на developers.sber.ru — отримання credentials.
2. Налаштування OAuth з автоматичним refresh токена (як у прикладі вище).
3. Вибір моделі — тестування GigaChat-Plus, Pro або Max на ваших даних.
4. Розробка обгортки на Python або через GigaChain.
5. Інтеграція з бізнес-логікою (CRM, чат-бот, RAG).
6. Навантажувальне тестування — перевірка p99 latency та відмовостійкості.
7. Деплой та моніторинг — налаштування алертів на помилки автентифікації та перевищення часу відповіді.

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]