- إعداد Gemini Pro API في لمحة
- كيفية الحصول على مفتاح Google API لـ Gemini
- كيفية استدعاء نقطة نهاية Gemini API الأصلية
- كيفية استخدام Gemini مع عميل متوافق مع OpenAI
- كيفية اختيار وإدارة معرّفات نموذج Gemini
- كيفية بناء خلفية قابلة لتبديل المزوّد
- كيفية دمج Gemini في خلفية وكيل
- متى يكون النموذج مفتوح المصدر مناسًب أكث
- أخطاء Gemini API الشائعة
- الخلاصة
- الأسئلة الشائعة
- مقالات مقترحة
يتم الوصول إلى Gemini Pro API عبر Gemini API باستخدام مفتاح يتم إنشاؤه في Google AI Studio. لطلب REST مباشر، استدعِ نقطة نهاية generateContent الخاصة بالنموذج؛ وإذا كان لديك تكامل حالي مع OpenAI SDK، فوجّه العميل إلى عنوان URL الأساسي المتوافق مع OpenAI من Google واستخدم معرّف نموذج Gemini حالي مثل gemini-3.1-pro-preview. التفاصيل المهمة أن “Gemini Pro” هو مصطلح بحث عن عائلة منتجات، وليس معرّف API دائم، لذا يجب على التطبيقات الإنتاجية قراءة قائمة النماذج الحالية من Google قبل تثبيت معرّف.
إعداد Gemini Pro API في لمحة
تحتاج إلى أربع قيم لتنفيذ طلب:
| الإعداد | القيمة |
|---|---|
| مفتاح API | أنشئ واحدًا في Google AI Studio |
| المضيف الأساسي الأصلي | https://generativelanguage.googleapis.com |
| مسار API الأصلي | /v1beta/models/{model}:generateContent |
| عنوان URL الأساسي المتوافق مع OpenAI | https://generativelanguage.googleapis.com/v1beta/openai/ |
| مثال على معرّف النموذج | gemini-3.1-pro-preview |
يوثق الدليل السريع لـ Gemini API من Google عملية إنشاء مفتاح API ونمط الطلب الأصلي. كما يوثق دليل التوافق مع OpenAI عنوان URL الأساسي للتوافق مع التطبيقات التي تستخدم بالفعل OpenAI Python أو JavaScript SDK.
استخدم Gemini SDK الأصلي أو REST API عندما تريد ميزات خاصة بـ Gemini بمجرد أن تعرضها Google. استخدم طبقة التوافق عندما يكون لديك بالفعل عميل بأسلوب OpenAI وترغب في تقليل أعمال الترحيل. التوافق مفيد، لكنه لا يضمن أن كل خيار خاص بمزوّد الخدمة سينتقل بشكل مثالي عبر واجهات API.
كيفية الحصول على مفتاح Google API لـ Gemini
أنشئ المفتاح في Google AI Studio، ثم خزّنه في متغير بيئة بدلاً من وضعه في كود المصدر:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
تعامل مع هذا كبيانات اعتماد من جانب الخادم. لا تقم بإضافته إلى Git، أو طباعته في السجلات، أو تضمينه في JavaScript في المتصفح أو حزمة تطبيق جوال. إذا كان الواجهة الأمامية بحاجة إلى مخرجات Gemini، فأرسل طلب المستخدم إلى الخادم الخلفي الخاص بك واترك الخادم الخلفي يستدعي Google API.
بالنسبة لخدمة إنتاجية، قرّر أيضًا من يمتلك مشروع Google Cloud، وكيفية تدوير المفاتيح، والبيئات التي تحصل على بيانات اعتماد منفصلة، وأين يتم مراقبة حصص الطلبات. يشرح دليل مفاتيح API من Google كيفية ارتباط مفاتيح Gemini API بمشاريع Google Cloud.
كيفية استدعاء نقطة نهاية Gemini API الأصلية
يضع مسار REST الأصلي معرّف النموذج في عنوان URL. هذا المثال يطلب من النموذج التجريبي Pro الحالي إرجاع قائمة مراجعة موجزة للترحيل:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "Create a seven-step checklist for migrating a Python API from one region to two regions. Include rollback checks."
}
]
}
]
}'
يحتوي الرد على مرشحين مع محتوى مولّد. يجب على التطبيقات الحقيقية التعامل مع قائمة مرشحين فارغة، والمحتوى المحظور، والمهلات، والردود غير 2xx بدلاً من الوصول المباشر إلى أول كائن في الرد.
يستخدم عنوان URL v1beta لأن هذا هو المسار الموضح في أمثلة Gemini API الحالية من Google. احتفظ بإصدار API في التهيئة حتى تتمكن من اختبار إصدار جديد دون نشر سلاسل نقطة النهاية في جميع أنحاء قاعدة الكود.
تشريح نقطة النهاية الأصلية
يتكون المسار من ثلاثة أجزاء:
/v1beta/models/{model}:generateContent
v1betaهو إصدار API.{model}هو معرّف النموذج الدقيق من صفحة نماذج Gemini من Google.generateContentهي طريقة التوليد.
غالبًا ما يعني رد 404 أن معرّف النموذج أو إصدار API أو الطريقة غير متطابقة. قبل تغيير كود المصادقة، قارن المسار الكامل مع وثائق النموذج الحالية.
كيفية استخدام Gemini مع عميل متوافق مع OpenAI
إذا كان تطبيقك يستخدم بالفعل حزمة OpenAI Python، فقم بتثبيتها وتغيير مفتاح API وعنوان URL الأساسي ومعرّف النموذج:
pip install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.chat.completions.create(
model="gemini-3.1-pro-preview",
messages=[
{
"role": "system",
"content": "You are a concise software architecture reviewer.",
},
{
"role": "user",
"content": "Review a queue worker design and list the top five failure modes.",
},
],
)
print(response.choices[0].message.content)
هذا هو أقصر طريق للفرق التي لديها تجريد موجود لإكمال الدردشات. كما يسهل إعادة استخدام منصة التقييم: حافظ على ثبات الموجه وتحقق من الرد، ثم بدّل تكوين المزوّد.
لا تفترض سلوكًا متطابقًا لمجرد أن مزوّدين يقبلان نفس استدعاء SDK. يمكن أن تختلف تعليمات النظام، ومخططات الأدوات، والمدخلات متعددة الوسائط، والتعامل مع الأمان، وأحداث البث، ومحاسبة الرموز المميزة، وبيانات الأخطاء. قم بإجراء اختبارات خاصة بالمزوّد قبل تغيير حركة الإنتاج.
كيفية اختيار وإدارة معرّفات نموذج Gemini
تجنب وضع اسم تسويقي مثل gemini-pro مباشرة في منطق التطبيق. تتغير معرّفات النماذج المتاحة من Google مع تقديم النماذج التجريبية وترقيتها وإيقافها. في وقت التحقق من هذا الدليل، سردت صفحة النماذج الرسمية من Google gemini-3.1-pro-preview كمعرّف لنموذج من فئة Pro.
استخدم طبقة تهيئة بدلاً من ذلك:
import os
GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview")
"
هذا الاختيار الصغير يجعل ترقيات النموذج تغييرًا في النشر بدلاً من إعادة كتابة الكود. بالنسبة لخدمة أكبر، قم بتخزين هذه الحقول معًا:
```json
{
"provider": "google",
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": "gemini-3.1-pro-preview",
"timeout_seconds": 60
}
قبل نقل نموذج جديد إلى الإنتاج:
- تأكد من ظهور المعرّف في وثائق النموذج الحالية من Google أو API النماذج.
- تحقق مما إذا كان النموذج في مرحلة المعاينة أو مستقر أو مجدول للإيقاف.
- قم بتشغيل مجموعة التقييم الخاصة بك لجودة الإجابة وصحة استدعاء الأداة.
- قم بقياس زمن الاستجابة واستخدام الرموز المميزة ومعدلات الفشل باستخدام موجهات تمثيلية.
- أضف نموذجًا احتياطيًا أو مسار فشل واضح قبل تحويل كل حركة المرور.
حدود المعدل ليست رقمًا عالميًا واحدًا. إنها تعتمد على النموذج ومستوى الاستخدام، لذا اقرأ توثيق حدود معدل Gemini API وراقب الحدود المطبقة على مشروعك.
كيفية بناء خلفية قابلة لتبديل المزوّد
يمكن لواجهة متوافقة مع OpenAI تقليل تغييرات الكود، لكن تبديل المزوّد يعمل بشكل أفضل عندما يحدد تطبيقك نفسه العقد. احتفظ بتكوين المزوّd خارج منطق الأعمال وقم بتطبيع المخرجات التي تحتاجها بالفعل.
import os
from openai import OpenAI
PROVIDERS = {
"gemini": {
"api_key": os.environ["GEMINI_API_KEY"],
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview"),
},
"novita": {
"api_key": os.environ["NOVITA_API_KEY"],
"base_url": "https://api.novita.ai/openai",
"model": os.getenv("NOVITA_MODEL", "xiaomimimo/mimo-v2.5-pro"),
},
}
def generate(provider_name: str, prompt: str) -> str:
provider = PROVIDERS[provider_name]
client = OpenAI(
api_key=provider["api_key"],
base_url=provider["base_url"],
)
response = client.chat.completions.create(
model=provider["model"],
messages=[{"role": "user", "content": prompt}],
)
return response.choices[0].message.content or ""
هذا المثال يُظهر الاختلافات عن قصد بدلاً من إخفائها. يحتفظ كل مزوّد ببيانات اعتماد خاصة به وعنوان URL الأساسي ومعرّف النموذج. يتلقى التطبيق سلسلة واحدة موحدة، بينما يمكن للاختبارات الخاصة بالمزوّد تغطية سلوك أكثر ثراءً مثل الأدوات أو المدخلات متعددة الوسائط.
يستخدم توثيق LLM API من Novita AI شكل API متوافق مع OpenAI للنماذج المدعومة. يمكن أن يكون هذا مفيدًا عندما ترغب الفريق في مقارنة Gemini مع نماذج مفتوحة المصدر دون إعادة بناء طبقة العميل بالكامل.
كيفية دمج Gemini في خلفية وكيل
خلفية الوكيل لديهما على الأقلمسؤليتن منفصلتن:
- الاستنتاج: يقر النموذج ماذا سيقول أو أي أداة سيدعوها.
- التنفيذ: بيئة تشغيل متحكمة تنفذ إجراءات الملف أو الصدفة أو المتصفح أو التطبيق.
يمكن لـ Gemini API معالجة جانب الاستنتاج. لا ينبغي معاملته كحد تنفيذ. إذا اقترح النموذج أمر صدفة، فلا يزال تطبيقك بحاجة إلى التحقق من صحة استدعاء الأداة، وتصريحه، وتشغيله في بيئة معزولة، والتقاط النتيجة، واتقرار السياق الذي سترسله إلى النموذج.
Novita Agent Sandbox مصمم لعمليات تنفيذ الوكلاء المعزولة. يمكن لبنية عملية استخدام Gemini للتفكير بينما يتعامل صندوق الحماية مع مهام الكود أو المتصفح بشكل منفصل:
طلب المستخدم
-> خدمة الوكيل
-> Gemini API للتفكير واختيار الأداة
-> فحوصات السياسة للإجراء المقترح
-> Agent Sandbox للتنفيذ المعزول
-> إرجاع نتيجة الأداة إلى خدمة الوكيل
-> Gemini API للرد النهائي
هذا الفصل يجعل النموذج قابلًا للاستبدال ويبقي التنفيذ غير الموثوق بعيدًا عن خادم التطبيق. كما يمنح الخلفية مكانًا واحدًا لفرض المهلات وسياسة الشبكة وحدود الملفات وتدوين المراجعة وتصريح المستخدم.
للإصدار الأول، اكشف فقط بعدًد ضيقً من الأدوات، حدد مخططات JSON لوسطتها، رفض الحقول غير المعروفة، ضع حدودً قصوى لوقت التنفيذ وحج المخرجات. أضف قدرات أوسع لاستخدام الكمبيوتر أو المتصفح فقط بع د وضوح نذج التصريح.
متى يكون النموذج مفتوح المصدر مناسًب أكث
نماذج Gemini Pro هي خيار قوي عندم تحتاج طبيقك إل قدرات نموذج Google وAPI المدار. قد يكون النموذج مفتوح المصدر أكثر ملاءمة عندما تحتاج إلى مزود ثانٍ، أو ترغب في تقييم سلوك النموذج مقابل إصدار عتلوي مرئي، أو تفضل نموذجًا متاحً من خلل نقطة نهاية متوافة مع OpenAI بجوار البنية التحتية الأخرى.
MiMo-V2.5-Pro هو أحد الخيارات الحالية على Novita AI. بطب ق، يصف بطاقة النموذج من Xiaomi النموذج على أنه نموذج خبير مختلط مفتوح المصدر، بينما توف Novita AI معرّف النموذج المستضاف xiaomimo/mimo-v2.5-pro. نظرًا لأنه يمكن استدعاء كل من نقطة نهاية التوافق مع Google و Novita AI باستخدام عميل بأسلوب OpenAI، يمكن للنمط القابل لتبديل المزود في القسم الساب ق تقييمهم بنفس الموج هات وفحوصات القبول.
لا تختر على أسا التسمية فقط. بنا مجمعة تقييم صغير من عملك الفعلي: تعل يقات مراجع الود، أسئلة الدعم، إجابات مبنية عل الاسترجع، استدعاءات الأدوات، أو المستندات الطويلة. قارن جودة المخرجات، زمن الاستجابة، سلوك الخطأ، والتكلفة باستخدام لوحات بيانات المزود الحالية قبل اتخاذ قرار التوجيه.
أخطاء Gemini API الشائعة
400: طلب غير صالح
تحقق من شكل JSON، وأدوار الرسائل، وتعريفات الأدوات، وأسماء المعلمات. قد لا يكون الخيار المقبول من قبل مزود آخر متوافق مع OpenAI مقبولاً من قبل طبقة التوافق من Google.
401 أو 403: فشل المصادقة أو الإذن
تأكد من وجود GEMINI_API_KEY في بيئة العملية وأنه ينتمي إلى مشروع Google Cloud المقصود. تحقق أيضً ما إذا كان المشروع والنموزج المحدد متاحين للحساب والمنطقة.
404: النموذج أو الطريقة غير موجودة
قارن معرّف النموذج الدقيق مع قائمة نماذج Gemini الحالية. بالنسبة لاستدعاءات REST الأصلية، تحقق من إصدار API واللاحقة :generateContent. بالنسبة لاستدعاءات المتوافقة مع OpenAI، تحقق من أن عنوان URL الأساسي ينتهي بـ /v1beta/openai/.
429: تجاوز حد المعدل
أعد المحاولة مع تأخير أسي وتباعد عشوائي، لكن لا تعامل إعادة المحاولة كبديل عن تخطيط السعة. ضع العمل المتفجر في قائمة انتظار، وحدد الطلبات المتزامنة، وافحص مستوى الاستخدام الحالي للمشروع والحدود الخاصة بالنموذج.
يعمل SDK، لكن الناتج يختلف بعد تبديل المزودين
يغطي التوافق واجهة الطلب، وليس سلوك النموذج المتطابق. أعد تشغيل اختبارات الموجّه والمخرجات المنظمة واستدعاء الأداة لكل مزود وإصدار نموذج.
الخلاصة
ابدأ بـ Gemini API الأصلي عندما تريد أوضح مسار للميزات الخاصة بـ Gemini. ابدأ بنقطة النهاية المتوافقة مع OpenAI عندما يكون لديك بالفعل خلفية بأسلوب OpenAI أو تحتاج إلى تقييم سرع للمزود. في كلتا الحالتن، احتفظ بمفتاح API في جانب الخادم، وضع معرّف النموذج في التهيئة، واختبر إصدار النموذج بالضبط، وافصل استنتاج النموذج عن تنفيذ الوكيل.
لتصميم إنتاجي مرن، احتفظ بنموذج بديل واحد على الأقل خلف نفس الواجهة المملوكة للتطبيق. يمنح هذا فريقك طريقة عملية لاختبار خيار مفتوح المصدر عل Novita AI، والتعامل مع تغييرات دورة حياة النموذج، وتوجيه تنفيذ الوكيل إلى صندوق حماية معزول بدلاً من ربط كل مسؤولية باستدعاء API واحد.
الأسئلة الشائعة
هل لا يزال هناك معرّف نموذج يسمى gemini-pro؟
لا تفترض أن gemini-pro هو المعرّف الحالي. “Gemini Pro API” غالبً ما يستخدم كعبارة بحث عن نماذج Gemini ذات القدرات الأعلى من Google، لكن يجب على التطبيقات استخدام معرّف دقيق من صفحة نماذج Gemini الحالية. يستخدم هذا الدليل gemini-3.1-pro-preview كمثال تم التحقق منه.
أين أحصل عل مفتاح Google API لـ Gemini؟
أنشئ مفتاح Gemini API في Google AI Studio. خزنه في سر من جانب الخادم مثل GEMINI_API_KEY، ليس في كود المصدر أو JavaScript في المتصفح.
ما هي نقطة نهاية Gemini API؟
المضيف الأصلي هو https://generativelanguage.googleapis.com. يستخدم طلب توليد المحتوى /v1beta/models/{model}:generateContent. عنوان URL الأساسي المتوافق مع OpenAI من Google هو https://generativelanguage.googleapis.com/v1beta/openai/.
هل يختلف Gemini Studio API عن Gemini API؟
Google AI Studio هو الواجهة الويب التي يستخدمها المطورون للتجربة وإنشاء مفتاح. تذهب طلبات التطبيق إلى Gemini API. عادةً ما تشير بحوث “Gemini Studio API” إلى سير العمل من AI Studio إلى API هذا.
هل Google Bard API هو نفس Gemini API؟
Gemini هو العلامة التجارية الحالية لـ API والنموذج. يجب أن تستخدم البحوث الأقد عن Google Bard API وثائق Gemini API الحالية ونقط النهاة ومعرّفات النموذج بدلاً من أمثلة Bard القديمة.
هل يمكنني استخدام OpenAI SDK مع Gemini؟
نعم. توثق Google نقطة نهاية توافق مع OpenAI. ضط عنوان URL الأساسي للعميل إلى عنوان URL التوافق من Google، قدم مفتاح Gemini API الخاص بك، واخت معرّف نموذج Gemini مدعوم. اختبر الميزات الخاصة بالمزوّد قبل الاعتماد على التكافؤ السلوكي الكامل.
هل يمكن لـ Gemini تشغيل الود لوكيل ذكاء اصطناعي؟
يمكن لـ Gemini التفكير في الود واقتراح استدعاءات أدوات، لكن يجب أن يتم التنفيذ في بيئة تشغيل متحكمة. احتفظ باستدعاء النموذج منفصلاً عن بيئة معزولة مثل Agent Sandbox، وتحقق من كل إجراء مطلوب قبل تشغيله.
هل هناك طبقة مجانية لتسعير Gemini API؟
نعم. تقول Google أن الحسابات الجديدة تبدأ في الطبقة المجانية، التي تسمح بالوصول إلى نماذج معينة في Gemini API و AI Studio حتى حدود معدل الطبقة المجانية للنماذج. للانتقال إلى طبقة مدفوعة، يجب عليك إعداد الفوترة في AI Studio. للحصول على أسعار الرموز المميزة بالضبط، تحقق من جدول التسعير من Google، لأن المعدلات خاصة بالنموذج؛ بالنسبة لـ gemini-3.1-pro-preview، يسرد الجدول الحالي تسعيرًا قياسيًا مدفوعًا ولا توجد رسوم رمزية للطبقة المجانية.
