BroadRouter
ابدأ الآن

شرح البث في LLM: مقاطع SSE والفروقات (delta) والاستخدام والإلغاء

بقلم فريق BroadNet Inference · قراءة في 4 دقائق · تاريخ النشر · آخر تحديث

تبث واجهة LLM API إكمال المحادثة بوصفه أحداث Server-Sent Events: كل سطر data يحمل مقطع JSON يحمل فيه choices[0].delta الجزء التالي من النص. اجمع الفروقات، وتوقف عند data: [DONE]، واضبط include_usage في stream_options لتحصل على أعداد الرموز في مقطع أخير بقائمة choices فارغة. وللإلغاء، أغلق الاتصال.

دون البث، لا يُعيد إكمال المحادثة أي شيء حتى تكتمل الإجابة كلها. فالرد البالغ 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 احتساب البث الملغى، فخطّط على أساس أن الرموز المولّدة حتى الانقطاع تُحتسب في الدفع حسب الاستخدام، وراجع سجلات استخدامك. وفي الخطة الثابتة لا يكلّف البث الملغى شيئًا إضافيًا، لكنه لا يحرّر الجلسة إلا حين يتوقف الخادم.

خمسة أخطاء في البث يجب فحصها

  1. الوكلاء الذين يخزّنون الاستجابات مؤقتًا. Nginx وبعض شبكات CDN تخزّن الاستجابات مؤقتًا، فيستلم العميل كل شيء دفعة واحدة. عطّل التخزين المؤقت في الوكيل لمسار البث.
  2. غياب فحص [DONE]. الاتصال المنقطع يبدو إجابة قصيرة. اعتبر غياب [DONE] إجابة غير مكتملة وسجّل X-Request-ID، كما يصف دليل الأخطاء.
  3. إعادة المحاولة في منتصف البث. حزم SDK لا تعيد المحاولة بعد أن يبدأ جسم الاستجابة بالوصول. وإعادة المحاولة طلب جديد، وفي الدفع حسب الاستخدام فاتورة جديدة.
  4. تجاهل finish_reason: length. في نماذج الاستدلال المنطقي مثل DeepSeek V4.1 Flash يُحتسب التفكير ضمن max_tokens، فقد يوقف الحد الصغير البث قبل ظهور أي نص مرئي. راجع ما تكلّفه رموز الاستدلال المنطقي.
  5. تقسيم الأسطر بطريقة خاطئة. إن كنت تحلّل SSE يدويًا، فخزّن البايتات حتى ترى سطرًا فارغًا. فقراءة TCP قد تنتهي في منتصف مقطع JSON.

أين تقع BroadNet Inference من هذا؟

تستخدم BroadNet Inference شكل البث القياسي المتوافق مع OpenAI، فتحلّله حزمتا Python وNode دون تعديل. ويتضمن الاستخدام في المقطع الأخير الرموز المخزّنة مؤقتًا ورموز الاستدلال المنطقي حين يُبلغ النموذج عنها. وتقول وثائقها إنه يجب التحقق من البث لكل نموذج قبل الاستخدام في بيئة الإنتاج، فشغّل الشيفرة أعلاه على النموذج نفسه الذي تطلقه. وإن كان أكثر ما يهمك هو سرعة وصول الرمز الأول، فاقرأ بعد ذلك TTFT مقابل الإنتاجية. وإن كنت تحتاج إلى صوت فوري عبر WebSockets، فهذه الواجهة ليست مصمّمة لذلك؛ فهي تقدّم إكمالات المحادثة وتفريغ الملفات الصوتية.

أسئلة شائعة

ما الفرق بين SSE وWebSockets في بث استجابات LLM؟

SSE اتجاه واحد، من الخادم إلى العميل، عبر استجابة HTTP عادية. وهذا كل ما يحتاجه إكمال المحادثة، لذلك تستخدم الواجهات المتوافقة مع OpenAI تقنية SSE. أما WebSockets فثنائية الاتجاه وتحتاج إلى ترقية البروتوكول؛ وتُستخدم للصوت الفوري، لا لإكمالات المحادثة.

لماذا قيمة usage فارغة (null) في مقاطع البث لدي؟

لا يُرسل الاستخدام إلا إذا طلبته. أضف stream_options مع ضبط include_usage على true. عندها تكون قيمة usage فارغة في كل مقطع ما عدا الأخير، ويحمل المقطع الأخير الإجماليات مع قائمة choices فارغة.

هل أدفع إذا ألغيت البث؟

يختلف المزوّدون، وكثير منهم لا يوثّق ذلك. افترض أن الرموز المولّدة قبل أن يلاحظ الخادم إغلاق الاتصال تُحتسب. سجّل X-Request-ID وقارنه بسجلات استخدامك.

كيف أعرف أن البث انتهى بشكل طبيعي؟

إذا استلمت data: [DONE] وكان لآخر مقطع محتوى finish_reason مثل stop. أما finish_reason بقيمة length فتعني أن max_tokens قطعت الإجابة. وغياب [DONE] يعني أن الاتصال انقطع.

هل يجعل البث النموذج أسرع؟

لا. إجمالي زمن التوليد هو نفسه. لكن البث يقلّل الوقت حتى يرى المستخدم الكلمات الأولى، وهذا ما يجعل واجهة المحادثة تبدو سريعة.

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