इस प्रोजेक्ट के बारे में

# XTokenHub XTokenHub LLM प्रदाता APIs के लिए एक सेल्फ-होस्टेड एग्रीगेशन गेटवे है। यह विभिन्न प्रदाताओं के पास मौजूद आपकी API कुंजियों को एक सिंगल चैनल-आधारित पैनल में एकत्र करता है, आपके क्लाइंट्स के लिए मानकीकृत प्रोटोकॉल एंडपॉइंट्स उपलब्ध कराता है, और टोकन उपयोग और कैश हिट रेट की लाइव रिपोर्ट देता है। इसका घोषित डिज़ाइन सिद्धांत यह है कि जहाँ तक संभव हो ट्रैफिक को प्रदाता के नेटिव प्रोटोकॉल के माध्यम से पास किया जाए, और कन्वर्जन (रूपांतरण) को केवल एक फॉलबैक के रूप में रखा जाए। ## मुख्य क्षमताएं - **चैनल-आधारित कुंजी प्रबंधन** — प्रति प्रदाता एंडपॉइंट एक प्रविष्टि, उपलब्धता प्रोबिंग, सक्षम/अक्षम स्विचिंग, और बैलेंस क्वेरी (जहाँ प्रदाता उन्हें उपलब्ध कराते हैं)। - **मॉडल ग्रुपिंग और रूटिंग** — प्रत्येक चैनल की अपनी मॉडल सूची होती है (मांग पर अपस्ट्रीम से ली गई), और सभी अपस्ट्रीम को एक सिंगल मॉडल लिस्टिंग एंडपॉइंट में मर्ज किया जाता है। रूटिंग के लिए प्रायोरिटी और वेटेड रैंडम सिलेक्शन का उपयोग किया जाता है, जिसमें एक ही मॉडल देने वाले चैनलों के बीच ऑटोमैटिक फेलओवर की सुविधा है। - **उपयोग अंतर्दृष्टि (Usage insight)** — एक डैशबोर्ड अनुरोध गणना, टोकन उपयोग, कैश हिट रेट और औसत लेटेंसी की रिपोर्ट करता है, जिन्हें मॉडल, चैनल या कॉलर कुंजी द्वारा एकत्रित किया जाता है। इसमें GitHub-स्टाइल एक्टिविटी हीटमैप और WebSocket के माध्यम से डेली ट्रेंड चार्ट दिए गए हैं। - **प्रोटोकॉल रूपांतरण** — गेटवे एक साथ OpenAI-स्टाइल चैट और रिस्पॉन्स एंडपॉइंट्स और एक Anthropic-स्टाइल मैसेज एंडपॉइंट उपलब्ध कराता है। अनुरोधों को केवल तब रूपांतरित किया जाता है जब इनबाउंड और अपस्ट्रीम प्रोटोकॉल अलग होते हैं; मैचिंग प्रोटोकॉल को बिना रीराइट किए फॉरवर्ड किया जाता है, जिससे टूल कॉल्स और मल्टीमोडल पेलोड सुरक्षित रहते हैं। - **गेटवे कुंजियाँ और प्रति-कॉलर आँकड़े** — विभिन्न कॉलर्स के लिए क्लाइंट-फेसिंग कुंजियाँ जारी की जाती हैं, और अनुरोध/टोकन कुल योग प्रति कुंजी एकत्रित किए जाते हैं। - **सिंगल-बाइनरी सेल्फ-होस्टिंग** — फ्रंटएंड Go बाइनरी में एम्बेडेड है, इसलिए एक बिल्ड एक स्टैटिक आर्टिफैक्ट (बिना CGO के) तैयार करता है जिसे Linux या macOS मशीन पर कॉपी किया जा सकता है। ## रूटिंग और मीटरिंग कैसे काम करते हैं README एक चार-चरणीय प्रवाह का वर्णन करता है: 1. प्रदाता बेस URL, API कुंजी और मॉडल सूची के साथ एक चैनल बनाएं। API स्टाइल (OpenAI-संगत के लिए Bearer, Anthropic-संगत के लिए x-api-key) बेस URL से ऑटो-डिटेक्ट किया जाता है और इसे ओवरराइड किया जा सकता है। इसमें बेयर डोमेन, /v1 सफिक्स, /anthropic जैसे सब-पाथ माउंट और वर्जन वाले माउंट सहित कई बेस-URL माउंटिंग फॉर्म समर्थित हैं। 2. एक नेटिव-प्रोटोकॉल प्रोब प्रत्येक प्रोटोकॉल एंडपॉइंट पर एक न्यूनतम अनुरोध भेजता है; 2xx रिस्पॉन्स उस प्रोटोकॉल को चैनल के लिए नेटिव के रूप में चिह्नित करता है, जिसे मैन्युअल रूप से भी ठीक किया जा सकता है। 3. आने वाले अनुरोधों को मॉडल देने वाले सक्षम चैनलों तक फ़िल्टर किया जाता है, नेटिव चैनलों को प्राथमिकता दी जाती है, और रूपांतरित चैनलों का उपयोग केवल फॉलबैक के रूप में किया जाता है। चयन प्रायोरिटी-असेंडिंग और वेटेड रैंडमनेस के साथ होता है, और नेटवर्क त्रुटियों, 401/403/408/429 या 5xx जैसी विफलताएं फेलओवर को ट्रिगर करती हैं। 4. उपयोग को अपस्ट्रीम रिस्पॉन्स से पार्स किया जाता है जहाँ रिपोर्ट किया गया हो (स्ट्रीमिंग उपयोग विकल्प स्वचालित रूप से जोड़े जाते हैं); जब अपस्ट्रीम कुछ रिपोर्ट नहीं करता है, तो एक स्थानीय ह्यूरिस्टिक अनुमान का उपयोग किया जाता है। कैश हिट रेट प्रदाता के cached-token फ़ील्ड से आता है, और प्रत्येक अनुरोध को एक लॉग टेबल में लिखा जाता है और UI पर पुश किया जाता है। ## डैशबोर्ड और API सरफेस एडमिन API में चैनल, गेटवे कुंजियाँ, रिटेंशन क्लीनअप के साथ अनुरोध लॉग, और सांख्यिकी एंडपॉइंट्स का एक सेट (सारांश, दैनिक रुझान, मॉडल-वार, चैनल-वार, कुंजी-वार, लाइफटाइम टोटल और मॉडल-वार रुझान) शामिल हैं, साथ ही एक हेल्थ एंडपॉइंट और लाइव इवेंट्स के लिए एक WebSocket एंडपॉइंट है। गेटवे एंडपॉइंट्स में एक मर्ज की गई मॉडल सूची और चैट, रिस्पॉन्स और मैसेज रूट्स शामिल हैं। कॉलर ऑथेंटिकेशन Bearer टोकन या x-api-key हेडर स्वीकार करता है और इसे कॉन्फ़िगरेशन द्वारा बंद किया जा सकता है। ## कॉन्फ़िगरेशन और संचालन कॉन्फ़िगरेशन प्राथमिकता पर्यावरण चर (environment variables), फिर एक YAML फ़ाइल, और फिर बिल्ट-इन डिफॉल्ट्स है। डेटा को WAL मोड में SQLite में एक सिंगल राइटर कनेक्शन के साथ स्टोर किया जाता है। अनुरोध लॉग डिफ़ॉल्ट रूप से असीमित रूप से बढ़ते हैं, इसलिए एक रिटेंशन जॉब कॉन्फ़िगर किए गए दिनों से पुराने पंक्तियों को हटा देता है, जिसमें साइकिल अंतराल, बैच आकार और एक वैकल्पिक VACUUM के लिए सेटिंग्स होती हैं। प्रोजेक्ट नोट करता है कि विलोपन के बाद SQLite फ़ाइल स्वचालित रूप से छोटी नहीं होती है। ## परीक्षण (Testing) यूनिट टेस्ट एक मिरर बाहरी टेस्ट पैकेज लेआउट में हैं और कॉन्फ़िगरेशन लोडिंग, इन-मेमोरी SQLite रिपॉजिटरी, इवेंट बस, WebSocket व्यवहार, फेक अपस्ट्रीम के माध्यम से प्रदाता प्रोबिंग और रूपांतरण, गेटवे चयन और स्टैट्स पर्सिस्टेंस, और एंड-टू-एंड हैंडलर/राउटर पाथ को कवर करते हैं। README एक पूर्ण रेस-इनेबल्ड टेस्ट रन और 87.6% स्टेटमेंट कवरेज, साथ ही WebSocket पुन: कनेक्शन और डेटा ट्रांसफॉर्म के लिए फ्रंटएंड टेस्ट की रिपोर्ट करता है। ## प्रोजेक्ट द्वारा बताए गए ज्ञात सीमाएं - रूपांतरण पाथ केवल टेक्स्ट चैट को संभालता है; टूल कॉल्स, मल्टीमोडल और कैश-कंट्रोल पेलोड के लिए नेटिव पासथ्रू चैनलों की आवश्यकता होती है। - बैलेंस क्वेरी वर्तमान में केवल DeepSeek को कवर करती है, क्योंकि अन्य प्रदाताओं के बैलेंस API अनडॉक्यूमेंटेड हैं, एक्सपायरिंग कुकी ऑथ की आवश्यकता होती है, या सार्वजनिक नहीं हैं। - स्थानीय टोकन अनुमान ह्यूरिस्टिक है और केवल फॉलबैक के रूप में उपयोग किया जाता है। - एडमिन API में कोई लॉगिन ऑथेंटिकेशन नहीं है और इसे बाहरी नेटवर्क आइसोलेशन के साथ सेल्फ-होस्टेड इंट्रानेट उपयोग के लिए बनाया गया है; कुंजियाँ प्लेनटेक्स्ट में स्टोर की जाती हैं। - कैश हिट रेट और प्रति-कुंजी एकत्रीकरण अनुरोध-लॉग स्नैपशॉट पर निर्भर करते हैं, इसलिए हटाए गए कुंजी का ऐतिहासिक उपयोग उसके नाम के तहत रहता है। ## साथी ऐप और लाइसेंस एक अलग SwiftUI मेनू बार ऐप बिना बैकएंड बदलावों के उसी एडमिन API और WebSocket का उपयोग करता है। XTokenHub को MIT लाइसेंस के तहत जारी किया गया है।