Руководство по интеграции GigaChat

Руководство по интеграции API GigaChat (российская языковая модель от Сбера) с CodeGraph.

Содержание

Обзор

GigaChat — российский поставщик языковых моделей от Сбербанка. CodeGraph поддерживает GigaChat как альтернативу OpenAI, Yandex AI Studio или локальным моделям.

Совет: Для большего контекстного окна (до 262K токенов) рассмотрите использование Yandex AI Studio с моделями Qwen3-235B и другими.

Быстрая настройка (3 шага)

Шаг 1: Установка ключа авторизации

# Windows PowerShell
$env:GIGACHAT_AUTH_KEY = "ваш_ключ_авторизации"

# Постоянная установка (сохраняется после перезагрузки)
[System.Environment]::SetEnvironmentVariable('GIGACHAT_AUTH_KEY', 'ваш_ключ', 'User')

# Linux/Mac
export GIGACHAT_AUTH_KEY="ваш_ключ_авторизации"

# Добавьте в ~/.bashrc для постоянного действия
echo 'export GIGACHAT_AUTH_KEY="ваш_ключ"' >> ~/.bashrc

Шаг 2: Настройка config.yaml

llm:
  provider: gigachat

  gigachat:
    client_id: "019a7e2b-aeb3-78c4-ba3d-ddc1142b4ee6"
    credentials: ${GIGACHAT_AUTH_KEY}
    scope: "GIGACHAT_API_PERS"
    model: "GigaChat-2-Pro"
    temperature: 0.7
    max_tokens: 2000
    timeout: 60

Шаг 3: Проверка

pytest tests/llm/test_gigachat.py -v

Ожидаемый вывод:

tests/llm/test_gigachat.py::test_auth_key_set PASSED
tests/llm/test_gigachat.py::test_config_valid PASSED
tests/llm/test_gigachat.py::test_sdk_available PASSED

Доступные модели

Модель Описание Рекомендуется для
GigaChat-2-Pro Новейшее поколение, самая мощная Сложный анализ (рекомендуется)
GigaChat-Max Максимальное качество Критически важные задачи
GigaChat-Pro Продвинутая Общий анализ кода
GigaChat-Plus Расширенная Баланс качества и скорости
GigaChat Базовая модель Простые запросы

Области доступа API

Область (Scope) Описание
GIGACHAT_API_PERS Персональный доступ (по умолчанию)
GIGACHAT_API_CORP Корпоративный доступ
GIGACHAT_API_B2B Доступ B2B

Устанавливается в config.yaml → llm.gigachat.scope.

Автоматическая настройка

Скрипт PowerShell

# Запуск автоматической настройки
.\chroma_db\setup_gigachat.ps1

Скрипт выполнит: 1. Запросит ключ авторизации 2. Создаст config.yaml из шаблона 3. Установит SDK GigaChat 4. Проверит конфигурацию

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

# Копирование шаблона
cp config/config.gigachat.yaml.example config.yaml

# Редактирование с вашими настройками
nano config.yaml

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

Через фабрику (рекомендуется)

Рекомендуемый способ использования GigaChat в CodeGraph — через фабрику LLM, которая автоматически читает config.yaml:

from src.llm.factory import get_llm_provider

# Создаёт провайдер на основе config.yaml (provider: gigachat)
provider = get_llm_provider()

# Генерация ответа
response = provider.generate(
    system_prompt="Вы — эксперт по анализу кода",
    user_prompt="Объясните как работает MVCC в PostgreSQL"
)
print(response.content)

В рабочем процессе

from src.workflow import MultiScenarioCopilot

copilot = MultiScenarioCopilot()
result = copilot.run("Найти методы обработки транзакций")
print(result['answer'])

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

import os
from langchain_gigachat import GigaChat

auth_key = os.getenv("GIGACHAT_AUTH_KEY")

llm = GigaChat(
    credentials=auth_key,
    scope="GIGACHAT_API_PERS",
    model="GigaChat-2-Pro",
    verify_ssl_certs=False
)

response = llm.invoke("Что такое PostgreSQL?")
print(response.content)

Справочник по конфигурации

Пример полного config.yaml

llm:
  provider: gigachat

  gigachat:
    # Обязательные
    client_id: "019a7e2b-aeb3-78c4-ba3d-ddc1142b4ee6"
    credentials: ${GIGACHAT_AUTH_KEY}
    scope: "GIGACHAT_API_PERS"
    model: "GigaChat-2-Pro"

    # Опциональные
    temperature: 0.7          # Креативность (0.0–1.0)
    max_tokens: 2000          # Максимальная длина ответа
    timeout: 60               # Время ожидания запроса (секунды)
    verify_ssl_certs: true    # Проверка SSL (false для разработки)
    base_url:                 # Пользовательская точка доступа API (опционально)
    top_p:                    # Top-p выборка (опционально)

Примечание: Логика повторных попыток (3 попытки, экспоненциальная задержка 0.5–10 с) встроена в GigaChatProvider и не конфигурируется через config.yaml.

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

# Обязательные
GIGACHAT_AUTH_KEY=ваш_ключ_авторизации

# Опциональные
GIGACHAT_CLIENT_ID=019a7e2b-aeb3-78c4-ba3d-ddc1142b4ee6

Потоковая генерация и эмбеддинги

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

GigaChatProvider поддерживает потоковую генерацию для вывода в реальном времени:

from src.llm.factory import get_llm_provider

provider = get_llm_provider()

for chunk in provider.generate_stream(
    system_prompt="Вы — аналитик кода",
    user_prompt="Опишите подсистему исполнителя"
):
    print(chunk, end="", flush=True)

Эмбеддинги

GigaChat предоставляет эмбеддинги через GigaChatEmbeddings:

from src.llm.factory import get_llm_provider

provider = get_llm_provider()

vectors = provider.get_embeddings([
    "Управление памятью в PostgreSQL",
    "Уровни изоляции транзакций"
])
# vectors: List[List[float]]

Устранение неполадок

Ошибка аутентификации (401)

Error: 401 Unauthorized

Решение:

# Проверка установки ключа
echo $GIGACHAT_AUTH_KEY

# Проверка формата ключа (должен быть в base64)
python -c "import base64; base64.b64decode('$GIGACHAT_AUTH_KEY')"

Время ожидания соединения

Error: Connection timed out

Решение:

# Увеличение времени ожидания в config.yaml
gigachat:
  timeout: 120  # секунды

Ошибка SSL-сертификата

Error: SSL: CERTIFICATE_VERIFY_FAILED

Решение:

# Отключение проверки SSL (не рекомендуется для рабочей среды)
gigachat:
  verify_ssl_certs: false

Ограничение частоты запросов

Error: 429 Too Many Requests

Решение: Встроенная логика повторных попыток автоматически обрабатывает ограничения частоты (3 попытки с экспоненциальной задержкой). Если ошибки продолжаются, уменьшите частоту запросов или обновите область доступа с GIGACHAT_API_PERS на GIGACHAT_API_CORP.

Рекомендации

  1. Никогда не сохраняйте ключи авторизации в репозитории — используйте переменные окружения
  2. Используйте GigaChat-2-Pro — наилучшее качество для анализа кода
  3. Установите подходящее время ожидания — 60 с для обычных задач, 120 с для сложных
  4. Используйте фабрику — get_llm_provider() автоматически обрабатывает конфигурацию

Вопросы безопасности

  • Храните ключи авторизации в переменных окружения
  • Добавьте .env в .gitignore
  • Используйте защищённое соединение (HTTPS)
  • Включите проверку SSL в рабочей среде (verify_ssl_certs: true)

Ресурсы

Следующие шаги