بخش 5.1 · وضعیت، حافظه و پایایی

استریمینگ: نسخه‌های v1 و v2، حالت stream_events v3 و حالت ابزارها

Streaming: v1, v2, stream_events v3, and the tools mode

فهرست مطالب
  1. حالت‌های استریمینگ در نسخه‌ی v1
  2. استفاده‌ی هم‌زمان از چند حالت
  3. شیء StreamPart در نسخه‌ی v2
  4. رویدادهای استریمینگ در نسخه‌ی v3 (stream_events)
  5. حالت ابزارها (tools mode)
  6. تاخیر تحویل در هر کدام از APIهای استریمینگ
  7. تصویرهای یک پیام در نسخه‌ی v3
  8. چرا تصویر دوم منتظر می‌ماند؟
  9. حلقه‌ی مصرف‌کننده‌ای که باید بنویسید
  10. استریم فراخوانی ابزار توسط یک مدل واقعی

اجرای یک ایجنت می‌تواند به سه شکل استریم شود: تکه‌های نسخه‌ی v1 که ساختارشان تابع تنظیمات شماست، دیکشنری‌های StreamPart در نسخه‌ی v2 با ساختاری یکپارچه، یا رویدادهای نسخه‌ی v3 که در مرحله‌ی بتا هستند.

فرض کنید خروجی ایجنت را با تنظیم stream_mode="messages" در پنجره‌ی چت استریم می‌کنید و توکن‌ها از راه می‌رسند. سپس "updates" را هم اضافه می‌کنید تا میزان پیشرفت ابزار را نشان دهید؛ اما حلقه‌ی کدتان از کار می‌افتد، چون حالا هر تکه (chunk) تبدیل به یک تاپل شده است. روند اجرای ایجنت فرقی نکرده؛ این API استریمینگ است که ساختار داده‌های خروجی را تغییر داده است.

در پایان این بخش، می‌توانید API و حالت استریمینگ مناسب را انتخاب کنید و ساختار هر تکه از خروجی یک اجرا را از پیش بدانید. همچنین کار با رویدادهای ابزار در حالت tools را یاد می‌گیرید؛ حالتی که نوعِ داده‌ی رسمی استریمینگ اشاره‌ای به آن نکرده است.

حالت‌های استریمینگ در نسخه‌ی v1

حالت استریم (Stream mode): نامی که به عنوان آرگومان stream_mode ارسال می‌کنید و مشخص می‌کند متد stream در هر گام از گراف چه چیزی برمی‌گرداند.

تکه (Chunk): هر قلم داده‌ای که متد stream تولید می‌کند. ساختار این تکه به حالت استریمینگ، تعداد حالت‌های انتخابی و نسخه‌ی استریمینگ بستگی دارد.

کیت آموزشی، ایجنت بخش 1.3 را در تمام حالت‌ها استریم می‌کند. در حالت updates، هر تکه شامل نام یک گره و کلیدهایی از وضعیت (state) است که آن گره بازنویسی کرده:

نخستین تکه در حالت updates capture/out/21-stream-updates-values.txt
chunk 0:
{
  "model": {
    "messages": [
      {
        "type": "AIMessage",
        "content": "",
        "id": "lc_run--<uuid-1>-0",
        "tool_calls": [
          {
            "name": "add",
…
            "id": "<uuid-2>",

فراخوانی ابزار به نام و id آن کوتاه شده است.

در حالت values، هر تکه کل وضعیت گراف است. اولین تکه فقط شامل ورودی اولیه است؛ بنابراین همین اجرا در حالت values چهار تکه و در حالت updates سه تکه تولید می‌کند.

در حالت messages، هر تکه یک جفت است: تکه‌ای از پیام و متادیتای آن. متادیتا نام گره و شماره‌ی گام را نشان می‌دهد. مدل ChatOllama فراخوانی ابزار (tool call) را یک‌جا در قالب یک تکه فرستاد و سپس تکه‌ای خالی با نشانه‌ی last ارسال کرد. پیام ToolMessage از گره‌ی ابزارها هم خودش در قالب یک تکه برمی‌گردد:

سه تکه نخست در حالت messages capture/out/22-stream-messages.txt
chunk 0:
{
  "message": {
    "type": "AIMessageChunk",
    "content": "",
    "id": "lc_run--<uuid-1>",
…
  "metadata": {
    "langgraph_node": "model",
    "langgraph_step": 1,
…
chunk 1:
{
  "message": {
    "type": "AIMessageChunk",
    "content": "",
    "id": "lc_run--<uuid-1>",
    "chunk_position": "last"
  },
…
chunk 2:
{
  "message": {
    "type": "ToolMessage",
    "content": "5",
…
  "metadata": {
    "langgraph_node": "tools",
    "langgraph_step": 2,

فراخوانی ابزار، متادیتای پاسخ، و محرک‌ها حذف شده‌اند.

پاسخ نهایی، یعنی .2 + 3 = 5، سپس در قالب هشت تکه‌ی متنی مانند 2، + و آمد. به دنبال آن دو تکه‌ی خالی ارسال شدند که دومی نشانه‌ی last داشت. این بخش‌بندی‌ها انتخاب Ollama بوده است؛ مدل دیگر یا نسخه‌ای دیگر ممکن است متن را به شکل متفاوتی خرد کند.

تصویر تکه‌های هر حالت را روی سه بار اجرای گره در همین تک‌اجرا نشان می‌دهد.

تکه‌های یک اجرای ایجنت در هر یک از حالت‌های streamهمان اجرا موجب تولید 3 تکه در حالت updates، 4 تکه در حالت values، 13 تکه در حالت messages و 23 رویداد از stream_events v3 می‌شود.
تکه‌های یک اجرای ایجنت در هر حالت استریم هشت ردیف، هر کدام برای یک استریم از اجرای همان ایجنت، در چهار ستون: ورودی، نود مدل در گام 1، نود ابزارها در گام 2، و نود مدل در گام 3. هر علامت یک تکه خوانده‌شده از فایل ضبط است که بر اساس محتوای آن رنگ‌آمیزی شده: نیلی کل حالت، آلبالویی خروجی مدل، سبز خروجی ابزار، کهربایی وظیفه‌ای که شروع یا پایان می‌یابد. حالت updates دارای 3، values دارای 4، messages دارای 13، tasks دارای 6، debug دارای 6، custom دارای 0، حالت tools دارای 4 تکه روی ایجنت slow_sum، و stream_events v3 دارای 23 رویداد است. استریم v3 هر گام را با یک رویداد values می‌بندد. ورودی مدل، گام 1 ابزارها، گام 2 مدل، گام 3 STREAM N updates 3 values 4 messages 13 tasks 6 debug 6 custom 0 tools 4 رویدادهای v3 23 کل حالت خروجی مدل خروجی ابزار شروع وظیفه پایان وظیفه هر علامت یک تکه است. tasks و debug بدون چک‌پوینتر اجرا شدند. The tools row is the slow_sum agent: started, two deltas, finished. یک رویداد values نسخه v3 هر ستون را می‌بندد.
هر ردیف یک استریم از اجرای همان ایجنت است. هر علامت نشان‌دهنده یک تکه است که روی اجرای نودی که آن را ساخته قرار دارد. رنگ مشخص می‌کند تکه حامل چیست: نیلی کل حالت، آلبالویی خروجی مدل، سبز خروجی ابزار، کهربایی وظیفه‌ای که شروع می‌شود (خط دور) یا پایان می‌یابد. ردیف tools مربوط به ایجنت slow_sum است که دو دلتا ساطع می‌کند. برگرفته از capture/out/21-stream-updates-values.txt، capture/out/22-stream-messages.txt، capture/out/23-stream-tasks-custom-debug.txt، capture/out/25-stream-events-v3.txt و capture/out/26-stream-tools-mode.txt.
حالت ماهیت هر تکه تعداد تکه‌ها برای اجرای جمع
updates {node: what it wrote} 3
values کل وضعیت پس از یک گام 4
messages تکه‌ای از پیام به همراه متادیتای آن 13
tasks شروع یا نتیجه‌ی اجرای یک گره 6
debug یک وظیفه یا نتیجه‌ی آن، به همراه گام و برچسب زمان 6
custom مقداری که گره یا ابزار با نویسنده‌ی استریم (stream writer) خود می‌نویسد 0، چون add چیزی نمی‌نویسد
tools رویداد ابزار: شروع، تغییرات خروجی، یا پایان 4، از ایجنت slow_sum

صفحه‌ی استریمینگ در مستندات LangGraph می‌گوید حالت tasks به چک‌پوینتر (checkpointer) نیاز دارد {{docs oss/python/langgraph/streaming}}. کیت آموزشی حالت‌های tasks و debug را بدون چک‌پوینتر اجرا کرد و از هر کدام شش تکه گرفت. بدون چک‌پوینتر، چهار تکه‌ی حالت debug که کیت چاپ می‌کند از نوع تکه‌های task و task_result بودند. کیت دو تکه‌ی آخر را چاپ نمی‌کند. این راهنما این عدم تطابق را به عنوان تناقض D124 ثبت می‌کند. حالت checkpoints در این کیت وجود ندارد و همان‌طور که در بخش 8.8 آمده، در ویرایش بعدی اضافه خواهد شد.

استفاده‌ی هم‌زمان از چند حالت

اگر فهرستی از حالت‌ها را ارسال کنید، هر تکه در نسخه‌ی v1 به یک تاپل شامل نام حالت و داده‌ی آن تبدیل می‌شود. کدی که برای یک حالت نوشته شده باشد، با اضافه‌شدن حالت دوم از کار می‌افتد:

دو حالت در v1 capture/out/22-stream-messages.txt
chunk 0:
{
  "mode": "messages",
  "chunk": "",
  "node": "model"
}

chunk 1:
{
  "mode": "messages",
  "chunk": "",
  "node": "model"
}

chunk 2:
{
  "mode": "updates",
  "nodes": [
    "model"
  ]
}
…
chunk 15:
{
  "mode": "updates",
  "nodes": [
    "model"
  ]
}

کیت حالت، متن و نود هر تاپل را چاپ کرد. تکه‌های 3 تا 14 حذف شده‌اند.

تکه‌های مربوط به messages در فراخوانی مدل، پیش از تکه‌ی updates همان گره به دست می‌رسند؛ چرا که کار گره باید تمام شود تا LangGraph بفهمد چه مقادیری نوشته شده است.

شیء StreamPart در نسخه‌ی v2

شیء StreamPart: دیکشنری خروجیِ فراخوانی stream(..., version="v2") که سه کلید دارد: type، ns و data. کلید type نام حالت و ns نام زیرگراف را مشخص می‌کند.

نسخه‌ی 1.1 فریم‌ورک LangGraph آرگومان version="v2" را اضافه کرد {{docs oss/python/langgraph/streaming}}. با این کار، چه یک حالت انتخاب کنید و چه چند حالت، هر تکه همیشه همین سه کلید یکسان را دارد:

یک StreamPart در v2 capture/out/24-stream-v2.txt
part 2:
{
  "type": "updates",
  "ns": [],
  "data": {
    "model": {
…
  "keys": [
    "data",
    "ns",
    "type"
  ]
}

به‌روزرسانی حالت حذف شده است. کیت لیست کلیدها را اضافه کرد.

متد invoke(..., version="v2") خروجی را در قالب شیء GraphOutput با دو ویژگی value و interrupts برمی‌گرداند. دسترسی به سبک دیکشنری قدیمی همچنان کار می‌کند، اما هشدار می‌دهد:

دسترسی دیکشنری در GraphOutput capture/out/24-stream-v2.txt
result['messages'] has 4 messages

warning LangGraphDeprecatedSinceV11: Accessing GraphOutput via `result[key]` is deprecated. Use `result.value` to access the output value directly, or `result.interrupts` for interrupts. Deprecated in LangGraph V1.1 to be removed in V3.0.

در کدهای جدید از نسخه‌ی v2 استفاده کنید. حلقه‌ای که بر اساس part["type"] تصمیم می‌گیرد، با اضافه‌شدن یک حالت جدید یا یک زیرگراف بدون مشکل به کارش ادامه می‌دهد. تصویر این سه ساختار را کنار هم نشان می‌دهد.

همان نتیجه ابزار در v1، v2 و v3نسخه v1 ساختار خود را با تعداد حالت‌ها تغییر می‌دهد، v2 همیشه type، ns و data را برمی‌گرداند، و v3 متد و شماره توالی را اضافه می‌کند.
همان نتیجه ابزار در v1، v2 و v3 سه ستون، هر کدام برای یک API استریم، که هر یک ToolMessage 5 از ابزار add را حمل می‌کنند. نسخه v1 با دو حالت یک تاپل از mode و data تولید می‌کند، و data همان ToolMessage به همراه متادیتای آن است. نسخه v2 یک دیکشنری StreamPart با type، ns و data تولید می‌کند. نسخه v3 یک فریم رویداد با type، method، params و seq برمی‌گرداند که در آن method برابر tools و داده همان رویداد tool-finished با خروجی ToolMessage است. V1، دو حالت یک تاپل (mode, data) تغییر شکل ساختار با حالت‌ها data (ToolMessage, metadata) langgraph_node: tools تکه 3 از messages V2، هر حالتی یک دیکشنری StreamPart type، ns، data type: messages data message: ToolMessage metadata: node tools بخش 3 رویداد V3 یک فریم رویداد type, method, params, seq method: tools params.data event: tool-finished output: ToolMessage seq 9 All three carry the same ToolMessage, with content 5 and the tool_call_id of the call.
هر ستون یک API استریم است. ساختار بیرونی در بالا و سپس نتیجه ابزاری که حامل آن است را بخوانید. برگرفته از capture/out/22-stream-messages.txt، capture/out/24-stream-v2.txt و capture/out/25-stream-events-v3.events.json.

رویدادهای استریمینگ در نسخه‌ی v3 (stream_events)

شیء GraphRunStream: شیئی که از خروجی stream_events(..., version="v3") دریافت می‌کنید. می‌توانید روی رویدادهای خام آن پیمایش کنید یا نماهای نوع‌بندی‌شده‌ی آن مثل messages، values و output را بخوانید.

مستندات استریمینگ LangChain برای برنامه‌های جدید، استریمینگ مبتنی بر رویداد را پیشنهاد می‌کند {{docs oss/python/langchain/streaming}}. در نسخه‌ی قفل‌شده‌ی فعلی، این قابلیت در وضعیت بتا قرار دارد و فراخوانی آن با هشدار همراه است:

stream_events v3 و اعضای آن capture/out/25-stream-events-v3.txt
warning LangChainBetaWarning: The v3 streaming protocol on Pregel is experimental.

public members of GraphRunStream:
[
  "abort",
…
  "messages",
  "output",
…
  "tool_calls",
  "values"
]

23 events

لیست اعضا به پنج مورد کوتاه شده است.

هر رویداد یک متد (method)، یک شیء پارامتر (params) شامل فضای نام و برچسب زمان، و یک شماره توالی (seq) دارد. فراخوانی ابزار در طول اجرا شامل دو رویداد با متد tools است:

یک رویداد v3 capture/out/25-stream-events-v3.events.json
  {
    "type": "event",
    "method": "tools",
    "params": {
      "namespace": [],
      "timestamp": "<epoch-ms>",
      "data": {
        "event": "tool-started",
        "tool_call_id": "<uuid-2>",
        "tool_name": "add",
        "input": {
          "a": 2,
          "b": 3
        }
      }
    },
    "seq": 8
  },

یک بار فراخوانی مدل، مجموعه‌ای از رویدادهای messages است: message-start، content-block-start، دلتاها، content-block-finish و message-finish. فراخوانی اول دارای یک رویداد content-block-delta از نوع tool-call-delta بود که کل داده‌های فراخوانی ابزار را حمل می‌کرد. فراخوانی دوم هشت رویداد از نوع text-delta داشت؛ یکی برای هر بخش از متن. بعد از هر گام هم یک رویداد values می‌آید. این یعنی 23 رویداد برای کل این اجرا، در مقایسه با 13 تکه در حالت messages.

سه تفاوت با نسخه‌های v1 و v2 وجود دارد که هنگام پورت‌کردن کد قدیمی باعث خطا می‌شوند:

  • فراخوانی stream_events(version="v3") آرگومان stream_mode را قبول نمی‌کند و خطای TypeError می‌دهد؛ چون نسخه‌ی v3 مجموعه‌ی حالت‌های خودش را می‌سازد.
  • حالت همگام stream_events(version="v2") خطای NotImplementedError می‌دهد. برای رویدادهای v1 و v2 باید از astream_events استفاده کنید.
  • محتوای پیام‌های هوش مصنوعی (AI messages) در run.output به صورت فهرستی از بلوک‌های استاندارد ذخیره می‌شود که مقدار output_version در بخش response_metadata آن‌ها v1 است. در نسخه‌های v1 و v2 محتوای همین پیام‌ها رشته متنی بود.
آخرین پیامِ run.output capture/out/25-stream-events-v3.txt
  {
    "type": "AIMessage",
    "content": [
      {
        "type": "text",
        "text": "2 + 3 = 5.",
        "index": 0
      }
    ],
    "id": "lc_run--<uuid-5>",
    "response_metadata": {
…
      "model_provider": "ollama",
      "output_version": "v1"
    },

متن چنین پیامی را با message.text بخوانید که طبق آنچه در بخش 3.3 آمده، برای هر دو ساختار کار می‌کند.

حالت ابزارها (tools mode)

رویداد ابزار (Tool event): تکه‌ای در حالت استریم tools. مقادیر آن شامل tool-started، tool-output-delta یا tool-finished است و tool_call_id را هم به همراه دارد.

نوع داده‌ی StreamMode نام هفت حالت را فهرست می‌کند و داک‌استرینگ stream هم همین هفت مورد را آورده است {{code libs/langgraph/langgraph/types.py}}. حلقه‌ی اجرا حالت tools را هم می‌پذیرد {{code libs/langgraph/langgraph/pregel/main.py}}. با این حال، صفحه‌ی استریمینگ مستندات LangGraph اسمی از آن نبرده است {{docs oss/python/langgraph/streaming}}. این راهنما این کاستی را به عنوان تناقض D4 ثبت می‌کند. یک ابزار، دلتای خروجی را با runtime.emit_output_delta ارسال می‌کند:

ابزاری که پیشرفت را گزارش می‌دهد capture/s_stream.py
@tool
def slow_sum(a: int, b: int, runtime: ToolRuntime) -> int:
    """Add two integers and report progress."""
    runtime.emit_output_delta({"partial": a})
    runtime.emit_output_delta({"partial": a + b})
    return a + b
حالت tools capture/out/26-stream-tools-mode.txt
chunk 0:
{
  "event": "tool-started",
  "tool_call_id": "<uuid-1>",
  "tool_name": "slow_sum",
  "input": {
    "a": 2,
    "b": 3
  }
}

chunk 1:
{
  "event": "tool-output-delta",
  "tool_call_id": "<uuid-1>",
  "delta": {
    "partial": 2
  }
}
…
chunk 3:
{
  "event": "tool-finished",
  "tool_call_id": "<uuid-1>",

رویداد خاتمه‌یافته به خطوط نخست آن خلاصه شده است.

در استریمی که بدون حالت tools اجرا شود، متد emit_output_delta عملاً کاری انجام نمی‌دهد. کیت آموزشی همین ایجنت را در حالت updates استریم کرد و فقط سه تکه‌ی مربوط به گره‌ها را تحویل گرفت. در نسخه‌ی v2، رویداد ابزار در قالب یک شیء StreamPart با فیلد type برابر با tools ظاهر می‌شود.

تاخیر تحویل در هر کدام از APIهای استریمینگ

تاخیر تحویل (Delivery delay): مدت‌زمانی که بر اساس یک ساعت مشخص، از لحظه‌ی ارسال یک توکن توسط سرور مدل تا لحظه‌ی دریافت آن در حلقه‌ی کد شما طول می‌کشد.

ما تاخیر تحویل را روی یک دستگاه مک (Apple M1 Max با 10 هسته و 64 GiB حافظه) برای نه روش مختلف استریمینگ یک ایجنت اندازه گرفتیم. مدل Qwen3 4B روی Ollama هر پاسخ را از طریق یک پراکسی روی 127.0.0.1 استریم می‌کرد؛ این پراکسی روی هر خطی که عبور می‌داد برچسب زمان می‌زد. هر API تعداد 24 بار برای یک پاسخ متنی 80 توکنی با فاصله‌ی تقریبی 32 میلی‌ثانیه‌ای میان توکن‌ها اجرا شد. همچنین 24 بار برای یک فراخوانی ابزار که به دنبال آن یک پاسخ تک‌جمله‌ای می‌آمد، به اجرا درآمد. هم‌زمان کارهای دیگری هم روی سیستم در حال اجرا بود و میانگین بار کاری (load average) بین 1.4 تا 6.2 متغیر بود.

هشت مورد از این نه API، توکن‌ها را تک‌به‌تک و با همان فواصل زمانی ارسالیِ سرور تحویل دادند. میانه‌ی تاخیر توکن اول برای یک پاسخ متنی بین 1.28 تا 3.46 میلی‌ثانیه بود و بدترین مقدار صدک 95ام (p95) به 7.63 میلی‌ثانیه رسید. درخواست ارسالی، 3.8 تا 10.5 میلی‌ثانیه پس از فراخوانی به پراکسی رسید. ادعایی در وب وجود دارد مبنی بر اینکه استریمینگ در LangGraph حدود 100 تا 300 میلی‌ثانیه به زمان دریافت اولین توکن اضافه می‌کند. این ادعا در اینجا رد شد و این راهنما آن را به عنوان تناقض D211 ثبت می‌کند.

لایه‌های میانی بخشی از زمان پردازنده (CPU) را مصرف می‌کنند، اما تاخیر محسوسی اضافه نمی‌کنند. زمان‌های مصرفی پردازنده که در ادامه آمده صرفاً جنبه‌ی مقایسه‌ای دارند و هزینه‌ی مطلق نیستند، چرا که پردازش‌های دیگری هم‌زمان روی سیستم در جریان بوده است. یک اجرای 80 توکنی در یک حلقه‌ی ساده‌ی openai معادل 63.4 میلی‌ثانیه و در فراخوانی ChatOpenAI.stream معادل 80.3 میلی‌ثانیه از پردازنده زمان برد. همین کار از طریق ایجنت بین 102.3 تا 140.4 میلی‌ثانیه طول کشید. اجرایی شامل فراخوانی ابزار و پاسخی کوتاه، در حلقه‌ی ساده 20.1 میلی‌ثانیه و از طریق ایجنت بین 41.0 تا 49.0 میلی‌ثانیه زمان مصرف کرد.

فراخوانی ابزار فقط به اندازه‌ی رفت‌وبرگشت فراخوانی خودِ ابزار، متن نهایی را به تاخیر انداخت. Ollama هر فراخوانی ابزار را در قالب یک تکه ارسال کرد و این تکه 1.9 تا 9.4 میلی‌ثانیه بعد از ارسال به حلقه‌ی کد رسید. در درخواست دوم، اولین توکن 1.74 تا 3.69 میلی‌ثانیه بعد از ارسال وارد حلقه شد. ردیف صورتی‌رنگ در تصویر تنها استثنای این روند است.

تأخیر تحویل نخستین توکن در هر اجرا، بر حسب API استریمهشت مورد از 9 API استریم، نخستین توکن را حدود 2 میلی‌ثانیه پس از ارسال تحویل می‌دهند، و حلقه‌ای که ابتدا استدلال را می‌خواند 2663 میلی‌ثانیه منتظر می‌ماند.
تأخیر تحویل نخستین توکن در هر اجرا، بر حسب API استریم یک نمودار نقطه‌ای در مقیاس لگاریتمی از زمان بین ارسال نخستین توکن Qwen3 4B توسط پروکسی و مشاهده آن توسط مصرف‌کننده، روی مک، 24 اجرا به ازای هر API. میانه‌ها: حالت openai معمولی 1.28 میلی‌ثانیه، حالت ChatOpenAI برابر 1.74 میلی‌ثانیه، حالت messages برابر 1.69 میلی‌ثانیه، حلقه مستندات v3 برابر 1.55 میلی‌ثانیه، و مصرف‌کننده ناهمگام v3 که اول استدلال را می‌خواند 2662.92 میلی‌ثانیه. 0.1 1 10 100 1000 10000 میلی‌ثانیه از ارسال به مصرف‌کننده، مقیاس لگاریتمی API استریم میانه حلقه معمولی openai 1.28 ms ChatOpenAI.stream 1.74 ms حالت messages 1.69 ms messages و updates 2.21 ms astream_events v2 1.85 ms v3، حلقه مستندات 1.55 ms v3، رویدادهای خام 2.05 ms v3 ناهمگام، حلقه متن 3.46 ms v3 ناهمگام، اول استدلال 2663 ms هر نقطه یک اجرای 80 توکنی از Qwen3 4B است، 24 اجرا برای هر API. خط تیره بلند میانه است. ردیف سرخ‌رنگ پیش از message.text روی message.reasoning حلقه می‌زند، بنابراین متن منتظر پایان می‌ماند.
هر ردیف یک API استریم است و هر نقطه نشان‌دهنده یک اجرای 80 توکنی از Qwen3 4B است (24 بار برای هر API) در مقیاس لگاریتمی. خط تیره نشانه میانه است که در سمت راست نیز درج شده است. برگرفته از capture/lab/summary/streaming-mac-real.json.

تصویرهای یک پیام در نسخه‌ی v3

تصویر (Projection): نمایی نوع‌بندی‌شده از یک پیام نسخه‌ی v3، مانند message.text، message.reasoning یا message.tool_calls که دلتاهای اختصاصی خودش را ارائه می‌دهد.

گزارش ایشوی langchain#38484 نشان می‌دهد مصرف‌کننده‌ی داده‌ها در نسخه‌ی v3 پاسخ نهایی را یک‌باره و به صورت ناگهانی دریافت می‌کند {{issue langchain#38484}}. اجراهای ما هم این موضوع را بازتولید کردند. ترتیبی که حلقه برای خواندن تصویرها پیش می‌گیرد جرقه‌ی این مشکل را می‌زند و ریشه‌ی آن در کد خود تصویرهاست. ردیف صورتی‌رنگ در تصویر درست مانند کد ایشو، ابتدا message.reasoning و سپس message.text را می‌خواند:

حلقه‌ای که استدلال را پیش از متن می‌خواند capture/lab/T04-streaming-mac-real/t04_run.py
    async def consume_messages(ms, label):
        async for message in ms:
            async for d in message.reasoning:
                pass
            async for d in message.text:
                rec.on_text(d, label)

مدل Qwen3 4B Instruct هیچ بخش استدلالی نمی‌فرستد، اما حلقه‌ی استدلال همچنان فقط زمانی تمام می‌شود که کل پیام به پایان برسد. در نتیجه هر 80 توکن متنی ناگهان با هم می‌رسند؛ آن هم با میانه‌ی تاخیری معادل 2,663 میلی‌ثانیه‌ای.

چرا تصویر دوم منتظر می‌ماند؟

استریم نسخه‌ی v3 هیچ رشته‌ی پس‌زمینه‌ای اجرا نمی‌کند؛ این خواننده است که داده‌ها را پول (pull) می‌کند. وقتی تصویری مثل message.text دلتای جدیدی در لیستش نداشته باشد، ایتریتور آن گراف را تا زمان دریافت رویداد بعدی جلو می‌برد {{code libs/core/langchain_core/language_models/chat_model_stream.py:247-269}} {{code libs/langgraph/langgraph/stream/run_stream.py:136-160}}. هر رویدادی که پیش کشیده شود به تمام تصویرهای آن پیام می‌رسد. دلتای متنی وارد لیست message.text می‌شود، حتی در حالی که هنوز هیچ کدی آن لیست را نمی‌خواند.

ایتریتور یک تصویر فقط وقتی متوقف می‌شود که برچسب اتمام روی آن تصویر بخورد. هر سه تصویر یک پیام در یک نقطه پایان‌یافته علامت می‌خورند: زمانی که کل پیام به پایان برسد {{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}}.

بنابراین، حلقه‌ی استدلال پیش از رسیدن آخرین توکن متنی امکان خروج ندارد. این حلقه حین انتظار، تک‌تک دلتاهای متنی را به درون لیست message.text می‌کشد. وقتی پیام تمام می‌شود، حلقه‌ی متن تمام این توکن‌ها را یک‌جا در آنجا می‌بیند. در بخش 2.5 این مسیر را درون کد دنبال می‌کنیم.

ما علت مسئله را روی سرور مهمان x86 با مدل Qwen3 8B و در وضعیت استدلال روشن، از طریق create_agent سنجیدیم. سه حلقه‌ی همگام در نسخه‌ی v3 هر کدام 5 بار به صورت درهم‌تنیده اجرا شدند. هر پاسخ شامل 211 دلتای استدلالی و سپس 60 دلتای متنی بود. در هر 5 اجرا، حلقه‌ای که اول استدلال را می‌خواند، هر 60 دلتای متنی را ظرف کمتر از 0.1 میلی‌ثانیه تحویل گرفت؛ در حالی که مدل کل پاسخ را در بازه‌ای بین 8.64 تا 8.89 ثانیه ارسال کرده بود.

این آزمایش روی یک ماشین زیر بار کاری انجام شده، بنابراین اعداد را به عنوان مرتبه‌ی بزرگی در نظر بگیرید. ردیف‌های مربوط به سیستم مک در ادامه، این تاخیر انباشتگی را بین 4.0 تا 8.5 ثانیه نشان می‌دهند.

حلقه‌ای که فقط روی message.text می‌چرخید، هر دلتا را با میانه‌ی تاخیر 0.7 میلی‌ثانیه و حداکثر 4.9 میلی‌ثانیه گرفت. حلقه‌ی روی رویدادهای خام هر پیام هم میانه‌ی تاخیر 0.7 میلی‌ثانیه‌ای و حداکثر 0.9 میلی‌ثانیه‌ای ثبت کرد.

ما همین دریافت ناگهانی را روی سیستم مک با مدل Qwen3 8B و قابلیت استدلال روشن، با پنج حلقه‌ی ناهمگام نسخه‌ی v3 و در قالب 5 اجرا برای هر کدام اندازه گرفتیم. هر پاسخ شامل 763 دلتای استدلالی و 62 دلتای متنی بود. حلقه‌ای با ترتیبی که در مستندات آمده و همچنین حلقه‌ی مبتنی بر asyncio.gather در گزارش ایشو، همگی هر 62 دلتای متنی را ظرف کمتر از 0.2 میلی‌ثانیه دریافت کردند. این فوران ناگهانی در هر 10 اجرا، بین 4.0 تا 8.5 ثانیه پس از ارسال اولین دلتای متنی به دست رسید. در مقابل، حلقه‌ای که فقط روی message.text می‌چرخید و حلقه‌ای که رویدادهای خام را می‌خواند، هر دلتای متنی را حداکثر 15.3 میلی‌ثانیه پس از ارسال دریافت کردند. تصویر یک اجرا از مدل Qwen3 4B را روی محور زمان برای دو حالت از این حلقه‌ها نمایش می‌دهد.

زمان ارسال و مشاهده هر توکن، در دو حلقه ناهمگام v3یک حلقه v3 که ابتدا استدلال را می‌خواند تمام 80 توکن را یکجا در 4052 میلی‌ثانیه می‌بیند، در حالی که حلقه مبتنی بر متن هر توکن را بلافاصله پس از ارسال مشاهده می‌کند.
زمان ارسال و مشاهده هر توکن، در دو مصرف‌کننده ناهمگام v3 خط زمانی یک اجرا از هر مصرف‌کننده روی مک، با 80 توکن از Qwen3 4B. در حلقه متن، هر توکن ظرف چند میلی‌ثانیه پس از ارسال مشاهده می‌شود، از 558.2 تا 3978.5 میلی‌ثانیه پس از شروع اجرا. در حلقه‌ای که ابتدا استدلال را می‌خواند، مدل از 413.5 تا 4016.9 میلی‌ثانیه ارسال می‌کند، و مصرف‌کننده تمام 80 توکن را در 4052.2 تا 4052.5 میلی‌ثانیه می‌بیند. 0 1000 2000 3000 4000 میلی‌ثانیه از زمان شروع اجرا فقط حلقه متن ارسال مدل مشاهده مصرف‌کننده حلقه استدلال، سپس متن ارسال مدل مشاهده مصرف‌کننده همه 80 تا در 4052 میلی‌ثانیه هر خط نشان‌دهنده یکی از 80 توکن در یک اجراست. خطوط زیتونی ارسال‌ها توسط Qwen3 4B روی Ollama هستند. سایر خطوط لحظاتی هستند که مصرف‌کننده توکن را دید. حلقه پایینی متن را در انتها می‌بیند.
جفت بالایی یک حلقه فقط روی message.text است و جفت پایینی ابتدا message.reasoning را می‌خواند. علامت‌های زیتونی ارسال‌ها توسط Qwen3 4B روی Ollama هستند و سایر علامت‌ها لحظاتی را نشان می‌دهند که حلقه توکن را دیده است. برگرفته از capture/lab/summary/streaming-mac-real.json.

این ترتیب خواندن روی تصویرهای دیگر هم تاثیر می‌گذارد. در فاز ابزار، حلقه‌ی ارائه‌شده در مستندات ابتدا message.text و سپس message.tool_calls را می‌خواند. مدل Ollama فراخوانی ابزار را در قالب یک تکه ارسال می‌کند؛ بنابراین در مدل Qwen3 4B، حلقه‌ی مستندات این فراخوانی را در میانه‌ی زمانی 7.9 میلی‌ثانیه بعد از ارسال دید. حالت ناهمگام آن بعد از 9.4 میلی‌ثانیه و حلقه‌ی ساده بعد از 1.9 میلی‌ثانیه به آن رسیدند.

ما این ترتیب را با یک مدل استدلالی واقعی روی مک سنجیدیم: استفاده از ChatOllama با مدل Qwen3 4B و تنظیم reasoning=True با 3 بار اجرا به ازای هر ترتیب. وقتی استدلال در اولویت خواندن بود، 484 دلتای استدلالی به شکل زنده استریم شدند. سپس تمام 103 دلتای متنی در یک لحظه و با تاخیری بین 3,424 تا 4,036 میلی‌ثانیه پس از آخرین دلتای استدلالی رسیدند. وقتی اولویت با متن بود، متن استریم شد و کل استدلال در انتها به صورت یک‌جا تحویل داده شد. مدل Qwen3 8B هم در 5 اجرا همین رفتار را نشان داد. با اولویت متن، 763 دلتای استدلالی آن در پایان ظرف کمتر از 2 میلی‌ثانیه، ولی با تاخیری بین 57 تا 112 ثانیه رسیدند.

مثال‌های بخش استدلال در مستندات استریمینگ LangChain ابتدا message.reasoning و سپس message.text را می‌خوانند {{docs oss/python/langchain/streaming}} {{docs oss/python/langchain/event-streaming}}. هنگام کار با مدلی استدلالی، آن مثال‌ها پاسخ نهایی را تازه پس از اتمام کل پیام نشان می‌دهند. صفحه‌ی LangGraph توصیه می‌کند اگر همه‌ی دلتاها را به ترتیب رسیدن می‌خواهید، رویدادهای خام را بخوانید {{docs oss/python/langgraph/event-streaming}}. حلقه‌ی رویدادهای خام در آزمایشگاه ما همین کار را کرد و تمام توکن‌های تصویر را استریم کرد:

یک حلقه روی رویدادهای خام v3 capture/lab/T04-streaming-mac-real/t04_run.py
def run_v3_raw(ctx, model, scenario, tag, rec):
    run = ctx["agent"].stream_events(inp(scenario, tag), version="v3")
    for ev in run:
        if ev.get("method") != "messages":
            continue
        data = ev["params"]["data"]
        e = data[0] if isinstance(data, (list, tuple)) else data
        if e.get("event") != "content-block-delta":
            continue
        d = e.get("delta", {})
        if d.get("type") == "tool-call-delta":
            rec.on_tool(1, "raw")
        elif d.get("type") == "text-delta":
            rec.on_text(d.get("text", ""), "raw")

اولین دلتای فراخوانی ابزار در این حالت 4.4 میلی‌ثانیه پس از ارسال و دلتای متنی آن 2.4 میلی‌ثانیه پس از ارسال رسید.

حلقه‌ی مصرف‌کننده‌ای که باید بنویسید

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

مصرف‌کننده‌ای که استدلال و متن را به محض ورود نشان می‌دهد capture/lab/internals/05-streaming/run.py
    stream = agent.stream_events({"messages": [{"role": "user", "content": PROMPT_38484}]}, version="v3")
    for message in stream.messages:
…
            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")))

branchهای دو حلقه دیگر حذف شده‌اند.

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

در پول‌ریکوئست بسته‌شده‌ی مربوط به این ایشو (#38533)، تنظیمات پیکربندی اجرا به فراخوانی model_.invoke در متد create_agent فرستاده شده بود {{code libs/langchain_v1/langchain/agents/factory.py:1509}}. آن تغییر دست به کدهای بخش تصویر نمی‌زند. در همان ایجنت، حلقه‌های مبتنی بر متن و رویداد خام از قبل تمام دلتاها را زنده می‌گرفتند. بنابراین منتظر برطرف‌شدن مشکل در متد create_agent نمانید.

استریم فراخوانی ابزار توسط یک مدل واقعی

مدل ChatOllama هر فراخوانی ابزار را کامل و همراه با شناسه‌اش درون یک تکه می‌فرستد. ورودی tool_call_chunks در آن، کل آرگومان‌ها را در قالب یک رشته و فیلد index را برابر با null دارد. تکه‌ای خالی با نشانه‌ی chunk_position="last" پاسخ را می‌بندد:

تکه‌ای که فراخوانی ابزار را حمل می‌کند capture/out/27-stream-tool-call-chunks.txt
13 chunks, 1 with tool_call_chunks
…
      "tool_call_chunks": [
        {
          "name": "add",
          "args": "{\"a\": 2, \"b\": 3}",
          "id": "<uuid-2>",
          "index": null,
          "type": "tool_call_chunk"
        }
      ],

میزان مصرف (usage) و متادیتا حذف شده‌اند.

کیت آموزشی از مدل خواست پیش از فراخوانی، جمله‌ی .Let me add را هم بنویسد. ابتدا چهار تکه‌ی متنی آمدند، بعد تکه‌ی حاوی فراخوانی ابزار، و در نهایت تکه‌ی خالی با نشانه‌ی last. بنابراین فراخوانی هیچ‌وقت سوار بر تکه‌ی نشانه‌گذاری‌شده با last ارسال نمی‌شود و نسخه‌ی v3 برای آن یک رویداد tool-call-delta تحویل گرفت. اگر مدلی واقعی یا شبیه‌سازی‌شده (fake) آرگومان‌ها را تکه‌تکه کند و روی تکه‌ای نشانه‌دار به پایان برسد، آخرین بخش داده در نسخه‌ی v3 از دست می‌رود؛ همان‌طور که در بخش 3.4 بررسی شده است.

منابع: capture/s_stream.py، capture/out/21-stream-updates-values.txt، capture/out/22-stream-messages.txt، capture/out/23-stream-tasks-custom-debug.txt، capture/out/24-stream-v2.txt، capture/out/25-stream-events-v3.txt، capture/out/25-stream-events-v3.events.json، capture/out/26-stream-tools-mode.txt، capture/out/27-stream-tool-call-chunks.txt؛ فایل‌های libs/langgraph/langgraph/types.py، libs/langgraph/langgraph/pregel/main.py و libs/langgraph/langgraph/pregel/_tools.py در langgraph 1.2.22؛ فایل libs/partners/ollama/langchain_ollama/chat_models.py در langchain-ollama 1.1.0؛ capture/lab/summary/streaming-mac-real.json، capture/lab/T04-streaming-mac-real/real_text-per-run.jsonl، capture/lab/T04-streaming-mac-real/real_tool-per-run.jsonl، capture/lab/T04-streaming-mac-real/03-iso38484-qwen3-8b.jsonl، capture/lab/T04-streaming-mac-real/real_text-runs-excerpt.jsonl، capture/lab/T04-streaming-mac-real/real_text-server-excerpt.jsonl، capture/lab/T04-streaming-mac-real/t04_run.py، capture/lab/T04-streaming-mac-real/t04_stream_server.py، capture/lab/T04-streaming-mac-real/t04_iso_real.py؛ capture/lab/summary/streaming-mac.json، capture/lab/T04-streaming-mac/reasoning-ollama-runs.jsonl؛ capture/lab/internals/05-streaming/run.py، capture/lab/internals/05-streaming/trace.txt، capture/lab/internals/05-streaming/v3_38484.json؛ فایل‌های libs/core/langchain_core/messages/ai.py، libs/core/langchain_core/language_models/_compat_bridge.py و libs/core/langchain_core/language_models/chat_model_stream.py در langchain-core 1.8.0؛ فایل libs/langgraph/langgraph/stream/run_stream.py در langgraph 1.2.22؛ فایل libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0؛ ایشوی langchain#38484 و pull request #38533؛ docs.langchain.com در docs commit 04d4d4a (بخش‌های oss/python/langgraph/streaming، oss/python/langchain/streaming، oss/python/langchain/event-streaming و oss/python/langgraph/event-streaming).