الأدلة الأساسية
المخرجات المهيكلة واستدعاء الأدوات
إرجاع JSON أو السماح للنموذج باستدعاء وظائف في تطبيقك
تطلب المخرجات المهيكلة من النموذج إرجاع بيانات بتنسيق JSON. أما استدعاء الأدوات فيسمح للنموذج بطلب وظيفة يقوم تطبيقك بتنفيذها. تعتمد الحقول المتاحة على تنسيق الـ API والنموذج المستخدم، لذا حافظ على تنسيق واحد طوال المحادثة وقم بالتحقق من صحة كل قيمة ينتجها النموذج داخل تطبيقك.
اختيار تنسيق API
| الحاجة | الـ API | الحقول |
|---|---|---|
| استجابات كائنات JSON قابلة للنقل | /v1/chat/completions | response_format: {"type": "json_object"} |
| استدعاء وظائف متوافق مع OpenAI | /v1/chat/completions | tools: [{ "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 بإرجاع اسم الوظيفة والوسائط؛ ويقوم تطبيقك بتنفيذها:
- أرسل الرسائل بالإضافة إلى تعريفات الأدوات.
- اقرأ استجابة النموذج بحثاً عن
tool_callsأوfunction_callأوtool_useالخاصة بـ Anthropic أو أجزاء استدعاء وظائف Gemini. - نفذ الأداة في الواجهة الخلفية (backend) الخاصة بك.
- ألحق نتيجة الأداة بنفس تنسيق الـ API.
- استمر في المحادثة حتى يرجع النموذج إجابة نهائية.
حافظ على نفس تنسيق الـ 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) |
| إنشاء استجابة | إنشاء استجابة |
| إنشاء رسالة | إنشاء رسالة |
| إنشاء محتوى Gemini | Generate Gemini Content |