استریم

هر دو مسیر دات‌هوش استریم را به شکل بومی خودشان ارائه می‌دهند: رویدادهای Server-Sent Events روی مسیر OpenAI و رویدادهای بومی Anthropic روی مسیر Anthropic. کدی که امروز با SDK خودتان استریم می‌گیرید، بدون تغییر کار می‌کند.

فعال‌کردن

استریم با stream: true در بدنهٔ درخواست روشن می‌شود و پاسخ از نوع text/event-stream است.

curl -N "https://gateway.dothoosh.com/v1/chat/completions" \
  -H "Authorization: Bearer $DOTHOOSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "stream": true,
    "messages": [{ "role": "user", "content": "یک بند دربارهٔ تهران بنویس" }]
  }'

شکل رویدادها

روی /v1/chat/completions هر رویداد یک خط data: است که یک chat.completion.chunk را حمل می‌کند؛ متن در choices[0].delta.content می‌آید و آخرین قطعه finish_reason را دارد:

data: {"id":"chatcmpl_…","object":"chat.completion.chunk","created":1774000000,"model":"YOUR_MODEL","choices":[{"index":0,"delta":{"role":"assistant","content":"تهران"},"finish_reason":null}]}

data: {"id":"chatcmpl_…","object":"chat.completion.chunk","created":1774000000,"model":"YOUR_MODEL","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

سه نکته که رفتار استریم را قابل‌پیش‌بینی می‌کند:

• پایان استریم `[DONE]` است. دقیقاً یک رویداد پایانی می‌آید: [DONE] یا یک خطا.
• `usage` فقط اگر بخواهید می‌آید. با "stream_options": {"include_usage": true} یک قطعهٔ آخر پیش از [DONE] با choices خالی و usage کامل می‌آید. بدون این گزینه، تسویه در سمت سرور همان‌طور انجام می‌شود، اما در استریم چیزی به شما نشان داده نمی‌شود.
• رویداد ناشناخته نادیده گرفته می‌شود. دات‌هوش رویدادهای ناشناخته را پس از اعتبارسنجی قالب دور می‌ریزد تا افزودن رویداد جدید در آینده استریم شما را نشکند.

روی /v1/responses رویدادها نام‌دار هستند (event: به‌همراه data:) و رویداد پایانی response.completed است؛ usage در همان رویداد پایانی می‌آید. رویدادهای پایانی دیگر response.failed، response.incomplete و error هستند.

روی /anthropic/v1/messages ترتیب رویدادها بومی Anthropic است: message_start، سپس برای هر بلوک content_block_start و content_block_delta و content_block_stop، سپس message_delta با مصرف تجمعی و در پایان message_stop. رویداد ping ممکن است در هر نقطه بیاید و باید نادیده گرفته شود. رویداد پایانی message_stop یا error است.

خطا در میانهٔ استریم

خطای میانهٔ استریم با همان پوشش پروتکل اعلام می‌شود و استریم را پایان می‌دهد:

پس از نخستین بایت، دات‌هوش مسیر را عوض نمی‌کند و درخواست را خودکار تکرار نمی‌کند: تکرار کورکورانه یعنی پرداخت دوباره برای پاسخی که نیمه‌کاره مانده است. کد partial_stream_after_first_byte retryable: false دارد و به بررسیٔ دستی ارجاع می‌شود.

قطع اتصال از سمت شما

اگر کلاینت اتصال را ببندد، دات‌هوش درخواست بالادست را لغو می‌کند و مصرفی که تا آن لحظه اندازه‌گیری شده است تسویه می‌شود. جریان‌های معلق رها نمی‌شوند و مصرف نامعلوم هرگز صفر فرض نمی‌شود.

فشار برگشتی

استریم با یک صف محدود به سمت شما جریان می‌گیرد. اگر مصرف‌کننده کندتر از تولیدکننده بخواند، فشار برگشتی به بالادست منتقل می‌شود و از رشد بی‌حد حافظه جلوگیری می‌شود. صف را با خواندن پیوستهٔ استریم خالی نگه دارید؛ پردازش سنگین خود را بعد از دریافت قطعه انجام دهید، نه داخل حلقهٔ خواندن.

مطالب مرتبط

• مسیردهی و تلاش مجدد
• خطاها و محدودیت‌ها
• سازگاری با OpenAI