- إعداد Gemini Pro API في لمحة
- كيفية الحصول على مفتاح Google API لـ Gemini
- كيفية استدعاء نقطة نهاية Gemini API الأصلية
- كيفية استخدام Gemini مع عميل متوافق مع OpenAI
- كيفية اختيار وإدارة معرفات نماذج Gemini
- كيفية بناء خلفية قابلة للتبديل بين الموفرين
- كيف يتناسب Gemini مع خلفية الوكيل
- متى يكون النموذج مفتوح المصدر خيارًا أفضل
- أخطاء Gemini API الشائعة
- الخلاصة
- الأسئلة الشائعة
- مقالات مقترحة
يتم الوصول إلى Gemini Pro API من خلال Gemini API باستخدام مفتاح تم إنشاؤه في Google AI Studio. لطلب REST مباشر، اتصل بنقطة نهاية generateContent للنموذج؛ وللتكامل مع SDK OpenAI الحالي، وجّه العميل إلى عنوان 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 الأساسي للتوافق مع التطبيقات التي تستخدم بالفعل SDK Python أو JavaScript من OpenAI.
استخدم 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 preview الحالي إرجاع قائمة مراجعة موجزة للهجرة:
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")
هذا الاختيار الصغير يجعل ترقيات النموذج تغييرًا في النشر بدلاً من إعادة كتابة الكود. بالنسبة لخدمة أكبر، قم بتخزين هذه الحقول معًا:
{
"provider": "google",
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": "gemini-3.1-pro-preview",
"timeout_seconds": 60
}
قبل نقل نموذج جديد إلى الإنتاج:
- تأكد من ظهور المعرف في وثائق النموذج الحالية من Google أو واجهة برمجة تطبيقات النماذج.
- تحقق مما إذا كان النموذج في مرحلة المعاينة أو مستقر أو مجدول للإيقاف.
- قم بتشغيل مجموعة التقييم الخاصة بك لجودة الإجابة وصحة استدعاء الأداة.
- قم بقياس زمن الاستجابة واستخدام الرمز ومعدلات الفشل باستخدام مطالبات تمثيلية.
- أضف نموذجًا احتياطيًا أو مسار فشل واضح قبل تحويل كل حركة المرور.
حدود المعدل ليست رقمًا واحدًا عالميًا. تعتمد على النموذج ومستوى الاستخدام، لذا اقرأ وثائق حدود معدل Gemini API من Google وراقب الحدود المطبقة على مشروعك.
كيفية بناء خلفية قابلة للتبديل بين الموفرين
يمكن للواجهة المتوافقة مع OpenAI تقليل تغييرات الكود، لكن تبديل الموفر يعمل بشكل أفضل عندما يحدد تطبيقك العقد بنفسه. احتفظ بتهيئة الموفر خارج منطق الأعمال وقم بتطبيع المخرجات التي تحتاجها بالفعل.
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 وواجهة برمجة تطبيقات مُدارة. قد يكون النموذج مفتوح المصدر خيارًا أفضل عندما تحتاج إلى موفر ثانٍ، أو تريد تقييم سلوك النموذج مقابل إصدار مرئي من المنبع، أو تفضل نموذجًا متاحًا من خلال نقطة نهاية متوافقة مع OpenAI إلى جانب بنية تحتية أخرى.
MiMo-V2.5-Pro هو خيار حالي واحد على Novita AI. يصف بطاقة نموذج Xiaomi المنبع أنه نموذج مفتوح المصدر من نوع Mixture-of-Experts، بينما توفر Novita AI معرف النموذج المستضاف xiaomimimo/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 تشغيل الكود لوكيل AI؟
يمكن لـ Gemini التفكير في الكود واقتراح استدعاءات أدوات، لكن يجب أن يتم التنفيذ في بيئة تشغيل خاضعة للرقابة. حافظ على استدعاء النموذج منفصلاً عن بيئة منعزلة مثل Agent Sandbox، وتحقق من صحة كل إجراء مطلوب قبل تشغيله.
