استخدام Gemini API عبر عميل متوافق مع OpenAI: دليل Python وJavaScript

ما الذي ستتعلمه في هذا الدليل؟

يتناول هذا الدليل خطوات الاتصال الأساسية للمطورين الذين يريدون توجيه شيفرة عميل متوافقة مع OpenAI لديهم بالفعل إلى Gemini API. ووفقًا لوثائق Google، يمكن الوصول إلى نماذج Gemini عبر مكتبات عملاء Python وTypeScript/JavaScript أو من خلال REST API. أما من يستخدمون عميلًا حاليًا، فيعتمد الانتقال الأساسي على ضبط مفتاح API وعنوان الطلب واسم النموذج.

تستخدم الأمثلة طلب إكمال محادثة. ويمكن لفرق الهندسة المعمارية والتصميم الداخلي الاستفادة من طريقة الاتصال الأساسية هذه ضمن تطبيق يجيب عن أسئلة تتعلق بنصوص المشاريع أو ملاحظات التصميم أو العروض المرئية. لكن هذا الدليل يشرح اتصال API فقط؛ ولا يقدم تكاملًا مع برنامج معماري بعينه أو ضمانًا لدقة مخرجات النموذج أو إضافة مخصصة لسير عمل التصميم.

المتطلبات: المفتاح والعميل والنموذج

قبل البدء، ستحتاج إلى مفتاح Gemini API من Google AI Studio. تعرض وثائق Google أمثلة على مكتبات عملاء OpenAI لـ Python وJavaScript/TypeScript، إضافة إلى طلبات REST. اسم النموذج المستخدم في أمثلة الشيفرة هو gemini-3.8-flash؛ وإذا اخترت نموذجًا متوافقًا آخر، فعليك تعديل حقل النموذج بما يناسبه. ولا يذكر المصدر رقم إصدار مكتبة العميل أو معلومات عن الأسعار.

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

إرسال الطلب الأول خطوة بخطوة

1. احصل على مفتاح API. أنشئ مفتاح Gemini API من Google AI Studio. يُستخدم المفتاح للمصادقة على الطلبات؛ وتحتوي الأمثلة على عنصر نائب لا على مفتاح حقيقي.

2. وجّه العميل إلى نقطة نهاية Gemini. يشير الحقل base_url في مثال Python والحقل baseURL في مثال JavaScript إلى عنوان Gemini API. يوجّه هذا الإعداد طلبات العميل إلى عنوان Gemini الموثق بدلًا من العنوان الافتراضي.

3. حدّد اسم النموذج. يستخدم المثال gemini-3.8-flash. يظهر اسم النموذج في حقل منفصل ضمن الطلب؛ وإذا استخدمت نموذجًا آخر، فيجب أن يتطابق هذا الحقل مع النموذج المختار.

4. نفّذ أول طلب نصي. يرسل مثال Python أدناه رسائل النظام والمستخدم ضمن طلب إكمال محادثة، ثم يطبع الرسالة الواردة في الاستجابة. أُخذت الشيفرة من الدليل المفتوح الترخيص الذي نشرته Google.

from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[
{ "role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Explain to me how AI works"
}
]
)
print(response.choices[0].message)

يطلب نص المستخدم في المثال شرحًا عامًا. وفي تطبيق مخصص للهندسة المعمارية، يمكن استبدال هذا النص بمحتوى يلائم غرض التطبيق، مثل طلب تلخيص ملاحظة عن مشروع. هذا تكييف لطريقة استخدام الشيفرة، ولا يعني أن المصدر يضمن نتائج لمهمة معمارية محددة.

1. أنشئ الاتصال الأساسي نفسه باستخدام JavaScript. يحدد مثال JavaScript أيضًا مفتاح API ونقطة النهاية والنموذج والرسائل. وبعد اكتمال الطلب، تُطبع الرسالة المستلمة في وحدة التحكم.

import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
const response = await openai.chat.completions.create({
model: "gemini-3.8-flash",
messages: [
{ role: "system",
content: "You are a helpful assistant."
},
{
role: "user",
content: "Explain to me how AI works",
},
],
});
console.log(response.choices[0].message);

1. أرسل طلب REST من دون استخدام عميل. ينفّذ مثال cURL أدناه العملية الأساسية نفسها عبر طلب HTTP. يوضع المفتاح في ترويسة Authorization، بينما يظهر النموذج والرسالة في متن الطلب.

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "Explain to me how AI works"
}
]
}'

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

أخطاء شائعة ونقاط للتحقق

• الإبقاء على نقطة النهاية الافتراضية: إذا لم يُوجَّه العميل إلى Gemini API، فقد لا يكون عنوان الطلب هو العنوان المتوقع. تحقق من إعداد base_url في Python وbaseURL في JavaScript، ومن عنوان REST.

• عدم استبدال العنصر النائب: القيمة GEMINI_API_KEY في الأمثلة ليست مفتاحًا حقيقيًا. استبدلها بالمفتاح الذي حصلت عليه من Google AI Studio.

• كتابة اسم النموذج على نحو خاطئ: يظهر النموذج في الأمثلة باسم gemini-3.8-flash. تحقق من تطابق القيمة في الطلب مع اسم النموذج المختار.

• افتراض أن جميع الميزات متوافقة بالطريقة نفسها: يتناول الدليل، إلى جانب إكمال المحادثات، موضوعات مثل الاستجابات المتدفقة واستدعاء الدوال وفهم الصور. لكن قد يختلف الطلب والإعداد لكل منها؛ ومثال المحادثة الأساسي هنا لا يغطي كل تفاصيل إعداد هذه الميزات.

• استخدام إعدادات التفكير معًا: توضح الوثائق أن reasoning_effort وthinking_level أو thinking_budget الخاصين بـ Gemini يتداخلان في الوظائف، وألا يُستخدما في الوقت نفسه. لذلك، راجع وثائق النموذج المعني عند إضافة إعدادات التفكير المتقدمة.

في سير عمل الهندسة المعمارية والتصميم الداخلي وarchviz، قد تكون هذه الطريقة نقطة انطلاق للمطورين الراغبين في تجربة الوصول النصي إلى API عبر عميل حالي. ويمكن اختبار أفكار مثل إضافة طلبات نصية تتعلق بأوصاف المشاريع أو ملاحظات التصميم إلى أداة داخل المكتب؛ لكن المصدر لا يذكر التوافق مع برامج محددة أو سير عمل لتوليد الصور أو متطلبات الأجهزة المحلية. وقبل الانتقال إلى بيئة الإنتاج، ينبغي تقييم التراخيص وتكاليف API وشروط النموذج المستخدم وتدفق البيانات داخل التطبيق على نحو مستقل؛ فالمصدر لا يقدم معلومات عن الأسعار أو الأجهزة.

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

بعد نجاح أول طلب نصي، يمكنك الاطلاع على أقسام الاستجابات المتدفقة واستدعاء الدوال وفهم الصور الواردة في وثائق Google نفسها. هذه ليست ميزات جاهزة مضافة مباشرة إلى مثال المحادثة الأساسي؛ بل ينبغي دراسة صيغة الطلب ومتطلبات كل منها على حدة. وإذا كان التطبيق لا يستخدم مكتبة عملاء OpenAI أصلًا، فينبغي أيضًا أخذ خيار الاتصال المباشر بـ Gemini API في الحسبان عند اتخاذ القرار الأولي.

بالنسبة إلى الفرق المعمارية، فإن الطريقة الأكثر أمانًا للتجربة هي إنشاء نموذج أولي صغير باستخدام نصوص مشاريع نموذجية غير حساسة، والتعامل مع المخرجات بوصفها محتوى مساعدًا للمراجعة لا بديلًا عن قرارات التصميم. ولا يعني هذا الاقتراح أن API تضمن نتيجة تصميمية معينة؛ بل هو نهج عملي لمساعدة الفريق على وضع آلية تحقق خاصة به قبل إدخال الاتصال التقني في سير العمل الفعلي.

المصدر والترخيص

أُعد هذا الدليل بتكييف أمثلة Python وJavaScript وREST الواردة في دليل Google الخاص بـ Gemini API بعنوان “OpenAI compatibility” إلى اللغة التركية. المصدر مرخص بموجب CC BY 4.0.