В последнее время все больше разработчиков экспериментируют с большими языковыми моделями. GigaChat от Сбера — одна из самых доступных и мощных моделей на российском рынке. У нее есть подробное REST API, которое позволяет интегрировать нейросеть в любой продукт: от телеграм-ботов до сложных корпоративных систем.

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

Я столкнулся с этими задачами и, чтобы упростить жизнь себе и другим Go-разработчикам, написал gigago — легковесный и идиоматичный SDK. Его цель — взять на себя всю "грязную работу" и позволить вам добавить GigaChat в проект буквально за несколько минут.

В этой статье я покажу, как это сделать за 3 простых шага.

Если вам интересен процесс и вы хотите следить за дальнейшими материалами, буду признателен за подписку на мой телеграм-канал. Там я публикую полезныe материалы по разработке, разборы сложных концепций, советы как быть продуктивным и конечно же отборные мемы: https://t.me/nullPointerDotEXE.

Что обычно скрывается «под капотом» работы с API?

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

1. Процесс OAuth-аутентификации. Согласно официальной документации, для получения токена нужно отправить POST-запрос на https://ngw.devices.sberbank.ru:9443/api/v2/oauth, передав в заголовке Authorization закодированные в Base64 Client ID и Client Secret.

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

3. Логику повторных запросов (Retries). Что если токен все-таки "протух" в момент запроса? API вернет ошибку 401 Unauthorized. Правильное поведение — перехватить эту ошибку, немедленно запросить новый токен и повторить исходный запрос.

4. Конфигурацию HTTP-клиента. Настройка таймаутов, передача кастомных параметров, работа с сертификатами — все это требует дополнительного кода.

Все это — абсолютно решаемые задачи, но они отнимают время. gigago делает все это за вас «из коробки».

Шаг 1: Установка библиотеки

Начнем с самого простого. Для установки gigago достаточно одной команды в вашем терминале:

go get github.com/Role1776/gigago

Шаг 2: Инициализация клиента

Теперь самое интересное. Создадим клиент gigago. Это — сердце нашей интеграции. В этот момент SDK самостоятельно выполнит тот самый OAuth-запрос, получит токен доступа и запустит в фоне горутину для его автоматического обновления.

Вам нужен только ваш авторизационный ключ, полученный в личном кабинете.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/Role1776/gigago"
)

func main() {
	ctx := context.Background()

	// Создаем клиент с вашим авторизационным ключом.
	// В этот момент SDK автоматически получает токен доступа.
	// Для локальной разработки может понадобиться отключить проверку сертификата.
    	client, err := gigago.NewClient(ctx, "YOUR_API_KEY", gigago.WithCustomInsecureSkipVerify(true))
	if err != nil {
		log.Fatalf("Ошибка создания клиента: %v", err)
	}
	// Важно! Закрываем клиент, чтобы остановить фоновое обновление токена.
	defer client.Close()

    // ... остальной код
}

Обратите внимание на defer client.Close(). Этот вызов необходим, чтобы корректно завершить работу фонового процесса, который обновляет токен.

Шаг 3: Отправка запроса и получение ответа

Клиент готов, токен получен и будет обновляться сам. Осталось только отправить сообщение модели.

// ... продолжение функции main

// Получаем модель, с которой будем работать.
model := client.GenerativeModel("GigaChat")

// (Опционально) Настраиваем параметры модели.
// Можно задать системный промпт, температуру и другие параметры.
model.SystemInstruction = "Ты — опытный гид по путешествиям. Отвечай кратко и по делу."
model.Temperature = 0.7

// Формируем сообщение для отправки.
messages := []gigago.Message{
    {Role: gigago.RoleUser, Content: "Какая столица у Франции?"},
}

// Отправляем запрос и получаем ответ.
resp, err := model.Generate(ctx, messages)
if err != nil {
    log.Fatalf("Ошибка генерации ответа: %v", err)
}

// Печатаем ответ модели.
fmt.Println(resp.Choices[0].Message.Content)

Запускаем код и получаем результат:

Париж.

Вот и все! Мы успешно интегрировали GigaChat, не написав ни строчки кода для аутентификации или управления токенами.

Гибкая настройка для продвинутых задач

Конечно, реальные проекты часто требуют более тонкой настройки. gigago поддерживает это через функциональные опции при создании клиента.

Например, если вы корпоративный клиент и вам нужен другой scope для токена:

client, err := gigago.NewClient(
    ctx,
    "YOUR_API_KEY",
    gigago.WithCustomScope("GIGACHAT_API_CORP"), // Указываем scope для юрлиц
)

Доступные опции:

• WithCustomURLAI(url string): Задать URL для API генерации.

• WithCustomURLOauth(url string): Задать URL для OAuth-сервиса.

• WithCustomClient(client http.Client): Использовать собственный http.Client

• WithCustomTimeout(timeout time.Duration): Установить таймаут для HTTP-запросов.

• WithCustomScope(scope string): Указать scope для токена (GIGACHAT_API_PERS, GIGACHAT_API_B2B, GIGACHAT_API_CORP).

• WithCustomInsecureSkipVerify(bool): Отключить проверку TLS-сертификата.

Заключение

Моей целью было создать инструмент, который бы помог разработчикам быстрее и проще начать использовать GigaChat в своих Go-проектах, следуя лучшим практикам языка. gigago берет на себя всю рутину, позволяя вам сосредоточиться на самом интересном — на создании умных и полезных приложений.

Надеюсь, этот гайд и библиотека будут вам полезны.

Проект полностью опенсорсный и доступен на GitHub в версии v1.0.0-rc.1. Я буду очень рад вашим звездам, вопросам и, конечно же, Pull Request'ам. Давайте вместе развивать экосистему инструментов вокруг GigaChat!

Ссылка на репозиторий: github.com/Role1776/gigago

По традиции жду ваших комментариев. Гудлак!