Развернуть

Python SDK для GigaChat API

Обновлено 2 февраля 2026

GigaChat — это Python-библиотека для работы с REST API GigaChat. Она является частью GigaChain и входит в состав langchain-gigachat — партнерского пакета opensource-фреймворка LangChain .

Библиотека управляет авторизацией запросов и предоставляет все необходимые методы для работы с API. Она поддерживает:

генерация ответов с помощью моделей GigaChat в синхронном и асинхронном режиме;
обработку потоковой передачи токенов;
создание эмбеддингов;
работу с функциями;
работу с файлами;
подсчет токенов.

Больше информации — в репозитории проекта .

Установка

Для работы библиотеки используйте Python в версии от 3.8 до 3.13.

Для установки библиотеки используйте менеджер пакетов pip:

pip install gigachat

Быстрый старт

Для работы с библиотекой вам понадобятся ключ авторизации API и сертификаты Минцифры.

Передайте полученный ключ авторизации в параметре credentials при инициализации объекта GigaChat.

Пример запроса на генерацию ответа с помощью библиотеки GigaChat:

from gigachat import GigaChat

# Укажите ключ авторизации, полученный в личном кабинете, в интерфейсе проекта GigaChat API
with GigaChat(credentials="ваш_ключ_авторизации") as giga:
    response = giga.chat("Какие факторы влияют на стоимость страховки на дом?")
    print(response.choices[0].message.content)

Примеры использования

Больше примеров — в репозитории .

Потоковая передача токенов

Получение токенов по мере их генерации:

from gigachat import GigaChat

with GigaChat() as client:
    for chunk in client.stream("Напиши короткое стихотворение о программировании"):
        print(chunk.choices[0].delta.content, end="", flush=True)
    print()  # Перевод строки в конце вывода

Асинхронный режим

Для работы в асинхронном режиме используйте конструкцию async/await:

import asyncio
from gigachat import GigaChat

async def main():
    async with GigaChat() as client:
        # Асинхронный чат
        response = await client.achat("Объясните квантовые вычисления простыми словами")
        print(response.choices[0].message.content)

        # Асинхронная потоковая передача
        print("Потоковый вывод:")
        async for chunk in client.astream("Расскажите анекдот"):
            print(chunk.choices[0].delta.content, end="", flush=True)
        print()

asyncio.run(main())

Создание эмбеддингов

Генерация векторного представления текста:

from gigachat import GigaChat

with GigaChat() as client:
    result = client.embeddings(["Привет, мир!", "Машинное обучение интересно"])

    for i, item in enumerate(result.data):
        print(f"Текст {i + 1}: {len(item.embedding)} измерений")

Работа с функциями функций

Пример вызова генерации аргументов для пользовательской функции прогноза погоды.

Подробнее о функциях в GigaChat — в разделе Работа с функциями.

from gigachat import GigaChat
from gigachat.models import Chat, Messages, MessagesRole, Function, FunctionParameters

weather_function = Function(
    name="get_weather",
    description="Получить текущую погоду в указанном месте",
    parameters=FunctionParameters(
        type="object",
        properties={
            "location": {
                "type": "string",
                "description": "Название города, например Москва"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Единицы измерения температуры"
            }
        },
        required=["location"],
    ),
)

chat = Chat(
    messages=[Messages(role=MessagesRole.USER, content="Какая погода в Токио?")],
    functions=[weather_function],
)

with GigaChat() as client:
    response = client.chat(chat)
    message = response.choices[0].message

    if response.choices[0].finish_reason == "function_call":
        print(f"Функция: {message.function_call.name}")
        print(f"Аргументы: {message.function_call.arguments}")

Параметры объекта GigaChat

В таблице описаны параметры, которые можно передать при инициализации объекта GigaChat:

Параметр	Обязательный	Значение по умолчанию	Описание
`credentials`	да	`None`	Ключ авторизации для обмена сообщениями с GigaChat API. Ключ авторизации содержит информацию о версии API, к которой выполняются запросы. Если вы используете версию API для ИП или юрлиц, укажите это явно в параметре `scope`
`verify_ssl_certs`	нет	`True`	Отключение проверки ssl-сертификатов. Для обращения к GigaChat API нужно установить корневой сертификат НУЦ Минцифры. Используйте параметр ответственно, так как отключение проверки сертификатов снижает безопасность обмена данными
`scope`	нет	`GIGACHAT_API_PERS`	Версия API, к которой будет выполнен запрос. По умолчанию запросы передаются в версию для физических лиц. Возможные значения: `GIGACHAT_API_PERS` — версия API для физических лиц; `GIGACHAT_API_B2B` — версия API для ИП и юрлиц при работе по предоплате. `GIGACHAT_API_CORP` — версия API для ИП и юрлиц при работе по постоплате.
`model`	нет	`GigaChat`	Позволяет явно задать модель GigaChat. Вы можете посмотреть список доступных моделей с помощью метода `get_models()`, который выполняет запрос `GET /models`. Стоимость запросов к разным моделям отличается. Подробную информацию о тарификации запросов к той или иной модели вы ищите в официальной документации
`base_url`	нет	`https://gigachat.devices.sberbank.ru/api/v1`	Адрес API. По умолчанию запросы отправляются по адресу `https://gigachat.devices.sberbank.ru/api/v1/`, но если вы хотите использовать модели в раннем доступе, укажите адрес `https://gigachat-preview.devices.sberbank.ru/api/v1`
`auth_url`	нет	`https://ngw.devices.sberbank.ru:9443/api/v2/oauth`	Адрес для получения токена доступа
`access_token`.	нет	`None`	Предварительно полученный токен доступа (обходит OAuth)
`timeout`	нет	`30.0`	Таймаут запросов в секундах
`max_connections`	нет	`None`	Максимальное количество одновременных соединений
`max_retries`	нет	`0`	Максимальное число повторных попыток при временных сбоях
`retry_backoff_factor`	нет	`0.5`	Коэффициент экспоненциальной выдержки (времени до отправки повторного запроса)
`retry_on_status_codes`	нет	`(429, 500, 502, 503, 504)`	HTTP-коды состояния, при которых повторяется запрос

Чтобы не указывать параметры при каждой инициализации, задайте их в переменных окружения.

Способы аутентификации

Для аутентификации, кроме ключа, полученного в личном кабинете, вы можете использовать:

имя пользователя и пароль для доступа к сервису;
сертификаты TLS;
токен доступа (access token), полученный в обмен на ключ авторизации в запросе POST /api/v2/oauth.

Для этого передайте соответствующие параметры при инициализации.

Имя пользователя и пароль

from gigachat import GigaChat

giga = GigaChat(
    base_url="https://gigachat.devices.sberbank.ru/api/v1",
    user="имя_пользоваеля",
    password="пароль",
)

Сертификаты по протоколу TLS (mTLS):

from gigachat import GigaChat

giga = GigaChat(
    base_url="https://gigachat.devices.sberbank.ru/api/v1",
    cert_file="certs/client.pem",         # Клиентский сертификат
    key_file="certs/client.key",          # Приватный ключ клиента
    key_file_password="<key_password>",   # Опционально: пароль для зашифрованного ключа
)

Токен доступа

from gigachat import GigaChat

giga = GigaChat(
    access_token="ваш_токен_доступа",
)

Токен действителен в течение 30 минут.

Предварительная аутентификация

По умолчанию, библиотека GigaChat получает токен доступа при первом запросе к API.

Если вам нужно получить токен и выполнить аутентификацию до запроса, инициализируйте объект GigaChat и вызовите метод get_token().

from gigachat import GigaChat

giga = GigaChat(credentials="<your_authorization_key>")
token = giga.get_token()
print(f"Время истечения: {token.expires_at}")

Настройка переменных окружения

Чтобы задать параметры с помощью переменных окружения, в названии переменной используйте префикс GIGACHAT_.

# Аутентификация
export GIGACHAT_CREDENTIALS="<your_authorization_key>"
export GIGACHAT_SCOPE="GIGACHAT_API_PERS"

# Подключение
export GIGACHAT_BASE_URL="https://gigachat.devices.sberbank.ru/api/v1"
export GIGACHAT_TIMEOUT="60.0"
export GIGACHAT_VERIFY_SSL_CERTS="true"
# TLS: путь к файлу связки доверенных сертификатов (обычно необходим — клиенты HTTP Python часто не используют хранилище доверия ОС по умолчанию)
export GIGACHAT_CA_BUNDLE_FILE="<your_ca_bundle_file>"

# Модель
export GIGACHAT_MODEL="GigaChat"

# Повтор попытки
export GIGACHAT_MAX_RETRIES="3"
export GIGACHAT_RETRY_BACKOFF_FACTOR="0.5"

Инициализация без передачи параметров:

from gigachat import GigaChat

# Параметры загружаются из переменных окружения
with GigaChat() as giga:
    response = giga.chat("Привет!")

Обработка ошибок

Исключения, которые может вернуть SDK:

from gigachat import GigaChat
from gigachat.exceptions import (
    GigaChatException,
    AuthenticationError,
    RateLimitError,
    BadRequestError,
    ForbiddenError,
    NotFoundError,
    RequestEntityTooLargeError,
    ServerError,
)

try:
    with GigaChat() as client:
        response = client.chat("Привет!")
        print(response.choices[0].message.content)
except AuthenticationError as e:
    print(f"Ошибка аутентификации: {e}")
except RateLimitError as e:
    print(f"Достигнут лимит скорости. Повторите попытку через {e.retry_after} секунд.")
except BadRequestError as e:
    print(f"Неверный запрос: {e}")
except ForbiddenError as e:
    print(f"Отказано в доступе: {e}")
except NotFoundError as e:
    print(f"Запрошенный ресурс не найден: {e}")
except RequestEntityTooLargeError as e:
    print(f"Слишком большой объем запроса: {e}")
except ServerError as e:
    print(f"Ошибка сервера: {e}")
except GigaChatException as e:
    print(f"Ошибка GigaChat: {e}")

Библиотека возвращает исключения:

Исключение	Код статуса HTTP	Описание
`GigaChatException`	—	Основное исключение библиотеки
`ResponseError`	—	Основная ошибка HTTP-ответа
`AuthenticationError`	401	Неверные или просроченные учетные данные
`BadRequestError`	400	Некорректный запрос или неверные параметры
`ForbiddenError`	403	Доступ запрещен (недостаточно прав)
`NotFoundError`	404	Запрашиваемый ресурс не найден
`RequestEntityTooLargeError`	413	Размер тела запроса превышает ограничения
`RateLimitError`	429	Превышен лимит запросов (используйте свойство `e.retry_after`)
`ServerError`	5xx	Внутренняя ошибка сервера

Дополнительные возможности

Контекстные переменные

С помощью SDK вы можете передавать идентификаторы сессий и запросов, а также задавать собственные заголовки запросов, которые могут понадобиться для отладки и журналирования:

from gigachat import GigaChat, session_id_cvar, request_id_cvar, custom_headers_cvar
import uuid

# Идентификаторы сессии и запроса
session_id_cvar.set("user-session-12345")
request_id_cvar.set(str(uuid.uuid4()))

# Собственный заголовок
custom_headers_cvar.set({"X-Custom-Header": "custom-value"})

with GigaChat() as client:
    response = client.chat("Привет!")

Доступные контекстные переменные:

Переменная	Заголовок	Описание
`session_id_cvar`	`X-Session-ID`	Идентификатор сессии
`request_id_cvar`	`X-Request-ID`	Идентификатор запроса
`client_id_cvar`	`X-Client-ID`	Идентификатор клиента
`custom_headers_cvar`		Словарь дополнительных заголовков

Настройка повтора

Настройте автоматическое повторение запросов с экспоненциальным откладыванием при возникновении временных сбоев:

from gigachat import GigaChat

client = GigaChat(
    max_retries=3,                          # Повторяем до трех раз
    retry_backoff_factor=0.5,               # Задержки: 0.5 секунды, 1 секунда, 2 секунды
    retry_on_status_codes=(429, 500, 502, 503, 504),
)

Подсчет токенов

Используйте метод tokens_count(), чтобы оценить количество токенов перед отправкой запросов:

from gigachat import GigaChat

with GigaChat() as client:
    counts = client.tokens_count(["Привет, мир!", "Программирование увлекательно"])
    for count in counts:
        print(f"Количество токенов: {count.tokens}, символов: {count.characters}")

Список моделей

Для просмотра списка доступных моделей и их параметров используйте метод get_models():

from gigachat import GigaChat

with GigaChat() as client:
    models = client.get_models()
    for model in models.data:
        print(f"{model.id_} (owned_by={model.owned_by})")

Работа с файлами

Для работы с хранилищем файлов используйте методы upload_file(), get_files() и delete_file():

from gigachat import GigaChat

with GigaChat() as client:
    # Загрузка файла
    with open("document.pdf", "rb") as f:
        uploaded = client.upload_file(f, purpose="general")
    print(f"Файл загружен: {uploaded.id}")

    # Просмотр списка файлов
    files = client.get_files()
    for file in files.data:
        print(f"{file.id}: {file.filename}")

    # Удаление файла
    client.delete_file(uploaded.id)

Проверка остатка токенов

С помощью метода get_balance() вы можете узнать сколько токенов у вас осталось. Метод работает если у вас есть оплаченные пакеты токенов. Если вы оплачиваете работу с API по схеме pay-as-you-go, запрос вернет ошибку 403 Permission Denied.

from gigachat import GigaChat

with GigaChat(scope="GIGACHAT_API_B2B") as client:
    balance = client.get_balance()
    for entry in balance.balance:
        print(f"{entry.usage}: {entry.value}")

Смотрите также

Примеры работы с GigaChat SDK

Описание

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней

Установка﻿

Быстрый старт﻿

Примеры использования﻿

Потоковая передача токенов﻿

Асинхронный режим﻿

Создание эмбеддингов﻿

Работа с функциями функций﻿

Параметры объекта GigaChat﻿

Способы аутентификации﻿

Имя пользователя и пароль﻿

Сертификаты по протоколу TLS (mTLS):﻿

Токен доступа﻿

Предварительная аутентификация﻿

Настройка переменных окружения﻿

Обработка ошибок﻿

Дополнительные возможности﻿

Контекстные переменные﻿

Настройка повтора﻿

Подсчет токенов﻿

Список моделей﻿

Работа с файлами﻿

Проверка остатка токенов﻿