بخش 2.5 · درون محیط اجرا

حالت‌های استریمینگ در مبدأ، و بافر تصویر نسخهٔ 3

Stream modes at their source, and the v3 projection buffer

فهرست مطالب
  1. یک صف، هفت حالت، شش تولیدکننده
  2. استریم نسخهٔ 3 را خواننده جلو می‌کشد
  3. علت رخ دادن مسئلهٔ langchain#38484
  4. کدی که باید برای مصرف‌کننده نوشت

در هر پیام فقط یک تصویر (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، ترتیب زیر را نشان می‌دهد:

تمام حالت‌های یک اجرای ایجنت، بر حسب زمان capture/lab/internals/05-streaming/trace.txt
     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 میلی‌ثانیه یک توکن استریم شد. این زمان‌بندی‌ها مربوط به یک بار اجرا روی ماشین مهمانی با بار پردازشی بالاست؛ بنابراین به ترتیب حالت‌ها توجه کنید، نه لزوماً به اعداد زمان. شکل هر حالت را روی فازهای مختلف اجرا جای‌گذاری کرده است.

محل تولید هر حالت استریم در یک اجرای ایجنتموارد updates، messages و custom هنگام اجرای وظایف تولید می‌شوند، values پس از فاز به‌روزرسانی و چک‌پوینت‌ها فقط هنگام شروع سوپرگام بعدی.
محل تولید هر حالت استریم در یک اجرای ایجنت هفت ردیف، هر ردیف برای یک حالت استریم، روی محور زمان به میلی‌ثانیه برای یک اجرای create_agent با Qwen3 4B روی مهمان سرور x86، با تمام حالت‌ها فعال و نسخه v2. محور سه اسپن بزرگ‌نمایی‌شده با بریدگی دارد: شروع، پایان گام اول مدل و گام ابزارها حوالی 1.9 ثانیه، و پاسخ از 2.6 ثانیه. سوپرگام‌ها عبارتند از مدل از 5 تا 1895.5 میلی‌ثانیه، ابزارها از 1895.5 تا 1900 میلی‌ثانیه، مدل از 1900 تا 3335.9 میلی‌ثانیه. هر تیک یک آیتم است: وظایف 6، پیام‌ها 13، سفارشی 1، به‌روزرسانی‌ها 3، مقادیر 4، چک‌پوینت‌ها 5، اشکال‌زدایی 11. آیتم‌های messages، custom و updates حین اجرای وظیفه یا هنگام پایان آن ظاهر می‌شوند. آیتم values بعد از فاز به‌روزرسانی می‌آید. آیتم‌های checkpoints و debug یک گام در ابتدای سوپرگام بعدی ظاهر می‌شوند، همراه با آیتم شروع tasks. توکن‌های پاسخ از 2658.7 میلی‌ثانیه رسیدند، تقریباً هر 67 میلی‌ثانیه یک عدد. حالت استریم شروع پایان مدل ابزارها پاسخ مدل وظایف 6 پیام‌ها 13 سفارشی 1 به‌روزرسانی‌ها 3 مقادیر 4 چک‌پوینت‌ها 5 اشکال‌زدایی 11 0 4 8 1894 1896 1898 1900 2600 2800 3000 3200 3400 ms 1 2 3 4 1 custom: the tool calls stream_writer at 1899.6 ms, inside the tools task 2 updates: وظیفه ابزارها در 1899.6 میلی‌ثانیه تمام و خروجی‌هایش یکجا فرستاده می‌شود 3 values: بعد از فاز به‌روزرسانی سوپرگام، در 1900 میلی‌ثانیه 4 چک‌پوینت‌ها: هنگام برنامه‌ریزی سوپرگام بعدی صادر می‌شوند، در 1900 میلی‌ثانیه
محور افقی میلی‌ثانیه از شروع یک اجرای create_agent است، در سه اسپن بزرگ‌نمایی‌شده با بریدگی‌هایی میان آن‌ها. هر ردیف یک حالت استریم و هر تیک یک آیتم است. نوار سایه‌دار سوپرگام ابزارهاست، برچسب‌های بالا گام‌های مدل را نام می‌برند و اعداد از یادداشت‌های زیر محور پیروی می‌کنند. از capture/lab/internals/05-streaming/trace.txt.

استریم نسخهٔ 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 اول خود خارج شود تا زمانی که آخرین توکن متنی هم از راه برسد:

سه حلقه مصرف‌کننده در ثبت داده‌ها capture/lab/internals/05-streaming/run.py
    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 دلتای متنی تولید شد:

اجرای 0 از هر حلقه capture/lab/internals/05-streaming/trace.txt
  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 هر حلقه را روی یک محور زمان مقایسه می‌کند.

دلتاهای متنی ارسال‌شده و دریافت‌شده در سه حلقه مصرف‌کننده v3حلقه‌ای که ابتدا استدلال را می‌خواند، همه 60 دلتای متنی را یکجا و 8.8 ثانیه پس از اولین ارسال دریافت می‌کند، در حالی که سایر حلقه‌ها هر کدام را ظرف 5 میلی‌ثانیه می‌گیرند.
دلتاهای متنی ارسال‌شده و دریافت‌شده در سه حلقه مصرف‌کننده v3 سه جفت ردیف روی محور زمان به ثانیه، اجرای 0 از پنج به ازای هر حلقه مصرف‌کننده روی نسخه v3 از stream_events در یک اجرای create_agent. مدل Qwen3 8B با حالت استدلال روشن، روی Ollama در مهمان سرور x86 است. این مدل حدود 211 دلتای استدلال را از ثانیه اول تا حدود 31.3 ثانیه ارسال کرد، سپس 60 دلتای متن را طی حدود 8.6 ثانیه فرستاد. ردیف بالایی هر جفت نشان می‌دهد هر دلتای متن چه زمانی ارسال شده است، و ردیف پایینی زمان دریافت آن توسط حلقه را مشخص می‌کند. حلقه‌های text-only و raw-events هر دلتا را ظرف چند میلی‌ثانیه دریافت کردند؛ در تمام پنج اجرا، بیشترین تأخیر آن‌ها 4.9 و 0.9 میلی‌ثانیه بود. حلقه‌ای که ابتدا message.reasoning را می‌خواند، همه 60 دلتای متنی را در 40.5 ثانیه دریافت کرد، تا 8786.6 میلی‌ثانیه پس از ارسال. در طول پنج اجرا، اولین دلتای متنی آن بین 8786.6 تا 9036.1 میلی‌ثانیه تأخیر داشت. حلقه مصرف‌کننده فقط متن ارسال شد دریافت شد بیشترین تأخیر 4.6 ms در این اجرا رویدادهای خام ارسال شد دریافت شد بیشترین تأخیر 0.9 ms در این اجرا استدلال، سپس متن ارسال شد دریافت شد هر 60 دلتا در فهرست message.text تا 8.8 s منتظر می‌مانند 30 32 34 36 38 40 42 s استدلال قبل از 31.3 s زنده استریم شد و رسم نشده است اولین دلتای متن با 8.79 تا 9.04 s تأخیر در هر 5 اجرا
هر جفت ردیف یک حلقه است، اجرای 0 از پنج. تیک‌های زیتونی ارسال‌ها توسط مدل هستند، و تیک‌های پایینی لحظاتی هستند که حلقه یک دلتا را دریافت کرده است. نوار گل‌بهی اسپن زمانی انتظار متن است. استدلال قبل از اسپن نمایش داده‌شده اجرا شد. برگرفته از capture/lab/internals/05-streaming/v3_38484.json و capture/lab/internals/05-streaming/trace.txt.

یک پول‌ریکوئست بسته‌شده برای این مشکل (#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.