Як я перестав переписувати код при кожній зміні LLM-провайдера. Архітектура, що економить нерви

💡 Усі статті, обговорення, новини про AI — в одному місці. Приєднуйтесь до AI спільноти!

Знаєте це відчуття? П’ятниця, вечір. Ви щойно завершили міграцію кодової бази з GPT-4 на Claude — переписали API-виклики, полагодили парсинг відповідей, оновили логіку стримінгу. Тиждень був пеклом, але фух — тести зелені.

І тут Google випускає новий Gemini з бенчмарками, від яких решта моделей виглядає як калькулятор із 1995 року.

Так. Я через це проходив. Не раз.

Після третьої міграції за пів року я сів і подумав: навіщо я переписую інтеграційний код, якщо єдине, що змінюється, — це HTTP-ендпоінт? Запит — JSON. Відповідь — JSON. Усі моделі приймають повідомлення на вхід і віддають текст на виході. Але дідька лисого. Чому зміна провайдера відчувається як заміна двигуна на ходу?

Саме так я натрапив на LM-Proxy — і це змінило мій підхід до архітектури LLM-застосунків. Розповім, що це таке, чому це важливо і як налаштувати все за 5 хвилин.

Чому ваш інтеграційний код — це бомба сповільненої дії

Давайте чесно глянемо на еволюцію типового LLM-проєкту.

Місяць 1: просто візьмемо OpenAI. Один провайдер, один SDK, усе просто.

Місяць 3: для задачі сумаризації Claude насправді працює краще. Давайте додамо Anthropic. Тепер у вас два різні SDK, два потоки автентифікації, два формати відповідей і один if/else, який переслідує вас уві сні.

Місяць 5: Gemini Flash набагато дешевший для простих запитів. Давайте перенаправимо туди нескладні задачі. Логіка маршрутизації тепер розповзлася по трьох файлах, обробка помилок для кожного провайдера — своя, а новий розробник вбив два дні лише на те, щоб розібратися, який API-ключ куди підставляти.

Місяць 7: хтось питає: «А можемо підняти локальну модель для чутливих даних?» — і ви починаєте оновлювати LinkedIn.

Корінь зла простий: кожен LLM-провайдер вигадав власний формат API, хоча всі вони роблять по суті одне й те саме. Формат OpenAI став де-факто стандартом — але Anthropic, Google та інші прийшли зі своїми примхами, схемами автентифікації та протоколами стримінгу.

Те, що нам потрібно — це універсальний перекладач. Reverse proxy, який зовні прикидається старим добрим OpenAI API, а всередині мовчки робить брудну роботу з перекладу запитів на «діалекти» інших провайдерів.

Рішення: LM-Proxy за одну хвилину

LM-Proxy — легковісний HTTP-проксі/шлюз на Python і FastAPI, сумісний з OpenAI API.

Його філософія проста:

Ваш застосунок спілкується з одним API. LM-Proxy спілкується з усіма іншими.

OpenAI, Anthropic, Google (AI Studio / Vertex AI), локальні PyTorch-моделі, Ollama, LM-Studio чи vLLM — все це стає доступним через єдиний ендпоінт /v1/chat/completions.

«Окей, черговий LLM-gateway», — скажете ви. Справедливо. Але дайте я поясню, чому саме цей вартий уваги і чим він відрізняється від «ентерпрайз-монстрів».

Чому це працює

1. Радикальний мінімалізм

Жодного Kubernetes. Жодного Redis. Ніякої архітектури з 47 мікросервісів.

pip install lm-proxy
lm-proxy

Один Python-пакет. Один TOML-конфіг. Одна команда. Запускається на VPS за $2/місяць у Docker-контейнері або вбудовується напряму в Python-застосунок як FastAPI-суб-застосунок. Ядро навмисно компактне — жодного зайвого баласту для задачі, яка його не потребує.

2. Конфігурація, для якої не потрібна наукова ступінь

Ось повний робочий конфіг, який маршрутизує GPT-запити до OpenAI, Claude — до Anthropic, а Gemini — до Google:

host = "0.0.0.0"
port = 8000

# Підключення до провайдерів (upstream)
[connections.openai]
api_type = "open_ai"
api_base = "https://api.openai.com/v1/"
api_key = "env:OPENAI_API_KEY"

[connections.anthropic]
api_type = "anthropic"
api_key = "env:ANTHROPIC_API_KEY"

[connections.google]
api_type = "google_ai_studio"
api_key = "env:GOOGLE_API_KEY"

# Магія маршрутизації
[routing]
"gpt*" = "openai.*"
"claude*" = "anthropic.*"
"gemini*" = "google.*"
"*" = "openai.gpt-4o-mini"        # fallback

# Групи доступу
[groups.default]
api_keys = ["my-team-api-key-1", "my-team-api-key-2"]

Прочитайте зверху донизу. Ви зрозуміли його за 30 секунд, правда? Чистий TOML з очевидною семантикою — ніяких кошмарів з відступами в YAML і JSON-простирадл на 200 рядків. До речі, YAML, JSON і Python-формати конфігурації теж підтримуються.

Префікс env: підтягує секрети зі змінних оточення або .env-файлів — ключі ніколи не потрапляють у git.

3. Маршрутизація за патернами (кілер-фіча)

Секція [routing] — це місце, де відбувається магія. Ключі — це glob-патерни, що зіставляються з назвою моделі, яку надсилає клієнт. Суфікс .* означає «передати назву моделі провайдеру як є». Тобто коли клієнт запитує claude-sonnet-4-5-20250929, LM-Proxy перенаправляє саме цю назву до API Anthropic. Жодних таблиць відповідності, жодних файлів із мапінгом моделей — воно просто працює.

Можна й прив’язати патерн до конкретної моделі:

[routing]
"custom*" = "local.llama-7b"        # Будь-який "custom*" запит → локальна Llama
"gpt-3.5*" = "openai.gpt-3.5-turbo" # Прив'язка до конкретної моделі
"*" = "openai.gpt-4o-mini"          # Все інше → дешевий fallback

Це означає, що клієнтський код ніколи не змінюється. Хочете спробувати нову модель — оновіть один рядок у конфігу. A/B-тест двох провайдерів — додайте правило. Вивести модель з обігу — перенаправте патерн. Нуль змін у коді.

4. Віртуальні ключі та контроль доступу

Ця фіча перетворює LM-Proxy з іграшки на production-інструмент. Проксі оперує двома рівнями ключів: віртуальні (клієнтські, для автентифікації з проксі) та провайдерські (справжні ключі від OpenAI, Anthropic тощо, які залишаються прихованими).

# Преміум-користувачі мають доступ до всього
[groups.premium]
api_keys = ["premium-key-1", "premium-key-2"]
allowed_connections = "*"

# Безкоштовний тариф — лише OpenAI
[groups.free]
api_keys = ["free-key-1"]
allowed_connections = "openai"

# Внутрішні інструменти — лише локальні моделі
[groups.internal]
api_keys = ["internal-key-1"]
allowed_connections = "local"

Upstream API-ключі ніколи не потрапляють до клієнтів. Можна проводити їх ротацію, не чіпаючи жодної клієнтської конфігурації. Можна створювати гранулярні рівні доступу — преміум-користувачі отримують Claude Opus, безкоштовні — GPT-4o-mini, внутрішні інструменти працюють на локальних моделях. Усе управляється одним конфіг-файлом.

Підтримується навіть зовнішня автентифікація — валідація віртуальних API-ключів через Keycloak, Auth0 або будь-який OIDC-провайдер:

[api_key_check]
class = "lm_proxy.api_key_check.CheckAPIKeyWithRequest"
method = "POST"
url = "http://keycloak:8080/realms/master/protocol/openid-connect/userinfo"
response_as_user_info = true
use_cache = true
cache_ttl = 60

[api_key_check.headers]
Authorization = "Bearer {api_key}"

Ваші наявні OAuth-токени автоматично стають ключами до LLM API. А якщо вбудовані валідатори не підходять, можна написати кастомний — просто Python-функція, яка приймає рядок API-ключа і повертає назву групи.

5. Повноцінна підтримка стримінгу

Cтримінг працює з коробки. Клієнти отримують відповіді в реальному часі, токен за токеном, незалежно від того, хто і в якому форматі їх генерує.

6. Бібліотека, а не лише сервер

LM-Proxy — це не тільки окремий сервіс, але й Python-пакет, який можна імпортувати. Оскільки він побудований на FastAPI, його можна вбудувати у наявний застосунок, використовувати в інтеграційних тестах або компонувати з іншими ASGI-middleware. Не потрібно запускати окремий процес, якщо ви цього не хочете.

Реальний сценарій: 5 хвилин до production

Розглянемо конкретну ситуацію. Ви розробляєте SaaS-продукт, який використовує LLM. Хочете GPT-4o для складних міркувань, Claude Sonnet для роботи з великими документами та Gemini Flash для дешевої класифікації.

Крок 1: Встановлення

pip install lm-proxy

Крок 2: Створити .env

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AI...

Крок 3: Створити config.toml

host = "0.0.0.0"
port = 8000

[connections.openai]
api_type = "open_ai"
api_base = "https://api.openai.com/v1/"
api_key = "env:OPENAI_API_KEY"

[connections.anthropic]
api_type = "anthropic"
api_key = "env:ANTHROPIC_API_KEY"

[connections.google]
api_type = "google_ai_studio"
api_key = "env:GOOGLE_API_KEY"

[routing]
"gpt*" = "openai.*"
"claude*" = "anthropic.*"
"gemini*" = "google.*"
"*" = "google.gemini-2.0-flash"

[groups.backend]
api_keys = ["backend-service-key"]
allowed_connections = "*"

[groups.frontend]
api_keys = ["frontend-widget-key"]
allowed_connections = "google"     # лише дешеві моделі

Крок 4: Запуск

lm-proxy

Крок 5: Використання з вашого застосунку

from openai import OpenAI

# Зверніть увагу: ми стукаємо на наш проксі
client = OpenAI(
    api_key="backend-service-key",
    base_url="http://localhost:8000/v1"
)

# Складні міркування → GPT-4o
response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "Проаналізуй цей контракт..."}]
)

# Великий документ → Claude
response = client.chat.completions.create(
    model="claude-opus-4-6",
    messages=[{"role": "user", "content": "Підсумуй цей 100-сторінковий звіт..."}]
)

# Швидка класифікація → Gemini Flash (дешево)
response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Це лист — спам? ..."}]
)

Один клієнт, один base URL, три провайдери. А завтра, коли вийде чергова модель, на 50% дешевша, ви зміните один рядок у config.toml і перезапустите сервер. Код застосунку залишиться незмінним.

LM-Proxy vs LiteLLM: Давид і Голіаф

У коментарях обов’язково запитають: «А чим це краще за LiteLLM?»

Скажемо чесно — LiteLLM — це 400-кілограмова горила в цій ніші. Понад 33 000 зірок на GitHub, підтримка 2000+ LLM, лістинг на AWS Marketplace, функціонал на кшталт дашбордів для трекінгу витрат, guardrails, кешування, rate limiting, SSO та інтеграції з MCP — це повновісна enterprise-платформа. Вона також пропонує як Python SDK, так і HTTP-проксі-сервер, тож архітектурно покриває схожу територію.

То чому ж обирати LM-Proxy?

З тієї ж причини, з якої ви обираєте Flask замість Django або SQLite замість PostgreSQL. Не кожній задачі потрібен «повний фарш» ентерпрайз-стеку.

LM-Proxy:

• Філософія: мінімальне ядро, розширюйте за потреби.
• Налаштування: pip install lm-proxy + один TOML-файл.
• Залежності: FastAPI + MicroCore (легковісно).
• Конфіг: TOML / YAML / JSON / Python.
• Вбудовування як бібліотеки: першокласний сценарій використання.
• Віртуальні ключі + групи: вбудовано.
• OIDC / Keycloak авт.: вбудовано.
• Трекінг витрат, guardrails, кеш: немає з коробки (розширюється через плагіни).
• Адмін-панель: ні.
• Підтримка провайдерів: усі основні + локальні моделі / вбудований інференс.

LiteLLM Proxy:

• Філософія: все включено.
• Налаштування: pip install 'litellm[proxy]' + YAML + опціонально БД.
• Залежності: важче дерево залежностей.
• Конфіг: YAML.
• Вбудовування як бібліотеки: підтримується, але не рекомендується документацією.
• Віртуальні ключі + групи: вбудовано (більш розвинуто).
• OIDC / Keycloak авт.: вбудовано (більш розвинуто: JWT-валідація, мапінг ролей, SSO UI).
• Трекінг витрат, guardrails, кеш: вбудовано.
• Адмін-панель: так.
• Підтримка провайдерів: усі основні.

Обирайте LM-Proxy, коли: вам потрібен легкий проксі, який легко вбудовується, з мінімальним footprint, можливістю конфігурування через Python і без потреби в 90% enterprise-функцій. Ідеально для невеликих команд, особистих проєктів або коли хочете шлюз, вихідний код якого можна повністю прочитати за один вечір.

Обирайте LiteLLM, коли: вам потрібен enterprise-рівень трекінгу витрат, UI для управління, десятки інтеграцій, guardrails, кешування та підтримка 100+ провайдерів і інтеграцій з коробки.

Інші альтернативи, як-от Portkey, схиляються ще більше в бік enterprise. LM-Proxy свідомо займає нішу «рівно стільки шлюзу, скільки потрібно» — достатньо потужний для production, достатньо простий, щоб конфіг-файл і був документацією.

Що вже є (і що хотілося б бачити далі)

Варто визнати — LM-Proxy вже покриває більше, ніж очікуєш від «легковісного» інструменту:

• Структуроване логування — система логування з підключенням JsonLogWriter і LogEntryTransformer (відстежує токени, тривалість, групу, з’єднання, IP-адресу), плюс застосунок lm-proxy-db-connector для запису логів у PostgreSQL, MySQL, SQLite та інші бази через SQLAlchemy
• Балансування навантаження — є приклад конфігурації, який розподіляє запити випадковим чином між кількома LLM-серверами за допомогою Python-формату конфігурації.
• Обробники запитів — механізм, подібний до middleware, для перехоплення запитів перед надсиланням до upstream-провайдерів, що дозволяє реалізувати наскрізні завдання на кшталт аудиту та маніпуляцій заголовками.
• Підтримка Vertex AI — Google Cloud Vertex AI підтримується поряд із простішим AI Studio API, з окремим прикладом конфігурації.

Проєкт розвивається (остання версія: v3.0.1), і кілька речей залишаються в моєму особистому списку побажань:

• Usage analytics dashboard — інфраструктура логування та БД уже солідна, але вбудований UI для візуалізації витрат і використання був би вишенькою на торті.
• Wildcard model expansion — режим expand_wildcards для /v1/models запланований, але ще не реалізований — наразі потрібно явно перелічувати моделі в конфігурації маршрутизації.
• Automatic provider failover — якщо OpenAI повертає 5xx, автоматично перенаправити запит до Anthropic. Балансування між інстансами одного провайдера вже є, але кросс-провайдерний failover доповнив би картину.

Філософія «extensibility-by-design» означає, що більшість можливостей можна додавати у вигляді плагінів, не чіпаючи ядро. Наприклад, існує пакет db-connector для підключення до БД, логування в неї та перевикористання підключення SQLAlchemy для інших потреб — зокрема як сховища API-ключів тощо.

Кодова база має ліцензію MIT і достатньо компактна, щоб прочитати її повністю за один вечір.

Підсумок

Якщо ви працюєте з кількома LLM-провайдерами, або підозрюєте, що будете — зав’язуйте писати код під конкретного провайдера / SDK. Втуліть між собою і ними проксі-шар, і нехай міграція між моделями буде тим, чим вона має бути: зміною одного рядка в конфігу.

pip install lm-proxy

→ GitHub | PyPI

А як ви вирішуєте проблему зоопарку моделей і їх API/SDK? Пишете свої врапери чи використовуєте готові шлюзи? Запрошую до холівару в коментарях.