অংশীদার এবং লাইব্রেরি ইন্টিগ্রেশন

এই নির্দেশিকাটি জেমিনি এপিআই (Gemini API)-এর উপর ভিত্তি করে লাইব্রেরি, প্ল্যাটফর্ম এবং গেটওয়ে তৈরির স্থাপত্যগত কৌশলগুলির রূপরেখা দেয়। এটি অফিসিয়াল জেনএআই এসডিকে (GenAI SDK), ডিরেক্ট এপিআই (Direct API) (REST/gRPC) এবং ওপেনএআই কম্প্যাটিবিলিটি লেয়ার (OpenAI compatibility layer) ব্যবহারের মধ্যেকার প্রযুক্তিগত সুবিধা-অসুবিধাগুলো বিস্তারিতভাবে বর্ণনা করে।

আপনি যদি অন্যান্য ডেভেলপারদের জন্য ওপেন-সোর্স ফ্রেমওয়ার্ক, এন্টারপ্রাইজ গেটওয়ে বা SaaS অ্যাগ্রিগেটরের মতো টুল তৈরি করেন এবং ডিপেন্ডেন্সি হাইজিন, বান্ডেল সাইজ বা ফিচার প্যারিটির জন্য অপটিমাইজ করার প্রয়োজন হয়, তাহলে এই গাইডটি ব্যবহার করুন।

অংশীদার একীকরণ বলতে কী বোঝায়?

যিনি জেমিনি এপিআই এবং এন্ড-ইউজার ডেভেলপারদের মধ্যে ইন্টিগ্রেশন তৈরি করেন, তিনিই পার্টনার। আমরা পার্টনারদের চারটি আর্কিটাইপে ভাগ করি। আপনার সাথে কোনটি সবচেয়ে বেশি মেলে তা শনাক্ত করা আপনাকে সঠিক ইন্টিগ্রেশন পথ বেছে নিতে সাহায্য করবে।

বাস্তুতন্ত্রের কাঠামো

• আপনার পরিচয়: কোনো ওপেন-সোর্স ফ্রেমওয়ার্ক (যেমন, LangChain, LlamaIndex, Spring AI) অথবা ভাষা-নির্দিষ্ট ক্লায়েন্টের রক্ষণাবেক্ষণকারী।
• আপনার লক্ষ্য: ব্যাপক সামঞ্জস্যতা। আপনি চান আপনার লাইব্রেরিটি ব্যবহারকারীর পছন্দের যেকোনো পরিবেশে কোনো রকম সংঘাত সৃষ্টি না করেই কাজ করুক।

রানটাইম এবং এজ প্ল্যাটফর্ম

• আপনি কারা: SaaS প্ল্যাটফর্ম, AI গেটওয়ে, বা ক্লাউড অবকাঠামো প্রদানকারী (যেমন, Vercel, Cloudflare, Zapier) যেখানে সীমাবদ্ধ পরিবেশে কোড নির্বাহ হয়।
• আপনার লক্ষ্য: পারফরম্যান্স। আপনার প্রয়োজন কম ল্যাটেন্সি, ন্যূনতম বান্ডেল সাইজ এবং দ্রুত কোল্ড স্টার্ট।

অ্যাগ্রিগেটর

• আপনার পরিচয়: প্ল্যাটফর্ম, প্রক্সি, বা অভ্যন্তরীণ "মডেল গার্ডেন" যা বিভিন্ন এলএলএম প্রদানকারীর (যেমন ওপেনএআই, অ্যানথ্রোপিক, গুগল) অ্যাক্সেসকে একটি একক ইন্টারফেসে স্বাভাবিক করে তোলে।
• আপনার লক্ষ্য: বহনযোগ্যতা এবং অভিন্নতা।

এন্টারপ্রাইজ গেটওয়ে

• আপনার পরিচয়: বড় কোম্পানিগুলোর অভ্যন্তরীণ প্ল্যাটফর্ম ইঞ্জিনিয়ারিং টিম, যারা শত শত অভ্যন্তরীণ ডেভেলপারের জন্য 'গোল্ডেন পাথ' তৈরি করে।
• আপনার লক্ষ্য: মানসম্মতকরণ, সুশাসন এবং সমন্বিত প্রমাণীকরণ।

এক নজরে তুলনা

বিশ্বব্যাপী সর্বোত্তম রীতি: নির্বাচিত পাথ নির্বিশেষে সকল পার্টনারকে অবশ্যই x-goog-api-client হেডারটি পাঠাতে হবে।

গুগল জেনএআই এসডিকে ইন্টিগ্রেশন

ফ্রেমওয়ার্কগুলোর ক্ষেত্রে, গুগল জেনএআই এসডিকে (Google GenAI SDK) প্রয়োগ করাই প্রায়শই সবচেয়ে সহজ উপায়, কারণ এতে সমর্থিত ভাষাগুলোতে সবচেয়ে কম সংখ্যক কোড লিখতে হয়।

অভ্যন্তরীণ প্ল্যাটফর্ম দলগুলোর জন্য, আপনার প্রধান অর্পণযোগ্য কাজটি প্রায়শই একটি "সুবর্ণ পথ" হয়ে থাকে, যা প্রোডাক্ট ইঞ্জিনিয়ারদের নিরাপত্তা নীতিমালা মেনে চলার পাশাপাশি দ্রুত কাজ করতে সাহায্য করে।

সুবিধাসমূহ:

• জেমিনি এন্টারপ্রাইজ এজেন্ট প্ল্যাটফর্ম মাইগ্রেশনের জন্য সমন্বিত ইন্টারফেস: অভ্যন্তরীণ ডেভেলপাররা প্রায়শই এপিআই কী (জেমিনি এপিআই) ব্যবহার করে প্রোটোটাইপ তৈরি করেন এবং প্রোডাকশন কমপ্লায়েন্সের জন্য জেমিনি এন্টারপ্রাইজ এজেন্ট প্ল্যাটফর্মে (আইএএম) তা ডেপ্লয় করেন। এই এসডিকে অথেনটিকেশনের পার্থক্যগুলোকে অ্যাবস্ট্রাক্ট করে। একইভাবে ফ্রেমওয়ার্কগুলোর ক্ষেত্রেও, আপনি একটি কোডপাথ ইমপ্লিমেন্ট করে দুই ধরনের ব্যবহারকারীকে সাপোর্ট দিতে পারেন।
• ক্লায়েন্ট-সাইড হেল্পার: এসডিকে-তে এমন কিছু প্রচলিত ইউটিলিটি অন্তর্ভুক্ত রয়েছে যা জটিল কাজের জন্য গতানুগতিক কোড লেখা কমিয়ে দেয়।
  • উদাহরণস্বরূপ: প্রম্পটে সরাসরি PIL ইমেজ অবজেক্ট সমর্থন করা, স্বয়ংক্রিয় ফাংশন কলিং, এবং কম্প্রিহেনসিভ টাইপ।
• প্রথম দিন থেকেই ফিচার অ্যাক্সেস: নতুন API ফিচারগুলো SDK-এর মাধ্যমে লঞ্চের সময় থেকেই পাওয়া যায়।
• উন্নত কোড জেনারেশন সাপোর্ট: লোকাল SDK ইনস্টলেশন কোডিং অ্যাসিস্ট্যান্টদের (যেমন, Cursor, Copilot) কাছে টাইপ ডেফিনিশন এবং ডকস্ট্রিং উন্মুক্ত করে। সরাসরি REST রিকোয়েস্ট জেনারেট করার তুলনায় এই কনটেক্সট কোড জেনারেশনের নির্ভুলতা বাড়ায়।

বিনিময়:

• নির্ভরশীলতার ভার ও জটিলতা: SDK-গুলোর নিজস্ব নির্ভরশীলতা থাকে, যা বান্ডেলের আকার এবং সম্ভাব্য সরবরাহ-শৃঙ্খল ঝুঁকি বাড়াতে পারে।
• ভার্সনিং: নতুন API ফিচারগুলো প্রায়শই সর্বনিম্ন SDK ভার্সনের সাথে সংযুক্ত থাকে। নতুন ফিচার বা মডেল অ্যাক্সেস করার জন্য আপনাকে ব্যবহারকারীদের কাছে আপডেট পাঠাতে হতে পারে, যার জন্য কিছু ক্ষেত্রে এমন ট্রানজিটিভ ডিপেন্ডেন্সিতে পরিবর্তন আনার প্রয়োজন হতে পারে যা আপনার ব্যবহারকারীদের প্রভাবিত করে।
• প্রোটোকল সীমাবদ্ধতা: SDK-গুলো শুধুমাত্র মূল API-এর জন্য HTTPS এবং Live API-এর জন্য WebSockets (WSS) সমর্থন করে। উচ্চ-স্তরের SDK ক্লায়েন্ট ব্যবহার করে gRPC সমর্থিত নয়।
• ভাষা সমর্থন: SDK-গুলো বর্তমান ভাষার সংস্করণগুলো সমর্থন করে। যদি আপনাকে EOL (এন্ড-অফ-লাইফ) সংস্করণ (যেমন, পাইথন ৩.৯) সমর্থন করতে হয়, তবে আপনাকে একটি ফর্ক রক্ষণাবেক্ষণ করতে হবে।

সর্বোত্তম অনুশীলন:

• ভার্সন লক করুন: বিভিন্ন টিমের মধ্যে স্থিতিশীলতা নিশ্চিত করতে আপনার অভ্যন্তরীণ বেস ইমেজগুলিতে SDK ভার্সনটি পিন করে দিন।

সরাসরি এপিআই ইন্টিগ্রেশন

যদি আপনি হাজার হাজার ডেভেলপারের কাছে কোনো লাইব্রেরি বিতরণ করেন, একটি সীমাবদ্ধ পরিবেশে কাজ চালান, অথবা এমন কোনো অ্যাগ্রিগেটর তৈরি করেন যার জন্য জেমিনির সর্বাধুনিক ফিচারগুলোর প্রয়োজন, তাহলে আপনার REST বা gRPC ব্যবহার করে সরাসরি API-এর সাথে ইন্টিগ্রেট করার প্রয়োজন হতে পারে।

সুবিধাসমূহ:

• সম্পূর্ণ ফিচার অ্যাক্সেস: OpenAI কম্প্যাটিবিলিটি লেয়ারের বিপরীতে, সরাসরি API ব্যবহার করে জেমিনি-নির্দিষ্ট ফিচারগুলো সক্রিয় করা যায়, যেমন ফাইল API-তে আপলোড করা, কন্টেন্ট ক্যাশিং তৈরি করা এবং দ্বি-মুখী লাইভ API ব্যবহার করা।
• ন্যূনতম নির্ভরতা: এমন পরিবেশে যেখানে আকার বা নিরীক্ষা খরচের কারণে নির্ভরতাগুলো সংবেদনশীল, সেখানে fetch মতো একটি স্ট্যান্ডার্ড লাইব্রেরির মাধ্যমে সরাসরি অথবা httpx মতো একটি র‍্যাপারের মাধ্যমে API ব্যবহার করা আপনার লাইব্রেরিকে হালকা রাখতে সাহায্য করে।
• ভাষা নিরপেক্ষ: যেসব ভাষা SDK-এর অন্তর্ভুক্ত নয়, যেমন Rust, PHP, এবং Ruby, তাদের জন্য এটিই একমাত্র পথ, কারণ এক্ষেত্রে ভাষার কোনো সীমাবদ্ধতা নেই।
• পারফরম্যান্স: ডিরেক্ট এপিআই-এর কোনো ইনিশিয়ালাইজেশন ওভারহেড নেই, ফলে সার্ভারলেস ফাংশনগুলোতে কোল্ড স্টার্ট কমে যায়।

বিনিময়:

• ম্যানুয়াল জেমিনি এন্টারপ্রাইজ এজেন্ট প্ল্যাটফর্ম ইমপ্লিমেন্টেশন: SDK-এর মতো নয়, সরাসরি API ব্যবহার করলে AI Studio (API Key) এবং জেমিনি এন্টারপ্রাইজ এজেন্ট প্ল্যাটফর্ম (IAM)-এর মধ্যেকার অথেনটিকেশনের পার্থক্যগুলো স্বয়ংক্রিয়ভাবে হ্যান্ডেল হয় না। আপনি যদি উভয় এনভায়রনমেন্টকে সাপোর্ট করতে চান, তবে আপনাকে আলাদা অথ হ্যান্ডলার ইমপ্লিমেন্ট করতে হবে।
• কোনো নেটিভ টাইপ বা হেল্পার নেই: আপনি রিকোয়েস্ট অবজেক্টের জন্য কোড কমপ্লিশন বা কম্পাইল-টাইম চেক পাবেন না, যদি না আপনি নিজে সেগুলো ইমপ্লিমেন্ট করেন। কোনো ক্লায়েন্ট "হেল্পার" (যেমন, ফাংশন-টু-স্কিমা কনভার্টার) নেই, তাই আপনাকে এই লজিকটি নিজে হাতে লিখতে হবে।

সর্বোত্তম অনুশীলন

আমরা একটি মেশিন-পঠনযোগ্য স্পেসিফিকেশন প্রদান করি যা ব্যবহার করে আপনি আপনার লাইব্রেরির জন্য টাইপ ডেফিনিশন তৈরি করতে পারেন, ফলে আপনাকে হাতে লিখে তা তৈরি করার প্রয়োজন হয় না। আপনার বিল্ড প্রক্রিয়ার সময় স্পেকটি ডাউনলোড করুন, টাইপগুলো তৈরি করুন এবং কম্পাইল করা কোডটি সরবরাহ করুন।

• এন্ডপয়েন্ট: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

ওপেনএআই এসডিকে ইন্টিগ্রেশন

আপনি যদি এমন একটি প্ল্যাটফর্ম হন যা মডেল-নির্দিষ্ট বৈশিষ্ট্যের চেয়ে একটি সমন্বিত স্কিমাকে (OpenAI Chat Completions) অগ্রাধিকার দেয়, তবে এটিই আপনার জন্য দ্রুততম পথ।

সুবিধাসমূহ:

• ঝামেলাহীন: আপনি প্রায়শই baseURL এবং apiKey পরিবর্তন করে Gemini সাপোর্ট যোগ করতে পারেন। এটি 'Bring Your Own Key' ইমপ্লিমেন্টেশনগুলিকে ইন্টিগ্রেট করার একটি দ্রুত উপায়, যার মাধ্যমে নতুন কোনো কোড না লিখেই Gemini সাপোর্ট যোগ করা যায়।
• সীমাবদ্ধতা: এই পথটি কেবল তখনই সুপারিশ করা হয়, যদি আপনি OpenAI SDK-এর মধ্যে সীমাবদ্ধ থাকেন এবং File API-এর মতো উন্নত Gemini ফিচারের প্রয়োজন না হয়, অথবা Grounding with Google Search-এর মতো টুলের জন্য ম্যানুয়ালি সাপোর্ট যোগ করার প্রয়োজন না হয়।

বিনিময়:

• বৈশিষ্ট্যের সীমাবদ্ধতা: সামঞ্জস্য স্তরটি জেমিনির মূল কার্যক্ষমতার উপর সীমাবদ্ধতা আরোপ করে। উপলব্ধ সার্ভার-সাইড টুলগুলো প্ল্যাটফর্মভেদে ভিন্ন হয়, এবং জেমিনি এপিআই টুলগুলোর সাথে কাজ করার জন্য ম্যানুয়াল পরিচালনার প্রয়োজন হতে পারে।
• অনুবাদের অতিরিক্ত কাজ: যেহেতু OpenAI স্কিমা জেমিনির আর্কিটেকচারের সাথে হুবহু মেলে না, তাই কম্প্যাটিবিলিটি লেয়ারের উপর নির্ভর করলে কিছু জটিলতা দেখা দেয়, যা সমাধানের জন্য অতিরিক্ত বাস্তবায়নের কাজ প্রয়োজন হয়; যেমন, ব্যবহারকারীর 'সার্চ' টুলকে সঠিক প্ল্যাটফর্ম টুলের সাথে মেলানো। যদি আপনার উল্লেখযোগ্য পরিমাণে বিশেষ বিবেচনার প্রয়োজন হয়, তবে প্রতিটি প্ল্যাটফর্মের জন্য একটি ডেডিকেটেড SDK বা API ব্যবহার করা আরও বেশি সুবিধাজনক হতে পারে।

সর্বোত্তম অনুশীলন

যেখানে সম্ভব, সরাসরি জেমিনি এপিআই (Gemini API)-এর সাথে ইন্টিগ্রেট করুন। তবে সর্বোচ্চ সামঞ্জস্যতার জন্য এমন একটি লাইব্রেরি ব্যবহার করার কথা বিবেচনা করুন যা বিভিন্ন প্রোভাইডার সম্পর্কে অবগত এবং আপনার হয়ে টুল ও মেসেজ ম্যাপিং পরিচালনা করতে পারে।

সকল অংশীদারদের জন্য সর্বোত্তম অনুশীলন: ক্লায়েন্ট শনাক্তকরণ

প্ল্যাটফর্ম বা লাইব্রেরি হিসেবে জেমিনি এপিআই-তে কল করার সময়, আপনাকে অবশ্যই x-goog-api-client হেডার ব্যবহার করে আপনার ক্লায়েন্টকে শনাক্ত করতে হবে।

এর মাধ্যমে গুগল আপনার নির্দিষ্ট ট্র্যাফিক সেগমেন্টগুলো শনাক্ত করতে পারে, এবং আপনার লাইব্রেরিটি যদি কোনো নির্দিষ্ট ধরনের ত্রুটি তৈরি করে, তবে আমরা ডিবাগ করতে সাহায্যের জন্য আপনার সাথে যোগাযোগ করতে পারি।

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-flash-preview: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 সামঞ্জস্যতা নির্দেশিকাটি পড়ুন