Skip to content

helios-ag/gigachat-go

BranchesTags

Repository files navigation

Go GigaChat AI Client

Go Reference

Клиентская библиотека на Go для работы с GigaChat API от Сбербанка.

Содержание

Особенности

  • ✅ Полная поддержка GigaChat API
  • ✅ Автоматическое обновление OAuth токенов
  • ✅ Поддержка двух методов аутентификации (Client Credentials и API Key)
  • ✅ Потокобезопасность
  • ✅ Контекстная поддержка для отмены запросов
  • ✅ Управление файлами (загрузка, удаление, список)
  • ✅ Проверка текста на AI-генерацию
  • ✅ Генерация эмбеддингов
  • ✅ Подсчет токенов
  • ✅ Удобный API с примерами использования

Установка

go get github.com/helios-ag/go-gigachat-ai

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

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

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/helios-ag/go-gigachat-ai"
    "github.com/helios-ag/go-gigachat-ai/gpt"
)

func main() {
    ctx := context.Background()
    
    // Создание клиента с API ключом
    client, err := gigachat.NewClientWithApiKey(ctx, "your-api-key")
    if err != nil {
        panic(err)
    }
    defer client.Close()
    
    // Установка глобального API
    gigachat.SetAPI(client)
    
    // Отправка запроса
    request := &gpt.ChatRequest{
        Model: "GigaChat-2-Pro",
        Messages: []gpt.Message{
            {
                Role:    "user",
                Content: "Привет, как дела?",
            },
        },
    }
    
    response, err := gpt.Chat(ctx, request)
    if err != nil {
        panic(err)
    }
    
    fmt.Println(response.Choices[0].Message.Content)
}

Использование Client ID и Client Secret

client, err := gigachat.NewClient(ctx, "client-id", "client-secret")
if err != nil {
    panic(err)
}
defer client.Close()

Конфигурация

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

Библиотека поддерживает следующие переменные окружения:

  • GIGACHAT_CLIENT_ID - идентификатор клиента
  • GIGACHAT_CLIENT_SECRET - секретный ключ клиента
  • GIGACHAT_API_KEY - API ключ (альтернатива Client ID/Secret)

Опции клиента

Клиент поддерживает различные опции конфигурации:

client, err := gigachat.NewClientWithConfig(config,
    gigachat.WithCustomURL("https://custom-api-url.com"),
    gigachat.WithCustomURLOauth("https://custom-oauth-url.com"),
    gigachat.WithCustomTimeout(60*time.Second),
    gigachat.WithCustomScope(gigachat.ScopeApiIndividual),
    gigachat.WithCustomClient(&http.Client{}),
)

Scopes (Области доступа)

Библиотека поддерживает следующие области доступа:

  • ScopeApiIndividual - для индивидуальных пользователей (GIGACHAT_API_PERS)
  • ScopeApiBusiness - для бизнеса (GIGACHAT_API_CORP)
  • ScopeApiB2B - для B2B (GIGACHAT_API_B2B)

Модели

Доступные константы моделей:

  • GIGACHAT_2_LITE - "GigaChat-2"
  • GIGACHAT_2_PRO - "GigaChat-2-Pro"
  • GIGACHAT_2_MAX - "GigaChat-2-Max"

Роли сообщений

  • UserRole - "user"
  • AssistantRole - "assistant"
  • SystemRole - "system"

Модули и функции

Основной клиент

NewClient(ctx context.Context, clientId string, clientSecret string) (*Client, error)

Создает новый клиент GigaChat с использованием Client ID и Client Secret.

Параметры:

  • ctx - контекст для управления жизненным циклом запроса
  • clientId - идентификатор клиента
  • clientSecret - секретный ключ клиента

Возвращает:

  • *Client - экземпляр клиента
  • error - ошибка, если не удалось создать клиент

NewClientWithApiKey(ctx context.Context, apiKey string) (*Client, error)

Создает новый клиент GigaChat с использованием API ключа.

Параметры:

  • ctx - контекст для управления жизненным циклом запроса
  • apiKey - API ключ (base64 encoded)

Возвращает:

  • *Client - экземпляр клиента
  • error - ошибка, если не удалось создать клиент

NewClientWithConfig(config *ClientConfig, options ...ClientOption) (*Client, error)

Создает новый клиент с кастомной конфигурацией.

Параметры:

  • config - конфигурация клиента
  • options - опции для настройки клиента

Опции:

  • WithCustomURL(url string) - кастомный URL API
  • WithCustomURLOauth(url string) - кастомный URL OAuth
  • WithCustomClient(client *http.Client) - кастомный HTTP клиент
  • WithCustomTimeout(timeout time.Duration) - кастомный таймаут
  • WithCustomScope(scope string) - кастомная область доступа

SetAPI(api API)

Устанавливает глобальный экземпляр API для использования в модулях.

GetAPI(options ...ClientOption) API

Получает глобальный экземпляр API или создает новый, если он не установлен.

Close()

Закрывает клиент, останавливает фоновые процессы (обновление токенов) и освобождает ресурсы.

GetConfig() *ClientConfig

Возвращает конфигурацию клиента.

GPT (Чат)

Модуль для работы с чатом GigaChat.

Chat(ctx context.Context, request *ChatRequest) (*schema.ChatCompletion, error)

Отправляет запрос на генерацию ответа чат-модели.

Параметры:

  • ctx - контекст запроса
  • request - запрос

Структура ChatRequest:

type ChatRequest struct {
    Model             string    // Модель для использования (например, "GigaChat-2-Pro")
    Messages          []Message // Массив сообщений
    Temperature       *float64  // Температура (опционально)
    TopP              *float64  // Top-p sampling (опционально)
    Stream            *bool     // Потоковая передача (опционально)
    MaxTokens         *int32    // Максимальное количество токенов (опционально)
    RepetitionPenalty *float64  // Штраф за повторения (опционально)
    UpdateInterval    *int64    // Интервал обновления для streaming (опционально)
}

Структура Message:

type Message struct {
    Role             string   // Роль отправителя ("user", "assistant", "system")
    Content          string   // Содержимое сообщения
    FunctionsStateId string   // ID состояния функций (опционально)
    Attachments      []string // Вложения (опционально)
}

Возвращает:

  • *schema.ChatCompletion - результат
  • error - ошибка, если запрос не удался

Пример:

request := &gpt.ChatRequest{
    Model: "GigaChat-2-Pro",
    Messages: []gpt.Message{
        {
            Role:    "system",
            Content: "Ты полезный ассистент.",
        },
        {
            Role:    "user",
            Content: "Расскажи о GigaChat",
        },
    },
    Temperature: floatPtr(0.7),
    MaxTokens:   int32Ptr(1000),
}

response, err := gpt.Chat(ctx, request)

Models (Модели)

Модуль для получения списка доступных моделей.

Models(ctx context.Context) (*schema.ModelsResponse, error)

Получает список всех доступных моделей.

Параметры:

  • ctx - контекст запроса

Возвращает:

  • *schema.ModelsResponse - список моделей
  • error - ошибка, если запрос не удался

Структура ModelsResponse:

type ModelsResponse struct {
    Data   []Model // Массив моделей
    Object string  // Тип объекта
}

type Model struct {
    ID      string // Идентификатор модели
    Object  string // Тип объекта
    OwnedBy string // Владелец модели
}

Пример:

models, err := models.Models(ctx)
if err != nil {
    panic(err)
}

for _, model := range models.Data {
    fmt.Printf("Model: %s\n", model.ID)
}

Embeddings (Эмбеддинги)

Модуль для генерации векторных представлений текста.

Embeddings(ctx context.Context, request *EmbeddingRequest) (*schema.EmbeddingResponse, error)

Генерирует эмбеддинги для указанного текста.

Параметры:

  • ctx - контекст запроса
  • request - запрос на генерацию эмбеддингов

Структура EmbeddingRequest:

type EmbeddingRequest struct {
    Model string // Модель для генерации эмбеддингов
    Input string // Текст для обработки
}

Возвращает:

  • *schema.EmbeddingResponse - эмбеддинги текста
  • error - ошибка, если запрос не удался

Пример:

request := &embeddings.EmbeddingRequest{
    Model: "Embeddings",
    Input: "Текст для генерации эмбеддингов",
}

response, err := embeddings.Embeddings(ctx, request)

AiCheck (Проверка на AI)

Модуль для проверки текста на наличие AI-генерации.

AiCheck(ctx context.Context, request *AiCheckRequest) (*schema.DetectionResult, error)

Проверяет текст на наличие признаков AI-генерации.

Параметры:

  • ctx - контекст запроса
  • request - запрос на проверку

Структура AiCheckRequest:

type AiCheckRequest struct {
    Model string // Модель для проверки (например, "GigaCheckDetection")
    Input string // Текст для проверки
}

Методы:

  • Validate() error - валидирует запрос (проверяет, что Model и Input не пустые)

Возвращает:

  • *schema.DetectionResult - результат проверки
  • error - ошибка, если запрос не удался

Структура DetectionResult:

type DetectionResult struct {
    Category    string   // Категория результата
    Characters  int      // Количество символов
    Tokens      int      // Количество токенов
    AIIntervals [][2]int // Интервалы текста, сгенерированные AI
}

Ошибки:

  • ErrModelRequired - модель не указана
  • ErrInputRequired - входной текст не указан

Пример:

request := &aicheck.AiCheckRequest{
    Model: "GigaCheckDetection",
    Input: "Текст для проверки на AI-генерацию",
}

result, err := aicheck.AiCheck(ctx, request)
if err != nil {
    panic(err)
}

fmt.Printf("Category: %s\n", result.Category)
fmt.Printf("AI Intervals: %v\n", result.AIIntervals)

Balance (Баланс)

Модуль для получения информации о балансе аккаунта.

Balance(ctx context.Context) (*schema.BalanceResponse, error)

Получает информацию о балансе аккаунта.

Параметры:

  • ctx - контекст запроса

Возвращает:

  • *schema.BalanceResponse - информация о балансе
  • error - ошибка, если запрос не удался

Пример:

balance, err := balance.Balance(ctx)
if err != nil {
    panic(err)
}

for _, bal := range balance.Balance {
    fmt.Printf("Usage: %s, Value: %d\n", bal.Usage, bal.Value)
}

Files (Файлы)

Модуль для управления файлами (загрузка, удаление, получение списка).

UploadFile(ctx context.Context, filePath string) (*schema.FileResponse, error)

Загружает файл на сервер GigaChat.

Параметры:

  • ctx - контекст запроса
  • filePath - путь к файлу для загрузки

Поддерживаемые типы файлов:

  • Изображения: .jpg, .jpeg, .png, .tiff, .bmp (максимум 15 МБ)
  • Аудио: .mp3, .wav, .ogg, .flac, .m4a (максимум 35 МБ)
  • Текст: .txt, .pdf, .doc, .docx (максимум 40 МБ)

Возвращает:

  • *schema.FileResponse - информация о загруженном файле
  • error - ошибка, если загрузка не удалась

Ошибки:

  • ErrFileNotFound - файл не найден
  • ErrFileSize - размер файла превышает лимит
  • ErrUnsupportedType - неподдерживаемый тип файла

Пример:

fileResponse, err := filesClient.UploadFile(ctx, "path/to/file.jpg")
if err != nil {
    panic(err)
}

fmt.Printf("File ID: %s\n", fileResponse.ID)

DeleteFile(ctx context.Context, fileID string) (*schema.FileDeleteResponse, error)

Удаляет файл с сервера.

Параметры:

  • ctx - контекст запроса
  • fileID - идентификатор файла для удаления

Возвращает:

  • *schema.FileDeleteResponse - результат удаления
  • error - ошибка, если удаление не удалось

Пример:

result, err := filesClient.DeleteFile(ctx, "file-id")

GetFiles(ctx context.Context) (*schema.FileListResponse, error)

Получает список всех загруженных файлов.

Параметры:

  • ctx - контекст запроса

Возвращает:

  • *schema.FileListResponse - список файлов
  • error - ошибка, если запрос не удался

Пример:

files, err := filesClient.GetFiles(ctx)

GetFileInfo(ctx context.Context, fileId string) (*schema.FileInfo, error)

Получает информацию о конкретном файле.

Параметры:

  • ctx - контекст запроса
  • fileId - идентификатор файла

Возвращает:

  • *schema.FileInfo - информация о файле
  • error - ошибка, если запрос не удался

Пример:

info, err := filesClient.GetFileInfo(ctx, "file-id")

Tokens (Подсчет токенов)

Модуль для подсчета количества токенов в тексте.

Tokens(ctx context.Context, request *Request) (*schema.TokenResponse, error)

Подсчитывает количество токенов в указанном тексте.

Параметры:

  • ctx - контекст запроса
  • request - запрос на подсчет токенов

Структура Request:

type Request struct {
    Model string   // Модель для подсчета
    Input []string // Массив текстов для подсчета
}

Возвращает:

  • *schema.TokenResponse - результат подсчета токенов
  • error - ошибка, если запрос не удался

Пример:

request := &tokens.Request{
    Model: "GigaChat-2-Pro",
    Input: []string{
        "Первый текст для подсчета",
        "Второй текст для подсчета",
    },
}

response, err := tokens.Tokens(ctx, request)

Batch (Пакетная обработка)

Модуль для работы с пакетной обработкой запросов (в разработке).

Batch(ctx context.Context) (*schema.BatchListResponse, error)

Получает список пакетных заданий.

Параметры:

  • ctx - контекст запроса

Возвращает:

  • *schema.BatchListResponse - список пакетных заданий
  • error - ошибка, если запрос не удался

Примечание: Модуль находится в разработке (WIP).

BatchStatus(ctx context.Context) (*schema.BatchListResponse, error)

Получает статус пакетных заданий.

Параметры:

  • ctx - контекст запроса

Возвращает:

  • *schema.BatchListResponse - статус пакетных заданий
  • error - ошибка, если запрос не удался

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

Полные примеры использования можно найти в директории example/:

  • example/gpt/main.go - пример работы с чатом
  • example/balance/main.go - пример получения баланса
  • example/aicheck/main.go - пример проверки текста на AI
  • example/listmodels/main.go - пример получения списка моделей

Авторизация и токены

Библиотека автоматически управляет OAuth токенами:

  1. Автоматическое получение токена при создании клиента
  2. Автоматическое обновление токена в фоновом режиме за 15 минут до истечения
  3. Потокобезопасное обновление - несколько запросов не приведут к множественным обновлениям токена
  4. Поддержка контекста - обновление токена может быть отменено через контекст

Механизм обновления токенов

Клиент запускает фоновую горутину, которая:

  • Проверяет срок действия токена каждую минуту
  • Обновляет токен, если до истечения осталось менее 15 минут
  • Ожидает завершения текущего обновления перед новым обновлением

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

Библиотека возвращает ошибки в формате, соответствующем стандартам Go:

response, err := gpt.Chat(ctx, request)
if err != nil {
    // Обработка ошибки
    fmt.Printf("Ошибка: %v\n", err)
    return
}

Ошибки API возвращаются в структуре schema.Response:

  • Status - код статуса ошибки
  • Message - сообщение об ошибке

Дополнительная информация

Endpoints

Библиотека использует следующие endpoints:

  • Models - /v1/models
  • ChatCompletions - /v1/chat/completions
  • Files - /v1/files
  • Balance - /v1/balance
  • AiCheck - /v1/ai/check
  • TokensCount - /v1/tokens/count
  • Embeddings - /v1/embeddings
  • FunctionsValidate - /v1/functions/validate
  • Batches - /v1/batches

Таймауты

По умолчанию используется таймаут 30 секунд. Его можно изменить через опцию WithCustomTimeout.

Безопасность

  • Библиотека поддерживает TLS (с возможностью отключения проверки сертификата для тестирования)
  • Токены хранятся в памяти и автоматически обновляются
  • Поддерживается работа с контекстами для отмены запросов

Производительность

  • Клиент потокобезопасен и может использоваться из нескольких горутин
  • Автоматическое управление соединениями HTTP
  • Эффективное обновление токенов без блокировки запросов

Лицензия

Проект распространяется по лицензии MIT.

About

Gigachat AI Go language client

Topics

api ai sberbank golang-package llm gigachat

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages