BroadRouter
ابدأ الآن

الأحداث التي يرسلها الخادم (SSE)

آخر تحديث

الأحداث التي يرسلها الخادم (server-sent events أو SSE) معيار ويب يتيح للخادم دفع تدفق من الأحداث النصية إلى العميل عبر استجابة HTTP واحدة طويلة الأمد بنوع المحتوى text/event-stream. وكل حدث سطر حقل أو أكثر، مثل data:، ينتهي بسطر فارغ.

يُسمّى أيضًا: الأحداث المرسلة من الخادم، أحداث الخادم، تدفق الأحداث، SSE، server-sent events، text/event-stream، event stream، EventSource

SSE هي الصيغة النصية البسيطة التي يقوم عليها كل رد متدفق من نماذج LLM تقريبًا. ومعرفة الصيغة تفيدك حين لا تتوفر حزمة SDK أو حين يسيء البث التصرف.

كيف تعمل

يعرّف معيار WHATWG HTML الصيغة. فللاستجابة نوع MIME هو text/event-stream، وهي بترميز UTF-8 دائمًا. والجسم أسطر بالشكل field: value:

: keep-alive comment, ignored by clients

event: update
id: 42
data: first line
data: second line

data: {"choices":[{"delta":{"content":"Hi"}}]}

data: [DONE]

قواعد التحليل المهمة:

  • السطر الفارغ يُطلق الحدث. وإلى أن يصل، يخزّن العميل ما يستقبله.
  • أسطر data: المتعددة تُضم بفواصل أسطر في رسالة واحدة.
  • السطر الذي يبدأ بنقطتين تعليق. ترسله الخوادم لإبقاء الاتصالات الخاملة مفتوحة.
  • تُحذف مسافة واحدة بعد النقطتين. وقد تنتهي الأسطر بـ CRLF أو LF أو CR.
  • event وid وretry تضبط نوع الحدث، ومعرّف آخر حدث، ومهلة إعادة الاتصال بالملّي ثانية.

قراءات الشبكة لا تتطابق مع حدود الأحداث. فقد تحمل قراءة واحدة نصف حدث أو ثلاثة أحداث، لذا يجب أن يخزّن المحلّل البايتات ويقسّم عند الأسطر الفارغة، لا عند كل قراءة.

إعادة الاتصال والوسطاء و[DONE]

يبني المعيار آلية تعافٍ للمتصفحات: بعد انقطاع الاتصال، يعيد EventSource الاتصال ويرسل ترويسة Last-Event-ID، ويمكن للخادم إيقاف المحاولات بالرد HTTP 204. وتحذّر المواصفة أيضًا من أن “legacy proxy servers” (ترجمة: الخوادم الوسيطة القديمة) قد تُسقط اتصالات HTTP بعد مهلة قصيرة، وتقترح سطر تعليق “every 15 seconds or so” (ترجمة: كل 15 ثانية تقريبًا).

تستخدم واجهات LLM API قدرًا أقل من ذلك. فبث Chat Completions لدى OpenAI لا يرسل إلا أسطر data: وينتهي بـ data: [DONE]، وهذا عُرف خاص بالواجهة لا بمعيار SSE. ولا يوجد معرّف حدث يمكن الاستئناف منه، لذا لا يمكن مواصلة بث منقطع؛ وإعادة المحاولة طلب جديد. والصورة العامة لـ البث المتدفق وفائدته في زمن أول رمز مشروحة في صفحته.

في BroadNet Inference

يقول توثيق BroadNet أن تضبط stream=true وأن “read Server-Sent Events until the literal data: [DONE] marker” (ترجمة: اقرأ الأحداث التي يرسلها الخادم حتى العلامة الحرفية data: [DONE]). فإن انتهى الاتصال قبلها، فاعتبر الاستجابة ناقصة، وسجّل الترويسة X-Request-ID، وقرّر هل إرسال طلب استدلال جديد آمن. ومع stream_options: {"include_usage": true}، تصل بيانات الاستخدام في الجزء الأخير. ويستخدم مثال curl في التوثيق الخيار -N كي لا يخزّن curl المخرجات مؤقتًا. ويشغل البث أيضًا مكانًا واحدًا ضمن حد التزامن حتى ينتهي: 4 على مفتاح الدفع حسب الاستخدام، وواحد على المفتاح بالساعة. ويطلب التوثيق منك التحقق من البث لكل نموذج قبل الإنتاج. وشيفرة كل SDK موجودة في دليل البث المتدفق، ومحتويات الأجزاء مشروحة في شرح البث المتدفق في LLM.

أسئلة شائعة

هل يمكنني استخدام واجهة EventSource في المتصفح مع LLM API؟

غالبًا لا، ليس مباشرةً. فالمُنشئ EventSource في المواصفة لا يقبل إلا عنوان URL وعلامة withCredentials، فلا يستطيع إرسال جسم POST ولا ترويسة Authorization. استخدم fetch وحلّل التدفق بنفسك، أو استخدم SDK.

ماذا يعني "data: [DONE]"؟

ليس جزءًا من معيار SSE. فالواجهات على طريقة OpenAI ترسل السطر الحرفي "data: [DONE]" حدثًا أخيرًا لتعلن اكتمال الرد.

لماذا يصل البث دفعة واحدة؟

هناك شيء بين الخادم وشيفرتك يخزّن الاستجابة مؤقتًا، مثل وسيط عكسي (reverse proxy)، أو إطار عمل، أو curl دون -N. عطّل التخزين المؤقت لهذا المسار.

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity