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

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

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

অংশীদার ইন্টিগ্রেশন কী?

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

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

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

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

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

সমষ্টিকারক

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

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

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

এক নজরে তুলনা

বিশ্বব্যাপী সর্বোত্তম অনুশীলন: সমস্ত অংশীদারদের অবশ্যই x-goog-api-client হেডার পাঠাতে হবে, বেছে নেওয়া পথ নির্বিশেষে।

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

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

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

সুবিধা:

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

বিনিময়:

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

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

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

সরাসরি API ইন্টিগ্রেশন

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

সুবিধা:

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

বিনিময়:

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

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

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

• শেষবিন্দু: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

OpenAI SDK ইন্টিগ্রেশন

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

সুবিধা:

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

বিনিময়:

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

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

সম্ভব হলে, সরাসরি জেমিনি এপিআই-এর সাথে ইন্টিগ্রেট করুন। তবে সর্বাধিক সামঞ্জস্যের জন্য এমন একটি লাইব্রেরি ব্যবহার করার কথা বিবেচনা করুন যা বিভিন্ন প্রদানকারী সম্পর্কে সচেতন এবং আপনার জন্য টুল এবং বার্তা ম্যাপিং পরিচালনা করতে পারে।

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

প্ল্যাটফর্ম বা লাইব্রেরি হিসেবে জেমিনি 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-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 সম্পর্কে জানতে লাইব্রেরির ওভারভিউ দেখুন।
• API রেফারেন্স ব্রাউজ করুন
• OpenAI সামঞ্জস্য নির্দেশিকাটি পড়ুন।