Sobre el proyecto

# XTokenHub XTokenHub es una puerta de enlace de agregación autoalojada para APIs de proveedores de LLM. Recopila las claves de API que ya posee a través de diversos proveedores en un único panel basado en canales, expone endpoints de protocolos estandarizados a sus clientes e informa en vivo sobre el uso de tokens y la tasa de aciertos de caché. El principio de diseño establecido es transmitir el tráfico a través del protocolo nativo del proveedor siempre que sea posible, tratando la conversión como un recurso de respaldo. ## Capacidades principales - **Gestión de claves basada en canales**: una entrada por endpoint de proveedor, con sondeo de disponibilidad, interruptor de habilitar/deshabilitar y consultas de saldo cuando el proveedor las expone. - **Agrupación y enrutamiento de modelos**: cada canal lleva su propia lista de modelos (obtenida del upstream bajo demanda), y todos los upstreams se fusionan en un único endpoint de listado de modelos. El enrutamiento utiliza prioridad más selección aleatoria ponderada, con failover automático entre canales que sirven el mismo modelo. - **Información de uso**: un tablero informa el recuento de solicitudes, el uso de tokens, la tasa de aciertos de caché y la latencia promedio, agregados por modelo, canal o clave de llamador, con un mapa de calor de actividad estilo GitHub y gráficos de tendencia diaria enviados a través de WebSocket. - **Conversión de protocolos**: la puerta de enlace expone simultáneamente endpoints de chat y respuestas estilo OpenAI y un endpoint de mensajes estilo Anthropic. Las solicitudes se convierten solo cuando los protocolos entrantes y los del upstream difieren; los protocolos coincidentes se reenvían sin reescritura, lo que según el proyecto preserva las llamadas a herramientas y las cargas útiles multimodales. - **Claves de puerta de enlace y estadísticas por llamador**: se emiten claves orientadas al cliente para diferentes llamadores, y los totales de solicitudes/tokens se agregan por clave. - **Autoalojamiento en binario único**: el frontend está embebido en el binario de Go, por lo que una compilación produce un único artefacto estático (sin CGO) que puede copiarse a una máquina Linux o macOS. ## Cómo funcionan el enrutamiento y la medición El README describe un flujo de cuatro pasos: 1. Crear un canal con la URL base del proveedor, la clave API y la lista de modelos. El estilo de API (Bearer para compatible con OpenAI, x-api-key para compatible con Anthropic) se detecta automáticamente a partir de la URL base y puede anularse. Se admiten varias formas de montaje de URL base, incluyendo dominios simples, sufijos /v1, montajes de subrutas como /anthropic y montajes versionados. 2. Un sondeo de protocolo nativo envía una solicitud mínima a cada endpoint de protocolo; una respuesta 2xx marca ese protocolo como nativo del canal, lo cual también puede corregirse manualmente. 3. Las solicitudes entrantes se filtran hacia los canales habilitados que sirven el modelo; se prefieren los canales nativos y los canales convertidos se utilizan solo como respaldo. La selección es de prioridad ascendente con aleatoriedad ponderada, y los fallos como errores de red, 401/403/408/429 o 5xx activan el failover. 4. El uso se analiza a partir de la respuesta del upstream donde se informa (con opciones de uso de streaming añadidas automáticamente); cuando el upstream no informa nada, se utiliza una estimación heurística local. La tasa de aciertos de caché proviene de los campos de tokens almacenados en caché del proveedor, y cada solicitud se escribe en una tabla de registros y se envía a la interfaz de usuario. ## Tablero y superficie de API La API de administración cubre canales, claves de puerta de enlace, registros de solicitudes con limpieza de retención y un conjunto de endpoints de estadísticas (resumen, tendencia diaria, por modelo, por canal, por clave, totales vitalicios y tendencia por modelo), además de un endpoint de salud y un endpoint de WebSocket para eventos en vivo. Los endpoints de la puerta de enlace incluyen una lista de modelos fusionada y las rutas de chat, respuestas y mensajes. La autenticación del llamador acepta un token Bearer o un encabezado x-api-key y puede desactivarse mediante configuración. ## Configuración y operaciones La precedencia de configuración es variables de entorno, luego un archivo YAML y finalmente los valores predeterminados integrados. Los datos se almacenan en SQLite en modo WAL con una única conexión de escritura. Los registros de solicitudes crecen sin límite por defecto, por lo que una tarea de retención elimina las filas más antiguas que un número configurable de días, con ajustes para el intervalo de ciclo, el tamaño del lote y un VACUUM opcional. El proyecto señala que el archivo SQLite no se reduce automáticamente después de la eliminación. ## Pruebas Las pruebas unitarias residen en una estructura de paquete de pruebas externa espejada y cubren la carga de configuración, repositorios SQLite en memoria, el bus de eventos, el comportamiento de WebSocket, el sondeo de proveedores y la conversión mediante upstreams falsos, la selección de puerta de enlace y la persistencia de estadísticas, y rutas de manejador/enrutador de extremo a extremo. El README reporta una ejecución de pruebas completa con race-enabled y una cobertura de sentencias del 87.6%, además de pruebas de frontend para la reconexión de WebSocket y transformaciones de datos. ## Limitaciones conocidas declaradas por el proyecto - La ruta de conversión maneja solo chat de texto; las llamadas a herramientas, los datos multimodales y las cargas útiles de control de caché necesitan canales de paso nativos. - Las consultas de saldo actualmente cubren solo DeepSeek, porque las APIs de saldo de otros proveedores no están documentadas, requieren autenticación por cookies que expiran o no son públicas. - La estimación local de tokens es heurística y se utiliza solo como respaldo. - La API de administración no tiene autenticación de inicio de sesión y está destinada al uso en intranets autoalojadas con aislamiento de red externa; las claves se almacenan en texto plano. - La tasa de aciertos de caché y la agregación por clave dependen de instantáneas del registro de solicitudes, por lo que el uso histórico de una clave eliminada permanece bajo su nombre. ## Aplicación complementaria y licencia Una aplicación de barra de menú de SwiftUI independiente consume la misma API de administración y WebSocket sin requerir cambios en el backend. XTokenHub se publica bajo la Licencia MIT.