استدعاء الأدوات والمخرجات المنظّمة في Gemini API: دليل للعمارة

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

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

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

المتطلبات

تتضمن وثائق Gemini API من Google أمثلة على SDK لـPython وJavaScript، إلى جانب أمثلة لـJava وGo وREST. يستخدم مثال Python العميل genai من حزمة google، بينما يستخدم مثال JavaScript الحزمة @google/genai. وفي مثال REST، يُمرر مفتاح API عبر المتغير GEMINI_API_KEY. لا توضح المصادر خطوات الإعداد أو الرسوم أو شروط الحساب؛ لذا ينبغي عدم افتراضها، والتحقق بشكل منفصل من أحدث المعلومات المتعلقة بإمكانية الوصول إلى API والأسعار قبل التطبيق.

اسم النموذج المستخدم في الأمثلة هو gemini-3.8-flash. ينبغي اختيار النموذج وفق متطلبات التطبيق؛ والمثال هنا يتبع اسم النموذج الوارد في الوثائق المصدرية. وعلى الفرق التي ستعمل باستخدام الشيفرة تجهيز SDK الخاص باللغة المستخدمة وإمكانية الوصول إلى Gemini API. لا يتطلب هذا الدليل بيئة تطوير متكاملة أو إضافة لبرنامج معماري محدد.

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

خطوة بخطوة: استدعاء الوظائف

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

from google import genai

get_room_data_function = {
    "type": "function",
    "name": "get_room_data",
    "description": "Returns room data for a project.",
    "parameters": {
        "type": "object",
        "properties": {
            "project_id": {"type": "string"}
        },
        "required": ["project_id"]
    }
}

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Mimari projedeki mekân verilerini getir.",
    tools=[{"type": "function", **get_room_data_function}]
)

for step in interaction.steps:
    if step.type == "function_call":
        print(step.name)
        print(step.arguments)

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

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

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

خطوة بخطوة: المخرجات المنظّمة

1. حدّد حقول البيانات المطلوبة. يمكن، مثلًا، إنشاء مخطط يتضمن أنواع الكائنات والمصفوفات والنصوص والأعداد الصحيحة لاستخراج اسم المساحة ومساحتها وبنود متطلباتها من ملاحظة مشروع. اختر أنواع الحقول وفق طريقة استخدام التطبيق لهذه البيانات. وتشرح المصادر، إلى جانب JSON Schema، خيارات تعريف المخططات باستخدام Pydantic في Python وZod في JavaScript.

2. أضف المخطط إلى الطلب. يوضح مثال Python أدناه كيفية طلب الاستجابة بصيغة JSON واستلامها من الحقل output_text. أسماء الحقول مثال تعليمي يركز على العمارة؛ وينبغي تحديد المعلومات المراد استخلاصها من مستندات المشروع وفق متطلبات العمل.

from google import genai

client = genai.Client()
room_schema = {
    "type": "object",
    "properties": {
        "rooms": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "room_name": {"type": "string"},
                    "area_m2": {"type": "integer"},
                    "requirements": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["room_name", "area_m2", "requirements"]
            }
        }
    },
    "required": ["rooms"]
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Proje notundaki mekânları çıkar: giriş holü 12 m²; doğal ışık gereksinimi var.",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": room_schema
    }
)

print(interaction.output_text)

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

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

أخطاء شائعة

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

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

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

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

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

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

أُعد هذا الدليل بالاستناد إلى وثيقتي Google المنشورتين لـGemini API: “Function calling with the Gemini API” و“Structured outputs”. وكلتا الوثيقتين مرخصة بموجب CC BY 4.0. أُعدّت الأمثلة ذات الطابع المعماري خصيصًا لهذا الدليل.