NeuroProxy_LLM

Прокси-сервер для LLM API, позволяющий маршрутизировать запросы к различным провайдерам LLM (Mistral, NVIDIA, OpenRouter и др.) через единую локальную точку входа.

Описание

NeuroProxy_LLM предоставляет единую точку входа для взаимодействия с различными LLM API. Сервер поддерживает:

Маршрутизацию запросов к разным провайдерам
Поддержку прокси-серверов для обхода ограничений
Кастомные обработчики для модификации ответов
Логирование и мониторинг запросов
Поддержку стриминга ответов (SSE)
Автоматическую обработку ошибок подключения
Декодирование ответов в формате brotli

Установка

Требования

Python 3.7 или выше
pip (менеджер пакетов Python)

Установка зависимостей

Вариант 1: Установка через requirements.txt (рекомендуется)

# Клонируйте репозиторий (если еще не сделали этого)
git clone https://github.com/StandarterDF/NeuroProxy_LLM
cd NeuroProxy_LLM

# Установите зависимости
pip install -r requirements.txt

Вариант 2: Ручная установка

pip install aiohttp==3.9.3 brotlicffi>=1.0.9

Для Windows (если возникают проблемы с установкой)

python -m pip install --upgrade pip
python -m pip install aiohttp==3.9.3 brotlicffi>=1.0.9

Проверка установки

После установки вы можете проверить, что все работает:

python -c "import aiohttp; print('aiohttp version:', aiohttp.__version__)"

Должна вывестись версия aiohttp (3.9.3 или выше).

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

Запуск сервера

python main.py [--port PORT] [--host HOST] [--proxy PROXY]

Параметры:

--port, -p: Порт для запуска сервера (по умолчанию: 8080)
--host: Интерфейс для привязки сервера (по умолчанию: 0.0.0.0)
--proxy: HTTP прокси для подключения к API (например, http://proxy.example.com:8080)
--no-custom-handlers: Отключает все кастомные обработчики глобально

Проверка прокси: При запуске сервер автоматически проверяет работоспособность указанного прокси. Если прокси недоступен, сервер не запустится и вернет код ошибки 1.

Пример с отключением кастомных обработчиков:

python main.py --port 8081 --no-custom-handlers

Примеры:

# Запуск на порту 8081
python main.py --port 8081

# Запуск на конкретном интерфейсе
python main.py --host 127.0.0.1

# Запуск с использованием HTTP прокси
python main.py --proxy http://proxy.example.com:8080

# Комбинированный запуск
python main.py --port 8081 --host 127.0.0.1 --proxy http://proxy.example.com:8080

# Пример с неверным прокси (сервер не запустится)
python main.py --proxy http://invalid.proxy:9999

Настройка эндпоинтов

Эндпоинты настраиваются в файле endpoints.py. По умолчанию доступны следующие маршруты:

/v1 → Mistral API (https://api.mistral.ai/v1)
/v2 → NVIDIA NIM API (https://integrate.api.nvidia.com/v1)
/v3 → OpenRouter API (https://openrouter.ai/api/v1), с опциональным кастомным обработчиком для фильтрации бесплатных моделей
/v0 → Локальный API (http://127.0.0.1:1234/v1) для LM Studio, llama.cpp, Ollama и других локальных LLM

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

Open WebUI, Chatbot UI и др.

Укажите следующие параметры:

Base URL: http://localhost:8080/v1 (для Mistral)
Base URL: http://localhost:8080/v2 (для NVIDIA)
Base URL: http://localhost:8080/v3 (для OpenRouter)
Base URL: http://localhost:8080/v0 (для локального API)

API Key

API ключ передается через заголовок X-Forwarded-Token. Пример:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "X-Forwarded-Token: ваш-api-ключ" \
  -H "Content-Type: application/json" \
  -d '{"model": "mistral-tiny", "messages": [{"role": "user", "content": "Hello!"}]}'

Проверка состояния сервера

curl http://localhost:8080/health

Ответ будет содержать информацию о всех зарегистрированных эндпоинтах.

Кастомные обработчики

NeuroProxy_LLM поддерживает кастомные обработчики для модификации ответов API. Например, для фильтрации бесплатных моделей OpenRouter:

# Включение кастомного обработчика
from endpoints import enable_custom_handlers
router = create_router()
enable_custom_handlers(router)

Также можно отключить все кастомные обработчики через CLI:

python main.py --no-custom-handlers

Поддержка стриминга

Сервер автоматически определяет и обрабатывает запросы на стриминг (SSE). Для стриминговых запросов:

Поддерживается прозрачная передача данных от целевого API
Логируются метрики: длительность, количество чанков, размер данных
Автоматическое извлечение информации о токенах из SSE-сообщений

Метрики производительности

Для каждого запроса логируются следующие метрики:

Время ответа (секунды)
Размер ответа (байты)
Количество токенов (если доступно в ответе)
Токены в секунду (для стриминговых запросов)

Настройка

Добавление новых эндпоинтов

Для добавления нового эндпоинта отредактируйте файл endpoints.py:

router.add_endpoint(
    path="/v4",
    target_url="https://api.example.com/v1",
    proxy="http://proxy.example.com:8080",  # опционально
    auth_header="X-Forwarded-Token",
    description="Example API",
)

Параметры эндпоинта

path: Локальный путь (например, /v1)
target_url: Целевой URL API
proxy: URL прокси-сервера (опционально)
auth_header: Заголовок для передачи API ключа (по умолчанию: X-Forwarded-Token)
description: Описание эндпоинта
custom_handler: Пользовательская функция для обработки запроса
use_custom_handler: Флаг использования кастомного обработчика

Быстрый запуск

Для удобного запуска сервера доступны скрипты:

Windows (start.bat)

start.bat [port] [host] [proxy]

Пример:

start.bat 8080 0.0.0.0 http://proxy.example.com:8080

Unix/Linux/macOS (start.sh)

./start.sh [port] [host] [proxy]

Пример:

./start.sh 8080 0.0.0.0 http://proxy.example.com:8080

Примечание: Если скрипт не запускается из-за проблем с символами конца строки (CRLF), вы можете исправить это с помощью команды:

sed -i 's/\r$//' start.sh

CLI

Для запуска сервера напрямую используйте:

python main.py --help

Это покажет все доступные параметры командной строки.

Логирование

Сервер логирует все запросы в стандартный вывод. Формат лога:

YYYY-MM-DD HH:MM:SS  LEVEL      MESSAGE

Уровни логирования

INFO: Основные события (запуск сервера, обработка запросов)
DEBUG: Подробная информация (заголовки, тело запроса)
WARNING: Предупреждения (таймауты, ошибки декодирования)
ERROR: Критические ошибки (ошибки подключения, исключения)

Обработка ошибок и таймауты

Сервер автоматически обрабатывает следующие ошибки:

ConnectionResetError: Возвращает HTTP 502 Bad Gateway
TimeoutError: Прерывает соединение и логирует предупреждение
Ошибки декодирования brotli: Использует исходные данные

Таймауты по умолчанию

Общий таймаут: 1200 секунд
Таймаут подключения: 300 секунд
Таймаут чтения: 150 секунд

Эти значения можно изменить в файле library.py.

При временных сбоях (HTTP 429, 502–504, ConnectionResetError) сервер автоматически выполняет до 2 повторных попыток с экспоненциальной задержкой для обычных (не потоковых) запросов.

Архитектура

Сервер построен на основе следующих компонентов:

ProxyRouter: Основной класс для управления эндпоинтами
EndpointConfig: Конфигурация отдельного эндпоинта
EndpointRoute: Скомпилированный маршрут для aiohttp
library.py: Основная логика проксирования
endpoints.py: Конфигурация эндпоинтов и кастомные обработчики

Расширение функциональности

Для добавления новых функций:

Создайте новый обработчик в endpoints.py
Зарегистрируйте его с помощью router.set_custom_handler()
Добавьте новый эндпоинт с помощью router.add_endpoint()

Пример добавления нового обработчика:

async def my_custom_handler(request, config, target_url, method, body, headers, params):
    # Ваша логика обработки
    return web.json_response({"custom": "response"})

router.set_custom_handler("/v4", my_custom_handler, enabled=True)

Лицензия

MIT

Name		Name	Last commit message	Last commit date
.gitignore		.gitignore
README.md		README.md
__main__.py		__main__.py
endpoints.py		endpoints.py
library.py		library.py
main.py		main.py
requirements.txt		requirements.txt
start.bat		start.bat
start.sh		start.sh

Latest commit

History

Folders and files

Repository files navigation