هر اجرا را در قالب یک وظیفهی مجزای asyncio شروع کنید که رویدادها را در یک صف مینویسد؛ با این کار، پاسخ HTTP فقط از صف میخواند و در صورت قطع ارتباط کلاینت، اجرای برنامه لغو نمیشود.
اگر agent.astream را داخل یک مسیر FastAPI بگذارید و چانکهای آن را بهصورت رویدادهای ارسالی سرور (Server-Sent Events یا SSE) برگردانید، همهچیز کار میکند؛ تا وقتی که اینترنت گوشی کاربر وسط فرایند بازگشت وجه (refund) قطع شود. وقتی ارتباط کلاینت قطع میشود، Starlette گروه وظایف (task group) مربوط به آن پاسخ را لغو میکند {{code starlette/responses.py:247-285}}. از آنجا که astream هم درون همین گروه اجرا میشود، دستور لغو به آن هم میرسد.
با پایان این بخش، میتوانید ساختار مورد نیاز این فصل را بسازید: مسیر وب اجرا را آغاز میکند، مالکیت آن به یک وظیفه (task) سپرده میشود و استریم فقط دادهها را میخواند. همچنین مشخص میکنید که کلاینت دقیقاً چه رویدادهایی را با چه ترتیبی دریافت کند.
سرویس در یک نگاه
سرویس مرجع ما یک برنامهی FastAPI با یک create_agent و یک پایگاه دادهی Postgres است و شش مسیر (route) دارد.
| مسیر | عملکرد |
|---|---|
POST /threads |
ایجاد یک ترد و ثبت مالک آن |
POST /threads/{id}/runs |
شروع یک اجرا با پیام کاربر و استریمینگ رویدادهای آن |
POST /threads/{id}/approve |
پاسخ به تایید معلق و استریم ادامهی فرایند اجرا |
GET /threads/{id}/state |
بازگرداندن پیامها، گرههای بعدی و وقفههای معلق |
GET /memories |
فهرست یادداشتهای ذخیرهشده برای درخواستکننده |
GET /healthz |
گزارش فعال بودن فرایند سرور |
ایجنت شش ابزار دارد؛ یک پشتهی میانافزار (middleware stack) که در بخش 9.5 توضیح داده شده، و چکپوینتر (checkpointer) و حافظهی ذخیرهسازیِ (store) Postgres که در بخش 9.2 آمده است. مدل هم یک مقدار تنظیمی است: ollama:<name> یا anthropic:<name>.
این پشته هشت میانافزار دارد که سهتای آنها گره اضافه میکنند. تصویر گراف کامپایلشدهی build_agent را بر اساس متن Mermaid آن رسم میکند. کیت، این گراف را با مدلهایی میسازد که هیچوقت فراخوانی نمیشوند و از یک جایگزین برای ماژول OpenTelemetry استفاده میکند. Tracing و ToolTimeout فقط قلابهای پوششی (wrap hooks) دارند؛ بنابراین این جایگزین تغییری در هیچ گرهای ایجاد نمیکند.
یک وظیفه مالک اجرا میشود
وظیفهی اجرا (Run task): وظیفهی asyncio که agent.astream را برای یک اجرا پیمایش میکند و تکتک رویدادها را داخل یک صف میگذارد. مسیر وب این وظیفه را راه میاندازد و بلافاصله برمیگردد؛ پاسخ HTTP فقط این صف را میخواند.
async def start(self, user_id, thread_id, payload):
if not await self.locks.acquire(thread_id):
raise HTTPException(409, "a run is already active on this thread")
queue = asyncio.Queue()
task = asyncio.create_task(self.run(user_id, thread_id, payload, queue))
self.active[thread_id] = task
task.add_done_callback(lambda _: self.active.pop(thread_id, None))
return queueاین تفکیک سه پیامد دارد: با قطع اتصال کلاینت، ارسال پاسخ تمام میشود، اما وظیفهی اجرا متوجه آن نمیشود و کارش ادامه مییابد. سرویس فهرستی از وظایف فعال را نگه میدارد تا هنگام خاموش شدن سرور (shutdown)، همانطور که در بخش 9.5 میبینیم، منتظر اتمام آنها بماند. قفل ترد قبل از شروع وظیفه گرفته شده و در بلوک finally آن آزاد میشود؛ بنابراین اگر اجرای دومی روی همان ترد بیاید، بلافاصله خطای 409 میگیرد.
async def run(self, user_id, thread_id, payload, queue):
status, started = "cancelled", time.perf_counter()
try:
status = await self.traced(user_id, thread_id, payload, queue)
finally:
seconds = round(time.perf_counter() - started, 4)
event("run.end", thread_id=thread_id, status=status, seconds=seconds)
await self.locks.release(thread_id)
queue.put_nowait(("done", {"status": status, "seconds": seconds}))
queue.put_nowait(None)ترتیب کارها در بلوک finally مهم است: قفل باید قبل از ارسال رویداد done آزاد شود. در غیر این صورت، کلاینتی که بهمحض خواندن done اجرای بعدی را شروع میکند، ممکن است وارد رقابت با آزادسازی قفل شود و خطای 409 بگیرد.
اندازهگیری کردیم: اثر قطع ارتباط کلاینت روی یک اجرا را روی مک با مدل Qwen3 4B در پنج آزمایش سنجیدیم. در هر آزمایش، یک پرسش متداول (FAQ) فرستاده شد و اتصال بلافاصله پس از اولین رویداد SSE (بین 245 تا 1910 میلیثانیه پس از درخواست) بسته شد. سپس بلافاصله پیام دومی به ترد ارسال شد و وضعیت آن تا پایان اجرا خوانده شد.
- پیام دوم در هر 5 آزمایش با خطای 409 مواجه شد، چون اجرای اول هنوز ترد را در اختیار داشت.
- اجرا در هر 5 آزمایش کامل شد و پس از 3.56 تا 4.71 ثانیه به وضعیت
doneرسید. هر ترد در نهایت با پیام کاربر، یک فراخوانیsearch_faq، نتیجهی آن و پاسخ نهایی خاتمه یافت.
رویدادهای روی استریم
وظیفهی اجرا از متد astream دو حالت استریمینگِ همزمان messages و updates را با پارامتر version="v2" درخواست میکند. سپس هر بخش را به token، tool_call، tool_result یا interrupt تبدیل میکند. وظیفهی اجرا در پایان یک رویداد done میافزاید و اگر در اجرا خطایی پرتاب شود، رویداد error را میفرستد.
def to_events(part):
if part["type"] == "messages":
chunk, meta = part["data"]
if chunk.type == "AIMessageChunk" and chunk.text and meta.get("langgraph_node") == "model":
yield "token", {"text": chunk.text}
return
for node, update in part["data"].items():
if node == "__interrupt__":
for item in update:
yield "interrupt", {"id": item.id, **item.value}
continue
if node not in ("model", "tools") or not isinstance(update, dict):
continueفیلتر کردن نام گره دلیل موجهی دارد: میانافزار خلاصهسازی (summarization) در قالب یک گره اختصاصی اجرا میشود. بهروزرسانیِ این گره همهی پیامها را پاک کرده و خلاصه به همراه پیامهای نگهداشتهشده را بازنویسی میکند {{code libs/langchain_v1/langchain/agents/middleware/summarization.py:551-557}}. در نتیجه پیامهای هوش مصنوعی را که کلاینت قبلاً دیده است، دوباره تکرار میکند. بدون این فیلتر، کلاینت رویدادهای تکراری tool_call را دوباره دریافت میکرد. توکنها فقط از گره model میآیند؛ بنابراین متن خلاصهسازی هرگز به کلاینت نمیرسد.
اندازهگیری کردیم: یک مکالمهی سه درخواستی را روی مک با مدل Qwen3 4B اجرا و زمان رسیدن هر رویداد به کلاینت را ثبت کردیم. مدل از قبل بارگذاری شده بود.
| درخواست | اولین رویداد | رویدادها، به ترتیب | done |
|---|---|---|---|
| سوال درباره سفارش | tool_call در 682 میلیثانیه |
tool_call، tool_result در 698 میلیثانیه، 30 توکن از 1016 میلیثانیه |
1527 میلیثانیه |
| بازگشت وجه 8900 سنتی | tool_call در 2090 میلیثانیه |
tool_call، interrupt در 2122 میلیثانیه |
2125 میلیثانیه با وضعیت interrupted |
| تایید | tool_result در 32 میلیثانیه |
tool_result، 38 توکن از 765 میلیثانیه |
2158 میلیثانیه |
هر رویداد tool_call ظرف 30 میلیثانیه پس از پایان فراخوانی مدل به کلاینت رسید. درخواست تایید یک رویداد interrupt بود و استریم 3 میلیثانیه پس از آن با رویداد done و وضعیت interrupted خاتمه یافت. در درخواست تایید، فراخوانی مدل انجام نشد: اولین رویداد، نتیجهی بازگشت وجه در 32 میلیثانیه پس از درخواست بود.
نخستین درخواست در یک ثبت دادهی قبلی که بلافاصله پس از آزمایشهای تخلیه با Qwen3 14B ارسال شد، 15.42 ثانیه طول کشید؛ چرا که اولین فراخوانی مدل بهخاطر بارگذاری مجدد Qwen3 4B حدود 13.4 ثانیه زمان برد. همیشه مدل را روی سرور اشتراکی در حافظه آماده نگه دارید؛ وگرنه اولین مشتری بعد از تعویض مدل باید معطل بارگذاری آن بماند.
ضربان قلب در زمان انتظار اجرا
یک اجرا ممکن است پیش از ارسال اولین رویدادش مدت زیادی منتظر بماند؛ مثلاً در صف سرورِ مدل پشت بقیهی اجراها معطل شود. تا آن لحظه هیچ بایتی از استریم ارسال نمیشود و کلاینت HTTP این سکوت را بهحساب قطعی اتصال میگذارد. سرویس ما اگر تا 15 ثانیه رویدادی دریافت نکند، یک خط کامنت SSE میفرستد. کلاینت باید خطوطی را که با دونقطه شروع میشوند نادیده بگیرد؛ بنابراین این کامنت حامل هیچ دادهای نیست.
HEARTBEAT = float(os.environ.get("HEARTBEAT_SECONDS", "15"))
async def sse(queue):
while True:
try:
item = await asyncio.wait_for(queue.get(), HEARTBEAT) if HEARTBEAT > 0 else await queue.get()
except TimeoutError:
yield ": waiting\n\n"
continue
if item is None:
return
name, data = item
yield f"event: {name}\ndata: {json.dumps(data, default=str)}\n\n"اندازهگیری کردیم: سناریوی بار 50 کاربره از بخش 9.7 را دوباره با یک ورکر و مدل Qwen3 4B روی مک در یک دور اجرا سنجیدیم. مهلت خواندن (read timeout) کلاینتها روی همان 120 ثانیه ماند.
| درخواستها | اتمام مهلت خواندن کلاینت | اجراهایی که کلاینتها پایانشان را دیدند | اجراهایی که سرور پایان داد | میانه و حداکثر ثانیه به ازای هر اجرا | |
|---|---|---|---|---|---|
| بدون ضربان قلب | 157 | 48 | 107 | 155، که 19 مورد هنگام خاموش شدن سرور cancelled شدند |
164.7 و 193.8 |
| با ضربان قلب | 200 | 0 | 192 | 192، بدون هیچ لغوی | 194.8 و 286.7 |
با وجود ضربان قلب، همهی نشستها هر چهار درخواست خود را ارسال کردند و کندترین اجرا 286.7 ثانیه طول کشید، بدون اینکه اتصالی قطع شود. 8 درخواست دیگر، تاییدیههایی بودند که خطای 409 گرفتند، چون مدل بازگشت وجهی پیشنهاد نداده بود. اجراها طولانیتر شدند چون تعداد بیشتری از آنها به مدل رسیدند؛ با این حال سرور همچنان 0.231 اجرا را در هر ثانیه به پایان رساند.
دستگاه مک برای این اجرا زیر بار سنگینی بود و میانگین بار (load average) به 32.78 رسید. زمانها را بر حسب ثانیه بهعنوان حد بالا و تعدادها را نتیجهی کار در نظر بگیرید. ضربان قلب کلاینت را متصل نگه میدارد؛ قرار نیست سرعت مدل را بیشتر کند.
منابع: capture/lab/prodapp-mac/code/app/server.py، capture/lab/prodapp-mac/code/app/agent.py، capture/out/54-draw-service-agent.txt، capture/s_draw.py، capture/lab/prodapp-mac/code/scripts/capture_stream.py، capture/lab/prodapp-mac/code/scripts/disconnect_real.py، capture/lab/prodapp-mac/summary/stream-mac.json، capture/lab/prodapp-mac/summary/disconnect-mac.json، capture/lab/prodapp-mac/runs/stream/stream-events.jsonl، capture/lab/prodapp-mac/runs/stream/stream.spans.jsonl، capture/lab/prodapp-mac/runs/disconnect/disconnect-trials.json، capture/lab/prodapp-mac/summary/fix-mac.json، capture/lab/prodapp-mac/runs/fix/load/load-summary.json، capture/lab/prodapp-mac/runs/load/load-summary.json؛ libs/langgraph/langgraph/pregel/main.py در langgraph 1.2.22؛ starlette/responses.py در starlette 1.10.0.