شروع کار

استریم

قالب SSE در چت، پایان استریم، قطعه‌ی usage با مقدار اعتبار، خطای میانه‌ی راه و رفتار هنگام قطع شدن اتصال.

برای گرفتن پاسخ تکه‌تکه در POST /v1/chat/completions، فیلد stream: true را بفرستید. پاسخ به‌جای JSON، یک جریان Server-Sent Events است. /v1/messages، /v1/responses و /v1beta/models/{model}:streamGenerateContent هم استریم دارند و رویدادهای قالب خودشان را می‌فرستند. توضیح این بخش درباره‌ی قالب OpenAI است.

قالب

سرآیندهای پاسخ Content-Type: text/event-stream; charset=utf-8 و Cache-Control: no-cache, no-transform هستند. هر قطعه یک خط data: با یک شیء JSON است و بین قطعه‌ها یک خط خالی می‌آید:

text
data: {"id":"chatcmpl-6f1d3c52-8a0e-4b1e-9d7a-2f6f1c3b9a10","object":"chat.completion.chunk","created":1790000000,"model":"openai/gpt-6-luna","choices":[{"index":0,"delta":{"role":"assistant","content":"Hel"},"finish_reason":null}]}

data: {"id":"chatcmpl-6f1d3c52-8a0e-4b1e-9d7a-2f6f1c3b9a10","object":"chat.completion.chunk","created":1790000000,"model":"openai/gpt-6-luna","choices":[{"index":0,"delta":{"content":"lo"},"finish_reason":null}]}

data: [DONE]
  • id در همه‌ی قطعه‌ها یکی است و برابر chatcmpl- به‌علاوه‌ی شناسه‌ی درخواست است.
  • delta متن، و در صورت وجود tool_calls، reasoning_content و refusal را می‌آورد.
  • قطعه‌ی آخر پاسخ finish_reason دارد (stop، length، tool_calls یا content_filter).
  • خط‌هایی که با : شروع می‌شوند (: ping) هر ۱۵ ثانیه برای زنده نگه داشتن اتصال می‌آیند. کتابخانه‌های SSE آن‌ها را نادیده می‌گیرند. اگر خودتان پارس می‌کنید، آن‌ها را رد کنید.

پایان استریم

استریم همیشه با data: [DONE] تمام می‌شود، چه موفق باشد چه با خطا. بعد از آن اتصال بسته می‌شود. استریمی که بدون [DONE] قطع شود، ناقص است.

قطعه‌ی usage و اعتبار

با stream_options: {"include_usage": true} درست پیش از [DONE] یک قطعه‌ی اضافه می‌آید که choices آن خالی است:

text
data: {"id":"chatcmpl-6f1d3c52-8a0e-4b1e-9d7a-2f6f1c3b9a10","object":"chat.completion.chunk","created":1790000000,"model":"openai/gpt-6-luna","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":9,"total_tokens":21,"credits":0.0042}}

مقدار credits اضافه‌ی وان ای آی است و اعتباری را می‌گوید که برای همین درخواست کم شد. در استریم سرآیند x-1ai-credits وجود ندارد، چون هزینه تا پایان استریم معلوم نیست. اگر include_usage را نفرستید، قطعه‌ی usage نمی‌آید. مقدار عددهای این مثال نمونه است. اگر درخواست از کش پاسخ گرفته شده باشد هم مقدار credits می‌آید.

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

وقتی اولین بایت فرستاده شد، وضعیت HTTP همان 200 می‌ماند. خطای بعدی به شکل یک فریم داده می‌آید و بعد [DONE]:

text
data: {"error":{"message":"The model provider did not respond in time.","type":"api_error","code":"provider_timeout","param":null,"request_id":"6f1d3c52-8a0e-4b1e-9d7a-2f6f1c3b9a10"},"credits":0.0011}

data: [DONE]

فیلد credits اینجا اعتبار توکن‌هایی است که تا قطع شدن تولید و حساب شده‌اند. کد خطا از همان فهرست خطاها است. کتابخانه‌های رسمی معمولاً چنین فریمی را خطا می‌کنند، ولی اگر خودتان پارس می‌کنید، وجود کلید error را بررسی کنید.

مسیر جایگزین (پایداری) فقط تا پیش از فرستادن اولین بایت به شما فعال است. بعد از آن، شکست استریم به همین شکل گزارش می‌شود.

قطع شدن اتصال

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

قاعده‌های نگهبان و استریم

اگر برای درخواست قاعده‌ی نگهبانِ «خروجی» تعریف شده باشد، دروازه ابتدا کل پاسخ را نگه می‌دارد، بررسی می‌کند و بعد قطعه‌ها را یک‌جا می‌فرستد. در این حالت زمان رسیدن اولین قطعه به اندازه‌ی کل تولید پاسخ است.

صفحه‌های مرتبط