पार्टनर और लाइब्रेरी इंटिग्रेशन

इस गाइड में, Gemini API की मदद से लाइब्रेरी, प्लैटफ़ॉर्म, और गेटवे बनाने के लिए, आर्किटेक्चरल रणनीतियों के बारे में बताया गया है. इसमें, आधिकारिक GenAI SDK टूल, Direct API (REST/gRPC), और OpenAI कंपैटबिलिटी लेयर का इस्तेमाल करने के बीच, तकनीकी पहलुओं के बारे में बताया गया है.

अगर अन्य डेवलपर के लिए टूल बनाए जा रहे हैं, जैसे कि ओपन-सोर्स फ़्रेमवर्क, एंटरप्राइज़ गेटवे या SaaS एग्रीगेटर, तो इस गाइड का इस्तेमाल करें. साथ ही, अगर आपको डिपेंडेंसी हाइजीन, बंडल साइज़ या फ़ीचर पैरिटी के लिए ऑप्टिमाइज़ करना है, तो भी इस गाइड का इस्तेमाल करें.

पार्टनर इंटिग्रेशन क्या है?

पार्टनर वह व्यक्ति या कंपनी होती है जो Gemini API और एंड-यूज़र डेवलपर के बीच इंटिग्रेशन बनाती है. हम पार्टनर को चार आर्किटाइप में बांटते हैं. यह पता लगाने से कि आपका आर्किटाइप कौनसा है, आपको इंटिग्रेशन का सही पाथ चुनने में मदद मिलेगी.

इकोसिस्टम फ़्रेमवर्क

• आप कौन हैं: ओपन-सोर्स फ़्रेमवर्क (जैसे, LangChain, LlamaIndex, Spring AI) या भाषा के हिसाब से क्लाइंट का रखरखाव करने वाले.
• आपका लक्ष्य: ज़्यादा से ज़्यादा कंपैटबिलिटी. आप चाहते हैं कि आपकी लाइब्रेरी, उपयोगकर्ता के चुने हुए किसी भी एनवायरमेंट में काम करे और उसमें कोई समस्या न आए.

रनटाइम और एज प्लैटफ़ॉर्म

• आप कौन हैं: SaaS प्लैटफ़ॉर्म, एआई गेटवे या क्लाउड इन्फ़्रास्ट्रक्चर की सेवा देने वाली कंपनियां (जैसे, Vercel, Cloudflare, Zapier). इनमें कोड का एक्ज़ीक्यूशन, सीमित एनवायरमेंट में होता है.
• आपका लक्ष्य: परफ़ॉर्मेंस. आपको कम से कम लेटेंसी, कम से कम बंडल साइज़, और तेज़ी से कोल्ड स्टार्ट की ज़रूरत है.

एग्रीगेटर

• आप कौन हैं: प्लैटफ़ॉर्म, प्रॉक्सी या इंटरनल "मॉडल गार्डन" जो कई अलग-अलग एलएलएम की सेवा देने वाली कंपनियों (जैसे, OpenAI, Anthropic, Google) के ऐक्सेस को एक ही इंटरफ़ेस में सामान्य बनाते हैं.
• आपका लक्ष्य: पोर्टेबिलिटी और एकरूपता.

एंटरप्राइज़ गेटवे

• आप कौन हैं: बड़ी कंपनियों में इंटरनल प्लैटफ़ॉर्म इंजीनियरिंग टीमें, जो सैकड़ों इंटरनल डेवलपर के लिए "गोल्डन पाथ" बनाती हैं.
• आपका लक्ष्य: स्टैंडर्डाइज़ेशन, गवर्नेंस, और यूनिफ़ाइड ऑथेंटिकेशन.

एक नज़र में तुलना

ग्लोबल सबसे सही तरीका: सभी पार्टनर को चुना गया पाथ चाहे कोई भी हो, x-goog-api-client हेडर भेजना होगा.

Google GenAI SDK इंटिग्रेशन

फ़्रेमवर्क के लिए, Google GenAI SDK को लागू करना अक्सर सबसे आसान तरीका होता है. ऐसा इसलिए, क्योंकि इसमें काम करने वाली भाषाओं में कोड की लाइनें कम होती हैं.

इंटरनल प्लैटफ़ॉर्म टीमों के लिए, आपका मुख्य काम अक्सर "गोल्डन पाथ" होता है. इससे प्रॉडक्ट इंजीनियर, सुरक्षा नीतियों का पालन करते हुए तेज़ी से काम कर पाते हैं.

फ़ायदे:

• Gemini Enterprise एजेंट प्लैटफ़ॉर्म माइग्रेशन के लिए यूनिफ़ाइड इंटरफ़ेस: इंटरनल डेवलपर अक्सर एपीआई पासकोड (Gemini API) का इस्तेमाल करके प्रोटोटाइप बनाते हैं और प्रोडक्शन के लिए, Gemini Enterprise एजेंट प्लैटफ़ॉर्म (IAM) पर डिप्लॉय करते हैं. एसडीके, ऑथेंटिकेशन के इन अंतरों को ऐब्स्ट्रैक्ट करता है. इसी तरह, फ़्रेमवर्क के लिए, एक कोडपाथ लागू किया जा सकता है और दो सेट के उपयोगकर्ताओं को सहायता दी जा सकती है.
• क्लाइंट-साइड हेल्पर: एसडीके में, इडियोमैटिक यूटिलिटी शामिल होती हैं. इससे मुश्किल कामों के लिए बॉयलरप्लेट कम हो जाता है.
  • उदाहरण: प्रॉम्प्ट में सीधे PIL इमेज ऑब्जेक्ट इस्तेमाल करना, फ़ंक्शन को अपने-आप कॉल करना, और अलग-अलग टाइप.
• लॉन्च के दिन से ही सुविधा का ऐक्सेस: एपीआई की नई सुविधाएं, एसडीके के ज़रिए लॉन्च के समय से ही उपलब्ध होती हैं.
• कोड जनरेट करने की सुविधा में सुधार: एसडीके को स्थानीय तौर पर इंस्टॉल करने पर, कोडिंग असिस्टेंट (जैसे, Cursor, Copilot) को टाइप की परिभाषाएं और डॉकस्ट्रिंग दिखती हैं. इस कॉन्टेक्स्ट से, REST के रॉ अनुरोध जनरेट करने के मुकाबले, कोड जनरेट करने की सटीक दर बेहतर होती है.

नुकसान:

• डिपेंडेंसी वेट और जटिलता: एसडीके की अपनी डिपेंडेंसी होती हैं. इससे बंडल साइज़ बढ़ सकता है और सप्लाई-चेन का जोखिम भी बढ़ सकता है.
• वर्शनिंग: एपीआई की नई सुविधाएं अक्सर एसडीके के कम से कम वर्शन से जुड़ी होती हैं. नई सुविधाएं या मॉडल ऐक्सेस करने के लिए, आपको उपयोगकर्ताओं को अपडेट पुश करने पड़ सकते हैं. कुछ मामलों में, ट्रांज़िटिव डिपेंडेंसी में बदलाव करने पड़ सकते हैं. इससे आपके उपयोगकर्ताओं पर असर पड़ सकता है.
• प्रोटोकॉल की सीमाएं: एसडीके, मुख्य एपीआई के लिए सिर्फ़ एचटीटीपीएस और Live API के लिए वेबसॉकेट (डब्ल्यूएसएस) के साथ काम करते हैं. हाई-लेवल एसडीके क्लाइंट का इस्तेमाल करके, gRPC के साथ काम नहीं किया जा सकता.
• भाषा की सहायता: एसडीके, भाषा के मौजूदा वर्शन के साथ काम करते हैं. अगर आपको ईओएल वर्शन (जैसे, Python 3.9) के साथ काम करना है, तो आपको फ़ोर्क बनाए रखना होगा.

सबसे सही तरीका:

• वर्शन लॉक करें: टीमों के बीच स्थिरता बनाए रखने के लिए, अपनी इंटरनल बेस इमेज में एसडीके वर्शन पिन करें.

Direct API इंटिग्रेशन

अगर हज़ारों डेवलपर के लिए कोई लाइब्रेरी डिस्ट्रिब्यूट की जा रही है, सीमित एनवायरमेंट में काम किया जा रहा है या ऐसा एग्रीगेटर बनाया जा रहा है जिसके लिए Gemini की नई सुविधाओं की ज़रूरत है, तो आपको REST या gRPC का इस्तेमाल करके, एपीआई के साथ सीधे इंटिग्रेट करना पड़ सकता है.

फ़ायदे:

• सभी सुविधाओं का ऐक्सेस: OpenAI कंपैटबिलिटी लेयर के उलट, एपीआई का सीधे तौर पर इस्तेमाल करने से, Gemini की खास सुविधाएं मिलती हैं. जैसे, File API पर अपलोड करना, कॉन्टेंट कैशिंग बनाना, और Live API का इस्तेमाल करना.
• कम से कम डिपेंडेंसी: ऐसे एनवायरमेंट में जहां साइज़ या ऑडिटिंग की लागत की वजह से, डिपेंडेंसी संवेदनशील होती हैं. fetch जैसी स्टैंडर्ड लाइब्रेरी या httpx जैसे रैपर के ज़रिए, एपीआई का सीधे तौर पर इस्तेमाल करने से, आपकी लाइब्रेरी हल्की बनी रहती है.
• भाषा के हिसाब से कोई पाबंदी नहीं: यह उन भाषाओं के लिए एकमात्र पाथ है जो एसडीके में शामिल नहीं हैं. जैसे, Rust, PHP, और Ruby. ऐसा इसलिए, क्योंकि इन भाषाओं के लिए कोई पाबंदी नहीं है.
• परफ़ॉर्मेंस: Direct API में, इनिशियलाइज़ेशन का कोई ओवरहेड नहीं होता. इससे सर्वरलेस फ़ंक्शन में कोल्ड स्टार्ट कम हो जाते हैं.

नुकसान:

• Gemini Enterprise एजेंट प्लैटफ़ॉर्म को मैन्युअल तरीके से लागू करना: एसडीके के उलट, एपीआई का सीधे तौर पर इस्तेमाल करने से, AI Studio (एपीआई पासकोड) और Gemini Enterprise एजेंट प्लैटफ़ॉर्म (IAM) के बीच ऑथेंटिकेशन के अंतर को अपने-आप हैंडल नहीं किया जाता. अगर आपको दोनों एनवायरमेंट के साथ काम करना है, तो आपको ऑथेंटिकेशन के लिए अलग-अलग हैंडलर लागू करने होंगे.
• कोई नेटिव टाइप या हेल्पर नहीं: अगर इन्हें खुद लागू नहीं किया जाता है, तो अनुरोध ऑब्जेक्ट के लिए, कोड पूरा होने या कंपाइल-टाइम की जांच की सुविधा नहीं मिलती है. क्लाइंट "हेल्पर" (जैसे, फ़ंक्शन-टू-स्कीमा कन्वर्टर) नहीं होते. इसलिए, आपको इस लॉजिक को मैन्युअल तरीके से लिखना होगा.

सबसे सही तरीका

हम मशीन से पढ़े जा सकने वाला स्पेसिफ़िकेशन उपलब्ध कराते हैं. इसका इस्तेमाल करके, अपनी लाइब्रेरी के लिए टाइप की परिभाषाएं जनरेट की जा सकती हैं. इससे आपको इन्हें मैन्युअल तरीके से लिखने की ज़रूरत नहीं पड़ती. बिल्ड प्रोसेस के दौरान, स्पेसिफ़िकेशन डाउनलोड करें, टाइप जनरेट करें, और कंपाइल किया गया कोड शिप करें.

• एंडपॉइंट: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

OpenAI SDK इंटिग्रेशन

अगर आपका प्लैटफ़ॉर्म, मॉडल के हिसाब से सुविधाओं के बजाय यूनिफ़ाइड स्कीमा (OpenAI Chat Completions) को प्राथमिकता देता है, तो यह आपके लिए सबसे तेज़ रास्ता है.

फ़ायदे:

• कम मुश्किल: अक्सर baseURL और apiKey बदलकर, Gemini के लिए सहायता जोड़ी जा सकती है. "अपना पासकोड इस्तेमाल करें" को लागू करने का यह एक तेज़ तरीका है. इससे नया कोड लिखे बिना, Gemini के लिए सहायता जोड़ी जा सकती है.
• सीमाएं: इस पाथ का सुझाव सिर्फ़ तब दिया जाता है, जब OpenAI SDK का इस्तेमाल करने की पाबंदी हो और Gemini की ऐडवांस सुविधाओं की ज़रूरत न हो. जैसे, File API या Google Search के साथ ग्राउंडिंग जैसे टूल के लिए, मैन्युअल तरीके से सहायता जोड़ना.

नुकसान:

• सुविधाओं की सीमाएं: कंपैटबिलिटी लेयर, Gemini की मुख्य क्षमताओं पर सीमाएं लगाती है. प्लैटफ़ॉर्म के हिसाब से, सर्वर-साइड टूल अलग-अलग होते हैं. साथ ही, Gemini API टूल के साथ काम करने के लिए, इन्हें मैन्युअल तरीके से हैंडल करना पड़ सकता है.
• अनुवाद का ओवरहेड: OpenAI स्कीमा, Gemini के आर्किटेक्चर से 1:1 मैप नहीं होता. इसलिए, कंपैटबिलिटी लेयर पर निर्भर रहने से कुछ समस्याएं आती हैं. इन्हें हल करने के लिए, लागू करने से जुड़ा ज़्यादा काम करना पड़ता है. जैसे, उपयोगकर्ता के "खोज" टूल को सही प्लैटफ़ॉर्म टूल पर मैप करना. अगर आपको ज़्यादा मात्रा में खास केसिंग की ज़रूरत है, तो हर प्लैटफ़ॉर्म के लिए, अलग-अलग एसडीके या एपीआई का इस्तेमाल करना ज़्यादा फ़ायदेमंद हो सकता है.

सबसे सही तरीका

जहां तक हो सके, Gemini API के साथ सीधे इंटिग्रेट करें. हालांकि, ज़्यादा से ज़्यादा कंपैटबिलिटी के लिए, ऐसी लाइब्रेरी का इस्तेमाल करें जो अलग-अलग सेवा देने वाली कंपनियों के बारे में जानती हो और आपके लिए टूल और मैसेज मैपिंग को हैंडल कर सकती हो.

सभी पार्टनर के लिए सबसे सही तरीका: क्लाइंट की पहचान करना

प्लैटफ़ॉर्म या लाइब्रेरी के तौर पर, Gemini API को कॉल करते समय, आपको x-goog-api-client हेडर का इस्तेमाल करके, अपने क्लाइंट की पहचान करनी होगी.

इससे Google को आपके ट्रैफ़िक के खास सेगमेंट की पहचान करने में मदद मिलती है. साथ ही, अगर आपकी लाइब्रेरी में कोई खास गड़बड़ी पैटर्न दिख रहा है, तो हम डीबग करने में आपकी मदद कर सकते हैं.

company-product/version फ़ॉर्मैट का इस्तेमाल करें. जैसे, acme-framework/1.2.0.

लागू करने के उदाहरण

from google import genai

client = genai.Client(
    api_key="...",
    http_options={
        "headers": {
            "x-goog-api-client": "acme-framework/1.2.0",
        }
    }
)

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H 'x-goog-api-client: acme-framework/1.2.0' \
    -d '{...}'

from openai import OpenAI

client = OpenAI(
    api_key="...",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
    default_headers={
        "x-goog-api-client": "acme-framework-oai/1.2.0",
    }
)

अगले चरण

• GenAI SDK टूल के बारे में जानने के लिए, लाइब्रेरी की खास जानकारी देखें
• एपीआई का संदर्भ ब्राउज़ करें
• OpenAI कंपैटबिलिटी गाइड पढ़ें