الأدلة الأساسية

المخرجات المهيكلة واستدعاء الأدوات

إرجاع JSON أو السماح للنموذج باستدعاء وظائف في تطبيقك

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

اختيار تنسيق API

الحاجةالـ APIالحقول
استجابات كائنات JSON قابلة للنقل/v1/chat/completionsresponse_format: {"type": "json_object"}
استدعاء وظائف متوافق مع OpenAI/v1/chat/completionstools: [{ "type": "function", "function": ... }]
أدوات استجابات OpenAI/v1/responsesحقول tools و tool_choice و text الخاصة بالاستجابات
استخدام أدوات Claude أو التفكير/v1/messagesمخطط أدوات Anthropic Messages
تعريفات وظائف Gemini أو الأدوات المدمجة/v1beta/models/:model:generateContentأدوات tools وأجزاء المحتوى الخاصة بـ Gemini

استخدم الأدوات المدمجة فقط مع تنسيق الـ API الذي يوثقها؛ لا تقوم TokenLab بتحويل تلك الأدوات بين التنسيقات.

وضع JSON

للحصول على كائن JSON يعمل عبر العديد من نماذج الدردشة، استخدم وضع JSON الخاص بـ Chat Completions:

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}

النماذج التي تدعم وضع JSON تدرج json-mode ضمن capabilities في GET /v1/models. تقبل Chat Completions كلاً من text و json_object. أما json_schema و strict فهما خاصان بنموذج وتنسيق معينين؛ استخدمهما فقط عندما يوثق النموذج المختار دعمهما.

قم دائماً بتحليل والتحقق من صحة JSON المُعاد على خادمك. وضع JSON لا يغني عن التحقق من صحة المخطط (schema) على مستوى التطبيق.

إكمال استدعاء أداة

تقوم TokenLab بإرجاع اسم الوظيفة والوسائط؛ ويقوم تطبيقك بتنفيذها:

  1. أرسل الرسائل بالإضافة إلى تعريفات الأدوات.
  2. اقرأ استجابة النموذج بحثاً عن tool_calls أو function_call أو tool_use الخاصة بـ Anthropic أو أجزاء استدعاء وظائف Gemini.
  3. نفذ الأداة في الواجهة الخلفية (backend) الخاصة بك.
  4. ألحق نتيجة الأداة بنفس تنسيق الـ API.
  5. استمر في المحادثة حتى يرجع النموذج إجابة نهائية.

حافظ على نفس تنسيق الـ API حتى يكتمل استدعاء الأداة والإجابة النهائية. تمثل التنسيقات الأربعة حالة الأداة بشكل مختلف.

مثال على Chat Completions

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

كتابة مخطط (schema) مفيد

  • حافظ على المخططات صغيرة وصريحة. المخططات المتداخلة الكبيرة تزيد من استهلاك الـ tokens وتقلل من الموثوقية.
  • فضل الحقول المطلوبة (required fields) للقيم التي لا يمكن لمنتجك الاستمرار بدونها.
  • استخدم التعدادات (enums) للمجموعات المغلقة التي تعتمد عليها واجهة المستخدم أو الواجهة الخلفية الخاصة بك.
  • قم بتضمين أمثلة في الـ prompt عندما يواجه النموذج صعوبة في فهم الشكل المطلوب.
  • إذا كان الحقل غير مدعوم، قم بإزالته أو استخدم تنسيق API يوثقه.

قبل تنفيذ أداة

  • سجل تنسيق الـ API، والنموذج، وأسماء الأدوات، وأسماء حقول المخطط.
  • تحقق من وسائط الأداة قبل تنفيذ أي تأثير جانبي.
  • طبق فحوصات الأذونات الخاصة بك قبل تنفيذ الأداة.
  • اجعل تنفيذ الأداة قابلاً للتكرار (idempotent) في حال تكرار العميل لطلب الأداة نفسه.
  • لا تقم بتسجيل الأسرار التي تعيدها الأدوات في الرسائل المرئية للنموذج.

مرجع الـ API

الموضوعالمرجع
API متعدد التنسيقاتMulti-Format API
إنشاء إكمال دردشةإنشاء إكمال المحادثة (Create Chat Completion)
إنشاء استجابةإنشاء استجابة
إنشاء رسالةإنشاء رسالة
إنشاء محتوى GeminiGenerate Gemini Content

في هذه الصفحة