Использование SDK

Обновлено 3 апреля 2025

Для работы с REST API GigaChat доступны одноименные библиотеки на Python, TypeScript/JavaScript и Java.

Перед началом работы убедитесь, что у вас установлены сертификаты НУЦ Минцифры.

SDK позволяет автоматически авторизовать запросы, и предоставляет методы для работы с GigaChat API. С их помощью можно:

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

Для работы с GigaChat также доступны партнерские пакеты LangChain, которые позволяют использовать модели GigaChat с фреймворком LangChain.

Подробнее — в документации GigaChain.

Начало работы

Чтобы начать работу с API с помощью SDK:

Установите или подключите в проект подходящую библиотеку:
- Python
- TS/JS
- Java
pip install gigachat
npm install gigachat
Подключите библиотеку в зависимости с помощью Gradle или Maven
Gradle:
implementation("chat.giga:gigachat-java:0.1.4")
Maven:
<dependency> <groupId>chat.giga</groupId> <artifactId>gigachat-java</artifactId> <version>0.1.4</version> </dependency>

Инициализируйте объект GigaChat:

Python
TS/JS
Java

from gigachat import GigaChat

giga = GigaChat(
   credentials="ключ_авторизации",
   scope="GIGACHAT_API_PERS",
   model="GigaChat",
)

import GigaChat from 'gigachat';

const giga = new GigaChat({
  credentials: 'ключ_авторизации',
  scope="GIGACHAT_API_PERS",
  model: 'GigaChat',
});

Базовый пример отправки запроса

public class CompletionExample {

    public static void main(String[] args) {
        GigaChatClient client = GigaChatClient.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("ключ_авторизации")
                                .build())
                        .build())
                .build();

        System.out.println(client.completions(CompletionRequest.builder()
                .model(ModelName.GIGA_CHAT)
                .message(ChatMessage.builder()
                        .content("текст запроса")
                        .role(Role.USER)
                        .build())
                .build()));
    }
}

При работе с библиотеками на Python и TS/JS объект GigaChat принимает параметры:

credentials — ключ авторизации для обмена сообщениями с GigaChat API. О том как получить ключ авторизации — в разделе Быстрый старт.
scope — версия API, к которой будет выполнен запрос. Необязательный параметр. Возможные значения:
- GIGACHAT_API_PERS — версия API для физических лиц;
- GIGACHAT_API_B2B — версия API для ИП и юрлиц при работе по предоплате.
- GIGACHAT_API_CORP — версия API для ИП и юрлиц при работе по постоплате.
По умолчанию запросы передаются в версию для физических лиц.
model — необязательный параметр, в котором можно явно задать модель GigaChat.

Примеры обращения к API с помощью библиотеки

Получить токен доступа

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

Вы можете получить токен принудительно для предварительной авторизации до отправки запросов с помощью метода get_token().

Python
Java

response = giga.get_token()

print(response)

public class GetTokenExample {

    public static void main(String[] args) {

        AuthClient client = AuthClient.builder()
                .withOAuth(
                    OAuthBuilder.builder()
                    .scope(Scope.GIGACHAT_API_PERS)
                    .authKey("<ключ_авторизации>")
                    .build()).build();
    
        client.getToken();
    }
}

Метод выполнит запрос POST /api/v2/oauth и вернет токен доступа, который вы сможете использовать для авторизации в сервисе. Токен доступа действует 30 минут.

Получить список моделей

Метод выполняет запрос GET /models и возвращает массив объектов с данными доступных моделей.

Python
TS/JS
Java

response = giga.get_models()

print(response)

data=[Model(id_='GigaChat', object_='model', owned_by='salutedevices'), Model(id_='GigaChat-Max', object_='model', owned_by='salutedevices'), Model(id_='GigaChat-Plus', object_='model', owned_by='salutedevices'), Model(id_='GigaChat-Pro', object_='model', owned_by='salutedevices')] object_='list'

let response = await giga.getModels()

console.log(response)

OAUTH UPDATE TOKEN
{
  object: 'list',
  data: [
    {
      id: 'GigaChat',
      object: 'model',
      owned_by: 'salutedevices',
      type: 'chat'
    },
    {
      id: 'GigaChat-Max',
      object: 'model',
      owned_by: 'salutedevices',
      type: 'chat'
    },
    {
      id: 'GigaChat-Plus',
      object: 'model',
      owned_by: 'salutedevices',
      type: 'chat'
    },
    {
      id: 'GigaChat-Pro',
      object: 'model',
      owned_by: 'salutedevices',
      type: 'chat'
    }
  ],
  xHeaders: {
    xRequestID: '020d6f83-6ace-4cc6-b72f-98ac8174cfaf',
    xSessionID: '44a557e9-fd47-491f-9c41-028724724d7e',
    xClientID: undefined
  }
}

public class ModelListExample {

    public static void main(String[] args) {

        GigaChatClient client = GigaChatClient.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("ключ_авторизации")
                                .build())
                        .build())
                .build();
        try {
            System.out.println(client.models());
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

ModelResponse(data=[Model(id=GigaChat, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-2, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-2-Max, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-2-Max-preview, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-2-Pro, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-2-Pro-preview, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-2-preview, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-Max, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-Max-preview, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-Plus, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-Plus-preview, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-Pro, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-Pro-preview, object=model, ownedBy=salutedevices, type=chat), Model(id=GigaChat-preview, object=model, ownedBy=salutedevices, type=chat)], object=list)

Получить ответ на сообщение

Метод выполняет запрос POST /chat/completions и возвращает ответ модели, сгенерированный на основе переданных сообщений.

Python
TS/JS
Java

В одном фрагменте:

from gigachat import GigaChat

model = GigaChat(
   credentials="ключ_авторизации",
   model="GigaChat-Pro",
)

response = giga.chat("Расскажи о себе в двух словах?")

print(response.choices[0].message.content)

    Я нейросетевая модель, созданная компанией Сбер в 2023 году. Могу помогать с ответами на вопросы, решать задачи и поддерживать беседу.

В режиме потоковой генерации токенов:

for chunk in giga.stream("Расскажи о себе подробно"):
    print(chunk.choices[0].delta.content, end="", flush=True)

    Я — нейросетевая модель, созданная компанией Сбер для помощи пользователям в решении различных задач и вопросов. Могу генерировать тексты, отвечать на вопросы, решать математические задачи, писать код, переводить тексты и многое другое. У меня есть несколько режимов работы, включая генеративный режим, режим математики, программирования, перевода и другие.
    
    Мои возможности включают:
    - Генерация текста: могу написать эссе, статью, рассказ или другой текст по вашему запросу.
    - Решение математических задач: могу решить уравнения, системы уравнений, неравенства и т.д.
    - Программирование: могу писать код на Python, JavaScript, SQL и других языках программирования.
    - Перевод: могу перевести текст с русского на английский и обратно.
    - Аналитика: могу анализировать данные и делать выводы на основе статистических данных.
    
    Я обучался на огромном количестве данных, что позволяет мне предоставлять точные и полезные ответы. Если у вас есть конкретный запрос или вопрос, я готов помочь!

В одном фрагменте:

let response = await giga.chat({
    messages: [{ role: 'user', content: 'Расскажи о себе в двух словах?' }],
});

console.log(response.choices[0]?.message.content);

OAUTH UPDATE TOKEN
Я – ИИ-помощник, готовый к разговору и решению задач!

В режиме потоковой генерации токенов:

let message = "";

for await (const chunk of giga.stream('Расскажи о себе подробно')) {
    message += chunk.choices[0]?.delta.content;
}

console.log(message);

OAUTH UPDATE TOKEN
Я – GigaChat, нейросетевая модель искусственного интеллекта, созданная компанией Сбер в 2023 году. Моя основная цель – помогать людям решать разнообразные задачи, будь то ответы на вопросы, написание текстов, программирование, математика, анализ информации и многое другое.

### Как я работаю?
Я обрабатываю запросы пользователей с помощью мощной нейронной сети, которая обучена на огромном количестве данных. Когда мне задают вопрос, я анализирую его содержание, ищу релевантные факты и идеи, а затем генерирую ответ. Важно отметить, что я стараюсь давать максимально точные и полезные ответы, основываясь на своих знаниях.

В одном фрагменте:

public class CompletionExample {

    public static void main(String[] args) {

        GigaChatClient client = GigaChatClient.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("ключ_авторизации")
                                .build())
                        .build())
                .build();
        try {
            System.out.println(client.completions(CompletionRequest.builder()
                    .model(ModelName.GIGA_CHAT_MAX)
                    .message(ChatMessage.builder()
                            .content("Расскажи о себе в двух словах?")
                            .role(Role.USER)
                            .build())
                    .build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

CompletionResponse(choices=[Choice(message=ChoiceMessage(role=assistant, content=Искусственный интеллект., created=null, name=null, functionsStateId=01b4f647-bc22-4c39-b75c-d6ab88ce4e4c, functionCall=null), index=0, finishReason=stop)], created=1743077275, model=GigaChat-Max:1.0.26.20, usage=Usage(promptTokens=12, completionTokens=10, totalTokens=22), object=chat.completion)

В режиме потоковой генерации токенов:

public class CompletionStreamingExample {

    public static void main(String[] args) {

        GigaChatClientAsync client = GigaChatClientAsync.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                              .scope(Scope.GIGACHAT_API_PERS)
                              .authKey("ключ_авторизации")
                              .build())
                        .build())
                .build();

        client.completions(CompletionRequest.builder()
                        .model(ModelName.GIGA_CHAT_MAX)
                        .message(ChatMessage.builder()
                                .content("Расскажи о себе подробно")
                                .role(Role.USER)
                                .build())
                        .build(),
                new ResponseHandler<>() {
                    @Override
                    public void onNext(CompletionChunkResponse chunk) {
                        System.out.println("Chunk: " + chunk);
                    }

                    @Override
                    public void onComplete() {
                        System.out.println("Stream completed");
                    }

                    @Override
                    public void onError(Throwable th) {
                        System.out.println("Error: " + th.getMessage());
                    }
                });
    }
}

Загрузить файл в хранилище

Метод выполняет запрос POST /files и возвращает объект с данными загруженного файла. Загруженные файлы доступны только вам.

Подробнее о работе с файлами с помощью API — в разделе Обработка файлов.

Python
TS/JS
Java

file = giga.upload_file(open("cat.jpg", "rb"))

const filePath = path.resolve('./media/cat.jpg');
const buffer = fs.readFileSync(filePath);
const file = new File([buffer], 'image.jpg', { type: 'image/jpeg' });
const uploadedFile = await giga.uploadFile(file);

public class UploadFileExample {

    public static void main(String[] args) {

        GigaChatClient client = GigaChatClient.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("ключ_авторизации")
                                .build())
                        .build())
                .build();
        try {
            System.out.println(client.uploadFile(UploadFileRequest.builder()
                    .file(new byte[1000])
                    .mimeType("application/pdf")
                    .fileName("test.pdf")
                    .purpose("general")
                    .build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

Скачать сгенерированное изображение

Метод выполняет запрос GET /files/{file_id}/content и возвращает файл изображения в бинарном представлении в формате JPG.

Подробнее о работе с файлами с помощью API — в разделе Обработка файлов.

Python
TS/JS
Java

image = giga.get_image(file_id='идентификатор_файла')

const img = giga.getImage('идентификатор_файла');

public class ImageDownloadFromCompletionsExample {

    public static void main(String[] args) {
        GigaChatClient client = GigaChatClient.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("ключ_авторизации")
                                .build())
                        .build())
                .build();
        try {
            // Получаем список моделей
            var modelResponse = client.models();
            if (modelResponse != null) {
                var completionsResponse = client.completions(CompletionRequest.builder()
                        .model(modelResponse.data().get(0).id())
                        .messages(List.of(
                                ChatMessage.builder()
                                        .role(Role.SYSTEM)
                                        .content("Ты — художник Густав Климт")
                                        .build(),
                                ChatMessage.builder()
                                        .role(Role.USER)
                                        .content("Нарисуй розового кота")
                                        .build()))
                        .build());
                if (completionsResponse != null) {
                    // Получаем ответ модели на сообщения
                    String content = completionsResponse.choices().get(0).message().content();
                    if (content != null && content.contains("img src=")) {
                        var fileId = content.split("\"")[1];
                        // Скачиваем сгенерированный файл
                        System.out.println(Arrays.toString(client.downloadFile(fileId, null)));
                    }
                }
            }
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

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

Выполняет запрос POST /embeddings и возвращает векторное представление запроса.

Подробнее об использовании эмбеддингов — в разделе Векторное представление текста.

Python
TS/JS
Java

response = giga.embeddings(["Hello world!"])
print(response)

const response = await giga.embeddings(['Hello world!']);

console.log(response.data);

public class EmbeddingExample {

    public static void main(String[] args) {

        GigaChatClient client = GigaChatClient.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("ключ_авторизации")
                                .build())
                        .build())
                .build();
        try {
            System.out.println(client.embeddings(EmbeddingRequest.builder()
                    .model("Embeddings")
                    .input(List.of("Hello world!"))
                    .build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }

}

Подсчитать количество токенов в запросе

Выполняет запрос POST /tokens/count и возвращает объект с информацией о количестве токенов, подсчитанных заданной моделью в строках.

Python
TS/JS
Java

result = giga.tokens_count(input_=["12345"], model="GigaChat-Pro")
    print(result)

    [TokensCount(tokens=6, characters=5, object_='tokens')]

const response = await giga.tokensCount(['Привет, как дела?', 'Как дела, как дела']);

console.log(response);

OAUTH UPDATE TOKEN
{
  tokens: [
    { object: 'tokens', tokens: 6, characters: 17 },
    { object: 'tokens', tokens: 5, characters: 18 }
  ],
  xHeaders: {
    xRequestID: 'e13d04d7-d02b-4e9e-ba5c-0476eace8527',
    xSessionID: '4a8b4b08-b4e6-4696-a8dc-dbadb2a5f46d',
    xClientID: undefined
  }
}

public class TokenCountExample {

    public static void main(String[] args) {

        GigaChatClient client = GigaChatClient.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("ключ_авторизации")
                                .build())
                        .build())
                .build();
        try {
            System.out.println(client.tokensCount(TokenCountRequest.builder()
                    .model(ModelName.GIGA_CHAT_MAX)
                    .input(List.of("Привет, как дела?", "Расскажи о себе"))
                    .build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

[TokenCount(object=tokens, tokens=6, characters=17), TokenCount(object=tokens, tokens=4, characters=15)]

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

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

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

Начало работы﻿

Примеры обращения к API с помощью библиотеки﻿

Получить токен доступа﻿

Получить список моделей﻿

Получить ответ на сообщение﻿

Загрузить файл в хранилище﻿

Скачать сгенерированное изображение﻿

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

Подсчитать количество токенов в запросе﻿

Начало работы

Примеры обращения к API с помощью библиотеки

Получить токен доступа

Получить список моделей

Получить ответ на сообщение

Загрузить файл в хранилище

Скачать сгенерированное изображение

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

Подсчитать количество токенов в запросе