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

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

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

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

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

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

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

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

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

موقع تجميع

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

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

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

مقارنة سريعة

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

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

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

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

المزايا:

• واجهة موحَّدة لنقل البيانات إلى Vertex AI: غالبًا ما يستخدم المطوّرون الداخليون مفاتيح API (Gemini API) لإنشاء نماذج أولية، ثم ينقلون البيانات إلى Vertex AI (إدارة الهوية وإمكانية الوصول) لضمان التوافق مع متطلبات الإنتاج. وتعمل حزمة تطوير البرامج (SDK) على تجريد هذه الاختلافات في المصادقة. وبالمثل بالنسبة إلى الأُطر، يمكنك تنفيذ مسار رمز واحد وإتاحة مجموعتَين من المستخدمين.
• أدوات مساعدة من جهة العميل: تتضمّن حزمة SDK أدوات مساعدة اصطلاحية تقلّل من النماذج الجاهزة للمهام المعقّدة.
  • أمثلة: إتاحة استخدام عناصر صور PIL مباشرةً في الطلبات، واستدعاء الدوال تلقائيًا، وأنواع شاملة.
• الوصول إلى الميزات في اليوم الأول: تتوفّر ميزات واجهة برمجة التطبيقات الجديدة عند طرحها من خلال حِزم SDK.
• توافُق محسّن مع إنشاء الرموز البرمجية: يتيح تثبيت حزمة SDK محلية عرض تعريفات الأنواع وسلاسل التوثيق لمساعدي الترميز (مثل المؤشر و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 الثنائية الاتجاه.
• الحد الأدنى من التبعيات: في بيئة تكون فيها التبعيات حساسة بسبب الحجم أو تكاليف التدقيق. يضمن استخدام واجهة برمجة التطبيقات مباشرةً من خلال مكتبة عادية، مثل fetch، أو من خلال برنامج تضمين، مثل httpx، أن تظل مكتبتك خفيفة الوزن.
• غير مرتبط بلغة معيّنة: هذا هو المسار الوحيد للغات التي لا تغطيها حِزم تطوير البرامج (SDK)، مثل Rust وPHP وRuby، إذ لا توجد قيود على اللغة.
• الأداء: لا تتضمّن Direct API أي تكلفة إضافية عند بدء التشغيل، ما يقلّل من عمليات بدء التشغيل الباردة في الدوال غير الخادمية.

المفاضلة:

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

أفضل ممارسة

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

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

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

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

المزايا:

• سهولة الاستخدام: يمكنك غالبًا إضافة دعم Gemini من خلال تغيير baseURL وapiKey. هذه طريقة سريعة لدمج عمليات تنفيذ ميزة "إحضار مفتاحك الخاص"، ما يتيح إضافة دعم Gemini بدون كتابة رمز برمجي جديد.
• القيود: لا يُنصح باتّباع هذا المسار إلا إذا كان بإمكانك استخدام حزمة تطوير البرامج (SDK) من OpenAI فقط ولا تحتاج إلى ميزات Gemini المتقدّمة، مثل File API، أو إذا كنت تريد إضافة إمكانية استخدام أدوات مثل Grounding with Google 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