وثائق واجهة API: إنشاء استدعاء دوال للدردشة

وصف الواجهة

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

• المرجع الرسمي: Function Calling Guide

المعلومات الأساسية

• طريقة الطلب: POST
• عنوان الطلب: https://api.codingplanx.ai/v1/chat/completions
• تنسيق البيانات: application/json

---

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

---

جسم الطلب (Body)

مثال على جسم الطلب

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "system",
            "content": "أنت مساعد دعم عملاء مفيد. استخدم الأدوات المتاحة لمساعدة المستخدم."
        },
        {
            "role": "user",
            "content": "مرحبًا، هل يمكنك إخباري بتاريخ تسليم طلبي؟"
        },
        {"role": "assistant", "content": "مرحبًا! يمكنني مساعدتك في ذلك. هل يمكنك تزويدي بمعرّف الطلب من فضلك؟"},
        {"role": "user", "content": "أعتقد أنه order_12345"}
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_delivery_date",
                "description": "احصل على تاريخ تسليم طلب العميل. استدعِ هذه الدالة كلما احتجت إلى معرفة تاريخ التسليم، على سبيل المثال عندما يسأل العميل: أين طردي؟",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "order_id": {
                            "type": "string",
                            "description": "معرّف طلب العميل."
                        }
                    },
                    "required": [
                        "order_id"
                    ],
                    "additionalProperties": false
                }
            }
        }
    ]
}

---

معاملات الاستجابة (Response)

مثال على الاستجابة (200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
مرحبًا، كيف يمكنني مساعدتك اليوم؟"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

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

س1: كيف يمكنني فرض استدعاء النموذج لدالة محددة بعينها؟
ج: يمكنك تحقيق ذلك عبر ضبط المعامل tool_choice. على سبيل المثال، إذا كان اسم دالتك هو get_weather، فيمكنك تعيين tool_choice إلى: {"type": "function", "function": {"name": "get_weather"}}۔ بهذه الطريقة سيتجاهل النموذج الرد العادي ويُخرج فقط معاملات تلك الدالة.

س2: لماذا تم اقتطاع محتوى الرد الخاص بي؟
ج: يُرجى التحقق من قيمة choices[0].finish_reason في الاستجابة. إذا كانت "length"، فهذا يعني أن النص الذي تم توليده تجاوز حد المعامل max_tokens الذي حددته، أو أنه بلغ الحد الأقصى لطول السياق الخاص بالنموذج. يمكنك محاولة زيادة قيمة max_tokens.

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

س4: ما هو تنسيق البيانات التي تُرجعها الواجهة عند تفعيل stream: true؟
ج: عند تفعيل البث، لن تُرجع الواجهة كائن JSON واحدًا، بل ستُرجع تدفق بيانات بصيغة Server-Sent Events (SSE). سيتم إرسال البيانات على شكل كتل مثل: data: {"id": "...", "choices": [{"delta": {"content": "..."}}]} ، وعند اكتمال الإرسال ستكون آخر رسالة هي data: [DONE].

س5: ما الذي يجب الانتباه إليه عند تفعيل response_format في وضع JSON؟
ج: عندما تضبط response_format على { "type": "json_object" }، يجب عليك في الوقت نفسه أن توضّح صراحةً داخل messages (في موجّه النظام أو موجّه المستخدم) أن على النموذج توليد بيانات بتنسيق JSON. إذا لم تفعل ذلك، فقد يدخل النموذج في حلقة توليد مستمرة للمسافات البيضاء، مما يؤدي إلى انتهاء مهلة الطلب أو بلوغ الحد الأعلى للرموز.