Интеграция GigaChat с LiteLLM

Полнофункциональная интеграция GigaChat API с LiteLLM - готовое решение для подключения российской языковой модели GigaChat через стандартный OpenAI-совместимый интерфейс. Включает автоматическое обновление токенов, преобразование контента и полную совместимость с AI-ассистентом Cline.

📚 Документация

Полная документация | CLI команды | FAQ | Тестовые запросы | Причины несовместимости с OpenAI API

🚀 Основные возможности

• Автоматическое обновление токенов
• Автоматическая настройка сертификатов
• Совместимость с Cline
• Streaming поддержка

📦 Установка

Через pip (рекомендуется)

# Установка пакета
pip install litellm-gigachat

# Проверка установки
litellm-gigachat --version

Из исходников (для разработки)

# 1. Клонирование репозитория
git clone https://github.com/stp008/litellm-gigachat.git
cd litellm-gigachat

# 2. Установка в режиме разработки
pip install -e .

# 3. Проверка установки
litellm-gigachat --version

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

1. Настройка API ключа

# Установите ваш authorization key от GigaChat
export GIGACHAT_AUTH_KEY="ваш_authorization_key"

2. Запуск прокси-сервера

# Через установленный пакет (рекомендуется)
litellm-gigachat

# Через исходники (для разработки)
python tools/start_proxy.py

# С кастомными параметрами (только для установленного пакета)
litellm-gigachat --host 127.0.0.1 --port 8000

# С кастомным файлом конфигурации
litellm-gigachat --config my_config.yml

# Справка по командам
litellm-gigachat --help

Примечание: Если вы работаете с исходниками проекта (клонировали репозиторий), используйте python tools/start_proxy.py. Если установили пакет через pip, используйте команду litellm-gigachat.

3. Использование через OpenAI API

import openai

client = openai.OpenAI(
    base_url="http://localhost:4000",
    api_key="any-key"  # Токен управляется автоматически
)

response = client.chat.completions.create(
    model="gigachat",
    messages=[{"role": "user", "content": "Привет, GigaChat!"}]
)

print(response.choices[0].message.content)

4. Использование через LiteLLM (программно)

import litellm_gigachat

# Автоматическая настройка интеграции
litellm_gigachat.setup_litellm_gigachat_integration()

# Использование через LiteLLM
import litellm

response = litellm.completion(
    model="openai/GigaChat",
    api_base="https://gigachat.devices.sberbank.ru/api/v1",
    api_key=litellm_gigachat.get_gigachat_token(),
    messages=[{"role": "user", "content": "Привет!"}]
)

print(response.choices[0].message.content)

Использование через Cline

Допустимо использовать сервер как в качестве OpenAI совместимого провайдера, так и в качестве LiteLLM провайдера. В случае использования второго варианта появляется больше доступных опций.

Настройка LiteLLM провайдера (рекомендуется):

Настройки OpenAI Compatible провайдера:

В настройках Cline укажите следующие параметры:

Основные настройки:

1. API Provider: Выберите LiteLLM или OpenAI Compatible из выпадающего списка
2. Base URL: Введите http://localhost:4000 (без слэша в конце)
3. API Key: Введите любое значение, например gigachat-key (токен управляется автоматически)
4. Model: Выберите одну из моделей:
   • gigachat - основная модель (рекомендуется для начала)
   • gigachat-pro - продвинутая модель для сложных задач
   • gigachat-max - модель с максимальными возможностями

4.3 Дополнительные настройки (опционально)

• Temperature: 0.7 (для баланса между креативностью и точностью)
• Max Tokens: 4000 (максимальная длина ответа)
• Timeout: 60 секунд

Тестирование интеграции с Cline

python test_cline_integration.py

🔧 CLI команды

После установки пакета доступна команда litellm-gigachat с полным набором команд для управления прокси-сервером:

🌐 Глобальные опции

Доступны для всех команд:

Опция	Описание
--version	Показать версию и выйти
-v, --verbose	Включить подробный вывод
-d, --debug	Включить режим отладки
--help	Показать справку

📚 Основные команды

1. start - Запуск прокси-сервера

Запускает LiteLLM прокси-сервер для GigaChat API.

litellm-gigachat start [OPTIONS]

Опции:

• --host TEXT - Хост сервера [default: 0.0.0.0]
• --port INTEGER - Порт сервера [default: 4000]
• --config TEXT - Файл конфигурации [default: config.yml]

Примеры:

# Запуск с настройками по умолчанию
litellm-gigachat start

# Запуск на localhost:8080
litellm-gigachat start --host localhost --port 8080

# Запуск с кастомным конфигом
litellm-gigachat start --config my-config.yml

# Запуск в verbose режиме
litellm-gigachat --verbose start

2. test - Тестирование подключения

Выполняет комплексное тестирование подключения к GigaChat API.

litellm-gigachat test [OPTIONS]

Опции:

• --timeout INTEGER - Таймаут тестирования в секундах [default: 30]

Выполняемые тесты:

• Проверка переменных окружения
• Тестирование TokenManager
• Проверка GigaChat API
• Тестирование LiteLLM интеграции

Примеры:

# Базовое тестирование
litellm-gigachat test

# Тестирование с увеличенным таймаутом
litellm-gigachat test --timeout 60

# Подробное тестирование
litellm-gigachat --verbose test

3. token-info - Информация о токене

Показывает детальную информацию о текущем токене доступа.

litellm-gigachat token-info [OPTIONS]

Опции:

• --format [json|table] - Формат вывода [default: table]

Отображаемая информация:

• Статус токена (активен/неактивен/истек)
• Время истечения и оставшееся время
• Область действия (scope)
• Переменные окружения (в verbose режиме)

Примеры:

# Показать информацию о токене
litellm-gigachat token-info

# Вывод в JSON формате
litellm-gigachat token-info --format json

# Подробная информация
litellm-gigachat --verbose token-info

4. refresh-token - Обновление токена

Принудительно обновляет токен доступа.

litellm-gigachat refresh-token [OPTIONS]

Опции:

• --force - Принудительно обновить токен даже если текущий еще действителен

Логика работы:

• Проверяет текущий токен
• Обновляет только если осталось < 5 минут (без --force)
• С --force обновляет принудительно

Примеры:

# Обновить токен если нужно
litellm-gigachat refresh-token

# Принудительно обновить токен
litellm-gigachat refresh-token --force

# Подробное обновление
litellm-gigachat --verbose refresh-token --force

5. examples - Интерактивные примеры

Запускает примеры использования из директории examples/.

litellm-gigachat examples [OPTIONS]

Опции:

• --list - Показать список доступных примеров
• --run TEXT - Запустить конкретный пример по имени

Режимы работы:

• Интерактивный выбор (по умолчанию)
• Список примеров (--list)
• Запуск конкретного примера (--run)

Примеры:

# Интерактивный режим выбора примеров
litellm-gigachat examples

# Показать список примеров
litellm-gigachat examples --list

# Запустить конкретный пример
litellm-gigachat examples --run basic_usage

# Подробный список примеров
litellm-gigachat --verbose examples --list

6. version - Информация о версии

Показывает версию пакета и компонентов системы.

litellm-gigachat version [OPTIONS]

Опции:

• --components - Показать версии всех компонентов
• --json-output - Вывод в формате JSON
• --check-updates - Проверить доступность обновлений

Отображаемая информация:

• Версия пакета litellm-gigachat
• Версии зависимостей (litellm, requests, etc.)
• Системная информация (Python, платформа)
• Информация об окружении

Примеры:

# Базовая информация о версии
litellm-gigachat version

# Показать все компоненты
litellm-gigachat version --components

# JSON вывод
litellm-gigachat version --json-output

# Проверить обновления
litellm-gigachat version --check-updates

# Полная информация в verbose режиме
litellm-gigachat --verbose version

🔧 Режимы работы

Обычный режим

• Минимальный вывод
• Только основные сообщения
• Подходит для автоматизации

Verbose режим (-v, --verbose)

• Дополнительная информация
• Расширенные таблицы
• Подробные логи операций

Debug режим (-d, --debug)

• Максимально подробный вывод
• Отладочная информация
• Трассировка ошибок
• Технические детали

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

# Полная диагностика в debug режиме
litellm-gigachat --debug test --timeout 60

# Запуск сервера с отладкой
litellm-gigachat --debug start --host localhost --port 8080

# Получение полной информации о системе
litellm-gigachat --verbose version --components --check-updates

# Принудительное обновление токена с подробным выводом
litellm-gigachat --verbose refresh-token --force

# Запуск примера с отладкой
litellm-gigachat --debug examples --run internal_gigachat_example

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

CLI автоматически загружает переменные из .env файла:

• GIGACHAT_AUTH_KEY - Обязательная переменная с ключом авторизации
• GIGACHAT_BASE_URL - URL базы GigaChat API (опционально)
• GIGACHAT_SCOPE - Область действия токена (опционально)
• GIGACHAT_VERIFY_SSL_CERTS - Проверка SSL сертификатов (опционально)

📋 Быстрая справка

# Показать все доступные команды
litellm-gigachat --help

# Справка по конкретной команде
litellm-gigachat start --help
litellm-gigachat test --help
litellm-gigachat token-info --help

# Проверить версию
litellm-gigachat --version

# Быстрый старт
export GIGACHAT_AUTH_KEY="ваш_ключ"
litellm-gigachat start

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

Официальные модели (с токенами)

Модель API	Описание
gigachat	Основная модель для общих задач
gigachat-pro	Продвинутая модель для сложных задач
gigachat-max	Модель с максимальными возможностями

Внутренние модели (с заголовками)

Модель API	Описание
gigachat-internal	Внутренняя установка основной модели
gigachat-pro-internal	Внутренняя установка продвинутой модели
gigachat-max-internal	Внутренняя установка модели с максимальными возможностями

Примечание: Внутренние модели доступны только при настройке переменных окружения для внутренней установки (см. раздел "Настройка внутренней установки").

🏢 Настройка внутренней установки GigaChat

Пакет поддерживает работу с внутренними установками GigaChat, которые используют заголовки аутентификации вместо токенов.

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

# Включить поддержку внутренней установки
export GIGACHAT_INTERNAL_ENABLED=true

# URL внутренней установки (обязательно)
export GIGACHAT_INTERNAL_URL=https://my-gigachat.company.com/api/v1

# Название заголовка аутентификации (по умолчанию: X-Client-Id)
export GIGACHAT_AUTH_HEADER_NAME=X-Client-Id

# Значение заголовка аутентификации (обязательно)
export GIGACHAT_AUTH_HEADER_VALUE=bddcba1a-6139-4b5f-9994-90f1b74e9109

Использование внутренних моделей

import openai

client = openai.OpenAI(
    base_url="http://localhost:4000",
    api_key="any-key"  # Заголовки управляются автоматически
)

# Использование внутренней модели
response = client.chat.completions.create(
    model="gigachat-internal",  # Автоматически добавится заголовок X-Client-Id
    messages=[{"role": "user", "content": "Привет!"}]
)

print(response.choices[0].message.content)

Тестирование внутренней установки

# Запуск примера
python examples/internal_gigachat_example.py

# Запуск тестов
python tests/test_internal_gigachat.py

# Тестирование через curl
curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer any-key" \
  -d '{
    "model": "gigachat-internal",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

Кастомизация

Вы можете настроить любые параметры:

# Пример для другой установки
export GIGACHAT_INTERNAL_ENABLED=true
export GIGACHAT_INTERNAL_URL=https://internal-ai.company.ru/v2
export GIGACHAT_AUTH_HEADER_NAME=Authorization-Key
export GIGACHAT_AUTH_HEADER_VALUE=secret-key-123

🧪 Тестирование

После установки через pip

# Проверка версии и CLI
litellm-gigachat --version
litellm-gigachat --help

# Запуск прокси-сервера (требует GIGACHAT_AUTH_KEY)
export GIGACHAT_AUTH_KEY="ваш_ключ"
litellm-gigachat

# Тестирование через curl (в другом терминале)
curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer any-key" \
  -d '{
    "model": "gigachat",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

При разработке из исходников

# Базовая функциональность
python tests/test_basic_functionality.py

# Интеграция с Cline
python tests/test_cline_integration.py

# Интерактивные примеры
python examples/basic_usage.py

# Все тесты
python -m pytest tests/

Быстрая проверка работоспособности

# test_quick.py
import openai

client = openai.OpenAI(
    base_url="http://localhost:4000",
    api_key="test-key"
)

try:
    response = client.chat.completions.create(
        model="gigachat",
        messages=[{"role": "user", "content": "Тест"}]
    )
    print("✅ Интеграция работает!")
    print(f"Ответ: {response.choices[0].message.content}")
except Exception as e:
    print(f"❌ Ошибка: {e}")

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

Ошибка "Authorization key не найден"

# Установите переменную окружения
export GIGACHAT_AUTH_KEY="ваш_ключ"

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

Проблемы с CLI командой

# Проверьте, что пакет установлен
pip list | grep litellm-gigachat

# Переустановите пакет при необходимости
pip install --upgrade litellm-gigachat

# Проверьте версию
litellm-gigachat --version

Проблемы с прокси-сервером

# Убедитесь, что прокси запущен
litellm-gigachat

# Проверьте, что порт свободен
lsof -i :4000

# Запустите на другом порту
litellm-gigachat --port 8000

Проблемы с Cline

• Убедитесь, что прокси запущен: litellm-gigachat
• Проверьте URL: http://localhost:4000
• Проверьте, что порт доступен: curl http://localhost:4000/health
• Тест интеграции: python tests/test_cline_integration.py

Проблемы с сертификатами

# Проверьте подключение к GigaChat API
curl -k https://gigachat.devices.sberbank.ru/api/v1/models

# При проблемах с SSL попробуйте переустановить certifi
pip install --upgrade certifi

Полное руководство: ❓ FAQ

🔗 Полезные ссылки

• 📚 Полная документация - подробное руководство
• ❓ FAQ - часто задаваемые вопросы
• 🔧 API Reference - примеры запросов

---

Лицензия: MIT | Поддерживаемые версии: Python 3.8+