---
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`
- ما إذا كان بإمكان المدخلات غير الموثوقة التأثير على الأوامر
- ما إذا كنت تضيف حواجز حماية لاستدعاءات الأدوات قبل التنفيذ
إذا كنت توجه مدخلات غير موثوقة إلى وكلاء يستخدمون هذه الأداة، تعامل معها كتكامل عالي المخاطر.
## توصيات التقوية
تُعد فحوصات القراءة فقط المدمجة طبقة دفاع إضافية، وليست حدًا كاملًا. فهي تفحص نص العبارة، ولغة SQL تختلف باختلاف نظام قواعد البيانات: إذ يمكن لعبارة تبدأ بـ `SELECT` أن تصل إلى نظام ملفات خادم قاعدة البيانات (`SELECT ... INTO OUTFILE`، `pg_read_file()`) أو أن تستدعي دالة ذات آثار جانبية. تُحظر المنافذ المعروفة صراحةً، لكن التحكم الكامل الوحيد هو الصلاحيات التي تمنحها في `db_uri`. **وجّه الأداة إلى دور قاعدة بيانات للقراءة فقط بأقل الصلاحيات الممكنة.**
استخدم جميع الإجراءات التالية في بيئة الإنتاج:
- استخدم مستخدم قاعدة بيانات للقراءة فقط كلما أمكن
- فضّل نسخة القراءة لأعباء العمل التحليلية/الاسترجاعية
- امنح أقل صلاحيات ممكنة (بدون أدوار المسؤول/المستخدم الفائق، بدون صلاحيات على مستوى الملفات/النظام)
- طبّق حدود الموارد على مستوى قاعدة البيانات (مهلة الاستعلام، مهلة القفل، حدود التكلفة/الصفوف)
- أضف خطافات `before_tool_call` لفرض أنماط الاستعلام المسموح بها
- فعّل تسجيل الاستعلامات والتنبيهات للعبارات التدميرية
## وضع القراءة فقط وتهيئة DML
تعمل `NL2SQLTool` في **وضع القراءة فقط بشكل افتراضي**. لا يُسمح إلا بأنواع العبارات التالية دون تهيئة إضافية:
- `SELECT`
- `SHOW`
- `DESCRIBE`
- `EXPLAIN`
أي محاولة لتنفيذ عملية كتابة (`INSERT`، `UPDATE`، `DELETE`، `DROP`، `CREATE`، `ALTER`، `TRUNCATE`، إلخ) ستُسبب خطأً ما لم يتم تفعيل DML صراحةً.
كما يحظر وضع القراءة فقط الطرق غير المباشرة للكتابة:
| المحظور في وضع القراءة فقط | مثال |
| --- | --- |
| الاستعلامات متعددة العبارات | `SELECT 1; DROP TABLE users` |
| تعبيرات CTE الكاتبة، بما في ذلك صيغة `MATERIALIZED` | `WITH d AS MATERIALIZED (DELETE FROM users RETURNING *) SELECT * FROM d` |
| عملية كتابة تلي تعبير CTE | `WITH d AS (SELECT 1) DELETE FROM users` |
| `EXPLAIN ANALYZE`، الذي ينفّذ العبارة التابعة له فعليًا | `EXPLAIN ANALYZE DELETE FROM users` |
| الكتابة إلى نظام ملفات خادم قاعدة البيانات | `SELECT * FROM users INTO OUTFILE '/var/www/shell.php'` |
| الدوال التي تصل إلى نظام ملفات الخادم أو تفتح اتصالًا جديدًا | `SELECT pg_read_file('/etc/passwd')`، `dblink_exec(...)` |
| عبارة `WITH` يتعذّر تحليلها للتأكد من أنها للقراءة فقط | `WITH d AS DELETE FROM users` |
تُحلَّل العبارات بعد إخفاء النصوص الحرفية والتعليقات، لذا لا تُعامَل كلمة مفتاحية مخبأة داخل نص حرفي على أنها أمر (`SELECT 'DROP TABLE users'` مسموح)، ولا يُخفي تعليقٌ موضوع بين الكلمات المفتاحية أمرًا (`EXPLAIN /*x*/ ANALYZE DELETE ...` محظور). كما أن الفاصلة المنقوطة داخل نص حرفي ليست فاصلًا بين العبارات، لذا فإن `SELECT ';'` عبارة واحدة صحيحة.
في وضع القراءة فقط، تضع الأداة أيضًا المعاملة في حالة `SET TRANSACTION READ ONLY`، فترفض PostgreSQL وMySQL عمليات الكتابة على مستوى قاعدة البيانات مهما كانت صياغة العبارة. أما الأنظمة التي لا تدعم هذه الصيغة (SQLite، SQL Server، Snowflake) فتُسجّل رسالة تصحيح وتعود إلى الاعتماد على فحص العبارات وحده — وهذا سبب إضافي للاعتماد على دور للقراءة فقط بدلًا من التحليل النصي.
### تفعيل عمليات الكتابة
يمكنك تفعيل 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,
)
```
يمنح تفعيل DML للوكيل القدرة على تعديل البيانات أو حذفها. لا تفعّله إلا عندما يتطلب حالة الاستخدام صراحةً وصولاً للكتابة، وتأكد من أن بيانات اعتماد قاعدة البيانات محدودة بالحد الأدنى من الصلاحيات المطلوبة.
## المتطلبات
- 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]
)
```
## مثال
كان هدف المهمة الأساسي:
"استرجاع المتوسط والحد الأقصى والحد الأدنى للإيرادات الشهرية لكل مدينة، مع تضمين المدن التي بها أكثر من مستخدم واحد فقط. أيضاً، قم بعدّ المستخدمين في كل مدينة وترتيب النتائج حسب متوسط الإيرادات الشهرية بترتيب تنازلي"
حاول الوكيل الحصول على المعلومات من قاعدة البيانات، الاستعلام الأول كان خاطئاً فحاول الوكيل مرة أخرى وحصل على المعلومات الصحيحة ومررها إلى الوكيل التالي.
كان هدف المهمة الثانية:
"مراجعة البيانات وإنشاء تقرير مفصّل، ثم إنشاء جدول في قاعدة البيانات بحقول مبنية على البيانات المقدمة. تضمين معلومات عن المتوسط والحد الأقصى والحد الأدنى للإيرادات الشهرية لكل مدينة، مع تضمين المدن التي بها أكثر من مستخدم واحد فقط. أيضاً، عدّ المستخدمين في كل مدينة وترتيب النتائج حسب متوسط الإيرادات الشهرية بترتيب تنازلي."
الآن تصبح الأمور مثيرة للاهتمام، حيث يولّد الوكيل استعلام SQL ليس فقط لإنشاء الجدول بل أيضاً لإدراج البيانات فيه. وفي النهاية لا يزال الوكيل يُرجع التقرير النهائي الذي يتطابق تماماً مع ما كان في قاعدة البيانات.
هذا مثال بسيط على كيفية استخدام أداة NL2SQLTool للتفاعل مع قاعدة البيانات وتوليد التقارير بناءً على البيانات الموجودة فيها.
توفر الأداة إمكانيات لا حصر لها لمنطق الوكيل وكيفية تفاعله مع قاعدة البيانات.
```md
DB -> Agent -> ... -> Agent -> DB
```