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

میان‌افزار HumanInTheLoopMiddleware و کلید یکتایی تراکنش

HumanInTheLoopMiddleware and the idempotency key

فهرست مطالب
  1. تاییدیه همان وقفه در دل فراخوانی ابزار است
  2. آنچه ادامه‌ی اجرا ذخیره می‌کند
  3. کرش بعد از ثبت ردیف استرداد
  4. کلید روی ابزار
  5. تاییدکننده همان چیزی را تایید می‌کند که شما نشان می‌دهید

بعد از کرشی که بلافاصله پس از اثر جانبی رخ داد، در 20 بار از 20 تلاش، تاییدیه همچنان در وضعیت معلق بود؛ بنابراین تنها یک کلید روی ابزار جلوی استرداد دوم را می‌گیرد.

کارشناس پشتیبانی دکمه‌ی Approve (تایید) را برای یک استرداد وجه می‌زند. ورکر ردیف استرداد را در پایگاه داده می‌نویسد و سپس فرایند، پیش از پایان اجرا کرش می‌کند و از بین می‌رود. یک ورکر جدید بالا می‌آید، کارشناس رشته‌ی گفت‌وگو را باز می‌کند و می‌بیند همان درخواست تایید دوباره منتظر است. اگر کارشناس بار دوم Approve را بزند، پول ممکن است دو بار به حساب مشتری برگردد.

با پایان این بخش، متوجه می‌شوید LangGraph هنگام ادامه‌ی اجرای یک فرایند پس از تایید چه مواردی را ذخیره می‌کند و چه مواردی را نه. همچنین یاد می‌گیرید چطور یک کلید یکتایی تراکنش (idempotency key) روی ابزاری بگذارید که تراکنش مالی انجام می‌دهد، و چطور دقیقاً به تاییدکننده نشان دهید چه چیزی را تایید می‌کند.

تاییدیه همان وقفه در دل فراخوانی ابزار است

این سرویس با استفاده از HumanInTheLoopMiddleware در حالت per_call از تابع refund_order محافظت می‌کند. در این حالت، میان‌افزار وقفه (interrupt) را از متد wrap_tool_call، داخل نود tools و درست پیش از فراخوانی ابزار صادر می‌کند {{code libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py:751}}. اجرا متوقف می‌شود و استریم یک رویداد interrupt را به همراه نام ابزار و آرگومان‌هایش ارسال می‌کند.

وقفه‌ای که تأییدکننده دید، از اجرای Qwen3 14B capture/lab/prodapp-mac/runs/suite/qwen3-14b/rep-1/cases/19-new_message_while_waiting_for_approval.json
     "interrupt",
     {
      "id": "515c4354e30817f8f987572b7a06c1bb",
      "type": "tool_approval",
      "tool_call_id": "804ec90d-84f1-406c-88a0-d51eb05e480c",
      "name": "refund_order",
      "args": {
       "order_id": "ORD-e19-3",
       "amount_cents": 0,
       "reason": "Customer requested a refund."
      },

یک رویداد از استریم، برگرفته از لاگ پرونده.

مسیر (route) مربوط به approve، به این وقفه با استفاده از شناسه‌ی (id) آن پاسخ می‌دهد. این مسیر یک نگاشت ادامه‌ی اجرا (resume map) می‌فرستد که برای هر وقفه‌ی معلق یک ورودی دارد. این مسیر یک تصمیم واحد را از درخواست می‌خواند و آن را به تک‌تک ورودی‌ها می‌دهد؛ بنابراین یک بار تایید شامل تمام استردادهای معلق می‌شود و شخص تاییدکننده پیش از کلیک باید همه‌ی آن‌ها را ببیند. برای تصمیم‌گیری جداگانه برای هر استرداد وجه، باید به ازای هر شناسه‌ی وقفه یک تصمیم مجزا ثبت کنید.

مسیر تأیید، به همراه دو فرم ادامه‌ی کار (resume) capture/lab/prodapp-mac/code/app/server.py
        state = await s.agent.aget_state(config(thread_id))
        decision = {"type": body.decision} | ({"message": body.message} if body.message else {})
        if state.interrupts and os.environ.get("RESUME_FORM") == "plain" and len(state.interrupts) == 1:
            payload = Command(resume=decision)
        elif state.interrupts:
            payload = Command(resume={item.id: decision for item in state.interrupts})
        elif state.next:
            payload = None
        else:
            raise HTTPException(409, "nothing to resume")

آنچه ادامه‌ی اجرا ذخیره می‌کند

نگاشت ادامه‌ی اجرا (Resume map): یک Command(resume=...) که مقدار آن یک دیکشنری با کلیدهایی از جنس شناسه‌های وقفه است. کتابخانه‌ی LangGraph نسخه‌ی 1.2.22 با این دو ساختار رفتاری متفاوت دارد: مقدار ساده‌ی resume به عنوان یک عملیات نوشتن معلق در چک‌پوینت به put_writes فرستاده می‌شود، اما نگاشت ادامه‌ی اجرا فقط وارد پیکربندیِ اجرا (run config) می‌شود و عملیات نوشتن آن انجام نمی‌شود {{code libs/langgraph/langgraph/pregel/_loop.py:1064-1091}}.

بنابراین با نگاشت ادامه‌ی اجرا، این تصمیم تا زمانی که وظیفه‌ی (task) مربوط به tools پایان یابد و عملیات نوشتن آن ذخیره شود، فقط در حافظه زنده می‌ماند. خود ابزار درون همین وظیفه اجرا می‌شود. اگر سیستم بعد از ثبت ردیف توسط ابزار کرش کند، این تصمیم از دست می‌رود. در نتیجه خواننده‌ی بعدی رشته‌ی گفت‌وگو با همان وقفه‌ی معلق روبه‌رو خواهد شد.

کرش بعد از ثبت ردیف استرداد

ما این موضوع را روی سیستم Mac با مدل Qwen3 4B در 10 تلاش برای هر شکل از رزومه اندازه گرفتیم. در هر تلاش کل مبلغ ORD-crash-2 با ذکر مبلغ و دلیل درون پیام درخواست شد؛ بنابراین مدل نیازی به تصمیم‌گیری یا انتخاب نداشت. ابزار بعد از commit کردن خود 3 ثانیه به خواب می‌رفت. اسکریپت منتظر ثبت ردیف استرداد می‌ماند، سیگنال SIGKILL را به ورکر می‌فرستاد و یک ورکر جدید را بالا می‌آورد. سپس رشته‌ی گفت‌وگو را می‌خواند، یک approve دیگر می‌فرستاد و جدول refunds را بررسی می‌کرد.

در 10 بار از 10 تلاش با نگاشت ادامه‌ی اجرا، ورکر جدید مقدار next را برابر با ["tools"] و همراه با وقفه‌ی معلق تایید گزارش داد. تایید دوم دوباره ابزار را اجرا کرد، کلید مطابقت داشت و ابزار مقدار "replayed": true را برگرداند. هر تلاش تنها با یک ردیف استرداد به مبلغ 8900 سنت به پایان رسید.

فرم ساده در 10 بار از 10 تلاش نتیجه‌ی یکسانی داشت: تاییدیه بعد از ری‌استارت معلق بود و یک ردیف باقی ماند. پس با هیچ‌کدام از این دو ساختار، کلاینت نمی‌تواند بر اساس وضعیت تشخیص دهد که تاییدیه پیش از کرش داده شده بود یا نه. ما بررسی نکردیم که آیا تصمیمی در فرم ساده درون checkpoint_writes زنده می‌ماند یا نه، و همچنین ادامه‌ی اجرا را بدون تصمیم جدید امتحان نکردیم.

کشته شدن ورکر بعد از ثبت سطر بازپرداخت و راه‌اندازی مجدد آنپس از کشته شدن فرایند، تأییدیه دوباره معلق شد و کلید یکتایی ابزار، تأیید دوم را به بازپخشی با همان یک سطر بازپرداخت تبدیل کرد.
کشته شدن ورکر بعد از ثبت سطر بازپرداخت و راه‌اندازی مجدد آن بالا: یک آزمایش روی مک با Qwen3 4B. تأیید در ثانیه 0 ارسال شد، سطر بازپرداخت در ثانیه 0.2 در Postgres ثبت شد و SIGKILL در ثانیه 0.3 آمد. فرایند جدید ترد را در ثانیه 3.1 خواند و next ["tools"] را یافت که تأییدیه در آن دوباره خواسته شد. پایین: مقدار resume از نوع map، 10 از 10 آزمایش با یک سطر بازپرداخت و درخواست مجدد تأیید در هر 10 بار؛ مقدار resume ساده، 10 از 10 آزمایش با یک سطر بازپرداخت و درخواست مجدد تأیید در هر 10 بار. 0 2 4 6 ثانیه پس از ارسال اولین تأیید worker 1 worker 2 پس از راه‌اندازی مجدد Postgres جدول refunds SIGKILL یک سطر، 8900 سنت همان کلید، replayed true تأییدیه دوباره خواسته شد تأیید همه‌ی آزمایش‌ها مقدار resume از نوع map 10 از 10 یک سطر بازپرداخت، در هر 10 بار تأییدیه مجدد خواسته شد مقدار resume ساده 10 از 10 یک سطر بازپرداخت، در هر 10 بار تأییدیه مجدد خواسته شد
قاب بالا یک آزمایش است، برحسب ثانیه پس از اولین تأیید. قاب پایین همه‌ی آزمایش‌ها است. مربع سبزآبی یک سطر بازپرداخت 8900 سنتی دارد و کادر کهربایی یعنی تأییدیه دوباره در انتظار مانده است. از capture/lab/prodapp-mac/summary/crash-mac.json.

بعد از اعمال بررسی‌های مربوط به مبلغ در زیربخش‌های بعدی، دوباره آزمایش کرش را با Qwen3 4B در 3 تلاش اجرا کردیم. نتیجه تغییری نکرد: در 3 بار از 3 تلاش، تاییدیه پس از ری‌استارت معلق ماند، تایید دوم کلید را بازپخش کرد و همان یک ردیف 8900 سنتی باقی ماند. همین تلاش‌ها با مدل Qwen3 14B اجرا نشد؛ زیرا ابزار Ollama به مدت 9.5 دقیقه، در حالی که پردازش دیگری حافظه را اشغال کرده بود، مدل را بارگذاری نکرد و ما متوقفشان کردیم.

کلید روی ابزار

استرداد وجه کاملاً ایمن است، زیرا refund_order پیش از نوشتن، کلید را بررسی می‌کند.

کلید یکتایی تراکنش و اعتبارسنجی مبلغ در refund_order capture/lab/prodapp-mac/code/app/tools.py
    key = f"{ctx.thread_id}:{order_id}:{amount_cents}"
    async with ctx.pool.connection() as conn, conn.transaction():
        cur = await conn.execute(
            "select total_cents, refunded_cents from orders where id = %s and user_id = %s for update",
            (order_id, ctx.user_id),
        )
        order = await cur.fetchone()
        if order is None:
            return json.dumps({"error": f"no order {order_id} on this account"})
        remaining = order["total_cents"] - order["refunded_cents"]
        if amount_cents <= 0:
            return json.dumps({"error": f"amount_cents must be positive; {remaining} cents can be refunded"})
        cur = await conn.execute(
            "select refund_id, order_id, amount_cents from refunds where idempotency_key = %s", (key,)
        )
        if existing := await cur.fetchone():
            return json.dumps({**existing, "replayed": True})
        if amount_cents > remaining:
            return json.dumps({"error": f"refund exceeds the {remaining} cents that can still be refunded"})
…

عملیات درج و به‌روزرسانی پس از بررسی‌ها حذف شده است.

این کلید از سه بخش تشکیل شده است: رشته‌ی گفت‌وگو، سفارش و مبلغ. این کلید نام هیچ درخواست مشخصی را در بر ندارد. ارسال مجدد همان درخواست در یک رشته‌ی گفت‌وگوی جدید کلید متفاوتی می‌گیرد؛ پس کلاینتی که درخواست را تکرار می‌کند باید همان رشته را حفظ کند.

دستور SELECT ... FOR UPDATE ردیف سفارش را قفل می‌کند تا دو ورکر نتوانند هم‌زمان از این بررسی عبور کنند. جدول refunds هم یک نمایه‌ی یکتا (unique index) روی این کلید دارد. فرایند بازپخش، اولین استرداد را با "replayed": true برمی‌گرداند و مدل به مشتری اعلام می‌کند که استرداد ثبت شده است.

درخواست همان مبلغ برای همان سفارش درون همان رشته‌ی گفت‌وگو نیز استرداد اول را بازپخش می‌کند، حتی اگر مانده‌حساب اجازه‌ی استرداد دوم را بدهد. ما این سناریو را آزمایش نکردیم. یک مشتری ممکن است دو استرداد وجه با مبالغ برابر بخواهد؛ در این حالت باید شناسه‌ی ذخیره‌شده‌ی tool_call_id را به کلید اضافه کنید. ادامه‌ی اجرا این شناسه را دوباره تکرار می‌کند، ولی یک درخواست تازه این کار را نخواهد کرد.

کلید دوام می‌آورد چون بازپخش، دقیقاً همان آرگومان‌ها را ارسال می‌کند. بعد از ری‌استارت، نود tools همان فراخوانی ابزاری را که چک‌پوینت ثبت کرده اجرا می‌کند؛ از روی همان پیام مدلی که هوش مصنوعی پیش از وقفه نوشته بود. مدل دوباره فراخوانی نمی‌شود. اگر می‌شد، ممکن بود مبلغ دیگری را انتخاب کند و کلید فرق کند. بخش محیط اجرا همین قانون را برای هر نود دیگری نشان می‌دهد: یک اثر جانبی را بر پایه‌ی آنچه چک‌پوینت ثبت کرده کلیدگذاری کنید. تایپ کردن یک پیام در رابط کاربری Agent Chat نیز مسیر دومی برای اعلام موفقیتی است که اصلاً اجرا نشده؛ همان‌طور که بخش رابط کاربری چت نشان می‌دهد.

تاییدکننده همان چیزی را تایید می‌کند که شما نشان می‌دهید

کلید یکتایی تراکنش مانع استرداد دوم می‌شود، اما جلوی اشتباه در همان استرداد اول را نمی‌گیرد. در اولین اجراهای ارزیابی، هر دو مدل Qwen3 4B و Qwen3 14B برای درخواست Refund ORD-e19-3 مقدار amount_cents را 0 پیشنهاد دادند و تست هم آن را تایید کرد. ابزار در 3 بار از 3 اجرا روی هر مدل، یک ردیف استرداد 0 سنتی ثبت کرد. سپس مدل به مشتری گفت که استرداد پردازش شده است. مدل Qwen3 14B برای سفارش‌های 12900 و 8900 سنتی هم بدون خواندن اطلاعات هیچ‌کدام، مبلغ 10000 سنت را پیشنهاد داد.

به همین دلیل سرویس حالا دو کار دیگر انجام می‌دهد: ابزار سفارش را می‌خواند و اگر مبلغ، 0 یا کمتر باشد یا از مبلغ قابل‌استردادِ باقی‌مانده تجاوز کند، از انجام آن امتناع می‌کند (refusal)؛ همان‌طور که در کد بالا آمد. متن خطای آن مقدار قابل‌استرداد را مشخص می‌کند تا مدل بتواند رفتار خود را اصلاح کند. همچنین درخواست تایید شامل توضیحاتی است که میان‌افزار از روی سفارش می‌سازد.

توضیحات تأییدیه، ساخته‌شده بر اساس سفارش capture/lab/prodapp-mac/code/app/tools.py
def refund_description(tool_call, state, runtime):
    args = tool_call["args"]
    with psycopg.connect(runtime.context.pool.conninfo, row_factory=dict_row) as conn:
        order = conn.execute(
            "select item, total_cents, refunded_cents from orders where id = %s and user_id = %s",
            (args.get("order_id"), runtime.context.user_id),
        ).fetchone()
…
    remaining = order["total_cents"] - order["refunded_cents"]
    return (f"Refund {args.get('amount_cents')} cents on {args.get('order_id')} ({order['item']}). "
            f"Order total {order['total_cents']} cents, refunded so far {order['refunded_cents']}, "
            f"refundable now {remaining}. Reason: {args.get('reason')}")

میان‌افزار HumanInTheLoopMiddleware یک description برای هر ابزار دریافت می‌کند؛ این توصیف می‌تواند یک رشته باشد یا یک فراخوان‌پذیر (callable) که فراخوانی ابزار، وضعیت و محیط اجرا (runtime) را تحویل می‌گیرد {{code libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py:613-620}}. این فراخوان‌پذیر همگام (synchronous) است، بنابراین برای یک کوئری، یک اتصال همگام کوتاه باز می‌کند.

ما دوباره شش ارزیابی استرداد وجه را روی سیستم Mac اندازه گرفتیم؛ 3 اجرا روی هر مدل، با همان پرامپت‌ها و مقادیر seed یکسان. شکل 9.3b موردِ استرداد صفر سنتی را نشان می‌دهد.

مدل ارزیابی‌های استرداد قبول‌شده، قبل و بعد اجراها با ردیف 0 سنتی، قبل و بعد متنی که تاییدکننده برای پیشنهاد 0 سنتی خواند
Qwen3 4B 1 از 6 در 3 از 3 اجرا، در هر دو بار 3 از 3، سپس 0 از 3 Refund 0 cents on ORD-e19-3 (Water bottle). Order total 2400 cents, refunded so far 0, refundable now 2400.
Qwen3 14B 3 از 6 در 3 از 3 اجرا، در هر دو بار 3 از 3، سپس 0 از 3 همان متن
بازپرداخت صفر سنتی قبل و بعد از بررسی مبلغ توسط ابزارپیشنهاد تأییدشده‌ی بازپرداخت 0 سنتی، قبل از بررسی‌ها در 6 از 6 اجرا سطر بازپرداخت نوشت و بعد از آن در 0 از 6 اجرا.
بازپرداخت صفر سنتی قبل و بعد از بررسی مبلغ توسط ابزار ارزیابی تقاضای بازپرداخت ORD-e19-3 دارد و هر آنچه مدل پیشنهاد دهد تأیید می‌کند. پیش از اصلاح، Qwen3 4B در 3 اجرا 3 سطر صفر سنتی نوشت و Qwen3 14B نیز 3 سطر صفر سنتی نوشت. پس از اصلاح، Qwen3 4B در 3 اجرا 0 سطر و Qwen3 14B نیز 0 سطر نوشت. متن تأیید پس از اصلاح: بازپرداخت 0 سنت برای ORD-e19-3 (Water bottle). کل سفارش 2400 سنت، بازپرداخت‌شده تاکنون 0، قابل بازپرداخت 2400. دلیل: مشتری درخواست بازپرداخت داده است. پیش از اصلاح پس از اصلاح Qwen3 4B بازپرداخت ORD-e19-3 اجرای 1 سطر 0 سنتی اجرای 2 سطر 0 سنتی اجرای 3 سطر 0 سنتی اجرای 1 درخواست 0 رد شد اجرای 2 درخواست 0 رد شد اجرای 3 درخواست 0 رد شد Qwen3 14B بازپرداخت ORD-e19-3 اجرای 1 سطر 0 سنتی اجرای 2 سطر 0 سنتی اجرای 3 سطر 0 سنتی اجرای 1 درخواست 0 رد شد اجرای 2 درخواست 0 رد شد اجرای 3 درخواست 0 رد شد آنچه تأییدکننده پس از اصلاح خواند بازپرداخت 0 سنت برای ORD-e19-3 (Water bottle). کل سفارش 2400 سنت، بازپرداخت‌شده تاکنون 0، قابل بازپرداخت 2400. دلیل: مشتری درخواست بازپرداخت داده است.
هر خانه یک اجرای ارزیابی است که هر بازپرداختی را که مدل برای ORD-e19-3 پیشنهاد کند تأیید می‌کند. رنگ سرخ یک سطر 0 سنتی ثبت کرد و سبزآبی هیچ سطری ننوشت. متن زیر درخواست تأییدیه پس از اعمال اصلاح است. از capture/lab/prodapp-mac/summary/fix-mac.json.

تعداد موارد قبولی تغییری نکرد، چرا که خطاها ناشی از تصمیم‌های خود مدل بودند. پس از امتناع مدل، Qwen3 14B در 3 بار از 3 اجرا، کل مبلغ 2400 سنت را پیشنهاد داد و از مشتری خواست تایید کند. این پاسخ درست است، اما ارزیابی باز هم رد می‌شود؛ زیرا انتظار دارد استرداد فوراً انجام شود. روی سفارش 8900 سنتی، ابزار با خطای refund exceeds the 8900 cents that can still be refunded از استرداد 10000 سنت امتناع کرد. در پیام بعدی مشتری، مدل Qwen3 14B جزئیات سفارش را خواند و در 3 بار از 3 اجرا، تایید کل مبلغ را خواست.

تنها یک خطا پابرجا می‌ماند: در سفارش 12900 سنتی، مدل Qwen3 14B مبلغ 10000 سنت را پیشنهاد داد و تاییدکننده متن Refund 10000 cents on ORD-e06-1 (Trail running shoes). Order total 12900 cents, refunded so far 0, refundable now 12900 را خواند. از آنجا که مبلغ معتبر است، ابزار آن را می‌پذیرد. تنها انسانی که اعداد را می‌خواند می‌تواند جلوی یک استرداد ناقص را بگیرد که هیچ‌کس خواستارش نبوده است.

منابع: capture/lab/prodapp-mac/summary/crash-mac.json، capture/lab/prodapp-mac/runs/crash-map/crash-trials.json، capture/lab/prodapp-mac/runs/crash-plain/crash-trials.json، capture/lab/prodapp-mac/runs/crash-map/t01-before-kill.log.jsonl، capture/lab/prodapp-mac/runs/crash-map/t01-after-restart.log.jsonl، capture/lab/prodapp-mac/code/scripts/crash_real.py، capture/lab/prodapp-mac/code/app/server.py، capture/lab/prodapp-mac/code/app/tools.py، capture/lab/prodapp-mac/code/app/db.py، capture/lab/prodapp-mac/runs/suite/qwen3-14b/rep-1/cases/19-new_message_while_waiting_for_approval.json، capture/lab/prodapp-mac/summary/evals-mac.json، capture/lab/prodapp-mac/summary/fix-mac.json، capture/lab/prodapp-mac/runs/fix/crash-qwen3-4b/crash-trials.json، capture/lab/prodapp-mac/runs/fix/INVALID.txt، capture/lab/prodapp-mac/runs/fix/suite/qwen3-4b/rep-1/cases/19-new_message_while_waiting_for_approval.json، capture/lab/prodapp-mac/runs/fix/suite/qwen3-14b/rep-1/cases/06-refund_approved_once.json، capture/lab/prodapp-mac/code/app/agent.py؛ libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py در langchain==1.5.0؛ libs/langgraph/langgraph/pregel/_loop.py در langgraph 1.2.22.