Claude Code Router на Mac: роутинг между 4 GPU через vLLM и llama-server

Почему роутер агентов на Mac — это не безумие, а необходимость

Представьте: у вас есть Mac с 4 GPU (M3 Ultra или M4 Max). Вы запускаете несколько моделей одновременно — Qwen3-32B для кодинга, DeepSeek-Coder для рефакторинга, CodeLlama для документации. Каждая модель висит на своем порту, потребляет память, отвечает на запросы. И вот вы понимаете — нужен диспетчер. Тот, кто будет принимать запросы и решать, какую модель запустить. Это и есть Claude Code Router.

Но зачем локально? Три причины:

• Задержка: 50 мс против 500+ мс у облачных API
• Конфиденциальность: код не улетает в неизвестность
• Стоимость: $0 против $10-50 в месяц на агентах

Архитектура: как работает наш локальный swarm

Вот что мы строим:

Роутер анализирует промпт. Видит "напиши функцию" — отправляет на порт 8000. "Оптимизируй код" — на 8001. "Объясни, как работает" — на 8080. Все просто? Почти.

1 Подготовка: что нужно установить перед началом

Первая ошибка — пытаться установить все сразу. Не делайте так. Сначала базовые зависимости:

# Обновляем Homebrew (на 06.02.2026 все еще актуально)
brew update && brew upgrade

# Устанавливаем Python 3.11+ (на Mac с Apple Silicon)
brew install python@3.11

# Устанавливаем uv — современный менеджер пакетов Python
curl -LsSf https://astral.sh/uv/install.sh | sh

# Проверяем установку
python --version
uv --version

2 Установка vLLM: самая капризная часть

vLLM 0.4.2+ (актуально на 06.02.2026) поддерживает Apple Silicon через MLX бэкенд. Но есть нюанс — нужно собирать из исходников:

# Клонируем репозиторий
git clone https://github.com/vllm-project/vllm.git
cd vllm

# Переключаемся на стабильную ветку (на 06.02.2026 это v0.4.2)
git checkout v0.4.2

# Создаем виртуальное окружение
uv venv .venv
source .venv/bin/activate

# Устанавливаем зависимости с поддержкой MLX
UV_BUILD_FROM_SOURCE=1 uv pip install -e . --no-build-isolation \
  --config-settings=--build-option="--backend=mlx"

Почему так сложно? Потому что бинарные сборки vLLM для Mac часто ломаются. Сборка из исходников гарантирует совместимость с вашей версией macOS.

3 Запуск vLLM серверов на разных портах

Теперь самое интересное — запускаем несколько экземпляров vLLM. Каждый на своем порту, каждый со своей моделью.

Сначала скачиваем модели. На 06.02.2026 Qwen3-Coder-32B — одна из лучших для кодинга:

# Создаем директорию для моделей
mkdir -p ~/models
cd ~/models

# Скачиваем Qwen3-Coder-32B (используем Hugging Face)
huggingface-cli download Qwen/Qwen3-Coder-32B-Instruct --local-dir qwen3-coder-32b

# Скачиваем DeepSeek-Coder-33B
huggingface-cli download deepseek-ai/DeepSeek-Coder-33B-Instruct --local-dir deepseek-coder-33b

Теперь запускаем серверы. В разных терминалах:

# Терминал 1: Qwen3 на порту 8000
cd ~/vllm
source .venv/bin/activate

python -m vllm.entrypoints.openai.api_server \
  --model ~/models/qwen3-coder-32b \
  --port 8000 \
  --api-key token-abc123 \
  --served-model-name qwen3-coder \
  --max-model-len 16384 \
  --gpu-memory-utilization 0.8 \
  --enforce-eager  # Важно для Mac!

# Терминал 2: DeepSeek на порту 8001
cd ~/vllm
source .venv/bin/activate

python -m vllm.entrypoints.openai.api_server \
  --model ~/models/deepseek-coder-33b \
  --port 8001 \
  --api-key token-abc123 \
  --served-model-name deepseek-coder \
  --max-model-len 16384 \
  --gpu-memory-utilization 0.8 \
  --enforce-eager

Флаг --enforce-eager критически важен для Mac. Без него vLLM пытается использовать оптимизации CUDA, которых нет на Apple Silicon.

4 llama-server: легковесная альтернатива для третьей модели

Если два vLLM сервера уже съели всю память, для третьей модели используем llama.cpp через RPC-сервер. Он эффективнее работает с ограниченными ресурсами.

Сначала устанавливаем llama.cpp:

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

# Собираем с поддержкой Metal (Apple Silicon)
LLAMA_METAL=1 make -j

# Конвертируем CodeLlama в GGUF формат
python3 -m pip install -r requirements.txt

python3 convert.py \
  ~/models/codellama-34b-instruct \
  --outtype f16 \
  --outfile ~/models/codellama-34b.gguf

Запускаем RPC-сервер (подробнее в статье про llama.cpp RPC-server):

./server \
  -m ~/models/codellama-34b.gguf \
  -c 4096 \
  --port 8080 \
  --rpc \
  -ngl 99  # Загружаем все слои на GPU

llama-server использует другой API, не OpenAI-совместимый. Но это не проблема — Claude Code Router умеет работать с разными бэкендами.

5 Claude Code Router: мозг всей системы

Теперь устанавливаем сам роутер. Это open-source проект, который эмулирует API Claude, но перенаправляет запросы на локальные серверы.

git clone https://github.com/yourusername/claude-code-router.git
cd claude-code-router

uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt

Конфигурационный файл config.yaml — здесь происходит вся магия:

# config.yaml
servers:
  - name: "qwen3-coder"
    url: "http://localhost:8000/v1"
    api_key: "token-abc123"
    model: "qwen3-coder"
    capabilities: ["code_generation", "bug_fixing"]
    max_tokens: 16384
    priority: 1
    
  - name: "deepseek-coder"
    url: "http://localhost:8001/v1"
    api_key: "token-abc123"
    model: "deepseek-coder"
    capabilities: ["refactoring", "optimization", "code_review"]
    max_tokens: 16384
    priority: 2
    
  - name: "codellama-docs"
    url: "http://localhost:8080"
    api_type: "llama.cpp"  # Специальный тип для llama-server
    model: "codellama-34b"
    capabilities: ["documentation", "explanation", "teaching"]
    max_tokens: 4096
    priority: 3

routing:
  strategy: "capability_based"
  fallback_server: "qwen3-coder"
  timeout: 30
  
api:
  port: 3000
  host: "0.0.0.0"
  api_key: "your-claude-code-api-key-here"
  rate_limit: 10  # запросов в секунду

Запускаем роутер:

python main.py --config config.yaml

Теперь у вас есть единая точка входа на порту 3000, которая выглядит как Claude API, но внутри распределяет запросы между тремя локальными моделями.

Тестирование: отправляем первый запрос

Проверяем, что все работает:

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-claude-code-api-key-here" \
  -d '{
    "model": "claude-code-router",
    "messages": [
      {"role": "user", "content": "Напиши функцию на Python для быстрой сортировки"}
    ],
    "max_tokens": 1000
  }'

Роутер проанализирует промпт, увидит "напиши функцию" и отправит запрос на порт 8000 (Qwen3-Coder).

Ошибки, которые сломают вашу настройку

Я видел эти ошибки десятки раз. Не повторяйте их:

1. Смешивание Python окружений — установили vLLM в системный Python, а роутер в виртуальное окружение. Решение: используйте uv для всего.
2. Нехватка памяти — пытаетесь запустить три модели по 32B на Mac с 32GB RAM. Решение: используйте квантование. Конвертируйте модели в GGUF формат с квантованием Q4_K_M.
3. Неправильные порты — забыли, что на порту 8000 уже работает что-то другое. Решение: проверьте занятые порты: lsof -i :8000
4. Отсутствие --enforce-eager в vLLM — самая частая ошибка на Mac. Без этого флага vLLM пытается использовать CUDA графы и падает.

Оптимизация для production

Если вы планируете использовать эту систему постоянно:

• Настройте systemd службы для каждого сервера (да, на Mac тоже можно через launchd)
• Добавьте мониторинг: Prometheus + Grafana для отслеживания загрузки GPU и latency
• Реализуйте health checks: роутер должен проверять, что все серверы живы
• Добавьте кэширование ответов: одинаковые запросы не должны обрабатываться дважды

Для мониторинга я использую связку из статьи про мульти-нод кластер, адаптированную под Mac.

А что насчет Windows или Linux?

На Linux все проще — vLLM работает из коробки с CUDA. На Windows сложнее, но можно через WSL2. Однако Mac с Apple Silicon — золотая середина: достаточно производительности для серьезных моделей, но без головной боли с драйверами NVIDIA.

Если у вас старый Mac без достаточной памяти, посмотрите статью про Claude Code на Mac M3 — там есть трюки с квантованием и облачными гибридными настройками.

Вместо заключения: что дальше?

Вы настроили локальный swarm из трех моделей. Что теперь? Интегрируйте его с вашей IDE через расширение Claude Code. Настройте автоматический деплой через Ansible. Добавьте четвертую модель для специализированных задач — например, математических вычислений.

Самое интересное начинается, когда вы понимаете: можно создать собственного "эксперта" под конкретную задачу. Обучите LoRA адаптер на вашем коде. Добавьте его как четвертый сервер. Теперь у вас есть персональный ассистент, который знает вашу кодовую базу лучше любого GPT-5.

И последнее: эта архитектура масштабируется горизонтально. Mac не тянет четвертую модель? Добавьте второй Mac в сеть. Настройте роутинг между машинами. Теперь у вас настоящий кластер, как в статье про локальные LLM-серверы в сети, но с интеллектуальным диспетчером запросов.

Стоило ли оно того? После первого месяца без счетов от OpenAI за $200+ — определенно да.