À propos du projet

# XTokenHub XTokenHub est une passerelle d’agrégation auto‑hébergée pour les API des fournisseurs de LLM. Elle regroupe les clés API que vous possédez déjà chez différents fournisseurs dans un panneau à canaux, expose des points d’accès à protocole standardisé à vos clients, et rapporte en direct l’utilisation des tokens et le taux de cache hit. Le principe de conception déclaré est de faire transiter le trafic dans le protocole natif du fournisseur chaque fois que possible, en ne recourant à la conversion qu’en dernier recours. ## Capacités principales - **Gestion des clés par canal** — une entrée par point d’accès fournisseur, avec sondage de disponibilité, activation/désactivation, basculement, et équilibrage des requêtes lorsque le fournisseur les expose. - **Groupement et routage des modèles** — chaque canal possède sa propre liste de modèles (récupérée à la demande en amont), et tous les amont sont fusionnés dans un point d’accès unique listant les modèles. Le routage utilise la priorité plus une sélection aléatoire pondérée, avec basculement automatique entre les canaux servant le même modèle. - **Analyse d’usage** — un tableau de bord indique le nombre de requêtes, l’usage des tokens, le taux de cache hit et la latence moyenne, agrégés par modèle, canal ou clé appelante, avec une carte de chaleur d’activité à la GitHub et des graphiques de tendance quotidiens poussés via WebSocket. - **Conversion de protocole** — la passerelle expose simultanément des points d’accès de type chat et réponses à la OpenAI et un point d’accès messages à la Anthropic. Les requêtes ne sont converties que lorsque les protocoles entrant et amont diffèrent ; les protocoles correspondants sont simplement transmis sans réécriture, ce qui, selon le projet, préserve les appels d’outils et les charges multimodales. - **Clés de passerelle et statistiques par appelant** — des clés côté client sont émises pour différents appelants, et les totaux de requêtes/tokens sont agrégés par clé. - **Auto‑hébergement en un seul binaire** — le front‑end est intégré dans le binaire Go, de sorte qu’une compilation produit un seul artefact statique (sans CGO) qui peut être copié sur une machine Linux ou macOS. ## Fonctionnement du routage et de la facturation Le README décrit un flux en quatre étapes : 1. Créez un canal avec l’URL de base du fournisseur, la clé API et la liste des modèles. Le style d’API (Bearer pour les compatibles OpenAI, x‑api‑key pour les compatibles Anthropic) est détecté automatiquement à partir de l’URL de base et peut être remplacé. Plusieurs formes de montage d’URL de base sont supportées, y compris les domaines nus, les suffixes /v1, les montages de sous‑chemin comme /anthropic, et les montages versionnés. 2. Un sondage en protocole natif envoie une requête minimale à chaque point d’accès protocolaire ; une réponse 2xx marque ce protocole comme natif pour le canal, ce qui peut aussi être corrigé manuellement. 3. Les requêtes entrantes sont filtrées vers les canaux activés servant le modèle ; les canaux natifs sont privilégiés, et les canaux convertis ne sont utilisés qu’en secours. La sélection se fait par priorité croissante avec aléatoire pondéré, et les échecs (erreurs réseau, 401/403/408/429 ou 5xx) déclenchent le basculement. 4. L’usage est extrait de la réponse amont lorsqu’il est fourni (avec les options d’usage en streaming ajoutées automatiquement) ; si l’amont ne rapporte rien, une estimation heuristique locale est utilisée. Le taux de cache hit provient des champs cached‑token du fournisseur, et chaque requête est enregistrée dans une table de logs et poussée vers l’UI. ## Tableau de bord et surface d’API L’API d’administration couvre les canaux, les clés de passerelle, les logs de requêtes avec nettoyage de rétention, et un ensemble de points d’accès statistiques (résumé, tendance quotidienne, par modèle, par canal, par clé, totaux à vie, tendance par modèle), ainsi qu’un point d’accès santé et un point d’accès WebSocket pour les événements en direct. Les points d’accès de la passerelle incluent une liste de modèles fusionnée et les routes chat, responses et messages. L’authentification des appelants accepte soit un token Bearer, soit un en‑tête x‑api‑key et peut être désactivée via configuration. ## Configuration et opérations La priorité de configuration est : variables d’environnement, puis fichier YAML, puis valeurs par défaut intégrées. Les données sont stockées dans SQLite en mode WAL avec une connexion écriture unique. Les logs de requêtes croissent sans limite par défaut, ainsi un job de rétention supprime les lignes plus anciennes qu’un nombre configurable de jours, avec des paramètres pour l’intervalle du cycle, la taille du lot et un VACUUM optionnel. Le projet indique que le fichier SQLite ne se rétrécit pas automatiquement après suppression. ## Tests Les tests unitaires se trouvent dans une disposition de package de test externe miroir et couvrent le chargement de configuration, les dépôts SQLite en mémoire, le bus d’événements, le comportement WebSocket, le sondage des fournisseurs et la conversion via des amonts factices, la sélection de la passerelle et la persistance des statistiques, ainsi que les chemins handler/router de bout en bout. Le README rapporte un exécution complète des tests avec la course activée et une couverture de 87,6 % des instructions, plus des tests front‑end pour la reconnexion WebSocket et les transformations de données. ## Limitations connues indiquées par le projet - Le chemin de conversion ne gère que le texte de chat ; les appels d’outils, les charges multimodales et les contrôles de cache nécessitent des canaux natifs en passage direct. - Les requêtes de solde couvrent actuellement uniquement DeepSeek, car les API de solde des autres fournisseurs sont non documentées, requièrent une authentification par cookie expirant, ou ne sont pas publiques. - L’estimation locale des tokens est heuristique et n’est utilisée qu’en secours. - L’API d’administration n’a pas d’authentification de connexion et est destinée à un usage intranet auto‑hébergé avec isolation réseau externe ; les clés sont stockées en texte clair. - Le taux de cache hit et l’agrégation par clé reposent sur des instantanés du log de requêtes, de sorte qu’une clé supprimée conserve son historique d’usage sous son nom. ## Application compagnon et licence Une application SwiftUI distincte pour la barre de menus consomme la même API d’administration et le WebSocket sans nécessiter de modifications du backend. XTokenHub est publié sous licence MIT.