حواجز الحماية

بمجرد أن يكون لديك مساحة عمل ومفتاح API (انظر المقدمة)، فإن حواجز الحماية هي الطريقة التي تضع بها سياسة محتوى أمام كل نموذج. هذه الصفحة هي المرجع الكنسي لمحرك حواجز الحماية في OrcaRouter — ما هو، وكيفية استخدامه، وكيف يتكامل مع بقية البوابة.

1. ما هو محرك حواجز الحماية

حاجز الحماية هو سياسة محتوى مسمّاة ضمن نطاق مساحة العمل — قائمة مرتبة من القواعد تشغّلها البوابة على مدخلات الطلب ومخرجات النموذج. تحفظ حاجز حماية مرة واحدة، وتربط أي مفتاح API به (أو تضبط واحداً كافتراضي لمساحة العمل)، وتقوم البوابة بفحص كل استدعاء قبل النموذج الأعلى وبعده. كل قاعدة تقرر شيئاً واحداً — ماذا تبحث عنه (نوع القاعدة)، وأين تبحث (مرحلة: مدخلات الطلب أو مخرجات النموذج)، وماذا تفعل حيال ذلك (إجراء: block أو mask أو flag). يشغّل المحرك كل قاعدة منطبقة ويطوي النتائج في قرار واحد. تعديل حاجز الحماية يحدث أثره على كل مفتاح مرتبط به في الاستدعاء التالي. بدون إعادة نشر. بدون تغيير في الكود. بدون ترقية SDK. السياسة تعيش في البوابة، وليس في تطبيقك — يبقى تطبيقك يستدعي /v1/chat/completions تماماً كما كان. المحرك حتمي وخالٍ من التبعيات للأنواع المدمجة من القواعد: مطابقة سلاسل وregex نقية بدون أي استدعاء شبكي، آمنة للتشغيل على مسار الترحيل الساخن. القواعد المتقدمة (المزودون الخارجيون، LLM judge، الترسيخ السياقي) تستدعي خارجياً وتُرسَل بالتزامن بحيث لا يتسلسل فحص بطيء خلف آخر أبداً. حواجز الحماية ضمن نطاق مساحة العمل — كل عضو يرى حواجز حماية مساحة عمله؛ لا شيء يعبر حدود المستأجر.

2. البداية السريعة — افحص طلبك الأول في 5 خطوات

أنشئ حاجز حماية

في وحدة التحكم، انتقل إلى /console/guardrails وانقر New guardrail. سمّه pii-shield. أضف قاعدة واحدة:

النوع: كشف PII
المرحلة: Input (الطلب)
الإجراء: Mask — تنقيح المطابقة
الكيانات: email، phone، ssn

احفظ.

اختبره في الـ sandbox

افتح علامة التبويب Test داخل المحرر، الصق “email me at jane@acme.com”، اختر مرحلة input، وشغّل. يُظهر الـ sandbox الحكم والنص المُصيَّر — email me at [EMAIL] — دون إرسال أي شيء للأعلى.

اربط مفتاحاً

اذهب إلى /console/token، أنشئ أو حرّر مفتاح API، واختر pii-shield من قائمة Guardrail المنسدلة. يعيش الربط على المفتاح في البوابة.

أرسل طلباً

باستخدام ذلك المفتاح، استدعِ OrcaRouter تماماً كما كان من قبل:

curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Reply to jane@acme.com please"}
    ]
  }'

تُخفي البوابة البريد الإلكتروني إلى [EMAIL] قبل إعادة التوجيه. لا يرى النموذج الأعلى العنوان أبداً.

شدّد السياسة

عد إلى /console/guardrails، حرّر pii-shield — غيّر الإجراء على ssn إلى Block عبر تجاوز لكل كيان. احفظ. أول طلب لاحق يحتوي على SSN يُرفض بـ HTTP 400 guardrail_blocked. بدون أي تغيير في التطبيق.

تلك هي القيمة الرئيسية.

3. المفاهيم: حواجز الحماية، القواعد، المراحل، الإجراءات

المفهوم	التعريف
Guardrail	سياسة مسمّاة ضمن نطاق مساحة العمل. المعرّف: `name` (≤ 64 حرفاً). لها `enabled` و`is_default` وكتلة `rules` بصيغة JSON.
Rule	فحص واحد داخل سياسة: `type` و`stage` و`action`، بالإضافة إلى حقول خاصة بالنوع. تعمل القواعد بالترتيب.
Stage	`input` (الطلب)، أو `output` (استجابة النموذج)، أو `both`.
Action	`block` (رفض الاستدعاء)، أو `mask` (تنقيح المطابقة)، أو `flag` (تسجيل فقط — مراقبة دون تغيير حركة المرور).

النطاق والافتراضي لمساحة العمل

حواجز الحماية ضمن نطاق مطابق تماماً لمفاتيح API: مشتركة على مستوى مساحة العمل عندما يكون لديك مساحة عمل نشطة، ولكل مستخدم خلاف ذلك. الحل لأي طلب:

ربط المفتاح — إذا كان للمفتاح guardrail_id صريح، فإن ذلك الحاجز ينطبق (عندما يكون موجوداً ومفعّلاً). الربط الصريح لا يتراجع صامتاً أبداً؛ تعطيله هو مفتاح الإيقاف.
افتراضي مساحة العمل — إذا لم يكن للمفتاح ربط، ينطبق حاجز is_default المفعّل لمساحة العمل.
لا هذا ولا ذاك — لا تطبيق. الطلب متطابق بايت ببايت مع مساحة عمل لم تفعّل الميزة أبداً.

يمكن لحاجز حماية واحد على الأكثر لكل مساحة عمل أن يكون الافتراضي. ترقية افتراضي جديد يُنزّل القديم في نفس المعاملة.

Fail-open بالتصميم. إذا واجه حل حاجز الحماية خطأً عابراً (مثل عطل مؤقت في قاعدة البيانات)، تتدهور البوابة إلى لا تطبيق بدلاً من إسقاط حركة المرور. تتدهور السلامة؛ ويُحفظ التوفّر.

كيف يبدو الحجب

الطلب المحجوب يعيد HTTP 400 مع رمز الخطأ guardrail_blocked ورسالة تسمّي حاجز الحماية والقاعدة التي أُطلقت. الطلب المحجوب لا يكلّفك أي حصة — حجب مرحلة input يُطلق قبل قياس الاستخدام، وحجب مرحلة output يردّ الحصة المستهلكة مسبقاً — ويُعلَّم بـ skip-retry (إعادة تشغيل نفس المطالبة ستحجب مجدداً فحسب).

4. أنواع القواعد

تقع القواعد في مجموعتين: مدمجة (حتمية، بدون شبكة) ومتقدمة (تستدعي نموذجاً أو مزوداً خارجياً).

النوع	المجموعة	ماذا تفعل
قائمة حظر الكلمات المفتاحية (`keyword`)	مدمجة	تطابق أياً من قائمة من المصطلحات الحرفية — غير حساسة لحالة الأحرف، ومطابقة جزئية (بحيث يطابق `class` أيضاً `classic`).
التعبير النمطي (`regex`)	مدمجة	يطابق نمط RE2 (زمن خطي، بدون مراجع خلفية).
كشف PII (`pii`)	مدمجة	يكشف أنواع الكيانات المدمجة (وكياناتك المخصصة). انظر §5.
الطول الأقصى (`max_chars`)	مدمجة	يحدّ عدد أحرف النص في مرحلة ما.
مزود خارجي (`external`)	متقدمة	يفوّض الفحص إلى مزود متصل (Aporia، Averta، BYO-webhook، …). انظر §9.
LLM judge (`llm_judge`)	متقدمة	يشغّل فحصاً دلالياً مقابل نموذج في مساحة عملك. انظر §6.
الترسيخ السياقي (`grounding`)	متقدمة	يسجّل مدى أمانة الإجابة مقابل المصادر المسترجعة على الطلب (RAG). انظر §7.

يمزج حاجز الحماية أي عدد من القواعد من أي أنواع. القواعد المتقدمة (external، llm_judge، grounding) تُرسَل بالتزامن بحيث لا يتسلسل فحص بطيء خلف آخر.

5. كشف PII بالتفصيل

قاعدة pii تكشف الكيانات الحساسة وتطبّق إجراء القاعدة على كل مطابقة. مجموعة الكواشف المدمجة مغلقة ومشتركة بين المحرك، والمدقق، وباني القواعد: email، phone، credit_card، ssn، ip، iban، mac_address، api_key_openai، aws_access_key، jwt، bitcoin_address. عند إجراء mask، تُستبدل كل مطابقة بوسم مُصنّف — يصبح البريد الإلكتروني [EMAIL]، ويصبح SSN [SSN]، وهكذا.

الكيانات المخصصة

أضف طبقة كواشفك الخاصة فوق المجموعة المدمجة. الكيان المخصص هو:

name — أحرف ASCII صغيرة / أرقام / شرطة سفلية، يجب أن يبدأ بحرف (مثل employee_id). يتدفق إلى سجلات التدقيق والقياس عن بُعد دون اقتباس.
pattern — تعبير Go RE2 النمطي (زمن خطي، بدون مراجع خلفية).
checksum — اختياري؛ luhn يتحقق من المطابقة بخوارزمية Luhn (مثلاً للأرقام الشبيهة بالبطاقات).
mask_with — استبدال حرفي اختياري؛ الافتراضي [<UPPERCASE_NAME>].

حتى 25 كياناً مخصصاً لكل قاعدة (كل منها مسح regex على كامل النص، فالسقف يبقي المسار الساخن خطياً). الأنماط المُجمَّعة تُخزَّن مؤقتاً عبر الطلبات.

تجاوزات الإجراء لكل كيان

قاعدة PII واحدة يمكنها تطبيق إجراءات مختلفة على كيانات مختلفة عبر entity_actions. قاعدة واحدة تُخفي emails / phones / IPs افتراضياً لكنها تحجب على credit_card أو ssn — بدلاً من ثلاث قواعد متداخلة:

{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}

يجب أن تكون المفاتيح كياناً مفعّلاً على القاعدة؛ ويجب أن تكون القيم block / mask / flag. يرفض المدقق أي شيء آخر.

6. LLM judge

قاعدة llm_judge تشغّل فحصاً دلالياً مقابل نموذج تستطيع مساحة عملك استدعاءه أصلاً. استخدمها للسياسات الضبابية التي لا يلتقطها أي regex — السُّمية، التحرش، الخروج عن الموضوع، نية حقن المطالبات.

الحقل	المعنى
`judge_model`	النموذج أو اسم موجه مستعار للتقييم به (مثل `gpt-4o-mini`، `orcarouter/cheap`). يُحَل مقابل قنوات مساحة عملك.
`judge_rubric`	رسالة النظام التي تصف ما يجب تعليمه.
`judge_format`	إحدى القيم `yes_no` أو `score` أو `category` (مطلوب؛ تختار وحدة التحكم `yes_no` مسبقًا).
`judge_threshold`	لـ `score`: احجب/علّم عندما تكون الدرجة عند هذه القيمة أو أعلى.
`judge_categories`	لـ `category`: القائمة المرفوضة.
`judge_timeout_ms`	يحدّ استدعاء الـ judge. `0` ← افتراضي المحرك.
`judge_fail_open`	`true` (الافتراضي) ← خطأ الـ judge يُلاحَظ لكن الطلب يستمر؛ `false` ← عامل الخطأ/المهلة كحجب.

استدعاء الـ judge يمر عبر قنوات مساحة عملك، لذا تُفوتر رموزه وتُنسب كأي استدعاء آخر (كسطر فرعي للـ judge). يُلحق المحرك ملحق JSON-schema بمعيارك بحيث يعيد النموذج مخرجات قابلة للتحليل.

7. الترسيخ السياقي

قاعدة grounding تقيس إجابة المساعد مقابل المصادر المسترجعة على الطلب (سياق RAG الخاص بك) وتعلّم أو تحجب الإجابات غير الأمينة لها. تعيد استخدام وصلة الـ judge — نفس قنوات مساحة العمل، نفس نسب التكلفة.

الحقل	الافتراضي	المعنى
`grounding_model`	اختيار مساحة العمل	النموذج الذي يحل إليه المشغّل فحص الأمانة.
`grounding_rubric`	مدمج	يتجاوز معيار الأمانة الافتراضي.
`grounding_threshold`	`0.7`	أرضية الأمانة، `0.0`–`1.0`. تحتها، يُطلق الإجراء.
`grounding_strict`	`false`	عندما يكون `true`، تُعامَل “no sources provided” كحجب (مقابل السماح الافتراضي).
`grounding_max_bytes`	`100000`	يحدّ سياق المصدر المُسلسل المُسلَّم للـ judge.
`grounding_timeout_ms`	`3000`	يحدّ استدعاء الـ judge.

8. القوالب، الـ sandbox، وأداة التقييم

مكتبة القوالب

زر New guardrail المنقسم يفتح مباشرة في قالب، والمكتبة الكاملة على بُعد نقرة واحدة. الإعدادات المسبقة مكتوبة من جانب الخادم بحيث تصف وحدة التحكم، والـ sandbox، وهذه المستندات السلوك نفسه بالضبط. تشمل الفئات:

PII (pii) — PII Shield، PII Blocker (صارم)، Contact-Info Redactor، response PII redactor.
الأسرار (secrets) — حواجز اعتماد AWS / OpenAI / GitHub، المفاتيح الخاصة ورموز السحابة، محافظ العملات المشفرة، الأسرار في المُخرجات.
الامتثال (compliance) — GDPR (PII الاتحاد الأوروبي)، PCI (حجب كامل للبطاقات)، HIPAA (PHI)، البيانات المالية، مُسجّل الامتثال، فرض إخلاء المسؤولية القانوني.
العلامة التجارية (brand) — الألفاظ النابية (block / mask / متعدد اللغات)، ذكر المنافسين، كلمات سلامة الأطفال المفتاحية.
الأمان (safety) — حقن المطالبات، jailbreak، تسريب رسالة النظام، إيذاء النفس.
التكلفة (cost) — سقوف حجم المطالبة/الاستجابة وسقوف الرموز.
الوكيل (agent) — مرشحات URL، صور markdown، استدعاء أدوات shell، وحقن SQL في المُخرجات.

طبّق إعداداً مسبقاً كنقطة انطلاق، ثم حرّر بحرية — الإعداد المسبق بذرة، وليس قفلاً.

الـ sandbox الاختباري

لكل محرر علامة تبويب Test. الصق عينة، اختر مرحلة، وشغّل السياسة الحالية محلياً — بدون استدعاء للأعلى، بدون حصة. يعيد الـ sandbox الحكم و(لقواعد mask) النص المُصيَّر، حتى تثبت أن قاعدة تفعل ما تتوقعه قبل ربط مفتاح.

أداة التقييم / الفريق الأحمر

علامة التبويب Eval تشغّل حاجز حماية مقابل مجموعة من المدخلات وتُبلّغ عن نتيجته — مفيدة لضبط معيار judge أو إثبات أن سياسة تلتقط هجمات معروفة قبل أن تشحنها.

المجموعات المُرفقة تأتي مع البوابة — مجموعات عدائية وفريق أحمر (مطالبات سلوك ضار، حقن أدوات، فريق أحمر متعدد اللغات) بالإضافة إلى مجموعات حميدة لقياس الإيجابيات الكاذبة.
المجموعات المخصصة — ارفع JSONL الخاص بك للاختبار مقابل أشكال حركة المرور الحقيقية لديك.
التشغيلات مدرجة مع نتائجها؛ افتح تشغيلاً لفحص حالات الفشل عينة بعينة.

9. المزودون الخارجيون

قاعدة external تفوّض الفحص إلى مزود متصل. اتصل بمزود مرة واحدة تحت Integrations (زر الدعوة للإجراء في رأس صفحة Guardrails)، ثم أشِر إلى الاتصال من قاعدة.

المزودون المدعومون

المزود	ما هو
Aporia Guardrails (`aporia`)	محرك سياسات قائم على مجموعة SLM للمطالبات والاستجابات.
Averta (`averta`)	نقطة نهاية مصنِّف SLM عامة (POST نص ← آمن / غير آمن + إعادة صياغة اختيارية).
BYO Webhook (`webhook`)	URL خاص بك — يستقبل المطالبات ويعيد أحكام سماح / حجب / إخفاء / تعليم.

يأخذ Aporia وAverta عنوان URL أساسياً + مفتاح API؛ ويأخذ الـ webhook عنوان URL + ترويسة مصادقة + سر HMAC.

حقول القاعدة

الحقل	المعنى
`connection_id`	التكامل المتصل المراد استخدامه (المسار الموصى به — يُحَل المزود + الأسرار من تكامل مساحة العمل وقت التشغيل).
`timeout_ms`	يحدّ استدعاء المزود الواحد. `0` ← الافتراضي.
`fail_open`	`true` (الافتراضي) ← خطأ المزود يُلاحَظ لكن الطلب يستمر؛ `false` ← عامل خطأ النقل / المهلة / المزود المجهول كحجب.

تُخزَّن الأسرار مشفّرة ومقنّعة عند القراءة. يحمل استدعاء الفحص إلغاء طلب الترحيل، بحيث لا يترك طلب مُلغى استدعاء مزود معلّقاً.

10. القابلية للملاحظة

تترك حواجز الحماية آثاراً يمكنك التصرف بناءً عليها.

تغذية المطابقات

كل قاعدة تُطلق تسجّل مطابقة — نوع القاعدة، الإجراء، سلسلة تفصيل، المرحلة، و(عند التفعيل) السلسلة الفرعية المطابقة. علامة التبويب Matches على صفحة Guardrails هي التغذية على مستوى مساحة العمل: سرد، تجميع، تصفية، التعمق في مطابقة واحدة، التصدير إلى CSV، ووسم الإيجابيات الكاذبة.

التقاط المحتوى الخام اختياري. مفتاح Log raw content لحاجز الحماية مُطفأ افتراضياً — الموقف المحافظ على الخصوصية. مع إطفائه، تسجّل تغذية المطابقات أن قاعدة أُطلقت وسلسلة التفصيل الوصفية الخاصة بها، لكن ليس السلسلة الفرعية المطابقة الفعلية (مثل عنوان البريد الإلكتروني نفسه). فعّله لكل حاجز حماية عندما تحتاج السلسلة الفرعية للفرز؛ الإعداد غير رجعي.

الإحصائيات

تشغّل تغذية المطابقات إحصائيات لكل حاجز حماية — تُظهر كل بطاقة حاجز خطاً بيانياً مصغراً للمطابقات على 7 أيام وعداداً، وتحمل علامة التبويب Matches إجمالي مساحة العمل. لتشريح النشاط حسب السياسة، استخدم العرض المجمّع لتغذية المطابقات ومرشحاتها (حسب حاجز الحماية، نوع القاعدة، الإجراء) — فهناك يعيش الاستخدام لكل حاجز حماية، ومزيج الإجراءات، ومعدل الإيجابيات الكاذبة.

تاريخ الإصدارات والتدقيق

كل إنشاء وتحديث وحذف يكتب صف تاريخ مُصدَّر في نفس معاملة التغيير. افتح History على صف حاجز حماية لـ:

رؤية كل إصدار مع من غيّره ومتى.
Diff أي إصدارين.
Revert إلى إصدار أقدم (يُسجَّل كإصدار جديد — لا يُعدَّل التاريخ أبداً).

11. العلاقة مع بقية البوابة

السطح	كيف يتكامل مع Guardrails؟
Models	حواجز الحماية محايدة للنموذج. نفس السياسة تركب على GPT-5 وClaude وGemini — تفحص النص، وليس اختيار النموذج.
Routing	مستقل. يقرر التوجيه أي نموذج/قناة تخدم الطلب؛ بينما تفحص حواجز الحماية نص الطلب/الاستجابة نفسه بغض النظر عن ذلك ولا تتجاوز أبداً اختيار النموذج. يجري فحص input قبل الاستدعاء الأمامي، وفحص output بعد أن يستجيب النموذج. وتحل قواعد judge وgrounding نموذجها الخاص عبر قنوات مساحة عملك، بشكل منفصل عن توجيه الطلب.
Prompts	مستقلان ومتكاملان. المطالبات تحقن رسالة نظام؛ وحواجز الحماية تفحص المحتوى وتبوّبه. يمكن أن ينطبق كلاهما على طلب واحد وتعمل حواجز الحماية دائماً. الترتيب مهم: تفحص قواعد input طلب المستدعي قبل حقن مطالبة من السجل (يحدث الحقن لاحقاً، في مرحلة التوجيه)، لذا ترى قواعد input رسائل المستدعي وليس مطالبة النظام المحقونة؛ أما قواعد output فتفحص استجابة النموذج في الحالتين.
API Keys	يرتبط المفتاح بحاجز حماية عبر `guardrail_id`. يعيش الربط على المفتاح في البوابة، لذا فإن تعديل حاجز الحماية ينقل كل مفتاح مرتبط دفعة واحدة؛ عدم وجود ربط يتراجع إلى افتراضي مساحة العمل.
تغذية المطابقات	كل قاعدة تُطلق تهبط في تغذية المطابقات لمساحة العمل (مخزنها الخاص، منفصل عن سجل الطلب). جمّعها وصفّها حسب حاجز الحماية، ونوع القاعدة، والإجراء لرؤية الاستخدام، ومزيج الإجراءات، ومعدل الإيجابيات الكاذبة لكل حاجز حماية.

12. مرجع API

جميع المسارات ضمن نطاق مساحة العمل عبر رأس X-Workspace-Id. يُفرض RBAC باستمرار: القراءات والـ sandbox الاختباري مفتوحة لكل عضو؛ الكتابات تتطلب Developer+ (وصلاحية guardrails:write)؛ تغييرات حركة الإنتاج (الحذف، التراجع، تكوين المزود) مبوّبة وفقاً لذلك.

حواجز الحماية

الطريقة والمسار	الدور	الغرض
`GET /api/guardrail/`	Member	قائمة حواجز الحماية (مع عدد المفاتيح المرتبطة).
`GET /api/guardrail/meta`	Member	مفردات المحرك — أنواع القواعد، المراحل، الإجراءات، كيانات PII، الإعدادات المسبقة، فئات الإعدادات المسبقة.
`GET /api/guardrail/my-permissions`	Member	صلاحيات حواجز الحماية للمستدعي (لتبويب الواجهة).
`GET /api/guardrail/:id`	Member	تفاصيل حاجز حماية واحد.
`GET /api/guardrail/:id/tokens`	Member	مفاتيح API المرتبطة بهذا الحاجز (محدودة، مع الإجمالي الحقيقي).
`POST /api/guardrail/test`	Member	الـ sandbox — تقييم سياسة على نص عينة في مرحلة. لا يُحفظ شيء.
`POST /api/guardrail/`	Developer+	إنشاء حاجز حماية.
`PUT /api/guardrail/`	Developer+	تحديث حاجز حماية (يكتب إصدار تاريخ جديداً).
`DELETE /api/guardrail/:id`	Developer+	حذف حاجز حماية.

التاريخ

الطريقة والمسار	الدور	الغرض
`GET /api/guardrail/:id/history`	Member	تاريخ الإصدارات (الأحدث أولاً).
`GET /api/guardrail/:id/history/diff`	Member	Diff إصدارين.
`GET /api/guardrail/:id/history/:version`	Member	إصدار تاريخي واحد.
`POST /api/guardrail/:id/revert`	Developer+	استعادة إصدار أقدم كإصدار جديد.

التقييم والمجموعات

الطريقة والمسار	الدور	الغرض
`POST /api/guardrail/:id/eval`	Member	تشغيل تقييم على مجموعة (اسم مُرفق أو JSONL مرفوع).
`GET /api/guardrail/:id/eval/runs`	Member	قائمة تشغيلات التقييم لحاجز حماية (مُرقَّمة الصفحات).
`GET /api/guardrail/eval/runs/:run_id`	Member	تفاصيل تشغيل تقييم واحد.
`GET /api/guardrail/eval/corpora`	Member	قائمة مجموعات مساحة العمل + المجموعات المُرفقة.
`POST /api/guardrail/eval/corpora`	Developer+	رفع مجموعة JSONL.
`GET /api/guardrail/eval/corpora/:id`	Member	تفاصيل المجموعة.
`DELETE /api/guardrail/eval/corpora/:id`	Developer+	حذف مجموعة.

المطابقات

الطريقة والمسار	الدور	الغرض
`GET /api/guardrail/match`	Member	قائمة المطابقات (ضمن نطاق مساحة العمل).
`GET /api/guardrail/match/grouped`	Member	المطابقات مجمّعة (مثلاً حسب القاعدة أو حاجز الحماية).
`GET /api/guardrail/match/stats`	Member	إحصائيات المطابقات (يدعم `?days=` و`?group_by=`).
`GET /api/guardrail/match/export`	Member	تصدير المطابقات كـ CSV.
`GET /api/guardrail/match/:id`	Member	تفاصيل مطابقة واحدة.
`POST /api/guardrail/match/:id/mark-fp`	Admin	وسم مطابقة كإيجابية كاذبة (rate-limited).
`DELETE /api/guardrail/match/:id/mark-fp`	Admin	إلغاء وسم إيجابية كاذبة (rate-limited).

ربط مفتاح

اضبط guardrail_id على مفتاح API (عبر محرر المفتاح أو واجهة token البرمجية). 0/null يعني لا ربط صريح — يتراجع المفتاح إلى حاجز الحماية الافتراضي لمساحة العمل، إن كان مضبوطاً.

13. الأسئلة الشائعة

ماذا لو لم يُحل أي حاجز حماية على طلب؟

السلوك متطابق بايت ببايت مع مساحة عمل لم تفعّل الميزة أبداً. إذا لم يكن المفتاح مرتبطاً ولم يُضبط افتراضي لمساحة العمل، فإن البوابة لا تجري أي تعديلات. لا يُحجب ولا يُخفى ولا يُسجَّل شيء في تغذية المطابقات.

هل يكلّف الطلب المحجوب حصة؟

لا. حجب مرحلة input يُطلق قبل قياس الاستخدام؛ وحجب مرحلة output يردّ الحصة المستهلكة مسبقاً بعد رفض الاستجابة. في كلتا الحالتين لا يدفع المستدعي أي حصة، ويحصل على HTTP 400 guardrail_blocked، ويُعلَّم الطلب بـ skip-retry (إعادة تشغيل نفس المطالبة مقابل قناة أخرى ستحجب مجدداً فحسب).

هل تُفرض قواعد المخرجات (الاستجابة) على البث؟

يعتمد ذلك على الإجراء. يُفرض Block بكلا الطريقتين: على الاستجابة غير المبثوثة تُفحص الإجابة قبل إرجاعها، وعلى الاستجابة المبثوثة يقطع ماسح البث التدفق في منتصفه ويصدر رسالة بديلة قبل أن يصل أي محتوى محجوب إلى العميل. أما Mask على المخرجات فينطبق حالياً على الاستجابات غير المبثوثة فقط — على الاستجابة المبثوثة يمر الجزء الأصلي دون إخفاء (إعادة كتابة التدفق ضمن المسار تحسين مخطط له). للإخفاء على المخرجات اليوم، استخدم طلبات غير مبثوثة أو اعتمد على الإخفاء في مرحلة المدخلات (input). أثبت مجموعة المرحلة/البث المحددة لديك في الـ sandbox وبتشغيل تقييم قبل الاعتماد عليها.

ما الفرق بين mask وblock؟

Mask ينقّح المطابقة (مثل jane@acme.com ← [EMAIL]) ويمرر الطلب بالنص المُنقّى — لا يرى النموذج الأعلى الأصل أبداً. Block يرفض الطلب بأكمله بـ HTTP 400. Flag لا يغيّر شيئاً في حركة المرور ويسجّل مطابقة فقط — استخدمه لقياس قاعدة قبل فرضها.

هل تُحاسب رموز المطالبات المحقونة ورموز الـ judge؟

القاعدة المدمجة (keyword / regex / PII / max_chars) لا تجري أي استدعاء نموذج ولا تحاسب شيئاً. قاعدة llm_judge أو grounding تستدعي نموذجاً عبر قنوات مساحة عملك، لذا تُفوتر تلك الرموز وتُنسب كسطر فرعي للـ judge.

كيف أرى ما طابقته قاعدة فعلاً؟

فعّل Log raw content لحاجز الحماية. مع إطفائه (الافتراضي)، تسجّل تغذية المطابقات أن قاعدة أُطلقت وسلسلة التفصيل الوصفية الخاصة بها لكن ليس السلسلة الفرعية المطابقة — الموقف المحافظ على الخصوصية. المفتاح غير رجعي: يؤثر فقط على المطابقات المسجّلة بعد تفعيله.

هل يمكنني التراجع عن تغيير في حاجز حماية؟

نعم. افتح History على حاجز الحماية، قارن الإصدارات بـ diff، وRevert إلى الإصدار الذي تريده. ينسخ Revert محتوى ذلك الإصدار إلى الأمام كإصدار جديد — لا يُعدَّل التاريخ أبداً — ويحدث التغيير أثره في الطلب التالي.

ماذا يحدث إذا انتهت مهلة مزود خارجي أو judge؟

افتراضياً، تتبع القواعد المتقدمة fail open: تُسجَّل المهلة أو خطأ النقل كقياس عن بُعد ويستمر الطلب. اضبط fail_open (external) أو judge_fail_open (judge) إلى false لـ fail closed — معاملة الخطأ كحجب — للسياسات التي يكون فيها فحص فائت غير مقبول.

​1. ما هو محرك حواجز الحماية

​2. البداية السريعة — افحص طلبك الأول في 5 خطوات

​3. المفاهيم: حواجز الحماية، القواعد، المراحل، الإجراءات

​النطاق والافتراضي لمساحة العمل

​كيف يبدو الحجب

​4. أنواع القواعد

​5. كشف PII بالتفصيل

​الكيانات المخصصة

​تجاوزات الإجراء لكل كيان

​6. LLM judge

​7. الترسيخ السياقي

​8. القوالب، الـ sandbox، وأداة التقييم

​مكتبة القوالب

​الـ sandbox الاختباري

​أداة التقييم / الفريق الأحمر

​9. المزودون الخارجيون

​المزودون المدعومون

​حقول القاعدة

​10. القابلية للملاحظة

​تغذية المطابقات

​الإحصائيات

​تاريخ الإصدارات والتدقيق

​11. العلاقة مع بقية البوابة

​12. مرجع API

​حواجز الحماية

​التاريخ

​التقييم والمجموعات

​المطابقات

​ربط مفتاح

​13. الأسئلة الشائعة

1. ما هو محرك حواجز الحماية

2. البداية السريعة — افحص طلبك الأول في 5 خطوات

3. المفاهيم: حواجز الحماية، القواعد، المراحل، الإجراءات

النطاق والافتراضي لمساحة العمل

كيف يبدو الحجب

4. أنواع القواعد

5. كشف PII بالتفصيل

الكيانات المخصصة

تجاوزات الإجراء لكل كيان

6. LLM judge

7. الترسيخ السياقي

8. القوالب، الـ sandbox، وأداة التقييم

مكتبة القوالب

الـ sandbox الاختباري

أداة التقييم / الفريق الأحمر

9. المزودون الخارجيون

المزودون المدعومون

حقول القاعدة

10. القابلية للملاحظة

تغذية المطابقات

الإحصائيات

تاريخ الإصدارات والتدقيق

11. العلاقة مع بقية البوابة

12. مرجع API

حواجز الحماية

التاريخ

التقييم والمجموعات

المطابقات

ربط مفتاح

13. الأسئلة الشائعة