استخدم أداة الدالة

مكتمل

نصيحة

راجع علامة التبويب النص والصور لمزيد من التفاصيل!

تتيح أداة الدوال لنموذجك استدعاء الدوال المعرفة من قبل المطور لاسترجاع البيانات أو تفعيل الإجراءات أثناء الاستجابة.

ما هي أداة الوظيفة؟

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

هذا النمط مثالي لربط التفكير النموذجي بالأنظمة الواقعية مثل واجهات برمجة التطبيقات (APIs)، وقواعد البيانات، وسير العمل التجاري، ووظائف المرافق.

تتضمن الميزات الرئيسية:

• استدعاءات الأدوات المهيكلة - يصدر النموذج طلبات استدعاء وظيفية صريحة
• التنفيذ الذي يتحكم به المطور - تطبيقك يقرر كيف وأين تعمل الوظائف
• نمط التكامل الموثوق - استدعاء واجهات برمجة التطبيقات (APIs)، الخدمات الداخلية، أو أدوات المساعدة بأمان
• التنسيق متعدد الأدوار - إعادة مخرجات الأداة وترك النموذج يستمر في التفكير
• الردود الأرضية - يمكن أن تشمل الإجابات بيانات حية مولدة من النظام

حالات الاستخدام الشائعة

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

مثال بسيط

إليك مثالا يعرض دالة get_time ويسمح للنموذج باستدعاؤها عند الحاجة:

import time
from openai import OpenAI

# Function to get the current time
def get_time():
    return f"The time is {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime())}"


# Main function
def main():
    client = OpenAI(
        base_url={openai_endpoint},
        api_key={auth_key_or_token}
    )

    function_tools = [
        {
            "type": "function",
            "name": "get_time",
            "description": "Get the current time"
        }
    ]

    # Initialize messages with a system prompt
    messages = [
        {"role": "developer", "content": "You are an AI assistant that provides information."},
    ]

    # Loop until the user types 'quit'
    while True:
        prompt = input("\nEnter a prompt (or type 'quit' to exit)\n")
        if prompt.lower() == "quit":
            break

        # Append the user prompt to the messages
        messages.append({"role": "user", "content": prompt})

        # Get initial response
        response = client.responses.create(
            model=model_deployment,
            input=messages,
            tools=function_tools
        )

        # Append model output to the messages
        messages += response.output

        # Was there a function call?
        for item in response.output:
            if item.type == "function_call" and item.name == "get_time":
                current_time = get_time()
                messages.append({
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": current_time
                })

                # Get a follow up response using the tool output
                response = client.responses.create(
                    model=model_deployment,
                    instructions="Answer only with the tool output.",
                    input=messages,
                    tools=function_tools
                )

        print(response.output_text)


# Run the main function when the script starts
if __name__ == '__main__':
    main()

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

قد يبدو الناتج شيئا كالتالي:

Enter a prompt (or type 'quit' to exit)
Hello

Hello! How can I help you today?

Enter a prompt (or type 'quit' to exit)
What time is it?

The time is 2026-03-19 17:17:41.

Enter a prompt (or type 'quit' to exit)

لم يتطلب أول موجه للمستخدم ("مرحبا") استخدام أداة الوظائف، لذا استجاب النموذج بشكل طبيعي. التنبيه الثاني ("كم الساعة؟") كان يشغل النموذج لاختيار الدالة get_time التي أشار إليها في رده. بعد ذلك، يقوم كود التطبيق بتشغيل الدالة ويعيد النتائج إلى النموذج، الذي يرسل بعد ذلك استجابة ثانية بنتائج الدالة.

نصيحة

يستخدم هذا المثال دالة واحدة بدون معلمات. يمكنك تكوين الأداة لاستخدام وظائف متعددة، مع أو بدون معلمات. لمزيد من المعلومات حول تحديد تفاصيل الوظائف، راجع دليل مطوري OpenAI.

كيف تعمل أداة الدوال

العملية العامة لاستخدام أداة الدالة هي:

1. أنت تعرف الأدوات - توفر تعريفا أو أكثر للوظيفة في مصفوفة الأدوات.
2. النموذج يقيم التوجيه - يحدد ما إذا كانت هناك حاجة لاستدعاء دالة.
3. النموذج يصدر استدعاء دالة - يتضمن الرد اسم الدالة وبيانات الاستدعاء.
4. تطبيقك يشغل المنطق - شغل وظيفة المطابقة في الكود الخاص بك.
5. تعيد مخرجات الدالة - ترسل عنصرا function_call_output بالنتيجة.
6. النموذج يكمل الإجابة - يدمج نتائج الأدوات في الرد النهائي.

أفضل الممارسات

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

القيود التي يجب معرفتها

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

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