إنشاء إكمالات دردشة لفهم الصور (بثّ/Streaming) best64

وصف الواجهة:
عند تقديم مطالبة (Prompt)، سيُرجع هذا النموذج إكمالًا واحدًا أو أكثر متوقَّعًا، ويمكنه أيضًا إرجاع احتمالات الرموز البديلة لكل موضع. تُستخدم هذه الواجهة بشكل أساسي لإنشاء إكمالات محادثة تتضمن فهم الصور (استنادًا إلى Base64) إلى جانب المطالبات النصية.

المرجع الرسمي: توثيق OpenAI API

تفاصيل الواجهة

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

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

اسم المعامل	مطلوب	النوع	القيمة المثالـية	الوصف
Content-Type	نعم	string	`application/json`	تنسيق البيانات
Accept	نعم	string	`application/json`	تنسيق الاستجابة المقبول
Authorization	لا	string	`Bearer {{YOUR_API_KEY}}`	رمز المصادقة

معاملات الطلب (Request Body)

اسم الحقل	النوع	مطلوب	الوصف
model	string	نعم	معرّف النموذج المراد استخدامه (مثل: `gpt-4o-mini`).
messages	array	نعم	قائمة الرسائل الموجودة في المحادثة حتى الآن. تتضمن `role` و`content`. بالنسبة لفهم الصور، يمكن أن يكون `content` مصفوفة تحتوي على نص و`image_url` (بصيغة Base64).
tools	array	نعم	قائمة الأدوات التي يمكن للنموذج استدعاؤها. حاليًا لا يتم دعم سوى الدوال كأدوات. تُستخدم لتوفير تعريفات الدوال التي يمكن للنموذج توليد إدخال JSON لها.
tool_choice	object	نعم	يتحكم في الدالة التي سيتم استدعاؤها. تعني `none` عدم الاستدعاء؛ وتعني `auto` الاختيار التلقائي؛ ويمكن أيضًا فرض استدعاء دالة محددة.
temperature	integer	لا	درجة حرارة أخذ العينات، وتتراوح بين 0 و2. القيم الأعلى (مثل 0.8) تجعل المخرجات أكثر عشوائية، بينما القيم الأقل (مثل 0.2) تجعلها أكثر حتمية. يُنصح بعدم تعديلها مع `top_p` في الوقت نفسه.
top_p	integer	لا	معامل أخذ العينات بالنواة (nucleus sampling). تعني القيمة 0.1 أنه سيتم النظر فقط في الرموز التي تُشكّل أعلى 10% من الكتلة الاحتمالية. يُنصح بعدم تعديله مع `temperature` في الوقت نفسه.
n	integer	لا	عدد خيارات إكمال الدردشة المطلوب توليدها لكل رسالة إدخال. القيمة الافتراضية هي 1.
stream	boolean	لا	مفتاح البثّ (Streaming). القيمة الافتراضية `false`. إذا تم تعيينه إلى `true`، فسيتم إرسال زيادات جزئية من الرسالة بصيغة Server-Sent Events (SSE)، وينتهي البث عند `data: [DONE]`.
stop	string	لا	تسلسل سيؤدي إلى إيقاف توليد المزيد من الرموز بواسطة API (بحد أقصى 4 تسلسلات). القيمة الافتراضية هي null.
max_tokens	integer	لا	الحد الأقصى لعدد الرموز التي يمكن توليدها في إكمال الدردشة. القيمة الافتراضية هي inf (غير محدود).
presence_penalty	number	لا	عقوبة الوجود (-2.0 إلى 2.0). تؤدي القيم الموجبة إلى معاقبة الرموز الجديدة بناءً على ما إذا كانت قد ظهرت من قبل في النص، مما يزيد احتمال تطرق النموذج إلى مواضيع جديدة.
frequency_penalty	number	لا	عقوبة التكرار (-2.0 إلى 2.0). تؤدي القيم الموجبة إلى معاقبة الرموز بناءً على تكرار ظهورها في النص الحالي، مما يقلل من احتمال تكرار النموذج لنفس المحتوى. القيمة الافتراضية هي 0.
logit_bias	object	لا	تعديل احتمال ظهور رموز محددة في الإكمال. يقبل كائن JSON يربط معرّفات الرموز بقيم انحياز تتراوح بين -100 و100.
user	string	لا	معرّف فريد يمثّل المستخدم النهائي لديك، للمساعدة في المراقبة واكتشاف إساءة الاستخدام.
response_format	object	لا	يحدد التنسيق الذي يجب أن يخرج به النموذج. تمرير `{ "type": "json_object" }` يفعّل وضع JSON. عند استخدامه، يجب أن تطلب من النموذج في المطالبة أن يخرج بصيغة JSON.
seen	integer	لا	ميزة تجريبية (Beta). بذرة أخذ عينات حتمية؛ استخدام نفس البذرة ونفس المعاملات في طلبات متكررة ينبغي أن يُرجع النتيجة نفسها (من دون ضمان حتمية مطلقة).

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

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "أنت مساعد مفيد."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "ماذا يوجد في هذه الصورة؟ يرجى وصفها بالتفصيل."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAiEAAAIhCAYAAACYF2qHAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAgAElEQVR4nOy9ebxtWVXf+x1zrrX2Pud2VRQUjUVf0glIYvOJLdJ8iCagIor... (تم اختصار سلسلة base64 الطويلة هنا)"
          }
        }
      ]
    }
  ]
}

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

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

مثال على الاستجابة (نجاح 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: كيف يمكن تفعيل البثّ (Streaming)؟
ج: قم بتعيين المعامل stream إلى true داخل جسم الطلب. بعد التفعيل، لن تنتظر الواجهة حتى يتم توليد الإجابة كاملة، بل ستُعيد البيانات تدريجيًا بصيغة Server-Sent Events (SSE) على شكل data: {...}، حتى يتم استلام العلامة data: [DONE] التي تشير إلى انتهاء التوليد.

س2: ما متطلبات ترميز Base64 للصور؟
ج: يجب أن تتضمن سلسلة Base64 الخاصة بالصورة بادئة صحيحة لنوع MIME، مثل data:image/png;base64, أو data:image/jpeg;base64,۔ يُنصح بضغط أبعاد الصورة بشكل مناسب قبل تحويلها إلى Base64 لتقليل زمن نقل الشبكة وخفض استهلاك prompt_tokens (فالصور الكبيرة جدًا قد تستهلك عددًا كبيرًا من الرموز أو حتى تتجاوز حد نافذة السياق).

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

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

س5: ماذا أفعل إذا واجهت خطأ 401 Unauthorized؟
ج: تحقق من أن رأس الطلب Authorization يحمل مفتاح API بشكل صحيح، ويجب أن يكون التنسيق بدقة: Bearer 你的API_KEY (لاحظ وجود مسافة واحدة بين Bearer والمفتاح).