إنشاء واجهة محادثة لفهم الصور (متدفق/غير متدفق)

تدعم هذه الواجهة إدخالًا متعدد الوسائط، مما يسمح للمستخدمين بإرسال نصوص وروابط صور URL داخل المحادثة. سيقوم النموذج بإنشاء رد مناسب بناءً على نص الطلب ومحتوى الصورة. كما تدعم الإخراج المتدفق (Streaming) لتوفير تجربة تفاعل أكثر سلاسة.

عنوان الواجهة: https://api.codingplanx.ai/v1/chat/completions
طريقة الطلب: POST
المرجع الرسمي: OpenAI Chat Completion API

معلمات الطلب

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

معلمات Body

اسم المعلمة	النوع	مطلوب	القيمة الافتراضية	الوصف
model	string	نعم	-	معرّف النموذج المستخدم (مثل `gpt-4o`, `gpt-4-vision-preview`).
messages	array	نعم	-	قائمة الرسائل في المحادثة حتى الآن. راجع هيكل `messages` أدناه.
stream	boolean	لا	`false`	ما إذا كان سيتم تفعيل الإخراج المتدفق. عند التفعيل سيتم إرسال Server-Sent Events (SSE).
temperature	number	لا	`1`	درجة حرارة أخذ العينات (0-2). كلما زادت كان الناتج أكثر عشوائية، وكلما انخفضت كان أكثر ثباتًا.
top_p	number	لا	`1`	احتمال أخذ العينات النووي. يُنصح عادةً بتعديل هذا الخيار أو `temperature` فقط، وليس كليهما معًا.
max_tokens	integer	لا	inf	الحد الأقصى لعدد الرموز التي يمكن توليدها في إكمال المحادثة.
n	integer	لا	`1`	عدد نتائج الإكمال التي سيتم إنشاؤها لكل رسالة إدخال.
presence_penalty	number	لا	`0`	(-2.0 إلى 2.0) القيم الموجبة تزيد احتمال تحدث النموذج عن مواضيع جديدة.
frequency_penalty	number	لا	`0`	(-2.0 إلى 2.0) القيم الموجبة تقلل احتمال تكرار النموذج لنفس الكلمات.
response_format	object	لا	-	تحديد صيغة الإخراج، مثل `{"type": "json_object"}`.
stop	string/array	لا	null	تسلسلات إيقاف توليد الرموز (حتى 4 كحد أقصى).
user	string	لا	-	معرّف فريد للمستخدم النهائي يُستخدم لمراقبة إساءة الاستخدام.

هيكل كائن messages

كل عنصر في قائمة الرسائل يحتوي على الحقول التالية:

role: (string) الدور، ويمكن أن يكون system, user, assistant, tool.
content: (string أو array) محتوى الرسالة.
- في وضع فهم الصور، يكون content عبارة عن مصفوفة تحتوي على كائنات من النوع text و image_url.

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

طلب JSON يجمع بين النص وفهم الصور

{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "أنت مساعد متخصص في تحليل الصور."
      },
      {
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "ماذا يوجد في هذه الصورة؟ يرجى الوصف بالتفصيل."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.png"
                    }
                }
            ]
        }
    ],
    "stream": true
}

شرح الاستجابة

الاستجابة غير المتدفقة (stream: false)

اسم المعلمة	النوع	الوصف
id	string	المعرّف الفريد لهذا الطلب.
object	string	نوع الكائن، وعادةً ما يكون `chat.completion`.
created	integer	الطابع الزمني للإنشاء (بالثواني).
choices	array	قائمة الخيارات التي أنشأها النموذج.
choices[n].message	object	كائن الرسالة التي أعادها النموذج (يتضمن `role` و `content`).
choices[n].finish_reason	string	سبب التوقف (مثل `stop`, `length`).
usage	object	إحصاءات استخدام الرموز.

مثال على الاستجابة

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "تُظهر هذه الصورة بحيرة هادئة، وخلفها سلسلة من الجبال المتصلة."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 120,
        "completion_tokens": 35,
        "total_tokens": 155
    }
}

الاستجابة المتدفقة (stream: true)

عندما تكون قيمة stream هي true، تعيد الواجهة text/event-stream. يبدأ كل سطر بـ data: ، ويكون المحتوى عبارة عن سلسلة JSON. أما آخر رسالة فتكون data: [DONE].

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

Q1: كيف يمكن رفع صورة بدلًا من استخدام URL؟
A: تدعم هذه الواجهة بشكل أساسي روابط الصور URL. إذا كانت لديك صورة محلية فقط، فيُنصح أولًا برفعها إلى خدمة استضافة صور أو تخزين كائنات (OSS)، أو تحويل الصورة إلى سلسلة Base64 بالتنسيق data:image/jpeg;base64,{base64_encode_data} ووضعها داخل الحقل url.

Q2: لماذا لا يظهر لديّ إحصاء usage في الطلبات المتدفقة؟
A: في بروتوكول التدفق المتوافق مع OpenAI، عادةً ما يتم إرجاع usage فقط في آخر جزء من البيانات أو من خلال إعداد معلمة خاصة مثل stream_options. يرجى التحقق مما إذا كان إصدار النموذج لديك يدعم إرجاع عدد الرموز أثناء التدفق.

Q3: ما حدود حجم الصورة والصيغ المدعومة لفهم الصور؟
A: يتم دعم PNG, JPEG, WEBP, GIF (غير المتحرك) بشكل عام. يُنصح بأن لا يتجاوز حجم الصورة 20MB. ولأفضل نتائج في التعرف، يُفضّل أن تكون الدقة 512x512 أو أعلى.

Q4: ماذا أفعل إذا ظهر الخطأ "401 Unauthorized"؟
A: تأكد من أنك مرّرت الحقل Authorization بشكل صحيح داخل Header، بالتنسيق Bearer متبوعًا بمفتاح API الخاص بك، وتأكد أيضًا من أن المفتاح صالح وأن الرصيد كافٍ.

Q5: هل تؤثر معلمة temperature على فهم الصور؟
A: نعم. تؤثر temperature على درجة الإبداع في وصف الصورة. إذا كنت تحتاج إلى وصف موضوعي ودقيق جدًا، فيُنصح بضبطها على قيمة منخفضة (مثل 0.2)؛ أما إذا كنت ترغب في وصف أكثر حيوية وإبداعًا، فيمكنك استخدام قيمة أعلى (مثل 0.8).

Q6: كيف أتعامل مع التعرف على عدة صور؟
A: يمكنك وضع عدة كائنات من النوع image_url داخل مصفوفة messages.content، وسيحاول النموذج فهم محتوى هذه الصور معًا.