الوثائق الرسمية لواجهة برمجة تطبيقات استدعاء الدوال (Function Calling)

تُستخدم هذه الواجهة لإنشاء إكمال دردشة (Chat Completion). من خلال توفير قائمة الرسائل وقائمة اختيارية من الأدوات (Functions)، يمكن للنموذج إنشاء رد نصي، أو إنشاء معاملات بصيغة JSON مطابقة لبنية محددة لاستدعاء دالة خارجية.

1. معلومات الواجهة

عنوان الواجهة: https://api.codingplanx.ai/v1/chat/completions
طريقة الطلب: POST
نوع المحتوى: application/json
طريقة المصادقة: Authorization: Bearer {{YOUR_API_KEY}}

2. معاملات الطلب

2.1 رؤوس الطلب (Headers)

اسم المعامل	النوع	مطلوب	مثال	الوصف
Content-Type	string	نعم	`application/json`	ثابت ويجب أن يكون `application/json`
Accept	string	نعم	`application/json`	يُنصح بتثبيته على `application/json`
Authorization	string	نعم	`Bearer sk-xxxxxx`	المصادقة باستخدام مفتاح API

2.2 جسم الطلب (Body)

اسم المعامل	النوع	مطلوب	القيمة الافتراضية	الوصف
model	string	نعم	-	معرّف النموذج المستخدم (مثل `gpt-4o`, `gpt-3.5-turbo` وغيرها).
messages	array	نعم	-	قائمة الرسائل في المحادثة حتى الآن. يحتوي كل عنصر على `role` (`"system"`, `"user"`, `"assistant"`, `"tool"`) و `content`.
tools	array	نعم	-	قائمة الأدوات التي يمكن للنموذج استدعاؤها. حاليًا يتم دعم `type: "function"` فقط. تُستخدم لتعريف اسم الدالة ووصفها والمعاملات الخاصة بها.
tool_choice	object/str	لا	`auto`	للتحكم في الدالة التي يجب على النموذج استدعاؤها. `none`: عدم الاستدعاء؛ `auto`: اختيار تلقائي؛ `{"type": "function", "function": {"name": "xxx"}}`: فرض استدعاء دالة محددة.
temperature	number	لا	1	درجة حرارة أخذ العينات (0-2). كلما زادت كانت النتائج أكثر عشوائية، وكلما انخفضت كانت أكثر حسمًا.
top_p	number	لا	1	احتمال أخذ العينات النووية (nucleus sampling).
n	integer	لا	1	عدد خيارات الإكمال التي سيتم إنشاؤها لكل رسالة إدخال.
stream	boolean	لا	false	ما إذا كان سيتم الإرسال بشكل متدفق. عند تعيينه إلى `true`، سيتم إرسال الرموز على شكل أحداث يرسلها الخادم (SSE).
stop	string/array	لا	null	تسلسلات الإيقاف التي تتوقف عندها الواجهة عن إنشاء الرموز.
max_tokens	integer	لا	inf	الحد الأقصى لعدد الرموز التي يمكن إنشاؤها.
presence_penalty	number	لا	0	قيمة بين -2.0 و 2.0. تزيد من احتمالية حديث النموذج عن مواضيع جديدة.
frequency_penalty	number	لا	0	قيمة بين -2.0 و 2.0. تقلل من احتمالية تكرار النموذج لنفس المحتوى.
response_format	object	لا	-	يحدد تنسيق الإخراج. مثل `{"type": "json_object"}` لتفعيل وضع JSON.
seed	integer	لا	-	إذا تم تحديده، سيحاول النظام جعل أخذ العينات حتميًا قدر الإمكان بحيث تُرجع الطلبات المتطابقة بنفس البذرة ونفس المعاملات النتيجة نفسها.
user	string	لا	-	معرّف فريد يمثل المستخدم النهائي، ويُستخدم لمراقبة إساءة الاستخدام.

3. مثال على الطلب

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "كيف هو طقس بكين اليوم؟"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "الحصول على الطقس الحالي لموقع محدد",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "اسم المدينة، مثل: مدينة بكين"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "tool_choice": "auto",
    "temperature": 0.8
}

4. معاملات الاستجابة

4.1 بنية جسم الاستجابة

اسم المعامل	النوع	الوصف
id	string	المعرّف الفريد لهذا الطلب.
object	string	نوع الكائن، ويكون عادةً `chat.completion`.
created	integer	طابع زمني Unix (بالثواني).
choices	array	يحتوي على قائمة بالاستجابات المُنشأة.
└ message	object	يحتوي على `role`, `content`، وقد يحتوي أيضًا على `tool_calls`.
└ finish_reason	string	سبب التوقف. `stop` (توقف طبيعي)، `length` (تم الوصول إلى `max_tokens`)، `tool_calls` (يتطلب استدعاء أداة).
usage	object	إحصاءات الاستهلاك: `prompt_tokens`, `completion_tokens`, `total_tokens`.

4.2 مثال على الاستجابة (نص عادي)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "الطقس في بكين اليوم مشمس، ودرجة الحرارة 25 درجة مئوية."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

5. الأسئلة الشائعة (FAQs)

س1: ما هو Function Calling (استدعاء الأدوات)؟
ج: هذه طريقة تمنح النموذج القدرة على استخدام إمكانات خارجية. لا يقوم النموذج بتنفيذ الشيفرة مباشرة، بل يُنشئ كائن JSON يحتوي على اسم الدالة والمعاملات المطلوبة. عليك استخراج هذا الـ JSON، ثم تنفيذ الدالة داخل بيئتك المحلية أو على خادمك، وبعد ذلك إعادة النتيجة إلى النموذج.

س2: لماذا قمت بإعداد tools ولكن النموذج لم يُرجع tool_calls؟
ج: قد تكون هناك الأسباب التالية:

يرى النموذج أن سؤال المستخدم لا يحتاج إلى استدعاء تلك الدالة.
وصف الدالة (description) غير واضح بما يكفي، مما يجعل النموذج غير قادر على مطابقة النية.
تم تعيين tool_choice صراحة إلى none.
قيود في قدرات النموذج (يُنصح باستخدام gpt-4o أو gpt-3.5-turbo أو غيرها من النماذج التي تدعم استدعاء الأدوات).

س3: كيف يمكنني إجبار النموذج على استدعاء دالة معيّنة؟
ج: يمكنك تعيين tool_choice إلى كائن محدد، على سبيل المثال:
"tool_choice": {"type": "function", "function": {"name": "get_current_weather"}}
بهذه الطريقة، حتى لو رأى النموذج أن الاستدعاء غير ضروري، فسيحاول إنشاء معاملات تلك الدالة.

س4: ماذا أفعل إذا كانت قيمة finish_reason هي length؟
ج: هذا يعني أن الرد المُنشأ تجاوز حد max_tokens أو تجاوز حد نافذة السياق الخاصة بالنموذج. يمكنك محاولة زيادة قيمة max_tokens، أو تقليص طول سجل messages.

س5: ما الذي يجب الانتباه إليه عند استخدام وضع JSON (JSON Mode)؟
ج: عند تعيين response_format: { "type": "json_object" }، يجب أن تطلب بوضوح من النموذج في رسالة System أو User أن يرد بصيغة JSON (على سبيل المثال: تضمين عبارة مثل "أجب بصيغة JSON")، وإلا فقد يدخل النموذج في حلقة لا نهائية من إخراج المسافات الفارغة.

س6: كيف أتعامل مع عدة استدعاءات أدوات؟
ج: في طلب واحد، قد يُنتج النموذج عدة استدعاءات أدوات في الوقت نفسه (على سبيل المثال، الاستعلام عن طقس بكين وشنغهاي معًا). عليك المرور على المصفوفة choices[0].message.tool_calls وتنفيذ المنطق المحلي المقابل لكل استدعاء على حدة.