میدلویر
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) نیز متن تغییریافته را در خود نگه میدارند. پکیج آزمایشی این دوره یک ورودی حاوی چهار نوع دادهی مختلف را هربار از یک میدلویر عبور میدهد. تصویر نتایج را در کنار هم نشان میدهد.
"content": "Mail ada@example.com, card **** **** **** 1111, from 192.168.1.20, see https://example.com/x",راهبرد hash نام نوع داده را در کنار یک هش کوتاه مینویسد؛ مثلاً <ip_hash:55235459>. نشانیهای یکسان خروجی هش برابری دارند؛ به این ترتیب مدل بدون دیدن مقادیر میتواند دو مقدار را از یکدیگر تشخیص دهد. راهبرد block پیش از فراخوانی مدل، خطا ایجاد میکند:
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} همخوانی دارند پاکسازی میکند:
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 را در اختیار آن میگذارد. پرسش ارسالی بدین شکل بود:
"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 را برگرداند:
"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 است:
"is_risky": {
"type": "noul",
…
"criteria": null
}دستورالعملها بعد از جملهی اول بریده شدهاند.
کلاس پیکربندی این میدلویر معیارهای پیشفرضی دارد: ریسکآمیز یعنی آسیبرسانی، اقدامی فراتر از اجازهی کاربر، افشای دادهها یا اثری بیرونی. سازندهی کلاس بهطور پیشفرض مقدار 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.