GigaChatLib 1.0.0

GigaChatLib

Библиотека для работы с GigaChat API (Сбер) для .NET. Реализует авторизацию с автоматическим кэшированием и обновлением токена, чат-completion (в т.ч. потоковую генерацию и вызов функций), эмбеддинги, подсчёт токенов, работу с файлами, список моделей и мониторинг баланса — с готовой регистрацией в DI.

Установка

dotnet add package GigaChatLib

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

Ключ авторизации (Authorization Key, Base64) выдаётся в личном кабинете.

using GigaChatLib.Clients;
using GigaChatLib.Dtos.Chat;
using GigaChatLib.Dtos.Chat.Messages;
using GigaChatLib.Enums;
using GigaChatLib.Extensions;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddGigaChat(options =>
{
    options.AuthorizationKey = "<ваш Authorization Key>";
    options.Scope = ApiScope.GIGACHAT_API_PERS;
});

await using var provider = services.BuildServiceProvider();
var giga = provider.GetRequiredService<IGigaChatClient>();

var response = await giga.Chat.CreateCompletionAsync(new ChatCompletionRequest
{
    Model = "GigaChat",
    Messages = { new UserMessage { Content = "Привет! Расскажи о себе в двух словах." } }
});

Console.WriteLine(response.Choices[0].Message.Content);

В ASP.NET Core или другом приложении с уже существующим IServiceCollection/IHostBuilder регистрация ничем не отличается — просто вызовите AddGigaChat() вместе с остальными сервисами.

Ручная сборка без DI

Если DI-контейнер не используется, клиенты можно собрать вручную — именно так и работает AddGigaChat() под капотом:

using GigaChatLib.Auth;
using GigaChatLib.Clients.Chat;
using GigaChatLib.Configuration;
using GigaChatLib.Http;

var options = new GigaChatOptions { AuthorizationKey = "<ваш ключ>" };

var authHttp = new HttpClient();
var authService = new GigaChatAuthService(authHttp, options);
var tokenProvider = new GigaChatTokenProvider(authService, options);

var http = new HttpClient(new BearerTokenHandler(tokenProvider) { InnerHandler = new HttpClientHandler() })
{
    BaseAddress = new Uri(options.BaseUrl)
};

var chat = new ChatClient(http);

Потоковая генерация (SSE)

StreamCompletionAsync возвращает IAsyncEnumerable<ChatCompletionChunk> — фрагменты ответа приходят по мере генерации:

await foreach (var chunk in giga.Chat.StreamCompletionAsync(request))
{
    var delta = chunk.Choices.FirstOrDefault()?.Delta;
    if (!string.IsNullOrEmpty(delta?.Content))
        Console.Write(delta.Content);
}

Вызов функций (function calling)

using GigaChatLib.Dtos.Chat.Functions;

var request = new ChatCompletionRequest
{
    Model = "GigaChat",
    Messages = { new UserMessage { Content = "Какая погода в Москве?" } },
    Functions = new List<FunctionDefinition>
    {
        new()
        {
            Name = "weather_forecast",
            Description = "Возвращает температуру на заданный период",
            Parameters = new
            {
                type = "object",
                properties = new { location = new { type = "string" } },
                required = new[] { "location" }
            }
        }
    },
    FunctionCall = FunctionCallMode.Auto // либо FunctionCallMode.Named("weather_forecast") для принудительного вызова
};

var response = await giga.Chat.CreateCompletionAsync(request);
var call = response.Choices[0].Message.FunctionCall;
if (call is not null)
{
    // выполнить call.Name с аргументами call.Arguments и отправить результат
    // обратно моделью сообщением с ролью function (FunctionMessage)
}

Остальные эндпоинты

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

Любая ошибка API (не-2xx ответ) выбрасывается как GigaChatApiException с StatusCode и, если сервер его вернул, ErrorCode:

try
{
    await giga.Chat.CreateCompletionAsync(request);
}
catch (GigaChatApiException ex)
{
    Console.WriteLine($"Ошибка {ex.StatusCode} ({ex.ErrorCode}): {ex.Message}");
}

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

GigaChat API использует сертификат, выпущенный «Российским национальным удостоверяющим центром» Минцифры России. Если в системе не установлен этот корневой сертификат (типичная ситуация вне корпоративного/российского окружения — например, на CI-агентах или машинах разработчиков без предустановленных сертификатов), запросы будут падать с ошибкой проверки TLS-цепочки.

Правильное решение — установить сертификат один раз в системное хранилище:

1. Скачайте корневой и промежуточный сертификаты с официальной страницы Госуслуг: https://www.gosuslugi.ru/tls.
2. Установите оба файла в хранилище «Доверенные корневые центры сертификации» (Trusted Root Certification Authorities) операционной системы.
3. После установки запросы к https://gigachat.devices.sberbank.ru и https://ngw.devices.sberbank.ru будут проходить проверку сертификата как обычно.

GigaChatOptions.IgnoreCertificateErrors отключает проверку TLS-сертификата целиком и предназначен только для локальной отладки, когда установить сертификат по каким-то причинам временно невозможно:

services.AddGigaChat(options =>
{
    options.AuthorizationKey = "...";
    options.IgnoreCertificateErrors = true; // только для отладки!
});

Никогда не включайте этот флаг в production — это отключает защиту от подмены сервера (MITM) для всех запросов библиотеки.

Структура проекта

• Auth/ — обмен Authorization Key на токен и его кэширование (GigaChatTokenProvider, single-flight обновление).
• Clients/ — клиенты API: Chat, Files, Models, Monitoring, Embeddings, Tokens.
• Configuration/ — GigaChatOptions.
• Dtos/ — модели запросов и ответов.
• Enums/ — перечисления (ApiScope, FinishReason, MessageRole).
• Exceptions/ — GigaChatApiException.
• Extensions/ — AddGigaChat() для регистрации в DI.
• Http/ — BearerTokenHandler, общий разбор ответов API.
• Json/ — единые настройки JsonSerializerOptions.

Примеры

В репозитории — рабочие примеры консольного и WPF-приложений (ExampleConsoleApp, ExampleWPFApp), использующие библиотеку через AddGigaChat().

Лицензия

Apache License 2.0.