Знакомьтесь: Switchyard — прокси и библиотека на Rust для маршрутизации и преобразования трафика LLM между API OpenAI и Anthropic

Команды, запускающие агентов для написания кода, сталкиваются с одной и той же проблемой. Claude Code работает с Anthropic Messages API, Codex CLI — с OpenAI, а модель, которую команда действительно хочет использовать, размещена за vLLM, NVIDIA NIM или Ollama. Переписывать агента не вариант, поэтому слой трансляции должен находиться где-то ещё.

Switchyard — ответ NVIDIA: прокси и библиотека на Rust для трафика LLM, которые маршрутизируют запросы между провайдерами, преобразуют форматы OpenAI и Anthropic, записывают эксплуатационные метрики и предоставляют типизированные компонуемые алгоритмы маршрутизации. Проект выпущен по лицензии Apache 2.0, а документация доступна по адресу docs.nvidia.com/nemo/switchyard.

Можно ли его развернуть? Да, но только для оценки. Бинарный файл устанавливается из crates.io, лаунчер — из PyPI, а самостоятельное размещение возможно где угодно, однако NVIDIA называет Switchyard предальфа-версией и экспериментальным проектом, предупреждает, что он не предназначен для использования в продакшене, и ожидает значительных изменений API и алгоритмов до выхода версии v1.0.

Что делает Switchyard

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

Сервер принимает три входных формата: OpenAI Chat Completions, OpenAI Responses и Anthropic Messages. Любой из них может обращаться к любому маршруту, а каждый настроенный клиент LLM выбирает собственный формат вышестоящего сервиса. Именно в этом заключается смысл такого разделения: API агента и API бэкенда больше не обязаны совпадать.

Три способа запуска

Путь через лаунчер предназначен для агентов, работающих с кодом. Установите опубликованный инструмент с помощью uv tool install --python 3.12 "nemo-switchyard[cli]", затем запустите switchyard launch claude, switchyard launch codex или switchyard launch openclaw для работы с пакетным развёртыванием или собственным TOML-файлом.

Путь через сервер устанавливает автономный прокси с помощью cargo install --locked switchyard-server, проверяет конфигурацию через --dry-run и запускает сервер на выбранных вами хосте и порте.

Путь через библиотеку использует switchyard-libsy, встраивая алгоритмы маршрутизации в приложение на Rust без собственного HTTP-стека. Библиотека сама никогда не вызывает модель: алгоритм решает, какую цель использовать, и передаёт каждый вызов модели обратно вызывающей стороне.

Алгоритмы маршрутизации

Маршрут — это один видимый клиенту идентификатор модели и лежащий в его основе алгоритм. Сервер поддерживает:

passthrough отправляет каждый запрос к одной цели.
random распределяет трафик между целями с использованием необязательных относительных весов; необязательное начальное значение позволяет воспроизводить последовательность выбора. Это вариант для A/B-тестирования и экспериментов со стоимостью.
llm_classifier обращается к цели-классификатору для получения оценки возможностей, а затем направляет запрос к слабой или сильной цели. Параметр base_threshold обязателен; параметры min_confidence, capability_elevated_floor и session_affinity позволяют настроить алгоритм, а всё, что классификатор не может определить, направляется к сильной цели. Установка mode = "escalation" сначала выполняет каждый шаг на слабом уровне, после чего классификатор решает, нужно ли повторно выполнить его на сильном уровне.
stage_router оценивает сигналы результатов вызова инструментов и прогресса агента за последние шаги, чтобы выбрать производительную или эффективную цель, избегая дополнительного вызова классификатора в большинстве случаев.

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

Наблюдаемость

GET /metrics возвращает данные Prometheus в текстовом формате от общепроцессного провайдера OpenTelemetry сервера. Наборы метрик охватывают запросы, ошибки, задержку вызовов модели, задержку полного шага, токены промпта, завершения, кэшированные токены, токены создания кэша и токены рассуждений, а также попытки HTTP-запросов к вышестоящим сервисам с разбивкой по результату и коду. Метка tier содержит значения strong или weak для различения решений классификатора, а вызовы классификатора исключены из этих наборов.

Наиболее интересная метрика — switchyard_routing_overhead_ms, которая показывает время работы алгоритма за вычетом вызова, обслужившего запрос. Вызовы классификатора не вычитаются, поэтому маршрут с классификатором LLM отображает здесь время классификации, тогда как passthrough и random показывают стоимость выбора цели, составляющую менее миллисекунды. Диапазоны начинаются с 0,1 мс. Отдельно параметр --routing-log-file добавляет JSON-запись для каждого завершённого ответа, а GET /v1/routing/session-stats возвращает итоги вызовов и токенов по каждой сессии из этого журнала.

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

Развёртывание в формате TOML состоит из трёх уровней: llm_clients определяют базовый URL, формат обмена данными, переменную окружения для учётных данных и политику повторных попыток; targets связывают один идентификатор вышестоящей модели с клиентом; routes предоставляют один видимый клиенту идентификатор модели и его алгоритм. Секреты никогда не хранятся в файле, поскольку api_key_env лишь указывает имя переменной окружения. Значение max_retries по умолчанию равно 2 и применяется к сбоям транспорта, тайм-аутам, HTTP-ответам 408/429 и ответам 5xx.

Основные выводы

Switchyard — это прокси и библиотека на Rust под лицензией Apache 2.0, которые маршрутизируют и преобразуют трафик LLM.
Он обеспечивает двустороннюю совместимость OpenAI Chat, OpenAI Responses и Anthropic Messages, включая потоковую передачу.
Поставляются четыре типа маршрутов: passthrough, random, классификатор LLM и управляемый сигналами маршрутизатор этапов.
Метрики Prometheus отделяют накладные расходы маршрутизации от задержки вызова модели с разбивкой по модели и уровню.
Проект находится на предальфа-стадии и прямо не предназначен для продакшена, поэтому относитесь к нему как к инструменту для оценки.

Посмотрите репозиторий на GitHub и документацию. Также подписывайтесь на нас в Twitter и не забудьте присоединиться к нашему сабреддиту о машинном обучении с аудиторией более 150 тыс. участников и подписаться на нашу рассылку. Постойте! Вы есть в Telegram? теперь к нам можно присоединиться и в Telegram.

Хотите сотрудничать с нами для продвижения вашего репозитория на GitHub, страницы на Hugging Face, релиза продукта, вебинара и т. д.? Свяжитесь с нами

Переведено автоматически с английского. Оригинал статьи — по ссылке ниже.