مرجع R.3

حالت‌های استریم و انواع رویدادها

Stream modes and event types

فهرست مطالب
  1. حالت‌های استریم
  2. ساختار چانک در نسخه v1
  3. ساختار StreamPart در نسخه v2
  4. رویدادهای ابزار
  5. رویدادهای stream_events در نسخه v3

اجرای یک گراف در LangGraph با هشت حالت، در دو نسخه‌ی چانک و از طریق یک پروتکل رویداد بتا (beta) استریم می‌شود که تک‌تک آن‌ها در langgraph نسخه 1.2.22 ساختار مشخص و ثابتی دارند.

تمام ردیف‌های این صفحه مستقیماً از کدهای langgraph نسخه 1.2.22 یا از لاگ‌های ضبط‌شده‌ی یک اجرای واقعی ایجنت استخراج شده‌اند. در این اجرا، ایجنت دو فراخوانی مدل و یک فراخوانی ابزار انجام می‌دهد. در بخش 5.1 توضیح داده‌ایم که چه زمانی باید از هر حالت استفاده کنید.

حالت‌های استریم

تایپ StreamMode هفت حالت را فهرست می‌کند {{code libs/langgraph/langgraph/types.py:132-134}}. حلقه‌ی اجرا حالت tools را هم می‌پذیرد، هرچند این مورد در تعریف تایپ نیامده است {{code libs/langgraph/langgraph/pregel/main.py:2949-2950}}. در جدول ثبت مغایرت‌ها در صفحه‌ی منابع، این مورد با شناسه D4 ثبت شده است.

حالت ساختار یک چانک در v1 تعداد چانک‌ها در اجرای ما فایل لاگ
values کل وضعیت (state) پس از هر مرحله 4 21-stream-updates-values.txt
updates دیکشنری از نام گره به تغییراتی که گره برگردانده 3 21-stream-updates-values.txt
messages یک تاپل شامل چانک پیام و یک دیکشنری متادیتا 13 22-stream-messages.txt
custom مقداری که گره یا ابزار به stream_writer فرستاده 0 (چون هیچ ابزاری مقداری نفرستاد) 23-stream-tasks-custom-debug.txt
tasks شروع وظیفه با id، name، input و triggers، یا نتیجه‌ی وظیفه با error و result 6 23-stream-tasks-custom-debug.txt
debug دیکشنری شامل step، timestamp، فیلد type با مقادیر checkpoint، task یا task_result، و payload 6 (بدون چک‌پوینتر) 23-stream-tasks-custom-debug.txt
checkpoints چک‌پوینت به همان شکل خروجی get_state در پکیج وجود ندارد ندارد
tools رویداد مربوط به ابزار، طبق جدول زیر 4 (روی ایجنت slow_sum) 26-stream-tools-mode.txt

گرافی که با create_agent ساخته می‌شود، اگر حالتی برایش تعیین نکنید، به‌طور خودکار updates را استریم می‌کند {{code libs/langgraph/langgraph/graph/state.py:1357}}. یک شیء معمولی Pregel حالت values را استریم می‌کند {{code libs/langgraph/langgraph/pregel/main.py:715}}. درون یک گراف دیگر هم اگر گرافی بدون تعیین حالت اجرا شود، values را استریم می‌کند {{code libs/langgraph/langgraph/pregel/main.py:2850-2857}}.

متادیتای هر چانک در حالت messages کلیدهایی مثل langgraph_node، langgraph_step، langgraph_triggers، ls_provider و ls_model_type را در خود دارد. با خواندن langgraph_node می‌توانید مدلِ خودِ ایجنت را از مدلی که درون یک ابزار فراخوانی شده تشخیص دهید.

ساختار چانک در نسخه v1

نوع فراخوانی خروجی stream
یک حالت تکی خودِ چانک
فهرستی از حالت‌ها یک تاپل به‌صورت (mode, chunk)
یک حالت همراه با subgraphs=True یک تاپل به‌صورت (namespace, chunk)
فهرستی از حالت‌ها همراه با subgraphs=True یک تاپل به‌صورت (namespace, mode, chunk)

ساختار StreamPart در نسخه v2

وقتی از version="v2" استفاده می‌کنید، فارغ از این‌که چه حالت‌هایی خواسته باشید، هر چانک در قالب یک TypedDict با کلیدهای type، ns و data دریافت می‌شود. مقدار v2 از نسخه‌ی 1.1.0 به langgraph اضافه شد.

تایپ مقدار type خط در types.py
ValuesStreamPart values 274
UpdatesStreamPart updates 286
MessagesStreamPart messages 298
CustomStreamPart custom 311
CheckpointStreamPart checkpoints 322
TasksStreamPart tasks 330
DebugStreamPart debug 345

{{code libs/langgraph/langgraph/types.py:274-379}}

فراخوانی invoke(..., version="v2") خروجی را در قالب شیء GraphOutput با دو فیلد value و interrupts برمی‌گرداند {{code libs/langgraph/langgraph/types.py:381-421}}. دسترسی به آن مثل یک دیکشنری همچنان کار می‌کند، اما همان‌طور که لاگ 24-stream-v2.txt نشان می‌دهد، اخطار LangGraphDeprecatedSinceV11 صادر می‌شود.

رویدادهای ابزار

حالت tools برای هر رویدادِ ابزار یک دیکشنری خروجی می‌دهد. کلید event نوع آن را مشخص می‌کند:

event سایر کلیدها در اجرای ما
tool-started tool_call_id، tool_name، input 1
tool-output-delta tool_call_id، delta 2 (از runtime.emit_output_delta)
tool-finished tool_call_id، output، شیء ToolMessage 1
tool-error طبق پروتکل تعریف می‌شود 0

{{code libs/prebuilt/langgraph/prebuilt/tool_node.py:1766}} {{code langchain_protocol/protocol.py:518-534}}

رویدادهای stream_events در نسخه v3

متد stream_events به‌طور پیش‌فرض از version="v2" استفاده می‌کند و باید صراحتاً v3 را مشخص کنید {{code libs/langgraph/langgraph/pregel/main.py:3751-3758}}. نسخه v3 آزمایشی (beta) است و هشدار LangChainBetaWarning: The v3 streaming protocol on Pregel is experimental. را صادر می‌کند {{code libs/langgraph/langgraph/pregel/main.py:3617}}. این متد یک شیء GraphRunStream برمی‌گرداند؛ طبق لاگ 25-stream-events-v3.txt، اعضای عمومی آن عبارتند از: abort، extensions، interleave، interrupted، interrupts، lifecycle، messages، output، subagents، subgraphs، tool_calls و values.

قاعده محل در کد
فرستادن stream_mode و subgraphs در نسخه v3 خطای TypeError می‌دهد. {{code libs/langgraph/langgraph/pregel/main.py:395-400}}
اجرای همگام (sync) متد stream_events در نسخه‌های v1 یا v2 خطای NotImplementedError می‌دهد. برای این نسخه‌ها از astream_events استفاده کنید. {{code libs/core/langchain_core/runnables/base.py:1818}}
ساختار رویدادها در این بسته آموزشی روی نسخه‌ی 0.0.21 از langchain-protocol فیکس شده است. capture/requirements.txt

هر رویداد خام در قالب یک فریم است؛ با type از نوع event، یک method، بخش params (شامل namespace، timestamp و data) و یک شماره‌ی توالی (seq). اجرای نمونه‌ی ما 23 فریم تولید کرد: 4 فریم values، 17 فریم messages و 2 فریم tools.

method محتوای data خط در protocol.py
lifecycle وضعیت گراف یا ساب‌ایجنت: started، running، completed، failed یا interrupted 269، 462
messages رویداد پیام و متادیتای آن 273
tools رویداد ابزار 277
input.requested، input.answered یک وقفه (interrupt) و پاسخ آن 281، 285
values، updates، checkpoints، custom، tasks داده‌های حالت متناظرِ همان نام در نسخه‌ی v1 289 تا 305

{{code langchain_protocol/protocol.py:269-306}}

یک فریم messages، برای هر پیام مدل یکی از رویدادهای زیر را در خود دارد:

رویداد کلیدها در اجرای ما
message-start role، id 2
content-block-start index، content 2
content-block-delta index، delta؛ مانند {"type": "text-delta", "text": "The"} 9 (شامل 8 مورد text-delta و 1 مورد tool-call-delta)
content-block-finish index، content، کل بلوک 2
message-finish در اجرای ما کلیدی نداشت 2
error طبق پروتکل تعریف می‌شود 0

{{code langchain_protocol/protocol.py:470-495}}

سرویس‌دهنده‌ای که آرگومان‌های فراخوانی ابزار را استریم می‌کند، دلتاهای tool-call-delta می‌فرستد {{code langchain_protocol/protocol.py:177}}. مدل ChatOllama کل فراخوانی را یک‌جا در یک چانک و قبل از چانک آخر ارسال می‌کند. بنابراین اجرای v3 در این بسته، تنها یک رویداد tool-call-delta دارد که کل داده‌های فراخوانی را در بر می‌گیرد.

منابع: libs/langgraph/langgraph/types.py، libs/langgraph/langgraph/pregel/main.py و libs/langgraph/langgraph/graph/state.py در langgraph نسخه 1.2.22؛ libs/prebuilt/langgraph/prebuilt/tool_node.py در langgraph-prebuilt نسخه 1.1.2؛ libs/core/langchain_core/runnables/base.py در langchain-core نسخه 1.8.0؛ langchain_protocol/protocol.py در langchain-protocol نسخه 0.0.21؛ capture/requirements.txt، capture/README.md، 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.

ترجمه‌ی فارسی Stream modes and event types از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما