در هر پیام فقط یک تصویر (projection) نسخهٔ 3 یا رویدادهای خام را بخوانید؛ چون حلقهای که اول استدلال را میخواند، پاسخ یک مدل استدلالی را با 8.8 تا 9.0 ثانیه تأخیر نشان داد.
رابط کاربری چت را به یک مدل استدلالی و متد stream_events(version="v3") تغییر میدهید. روند فکر کردن مدل به مدت نیم دقیقه زنده استریم میشود. سپس پاسخ نهایی، پس از مکثی به اندازهٔ زمان تولید خود پاسخ، یکباره ظاهر میشود. لاگهای سرور نشان میدهند که مدل، پاسخ را توکنبهتوکن فرستاده است. توکنها در تمام این مدت داخل فرایند حضور داشتهاند؛ منتها درون بافری که حتی از وجودش خبر نداشتید.
با اتمام این بخش، تابعی را که هر حالت استریم را تولید میکند و لحظهٔ دقیق وقوع آن در ابرگام (superstep) را خواهید شناخت. همچنین میتوانید مشکل گزارششده در langchain#38484 را با استناد به کد توضیح دهید و یک مصرفکنندهٔ نسخهٔ 3 بنویسید که هر توکن را درست در لحظهٔ رسیدن نمایش دهد.
یک صف، هفت حالت، شش تولیدکننده
تمام حالتهای استریم در stream() خروجی خود را داخل یک صف مینویسند. حلقهٔ اجرایی بین زمانهای تکمیل وظایف، این صف را خالی میکند و فرمت نسخهٔ 2 هر آیتم را در قالب یک شیء StreamPart شامل type، ns و data بستهبندی میکند {{code libs/langgraph/langgraph/pregel/main.py:4436-4449}}. ما پشتهٔ فراخوانی (call stack) را در لحظهٔ ورود هر آیتم به صف ثبت کردیم:
| حالت | تولیدکننده | زمان وقوع |
|---|---|---|
checkpoints و debug |
_prepare_tasks_and_emit_checkpoint {{code libs/langgraph/langgraph/pregel/_loop.py:806-809}} |
در آغاز ابرگام بعدی |
tasks |
tick {{code libs/langgraph/langgraph/pregel/_loop.py:697-699}} |
هنگام برنامهریزی وظایف، و مجدداً همراه با هر نتیجه |
updates |
ابتدا put_writes و سپس output_writes {{code libs/langgraph/langgraph/pregel/_loop.py:563-565}} |
با پایان هر وظیفه |
values |
after_tick {{code libs/langgraph/langgraph/pregel/_loop.py:743-745}} |
پس از فاز بهروزرسانی (update phase) |
messages |
StreamMessagesHandler.on_llm_new_token {{code libs/langgraph/langgraph/pregel/_messages.py:175-188}} |
برای هر توکن مدل، از طریق کالبک |
custom |
کلوژر مربوط به stream_writer {{code libs/langgraph/langgraph/pregel/main.py:2954-2967}} |
زمانی که کد شما رایتر را فراخوانی کند |
در عمل، دو ردیف اهمیت ویژهای دارند. حالت updates به ازای هر وظیفه ارسال میشود؛ بنابراین یک وظیفهٔ موازیِ کند جلوی انتشار بهروزرسانیِ یک وظیفهٔ سریع را نمیگیرد. در مقابل، values منتظر اتمام کل ابرگام میماند. اجرای یک نمونه create_agent با فعال بودن تمام حالتها و با استفاده از مدل Qwen3 4B روی ماشین مهمان سرور x86، ترتیب زیر را نشان میدهد:
1894.5 ms messages AIMessageChunk chunk text='' node=model step=1
1894.6 ms messages AIMessageChunk chunk text='' node=model step=1
1894.6 ms updates keys=['model']
1894.6 ms tasks result model
1894.6 ms debug type=task_result step=1
1895.5 ms values 2 messages
1895.5 ms checkpoints step=1 next=['tools']
1895.5 ms debug type=checkpoint step=1
1895.5 ms tasks start tools
1895.5 ms debug type=task step=2
1899.6 ms custom {'progress': 'looking up Paris'}
1899.6 ms messages ToolMessage chunk text='Paris: sunny' node=tools step=2
…
2658.7 ms messages AIMessageChunk chunk text='The' node=model step=3
2726.1 ms messages AIMessageChunk chunk text=' weather' node=model step=3پایان گام اول مدل، گام ابزارها و شروع پاسخ. بقیه اجرا بریده شده است.
گام اول مدل 1.89 ثانیه طول کشید و هیچ متنی استریم نکرد؛ چون پاسخ آن یک فراخوانی ابزار بود. گام اجرای ابزارها 4.5 میلیثانیه زمان برد. پس از آن، پاسخ نهایی به ازای هر حدود 67 میلیثانیه یک توکن استریم شد. این زمانبندیها مربوط به یک بار اجرا روی ماشین مهمانی با بار پردازشی بالاست؛ بنابراین به ترتیب حالتها توجه کنید، نه لزوماً به اعداد زمان. شکل هر حالت را روی فازهای مختلف اجرا جایگذاری کرده است.
استریم نسخهٔ 3 را خواننده جلو میکشد
متد stream_events(version="v3") هیچ ترد پسزمینهای اجرا نمیکند. این متد گراف را فقط زمانی به پیش میبرد که خواننده دادههای بیشتری بخواهد. هر تصویر، مثل message.text، فهرستی از تغییرات تدریجی (deltas) و یک مکاننما نگه میدارد. وقتی مکاننما به انتهای فهرست برسد، تکرارکننده تابع _request_more را صدا میزند که گراف را تا زمان رسیدن رویداد جدید اجرا میکند {{code libs/core/langchain_core/language_models/chat_model_stream.py:247-269}} {{code libs/langgraph/langgraph/stream/run_stream.py:136-160}}. تکرارکننده زمانی متوقف میشود که تصویر مورد نظر علامت خاتمه (done) دریافت کند.
هر رویدادی که کشیده (pull) میشود، به تمام تصویرهای پیام مربوطهاش میرود. دلتای متنی وارد فهرست message.text میشود، حتی اگر هنوز هیچ کدی آن فهرست را نخوانده باشد.
علت رخ دادن مسئلهٔ langchain#38484
در ایشوی langchain#38484 گزارش شده که مصرفکنندهٔ نسخهٔ 3 پاسخ نهایی را یکباره تحویل میگیرد {{issue langchain#38484}}. در بخش 5.1 این رفتار را بازتولید کردیم. بررسی کد علت آن را روشن میکند.
هر سه تصویر مربوط به یک پیام در یک نقطهٔ واحد علامت پایان میخورند: درست زمانی که کل پیام به پایان برسد {{code libs/core/langchain_core/language_models/chat_model_stream.py:1092-1094}}. پایان بلوک استدلال، صرفاً همان بلوک را نهایی میکند و به معنای تکمیل message.reasoning نیست {{code libs/core/langchain_core/language_models/chat_model_stream.py:962-976}}. در نتیجه، این حلقه نمیتواند از دستور for اول خود خارج شود تا زمانی که آخرین توکن متنی هم از راه برسد:
for message in stream.messages:
if pattern == "reasoning_then_text":
for d in message.reasoning:
got.append((now(), "reasoning", d))
for d in message.text:
got.append((now(), "text", d))
elif pattern == "text_only":
for d in message.text:
got.append((now(), "text", d))
elif pattern == "raw_events":
for ev in message:
if ev.get("event") == "content-block-delta":
delta = ev.get("delta", {})
kind = "reasoning" if delta.get("type") == "reasoning-delta" else "text"
got.append((now(), kind, delta.get("reasoning") or delta.get("text")))در مدتی که حلقهٔ استدلال معطل است، دلتاهای متنی را دریافت کرده و به فهرست message.text سرازیر میکند. با پایان پیام، حلقهٔ دوم تمام آنها را به صورت آماده در بافر مییابد.
ما عملکرد این سه حلقه را روی ماشین مهمان سرور x86 با مدل Qwen3 8B، استدلالِ فعال، از طریق create_agent، با 5 بار اجرا به ازای هر حلقه و با ترکیب نوبتی اجرای حلقهها اندازه گرفتیم. زمان ارسال، لحظهای است که استریم HTTP مربوط به Ollama بخش مورد نظر را به LangChain تحویل داده است. در هر اجرا، ابتدا 211 دلتای استدلال و سپس 60 دلتای متنی تولید شد:
run 0 reasoning_then_text emitted r/t=211/60 received r/t=211/60 text emit [31688.1, 40330.7] spread 8642.6 ms; text receive [40474.7, 40474.8] spread 0.1 ms; text lag median/max [4635.1, 8786.6]; reasoning lag median/max [0.7, 7.0]
run 0 text_only emitted r/t=211/60 received r/t=0/60 text emit [32307.5, 41001.4] spread 8693.9 ms; text receive [32308.2, 41002.2] spread 8694.0 ms; text lag median/max [0.7, 4.6]; reasoning lag median/max None
run 0 raw_events emitted r/t=211/60 received r/t=211/60 text emit [32819.0, 42027.1] spread 9208.1 ms; text receive [32819.8, 42027.8] spread 9208.0 ms; text lag median/max [0.7, 0.9]; reasoning lag median/max [0.7, 4.0]در هر 5 اجرا، حلقهای که اول استدلال را میخواند، تمام 60 دلتای متنی را با فاصلهٔ کمتر از 0.1 میلیثانیه از یکدیگر دریافت کرد؛ در حالی که مدل آنها را در طول بازهٔ 8.6 تا 8.9 ثانیه فرستاده بود. این ارقام نتیجهٔ یک بار آزمایش روی سیستمی با بار کاری است؛ پس آنها را برای درک ترتیب رخداد در نظر بگیرید. دادههای سیستم مک در بخش 5.1 این میزان تأخیر را بین 4.0 تا 8.5 ثانیه نشان میدهند.
دلتاهای استدلال این حلقه زنده رسیدند. حلقهٔ فقطمتنی (text-only)، متن را با میانهٔ تأخیر 0.7 میلیثانیه و حداکثر 4.9 میلیثانیه در طول 300 دلتا دریافت کرد. حلقهٔ رویدادهای خام نیز آنها را با میانهٔ 0.7 میلیثانیه و حداکثر 0.9 میلیثانیه تحویل گرفت. شکل اجرای شمارهٔ 0 هر حلقه را روی یک محور زمان مقایسه میکند.
یک پولریکوئست بستهشده برای این مشکل (#38533)، کانفیگ اجرا را در create_agent به model_.invoke منتقل میکرد {{code libs/langchain_v1/langchain/agents/factory.py:1509}}. آن تغییر به این سازوکار ارتباطی ندارد. در همان ایجنت، حلقههای رویداد خام و فقطمتنی همین حالا هم تمام دلتاها را زنده دریافت میکردند؛ پس کالبکهای مدل بدون آن تغییر هم به استریم میرسند.
کدی که باید برای مصرفکننده نوشت
یکی از این دو ساختار را انتخاب کنید. اگر فقط پاسخ را نشان میدهید، منحصراً message.text را بخوانید. اگر هم استدلال و هم پاسخ را نشان میدهید، رویدادهای خام هر پیام را بخوانید و بر اساس نوع دلتا مسیر را تفکیک کنید؛ درست شبیه به branch مربوط به raw_events در بالا. با این کار، هر دلتا دقیقاً به ترتیبی که مدل فرستاده به رابط کاربری شما میرسد.
هرگز دو تصویر از یک پیام واحد را پشت سر هم نخوانید. این قاعده برای message.tool_calls هم صدق میکند که در بخش 5.1 اندازهگیری شد. تصویری که در نوبت دوم میخوانید، همیشه تا انتهای پیام منتظر میماند.
منابع: capture/lab/internals/05-streaming/trace.txt، capture/lab/internals/05-streaming/run.py، capture/lab/internals/05-streaming/v3_38484.json، capture/lab/internals/common/real.py؛ libs/langgraph/langgraph/pregel/main.py، libs/langgraph/langgraph/pregel/_loop.py، libs/langgraph/langgraph/pregel/_messages.py و libs/langgraph/langgraph/stream/run_stream.py در langgraph 1.2.22؛ libs/core/langchain_core/language_models/chat_model_stream.py در langchain-core 1.8.0؛ libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0؛ ایشوی langchain-ai/langchain#38484 و پولریکوئست #38533.