البث (Streaming)

اضبط stream: true في Chat completions أو Responses أو Completions لتستقبل الـ tokens فور توليدها. تستخدم الاستجابة server-sent events (Content-Type: text/event-stream). يمرّر api14 إليك البايتات القادمة من المزوّد الأصلي فور وصولها ولا يخزّنها مؤقتًا.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api14.com/api/v1",
  apiKey: process.env.API14_API_KEY,
});

const stream = await client.chat.completions.create({
  "model": "openai/gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "Explain vector databases in two sentences."
    }
  ],
  "stream": true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

صيغة الأحداث

كل حدث عبارة عن سطر data: يحمل جزءًا (chunk) بصيغة JSON. ينتهي البث بـ data: [DONE].

data: {"id":"gen-1760000000-abc","object":"chat.completion.chunk","model":"openai/gpt-5-mini","choices":[{"index":0,"delta":{"role":"assistant","content":"Hel"}}]}

data: {"id":"gen-1760000000-abc","object":"chat.completion.chunk","model":"openai/gpt-5-mini","choices":[{"index":0,"delta":{"content":"lo!"}}]}

data: {"id":"gen-1760000000-abc","object":"chat.completion.chunk","model":"openai/gpt-5-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":3,"total_tokens":13,"cost":0.0000085}}

data: [DONE]

• يحمل الجزء الأخير قبل [DONE] الحقل usage، بما في ذلك cost بالدولار الأمريكي. لا تحتاج إلى stream_options.include_usage، فالإبلاغ عن الاستخدام مفعَّل دائمًا.
• قيمة id واحدة في كل الأجزاء، وهي معرّف عملية التوليد الذي يمكنك تمريره إلى الاستعلام عن عملية توليد.
• يرسل بعض المزوّدين أسطر تعليقات SSE تبدأ بـ : لإبقاء الاتصال مفتوحًا. تتجاهلها عملاء SSE وحِزم OpenAI SDK. إذا كنت تحلّل البث بنفسك، فتخطَّ الأسطر التي تبدأ بـ :.

الفوترة في البث

تقرأ البوابة جزء usage الأخير أثناء تمرير البث، وتخصم من رصيدك بمجرد إغلاق البث.

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

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

الأخطاء التي تقع قبل البايت الأول، مثل مفتاح غير صالح أو رصيد منخفض أو نموذج غير معروف، تُعيد خطأ JSON عاديًا برمز حالة 4xx أو 5xx. راجع الأخطاء. وإذا فشل المزوّد في منتصف البث، فقد ينتهي البث بجزء يحتوي على كائن error وfinish_reason: "error":

{ "error": { "code": 502, "message": "Provider disconnected" }, "choices": [{ "delta": { "content": "" }, "finish_reason": "error" }] }

تحقّق دائمًا من finish_reason في الجزء الأخير.

نصائح

• تقوم الخوادم الوكيلة (proxies) والمنصات بدون خادم (serverless) أحيانًا بتخزين الاستجابات مؤقتًا. عطّل التخزين المؤقت للاستجابة (مثل X-Accel-Buffering: no في nginx) إذا كنت تمرّر البث إلى المتصفحات.
• تُبثّ استدعاءات الأدوات على شكل أجزاء delta.tool_calls. اجمع سلاسل arguments حسب index قبل تحليلها. راجع استدعاء الأدوات.
• تبثّ نماذج الاستدلال تفكيرها في delta.reasoning قبل الإجابة. راجع الاستدلال.