FreeLLMAPI

Что такое FreeLLMAPI?

FreeLLMAPI — OpenAI-совместимый прокси-сервер, который объединяет бесплатный доступ от нескольких LLM-провайдеров за единым API-интерфейсом. Вместо настройки отдельных SDK и обработки разных лимитов для каждого провайдера вы указываете OpenAI-совместимому клиенту адрес прокси и отправляете запросы на один эндпоинт.

Проект предназначен для личных экспериментов. Он агрегирует ключи от ~14 провайдеров (через адаптеры провайдеров), направляет каждый запрос на доступную модель и выполняет автоматический failover при rate-limit или ошибках провайдера.

Ключевые возможности

• OpenAI-совместимые эндпоинты: Реализует POST /v1/chat/completions и GET /v1/models, чтобы OpenAI SDK и другие OpenAI-совместимые клиенты работали при смене base_url.
• Поддержка стриминга: При stream: true сервер возвращает ответы через Server-Sent Events (SSE); иначе — стандартный JSON-ответ.
• Проксирование tool calling: Поддерживает OpenAI-стиль tools / tool_choice, перенаправляет tool_calls ассистента и последующие сообщения роли tool через адаптеры провайдеров.
• Автоматический failover и повторы: При 429, 5xx или таймауте от провайдера роутер помечает ключ как временно недоступный и повторяет запрос с следующим провайдером в цепочке fallback (до 20 попыток).
• Учет использования по ключам относительно лимитов провайдера: Отслеживает RPM, RPD, TPM и TPD для (platform, model, key) и выбирает ключи ниже бесплатных лимитов.
• «Липкий» роутинг для многоходовых бесед: Держит разговор на той же модели 30 минут, чтобы минимизировать переключения посреди беседы.
• Шифрование ключей: Шифрует ключи провайдеров с AES-256-GCM перед хранением в SQLite; расшифровка в памяти перед использованием.
• Единая аутентификация прокси: Клиент аутентифицируется у прокси одним bearer-токеном freellmapi-..., без использования ключей провайдеров.
• Проверки здоровья и админ-панель: Периодические пробы помечают ключи как healthy/rate-limited/invalid/error; админ-панель (React + Vite) позволяет управлять ключами, менять приоритет fallback, просматривать аналитику и запускать playground для промптов.

Как использовать FreeLLMAPI

1. Установите зависимости: Используйте Node.js 20+ и npm.
2. Клонируйте и установите:
   • git clone https://github.com/tashfeenahmed/freellmapi.git
   • cd freellmapi
   • npm install
3. Настройте окружение:
   • Скопируйте пример: cp .env.example .env
   • Сгенерируйте ENCRYPTION_KEY и добавьте в .env (репозиторий предоставляет команду для случайного 32-байтного hex-ключа).
4. Запустите прокси: Запустите сервер по инструкции в quick start / README репозитория (страница содержит шаги настройки, документация репозитория — точную команду запуска).
5. Настройте OpenAI-совместимый клиент:
   • Укажите base_url на локальный сервер FreeLLMAPI.
   • Аутентифицируйтесь bearer-токеном прокси (freellmapi-...) и вызывайте POST /v1/chat/completions (опционально с stream: true).

Сценарии использования

• Тестирование чата в одном коде по провайдерам: Направьте существующее OpenAI-совместимое приложение (или библиотеку) на прокси, чтобы экспериментировать с моделями без отдельных SDK провайдеров.
• Снижение ручных сбоев по лимитам: Используйте автоfailover, чтобы пропускать провайдеры с 429/5xx/таймаутами и продолжать запрос на следующей модели в порядке fallback.
• Чат-флоу с инструментами: Запускайте OpenAI-стиль tool calling, где tool_calls и сообщения с результатами инструментов маршрутизируются через прокси.
• Стабильность длинных бесед: Держите сессии на той же модели во время активности (30 минут sticky-сессий) с fallback при недоступности провайдера.
• Локальные эксперименты с шифрованием ключей: Централизуйте ключи провайдеров в прокси с шифрованием на диске, чтобы клиентам не нужно было хранить ключи провайдеров.

Часто задаваемые вопросы

• Поддерживает ли FreeLLMAPI полный OpenAI API? Нет. Фокус на chat completions и списке моделей (/v1/chat/completions, /v1/models). Embeddings, изображения, аудио/речь, мультимодальные входы не поддерживаются, как и legacy /v1/completions, moderation и множественные completions.

• Как FreeLLMAPI обрабатывает лимиты? Отслеживает счетчики по ключам (RPM/RPD/TPM/TPD) и выбирает ключи ниже лимитов. При 429 (или 5xx/таймаутах) от провайдера роутер повторяет с следующим в цепочке fallback.

• Будет ли работать стриминг с моим клиентом? Да. Прокси поддерживает стриминг через SSE при stream: true для чат-эндпоинта.

• Можно ли использовать существующие OpenAI-совместимые библиотеки? Прокси предназначен для работы с официальными OpenAI SDK и другими OpenAI-совместимыми клиентами при указании base_url прокси.

• Это для продакшена? Репозиторий явно указывает: «только для личных экспериментов».

Альтернативы

• Использовать одного провайдера напрямую: Многие сервисы предлагают свой API с последовательной семантикой, но вы не получите агрегацию нескольких провайдеров, автоматический failover или stacking бесплатных тарифов в одном endpoint.
• Создать собственный роутер/слой fallback: Кастомный прокси может реализовать failover и ротацию ключей, но вам придется самостоятельно управлять SDK провайдеров, лимитами и обработкой ошибок.
• Использовать фреймворк оркестрации с поддержкой нескольких LLM-бэкендов: Некоторые инструменты маршрутизируют запросы по разным провайдерам моделей, но workflow может отличаться (и может не предоставлять OpenAI-совместимое поведение прокси /v1/chat/completions, описанное здесь).
• Ручное переключение ключей и моделей: Вы можете выбирать провайдеров вручную в приложении, но потеряете автоматический retry/failover и учет лимитов по ключам, которые предоставляет FreeLLMAPI.