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

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

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

ما هو التكامل مع الشركاء؟

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

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

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

المنصة في وقت التشغيل والمنصة الطرفية

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

موقع تجميع

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

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

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

مقارنة سريعة

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

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

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

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

المزايا:

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

المفاضلة:

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

أفضل ممارسة:

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

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

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

المزايا:

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

المفاضلة:

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

أفضل ممارسة

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

• نقطة النهاية: 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) أو واجهة برمجة تطبيقات مخصصة لكل منصة.

أفضل ممارسة

يمكنك التكامل مباشرةً مع 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-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",
    }
)

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

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