بخش 4.8 · ایجنت، خروجی ساختاریافته و میان‌افزار

گاردریل‌ها، داده‌های حساس و میدل‌ویر تصمیم‌گیری (نسخه‌ی آزمایشی)

Guardrails, PII, and the decision middleware (beta)

فهرست مطالب
  1. دو نوع گاردریل
  2. میدل‌ویر PIIMiddleware
  3. مدل‌های تصمیم‌گیر
  4. میدل‌ویر ModelRouterMiddleware
  5. میدل‌ویر AutoModeMiddleware

میدل‌ویر PIIMiddleware داده‌های حساس فردی را بر اساس یک قاعده‌ی ثابت بازنویسی یا مسدود می‌کند؛ دو میدل‌ویر آزمایشی نیز به کمک یک مدل تصمیم‌گیر، مدل مناسب را برمی‌گزینند یا جلوی فراخوانی را می‌گیرند.

کاربری یک نشانی ایمیل و شماره کارت بانکی را در ایجنت پشتیبانی شما وارد می‌کند. اکنون ارائه‌دهنده‌ی مدل هر دوی این داده‌ها را در اختیار دارد. یک روز بعد، مدل درخواست حذف branch به نام main را می‌دهد و ابزار مربوطه اجرا می‌شود. در هر دو حالت، جای یک بررسی میان کاربر، مدل و ابزارها خالی بوده است.

پس از پایان این بخش، می‌توانید راهبرد مناسب برای پاک‌سازی داده‌های حساس (PII strategy) را انتخاب کنید، مشخص کنید PIIMiddleware در چه نقطه‌ای وارد عمل شود و تغییرات اعمال‌شده توسط آن را ببینید. همچنین می‌توانید میدل‌ویرهای ModelRouterMiddleware و AutoModeMiddleware را راه‌اندازی کنید و تعیین کنید چه داده‌هایی به مدل‌های تصمیم‌گیر آن‌ها ارسال شود.

دو نوع گاردریل

گاردریل (Guardrail): بررسی و اعتبارسنجی‌ای که درون ایجنت اجرا می‌شود و درخواست، پاسخ یا فراخوانی ابزار (Tool call) را تغییر می‌دهد، مسدود می‌کند یا روند آن را متوقف می‌سازد.

صفحه‌ی مستندات گاردریل‌ها به دو نوع گاردریل اشاره می‌کند {{docs oss/python/langchain/guardrails}}. گاردریل قطعی (Deterministic guardrail) از قواعدی مانند عبارت باقاعده (Regular expression) استفاده می‌کند. این روش سریع و تکرارپذیر است، اما مواردی را که در قاعده‌اش تعریف نشده باشند جا می‌اندازد. گاردریل مبتنی بر مدل (Model-based guardrail) برای ارزیابی از یک مدل یا دسته‌بند کمک می‌گیرد و هزینه‌ی یک فراخوانی را دارد.

در langchain، میدل‌ویر PIIMiddleware همان گاردریل قطعی است. میدل‌ویر HumanInTheLoopMiddleware تصمیم‌گیری را به انسان می‌سپارد و در بخش 6.5 به آن پرداخته شده است. دو میدل‌ویر تصمیم‌گیری که در ادامه می‌آیند نیز مبتنی بر مدل هستند.

میدل‌ویر PIIMiddleware

میدل‌ویر داده‌های حساس (PIIMiddleware): میدل‌ویری که یک نوع مشخص از داده‌های حساس فردی را در پیام‌ها پیدا می‌کند و روی هر مورد منطبق، یک راهبرد مشخص را اعمال می‌نماید.

هر نمونه (Instance) یک نوع داده را مدیریت می‌کند: email، credit_card، ip، mac_address، url، یا نوعی دلخواه به کمک یک آشکارساز (detector) از خودتان {{code libs/langchain_v1/langchain/agents/middleware/pii.py}}. برای هر نوع داده از یک نمونه استفاده کنید. نام‌گذاری هر نمونه به‌صورت PIIMiddleware[<type>] است؛ بنابراین دو نمونه از یک نوع داده با یکدیگر تداخل خواهند داشت. مقادیر پیش‌فرض آن مشخص می‌کنند در چه مراحلی وارد عمل شود:

گزینه پیش‌فرض مرحله‌ی اجرا
apply_to_input True روی تازه‌ترین پیام کاربر، در before_model
apply_to_output False روی تازه‌ترین پیام هوش مصنوعی، در after_model
apply_to_tool_results False روی پیام‌های ابزارِ پس از تازه‌ترین پیام هوش مصنوعی، در before_model
strategy redact اقدام لازم در برخورد با داده‌های منطبق

این میدل‌ویر پیام را در وضعیت (State) تغییر می‌دهد؛ بنابراین چک‌پوینت (Checkpoint) و ردگیری محاسبات (Trace) نیز متن تغییریافته را در خود نگه می‌دارند. پکیج آزمایشی این دوره یک ورودی حاوی چهار نوع داده‌ی مختلف را هربار از یک میدل‌ویر عبور می‌دهد. تصویر نتایج را در کنار هم نشان می‌دهد.

چهار استراتژی PII روی یک ورودیاستراتژی‌های redact و hash بخش منطبق را جایگزین می‌کنند، mask چهار رقم آخر کارت را نگه می‌دارد، و block پیش از هرگونه فراخوانی مدل استثنا صادر می‌کند.
چهار استراتژی PII روی یک ورودی یک پیام کاربر حاوی یک نشانی ایمیل، شماره کارت، نشانی IP و یک URL است که زیر هرکدام با رنگ ردیف متناظر خط کشیده شده است. پنج ردیف هرکدام یک PIIMiddleware را اجرا کردند. فیلتر email با redact عبارت «ada@example.com» را به «[REDACTED_EMAIL]» تبدیل کرد. فیلتر credit_card با mask عبارت «4111 1111 1111» را به «**** **** ****» تبدیل کرد. فیلتر ip با hash مقدار «192.168.1.20» را به «<ip_hash:55235459>» تبدیل کرد. فیلتر url با redact عبارت «https://example.com/x» را به «[REDACTED_URL]» تغییر داد. فیلتر email با block خطای PIIDetectionError صادر کرد («Detected 1 instance(s) of email in text content») و مدل 0 فراخوانی داشت. سایر اجراها هرکدام 1 فراخوانی مدل داشتند و فقط اسپن منطبق‌شده از جدیدترین پیام کاربر تغییر کرد. پیام کاربر 1 2 ایمیل ada@example.com، کارت 4111 1111 1111 1111، 3 4 از 192.168.1.20، ببینید https://example.com/x PIIMIDDLEWARE اسپن منطبق تبدیل می‌شود به فراخوانی مدل 1 'email' strategy='redact' ada@example.com [REDACTED_EMAIL] 1 2 'credit_card' strategy='mask' 4111 1111 1111 **** **** **** 1 3 'ip' strategy='hash' 192.168.1.20 <ip_hash:55235459> 1 4 'url' strategy='redact' https://example.com/x [REDACTED_URL] 1 5 'email' strategy='block' PIIDetectionError Detected 1 instance(s) of email in text content 0 هر ردیف یک اجرا است. خاکستری: ورودی اصلی. پررنگ: ذخیره و ارسال‌شده به‌جای آن. Only the newest human message changed, because apply_to_input is the default.
هر ردیف نشان‌دهنده‌ی یک‌بار اجرای کیت با یک PIIMiddleware است. ستون سمت چپ تنظیمات را نشان می‌دهد و ستون سمت راست متن دریافت‌شده توسط مدل یا خطا را نمایش می‌دهد. برگرفته از capture/out/14-mw-pii.txt.
پیام کاربر پس از اعمال ('PIIMiddleware('credit_card', strategy='mask capture/out/14-mw-pii.txt
    "content": "Mail ada@example.com, card **** **** **** 1111, from 192.168.1.20, see https://example.com/x",

راهبرد hash نام نوع داده را در کنار یک هش کوتاه می‌نویسد؛ مثلاً <ip_hash:55235459>. نشانی‌های یکسان خروجی هش برابری دارند؛ به این ترتیب مدل بدون دیدن مقادیر می‌تواند دو مقدار را از یکدیگر تشخیص دهد. راهبرد block پیش از فراخوانی مدل، خطا ایجاد می‌کند:

PIIMiddleware('email', strategy='block') capture/out/14-mw-pii.txt
raised langchain.agents.middleware._redaction.PIIDetectionError: Detected 1 instance(s) of email in text content

model calls, as the model received them:
[]

لاگ مدل پس از وقوع خطا خالی است.

آشکارساز سفارشی می‌تواند یک عبارت باقاعده یا یک تابع باشد. این پکیج کلیدهایی را که با الگوی sk-[a-z0-9]{8} همخوانی دارند پاک‌سازی می‌کند:

یک آشکارساز سفارشی capture/s_middleware.py
        middleware=[PIIMiddleware("api_key", detector=r"sk-[a-z0-9]{8}", strategy="redact")], inp=ask("my key is sk-abcd1234"), first=0)

مدل عبارت my key is [REDACTED_API_KEY] را دریافت کرد و در پاسخ گفت که کلید پاک‌سازی شده است. با تنظیم apply_to_output=True، از مدل خواسته شد عبارت .Write to grace@example.org را برگرداند. این پاسخ در وضعیت ذخیره‌شده به .Write to [REDACTED_EMAIL] تبدیل شد.

در هر چهار اجرا روی ورودی، مدل Qwen3 4B یک پاسخ یکسان برگرداند: .I'm sorry, but I can't assist with that request. ورودی همچنان دربردارنده‌ی شماره کارت، نشانی یا نشانی وب بود و مدل از پاسخ‌دهی خودداری کرد. پاک‌سازی داده‌های حساس متن خوانده‌شده توسط مدل را تغییر می‌دهد، اما لزوماً درخواست را از نظر مدل امن جلوه نمی‌دهد.

در صفحه‌ی گاردریل‌ها، به یک مبدل استریم (Stream transformer) برای حالت apply_to_output=True اشاره شده است. این مبدل 128 نویسه‌ی آخر هر بلوک متنی را نگه می‌دارد تا موردی که بین تکه‌ها (Chunks) پخش شده باشد ارسال نشود {{docs oss/python/langchain/guardrails}}. این پکیج تست ارسال استریمی را با PIIMiddleware انجام نداده است. این تست در ویرایش بعدی ارائه خواهد شد و بخش 8.8 آن را فهرست کرده است.

مدل‌های تصمیم‌گیر

مدل تصمیم‌گیر (Decision model): کلاسی بر پایه‌ی BaseDecisionModel از ماژول langchain_core.decisions که به‌تازگی در langchain-core نسخه‌ی 1.8.0 معرفی شده است. این مدل به پرسش‌های دارای نوع (Typed) پاسخ می‌دهد؛ مثل انتخاب میان چند گزینه‌ی مشخص یا ارزیابی احتمال درستی یک گزاره.

بر اساس یادداشت‌های انتشار، هر دو میدل‌ویر تصمیم‌گیری به‌تازگی در langchain 1.5.0 معرفی شده‌اند و در مرحله‌ی آزمایشی (Beta) قرار دارند. صفحه‌ی میدل‌ویرهای پیش‌ساخته نیز هر دو را آزمایشی علامت زده است {{docs oss/python/langchain/middleware/built-in}}. در کد، ModelRouterMiddleware دکوراتور beta دارد و هنگام ساخت آن هشدار می‌دهد. در مقابل، میدل‌ویر AutoModeMiddleware عبارت آزمایشی را تنها در docstring خود آورده و هشداری صادر نمی‌کند {{code libs/langchain_v1/langchain/agents/middleware/auto_mode.py}}. افزون بر این، LangChain تنها برای OpenAI و Google مدل‌های تصمیم‌گیر دارد.

به همین دلیل، پکیج آزمایشی با نوشتن کلاسی حدوداً 34 خطی به نام OllamaDecisionModel این نیاز را برطرف می‌کند. این کلاس هر پرسش و وضعیت جاری را در حالت JSON برای Qwen3 4B می‌فرستد و پاسخ JSON را به یک جواب تایپ‌دار تبدیل می‌کند. پرسش‌های زیر مواردی هستند که میدل‌ویر ارسال کرده و پاسخ‌ها را مدل برگردانده است.

میدل‌ویر ModelRouterMiddleware

میدل‌ویر ModelRouterMiddleware در فاز before_agent یک پرسش چندگزینه‌ای مطرح می‌کند و مدل انتخابی را برای تمام فراخوانی‌های مدل در طول همان اجرا به کار می‌گیرد. پکیج آزمایشی دو گزینه‌ی fast و deep را در اختیار آن می‌گذارد. پرسش ارسالی بدین شکل بود:

پرسش ارسال‌شده توسط ModelRouterMiddleware capture/out/20-mw-decisions.txt
    "questions": {
      "model_route": {
        "type": "choice",
        "criteria": {
          "fast": "arithmetic and short answers",
          "deep": "long reasoning"
        },
        "instructions": "Pick the cheapest model that can answer."
      }
    }

مدل تصمیم‌گیر گزینه‌ی fast را برگزید؛ با احتمال 0.999 در برابر 0.001 برای گزینه deep. مسیر deep به مدل qwen3:8b اشاره داشت که اصلاً فراخوانی نشد. تنها فراخوانی مدل توسط مدلِ مسیر fast انجام شد، مدلی که به create_agent داده شده بود فراخوانی نشد و پاسخ نهایی در state["model_route"] ثبت گردید. در این اجرا هشدار LangChainBetaWarning: The middleware ModelRouterMiddleware is in beta. داده شد.

میدل‌ویر AutoModeMiddleware

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

این میدل‌ویر فراخوانی ابزار، توضیحات ابزار و تا 30 پیام اخیر را می‌فرستد {{code libs/langchain_v1/langchain/agents/middleware/auto_mode.py}}. برای یک فراخوانی مسدودشده، یک ToolMessage حاوی خطا ثبت می‌شود و ابزار اجرا نخواهد شد. ابزاری که در فهرست نیاورده باشید بدون هیچ سؤالی اجرا می‌شود. اگر مدل تصمیم‌گیر با خطا متوقف شود، خطا به سطح بالاتر می‌رود و ابزار اجرا نمی‌شود. این میدل‌ویر صرفاً مسدود می‌کند و هرگز موضوع را از انسان نمی‌پرسد.

پکیج آزمایشی ابزارهای delete_branch و add را فهرست کرده و از مدل می‌خواهد هر دو را در قالب یک پاسخ فراخوانی کند. مدل تصمیم‌گیر برای delete_branch احتمال 0.999 و برای add مقدار 0.0 را برگرداند:

یک فراخوانی مسدودشده و یک فراخوانی مجاز capture/out/20-mw-decisions.txt
    "type": "ToolMessage",
    "content": "The tool call `delete_branch` was blocked because it was classified as risky (probability: 1.00). The tool was not executed.",
    "name": "delete_branch",
…
    "tool_call_id": "<uuid-3>",
    "status": "error"
  },
  {
    "type": "ToolMessage",
    "content": "5",
    "name": "add",

دو ToolMessage. شناسه‌ها کوتاه شده‌اند.

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

تصویر این دو مسیر را رسم می‌کند. در پرسشی که مدل تصمیم‌گیر دریافت کرده، مقدار criteria برابر با null است:

پرسش ارسال‌شده توسط AutoModeMiddleware capture/out/20-mw-decisions.txt
    "is_risky": {
      "type": "noul",
…
      "criteria": null
    }

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

نحوه‌ی برخورد AutoModeMiddleware با یک فراخوانی ابزاریک فراخوانی ابزار فهرست‌شده با امتیاز 0.5 یا بالاتر، یک ToolMessage خطا دریافت می‌کند و هرگز اجرا نمی‌شود، و در صورت ارسال نکردن criteria، مقدار آن null فرستاده می‌شود.
نحوه‌ی برخورد AutoModeMiddleware با یک فراخوانی ابزار مدل دو فراخوانی ابزار می‌خواهد: delete_branch با نام main و add با 2 و 3. برای هر ابزار فهرست‌شده، AutoModeMiddleware پرسش بولی is_risky را همراه با دستورالعمل‌ها، فراخوانی ابزار، توصیف ابزار، حداکثر تا 30 پیام و criteria برابر با null از مدل تصمیم‌گیری می‌پرسد. امتیاز delete_branch برابر 0.999 شد (0.5 یا بالاتر)، بنابراین یک ToolMessage خطا گرفت و اجرا نشد. امتیاز add برابر 0.0 شد، پس اجرا شد و 5 بازگرداند. ابزاری که در فهرست نباشد بدون هیچ پرسشی اجرا می‌شود. AIMessage tool_calls delete_branch(main), add(2, 3) question is_risky, type noul instructions, tool_call, tool_description, حداکثر 30 پیام، criteria: null هر ابزار فهرست‌شده delete_branch: 0.999 0.5 یا بیشتر: خطای ToolMessage، ابزار اجرا نمی‌شود add: 0.0 زیر 0.5: ابزار اجرا می‌شود، ToolMessage 5 خطرناک مجاز a tool missing from tools= بدون پرسش از مدل تصمیم‌گیری اجرا می‌شود احتمالات، پاسخ‌های Qwen3 4B از طریق OllamaDecisionModel کیت هستند.
از فراخوانی ابزار در بالا بخوانید. کادر زرد رنگ پرسش ارسال‌شده به مدل تصمیم‌گیری به همراه فیلدهای آن است. کادر سرخ‌رنگ فراخوانی مسدودشده‌ی delete_branch است و کادر سبز add است که اجرا شد. برگرفته از capture/out/20-mw-decisions.txt.

کلاس پیکربندی این میدل‌ویر معیارهای پیش‌فرضی دارد: ریسک‌آمیز یعنی آسیب‌رسانی، اقدامی فراتر از اجازه‌ی کاربر، افشای داده‌ها یا اثری بیرونی. سازنده‌ی کلاس به‌طور پیش‌فرض مقدار criteria=None را می‌گیرد و همان را انتقال می‌دهد؛ همین مقدار None جایگزین تنظیمات پیش‌فرض می‌شود {{code libs/langchain_v1/langchain/agents/middleware/auto_mode.py}}. بنابراین بدون آرگومان criteria، مدل تصمیم‌گیر دستورالعمل‌ها را بدون هیچ معیاری دریافت می‌کند. اگر مدل تصمیم‌گیر شما به این معیارها نیاز دارد، نمونه‌ای از NoulCriteria همراه با متن‌های مربوط به true و false را پاس بدهید.

منابع: capture/out/14-mw-pii.txt، capture/out/20-mw-decisions.txt، capture/s_middleware.py، capture/README.md؛ مستندات docs.langchain.com در commit مستندات به شماره‌ی 04d4d4a (بخش‌های oss/python/langchain/guardrails و oss/python/langchain/middleware/built-in)؛ فایل‌های libs/langchain_v1/langchain/agents/middleware/pii.py، auto_mode.py و model_router.py در langchain==1.5.0؛ و libs/core/langchain_core/decisions در langchain-core 1.8.0.