بخش 9.1 · محیط عملیاتی

اندپوینت اجرا: StreamingResponse و یک وظیفه به ازای هر اجرا

The run endpoint: StreamingResponse and one task per run

فهرست مطالب
  1. سرویس در یک نگاه
  2. یک وظیفه مالک اجرا می‌شود
  3. رویدادهای روی استریم
  4. ضربان قلب در زمان انتظار اجرا

هر اجرا را در قالب یک وظیفه‌ی مجزای 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) دارند؛ بنابراین این جایگزین تغییری در هیچ گره‌ای ایجاد نمی‌کند.

گراف ایجنت سرویسچهار گره قلاب از سه میان‌افزار دور مدل قرار دارند و ModelCallLimitMiddleware می‌تواند اجرا را قبل یا بعد از فراخوانی مدل پایان دهد.
گراف ایجنت سرویس گراف کامپایل‌شده‌ی build_agent در سرویس مرجع، رسم‌شده از خروجی draw_mermaid آن. این گراف 8 گره دارد که 4 تای آن‌ها گره‌های قلاب هستند: SummarizationMiddleware.before_model، ModelCallLimitMiddleware.before_model، ModelCallLimitMiddleware.after_model، HumanInTheLoopMiddleware.after_model. سایر میان‌افزارها فقط قلاب‌های wrap دارند و گرهی اضافه نمی‌کنند. ModelCallLimitMiddleware می‌تواند اجرا را قبل از مدل یا بعد از آن پایان دهد. گره tools شامل 6 ابزار است: read_order، refund_order، search_faq، create_ticket، save_note، recall_notes. GET_GRAPH() OF BUILD_AGENT 8 گره، 4 تای آن‌ها قلاب __start__ model tools __tools = read_order, refund_order, search_faq, create_ticket, save_note, recall_notes SummarizationMiddleware.before_model ModelCallLimitMiddleware.before_model ModelCallLimitMiddleware.after_model HumanInTheLoopMiddleware.after_model __end__ یال ساده یال شرطی، انتخاب‌شده در زمان اجرا
خواندن از __start__ در بالا آغاز می‌شود. جعبه‌های آبی گره‌های قلاب هستند. پنج میان‌افزار دیگر فراخوانی مدل یا فراخوانی‌های ابزار را در بر می‌گیرند و گرهی اضافه نمی‌کنند. از capture/out/54-draw-service-agent.txt.

یک وظیفه مالک اجرا می‌شود

وظیفه‌ی اجرا (Run task): وظیفه‌ی asyncio که agent.astream را برای یک اجرا پیمایش می‌کند و تک‌تک رویدادها را داخل یک صف می‌گذارد. مسیر وب این وظیفه را راه می‌اندازد و بلافاصله برمی‌گردد؛ پاسخ HTTP فقط این صف را می‌خواند.

مسیر یک وظیفه را آغاز می‌کند، و پاسخ صف آن را می‌خواند capture/lab/prodapp-mac/code/app/server.py
    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 می‌گیرد.

وظیفه اجرا قفل را آزاد می‌کند، سپس done را می‌فرستد capture/lab/prodapp-mac/code/app/server.py
    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 را می‌فرستد.

چگونه بخش‌های جریان به رویدادهای SSE تبدیل می‌شوند capture/lab/prodapp-mac/code/app/server.py
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 ثانیه زمان برد. همیشه مدل را روی سرور اشتراکی در حافظه آماده نگه دارید؛ وگرنه اولین مشتری بعد از تعویض مدل باید معطل بارگذاری آن بماند.

سه درخواست، اسپن‌های هر اجرا، و رویدادهایی که کلاینت خواندکلاینت هر فراخوانی ابزار را پس از پایان فراخوانی مدل آن خواند، و درخواست تأیید در قالب یک رویداد وقفه رسید که به جریان پایان داد.
سه درخواست به سرویس، اسپن‌های هر اجرا، و رویدادهای SSE یک گفتگو با Qwen3 4B روی مک. درخواست 1 مدت 1527 میلی‌ثانیه طول کشید، با 2 فراخوانی مدل و رویدادهای tool_call، tool_result، done. درخواست 2 مدت 2125 میلی‌ثانیه طول کشید، با 1 فراخوانی مدل و رویدادهای tool_call، interrupt، done. درخواست 3 مدت 2158 میلی‌ثانیه طول کشید، با 1 فراخوانی مدل و رویدادهای tool_result، done. model.call اسپن ابزار رویداد SSE در سمت کلاینت رویدادهای توکن 1. POST /runs: سفارش من کجاست وظیفه سرور جریان کلاینت 556 ورودی، 24 خروجی 635 ورودی، 31 خروجی tool_call read_order tool_result done 2. POST /runs: بازپرداخت 8900 سنت وظیفه سرور جریان کلاینت 699 ورودی، 44 خروجی tool_call refund_order وقفه done، متوقف‌شده با وقفه 3. POST /approve: تایید 0 500 1000 1500 2000 2500 وظیفه سرور جریان کلاینت 790 ورودی، 39 خروجی tool_result done میلی‌ثانیه پس از ارسال درخواست
هر قاب یک درخواست HTTP برحسب میلی‌ثانیه پس از ارسال است. ردیف بالا وظیفه اجرا با اسپن‌های مدل و ابزار است. ردیف پایین کلاینت را با هر رویداد SSE در زمان رسیدن آن نشان می‌دهد. از capture/lab/prodapp-mac/summary/stream-mac.json.

ضربان قلب در زمان انتظار اجرا

یک اجرا ممکن است پیش از ارسال اولین رویدادش مدت زیادی منتظر بماند؛ مثلاً در صف سرورِ مدل پشت بقیه‌ی اجراها معطل شود. تا آن لحظه هیچ بایتی از استریم ارسال نمی‌شود و کلاینت HTTP این سکوت را به‌حساب قطعی اتصال می‌گذارد. سرویس ما اگر تا 15 ثانیه رویدادی دریافت نکند، یک خط کامنت SSE می‌فرستد. کلاینت باید خطوطی را که با دونقطه شروع می‌شوند نادیده بگیرد؛ بنابراین این کامنت حامل هیچ داده‌ای نیست.

خواننده جریان، با یک خط کامنت به ازای هر 15 ثانیه سکوت capture/lab/prodapp-mac/code/app/server.py
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 رسید. زمان‌ها را بر حسب ثانیه به‌عنوان حد بالا و تعدادها را نتیجه‌ی کار در نظر بگیرید. ضربان قلب کلاینت را متصل نگه می‌دارد؛ قرار نیست سرعت مدل را بیشتر کند.

آنچه 50 کلاینت مشاهده کردند، بدون و با ضربان قلب روی جریانبا درج یک خط کامنت در هر 15 ثانیه، 0 از 200 درخواست دچار تایم‌اوت شدند، در برابر 48 نشست از دست رفته بر اثر تایم‌اوت خواندن بدون آن.
آنچه 50 کلاینت مشاهده کردند، بدون و با ضربان قلب روی جریان بدون ضربان قلب: 102 مورد done، 5 مورد interrupted، 2 مورد 409 در approve، 48 مورد ReadTimeout، 0.208 اجرا بر هر ثانیه. با ضربان قلب هر 15 ثانیه: 150 مورد done، 42 مورد interrupted، 8 مورد 409 در approve، 0 مورد ReadTimeout، 0.231 اجرا بر هر ثانیه. یک ورکر، Qwen3 4B روی مک، تایم‌اوت خواندن 120 ثانیه. بدون ضربان قلب 0.208 اجرا بر ثانیه، میانه 165 ثانیه بر اجرا 102 48 با ضربان قلب هر 15 ثانیه 0.231 اجرا بر ثانیه، میانه 195 ثانیه بر اجرا 150 42 done interrupted 409 در approve ReadTimeout
هر میله نشان‌دهنده‌ی یک بار اجرای بار کاری با 50 کاربر و یک ورکر است. بخش‌ها شامل درخواست‌هایی هستند که با done به پایان رسیدند، برای تأیید دچار وقفه شدند، با خطای 409 رد شدند، یا بر اثر تایم‌اوت خواندن کلاینت از دست رفتند. از capture/lab/prodapp-mac/summary/fix-mac.json.

منابع: 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.