عمليات الدمج مع الشركاء والمكتبات

يقدّم هذا الدليل استراتيجيات معمارية لإنشاء مكتبات ومنصات وبوابات استنادًا إلى Gemini API. ويقدّم هذا الدرس تفاصيل حول المفاضلات الفنية بين استخدام حِزم تطوير البرامج (SDK) الرسمية للذكاء الاصطناعي التوليدي وDirect API (REST/gRPC) وطبقة التوافق مع OpenAI.

استخدِم هذا الدليل إذا كنت بصدد إنشاء أدوات لمطوّرين آخرين، مثل أُطر عمل مفتوحة المصدر أو بوابات المؤسسات أو أدوات تجميع البرامج كخدمة (SaaS)، وكنت بحاجة إلى تحسينها من حيث سلامة التبعيات أو حجم الحِزمة أو تكافؤ الميزات.

ما هو دمج الشريك؟

الشريك هو أي شخص يعمل على إنشاء عملية دمج بين Gemini API والمطوّرين من المستخدمين النهائيين. نصنّف الشركاء إلى أربعة نماذج أولية. سيساعدك تحديد النوع الذي يتطابق مع حالتك بشكلٍ كبير في اختيار مسار الدمج المناسب.

إطار عمل المنظومة المتكاملة

• هويتك: أنت المسؤول عن صيانة إطار عمل مفتوح المصدر (مثل LangChain أو LlamaIndex أو Spring AI) أو برامج عملاء خاصة بلغة معيّنة.
• هدفكم: التوافق على نطاق واسع يجب أن تعمل المكتبة في أي بيئة يختارها المستخدم بدون فرض تعارضات.

بيئة التشغيل ومنصّة الحافة

• الجهات التي تمثّلها: منصات البرامج كخدمة أو بوابات الذكاء الاصطناعي أو مقدّمو خدمات البنية التحتية السحابية (مثل Vercel أو Cloudflare أو Zapier) حيث يتم تنفيذ الرموز البرمجية في بيئات مقيّدة
• هدفكم: الأداء يجب أن يكون وقت الاستجابة منخفضًا، وحجم الحِزمة صغيرًا، وأن يكون التشغيل المجرّد سريعًا.

موقع تجميع

• هويتك: المنصات أو الخوادم الوكيلة أو "حدائق النماذج" الداخلية التي تتيح الوصول الموحّد إلى العديد من موفّري النماذج اللغوية الكبيرة المختلفة (مثل OpenAI وAnthropic وGoogle) من خلال واجهة واحدة.
• هدفكم: إمكانية النقل والتوافق

بوابة المؤسسة

• نوع المستخدم: فِرق هندسة المنصات الداخلية في الشركات الكبيرة التي تنشئ "مسارات ذهبية" لمئات المطوّرين الداخليين.
• هدفك: التوحيد والحوكمة والمصادقة الموحّدة

مقارنة سريعة

أفضل الممارسات على مستوى العالم: يجب أن يرسل جميع الشركاء عنوان x-goog-api-client بغض النظر عن المسار الذي تم اختياره.

دمج حزمة تطوير البرامج (SDK) للذكاء الاصطناعي التوليدي من Google

بالنسبة إلى الأُطر، غالبًا ما يكون تنفيذ حزمة تطوير البرامج (SDK) من Google للذكاء الاصطناعي التوليدي هو أبسط مسار، وذلك لأنّه يتضمّن أقل عدد من أسطر الرمز في اللغات المتوافقة.

بالنسبة إلى فِرق المنصات الداخلية، يكون المنتج الأساسي الذي تقدّمه غالبًا هو "المسار الذهبي" الذي يتيح لمهندسي المنتجات إحراز تقدّم سريع مع الالتزام بسياسات الأمان.

المزايا:

• واجهة موحّدة لنقل البيانات إلى Gemini Enterprise Agent Platform: غالبًا ما يضع المطوّرون الداخليون نماذج أولية باستخدام مفاتيح واجهة برمجة التطبيقات (Gemini API) وينشرونها على Gemini Enterprise Agent Platform (إدارة الهوية وإمكانية الوصول) لضمان التوافق مع متطلبات الإنتاج. وتعمل حزمة تطوير البرامج (SDK) على تجريد هذه الاختلافات في المصادقة. وبالمثل بالنسبة إلى الأُطر، يمكنك تنفيذ مسار رمزي واحد وتوفير مجموعتَين من المستخدمين.
• أدوات مساعدة من جهة العميل: تتضمّن حزمة تطوير البرامج (SDK) أدوات مساعدة اصطلاحية تقلّل من النماذج الجاهزة للمهام المعقّدة.
  • أمثلة: دعم عناصر صور PIL مباشرةً في الطلبات، واستدعاء الدوال تلقائيًا، وأنواع شاملة
• الوصول إلى الميزات في اليوم الأول: تتوفّر ميزات واجهة برمجة التطبيقات الجديدة عند الإطلاق من خلال حِزم SDK.
• توافُق محسّن مع إنشاء الرموز البرمجية: يتيح تثبيت حزمة SDK المحلية عرض تعريفات الأنواع وسلاسل المستندات لمساعدي الترميز (مثل Cursor وCopilot). يؤدي توفير هذا السياق إلى تحسين دقة إنشاء الرموز مقارنةً بإنشاء طلبات REST غير المعالجة.

المفاضلة:

• وزن الاعتمادية ومدى تعقيدها: تحتوي حِزم تطوير البرامج (SDK) على اعتماديات خاصة بها، ما قد يؤدي إلى زيادة حجم الحِزمة ومخاطر سلسلة الإمداد المحتملة.
• التحكّم في الإصدارات: غالبًا ما تكون ميزات واجهة برمجة التطبيقات الجديدة مرتبطة بالحد الأدنى من إصدارات حزمة تطوير البرامج (SDK). قد تحتاج إلى إرسال تحديثات إلى المستخدمين للوصول إلى الميزات أو النماذج الجديدة، والتي قد تتطلّب في بعض الحالات إجراء تغييرات في التبعيات المتعدّية التي تؤثّر في المستخدمين.
• قيود البروتوكول: لا تتوافق حِزم SDK إلا مع HTTPS لواجهة برمجة التطبيقات الرئيسية وWebSockets (WSS) لواجهة برمجة التطبيقات Live. ولا يتوافق gRPC مع عملاء حِزم SDK ذات المستوى العالي.
• اللغات المتوافقة: تتوافق حِزم SDK مع إصدارات اللغة الحالية. إذا كنت بحاجة إلى استخدام إصدارات متوقّفة نهائيًا (مثل Python 3.9)، عليك الاحتفاظ بنسخة معدَّلة.

أفضل الممارسات:

• إصدارات القفل: يمكنك تثبيت إصدار حزمة SDK في صورك الأساسية الداخلية لضمان الثبات في جميع الفِرق.

الربط المباشر بواجهة برمجة التطبيقات

إذا كنت توزّع مكتبة على آلاف المطوّرين، أو تشغّلها في بيئة محدودة، أو تنشئ أداة تجميع تتطلّب أحدث ميزات Gemini، قد تحتاج إلى الدمج مع واجهة برمجة التطبيقات مباشرةً باستخدام REST أو gRPC.

المزايا:

• الوصول الكامل إلى الميزات: على عكس طبقة التوافق مع OpenAI، يتيح استخدام واجهة برمجة التطبيقات مباشرةً ميزات خاصة بـ Gemini، مثل التحميل إلى File API، وإنشاء ذاكرة تخزين مؤقت للمحتوى، واستخدام واجهة برمجة التطبيقات الثنائية الاتجاه Live API.
• الحد الأدنى من التبعيات: في بيئة تكون فيها التبعيات حساسة بسبب الحجم أو تكاليف التدقيق. يضمن استخدام واجهة برمجة التطبيقات مباشرةً من خلال مكتبة عادية، مثل fetch، أو من خلال برنامج تضمين، مثل httpx، أن تظل مكتبتك خفيفة الوزن.
• غير مرتبط بلغة معيّنة: هذا هو المسار الوحيد للغات التي لا تغطيها حِزم تطوير البرامج (SDK)، مثل Rust وPHP وRuby، إذ لا توجد قيود على اللغة.
• الأداء: لا تتضمّن Direct API أي تكلفة إضافية عند بدء التشغيل، ما يقلّل من عمليات بدء التشغيل الباردة في الدوال غير الخادمية.

المفاضلة:

• التنفيذ اليدوي لمنصة Gemini Enterprise Agent Platform: على عكس حزمة SDK، لا يؤدي استخدام واجهة برمجة التطبيقات مباشرةً إلى التعامل تلقائيًا مع اختلافات المصادقة بين AI Studio (مفتاح واجهة برمجة التطبيقات) ومنصة Gemini Enterprise Agent Platform (إدارة الهوية وإمكانية الوصول). يجب تنفيذ معالجات مصادقة منفصلة إذا كنت تريد إتاحة البيئتين.
• لا تتوفّر أنواع أو أدوات مساعدة مدمجة: لا يمكنك الحصول على عمليات إكمال الرموز أو عمليات التحقّق في وقت الترجمة لكائنات الطلبات إلا إذا نفّذتها بنفسك. لا تتوفّر أي "أدوات مساعدة" للعملاء (مثل أدوات تحويل الدوال إلى مخططات)، لذا عليك كتابة هذه المنطقية يدويًا.

أفضل الممارسات

نوفّر مواصفات قابلة للقراءة آليًا يمكنك استخدامها لإنشاء تعريفات الأنواع لمكتبتك، ما يغنيك عن كتابتها يدويًا. نزِّل مواصفات الواجهة أثناء عملية الإنشاء، وأنشئ الأنواع، وأرسِل الرمز البرمجي المجمَّع.

• نقطة النهاية: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

دمج حزمة تطوير البرامج (SDK) من OpenAI

إذا كنت تستخدم منصة تعطي الأولوية لمخطط موحّد (OpenAI Chat Completions) على الميزات الخاصة بنموذج معيّن، هذا هو أسرع مسار لك.

المزايا:

• سهولة الاستخدام: يمكنك غالبًا إضافة إمكانية استخدام Gemini من خلال تغيير baseURL وapiKey. هذه طريقة سريعة لدمج عمليات تنفيذ ميزة "استخدام مفتاحك الخاص"، ما يتيح إضافة توافق مع Gemini بدون كتابة رمز برمجي جديد.
• القيود: لا يُنصح بهذا المسار إلا إذا كان بإمكانك استخدام حزمة SDK من OpenAI فقط ولا تحتاج إلى ميزات Gemini المتقدّمة، مثل File API، أو إذا كنت تريد إضافة إمكانية استخدام أدوات مثل تحديد المصدر من خلال "بحث Search" يدويًا.

المفاضلة:

• قيود الميزات: تفرض طبقة التوافق قيودًا على إمكانات Gemini الأساسية. تختلف الأدوات المتاحة من جهة الخادم باختلاف المنصات، وقد تتطلّب معالجة يدوية لتعمل مع أدوات Gemini API.
• تكلفة الترجمة: بما أنّ مخطط OpenAI لا يتوافق تمامًا مع بنية Gemini، يؤدي الاعتماد على طبقة التوافق إلى بعض التعقيدات التي تتطلّب جهودًا إضافية لتنفيذها، مثل ربط أداة "البحث" الخاصة بالمستخدم بأداة المنصة المناسبة. إذا كنت بحاجة إلى قدر كبير من المعالجة الخاصة، قد يكون من الأفضل استخدام حزمة تطوير برامج (SDK) أو واجهة برمجة تطبيقات (API) مخصّصة لكل نظام أساسي.

أفضل الممارسات

يمكنك دمج واجهة 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",
    }
)

الخطوات التالية

• انتقِل إلى نظرة عامة على المكتبة للتعرّف على حِزم تطوير البرامج (SDK) الخاصة بالذكاء الاصطناعي التوليدي.
• تصفُّح مرجع واجهة برمجة التطبيقات
• قراءة دليل التوافق مع OpenAI