وثائق API: إنشاء مخرجات منظَّمة

وصف الواجهة

عند تزويد النموذج بموجّه (Prompt)، سيُرجع النموذج استجابة إكمال واحدة أو أكثر متوقعة، كما يدعم فرض إخراج منظَّم وفق JSON Schema محدد.

المرجع الرسمي: OpenAI Structured Outputs

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

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

---

ترويسات الطلب (Headers)

---

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

مثال الطلب (Request Example)

{
  "model": "gpt-4.1-2025-04-14",
  "messages": [
    {
      "role": "system",
      "content": "حدّد ما إذا كان إدخال المستخدم ينتهك إرشادات محددة واشرح السبب إذا كان كذلك."
    },
    {
      "role": "user",
      "content": "كيف أستعد لمقابلة عمل؟"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "content_compliance",
      "description": "يحدد ما إذا كان المحتوى ينتهك قواعد الإشراف المحددة",
      "schema": {
        "type": "object",
        "properties": {
          "is_violating": {
            "type": "boolean",
            "description": "يشير إلى ما إذا كان المحتوى ينتهك الإرشادات"
          },
          "category": {
            "type": ["string", "null"],
            "description": "نوع الانتهاك إذا كان المحتوى ينتهك الإرشادات، وإلا فتكون القيمة Null.",
            "enum": ["violence", "sexual", "self_harm"]
          },
          "explanation_if_violating": {
            "type": ["string", "null"],
            "description": "شرح سبب اعتبار المحتوى مخالفًا"
          }
        },
        "required": ["is_violating", "category", "explanation_if_violating"],
        "additionalProperties": false
      },
      "strict": true
    }
  }
}

---

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

مثال الاستجابة (Response Example)

{
    "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. ما هو response_format وكيف أضمن أن يُخرج النموذج JSON صارمًا؟

يتيح لك المعامل response_format مطالبة النموذج بإرجاع البيانات بتنسيق محدد. إذا كنت تريد استخدام "الإخراج المنظَّم"، فيجب ضبطه إلى {"type": "json_schema"} وتعريف JSON Schema بداخله، مع تفعيل strict: true. يضمن ذلك أن يُخرج النموذج البيانات بنسبة 100% وفق الحقول وأنواع البيانات التي حددتها، دون الحاجة إلى تنفيذ معالجة إضافية لتحمل أخطاء JSON في تطبيقك.

2. لماذا يتم اقتطاع إخراج JSON الخاص بي؟

إذا كانت قيمة choices[0].finish_reason في بيانات الاستجابة هي length، فهذا يعني أن النص المولَّد قد وصل إلى حد max_tokens، أو أنه تجاوز الحد الأقصى لطول السياق الذي يدعمه النموذج. يُنصح بزيادة قيمة max_tokens في الطلب.

3. ما الفرق بين temperature وtop_p؟ وأيّهما ينبغي أن أعدّل؟

كلاهما يُستخدم للتحكم في عشوائية إخراج النموذج:

• temperature يقوم بتحجيم توزيع احتمالات إخراج النموذج. كلما انخفضت القيمة، أصبح الإخراج أكثر دقة وحتمية؛ وكلما ارتفعت، أصبح الإخراج أكثر تفرعًا.
• top_p (أخذ العينات النووية) يقيّد النموذج بحيث يختار فقط من الكلمات الأعلى احتمالًا التي تصل كتلتها الاحتمالية التراكمية إلى p. التوصية الرسمية: عدّل أحدهما فقط، ولا تعدّل temperature وtop_p في الوقت نفسه.

4. ماذا يحدث عند تفعيل stream: true؟

عند ضبط stream: true، لن تنتظر الواجهة حتى يكتمل الجواب بالكامل قبل الإرجاع، بل ستُعيد مقاطع من البيانات بشكل متدفق وفوري كما لو أنها تُكتب مباشرة. سيتحول تنسيق الإرجاع إلى Server-Sent Events (SSE). يحتاج العميل إلى الاستماع إلى تدفق البيانات وتجميع delta.content حتى يتم استلام العلامة [DONE] التي تشير إلى النهاية.

5. كيف أضمن الحصول على نفس الإجابة تمامًا عند استدعاء نفس الـ Prompt في كل مرة؟

على الرغم من أن النماذج اللغوية الكبيرة تتضمن قدرًا من العشوائية، يمكنك تمرير المعامل seen (Seed) المحدد، وضبط temperature إلى 0، لتحقيق أعلى درجة ممكنة من الحتمية في الإخراج. إذا لاحظت أن قيمة system_fingerprint في نتيجة الإرجاع قد تغيّرت، فهذا يعني أن إعدادات النموذج في الخلفية قد تم تعديلها بشكل طفيف، وعندها قد تظهر فروق بسيطة حتى مع استخدام نفس الـ Seed.