Развернуть

Python SDK для GigaChat API

Обновлено 8 июня 2026

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

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

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

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

Установка

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

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

pip install gigachat

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

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

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

Пример запроса на генерацию ответа:

from gigachat import GigaChat

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

Миграция на новый API-контракт

Методы client.chat и client.achat теперь предоставляют primary-поверхность chat/completions:

client.chat.create(...)
client.chat.stream(...)
client.chat.parse(...)
await client.achat.create(...)
client.achat.stream(...)
await client.achat.parse(...)

Предыдущий контракт доступен через корневые методы совместимости:

client.chat(...)
client.stream(...)
client.chat_parse(...)
await client.achat(...)
client.astream(...)
await client.achat_parse(...)

Корневые методы не считаются устаревшими и не выдают DeprecationWarning. При миграции используйте новые primary-модели: ChatCompletionRequest, ChatCompletionResponse, ChatMessage и связанные с ними Chat*-модели вместо старых Chat, Messages, Function, Usage.

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

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

Генерация ответа

from gigachat import GigaChat

with GigaChat(credentials="<ваш_ключ_авторизации>") as client:
    response = client.chat.create("Привет, GigaChat!")
    print(response.messages[0].content[0].text)

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

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

from gigachat import GigaChat

with GigaChat() as client:
    for chunk in client.chat.stream("Напиши короткое стихотворение о программировании"):
        for msg in chunk.messages or []:
            for part in msg.content or []:
                if part.text:
                    print(part.text, end="", flush=True)
    print()

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

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

import asyncio
from gigachat import GigaChat


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

        # Асинхронная потоковая передача
        print("Потоковый вывод:")
        async for chunk in client.achat.stream("Расскажите анекдот"):
            for msg in chunk.messages or []:
                for part in msg.content or []:
                    if part.text:
                        print(part.text, 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 ChatCompletionRequest, ChatMessage, ChatFunctionSpecification, ChatFunctionsTool

# Описание функции
functions = [
    ChatFunctionSpecification(
        name="get_weather",
        description="Возвращает текущую погоду для местоположения",
        parameters={
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "Название города, например, «Москва»"
                }
            },
            "required": ["location"]
        }
    )
]

request = ChatCompletionRequest(
    messages=[ChatMessage(role="user", content="Какая погода в Болхове?")],
    tools=[ChatFunctionsTool(functions=functions)],
)

with GigaChat() as client:
    response = client.chat.create(chat)
    message = response.messages[0]
    function_call = extract_function_call(message)

    if function_call is not None:
        print(f"Функция: {function_call.name}")
        print(f"Аргументы: {function_call.arguments}")

Vision

Библиотека поддерживает распознавание изображений — передайте изображение в запросе и задайте о нем вопрос:

from gigachat import GigaChat
from gigachat.models import ChatCompletionRequest, ChatMessage, ChatContentPart

request = ChatCompletionRequest(
    messages=[ChatMessage(role="user", content=[
        ChatContentPart(type="text", text="Что изображено на этой картинке?"),
        ChatContentPart(type="image_url", image_url={"url": "https://example.com/image.jpg"}),
    ])],
)

with GigaChat() as client:
    response = client.chat.create(request)
    print(response.messages[0].content[0].text)

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

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

Параметр	Обязательный	Значение по умолчанию	Описание
`credentials`	да	`None`	Ключ авторизации для обмена сообщениями с GigaChat API. Ключ авторизации содержит информацию о версии API, к которой выполняются запросы. Если вы используете версию API для ИП или юрлиц, укажите это явно в параметре `scope`
`user`	`str`	`None`	Имя пользователя для аутентификации
`password`	`str`	`None`	Пароль для аутентификации
`ca_bundle_file`	`str`	`None`	Путь к файлу корневого сертификата
`cert_file`	`str`	`None`	Путь к клиентскому сертификату (для mTLS)
`key_file`	`str`	`None`	Путь к клиентскому ключу (для mTLS)
`key_file_password`	`str`	`None`	Пароль для клиентского ключа
`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/`
`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-коды состояния, при которых повторяется запрос

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

Переменные окружения

Все параметры можно задать в переменных окружения с префиксом GIGACHAT_:

# Аутентификация
export GIGACHAT_CREDENTIALS="<ваш_ключ_авторизации>"
export GIGACHAT_SCOPE="GIGACHAT_API_PERS"

# Подключение
export GIGACHAT_BASE_URL="https://api.giga.chat/v1"
export GIGACHAT_TIMEOUT="60.0"
export GIGACHAT_VERIFY_SSL_CERTS="true"
export GIGACHAT_CA_BUNDLE_FILE="<путь_к_файлу_ca>"

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

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

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

from gigachat import GigaChat

# Конфигурация загружается из переменных окружения
with GigaChat() as client:
    response = client.chat.create("Привет!")
    print(response.messages[0].content[0].text)

Аутентификация

Библиотека поддерживает разные способы аутентификации.

При использовании нескольких способов одновременно они применяются в порядке:

custom_headers_cvar["Authorization"] — переопределяет любой другой источник.
authorization_cvar — отключает автоматическое получение и обновление токена.
Явная передача токена в access_token. При ошибке 401 и наличии OAuth-ключа или логина/пароля SDK получит новый токен.
Ключ авторизации в credentials — ключ для получения и обновления токена.
Логин и пароль (user + password) — получение токена через /token.

Ключ авторизации (рекомендуется)

from gigachat import GigaChat

client = GigaChat(credentials="<ваш_ключ_авторизации>")

В ключе авторизации содержатся данные о версии API: GIGACHAT_API_B2B, GIGACHAT_API_PERS или GIGACHAT_API_CORP. Чтобы избежать ошибок, передайте ее явно в scope:

client = GigaChat(
    credentials="<ваш_ключ_авторизации>",
    scope="GIGACHAT_API_B2B",
)

from gigachat import GigaChat

client = GigaChat(
    base_url="https://api.giga.chat/api/v1",
    user="<имя_пользователя>",
    password="<пароль>",
)

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

from gigachat import GigaChat

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

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

from gigachat import GigaChat

client = GigaChat(access_token="<ваш_токен_доступа>")

Токен доступа действует 30 минут. Используйте этот способ, если управляете жизненным циклом токена самостоятельно.

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

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

from gigachat import GigaChat

client = GigaChat(credentials="<ваш_ключ_авторизации>")
token = client.get_token()  # Аутентификация сейчас
print(f"Токен истекает: {token.expires_at}")

SSL-сертификаты

API GigaChat использует сертификаты, выпущенные НУЦ Минцифры. Чтобы библиотека могла отправлять запросы, настройте корневой сертификат.

Отключение проверки сертификатов

Отключение проверки сертификатов снижает безопасность обмена данными и не рекомендуется для production-среды.

from gigachat import GigaChat

client = GigaChat(verify_ssl_certs=False)

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

Исключения, которые может вернуть 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.create("Привет!")

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

Переменная	Заголовок	Описание
`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),
)

При использовании SDK c библиотекой, которая тоже делает повторы запросов (langchain-gigachat или LangChain), включите их только в одной из библиотек. В противном случае число повторных попыток будет умножаться: три повтора SDK × три повтора фреймворка.

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

Используйте метод 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}")

    # Просмотр выбранного файла
    single_file = client.get_file("{uploaded.id_}")
    print(f"{single_file}")

    # Удаление файла
    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

, чтобы сообщить нам об ошибке

Установка﻿

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

Миграция на новый API-контракт﻿

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

Генерация ответа﻿

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

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

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

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

Vision﻿

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

Переменные окружения﻿

Аутентификация﻿

Ключ авторизации (рекомендуется)﻿

Логин и пароль﻿

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

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

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

SSL-сертификаты﻿

Отключение проверки сертификатов﻿

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

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

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

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

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

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

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

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