crewAI/docs/ar/tools/database-data/nl2sqltool.mdx

---
title: أداة NL2SQL
description: أداة `NL2SQLTool` مصممة لتحويل اللغة الطبيعية إلى استعلامات SQL.
icon: language
mode: "wide"
---

## نظرة عامة

تُستخدم هذه الأداة لتحويل اللغة الطبيعية إلى استعلامات SQL. عند تمريرها إلى الوكيل، ستقوم بتوليد الاستعلامات ثم استخدامها للتفاعل مع قاعدة البيانات.

يتيح ذلك سير عمل متعددة مثل أن يقوم وكيل بالوصول إلى قاعدة البيانات واسترجاع المعلومات بناءً على الهدف ثم استخدام تلك المعلومات لتوليد استجابة أو تقرير أو أي مخرجات أخرى. بالإضافة إلى ذلك، يوفر القدرة للوكيل على تحديث قاعدة البيانات بناءً على هدفه.

**تنبيه**: الأداة للقراءة فقط بشكل افتراضي (SELECT/SHOW/DESCRIBE/EXPLAIN فقط). تتطلب عمليات الكتابة تمرير `allow_dml=True` أو ضبط متغير البيئة `CREWAI_NL2SQL_ALLOW_DML=true`. عند تفعيل الكتابة، تأكد من أن الوكيل يستخدم مستخدم قاعدة بيانات محدود الصلاحيات أو نسخة قراءة كلما أمكن.

## نموذج الأمان

`NL2SQLTool` هي أداة قابلة للتنفيذ. تقوم بتشغيل استعلامات SQL المولّدة من النموذج مباشرة على اتصال قاعدة البيانات المُهيأ.

هذا يعني أن المخاطر تعتمد على خيارات النشر الخاصة بك:

- بيانات الاعتماد التي تقدمها في `db_uri`
- ما إذا كان بإمكان المدخلات غير الموثوقة التأثير على الأوامر
- ما إذا كنت تضيف حواجز حماية لاستدعاءات الأدوات قبل التنفيذ

إذا كنت توجه مدخلات غير موثوقة إلى وكلاء يستخدمون هذه الأداة، تعامل معها كتكامل عالي المخاطر.

## توصيات التقوية

استخدم جميع الإجراءات التالية في بيئة الإنتاج:

- استخدم مستخدم قاعدة بيانات للقراءة فقط كلما أمكن
- فضّل نسخة القراءة لأعباء العمل التحليلية/الاسترجاعية
- امنح أقل صلاحيات ممكنة (بدون أدوار المسؤول/المستخدم الفائق، بدون صلاحيات على مستوى الملفات/النظام)
- طبّق حدود الموارد على مستوى قاعدة البيانات (مهلة الاستعلام، مهلة القفل، حدود التكلفة/الصفوف)
- أضف خطافات `before_tool_call` لفرض أنماط الاستعلام المسموح بها
- فعّل تسجيل الاستعلامات والتنبيهات للعبارات التدميرية

## وضع القراءة فقط وتهيئة DML

تعمل `NL2SQLTool` في **وضع القراءة فقط بشكل افتراضي**. لا يُسمح إلا بأنواع العبارات التالية دون تهيئة إضافية:

- `SELECT`
- `SHOW`
- `DESCRIBE`
- `EXPLAIN`

أي محاولة لتنفيذ عملية كتابة (`INSERT`، `UPDATE`، `DELETE`، `DROP`، `CREATE`، `ALTER`، `TRUNCATE`، إلخ) ستُسبب خطأً ما لم يتم تفعيل DML صراحةً.

كما تُحظر الاستعلامات متعددة العبارات التي تحتوي على فاصلة منقوطة (مثل `SELECT 1; DROP TABLE users`) في وضع القراءة فقط لمنع هجمات الحقن.

### تفعيل عمليات الكتابة

يمكنك تفعيل DML (لغة معالجة البيانات) بطريقتين:

**الخيار الأول — معامل المُنشئ:**

```python
from crewai_tools import NL2SQLTool

nl2sql = NL2SQLTool(
    db_uri="postgresql://example@localhost:5432/test_db",
    allow_dml=True,
)
```

**الخيار الثاني — متغير البيئة:**

```bash
CREWAI_NL2SQL_ALLOW_DML=true
```

```python
from crewai_tools import NL2SQLTool

# DML مفعّل عبر متغير البيئة
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
```

### أمثلة الاستخدام

**القراءة فقط (الافتراضي) — آمن للتحليلات والتقارير:**

```python
from crewai_tools import NL2SQLTool

# يُسمح فقط بـ SELECT/SHOW/DESCRIBE/EXPLAIN
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
```

**مع تفعيل DML — مطلوب لأعباء عمل الكتابة:**

```python
from crewai_tools import NL2SQLTool

# يُسمح بـ INSERT وUPDATE وDELETE وDROP وغيرها
nl2sql = NL2SQLTool(
    db_uri="postgresql://example@localhost:5432/test_db",
    allow_dml=True,
)
```

<Warning>
يمنح تفعيل DML للوكيل القدرة على تعديل البيانات أو حذفها. لا تفعّله إلا عندما يتطلب حالة الاستخدام صراحةً وصولاً للكتابة، وتأكد من أن بيانات اعتماد قاعدة البيانات محدودة بالحد الأدنى من الصلاحيات المطلوبة.
</Warning>

## المتطلبات

- SqlAlchemy
- أي مكتبة متوافقة مع قواعد البيانات (مثل psycopg2، mysql-connector-python)

## التثبيت

قم بتثبيت حزمة crewai_tools

```shell
pip install 'crewai[tools]'
```

## الاستخدام

لاستخدام أداة NL2SQLTool، تحتاج إلى تمرير عنوان URI لقاعدة البيانات إلى الأداة. يجب أن يكون العنوان بصيغة `dialect+driver://username:password@host:port/database`.

```python Code
from crewai_tools import NL2SQLTool

# psycopg2 was installed to run this example with PostgreSQL
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")

@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config["researcher"],
        allow_delegation=False,
        tools=[nl2sql]
    )
```

## مثال

كان هدف المهمة الأساسي:

"استرجاع المتوسط والحد الأقصى والحد الأدنى للإيرادات الشهرية لكل مدينة، مع تضمين المدن التي بها أكثر من مستخدم واحد فقط. أيضاً، قم بعدّ المستخدمين في كل مدينة وترتيب النتائج حسب متوسط الإيرادات الشهرية بترتيب تنازلي"

حاول الوكيل الحصول على المعلومات من قاعدة البيانات، الاستعلام الأول كان خاطئاً فحاول الوكيل مرة أخرى وحصل على المعلومات الصحيحة ومررها إلى الوكيل التالي.

![alt text](https://github.com/crewAIInc/crewAI-tools/blob/main/crewai_tools/tools/nl2sql/images/image-2.png?raw=true)
![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-3.png)


كان هدف المهمة الثانية:

"مراجعة البيانات وإنشاء تقرير مفصّل، ثم إنشاء جدول في قاعدة البيانات بحقول مبنية على البيانات المقدمة. تضمين معلومات عن المتوسط والحد الأقصى والحد الأدنى للإيرادات الشهرية لكل مدينة، مع تضمين المدن التي بها أكثر من مستخدم واحد فقط. أيضاً، عدّ المستخدمين في كل مدينة وترتيب النتائج حسب متوسط الإيرادات الشهرية بترتيب تنازلي."

الآن تصبح الأمور مثيرة للاهتمام، حيث يولّد الوكيل استعلام SQL ليس فقط لإنشاء الجدول بل أيضاً لإدراج البيانات فيه. وفي النهاية لا يزال الوكيل يُرجع التقرير النهائي الذي يتطابق تماماً مع ما كان في قاعدة البيانات.

![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-4.png)
![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-5.png)

![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-9.png)
![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-7.png)


هذا مثال بسيط على كيفية استخدام أداة NL2SQLTool للتفاعل مع قاعدة البيانات وتوليد التقارير بناءً على البيانات الموجودة فيها.

توفر الأداة إمكانيات لا حصر لها لمنطق الوكيل وكيفية تفاعله مع قاعدة البيانات.

```md
 DB -> Agent -> ... -> Agent -> DB
```