استدعاء الدوال في Gemini API: استدعاء الأدوات في سير العمل المعماري

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

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

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

المتطلبات

للبدء، تحتاج إلى مفتاح Gemini API وبيئة قادرة على إرسال طلبات API. يعرض دليل البدء الرسمي استخدام Python SDK وJavaScript SDK وREST، كما يقدم أمثلة لـ Java وGo. اخترنا Python في هذا الشرح.

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

عند الانتقال إلى الاستخدام المدفوع، تُتاح للحساب حدود طلبات أوسع؛ ويتطلب ذلك إعداد Cloud Billing. ويذكر دليل Google دفعًا مسبقًا لا يقل عن 5 دولارات أمريكية أو ما يعادلها من العملة مقابل الأرصدة المدفوعة. هذه ليست تقديرًا لتكلفة الاستخدام، بل شرط الدفع المسبق المذكور في المصدر. تحقّق من إعدادات الحساب والفوترة قبل الانتقال إلى الاستخدام المدفوع.

الأمر الوارد في الدليل الرسمي لتثبيت Python SDK:

pip install -U google-genai

إنشاء استدعاء دالة خطوة بخطوة

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

2. حدّد المعلومات التي ستطلبها من النموذج. يمكن أن يكون طلب المستخدم، مثلًا، كالتالي:

ابحث في كتالوج المواد عن أغطية أرضيات فاتحة اللون وبمظهر حجري لمشروعي.

يمثل هذا النص مثالًا على تحويل النموذج لطلب بلغة طبيعية إلى معلمات دالة. وينبغي تحديد الحقول المطلوبة في التطبيق وفقًا لبنية الكتالوج؛ وفي المثال أدناه، يُحفظ نص البحث في حقل نصي واحد.

1. أعِد مخطط الدالة. تحدد أمثلة استدعاء الدوال من Google اسم الدالة ووصفها ومخطط المعلمات. ويُحدَّد نوع المعلمات، وتُضاف الحقول الإلزامية إلى قائمة required. يمثّل search_materials والحقل query أدناه مثالًا معدّلًا ليتناسب مع كتالوج معماري.

from google import genai

search_materials_function = {
    "type": "function",
    "name": "search_materials",
    "description": "Searches a project material catalog using a text query.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The material search query."
            }
        },
        "required": ["query"]
    }
}

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

1. أرسل الطلب إلى Gemini API وافحص خطوة الاستدعاء. تستخدم أمثلة دليل البدء العميل genai.Client() وطلب interactions.create وحقول النتائج مثل interaction.output_text. أما وثيقة استدعاء الدوال فتوضح التحقق من نوع function_call بين خطوات الاستجابة، وقراءة اسم الدالة ومعلماتها.

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="ابحث عن أغطية أرضيات فاتحة اللون وبمظهر حجري لمشروعي.",
    tools=[search_materials_function],
)

for step in interaction.steps:
    if step.type == "function_call":
        print("الدالة:", step.name)
        print("المعلمات:", step.arguments)

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

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

أخطاء شائعة

• ترك وصف الدالة غامضًا: ينبغي توضيح مهمة الأداة المتوقع أن يختارها النموذج. ويجب أن تدعم أسماء الدوال وأوصافها وتعريفات معلماتها بعضها بعضًا.

• عدم مواءمة المعلمات مع التطبيق: يجب أن تتوافق الحقول في المخطط مع المعلومات التي يتوقعها النظام الخارجي. وإلا فقد لا يتمكن التطبيق من استخدام المعلمات التي أنشأها النموذج على نحو صحيح.

• اعتبار استدعاء النموذج هو تنفيذ العملية: ينشئ استدعاء الدوال الاستدعاءات والمعلمات اللازمة للتواصل مع نظام خارجي. أما تنفيذ الدالة في النظام الفعلي فيعتمد على الربط الذي يوفره التطبيق.

• إدارة مفتاح API بلا عناية: يساعد المفتاح على ربط طلبات API بالحساب وتتبع الاستخدام. ويوضح دليل البدء مثالًا على حفظ المفتاح في متغير بيئة.

• تجاهل الرسوم وحدود الاستخدام: تتغير حدود الطلبات وإعدادات الفوترة عند الانتقال إلى الفئة المدفوعة. تحقّق من معلومات الاستخدام والفوترة في AI Studio قبل البدء بالاستخدام.

أثر ذلك في سير عمل الهندسة المعمارية والتصور المعماري

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

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

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

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

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

أُعد هذا الدليل استنادًا إلى دليلي Google لاستدعاء الدوال في Gemini API والبدء باستخدامه. كلا المصدرين مرخّص بموجب CC BY 4.0. تُرجم المحتوى إلى التركية ووُطّع ليتناسب مع سيناريو كتالوج مواد معماري.