لمزيد من التعليمات التفصيلية، راجع [دليل التثبيت](https://docs.nvidia.com/nemo/guardrails/get-started/installation-guide).

## نظرة عامة

<!-- start-documentation-reuse -->

تُمكّن مكتبة NeMo Guardrails المطورين الذين يبنون تطبيقات قائمة على LLM من إضافة **حواجز قابلة للبرمجة** بين كود التطبيق وLLM.

<div align="center">
  <img src="https://raw.githubusercontent.com/NVIDIA-NeMo/Guardrails/develop/docs/_static/images/programmable_guardrails.png"  width="75%" alt="Programmable Guardrails">
</div>

تشمل الفوائد الرئيسية لإضافة *حواجز قابلة للبرمجة* ما يلي:

- **بناء تطبيقات LLM موثوقة وآمنة ومحمية:** يمكنك تعريف حواجز لتوجيه المحادثات وحمايتها؛ يمكنك اختيار تعريف سلوك تطبيقك القائم على LLM في موضوعات محددة ومنعه من الانخراط في مناقشات حول موضوعات غير مرغوب فيها.

- **ربط النماذج والسلاسل والخدمات الأخرى بشكل آمن:** يمكنك ربط LLM بخدمات أخرى (المعروفة أيضًا بالأدوات) بسلاسة وأمان.

- **حوار قابل للتحكم**: يمكنك توجيه LLM لاتباع مسارات محادثة محددة مسبقًا، مما يتيح لك تصميم التفاعل وفقًا لأفضل ممارسات تصميم المحادثات وتطبيق إجراءات التشغيل القياسية (مثل المصادقة والدعم).

<!-- end-documentation-reuse -->

### الحماية من ثغرات LLM

توفر مكتبة NeMo Guardrails عدة آليات لحماية تطبيق محادثة مدعوم بـ LLM من ثغرات LLM الشائعة، مثل كسر الحماية وحقن الأوامر. فيما يلي نظرة عامة نموذجية على الحماية التي توفرها تكوينات الحواجز المختلفة للمثال [ABC Bot](https://github.com/nvidia-nemo/guardrails/blob/develop/examples/bots/abc) المضمّن في هذا المستودع. لمزيد من التفاصيل، يُرجى الرجوع إلى صفحة [فحص ثغرات LLM](https://docs.nvidia.com/nemo/guardrails/evaluation/llm-vulnerability-scanning.html).

<div align="center">
<img src="https://raw.githubusercontent.com/NVIDIA-NeMo/Guardrails/develop/docs/_static/images/abc-llm-vulnerability-scan-results.png" width="500">
</div>

### حالات الاستخدام

يمكنك استخدام الحواجز القابلة للبرمجة في أنواع مختلفة من حالات الاستخدام:

1. **الإجابة على الأسئلة** عبر مجموعة من المستندات (المعروفة أيضًا بالتوليد المعزز بالاسترجاع): فرض التحقق من الحقائق ومراقبة المخرجات.
2. **المساعدون المتخصصون في مجال معين** (المعروفون أيضًا بروبوتات المحادثة): ضمان بقاء المساعد في صلب الموضوع واتباعه لمسارات المحادثة المصممة.
3. **نقاط نهاية LLM**: إضافة حواجز إلى LLM المخصص الخاص بك لتفاعل أكثر أمانًا مع العملاء.
4. **سلاسل LangChain** (اختياري): إذا كنت تستخدم LangChain لأي حالة استخدام، يمكنك إضافة طبقة حواجز حول سلاسلك. لتمكين هذا التكامل، اضبط متغير البيئة `NEMOGUARDRAILS_LLM_FRAMEWORK=langchain` أو استدعِ `set_default_framework("langchain")`.

### الاستخدام

لإضافة حواجز قابلة للبرمجة إلى تطبيقك، يمكنك استخدام واجهة برمجة تطبيقات Python أو خادم الحواجز (راجع [دليل الخادم](https://docs.nvidia.com/nemo/guardrails/get-started/integrate-into-application) لمزيد من التفاصيل). استخدام واجهة برمجة تطبيقات Python مشابه لاستخدام LLM مباشرةً. يتطلب استدعاء طبقة الحواجز بدلاً من LLM تغييرات بسيطة فقط في قاعدة الكود، ويتضمن خطوتين بسيطتين:

1. تحميل تكوين الحواجز وإنشاء نسخة `LLMRails`.
2. إجراء الاستدعاءات إلى LLM باستخدام طريقتي `generate`/`generate_async`.```python
from nemoguardrails import LLMRails, RailsConfig

# Load a guardrails configuration from the specified path.
config = RailsConfig.from_path("PATH/TO/CONFIG")
rails = LLMRails(config)

completion = rails.generate(
    messages=[{"role": "user", "content": "Hello world!"}]
)

تنسيق الإدخال والإخراج لطريقة `generate` مشابه لـ [Chat Completions API](https://platform.openai.com/docs/guides/gpt/chat-completions-api) من OpenAI.

#### واجهة API غير المتزامنة

مكتبة NeMo Guardrails هي مجموعة أدوات غير متزامنة أولاً حيث يتم تنفيذ الآليات الأساسية باستخدام نموذج Python غير المتزامن. تحتوي الطرق العامة على نسختين متزامنة وغير متزامنة. على سبيل المثال: `LLMRails.generate` و `LLMRails.generate_async`.

### نماذج LLM المدعومة

يمكنك استخدام NeMo Guardrails مع نماذج LLM متعددة مثل OpenAI GPT-3.5 و GPT-4 و LLaMa-2 و Falcon و Vicuna أو Mosaic. لمزيد من التفاصيل، راجع قسم [نماذج LLM المدعومة](https://docs.nvidia.com/nemo/guardrails/about-nemo-guardrails-library/supported-llms) في دليل التكوين.

### أنواع Guardrails

تدعم مكتبة NeMo Guardrails خمسة أنواع رئيسية من guardrails:

<div align="center">
  <img src="https://raw.githubusercontent.com/NVIDIA-NeMo/Guardrails/develop/docs/_static/images/programmable_guardrails_flow.png"  width="75%" alt="Programmable Guardrails Flow">
</div>

1. **Input rails**: تُطبَّق على الإدخال من المستخدم؛ يمكن لـ input rail رفض الإدخال، مما يوقف أي معالجة إضافية، أو تعديل الإدخال (على سبيل المثال، لإخفاء بيانات قد تكون حساسة، أو لإعادة الصياغة).

2. **Dialog rails**: تؤثر على كيفية توجيه LLM؛ تعمل dialog rails على رسائل الشكل الأساسي (canonical form) للتفاصيل راجع [دليل Colang](https://docs.nvidia.com/nemo/guardrails/configure-guardrails/colang)) وتحدد ما إذا كان يجب تنفيذ إجراء، وما إذا كان يجب استدعاء LLM لتوليد الخطوة التالية أو استجابة، وما إذا كان يجب استخدام استجابة محددة مسبقًا بدلاً من ذلك، إلخ.

3. **Retrieval rails**: تُطبَّق على الأجزاء المسترجعة في حالة سيناريو RAG (Retrieval Augmented Generation)؛ يمكن لـ retrieval rail رفض جزء، مما يمنعه من استخدامه لتوجيه LLM، أو تعديل الأجزاء ذات الصلة (على سبيل المثال، لإخفاء بيانات قد تكون حساسة).

4. **Execution rails**: تُطبَّق على إدخال/إخراج الإجراءات المخصصة (المعروفة أيضًا باسم الأدوات)، التي يحتاج LLM إلى استدعائها.

5. **Output rails**: تُطبَّق على الإخراج الذي يولده LLM؛ يمكن لـ output rail رفض الإخراج، مما يمنعه من إعادته إلى المستخدم، أو تعديله (على سبيل المثال، إزالة البيانات الحساسة).

### تكوين Guardrails

يحدد تكوين guardrails **نموذج (نماذج) LLM** التي سيتم استخدامها و**واحدًا أو أكثر من guardrails**. يمكن أن يتضمن تكوين guardrails أي عدد من input/dialog/output/retrieval/execution rails. التكوين بدون أي rails مُكوَّنة سيقوم أساسًا بإعادة توجيه الطلبات إلى LLM.

يبدو الهيكل القياسي لمجلد تكوين guardrails كما يلي:```
.
├── config
│   ├── actions.py
│   ├── config.py
│   ├── config.yml
│   ├── rails.co
│   ├── ...

تحتوي ملفات `.co` المضمّنة في إعداد guardrails على تعريفات Colang (راجع القسم التالي للحصول على نظرة سريعة عن ماهية Colang) التي تُعرّف أنواعًا مختلفة من الحواجز (rails). فيما يلي مثال لملف `greeting.co` الذي يُعرّف حواجز الحوار (dialog rails) لتحية المستخدم.```colang
define user express greeting
  "Hello!"
  "Good afternoon!"

define flow
  user express greeting
  bot express greeting
  bot offer to help

define bot express greeting
  "Hello there!"

define bot offer to help
  "How can I help you today?"

### Colang

لتكوين وتنفيذ أنواع مختلفة من الحواجز الأمنية، تقدّم هذه المجموعة **Colang**، وهي لغة نمذجة صُممت خصيصًا لتصميم تدفقات حوارية مرنة وقابلة للتحكم في الوقت نفسه. تتميز Colang بصياغة شبيهة بـ Python ومصممة لتكون بسيطة وبديهية، خاصةً للمطورين.```{note}
Two versions of Colang, 1.0 and 2.0, are supported and Colang 1.0 is the default.

تتضمن المكتبة حواجز حماية للتحقق الذاتي من LLM (مراجعة المدخلات/المخرجات، والتحقق من الحقائق، واكتشاف الهلوسة)، ونماذج أمان NVIDIA (أمان المحتوى، أمان الموضوع)، واكتشاف كسر الحماية والحقن، وتكاملات مع نماذج المجتمع وواجهات برمجة التطبيقات الخارجية. للحصول على القائمة الكاملة، راجع [وثائق مكتبة Guardrails](https://docs.nvidia.com/nemo/guardrails/user-guides/guardrails-library.html).

## CLI

تأتي مكتبة NeMo Guardrails أيضًا مع واجهة سطر أوامر (CLI) مدمجة.```bash
$ nemoguardrails --help

Usage: nemoguardrails [OPTIONS] COMMAND [ARGS]...

actions-server    Start a NeMo Guardrails actions server.
chat              Start an interactive chat session.
evaluate          Run an evaluation task.
server            Start a NeMo Guardrails server.

على سبيل المثال، للحصول على إكمال محادثة لإعداد `sample`، يمكنك استخدام نقطة النهاية `/v1/chat/completions`:```
POST /v1/chat/completions

# استنساخ المستودع
git clone https://github.com/yourusername/kitploit-tool.git
cd kitploit-tool

# إنشاء بيئة افتراضية
python3 -m venv venv
source venv/bin/activate  # على Windows: venv\Scripts\activate

# تثبيت التبعيات
pip install -r requirements.txt

# تثبيت الأداة
pip install -e .

pip install kitploit-tool

# سحب الصورة
docker pull kitploit/tool:latest

# تشغيل الحاوية
docker run -it --rm kitploit/tool:latest --help

# التحقق من التثبيت
kitploit-tool --version

# تشغيل الاختبارات
pytest tests/

# عرض المساعدة
kitploit-tool --help

# تشغيل الفحص الأساسي
kitploit-tool scan --target example.com

# تشغيل الفحص مع خيارات متقدمة
kitploit-tool scan --target example.com --deep --output results.json

kitploit-tool scan --target 192.168.1.1 --port 80

kitploit-tool scan --target 192.168.1.1 --ports 1-1000

kitploit-tool scan --target 192.168.1.0/24 --threads 50

kitploit-tool scan --target example.com --output results.json --format json

# config.yaml
target: example.com
threads: 20
timeout: 60
deep_scan: true
output:
  format: json
  file: results.json

kitploit-tool scan --config config.yaml

from kitploit_tool import Scanner

# إنشاء مثيل الماسح الضوئي
scanner = Scanner(target="example.com")

# تشغيل الفحص
results = scanner.scan()

# معالجة النتائج
for result in results:
    print(f"المنفذ: {result.port}, الحالة: {result.status}")

from kitploit_tool import Scanner, ScanConfig

# تكوين الفحص
config = ScanConfig(
    threads=20,
    timeout=60,
    deep_scan=True
)

# إنشاء الماسح الضوئي مع التكوين
scanner = Scanner(target="example.com", config=config)

# تشغيل الفحص مع معالجات الأحداث
scanner.on("port_found", lambda port: print(f"تم العثور على منفذ: {port}"))
scanner.on("scan_complete", lambda results: print(f"اكتمل الفحص: {len(results)} نتيجة"))

results = scanner.scan()

from kitploit_tool import Scanner, ScanError

try:
    scanner = Scanner(target="example.com")
    results = scanner.scan()
except ScanError as e:
    print(f"فشل الفحص: {e}")
except Exception as e:
    print(f"حدث خطأ غير متوقع: {e}")

# استنساخ المستودع
git clone https://github.com/yourusername/kitploit-tool.git
cd kitploit-tool

# إنشاء بيئة افتراضية
python3 -m venv venv
source venv/bin/activate

# تثبيت تبعيات التطوير
pip install -r requirements-dev.txt

# تثبيت خطافات pre-commit
pre-commit install

# تشغيل جميع الاختبارات
pytest

# تشغيل الاختبارات مع التغطية
pytest --cov=kitploit_tool tests/

# تشغيل اختبار محدد
pytest tests/test_scanner.py::test_basic_scan

نموذج الإخراج:```json
{"role": "assistant", "content": "Hi! How can I help you?"}

قم بتعيين إلغاء الاشتراك قبل بدء تشغيل مكتبة NVIDIA NeMo Guardrails. تغيير متغيرات البيئة أو إنشاء `do_not_track` بعد بدء القياس عن بُعد لا يوقف خيط نبضات القلب قيد التشغيل بالفعل.

راجع [docs/telemetry.md](https://docs.nvidia.com/nemo/guardrails/latest/telemetry.html) للحصول على المخطط الكامل والأوصاف التفصيلية لكل حقل.

يمكنك إلغاء الاشتراك في جمع القياس عن بُعد في أي وقت. ينطبق إلغاء الاشتراك فقط على جمع البيانات بواسطة مكتبة NVIDIA NeMo Guardrails نفسها.

لنقاط النهاية الخارجية شروط وممارسات خصوصية منفصلة. يمكن لمكتبة NVIDIA NeMo Guardrails استخدام نقاط نهاية الاستدلال مثل NVIDIA Build (`build.nvidia.com`). إذا كنت تستخدم NVIDIA Build أو أي نقطة نهاية خارجية أخرى، فإن شروط الخدمة وممارسات الخصوصية لتلك النقطة تنطبق بشكل مستقل عن المكتبة. أي إلغاء اشتراك في القياس عن بُعد في مكتبة NVIDIA NeMo Guardrails لا يمتد إلى نقطة النهاية التي تختارها. NVIDIA Build مخصص للتقييم والاختبار فقط ويجب عدم استخدامه في بيئات الإنتاج. لا ترسل معلومات سرية أو بيانات شخصية عند استخدام NVIDIA Build.

## دعوة المجتمع للمساهمة

تُعد قواعد الحماية النموذجية الموجودة في المستودع نقاط انطلاق ممتازة. ندعو المجتمع بحماس للمساهمة في جعل قوة نماذج اللغة الكبيرة الموثوقة والآمنة والمأمونة متاحة للجميع. للحصول على إرشادات حول إعداد بيئة تطوير وكيفية المساهمة في مكتبة NeMo Guardrails، راجع [إرشادات المساهمة](https://github.com/nvidia-nemo/guardrails/blob/develop/CONTRIBUTING.md).

## الترخيص

مكتبة NeMo Guardrails مرخّصة بموجب [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).

## كيفية الاستشهاد

إذا كنت تستخدم مكتبة NeMo Guardrails، فاستشهد بـ [ورقة EMNLP 2023](https://aclanthology.org/2023.emnlp-demo.40) التي تقدّمها.```bibtex
@inproceedings{rebedea-etal-2023-nemo,
    title = "{N}e{M}o Guardrails: A Toolkit for Controllable and Safe {LLM} Applications with Programmable Rails",
    author = "Rebedea, Traian  and
      Dinu, Razvan  and
      Sreedhar, Makesh Narsimhan  and
      Parisien, Christopher  and
      Cohen, Jonathan",
    editor = "Feng, Yansong  and
      Lefever, Els",
    booktitle = "Proceedings of the 2023 Conference on Empirical Methods in Natural Language Processing: System Demonstrations",
    month = dec,
    year = "2023",
    address = "Singapore",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2023.emnlp-demo.40",
    doi = "10.18653/v1/2023.emnlp-demo.40",
    pages = "431--445",
}