Интеграция 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"]