ادغام شرکا و کتابخانه‌ها

این راهنما، استراتژی‌های معماری برای ساخت کتابخانه‌ها، پلتفرم‌ها و دروازه‌ها بر روی رابط برنامه‌نویسی Gemini را تشریح می‌کند. این راهنما جزئیات مربوط به بده‌بستان‌های فنی بین استفاده از SDKهای رسمی GenAI، رابط برنامه‌نویسی کاربردی مستقیم (REST/gRPC) و لایه سازگاری OpenAI را شرح می‌دهد.

اگر در حال ساخت ابزارهایی برای سایر توسعه‌دهندگان، مانند چارچوب‌های متن‌باز، دروازه‌های سازمانی یا تجمیع‌کننده‌های SaaS هستید و نیاز به بهینه‌سازی برای سلامت وابستگی، اندازه بسته یا برابری ویژگی‌ها دارید، از این راهنما استفاده کنید.

ادغام شرکا چیست؟

شریک به هر کسی گفته می‌شود که بین رابط برنامه‌نویسی کاربردی Gemini و توسعه‌دهندگان کاربر نهایی، یکپارچه‌سازی ایجاد می‌کند. ما شرکا را به چهار نمونه اولیه طبقه‌بندی می‌کنیم. شناسایی اینکه کدام یک از آنها بیشترین تطابق را با شما دارد، به شما در انتخاب مسیر یکپارچه‌سازی مناسب کمک خواهد کرد.

چارچوب اکوسیستم

  • شما چه کسی هستید: نگهدارنده یک چارچوب متن‌باز (مثلاً LangChain، LlamaIndex، Spring AI) یا کلاینت‌های مختص زبان.
  • هدف شما: سازگاری گسترده. شما می‌خواهید کتابخانه‌تان در هر محیطی که کاربر انتخاب می‌کند، بدون ایجاد تداخل، کار کند.

زمان اجرا و پلتفرم لبه

  • شما چه کسی هستید: پلتفرم‌های SaaS، دروازه‌های هوش مصنوعی یا ارائه‌دهندگان زیرساخت ابری (مثلاً Vercel، Cloudflare، Zapier) که در آن‌ها اجرای کد در محیط‌های محدود انجام می‌شود.
  • هدف شما: عملکرد. شما به تأخیر کم، حداقل اندازه بسته نرم‌افزاری و شروع سریع و بدون وقفه نیاز دارید.

جمع کننده

  • شما چه کسی هستید: پلتفرم‌ها، پروکسی‌ها یا «باغ‌های مدل» داخلی که دسترسی را در بین بسیاری از ارائه‌دهندگان مختلف LLM (مانند OpenAI، Anthropic، Google) به یک رابط واحد عادی می‌کنند.
  • هدف شما: قابلیت حمل و یکنواختی.

دروازه سازمانی

  • شما چه کسی هستید: تیم‌های مهندسی پلتفرم داخلی در شرکت‌های بزرگ که «مسیرهای طلایی» را برای صدها توسعه‌دهنده داخلی می‌سازند.
  • هدف شما: استانداردسازی، مدیریت و احراز هویت یکپارچه.

مقایسه در یک نگاه

بهترین شیوه جهانی: همه شرکا باید هدر x-goog-api-client را صرف نظر از مسیر انتخاب شده ارسال کنند.

اگر شما ... هستید مسیر پیشنهادی مزیت کلیدی بده‌بستان کلیدی بهترین شیوه
دروازه سازمانی، چارچوب اکوسیستم کیت توسعه نرم‌افزاری GenAI گوگل برابری و سرعت رأس‌ها. مدیریت داخلی برای انواع، احراز هویت و ویژگی‌های پیچیده (مثلاً آپلود فایل). مهاجرت یکپارچه به فضای ابری گوگل. وزن وابستگی. وابستگی‌های انتقالی می‌توانند پیچیده و خارج از کنترل شما باشند. محدود به زبان‌های پشتیبانی‌شده (Python/Node/Go/Java). قفل کردن نسخه‌ها. نسخه‌های SDK را در ایمیج‌های پایه داخلی خود پین کنید تا از پایداری در بین تیم‌ها اطمینان حاصل شود.
چارچوب اکوسیستم، پلتفرم‌های لبه‌ای و تجمیع‌کننده‌ها رابط برنامه‌نویسی کاربردی مستقیم

(REST / gRPC)		 بدون وابستگی. شما می‌توانید کلاینت HTTP و اندازه دقیق بسته را کنترل کنید. دسترسی کامل به تمام APIها و ویژگی‌های مدل. سربار بالای توسعه‌دهنده. ساختارهای JSON می‌توانند عمیقاً تو در تو باشند و نیاز به اعتبارسنجی دستی دقیق و بررسی نوع دارند. از مشخصات OpenAPI استفاده کنید. تولید نوع را با استفاده از مشخصات رسمی ما به صورت خودکار انجام دهید، به جای اینکه آنها را با دست بنویسید.
تجمیع‌کننده با استفاده از OpenAI SDKهایی که فقط به گردش‌های کاری مبتنی بر متن نیاز دارند

(بهینه‌سازی برای قابلیت حمل قدیمی)		 سازگاری با OpenAI قابلیت حمل فوری. استفاده مجدد از کد یا کتابخانه‌های موجود سازگار با OpenAI. سقف ویژگی. ویژگی‌های خاص مدل (فیلم بومی، ذخیره‌سازی) ممکن است در دسترس نباشند. طرح مهاجرت. از این برای اعتبارسنجی سریع استفاده کنید، اما برای استفاده از ویژگی‌های کامل API، قصد دارید آن را به Direct API ارتقا دهید.

ادغام با Google GenAI SDK

برای چارچوب‌ها، پیاده‌سازی Google GenAI SDK اغلب ساده‌ترین مسیر است، با توجه به کمترین تعداد خطوط کد در زبان‌های پشتیبانی‌شده.

برای تیم‌های پلتفرم داخلی، دستاورد اصلی شما اغلب یک «مسیر طلایی» است که به مهندسان محصول اجازه می‌دهد ضمن رعایت سیاست‌های امنیتی، سریع حرکت کنند.

مزایا:

  • رابط یکپارچه برای مهاجرت هوش مصنوعی Vertex: توسعه‌دهندگان داخلی اغلب با استفاده از کلیدهای API (Gemini API) نمونه اولیه را ایجاد می‌کنند و برای انطباق با محیط تولید، آن را در Vertex AI (IAM) مستقر می‌کنند. SDK این تفاوت‌های احراز هویت را خلاصه می‌کند. به طور مشابه برای چارچوب‌ها، می‌توانید یک مسیر کد را پیاده‌سازی کنید و از دو مجموعه کاربر پشتیبانی کنید.
  • کمک‌کننده‌های سمت کلاینت: SDK شامل ابزارهای اصطلاحی است که کدهای تکراری را برای کارهای پیچیده کاهش می‌دهد.
    • مثال‌ها: پشتیبانی از اشیاء تصویر PIL به طور مستقیم در اعلان‌ها، فراخوانی خودکار تابع و انواع جامع.
  • دسترسی به ویژگی‌های روز صفر: ویژگی‌های جدید API در زمان عرضه از طریق SDKها در دسترس هستند.
  • پشتیبانی بهبود یافته از تولید کد: نصب SDK محلی، تعاریف نوع و رشته‌های مستندات را در اختیار دستیاران کدنویسی (مثلاً Cursor، Copilot) قرار می‌دهد. این زمینه، دقت تولید کد را در مقایسه با تولید درخواست‌های خام REST بهبود می‌بخشد.

معامله:

  • وزن و پیچیدگی وابستگی: SDKها وابستگی‌های خاص خود را دارند که می‌تواند اندازه بسته و ریسک بالقوه زنجیره تأمین را افزایش دهد.
  • نسخه‌بندی: ویژگی‌های جدید API اغلب به حداقل نسخه‌های SDK پین می‌شوند. ممکن است لازم باشد برای دسترسی به ویژگی‌ها یا مدل‌های جدید، به‌روزرسانی‌هایی را برای کاربران ارسال کنید که در برخی موارد ممکن است نیاز به تغییراتی در وابستگی‌های انتقالی داشته باشد که بر کاربران شما تأثیر می‌گذارد.
  • محدودیت‌های پروتکل: SDKها فقط از HTTPS برای API اصلی و WebSockets (WSS) برای API زنده پشتیبانی می‌کنند. gRPC با استفاده از کلاینت‌های SDK سطح بالا پشتیبانی نمی‌شود.
  • پشتیبانی از زبان: SDK ها از نسخه‌های فعلی زبان پشتیبانی می‌کنند. اگر نیاز به پشتیبانی از نسخه‌های EOL (مثلاً پایتون ۳.۹) دارید، باید یک انشعاب (fork) ایجاد کنید.

بهترین روش:

  • قفل کردن نسخه‌ها: نسخه SDK را در ایمیج‌های پایه داخلی خود پین کنید تا از پایداری در بین تیم‌ها اطمینان حاصل شود.

ادغام مستقیم API

اگر در حال توزیع یک کتابخانه بین هزاران توسعه‌دهنده هستید، در یک محیط محدود اجرا می‌کنید، یا یک تجمیع‌کننده می‌سازید که به ویژگی‌های پیشرفته Gemini نیاز دارد، ممکن است نیاز داشته باشید که مستقیماً با استفاده از REST یا gRPC با API ادغام شوید.

مزایا:

  • دسترسی کامل به ویژگی‌ها: برخلاف لایه سازگاری OpenAI، استفاده از API مستقیماً ویژگی‌های خاص Gemini مانند آپلود در File API، ایجاد ذخیره‌سازی محتوا و استفاده از Live API دو طرفه را فعال می‌کند.
  • حداقل وابستگی‌ها: در محیطی که وابستگی‌ها به دلیل اندازه یا هزینه‌های حسابرسی حساس هستند، استفاده مستقیم از API از طریق یک کتابخانه استاندارد مانند fetch یا از طریق یک wrapper مانند httpx تضمین می‌کند که کتابخانه شما سبک باقی بماند.
  • زبان‌های برنامه‌نویسی: این تنها مسیر برای زبان‌هایی است که توسط SDKها پشتیبانی نمی‌شوند، مانند Rust، PHP و Ruby، زیرا هیچ محدودیت زبانی وجود ندارد.
  • عملکرد: API مستقیم هیچ سربار اولیه‌سازی ندارد و شروع‌های سرد را در توابع بدون سرور به حداقل می‌رساند.

معامله:

  • پیاده‌سازی دستی هوش مصنوعی Vertex: برخلاف SDK، استفاده مستقیم از API به طور خودکار تفاوت‌های احراز هویت بین AI Studio (کلید API) و Vertex AI (IAM) را مدیریت نمی‌کند. اگر می‌خواهید از هر دو محیط پشتیبانی کنید، باید کنترل‌کننده‌های احراز هویت جداگانه‌ای پیاده‌سازی کنید.
  • بدون انواع یا کمکی‌های بومی: شما تکمیل کد یا بررسی‌های زمان کامپایل برای اشیاء درخواست را دریافت نمی‌کنید، مگر اینکه خودتان آنها را پیاده‌سازی کنید. هیچ "کمکی" برای کلاینت وجود ندارد (مثلاً مبدل‌های تابع به طرحواره)، بنابراین باید خودتان این منطق را به صورت دستی بنویسید.

بهترین شیوه

ما یک مشخصات قابل خواندن توسط ماشین ارائه می‌دهیم که می‌توانید از آن برای تولید تعاریف نوع برای کتابخانه خود استفاده کنید و از نوشتن دستی آنها جلوگیری کنید. مشخصات را در طول فرآیند ساخت خود دانلود کنید، انواع را تولید کنید و کد کامپایل شده را ارسال کنید.

  • نقطه پایانی: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

ادغام OpenAI SDK

اگر شما پلتفرمی هستید که طرح یکپارچه (OpenAI Chat Completions) را بر ویژگی‌های خاص مدل اولویت می‌دهد، این سریع‌ترین مسیر شماست.

مزایا:

  • اصطکاک کم: شما اغلب می‌توانید با تغییر baseURL و apiKey پشتیبانی Gemini را اضافه کنید. این یک روش سریع برای ادغام پیاده‌سازی‌های «کلید خودتان را بیاورید» است و پشتیبانی Gemini را بدون نوشتن کد جدید اضافه می‌کند.
  • محدودیت‌ها: این مسیر فقط در صورتی توصیه می‌شود که به OpenAI SDK محدود شده باشید و به ویژگی‌های پیشرفته Gemini مانند File API یا افزودن دستی پشتیبانی از ابزارهایی مانند Grounding with Google Search نیازی نداشته باشید.

معامله:

  • محدودیت‌های ویژگی: لایه سازگاری محدودیت‌هایی را برای قابلیت‌های اصلی Gemini ایجاد می‌کند. ابزارهای سمت سرور موجود بین پلتفرم‌ها متفاوت هستند و ممکن است برای کار با ابزارهای API Gemini نیاز به مدیریت دستی داشته باشند.
  • سربار ترجمه: از آنجا که طرح OpenAI به صورت ۱:۱ با معماری Gemini نگاشت نمی‌شود، تکیه بر لایه سازگاری، پیچیدگی‌هایی را ایجاد می‌کند که نیاز به کار پیاده‌سازی اضافی برای حل دارند، مانند نگاشت ابزار «جستجوی» کاربر به ابزار پلتفرم مناسب. اگر به مقدار قابل توجهی از موارد خاص نیاز دارید، ممکن است استفاده از یک SDK یا API اختصاصی برای هر پلتفرم ارزش بیشتری داشته باشد.

بهترین روش

در صورت امکان، مستقیماً با API Gemini ادغام شوید. با این حال، برای حداکثر سازگاری، استفاده از کتابخانه‌ای را در نظر بگیرید که از ارائه‌دهندگان مختلف آگاه باشد و بتواند نگاشت ابزار و پیام را برای شما مدیریت کند.

بهترین روش برای همه شرکا: شناسایی مشتری

هنگام فراخوانی API Gemini به عنوان یک پلتفرم یا کتابخانه، باید کلاینت خود را با استفاده از هدر x-goog-api-client شناسایی کنید.

این به گوگل اجازه می‌دهد بخش‌های خاص ترافیک شما را شناسایی کند، و اگر کتابخانه شما الگوی خطای خاصی را تولید می‌کند، می‌توانیم برای کمک به رفع اشکال با شما تماس بگیریم.

از قالب company-product/version استفاده کنید (مثلاً acme-framework/1.2.0 ).

نمونه‌های پیاده‌سازی

کیت توسعه نرم‌افزاری GenAI

با ارائه کلاینت API، SDK به طور خودکار هدر سفارشی شما را به هدرهای داخلی خود اضافه می‌کند.

from google import genai

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

API مستقیم (REST) 

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 '{...}'

کیت توسعه نرم‌افزاری OpenAI 

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",
    }
)

مراحل بعدی