Привет, Хабр!

В последнее время все больше разработчиков экспериментируют с большими языковыми моделями. 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

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