GigaChat API на Python: подключение за вечер с примерами кода

Подключить GigaChat к своему коду можно за вечер, и почти всё время съедают две вещи, о которых не пишут в первых абзацах: корневой сертификат Минцифры и токен на 30 минут. Разобрали весь путь по шагам с рабочим кодом на Python: ключ, сертификат, токен, первый запрос, SDK, потоковый ответ и разбор семи ошибок, на которых застревают в первый вечер. Плюс актуальные на 2026 год тарифы и бесплатная квота в 365 млн токенов.
Статью написал:
Ваня Буявец, продюсер, основатель Checkroi
Ваня Буявец
Основатель Checkroi, продюсер, эксперт в выборе онлайн-курсов
Все 2426 статей автора Подписаться на Телеграм-канал
Одобрено экспертом:
Наташа Буявец, основатель Checkroi, эксперт по онлайн-курсам
Наташа Буявец
Основательница Checkroi, продюсер Youtube-каналов, эксперт по онлайн-курсам
Все 3086 экспертных мнений Подписаться на Телеграм-канал
Обложка: GigaChat API на Python: подключение за вечер с примерами кода

Подключить GigaChat к своему коду можно за один вечер. Основное время уходит не на логику, а на две вещи, о которых редко пишут в первых абзацах инструкций: корневой сертификат НУЦ Минцифры и токен, который живёт ровно тридцать минут.

Мы прошли путь целиком и собрали его в том порядке, в котором он и делается: ключ, сертификат, токен, первый запрос, потом SDK, потоковый ответ, деньги и разбор ошибок, на которых спотыкаются почти все.

Код в статье на Python, но схема авторизации одинаковая для любого языка: два HTTP-запроса, один заголовок и одна переменная окружения.

Если вы пока не знаете, что такое GigaChat и чем он отличается от других нейросетей, начните с обзора «Что такое GigaChat», а потом возвращайтесь сюда.

Статья рассчитана на того, кто уже писал что-то на Python уровня «скрипт на requests», но с внешними API работал мало. Все термины разбираем по дороге.

Если Python вы только начинаете, посмотрите нашу подборку курсов по Python: там есть и короткие интенсивы на две недели, и полноценные программы с нуля.

CheckroiCheckroiПодборка курсов по GigaChat92 курса • 18 школСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить

Что такое GigaChat API и зачем он нужен

Рой подключает нейросеть к своему коду

API (application programming interface) это способ обратиться к сервису из своей программы, а не руками через сайт. Вы отправляете HTTP-запрос с текстом, получаете обратно ответ модели в формате JSON, и дальше делаете с ним что хотите: кладёте в базу, шлёте в Telegram, вставляете в отчёт.

Через веб-интерфейс так не сделаешь: там один человек, одна вкладка, ручное копирование. Через API вы обрабатываете тысячу писем в цикле, пока пьёте кофе.

Типовые задачи, ради которых берут GigaChat API:

  • разбор входящих обращений и писем по категориям;
  • краткие пересказы длинных документов и созвонов;
  • генерация карточек товаров и описаний по шаблону;
  • чат-бот в Telegram или на сайте;
  • поиск по своей базе знаний через эмбеддинги.

Главная причина брать именно GigaChat, а не зарубежный аналог: он работает из России напрямую, оплачивается рублями с обычной карты или по счёту, а данные остаются в российском правовом поле. Для сравнения соседнего варианта у нас есть разбор «YandexGPT API», там та же логика, но своя схема ключей.

Сразу про деньги. Физлицу для старта платить не нужно: в бесплатном режиме дают 365 млн токенов на год. Этого хватит на несколько пет-проектов, подробности в разделе про тарифы ниже.

Что понадобится до первой строчки кода

Список короткий, но каждый пункт обязателен.

  1. Аккаунт Сбер ID и доступ в личный кабинет разработчика на developers.sber.ru.
  2. Ключ авторизации (его же называют Authorization key). Это строка в Base64, склеенная из Client ID и Client Secret.
  3. Корневой сертификат НУЦ Минцифры, скачанный с Госуслуг. Без него Python откажется устанавливать соединение.
  4. Python 3.8 или новее. Официальный SDK поддерживает версии с 3.8 по 3.13.

Про сертификат стоит сказать отдельно, потому что именно на нём застревает большинство. Сайты GigaChat используют сертификаты российского удостоверяющего центра, а Python проверяет соединения по собственному списку доверенных центров из пакета certifi, куда российский корневой сертификат не входит. Браузер у вас может открывать эти адреса нормально (у системы свой список), а скрипт будет падать.

Канал основателя Checkroi Вани Буявца3 700 человек читают мой Телеграм-канал про нейросетиСобрал промпты для Claude Code и ChatGPT, разборы ИИ-инструментов и лайфхаки по продвижению бизнеса в одном местеПрисоединиться

Шаг 1: получить ключ авторизации

Заходите в личный кабинет на developers.sber.ru, создаёте проект GigaChat API и нажимаете кнопку генерации нового Client Secret. Система покажет вам три вещи: Client ID, Client Secret и готовый ключ авторизации.

Копируйте именно ключ авторизации целиком. Секрет показывают один раз, потом его можно только перевыпустить.

Тут же выбирается scope, то есть тип доступа. Он определяет и лимиты, и набор доступных моделей:

Scope Кому Как платят
GIGACHAT_API_PERS физлицам, для себя и пет-проектов бесплатная квота, потом пакеты
GIGACHAT_API_B2B компаниям предоплаченные пакеты токенов
GIGACHAT_API_CORP компаниям постоплата по факту использования

Для личного проекта берите GIGACHAT_API_PERS. Если укажете чужой scope, получите ошибку доступа на этапе получения токена, и это одна из самых частых причин загадочного 401.

Ключ никогда не пишите прямо в коде, который пойдёт в репозиторий. Кладите в переменную окружения:

export GIGACHAT_CREDENTIALS="ваш_ключ_авторизации"
export GIGACHAT_SCOPE="GIGACHAT_API_PERS"

Шаг 2: поставить сертификат НУЦ Минцифры

Скачайте с Госуслуг корневой сертификат «Russian Trusted Root CA». На Windows он придёт файлом .cer, на macOS и Linux .crt.

Дальше есть два пути. Правильный: указать Python путь к этому файлу через переменную окружения.

# macOS и Linux
export GIGACHAT_CA_BUNDLE_FILE="/path/to/Russian_Trusted_Root_CA.crt"

# Windows
set GIGACHAT_CA_BUNDLE_FILE=C:pathtoRussian_Trusted_Root_CA.cer

Быстрый и грязный: отключить проверку сертификатов вообще.

export GIGACHAT_VERIFY_SSL_CERTS="false"

Про отключение проверки. Для локальных экспериментов это допустимо, для боевого сервера нет. Выключенная проверка означает, что вы согласны разговаривать с кем угодно, кто представится нужным адресом. Поставьте сертификат один раз и забудьте.

Шаг 3: получить токен доступа

GigaChat работает по схеме OAuth: ключ авторизации вы меняете на короткоживущий токен доступа (access token), и уже с ним ходите к модели. Токен действует 30 минут, потом нужен новый.

Запрос за токеном уходит на отдельный адрес, не на тот, где живёт сама модель. Это вторая по популярности причина недоумения новичков.

import os
import uuid
import requests

OAUTH_URL = "https://ngw.devices.sberbank.ru:9443/api/v2/oauth"
CA_BUNDLE = os.environ["GIGACHAT_CA_BUNDLE_FILE"]

def get_token():
    headers = {
        "Content-Type": "application/x-www-form-urlencoded",
        "Accept": "application/json",
        "RqUID": str(uuid.uuid4()),
        "Authorization": f"Basic {os.environ['GIGACHAT_CREDENTIALS']}",
    }
    data = {"scope": os.environ.get("GIGACHAT_SCOPE", "GIGACHAT_API_PERS")}
    r = requests.post(OAUTH_URL, headers=headers, data=data, verify=CA_BUNDLE, timeout=30)
    r.raise_for_status()
    payload = r.json()
    return payload["access_token"], payload["expires_at"]

token, expires_at = get_token()
print("токен получен, истекает в", expires_at)

Разберём заголовки, потому что каждый тут не просто так.

  • Authorization: Basic: здесь идёт именно ключ авторизации, а не токен. Слово Basic, не Bearer.
  • RqUID: уникальный идентификатор запроса в формате UUID4. Заголовок обязательный, генерируйте новый на каждый вызов.
  • Content-Type: application/x-www-form-urlencoded: scope уходит формой, не JSON. Если отправить JSON, получите отказ.

Поле expires_at в ответе приходит в миллисекундах. Удобно сохранить его и запрашивать новый токен заранее, секунд за шестьдесят до истечения, чтобы не поймать отказ посреди цикла обработки.

Шаг 4: первый запрос к модели

Теперь идём на основной адрес. Актуальный базовый URL это https://api.giga.chat, старый gigachat.devices.sberbank.ru пока работает, но его выводят из обращения.

API_URL = "https://api.giga.chat/v1/chat/completions"

def ask(token, prompt, model="GigaChat-2"):
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Authorization": f"Bearer {token}",
    }
    body = {
        "model": model,
        "messages": [
            {"role": "system", "content": "Ты помощник. Отвечай коротко и по существу."},
            {"role": "user", "content": prompt},
        ],
        "temperature": 0.3,
    }
    r = requests.post(API_URL, headers=headers, json=body, verify=CA_BUNDLE, timeout=60)
    r.raise_for_status()
    return r.json()["choices"][0]["message"]["content"]

print(ask(token, "Объясни в двух предложениях, что такое эмбеддинг."))

Обратите внимание на смену схемы: сюда идёт Bearer, а не Basic. Перепутанная схема даёт ровно тот же 401, что и неверный ключ, и по тексту ошибки их не различить.

Структура messages та же, что в большинстве современных чат-моделей. Роль system задаёт правила поведения на весь диалог, user это реплика человека, assistant прилетает в ответе. Историю переписки вы храните у себя и присылаете целиком каждый раз: сервер между запросами ничего не помнит.

Параметр temperature отвечает за разброс ответов. Ноль и близкие значения дают предсказуемый результат для классификации и извлечения данных, значения около единицы нужны там, где хочется вариативности.

Ваня БуявецКанал основателя Checkroi Вани БуявцаЗабирайте промпты и обучение по нейросетям в моём Телеграм-каналеБольше 3 700 человек уже применяют Claude Code, ChatGPT и другие нейросети в работе, учёбе, бизнесе и жизниПерейти в канал

То же самое через официальный SDK

Всё, что мы написали руками, уже собрано в библиотеке. Она сама получает токен, следит за его сроком и повторяет упавшие запросы.

pip install gigachat

Актуальная версия на конец лета 2026 года это 0.2.3 (вышла 31 июля 2026), поддерживаются Python с 3.8 по 3.13. Минимальный пример из документации выглядит так:

from gigachat import GigaChat

with GigaChat(
    base_url="https://api.giga.chat/v1",
    credentials="ключ_авторизации",
    scope="GIGACHAT_API_PERS",
    ca_bundle_file="/path/to/Russian_Trusted_Root_CA.crt",
) as client:
    response = client.chat.create("Привет, как дела?")
    print(response.messages[0].content[0].text)

Если вы уже выставили переменные окружения из первого шага, конструктор можно звать вообще без аргументов: GigaChat() подхватит всё сам.

Что ещё умеет SDK из коробки: потоковая передача, асинхронный режим, эмбеддинги, вызов функций, работа с картинками, подсчёт токенов и проверка остатка квоты. Ради последнего пункта библиотеку стоит поставить, даже если основной код у вас на голых запросах.

Что выбрать новичку. Берите SDK. Ручные запросы полезно один раз написать, чтобы понимать, что происходит под капотом, но в проекте держать свою обвязку над OAuth незачем.

Какие модели доступны и какую брать

Внутри GigaChat несколько семейств моделей, они отличаются качеством, скоростью и ценой токена. Имя модели передаётся строкой в поле model.

Модель Чем берёт Куда ставить
GigaChat-2 (Lite) быстрая и самая дешёвая классификация, короткие ответы, черновики
GigaChat-2-Pro заметно умнее на связном тексте тексты, пересказы, разбор документов
GigaChat-2-Max сильнее всех в линейке двойки сложная логика, длинный контекст
GigaChat-3-Ultra старшая модель нового поколения самые тяжёлые задачи
EmbeddingsGigaR векторы вместо текста поиск по своей базе знаний

Если непонятно, с чего начинать: берите GigaChat-2. На нём вы отладите логику, потратив копейки от бесплатной квоты, и переключитесь на старшую модель одной строкой, когда упрётесь в качество. Менять модель это одно слово в теле запроса.

Полный список того, что доступно именно вашему ключу, всегда можно спросить у API:

r = requests.get("https://api.giga.chat/v1/models",
                 headers={"Authorization": f"Bearer {token}"},
                 verify=CA_BUNDLE, timeout=30)
for m in r.json()["data"]:
    print(m["id"])

Подробное сравнение семейств с примерами ответов мы разбирали в статье «Какую модель GigaChat выбрать».

Потоковый ответ, чтобы не ждать молча

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

from gigachat import GigaChat

with GigaChat() as client:
    for chunk in client.chat.stream("Напиши план поста про GigaChat API"):
        piece = chunk.choices[0].delta.content
        if piece:
            print(piece, end="", flush=True)

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

Совместимость с OpenAI и миграция чужого кода

У GigaChat есть режим совместимости с интерфейсом OpenAI. Практический смысл простой: если у вас уже написан код под openai, менять придётся две строки, а не весь проект.

from openai import OpenAI

client = OpenAI(
    api_key=token,                        # тот же токен доступа на 30 минут
    base_url="https://api.giga.chat/v1",  # адрес GigaChat вместо адреса OpenAI
)

answer = client.chat.completions.create(
    model="GigaChat-2",
    messages=[{"role": "user", "content": "Привет"}],
)
print(answer.choices[0].message.content)

Ограничение у этого пути одно и важное: токен всё равно живёт тридцать минут, и обновлять его придётся своей обвязкой. Библиотека OpenAI про схему авторизации Сбера ничего не знает и сама ключ не перевыпустит.

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

Сколько это стоит

Цифры ниже актуальны на 1 сентября 2026 года, Сбер их периодически пересматривает, поэтому перед запуском в продакшен сверьтесь со страницей тарифов.

Физическим лицам доступен бесплатный режим: 365 млн токенов на генерацию текста с обновлением раз в двенадцать месяцев. Квота разложена по семействам моделей.

Семейство Бесплатная квота на год
Lite (GigaChat, GigaChat-2) 250 млн токенов
Pro 40 млн токенов
Max 25 млн токенов
Ultra (GigaChat-3-Ultra) 50 млн токенов

Чтобы это стало осязаемым: токен это кусочек текста примерно в три-четыре русских символа, и считаются токены и на входе, и на выходе. Запрос на страницу текста с ответом на страницу обойдётся примерно в 1000 токенов. То есть 250 млн на Lite это порядка четверти миллиона таких обменов за год. Для пет-проекта потолок недостижимый.

Когда квота кончилась, покупаются пакеты, каждый живёт месяц с даты покупки.

Пакет Объём Цена с НДС
GigaChat 2 Lite 20 млн токенов 1 300 ₽
GigaChat 2 Pro 3 млн токенов 1 500 ₽
GigaChat 2 Max 3 млн токенов 1 950 ₽
Embeddings 50 млн токенов 700 ₽

Компаниям доступны свои схемы: предоплаченные пакеты по scope B2B и постоплата по факту через CORP, вплоть до установки в собственном контуре.

Как прикинуть бюджет проекта заранее

Считать расход в токенах непривычно, поэтому переведём в понятные величины на конкретном примере.

Допустим, вы разбираете входящие обращения, как в примере ниже. Одно обращение это примерно 150 токенов на входе (само письмо плюс системная инструкция) и 30 токенов на выходе (короткий JSON). Итого около 180 токенов на письмо, округлим до 200.

При тысяче обращений в день выходит 200 тысяч токенов в сутки, то есть примерно 6 млн в месяц и 73 млн в год. Бесплатная квота Lite в 250 млн токенов покрывает такой поток с запасом в три года. Если тот же объём гнать через Max, годовой расход упрётся в квоту 25 млн уже на четвёртом месяце, и дальше пойдут пакеты по 1 950 ₽ за 3 млн токенов.

Отсюда практическое правило: стоимость проекта определяет не количество запросов, а выбор модели и длина контекста. Перевод классификации с Max на Lite экономит больше, чем любая оптимизация кода.

Точный расход конкретного запроса можно узнать, не гадая: API отдаёт число потраченных токенов в ответе, а SDK умеет считать их отдельным вызовом до отправки. Прогоните сотню реальных примеров, посмотрите среднее и умножайте на свой объём.

Если вы ещё выбираете, на чьём API строить проект, сравните расклад с соседним вариантом в разборе «Что такое YandexGPT», а посмотреть программы с практикой именно по этой модели можно в подборке курсов по GigaChat.

Семь ошибок первого вечера

Раскладка инструментов для отладки подключения

Собрали то, на чём люди теряют часы, в порядке частоты.

Ошибка 1: сертификат не подложен

Симптом: SSLError и слова про certificate verify failed. Причина: Python проверяет соединение по своему списку доверенных центров, российского корневого сертификата там нет. Лечение: скачать сертификат с Госуслуг и указать путь через GIGACHAT_CA_BUNDLE_FILE или параметр verify в requests.

Ошибка 2: перепутаны Basic и Bearer

За токеном идёте с Basic и ключом авторизации, к модели с Bearer и полученным токеном. Перепутали местами, получили 401 без внятного пояснения. Проверяется за секунду, а ищется долго.

Ошибка 3: не тот scope

Ключ выпущен для физлица, а в запросе указан GIGACHAT_API_B2B. Отказ приходит на этапе получения токена. Сверьте scope в личном кабинете и в коде.

Ошибка 4: токен протух посреди работы

Скрипт получил токен на старте и молотит цикл сорок минут. На тридцать первой минуте всё падает. Храните expires_at и обновляйте токен заранее, либо просто используйте SDK, он делает это сам.

Ошибка 5: старый адрес

В туториалах двухлетней давности фигурирует gigachat.devices.sberbank.ru. Он ещё отвечает, но переезжает на api.giga.chat. Если поймали странные отказы по адресу, проверьте, куда именно стучитесь.

Ошибка 6: scope ушёл в JSON

Запрос за токеном принимает тело формой, с заголовком application/x-www-form-urlencoded. Отправили json= вместо data=, получили отказ. В коде выше это уже учтено.

Ошибка 7: забыт RqUID

Заголовок с уникальным идентификатором запроса обязателен, и он должен быть валидным UUID4. Подставили строку вида test-123, получили отказ. Генерируйте через uuid.uuid4().

CheckroiCheckroiПодборка курсов по промпт-инжинирингу174 курса • 37 школСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить

Как не сжечь квоту на отладке

Три привычки, которые экономят токены и нервы.

Во-первых, отлаживайте промпты на Lite-модели и переключайтесь на старшую только когда логика устоялась. Разница в расходе квоты кратная, а для проверки «работает ли вообще» качества Lite хватает.

Во-вторых, ограничивайте длину ответа параметром max_tokens. Модель без ограничений охотно пишет три абзаца там, где вам нужно одно слово категории.

В-третьих, не шлите всю историю диалога, если задача её не требует. Для классификации писем каждое письмо это независимый запрос, и тащить в него предыдущие сорок бессмысленно: вы платите за каждый токен контекста заново.

В-четвёртых, кешируйте ответы на повторяющиеся запросы. В обработке каталогов и писем одинаковые тексты встречаются чаще, чем кажется: словарь «хеш запроса к ответу» на диске срезает расход на десятки процентов и заодно ускоряет повторные прогоны.

Остаток квоты удобно проверять прямо из кода, SDK умеет это одним вызовом. Заведите привычку смотреть баланс после больших прогонов.

CheckroiCheckroiПодборка курсов по Python561 курс • 46 школСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить

Рабочий пример: разбираем входящие письма по категориям

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

Ключевых приёмов тут три. Просим модель отвечать строго JSON-ом, даём температуру около нуля, чтобы ответ был стабильным, и ограничиваем длину ответа.

import json
from gigachat import GigaChat

SYSTEM = """Ты классификатор обращений в поддержку.
Верни ТОЛЬКО JSON без пояснений, вида:
{"category": "оплата|доставка|возврат|техника|другое", "urgent": true|false}"""

letters = [
    "Второй день не могу оплатить заказ, карта проходит, а на сайте ошибка",
    "Подскажите, пожалуйста, когда планируется поступление синего цвета",
    "Пришёл разбитый монитор, нужен возврат денег, заказ 88214",
]

with GigaChat(model="GigaChat-2", scope="GIGACHAT_API_PERS") as client:
    for text in letters:
        resp = client.chat.create({
            "messages": [
                {"role": "system", "content": SYSTEM},
                {"role": "user", "content": text},
            ],
            "temperature": 0,
            "max_tokens": 60,
        })
        raw = resp.messages[0].content[0].text
        try:
            data = json.loads(raw)
        except json.JSONDecodeError:
            data = {"category": "другое", "urgent": False, "raw": raw}
        print(data, "|", text[:40])

Обратите внимание на try вокруг разбора JSON. Модель обычно слушается инструкции, но иногда добавляет вежливую фразу перед скобкой, и без защиты скрипт упадёт на середине списка. В боевом коде такой ответ логируют и отправляют на второй проход.

Из этого каркаса вырастает почти любая рутинная автоматизация: замените системный промпт и список на выборку из базы, и получите разбор отзывов, тегирование карточек товаров или сортировку резюме.

Асинхронный режим, когда запросов много

Цикл из примера выше обрабатывает письма по одному: отправили, подождали ответ, взяли следующее. На трёх письмах незаметно, на трёх тысячах это часы ожидания сети.

Библиотека умеет работать асинхронно, то есть держать несколько запросов в воздухе одновременно.

import asyncio
from gigachat import GigaChat

async def classify_all(texts):
    async with GigaChat(model="GigaChat-2") as client:
        sem = asyncio.Semaphore(5)   # не больше пяти запросов разом

        async def one(text):
            async with sem:
                r = await client.achat.create(text)
                return r.messages[0].content[0].text

        return await asyncio.gather(*[one(t) for t in texts])

results = asyncio.run(classify_all(letters))

Ограничитель через Semaphore здесь обязателен. Без него вы отправите тысячу запросов одновременно, упрётесь в лимит частоты на стороне сервиса и получите пачку отказов вместо ускорения. Пять-десять параллельных запросов это разумный старт, дальше подбирайте по поведению.

Чек-лист диагностики, когда ничего не работает

Проверяйте по порядку, каждый пункт отсекает свой класс проблем.

  1. Сеть и сертификат. Получается ли вообще достучаться до ngw.devices.sberbank.ru. Ошибка про сертификат означает, что до второго пункта вы не дошли.
  2. Токен. Отдельным маленьким скриптом вызовите только get_token(). Токен пришёл, значит ключ, scope и заголовки в порядке, и проблема ниже по течению.
  3. Список моделей. Запрос к /v1/models с полученным токеном. Отвечает, значит Bearer и адрес верные, а дело в теле запроса к модели.
  4. Тело запроса. Имя модели строкой точно как в списке, роли в messages из допустимого набора, JSON валиден.
  5. Квота. Проверьте остаток токенов. Кончившаяся квота выглядит не как «денег нет», а как обычный отказ в доступе.

Такой порядок экономит время, потому что ошибка почти всегда даёт один и тот же невнятный 401, и угадывать причину бесполезно. Проще пройти лесенку сверху вниз и увидеть, на какой ступени она ломается.

Отдельно стоит сказать про порядок разработки. Сначала соберите сценарий целиком на трёх-пяти примерах в обычном скрипте и убедитесь, что ответы вас устраивают. И только потом заворачивайте всё это в бота, веб-сервис или планировщик. Ошибка новичка выглядит так: человек сразу пишет телеграм-бота, ловит отказ и полдня не может понять, где именно проблема, в авторизации, в промпте или в самом боте. Три слоя сразу отлаживать вдвое дольше, чем по одному.

Как хранить ключ и не выложить его в репозиторий

Ключ авторизации это доступ к вашей квоте и к вашим деньгам, если квота платная. Утёкший ключ обычно обнаруживают по счёту, а не по уведомлению.

Минимальная гигиена состоит из трёх шагов. Ключ живёт в файле .env рядом с проектом, сам файл записан в .gitignore, а в репозиторий кладётся только образец .env.example с пустыми значениями.

# .env  (в git не попадает)
GIGACHAT_CREDENTIALS=ваш_ключ
GIGACHAT_SCOPE=GIGACHAT_API_PERS
GIGACHAT_CA_BUNDLE_FILE=/path/to/Russian_Trusted_Root_CA.crt
from dotenv import load_dotenv   # pip install python-dotenv
load_dotenv()

from gigachat import GigaChat
with GigaChat() as client:        # всё подхватится из окружения
    print(client.chat.create("Проверка связи").messages[0].content[0].text)

Если ключ всё-таки уехал в публичный коммит, удалять историю бесполезно: считайте его скомпрометированным и перевыпустите Client Secret в личном кабинете. Старый после этого перестанет работать.

На сервере переменные окружения задаются средствами самого сервера или контейнера, файл .env туда обычно не кладут.

Ограничения, о которых лучше знать заранее

Чтобы не строить планы на том, чего нет.

Сервер не помнит диалог. Каждый запрос независим, всю переписку вы храните у себя и присылаете заново. Это не только про удобство: длинная история означает больше токенов на входе и, значит, больше расход квоты на каждом шаге.

Модель придумывает факты. Она уверенно выдаст несуществующий номер закона или чужую цитату. Для задач, где важна точность, нужен либо поиск по вашим документам с подстановкой найденного в контекст, либо проверка результата отдельным шагом.

Формат ответа не гарантирован. Даже с прямой инструкцией «только JSON» модель иногда добавит фразу перед скобкой. Разбор ответа всегда оборачивайте защитой, как в примере с письмами выше.

Лимит частоты. Параллельных запросов можно держать ограниченное число, и его превышение выглядит как ошибка, а не как очередь. Отсюда ограничитель в асинхронном примере.

Что делать дальше

Рой радуется первому успешному ответу

Когда первый запрос прошёл, дальше обычно идут в одну из трёх сторон.

Эмбеддинги и поиск по своим документам. Модель EmbeddingsGigaR превращает текст в вектор чисел, по которым можно искать похожее. Так собирают поиск по внутренней базе знаний: вопрос сотрудника переводится в вектор, находятся ближайшие куски документов, и уже они уходят в модель как контекст.

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

Качество ответов. Часто выясняется, что дело не в модели, а в формулировке запроса. Правила, которые работают одинаково для любой нейросети, мы собрали в материале «Промпт-инжиниринг»: там про роли, структуру задачи и примеры в промпте.

И если решаете, на какой российской модели строить продукт, посмотрите наше сравнение «GigaChat или YandexGPT»: схемы подключения у них разные, а задачи часто закрываются обеими.

Где научиться работать с нейросетями через код

Разобраться с одним API по инструкции можно за вечер. Сложности начинаются дальше: как считать стоимость, как оценивать качество ответов, где нужен дообученный вариант, а где достаточно хорошего промпта. Этому учат на программах по нейросетям и машинному обучению.

КурсШколаСтоимость со скидкойВ рассрочкуДлитель­ностьОбзор курса от Checkroi
Нейросети для изображений и видео
Перейти на сайт курса
Академия ЭдюсонЭдюсон47 504 ₽3958 ₽/мес.2 месяцаОбзор курса
Нейросети для рабочих задач
Перейти на сайт курса
SkillboxSkillbox31 290 ₽2608 ₽/мес.1 месяцОбзор курса
Нейросети. Практический курс
Перейти на сайт курса
SkillboxSkillbox74 900 ₽6242 ₽/мес.3 месяцаОбзор курса
Нейросети для каждого: как решать рабочие задачи быстрее
Перейти на сайт курса
НетологияНетология57 000 ₽2763 ₽/мес.6 недельОбзор курса
Продуктовый маркетолог + Нейросети для маркетинга
Перейти на сайт курса
НетологияНетология110 200 ₽3875 ₽/мес.5 месяцевОбзор курса
Нейросети для дизайнера
Перейти на сайт курса
SkillboxSkillbox84 272 ₽3831 ₽/мес.4 месяцаОбзор курса
Нейросети для работыSkyproSkypro44 690 ₽5477 ₽/мес.3 месяцаОбзор курса
Нейросети для каждого
Перейти на сайт курса
Академия СинергияАкадемия Синергия39 900 ₽3325 ₽/мес.3 месяцаОбзор курса
Нейросети для начинающих
Перейти на сайт курса
SF EducationSF Education42 000 ₽2333 ₽/мес.1 месяцОбзор курса
Нейросети для маркетинга
Перейти на сайт курса
SkillboxSkillbox29 800 ₽4967 ₽/мес.1 месяцОбзор курса

Больше программ — в полном каталоге курсов по нейросетям и искусственному интеллекту

Если сначала хочется добрать базу по языку, у нас есть отдельная подборка курсов по Python с фильтрами по уровню и формату.

Прокомментировать

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

Нужно ли платить, чтобы попробовать GigaChat API?

Нет. Физическим лицам дают бесплатную квоту 365 млн токенов на генерацию текста с обновлением раз в год: 250 млн на Lite-модели, 40 млн на Pro, 25 млн на Max и 50 млн на Ultra. Для пет-проекта и обучения этого хватит с запасом. Данные актуальны на 1 сентября 2026 года.

Почему Python выдаёт ошибку сертификата при запросе к GigaChat?

GigaChat использует сертификаты российского удостоверяющего центра НУЦ Минцифры, а Python проверяет соединения по своему списку доверенных центров из пакета certifi, куда этот сертификат не входит. Скачайте с Госуслуг корневой сертификат Russian Trusted Root CA и укажите путь к нему через переменную GIGACHAT_CA_BUNDLE_FILE или параметр verify в requests.

Сколько живёт токен доступа GigaChat?

30 минут. В ответе на запрос токена приходит поле expires_at в миллисекундах, по нему удобно обновлять токен заранее, секунд за шестьдесят до истечения. Официальный Python SDK следит за сроком сам, поэтому в нём эта проблема не возникает.

Чем отличается Basic от Bearer в запросах к GigaChat?

За токеном вы идёте на OAuth-адрес с заголовком Authorization: Basic и ключом авторизации. К самой модели вы идёте на api.giga.chat с заголовком Authorization: Bearer и полученным токеном. Перепутанные схемы дают одинаковый 401, и по тексту ошибки их не различить, поэтому проверяйте это первым делом.

Какой scope выбрать: PERS, B2B или CORP?

GIGACHAT_API_PERS для физлиц и личных проектов, GIGACHAT_API_B2B для компаний с предоплаченными пакетами токенов, GIGACHAT_API_CORP для компаний с оплатой по факту использования. Scope должен совпадать с тем, под который выпущен ключ, иначе токен просто не выдадут.

Можно ли использовать библиотеку OpenAI с GigaChat?

Да, у GigaChat есть режим совместимости: достаточно подставить base_url="https://api.giga.chat/v1" и токен доступа вместо ключа OpenAI. Ограничение в том, что токен всё равно живёт 30 минут, а библиотека OpenAI про схему авторизации Сбера не знает и сама его не обновит. Для нового кода удобнее родной SDK.

Какую модель GigaChat выбрать для старта?

GigaChat-2 из семейства Lite. Она быстрая и дешёвая по токенам, на ней удобно отлаживать логику и промпты. Когда упрётесь в качество, переключитесь на Pro или Max: это одно слово в теле запроса, остальной код не меняется.

Помнит ли GigaChat предыдущие сообщения?

Нет. Каждый запрос независим, сервер между вызовами ничего не хранит. Историю диалога вы держите у себя и присылаете целиком в массиве messages. Учитывайте, что длинная история это лишние токены на входе при каждом запросе.

Как обработать много запросов быстро?

Использовать асинхронный режим SDK и держать несколько запросов одновременно, обязательно ограничив их число через asyncio.Semaphore. Разумный старт это пять-десять параллельных запросов: без ограничителя вы упрётесь в лимит частоты и получите пачку отказов вместо ускорения.

Читайте Checkroi первым в Google
Добавьте Checkroi в избранные источники — и наши разборы курсов и обзоры школ будут показываться выше в вашей выдаче Google.
Оставить комментарий
0 комментариев
Форма комментария

Оставьте комментарий

Напишите, что думаете. Нам важно ваше мнение!