مقدمة حول واجهة برمجة تطبيقات Gemini
يقدم هذا الدليل الشامل خطوات البدء السريع للتعامل مع واجهة برمجة تطبيقات Gemini (Gemini API). سنستعرض كيفية إعداد المكتبات البرمجية، وإجراء طلبك الأول، وبث الردود، وإنشاء محادثات متعددة الجولات، بالإضافة إلى كيفية الاستفادة من الأدوات المتقدمة باستخدام طريقة generateContent القياسية.
قبل البدء
لاستخدام واجهة برمجة تطبيقات Gemini، يجب أن تمتلك مفتاح واجهة برمجة تطبيقات (API Key) خاصاً بك. يعمل هذا المفتاح على مصادقة طلباتك، وتطبيق حدود الأمان، وتتبع معدلات الاستخدام الخاصة بحسابك. يمكنك إنشاء مفتاحك مجاناً عبر منصة AI Studio.
تثبيت حزمة تطوير البرمجيات (SDK) الخاصة بـ Google GenAI
لغة بايثون (Python)
باستخدام إصدار Python 3.9 أو أحدث، قم بتثبيت حزمة google-genai عبر تنفيذ الأمر التالي في واجهة الأوامر:
pip install -q -U google-genai
لغة جافا سكريبت (JavaScript)
باستخدام Node.js إصدار 18 أو أحدث، قم بتثبيت حزمة SDK الخاصة بـ Google Gen AI لبيئات TypeScript و JavaScript عبر الأمر التالي:
npm install @google/genai
توليد النصوص
يمكنك استخدام الطريقة models.generate_content لتوليد استجابة نصية بناءً على المدخلات المقدمة.
مثال بلغة بايثون
from google import genai
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="Explain how AI works in a few words"
)
print(response.text)مثال بلغة جافا سكريبت
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const response = await ai.models.generateContent({
model: "gemini-3.5-flash",
contents: "Explain how AI works in a few words",
});
console.log(response.text);
}
main();الاستجابات الديناميكية (البث)
بشكل افتراضي، ينتظر النموذج حتى اكتمال عملية التوليد بالكامل قبل إرسال الرد. للحصول على تجربة أكثر تفاعلية وسرعة، يمكنك بث أجزاء الرد فور توليدها.
مثال بلغة بايثون
response = client.models.generate_content_stream(
model="gemini-3.5-flash",
contents="Explain how AI works in detail"
)
for chunk in response:
print(chunk.text, end="", flush=True)المحادثات متعددة الجولات
توفر حزم SDK مساعد محادثة (Chat) يحتفظ بالحالة، مما يتيح لك إنشاء تجربة محادثة تدير سجل الحوار تلقائياً.
مثال بلغة بايثون
chat = client.chats.create(model="gemini-3.5-flash")
response1 = chat.send_message("I have 2 dogs in my house.")
response2 = chat.send_message("How many paws are in my house?")استخدام الأدوات
يمكنك توسيع قدرات النموذج من خلال ربط الردود ببحث Google للوصول إلى محتوى الويب في الوقت الفعلي. يقرر النموذج تلقائياً متى يحتاج لإجراء بحث، وينفذ الاستعلامات، ويصيغ إجابة دقيقة.
أدوات إضافية مدعومة:
- تنفيذ الكود: يتيح للنموذج كتابة وتشغيل كود Python لحل المسائل الرياضية المعقدة.
- سياق الرابط (URL): لربط الإجابات بمحتوى صفحات ويب محددة.
- البحث في الملفات: لاستيراد الملفات وربط الإجابات بمحتواها عبر البحث الدلالي.
- خرائط Google: لربط الإجابات ببيانات المواقع والبحث عن الأماكن والمسارات.
- استخدام الحاسوب: لتمكين النموذج من التفاعل مع الشاشة ولوحة المفاتيح والفأرة الافتراضية.
استدعاء الوظائف المخصصة (Function Calling)
استخدم استدعاء الوظائف لربط النماذج بأدواتك وواجهات برمجة التطبيقات الخاصة بك. يحدد النموذج متى يجب استدعاء وظيفتك ويعيد functionCall في الرد لتتمكن تطبيقك من تنفيذه.