البث المتدفق للردود عبر API في كل صيغة

مع البث المتدفق يصلك الرد على أجزاء أثناء كتابة النموذج له، فيرى المستخدم النص فورًا بدلًا من انتظار الرد كاملًا. كل الصيغ تدعمه عبر Server-Sent Events، أي أسطر تبدأ بـ data:، وقد يسبقها سطر event:.

التفعيل#

• Chat Completions وResponses وMessages: أضف "stream": true إلى جسم الطلب.
• Gemini: استدعِ :streamGenerateContent?alt=sse بدلًا من :generateContent.

مع cURL أضف -N لتظهر الأجزاء فور وصولها. وفي Python مع requests مرّر stream=True واقرأ الأسطر عبر iter_lines. المكتبات الرسمية تتولى هذا كله عنك.

curl --request POST "https://api.5abeer.ai/v1/chat/completions" \
  --header "Authorization: Bearer $KHABEER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"claude-sonnet-5.5","messages":[{"role":"user","content":"اكتب فكرة منتج في سطر واحد"}]}'

{
  "id": "chatcmpl-9f2",
  "object": "chat.completion",
  "model": "claude-sonnet-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "مرحبًا! كيف أساعدك اليوم؟"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 12,
    "total_tokens": 33
  }
}

ما يصلك في كل صيغة#

• Chat Completions: أسطر data: كل منها chat.completion.chunk والنص في choices[0].delta.content، وينتهي البث بالسطر data: [DONE].
• Responses: أحداث مسمّاة، response.created ثم response.output_text.delta وأحداث استدعاء الدوال، وينتهي بالحدث response.completed الذي يحمل الرد الكامل.
• Messages: message_start، ثم لكل كتلة content_block_start وcontent_block_delta وcontent_block_stop، ثم message_delta، وينتهي بالحدث message_stop.
• Gemini: كل حدث رد جزئي بالشكل نفسه للرد الكامل، وآخر حدث يحمل finishReason وusageMetadata.

أمثلة كاملة لكل بث في المراجع: Chat Completions وResponses وMessages وGemini.

أرقام الاستخدام#

• Chat Completions: أضف "stream_options": {"include_usage": true} فيحمل آخر جزء قبل [DONE] الحقل usage مع choices فارغة. نماذج GPT ترسله دائمًا حتى دون هذا الخيار.
• Responses: الحقل usage داخل response.completed.
• Messages: أرقام الإدخال في message_start، وأرقام الإخراج في message_delta.
• Gemini: الحقل usageMetadata في آخر حدث.

الأخطاء أثناء البث#

الخطأ الذي يقع قبل بدء البث يصلك ردًا عاديًا بصيغة JSON مع حالته في HTTP. أما بعد بدء البث فالحالة 200 قد أُرسلت، فيصلك الخطأ داخل البث:

• Chat Completions وGemini: سطر data: فيه كائن error.
• Responses: حدث response.failed.
• Messages: حدث error.

يحمل كل منها الرمز نفسه للخطأ العادي، والتفاصيل في الحدود ورموز الأخطاء. اعرض للمستخدم ما كُتب حتى الآن، واعرض عليه إعادة المحاولة.

نصائح#

• اقرأ البث سطرًا سطرًا، وتجاهل الأسطر الفارغة وأسطر event: التي لا تحتاجها.
• اجعل مهلة الانتظار طويلة، فالإجابة الطويلة قد يستمر بثها عدة دقائق.
• لا تحلّل JSON ناقصًا من استدعاء أداة قبل انتهاء كتلته؛ اجمع أجزاء arguments أو input_json_delta أولًا.