سير العمل المعماري باستخدام Gemini API: أول طلب نصي في Python

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

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

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

المتطلبات: الحساب والمفتاح والبرامج

للبدء، احصل على مفتاح API عبر Google AI Studio. ووفقًا لدليل Google، يمكن لـ AI Studio إنشاء مشروع ومفتاح تلقائيًا للمستخدمين الجدد؛ أما المستخدمون الحاليون فيمكنهم إنشاء اقتران جديد بين مفتاح API ومشروع من صفحة مفاتيح API. ويشير الدليل أيضًا إلى أن المشاريع الإضافية المستوردة من Google Cloud قد تحتاج إلى التحقق كي تتمكن من استخدام الفئة المجانية.

سنستخدم في هذا الدليل SDK الخاص بـ Python. ويُثبّت أمر التثبيت الوارد في المصدر حزمة google-genai أو يحدّثها. وبما أن الدليل لا يحدد متطلبات إصدار معينة من Python، فلا نضيف هنا أي شرط متعلق بالإصدار. عرّف مفتاح API كمتغير بيئة بدلًا من كتابته مباشرة في الشيفرة المصدرية:

export GEMINI_API_KEY="YOUR_API_KEY"

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

للانتقال إلى الفئة المدفوعة، يلزم إعداد Cloud Billing وإضافة وسيلة دفع والدفع مسبقًا مقابل رصيد مدفوع بقيمة لا تقل عن 5 دولارات أو ما يعادلها. وتذكر Google أن الفئة المدفوعة ترفع حدود السرعة. ويمكن متابعة استخدام API من شاشة الاستخدام في Google AI Studio.

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

1. ثبّت SDK. شغّل الأمر التالي في بيئة Python:

pip install -U google-genai

يثبّت الأمر حزمة google-genai باستخدام pip أو يحدّث التثبيت الحالي. إذا كنت تستخدم أكثر من بيئة Python، فتأكد من تشغيل الأمر في البيئة التي ستشغّل فيها الشيفرة.

1. أعِدّ أول طلب نصي. أضف المثال التالي إلى ملف Python. تطلب المطالبة مقترحات مكتوبة لصالة سكنية صغيرة:

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Küçük bir konut salonu için gün ışığını ve dolaşımı gözeten üç tasarım önerisi yaz. Her öneride tasarım kararını ve gerekçesini belirt."
)
print(interaction.output_text)

يُرسل الطلب إلى نموذج gemini-3.8-flash عبر Interactions API؛ ويطبع المثال النتيجة على الشاشة باستخدام interaction.output_text. يمكنك تعديل نص المطالبة وفقًا لمهمة العمل النصية المطلوبة. فعلى سبيل المثال، يمكنك طلب شرح لمفهوم بغرض عرض تقديمي، أو مسودة تقارن بين خيارات المواد، أو قائمة أسئلة لاجتماع مع عميل. ويسهّل وصف نطاق الاستجابة المتوقعة وشكلها بوضوح تقييم النص الناتج.

1. خصّص المطالبة لسياق المشروع. بدلًا من أمر عام، حدّد نوع المساحة والمخرج المطلوب. المثال التالي مطالبة أصلية أُعدّت للتحضير لاجتماع تصميم داخلي:

Bir kafe iç mekânı için konsept geliştirme toplantısına hazırlanıyorum. Tasarım ekibinin tartışması için üç farklı atmosfer yönü öner. Her yönü kısa bir başlık, mekânsal yaklaşım ve müşteriye sorulacak iki net soruyla açıkla. Proje verisi verilmediğinde varsayım üretme; eksik bilgileri ayrıca belirt.

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

1. تلقَّ الاستجابة على هيئة تدفق. إذا كان التطبيق بحاجة إلى معالجة الاستجابة على أجزاء أثناء إنشائها، فيمكن استخدام stream=True في الطلب. ويستعرض المثال التالي الأحداث المعادة من API ويطبعها على الشاشة:

from google import genai

client = genai.Client()
stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Bir mimari konsept sunumu için kısa bir açılış metni yaz.",
    stream=True
)
for event in stream:
    print(event)

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

الاستخدام في سير العمل المعماري والتصوير المعماري

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

لا تقيس هذه الأمثلة أداء التصيير المحلي على محطة العمل. وبما أن المصدر لا يقدّم متطلبات محددة لوحدة معالجة الرسومات أو توصيات للأجهزة لهذا الاستخدام، فلا ينبغي اتخاذ قرار بترقية الأجهزة بناءً على هذه الأمثلة. ومن المهم على مستوى الحساب إدارة مفتاح API ومتابعة الاستخدام وتقييم تكلفة الفئة المدفوعة عند الحاجة. ويتطلب الانتقال إلى الاستخدام المدفوع إعداد Cloud Billing والدفع المسبق؛ ومن المفيد أن تحدد الفرق مسبقًا مسؤولية الاستخدام وكيفية متابعة الميزانية.

الأخطاء الشائعة والخطوات التالية

• المفتاح غير معرّف: شغّل ملف Python من البيئة التي عُرّف فيها المتغير GEMINI_API_KEY.

• ثُبّتت الحزمة في بيئة مختلفة: تحقق من وجود حزمة google-genai في بيئة Python التي تشغّل الشيفرة.

• المطالبة عامة أكثر من اللازم: حدّد نوع المساحة والغرض من النص المطلوب وشكل الاستجابة.

• اعتبار الاستجابة معلومات معتمدة عن المشروع: لا تتعامل مع النص باعتباره قرارًا تصميميًا أو تحققًا تقنيًا؛ بل اعرضه على الفريق للمراجعة.

• بدء الاستخدام المدفوع من دون تخطيط: راجع شروط Cloud Billing والدفع المسبق قبل الانتقال إلى الاستخدام المدفوع.

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

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

أُعدّ هذا الدليل باللغة التركية بالاستناد إلى دليل “Getting started” (K1) الذي نشرته Google لـ Gemini API. ونُشر المصدر بموجب ترخيص CC BY 4.0. أما المطالبات النموذجية المخصصة للعمارة والتصميم الداخلي فأُعدّت خصيصًا لهذا الدليل.