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

इस गाइड में, 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 को लागू करना अक्सर सबसे आसान तरीका होता है. ऐसा इसलिए, क्योंकि इसमें काम करने वाली भाषाओं में कोड की सबसे कम लाइनें होती हैं.

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

फ़ायदे:

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

ट्रेड-ऑफ़:

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

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

• वर्शन लॉक करना: अपनी इंटरनल बेस इमेज में एसडीके के वर्शन को पिन करें, ताकि सभी टीमों के लिए एक जैसा वर्शन उपलब्ध रहे.

एपीआई का सीधे तौर पर इंटिग्रेशन

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

फ़ायदे:

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

ट्रेड-ऑफ़:

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

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

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

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

OpenAI SDK टूल का इंटिग्रेशन

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

फ़ायदे:

• आसानी से इस्तेमाल किया जा सकता है: baseURL और apiKey में बदलाव करके, Gemini की सुविधा को आसानी से जोड़ा जा सकता है. यह "Bring Your Own Key" को इंटिग्रेट करने का तेज़ तरीका है. इससे नया कोड लिखे बिना, 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-2.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 के साथ काम करने से जुड़ी गाइड पढ़ें