الأدلة الأساسية
البث (Streaming)
عرض مخرجات النموذج فور وصولها
نظرة عامة
يقوم البث (Streaming) بتسليم مخرجات النموذج في أحداث صغيرة بدلاً من انتظار الإجابة الكاملة. استخدم بث Responses للنماذج التي تدرج openai_responses في accepted_request_formats؛ واحتفظ ببث Chat Completions عندما يكون ذلك هو ما يتوقعه الـ SDK أو التطبيق الخاص بك بالفعل.
بث Responses
curl https://api.tokenlab.sh/v1/responses \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-terra",
"input": "Write a short poem.",
"stream": true
}'يحافظ بث Responses SSE على أسماء الأحداث والترتيب والحقول الموثقة. بعد وصول الحدث الأول، يعتبر البث الذي تمت مقاطعته غير مكتمل ولا يتم إعادة تشغيله تلقائياً.
بث Responses عبر WebSocket
اتصل بـ wss://api.tokenlab.sh/v1/responses وأرسل أحداث response.create. يتم بث استجابات WebSocket دائماً ولا تدعم background أو response.cancel. يقوم response.create مع generate: false بإرجاع معرف (ID) يمكن متابعته دون توليد مخرجات نموذج أو إنشاء تكلفة على النموذج.
يتعامل كل اتصال مع استجابة نشطة واحدة في كل مرة ويستمر لمدة تصل إلى 60 دقيقة. تتضمن الأحداث sequence_number خاصاً بنطاق الاستجابة. تستخدم أحداث البث المسماة error كائن حدث مسطح؛ بينما تستخدم إخفاقات الاتصال والبروتوكول كائن error متداخلاً.
بث Chat Completions
إذا كان إطار العمل الخاص بك لا يزال يتوقع أجزاء SSE من /v1/chat/completions، فإن ذلك يعمل أيضاً:
import os
from openai import OpenAI
with OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
) as client:
finish_reason = None
with client.chat.completions.create(
model="gpt-5.6-terra",
messages=[{"role": "user", "content": "Write a short poem."}],
stream=True,
stream_options={"include_usage": True},
) as stream:
for chunk in stream:
if not chunk.choices:
continue
choice = chunk.choices[0]
if choice.delta.content:
print(choice.delta.content, end="", flush=True)
if choice.finish_reason:
finish_reason = choice.finish_reason
if finish_reason != "stop":
raise RuntimeError(f"Stream ended without a complete text answer: {finish_reason}")بث الرسائل (Messages Streaming)
يقوم POST /v1/messages مع "stream": true بإرجاع أحداث Anthropic Messages SSE. تعامل مع البث على أنه مكتمل فقط بعد حدث message_stop؛ البث الذي ينتهي قبل ذلك يعتبر غير مكتمل.
بث Gemini
يقوم POST /v1beta/models/{model}:streamGenerateContent?alt=sse بإرجاع أجزاء Gemini. يمكن أن يحتوي الحدث على بيانات وصفية فقط، وقد تغفل الأحداث الوسيطة finishReason، ويمكن أن ينتهي البث بشكل طبيعي دون علامة [DONE] الخاصة بـ Chat Completions.
شروط إنهاء البث
شروط الإكمال النموذجية:
response.completedلبث Responses APImessage_stopلبث الرسائلfinish_reason: "stop"لبث Chat Completionsfinish_reason: "length"عند الوصول إلى حد الرموز (token limit)- أحداث استدعاء الأدوات/الوظائف عندما يريد النموذج استخدام الأدوات
نمط تطبيق الويب
قم بتشغيل مستهلك بث الـ SDK على خادمك. يجب أن يقوم المتصفح باستدعاء الواجهة الخلفية (backend) الخاصة بك والموثقة؛ احتفظ بمفتاح TokenLab في بيئة الخادم. قم بتمرير أجزاء النص (text deltas) إلى المتصفح وألغِ البث الصاعد (upstream stream) عندما يتوقف المستخدم أو ينقطع الاتصال. استخدم الـ SDK لتحليل أحداث SSE: جزء الشبكة الواحد ليس بالضرورة حدثاً كاملاً واحداً.