Об этом проекте

# XTokenHub XTokenHub — это самохостимый агрегирующий шлюз для API LLM-провайдеров. Он собирает имеющиеся у вас API-ключи разных провайдеров в единую панель каналов, предоставляет стандартизированные протокольные эндпоинты для ваших клиентов и в реальном времени отчёте об использовании токенов и уровне попадания в кэш. Заявленный принцип проектирования — пропускать трафик через нативный протокол провайдера whenever возможно, рассматривая конвертацию как запасной вариант. ## Основные возможности - **Канальное управление ключами** — одна запись на эндпоинт провайдера, с зондированием доступности, переключением включения/выключения и запросами баланса, где провайдер их предоставляет. - **Группировка моделей и маршрутизация** — каждый канал несёт собственный список моделей (запрашиваемый у вышестоящего источника по мере необходимости), все источники объединяются в единственный эндпоинт списка моделей. Маршрутизация использует приоритет плюс взвешенный случайный выбор, с автоматическим фалловером между каналами, обслуживающими одну и ту же модель. - **Аналитика использования** — дашборд отображает количество запросов, использование токенов, уровень попадания в кэш и среднюю задержку, агрегированные по модели, каналу или ключу вызывающего, с активностью в стиле GitHub и ежедневными графиками трендов, транслируемыми через WebSocket. - **Конвертация протоколов** — шлюз одновременно предоставляет OpenAI-совместимые chat и responses эндпоинты, а также Anthropic-совместимый messages-эндпоинт. Запросы конвертируются только тогда, когда входящий и вышестоящий протоколы различаются; при совпадении протоколы передаются без преобразования, что, по утверждению проекта, сохраняет вызовы инструментов и мультимодальные payloads. - **Ключи шлюза и статистика по вызывающим** — клиентские ключи выдаются для разных вызывающих, а суммарные запросы и токены агрегируются по ключу. - **Самохостинг одним бинарником** — фронтенд встроен в Go-бинарник, поэтому сборка даёт один статичный артефакт (без CGO), который можно скопировать на Linux или macOS машину. ## Как работают маршрутизация и учёт README описывает четырёхшаговый поток: 1. Создайте канал с базовым URL провайдера, API-ключом и списком моделей. Стиль API (Bearer для OpenAI-совместимых, x-api-key для Anthropic-совместимых) автоматически определяется из базового URL и может быть переопределён. Поддерживаются несколько форм монтирования base-URL, включая голые домены, суффикс /v1, подпути вроде /anthropic и версионированные монтирования. 2. Зонд нативного протокола отправляет минимальный запрос каждому протокольному эндпоинту; ответ 2xx помечает этот протокол как нативный для канала, что также можно исправить вручную. 3. Входящие запросы фильтруются по включённым каналам, обслуживающим модель; нативные каналы имеют приоритет, конвертируемые используются только как фоллбэк. Выбор —ascending по приоритету со случайностью, а такие сбои, как сетевые ошибки, 401/403/408/429 или 5xx, вызывают фалловер. 4. Использование парсится из вышестоящего ответа там, где оно сообщается (с автоматически добавленными опциями streaming usage); когда источник ничего не сообщает, используется локальная эвристическая оценка. Уровень попадания в кэш берётся из cached-token полей провайдера, каждый запрос записывается в таблицу логов и транслируется в UI. ## Дашборд и API-поверхность Административный API охватывает каналы, ключи шлюза, логи запросов с очисткой по retention, набор эндпоинтов статистики (сводка, ежедневный тренд, по моделям, по каналам, по ключам,Lifetime totals и тренды по моделям), а также health-эндпоинт и WebSocket-эндпоинт для живых событий. Шлюзовые эндпоинты включают объединённый список моделей и маршруты chat, responses и messages. Аутентификация вызывающих принимает либо Bearer токен, либо x-api-key заголовок и может быть отключена конфигурацией. ## Конфигурация и эксплуатация Приоритет конфигурации: переменные окружения, затем YAML-файл, затем встроенные значения по умолчанию. Данные хранятся в SQLite в WAL-режиме с одним соединением писателя. Логи запросов растут неограниченно по умолчанию, поэтому job retention удаляет строки старше заданного числа дней, с настройками интервала цикла, размера пакета и опционального VACUUM. Проект отмечает, что файл SQLite не уменьшается автоматически после удаления. ## Тестирование Юнит-тесты расположены вmirrored внешней тестовой пакетной компоновке и охватывают загрузку конфигурации, ин-мемори SQLite-репозитории, event bus, поведение WebSocket, зондирование провайдеров и конвертацию через фейковые upstreams, выбор шлюза и сохранение статистики, а также end-to-end handler/router пути. README сообщает о полном запуске тестов с race detection и покрытии statements на 87,6%, плюс фронтенд-тесты для переподключения WebSocket и трансформаций данных. ## Известные ограничения, заявленные проектом - Путь конвертации обрабатывает только текстовый чат; tool calls, мультимодальные и cache-control payloads требуют нативных passthrough-каналов. - Запросы балансаcurrently покрывают только DeepSeek, поскольку API баланса других провайдеров неофициальны, требуют истецший cookie-аутентификацию или являются общедоступными. - Локальная оценка токенов является эвристической и используется только как фоллбэк. - Административный API не имеет логин-аутентификации и предназначен для самохостимого использования в интрасети с изоляцией от внешних сетей; ключи хранятся в открытом виде. - Уровень попадания в кэш и агрегация по ключам основаны на снимках логов запросов, поэтому историческое использование удалённого ключа остаётся под его именем. ## Сопутствующее приложение и лицензия Отдельное SwiftUI menu bar app потребляет тот же административный API и WebSocket без необходимости изменений на бэкенде. XTokenHub выпущен под лицензией MIT.