mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-08-10 08:21:54 +00:00
338662201f
The page claimed read-only mode blocked "multi-statement queries containing semicolons" and said nothing about CTEs, EXPLAIN ANALYZE, or the fact that a SELECT can still reach the database server's filesystem. Both gaps matter now that those routes are enforced. - Replace the semicolon sentence with a table of every indirect write route blocked in read-only mode: multi-statement, writable CTEs (including AS MATERIALIZED), a write after a CTE, EXPLAIN ANALYZE, INTO OUTFILE, server-filesystem functions, and unparseable WITH statements. - Explain that analysis masks literals and comments, so `SELECT 'DROP TABLE users'` is allowed while `EXPLAIN /*x*/ ANALYZE DELETE ...` is blocked, and that a semicolon inside a literal no longer splits statements. - Document the new SET TRANSACTION READ ONLY backstop and which backends fall back without it. - Add a warning that these checks are defence in depth and a least-privileged read-only database role is the only complete control. Every example in the new table was verified against the implementation. Applied to en/ar/ko/pt-BR under docs/edge; the ko and pt-BR pages carry the warning inline as they have no Hardening Recommendations section. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
189 lines
12 KiB
Plaintext
189 lines
12 KiB
Plaintext
---
|
|
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`
|
|
- ما إذا كان بإمكان المدخلات غير الموثوقة التأثير على الأوامر
|
|
- ما إذا كنت تضيف حواجز حماية لاستدعاءات الأدوات قبل التنفيذ
|
|
|
|
إذا كنت توجه مدخلات غير موثوقة إلى وكلاء يستخدمون هذه الأداة، تعامل معها كتكامل عالي المخاطر.
|
|
|
|
## توصيات التقوية
|
|
|
|
<Warning>
|
|
تُعد فحوصات القراءة فقط المدمجة طبقة دفاع إضافية، وليست حدًا كاملًا. فهي تفحص نص العبارة، ولغة SQL تختلف باختلاف نظام قواعد البيانات: إذ يمكن لعبارة تبدأ بـ `SELECT` أن تصل إلى نظام ملفات خادم قاعدة البيانات (`SELECT ... INTO OUTFILE`، `pg_read_file()`) أو أن تستدعي دالة ذات آثار جانبية. تُحظر المنافذ المعروفة صراحةً، لكن التحكم الكامل الوحيد هو الصلاحيات التي تمنحها في `db_uri`. **وجّه الأداة إلى دور قاعدة بيانات للقراءة فقط بأقل الصلاحيات الممكنة.**
|
|
</Warning>
|
|
|
|
استخدم جميع الإجراءات التالية في بيئة الإنتاج:
|
|
|
|
- استخدم مستخدم قاعدة بيانات للقراءة فقط كلما أمكن
|
|
- فضّل نسخة القراءة لأعباء العمل التحليلية/الاسترجاعية
|
|
- امنح أقل صلاحيات ممكنة (بدون أدوار المسؤول/المستخدم الفائق، بدون صلاحيات على مستوى الملفات/النظام)
|
|
- طبّق حدود الموارد على مستوى قاعدة البيانات (مهلة الاستعلام، مهلة القفل، حدود التكلفة/الصفوف)
|
|
- أضف خطافات `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,
|
|
)
|
|
```
|
|
|
|
<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]
|
|
)
|
|
```
|
|
|
|
## مثال
|
|
|
|
كان هدف المهمة الأساسي:
|
|
|
|
"استرجاع المتوسط والحد الأقصى والحد الأدنى للإيرادات الشهرية لكل مدينة، مع تضمين المدن التي بها أكثر من مستخدم واحد فقط. أيضاً، قم بعدّ المستخدمين في كل مدينة وترتيب النتائج حسب متوسط الإيرادات الشهرية بترتيب تنازلي"
|
|
|
|
حاول الوكيل الحصول على المعلومات من قاعدة البيانات، الاستعلام الأول كان خاطئاً فحاول الوكيل مرة أخرى وحصل على المعلومات الصحيحة ومررها إلى الوكيل التالي.
|
|
|
|
|
|
|
|
|
|
|
|
كان هدف المهمة الثانية:
|
|
|
|
"مراجعة البيانات وإنشاء تقرير مفصّل، ثم إنشاء جدول في قاعدة البيانات بحقول مبنية على البيانات المقدمة. تضمين معلومات عن المتوسط والحد الأقصى والحد الأدنى للإيرادات الشهرية لكل مدينة، مع تضمين المدن التي بها أكثر من مستخدم واحد فقط. أيضاً، عدّ المستخدمين في كل مدينة وترتيب النتائج حسب متوسط الإيرادات الشهرية بترتيب تنازلي."
|
|
|
|
الآن تصبح الأمور مثيرة للاهتمام، حيث يولّد الوكيل استعلام SQL ليس فقط لإنشاء الجدول بل أيضاً لإدراج البيانات فيه. وفي النهاية لا يزال الوكيل يُرجع التقرير النهائي الذي يتطابق تماماً مع ما كان في قاعدة البيانات.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
هذا مثال بسيط على كيفية استخدام أداة NL2SQLTool للتفاعل مع قاعدة البيانات وتوليد التقارير بناءً على البيانات الموجودة فيها.
|
|
|
|
توفر الأداة إمكانيات لا حصر لها لمنطق الوكيل وكيفية تفاعله مع قاعدة البيانات.
|
|
|
|
```md
|
|
DB -> Agent -> ... -> Agent -> DB
|
|
```
|