یک نویسه اشتباه در یک کوئری SQL ممکن است در ظاهر معتبر باشد، اما اغلب تنها همین یک مورد کافی است تا گزارش‌های داده‌ای شما کاملاً غلط شوند. برای مقابله با این مشکل، Hugging Face چارچوبی به نام smolagents معرفی کرده است که در یک راهنمای فنی اخیر با جزئیات شرح داده شده است. این چارچوب به عامل‌ها (Agents) اجازه می‌دهد در حین تعامل با پایگاه‌داده، استدلال کنند، اقدام نمایند و اشتباهات خود را به‌صورت خودکار اصلاح کنند.
مشکل سنتی تبدیل متن به SQL
بسیاری از خط لوله‌های سنتی تبدیل متن به SQL (text-to-SQL) به‌صورت کورکورانه عمل می‌کنند: کاربر سوالی می‌پرسد، مدل یک کوئری تولید می‌کند و سیستم بلافاصله آن را اجرا می‌کند. این الگوی عملیاتی اساساً شکننده است. طبق مستندات فنی این پروژه، اگر مدل یک کوئری نادرست تولید کند، ممکن است باز هم بدون فعال کردن هیچ خطای سیستمی قابل مشاهده‌ای اجرا شود. در این حالت، سیستمی پاسخی را برمی‌گرداند که در ظاهر معتبر به نظر می‌رسد اما از نظر واقعی غلط است. در چنین مواردی، کاربر هرگز متوجه نمی‌شود که پاسخ نادرست است، زیرا هیچ شکست سیستمی برای علامت‌گذاری این اشتباه رخ نداده است.
همان‌طور که در تحلیل‌های قبلی ما درباره نحوه بهینه‌سازی پشته‌های ماژولار توسط Hugging Face و Cerebras برای کاهش تأخیر اشاره کردیم، رویکرد جدید این شرکت دقت را بر سرعت اجرای تک‌مرحله‌ای ترجیح می‌دهد. این متد، تعامل با پایگاه‌داده را نه یک задачу ساده ترجمه، بلکه یک فرآیند تکرارشونده از آزمون و تأیید می‌بیند.
چارچوب ReAct
قلب این سیستم CodeAgent است که الگوی ری‌اکت (ReAct یا Reasoning + Acting) را پیاده می‌کند. در این الگو، عامل به جای اینکه صرفاً یک خروجی SQL تولید کند، کدهای پایتون می‌نویسد و آن‌ها را اجرا می‌کند تا با پایگاه‌داده تعامل یابد. سپس عامل نتیجه را مشاهده می‌کند و بر اساس آن تصمیم می‌گیرد که آیا وظیفه به پایان رسیده است یا خیر. این رویکرد، یک ترجمه کورکورانه را به یک حلقه تبدیل می‌کند که در آن عامل می‌تواند نتایج کوئری‌های خود را بازبینی کرده و تصمیم بگیرد که آیا اصلاحی لازم است یا خیر.
به گزارش Hugging Face، این سازوکار از «شکست‌های خاموش» جلوگیری می‌کند؛ یعنی شرایطی که در آن یک کوئری بدون خطا اجرا می‌شود اما داده‌های غلط برمی‌گرداند. پیاده‌سازی این سیستم بر سه مؤلفه اصلی متکی است:
- smolagents: چارچوب سبک عامل‌محور Hugging Face که در آدرس github.com/huggingface/smolagents میزبانی می‌شود.
- SQLAlchemy: ابزاری که برای ایجاد و مدیریت پایگاه‌داده‌های SQLite در حافظه (in-memory) و اجرای کوئری‌ها به کار می‌رود.
- InferenceClientModel: پلی برای اتصال به APIهای استنتاج سرورلس یا اختصاصی Hugging Face؛ لحظه‌ای که مدل واقعاً جواب تولید می‌کند.
جزئیات پیاده‌سازی فنی
برای اینکه عامل نسبت به پایگاه‌داده آگاه شود، توسعه‌دهندگان از پرامپت‌های استاندارد و باز استفاده نمی‌کنند. در عوض، طرحواره (Schema) جداول مستقیماً در docstring یک ابزار که با دکوراتور @tool علامت‌گذاری شده، جای می‌گیرد.
- تعریف ابزار: تابعی به نام
sql_engineبرای انجام کوئری‌های SQL ایجاد می‌شود. - جای‌گذاری طرحواره: در docstring تابع
sql_engineبه‌طور صریح نام جدول (receipts) و ستون‌های آن لیست شده است:receipt_id(از نوع INTEGER)،customer_name(از نوع VARCHAR(16))،price(از نوع FLOAT) وtip(از نوع FLOAT). - منطق عامل: CodeAgent این docstring را می‌خواند تا طرحواره موجود و نحوه فرمت‌بندی کوئری‌ها را درک کند. برای مثال، درخواستی مانند «می‌توانی نام مشتری‌ای که گران‌ترین رسید را داشته است به من بگویی؟» توسط عامل پردازش شده، کوئری SQL تولید می‌شود و سپس از طریق ابزار
sql_engineاجرا می‌گردد.
مدیریت سناریوهای پیچیده
با افزایش پیچیدگی، این چارچوب اجازه مقیاس‌پذیری پویا را می‌دهد. در یک «آزمون فشار» برای این عامل، جدول دومی به نام waiters اضافه شد. این جدول هر receipt_id را به نام گارسونی که به مشتری سرویس داده مرتبط می‌کند. این تغییر، عامل را مجبور می‌کند تا برای پاسخ به سوالاتی مانند «کدام گارسون مجموعاً انعام بیشتری دریافت کرده است؟»، روی مفهوم JOIN (اتصال بین دو جدول) استدلال کند.
در طول این انتقال، دو تنظیم کلیدی صورت می‌گیرد:
- توصیفات پویا: شرح
sql_engine.descriptionبه‌طور پویا به‌روزرسانی می‌شود تا ستون‌های هر دو جدول را شامل شود. این یعنی عامل درک خود از محیط را بدون نیاز به هیچ‌گونه بازآموزی یا بازنویسی منطق، به‌روز می‌کند. - مقیاس‌بندی مدل: برای مدیریت دشواری افزایش یافته در استدلال روی JOINها، مدل از Llama-3.1-8B-Instruct به مدل قدرتمندتر Qwen3-Next-80B-A3B-Thinking تغییر می‌یابد. مستندات تأیید می‌کنند که این ارتقای مدل، نتایج را برای کوئری‌های پیچیده به‌طور قابل‌توجهی بهبود می‌بخشد.
مزایای تطبیقی
این چرخش معماری، فرض بنیادی تحلیل داده‌های مبتنی بر AI را تغییر می‌دهد. یک خط لوله مستقیم Text-to-SQL صلب است؛ یعنی در یک مرحله تولید و اجرا می‌کند، خطاها را نادیده می‌گیرد و به طرحواره‌های سخت‌کد شده (hard-coded) نیاز دارد.
در مقابل، رویکرد ReAct در smolagents مزایای زیر را ارائه می‌دهد:
- اصلاح تکرارشونده: توانایی تشخیص نتایج مشکوک یا خالی و تلاش مجدد به‌صورت خودکار.
- طرحواره‌های قابل تعویض سریع (Hot-Swappable): طرحواره در توصیف ابزار قرار دارد و می‌تواند در لحظه به‌روزرسانی شود.
- انعطاف‌پذیری: با تنظیم ساده مدل یا ابزار، در مواجهه با JOINهای پیچیده، زیرکوئری‌ها (subqueries) و فیلترهای تودرتو بهتر مقیاس می‌گیرد.
در نهایت، جهش کیفیت از این می‌آید که به مدل «علیت» یا agency داده شود تا مشاهده و اصلاح کند. وقتی مدل می‌بیند که یک کوئری به‌طور غیرمنتظره‌ای صفر ردیف برگردانده است، می‌تواند فرضیه بزند که چرا اتصال جداول شکست خورده و عبارت SQL را در لحظه بازنویسی کند.
توسعه‌دهندگان اکنون می‌توانند این الگو را با استفاده از مخزن smolagents پیاده کنند و نمونه «Self-correcting Text-to-SQL» آماده اجرا در Google Colab و SageMaker Studio Lab است.
گام بعدی شما
- مخزن smolagents در گیت‌هاب را بررسی کنید و نمونه «Self-correcting Text-to-SQL» را در Google Colab اجرا نمایید.
- اگر از سیستم‌های Text-to-SQL سنتی استفاده می‌کنید، مدل خود را از حالت «تولید مستقیم» به حالت «تولید-مشاهده-اصلاح» تغییر دهید.
- برای کوئری‌های پیچیده، مدل‌های استدلالی (Reasoning Models) با پارامترهای بالاتر را جایگزین مدل‌های کوچک کنید.
اما داستان سخت‌افزاری این تحول و نحوه اجرای مدل‌های ۸۰ میلیارد پارامتری در محیط‌های سبک، حتی شگفت‌انگیزتر است؛ به تحلیل ما درباره ترازهای محاسباتی در لبه مراجعه کنید.
گفتگو