ypollak2/llm-router

pip install llm-routing   # PyPI name is llm-routing; the CLI command is llm-router

• Зачем это устанавливают

• 8-е место в RouterArena

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

• Пример маршрутизации

• Совместимость

• Как это работает

• Возможности

• CLI

• Провайдеры

• Политики маршрутизации

• MCP-инструменты

• Экономия: как это работает

• Доверие, конфиденциальность и локальный дизайн

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

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

• Для предприятий

• Участие в разработке

Зачем это устанавливают

Инструменты ИИ-кодинга по умолчанию отправляют слишком много промптов на премиальные модели.

Это означает:

• Вы тратите платные токены на простые вопросы

• Вы быстрее, чем нужно, расходуете квоту Claude, Gemini или OpenAI

• Вы прекращаете работу, когда один провайдер ограничивает запросы или недоступен

llm-router находится между вашим инструментом кодинга и провайдерами моделей. Он классифицирует каждый промпт, сначала пробует самую дешёвую подходящую модель и автоматически переключается на запасные варианты при необходимости.

Ваш рабочий процесс остаётся прежним. Роутер меняет выбор модели под капотом.

Related MCP server: MCP AI Router

8-е место в RouterArena

llm-router прошёл независимое бенчмарк-тестирование и занял 8-е место в RouterArena — сообщественном рейтинге, который оценивает роутеры моделей по точности маршрутизации, задержке, экономической эффективности и надёжности запасных вариантов.

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

1. Установка

pip install llm-routing
llm-router install

Имя пакета: llm-routing на PyPI. Команда CLI: llm-router.

2. Добавьте провайдеров (необязательно)

export OPENAI_API_KEY="sk-..."          # GPT-4o, o3
export GEMINI_API_KEY="AIza..."         # Gemini Flash/Pro (free tier available)
export OLLAMA_BASE_URL="http://localhost:11434"  # Local models (free)
export OPENROUTER_API_KEY="sk-or-v1-…"  # 343 OpenRouter models (qwen, deepseek, grok, …)

Работает с нулевым количеством API-ключей на подписках Claude Code Pro/Max — маршрутизация использует MCP-инструменты, которые вызывают внешние модели только когда это выгодно. Добавьте OPENROUTER_API_KEY, чтобы разблокировать пул рабочих моделей с открытыми весами, используемый политикой cost_aggressive.

3. Проверка

llm-router health            # Check provider connectivity

Если вы уже используете Claude Code, Codex или Gemini CLI, сохраните свой текущий рабочий процесс и позвольте llm-router выбирать модели под капотом.

Пример маршрутизации

Точная цепочка зависит от настроенных провайдеров, бюджетного профиля и политики маршрутизации.

Совместимость

• Полная автоматическая маршрутизация означает, что хуки перехватывают промпты и маршрутизируют их автоматически без изменения рабочего процесса.

• Ручные MCP-инструменты означают, что маршрутизация доступна по запросу через такие инструменты, как llm_query.

llm-router install                    # Claude Code (default)
llm-router install --host codex       # Codex CLI
llm-router install --host gemini-cli  # Gemini CLI
llm-router install --host vscode      # VS Code
llm-router install --host cursor      # Cursor

Подробности по каждому хосту см. в guide/HOST_SUPPORT_MATRIX.md.

Берегите свою 5-часовую квоту Claude Code

enforce: smart + mode: zero_claude заставляет промпты либо выполняться внешне, либо останавливаться до запуска нативного Claude — см. guide/GETTING_STARTED.md.

Как это работает

User prompt
    │
    ▼
┌──────────────────────┐
│ Complexity Classifier │  ← Heuristic (free, instant) or Ollama/Flash ($0.0001)
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Free-First Router   │  ← Tries cheapest model first, walks up the chain
│                      │
│  Ollama (free)       │
│  → Codex (prepaid)   │
│  → Gemini Flash      │
│  → GPT-4o / Claude   │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Guards (parallel)   │  ← Circuit breaker, budget pressure, quality check
└──────────┬───────────┘
           │
           ▼
      Response + cost logged to local SQLite

Классификация бесплатна для многих задач (регулярные выражения-эвристики распознают ~70%) или почти бесплатна для неоднозначных промптов при использовании локального Ollama или Gemini Flash.

Возможности

Помимо «отправлять дешёвые промпты на дешёвые модели»:

• Секреты никогда не покидают вашу машину. Промпт, содержащий API-ключ, токен или приватный ключ, направляется только на локальные модели — с отказом по умолчанию, поэтому он не может попасть к внешнему провайдеру.

• Маршрутизация подписки с инвертированной стоимостью. Сначала бесплатные/локальные модели для простых и умеренных промптов, затем ваше платное место для сложных, причём место понижается, когда его квота перегружена. Включите с помощью LLM_ROUTER_SUBSCRIPTION_PROVIDER.

• Автоматический запасной вариант с автоматическими выключателями. Провайдер, который выходит из строя или ограничивает запросы, пропускается, а не ретраится до бесконечности.

• Вы видите, как это работает. Строка состояния, заголовок терминала и уведомление ОС показывают последнюю маршрутизированную модель, экономию и состояние здоровья — для хостов без встроенной строки состояния.

• Итоговая сводка по сессии. Экономия относительно базового уровня, распределение по уровням, стоимость по провайдерам, задержка p50/p95/p99 и основные маршруты.

• Медиа и конвейеры тоже. llm_image / llm_video / llm_audio, а также llm_orchestrate для многошаговых исследований.

CLI

llm-router install      # wire up your host (Claude Code by default)
llm-router health       # provider connectivity
llm-router status       # savings + quota at a glance
llm-router doctor       # diagnose a broken setup

Полная справка по командам: guide/GETTING_STARTED.md

Провайдеры

20+ провайдеров, бесплатные в приоритете. Ollama (локальный, бесплатный) возглавляет цепочку; OpenRouter (343 модели за одним ключом) — самое большое единичное преимущество; Gemini и Groq имеют пригодные бесплатные тарифы. Anthropic работает через вашу существующую подписку Claude — API-ключ не нужен.

Каждый провайдер, его модели, ценовой уровень и переменная окружения: guide/PROVIDERS.md

Политики маршрутизации

Политика определяет, насколько активно роутер уводит запросы от вашей премиальной модели — от conservative (экономия 10–15%) через balanced (по умолчанию, 35–45%) до cost_aggressive (70–85%, требуется OPENROUTER_API_KEY).

llm-router policy set cost_aggressive

Все шесть политик, пороговые значения и YAML-схема: guide/POLICIES.md

MCP-инструменты

60 инструментов для маршрутизации, анализа, кода, медиа, бюджета и диагностики — доступны любому MCP-хосту. Поверхность по умолчанию consolidated показывает 11 основных инструментов; установите LLM_ROUTER_SLIM=full, чтобы получить все 60.

Каждый инструмент с его сигнатурой: guide/TOOLS.md

Экономия: как это работает

Экономия рассчитывается путём сравнения фактических расходов с базовым сценарием, в котором каждая задача направляется на Claude Sonnet/Opus.

Методология:

1. Каждая маршрутизированная задача записывает: использованную модель, потреблённые токены, расчётную стоимость

2. Базовая стоимость вычисляется так, как если бы те же токены обрабатывались самой дорогой моделью в цепочке

3. Экономия = (базовая - фактическая) / базовая

Допущения и ограничения:

• Базовый сценарий предполагает, что вы использовали бы Opus/Sonnet для всего (худший случай)

• Оценка токенов использует приближение len(text) / 4, а не точные подсчёты токенизатора

• Данные о стоимости взяты из таблиц цен LiteLLM (могут отставать от изменений цен провайдеров)

• Экономия значительно варьируется в зависимости от рабочей нагрузки — сессии с большим объёмом кода направляют больше запросов на дешёвые модели

• Сам роутер добавляет небольшие накладные расходы (классификация стоит ~$0.0001 за неоднозначную задачу)

Наблюдаемый диапазон: экономия 35–80% в зависимости от политики и состава задач. Цифра «87%» в некоторых документах представляет собой пик для одного пользователя за конкретный период разработки, а не гарантированный результат.

Доверие, конфиденциальность и локальный дизайн

llm-router работает полностью на вашей машине. Никакого облачного прокси, никакой телеметрии, аккаунт не требуется.

Что мы делаем:

• Удаляем ключи API из структурированных журналов

• Обнаруживаем взаимоблокировки хуков до установки

• Храним все данные локально в ~/.llm-router/

• Соблюдаем лимиты запросов и условия использования провайдеров

Что вам стоит знать:

• Промпты отправляются провайдеру, которого выберет маршрутизатор, — ознакомьтесь с политикой конфиденциальности вашего провайдера

• Журналы использования (SQLite) не шифруются на диске — при необходимости используйте полное шифрование диска

• Маршрутизатор не может предотвратить джейлбрейки моделей или внедрение промптов на уровне провайдера

См. SECURITY.md о политике ответственного раскрытия уязвимостей.

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

Всё настраивается переменными окружения — для запуска не требуется файл конфигурации:

export OPENROUTER_API_KEY="sk-or-v1-..."          # biggest single unlock
export OLLAMA_BASE_URL="http://localhost:11434"   # local, free
export LLM_ROUTER_POLICY="cost_aggressive"        # routing policy
export LLM_ROUTER_ENFORCE="smart"                 # off | advise | smart | hard

Полный справочник, схема файла конфигурации и переопределения для каждого хоста: guide/GETTING_STARTED.md

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

Полный индекс: guide/README.md

Корпоративное использование

llm-router создан для отдельных разработчиков и небольших команд: локальная экономия средств, нулевые операционные затраты и никакого размещения у хостинга. Если вам нужны контроль политик для всей команды, экспорт аудита, SSO или бюджеты по организациям, для этого существует Chuzom.

Вклад в проект

Вклад приветствуется. Полные правила см. в CONTRIBUTING.md.

git clone https://github.com/ypollak2/llm-router.git
cd llm-router
uv sync --extra dev
uv run pytest tests/ -q         # Run tests (1900+)
uv run ruff check src/ tests/   # Lint

-|-----------| | llm-routing | Текущий пакет PyPI (pip install llm-routing) | | llm-router | Команда CLI и имя репозитория GitHub | | claude-code-llm-router | Устаревший пакет (перенаправляет на llm-routing) |