دون البث، لا يُعيد إكمال المحادثة أي شيء حتى تكتمل الإجابة كلها. فالرد البالغ 600 رمز بسرعة نحو 100 رمز في الثانية يعني عدة ثوانٍ من الصمت. ومع البث تظهر الكلمات الأولى بمجرد أن يكتبها النموذج. يشرح هذا المقال ما ينتقل فعلًا عبر الشبكة، وكيف تحلّله، وكيف تستخرج استخدام الرموز من البث، وكيف توقفه بسلاسة. وللاطلاع على قواعد BroadNet الخاصة باختصار، راجع الدليل المرجعي للبث.
كيف يبدو بث SSE على الشبكة؟
أحداث Server-Sent Events هي استجابة HTTP عادية بترويسة Content-Type: text/event-stream. يُبقي الخادم الاتصال مفتوحًا ويكتب الأحداث. وكل حدث سطر data: واحد أو أكثر يليه سطر فارغ. وتضع الواجهات المتوافقة مع OpenAI مقطع JSON واحدًا في كل حدث، وتنتهي بالقيمة الحرفية [DONE]:
data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}
data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"One, "},"finish_reason":null}],"usage":null}
data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"two, three."},"finish_reason":"stop"}],"usage":null}
data: {"id":"c1","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":6,"total_tokens":20}}
data: [DONE]
الشكل أعلاه توضيحي ومختصر. فالمقاطع الحقيقية تحمل أيضًا model وcreated، وقد تُبلغ نماذج الاستدلال المنطقي عن رموز الاستدلال ضمن الاستخدام.
ماذا يحتوي المقطع؟
| الحقل | أين | معناه |
|---|---|---|
choices[0].delta.role |
المقطع الأول | عادةً assistant. يُرسل مرة واحدة. |
choices[0].delta.content |
معظم المقاطع | الجزء التالي من النص. قد يكون فارغًا. |
choices[0].delta.tool_calls |
استدعاءات الأدوات | أجزاء من اسم الدالة ووسائط JSON، تُجمع حسب index. |
choices[0].finish_reason |
آخر مقطع محتوى | stop أو length أو tool_calls. وقيمته null قبل ذلك. |
usage |
المقطع الأخير، إن طُلب | إجماليات الطلب كله. وقيمته null في كل مكان آخر. |
الفكرة الأساسية هي الفرق (delta) لا اللقطة الكاملة. فكل مقطع يحمل الجديد فقط، وأنت تعيد بناء الرسالة بجمع الأجزاء بالترتيب. واستدعاءات الأدوات تُبث بالطريقة نفسها: تصل الوسائط أجزاءً نصية ليست JSON صالحًا حتى يصل آخرها، فلا تحلّلها إلا بعد أن تصبح قيمة finish_reason هي tool_calls.
كيف تحصل على استخدام الرموز من البث؟
الاستجابة غير المتدفقة تتضمن usage دائمًا. أما البث فلا، إلا إذا طلبت. اضبط stream_options: {"include_usage": true} فيرسل الخادم مقطعًا إضافيًا واحدًا قبل [DONE]. يحمل هذا المقطع الإجماليات ومصفوفة choices فارغة. وعلى BroadNet Inference قد يتضمن الاستخدام أيضًا prompt_tokens_details.cached_tokens وcompletion_tokens_details.reasoning_tokens حين يُبلغ النموذج عنهما، وهذا ما تحتاجه لتسجيل التكلفة.
والخطأ الشائع: الشيفرة التي تقرأ chunk.choices[0] في كل مقطع تُطلق خطأ فهرس عند مقطع الاستخدام. افحص choices أولًا.
Python: البث وجمع الاستخدام والإلغاء
import os
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
stream = client.chat.completions.create(
model="broadnet/deepseek-v4.1-flash", # DeepSeek V4.1 Flash, a reasoning model
messages=[{"role": "user", "content": "Explain SSE in three sentences."}],
stream=True,
stream_options={"include_usage": True},
max_tokens=2000, # reasoning counts toward this limit
)
def user_pressed_stop(): # replace with your own condition
return False
parts, usage, finish = [], None, None
try:
for chunk in stream:
if chunk.choices:
choice = chunk.choices[0]
if choice.delta.content:
parts.append(choice.delta.content)
print(choice.delta.content, end="", flush=True)
if choice.finish_reason:
finish = choice.finish_reason
if chunk.usage:
usage = chunk.usage
if user_pressed_stop(): # your own condition
break
finally:
stream.close() # closes the HTTP connection
text = "".join(parts)
الأمر break وحده يوقف القراءة، لكن المقبس (socket) يبقى مفتوحًا حتى يجمعه جامع المهملات. أغلقه صراحةً ليرى الخادم انقطاع الاتصال.
Node: البث مع AbortController
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY });
const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // hard stop after 30 s
const stream = await client.chat.completions.create(
{
model: "broadnet/deepseek-v4.1-flash",
messages: [{ role: "user", content: "Explain SSE in three sentences." }],
stream: true,
stream_options: { include_usage: true },
},
{ signal: controller.signal },
);
let text = "";
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) text += delta;
if (chunk.usage) console.log(chunk.usage);
}
يوثّق ملف README لمكتبة openai-node الخيار signal، وهو يعمل أثناء قراءة جسم الاستجابة أيضًا. وفي خادم ويب، اربط controller.abort() بحدث close لطلب العميل، حتى يوقف المستخدم الذي يغادر الصفحة التوليدَ أيضًا. ومزيد من الإعداد في دليل Node SDK.
curl: رؤية الأحداث الخام
curl -N https://inference.broadnet.ai/v1/chat/completions \
-H "Authorization: Bearer $BROADNET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"broadnet/gemma-4-26b-a4b","stream":true,"stream_options":{"include_usage":true},"messages":[{"role":"user","content":"Count to five."}]}'
الخيار -N يعطّل التخزين المؤقت للمخرجات فتُطبع الأحداث فور وصولها. اضغط Ctrl+C للإلغاء؛ فهذا يغلق الاتصال. ومنشئ طلبات API يولّد هذا الطلب، ونسختيه بـ Python وNode، لأي نموذج وعنوان أساسي (base URL).
كيف تلغي البث، وكم يكلّف ذلك؟
الإلغاء في SSE مجرد إغلاق للاتصال، فلا توجد رسالة «توقف». وما يحدث بعد ذلك يعود إلى الخادم: فالخادم المنضبط يلاحظ المقبس المغلق ويتوقف عن التوليد. والرموز المنتَجة قبل تلك اللحظة عمل حقيقي. ولا يوثّق المرجع التقني لواجهة BroadNet احتساب البث الملغى، فخطّط على أساس أن الرموز المولّدة حتى الانقطاع تُحتسب في الدفع حسب الاستخدام، وراجع سجلات استخدامك. وفي الخطة الثابتة لا يكلّف البث الملغى شيئًا إضافيًا، لكنه لا يحرّر الجلسة إلا حين يتوقف الخادم.
خمسة أخطاء في البث يجب فحصها
- الوكلاء الذين يخزّنون الاستجابات مؤقتًا. Nginx وبعض شبكات CDN تخزّن الاستجابات مؤقتًا، فيستلم العميل كل شيء دفعة واحدة. عطّل التخزين المؤقت في الوكيل لمسار البث.
- غياب فحص
[DONE]. الاتصال المنقطع يبدو إجابة قصيرة. اعتبر غياب[DONE]إجابة غير مكتملة وسجّلX-Request-ID، كما يصف دليل الأخطاء. - إعادة المحاولة في منتصف البث. حزم SDK لا تعيد المحاولة بعد أن يبدأ جسم الاستجابة بالوصول. وإعادة المحاولة طلب جديد، وفي الدفع حسب الاستخدام فاتورة جديدة.
- تجاهل
finish_reason: length. في نماذج الاستدلال المنطقي مثل DeepSeek V4.1 Flash يُحتسب التفكير ضمن max_tokens، فقد يوقف الحد الصغير البث قبل ظهور أي نص مرئي. راجع ما تكلّفه رموز الاستدلال المنطقي. - تقسيم الأسطر بطريقة خاطئة. إن كنت تحلّل SSE يدويًا، فخزّن البايتات حتى ترى سطرًا فارغًا. فقراءة TCP قد تنتهي في منتصف مقطع JSON.
أين تقع BroadNet Inference من هذا؟
تستخدم BroadNet Inference شكل البث القياسي المتوافق مع OpenAI، فتحلّله حزمتا Python وNode دون تعديل. ويتضمن الاستخدام في المقطع الأخير الرموز المخزّنة مؤقتًا ورموز الاستدلال المنطقي حين يُبلغ النموذج عنها. وتقول وثائقها إنه يجب التحقق من البث لكل نموذج قبل الاستخدام في بيئة الإنتاج، فشغّل الشيفرة أعلاه على النموذج نفسه الذي تطلقه. وإن كان أكثر ما يهمك هو سرعة وصول الرمز الأول، فاقرأ بعد ذلك TTFT مقابل الإنتاجية. وإن كنت تحتاج إلى صوت فوري عبر WebSockets، فهذه الواجهة ليست مصمّمة لذلك؛ فهي تقدّم إكمالات المحادثة وتفريغ الملفات الصوتية.
