BIRD-INTERACT 1.0

⚠️ اطلاعیه

👉 ما راهنمای ارسال را به‌روزرسانی کرده‌ایم که در آن اسکافولدهای عامل سفارشی نیز پشتیبانی می‌شوند. لطفاً برای مشاهده جزئیات راهنمای ارسال ما اینجا را ببینید.

📰 اخبار

• [2026-03-29] 🔥🔥🔥 BIRD-Interact-ADK: ما BIRD-Interact-ADK را منتشر کردیم، یک پیاده‌سازی مبتنی بر Google ADK با معماری ماژولار شامل ۳ میکروسرویس (عامل، شبیه‌ساز کاربر و محیط پایگاه داده). می‌توانید به سادگی عامل، شبیه‌ساز کاربر یا محیط پایگاه داده خودتان را جایگزین کنید. از اجرای موازی و هر ارائه‌دهنده LLM سازگار با LiteLlm پشتیبانی می‌کند. توصیه می‌کنیم برای تحقیقات خود از این پیاده‌سازی استفاده کنید.
• [2026-02-08] 🔥🔥🔥 مقاله Bird-Interact ما در ICLR 2026 (Oral) پذیرش شد! در ریودوژانیرو 🇧🇷 می‌بینیمتان!
• [2025-11-06] 🐛 رفع اشکال و 🐳 به‌روزرسانی Docker: نسخه sqlglot به 26.16.4 به‌روزرسانی شد تا اشکال عدم توانایی تجزیه صحیح SQL توسط شبیه‌ساز کاربر برطرف شود. می‌توانید با اجرای pip install sqlglot==26.16.4 در محیط bird_interact_eval این مشکل را برطرف کنید. تصویر bird_interact_eval نیز به‌روزرسانی شده است، بنابراین می‌توانید آن را دریافت و کانتینر bird_interact_eval را مجدداً بسازید.
• [2025-10-21] 🐳 به‌روزرسانی Docker: ما داکر محیط پایگاه داده کامل (Full DB Env) را اضافه کردیم. همچنین ۳ تصویر داکر (پایه/کامل و محیط ارزیابی برای هر دو a-Interact و c-Interact) را به Docker Hub ارسال کردیم تا راه‌اندازی محیط را آسان‌تر کنیم. دیگر نیازی به دانلود dump پایگاه داده و ساخت دستی تصویرها نیست!
• [2025-10-08] 📝 مقاله Bird-Interact اکنون به صورت عمومی در دسترس است!

• [2025-08-26] 🚀 با هیجان اعلام می‌کنیم که مجموعه BIRD-Interact-Full (600) منتشر شد!

• [2025-08-26] 📬 ما این هفته داده‌های Ground Truth و Test cases را به لیست ایمیل خود ارسال خواهیم کرد.

• [2025-08-26] 💾 همچنین نسخه SQLite از LiveSQLBench-Lite را برای تحقیقات محلی آسان‌تر منتشر کرده‌ایم.

• [2025-08-22] رفع اشکال: در کد Bird-Interact-Agent، باگی را رفع کردیم که هنگام ارزیابی SQL فاز-۲، اجرای موفق SQL ذخیره‌شده فاز-۱ ممکن نبود و باعث کاهش نرخ موفقیت فاز-۲ می‌شد. این باگ فقط بر کارهایی تأثیر داشت که در آن‌ها SQL فاز۱ عملیاتی روی پایگاه داده انجام می‌دهد، مانند CREATE table و غیره.

🧸 نمای کلی

BIRD-INTERACT، یک بنچمارک تعاملی text-to-SQL است که ارزیابی Text-to-SQL را از دریچه تعاملات پویا بازآفرینی می‌کند. این محیط، یک پایگاه دانش سلسله‌مراتبی، مستندات پایگاه داده و یک شبیه‌ساز کاربر مبتنی بر عملکرد را ترکیب می‌کند تا محیط‌های سازمانی واقعی را برای انجام کامل عملیات CRUD بازسازی کند. دو حالت آزمایشی سخت‌گیرانه ارائه می‌دهد: (1) تعامل مکالمه‌ای منفعل و (2) تعامل عاملی فعال، که شامل ۶۰۰ تسک حاشیه‌نویسی‌شده از جمله هوش تجاری (BI)، عملیات CRUD و غیره است و هرکدام با موارد تست قابل اجرا محافظت می‌شوند. ارزیابی‌های معمول بین ۱۹۶۸ تا ۵۴۹۶ دور تعامل بین مدل و شبیه‌ساز کاربر ایجاد می‌کند، در حالی که مدل‌های استدلال پیشرفته فعلی فقط ≈۲۴٪ و ≈۱۸٪ از تسک‌ها را حل می‌کنند که دشواری این بنچمارک را نشان می‌دهد.

✅ دو حالت ارزیابی

BIRD-INTERACT دو حالت ارزیابی زیر را پشتیبانی می‌کند:

• c-Interact: تعامل مکالمه‌ای که حالت منفعل است و روند کاری ثابتی دارد. کد و اطلاعات جزئی در bird_interact_conv موجود است.
• a-Interact: تعامل عاملی که حالت فعال و تجسم‌یافته است، روند کاری پویا است و توسط مدل‌ها هدایت می‌شود. کد و اطلاعات جزئی در bird_interact_agent موجود است.

🐣 نسخه سبک

ما نسخه سبک BIRD-INTERACT به نام bird-interact-lite-exp را منتشر کرده‌ایم که شامل ۲۷۰ تسک واقعی با کیفیت بالا ویژه PostgreSQL است. این نسخه برای آزمایش سریع نقطه شروع مناسبی است.

🦜 نسخه کامل

نسخه کامل BIRD-INTERACT با نام bird-interact-full یک بنچمارک جامع است که شامل ۶۰۰ تسک برای PostgreSQL می‌باشد. این نسخه دامنه گسترده‌ای از عملیات SQL و پرسش‌های کاربری را پوشش می‌دهد. نسخه کامل به‌زودی منتشر خواهد شد.

نتایج عملکرد مدل‌ها بر روی BIRD-INTERACT-FULL

#### 1. عملکرد c-Interact Text-to-SQL | رتبه | نام مدل | پاداش نرمال‌شده | هزینه متوسط (دلار)/وظیفه | سطح | |:----:|:-------------------|:--------------------:|:-------------------------:|:-------------------:| | 1 | Gemini-2.5-Pro | ۲۰.۹۲ | $۰.۰۴ | 🏆 چت عالی | | 2 | O3-Mini | ۲۰.۲۷ | $۰.۰۷ | 🏆 چت عالی | | 3 | Claude-Sonnet-4 | ۱۸.۳۵ | $۰.۲۹ | 💎 چت خوب | | 4 | Qwen-3-Coder-480B | ۱۷.۷۵ | $۰.۱۱ | 💎 چت خوب | | 5 | Deepseek-Chat-V3.1 | ۱۵.۱۵ | $۰.۱۲ | ✨ استاندارد | | 6 | Claude-Sonnet-3.7 | ۱۳.۸۷ | $۰.۲۹ | ✨ استاندارد | | 7 | GPT-5 | ۱۲.۵۸ | $۰.۰۸ | ⚪ پایه‌ای |

#### 2. عملکرد a-Interact Text-to-SQL | رتبه | نام مدل | پاداش نرمال‌شده | هزینه متوسط (دلار)/وظیفه | سطح | |:----:|:-------------------|:--------------------:|:-------------------------:|:--------------------------:| | 1 | GPT-5 | ۲۵.۵۲ | $۰.۲۴ | 🏆 تعامل عالی | | 2 | Claude-Sonnet-4 | ۲۳.۲۸ | $۰.۵۱ | 🏆 تعامل عالی | | 3 | Claude-Sonnet-3.7 | ۱۷.۴۵ | $۰.۶۰ | 💎 تعامل خوب | | 4 | Gemini-2.5-Pro | ۱۷.۳۳ | $۰.۲۲ | 💎 تعامل خوب | | 5 | O3-Mini | ۱۶.۴۳ | $۰.۰۶ | ✨ استاندارد | | 6 | Deepseek-Chat-V3.1 | ۱۳.۴۷ | $۰.۰۶ | ✨ استاندارد | | 7 | Qwen-3-Coder-480B | ۱۰.۵۸ | $۰.۰۷ | ⚪ پایه‌ای |

\ پارامترهای بودجه: بودجه شروع/بودجه صبر کاربر، با واحد ارز مجازی bird-coin* اندازه‌گیری شده است. برای اطلاعات بیشتر به bird_interact_agent/README.md مراجعه کنید.

مقیاس‌گذاری زمان تعامل (ITS)

مقیاس‌گذاری زمان تعامل (ITS) به توانایی یک مدل برای افزایش مداوم عملکرد نهایی خود در تعاملات چندمرحله‌ای اشاره دارد. وقتی این عملکرد تعاملی از عملکرد ایده‌آل مدل در یک وظیفه کاملاً مشخص و بدون ابهام فراتر رود، می‌گوییم مدل از قانون ITS پیروی می‌کند. با افزایش صبر کاربر و تعداد نوبت‌های تعامل، عملکرد بهبود می‌یابد و نشان می‌دهد مدل می‌تواند ارتباط مؤثر را در گفتگوی طولانی حفظ کند. در حال حاضر، تنها claude-3-7-sonnet این قانون را رعایت می‌کند.

راه‌اندازی محیط

• کانتینرهای Docker برای پایگاه داده bird-interact-lite، پایگاه داده bird-interact-full و محیط ارزیابی را اجرا کنید:

   cd env
   docker compose pull 
   docker compose up -d
   ``
   چند دقیقه منتظر بمانید تا پایگاه داده مقداردهی اولیه شود.
   
  شما می‌توانید پیشرفت ساخت را با موارد زیر پیگیری کنید:
  `bash
  docker compose logs -f --tail=100 bird_interact_postgresql_full # or bird_interact_postgresql for bird-interact-lite
  `
  اگر کار تمام شده باشد، باید لاگ‌ها را بدون خطا مشاهده کنید مانند:
  `bash
  bird_interact_postgresql_full  | 2025-10-28 17:58:30.413 HKT [1] LOG:  database system is ready to accept connection
  `
اگر قبلاً کانتینر ساخته‌اید و می‌خواهید آن را دوباره بسازید، می‌توانید فرمان زیر را اجرا کنید:
  `bash
  docker compose down -v # this cmd removes the containers and the volumes
  docker compose pull   # pull the latest images from Docker Hub
  docker compose up -d --force-recreate # build and start the containers again. --force-recreate means force the recreation of the containers. 
  # Or docker compose up -d --force-recreate bird_interact_eval to only recreate the bird_interact_eval container about evalution code environment.
  `
   
   این دستور ۳ کانتینر را با استفاده از ایمیج‌های آماده از Docker Hub اجرا می‌کند:
   
bird_interact_postgresql: پایگاه داده PostgreSQL برای bird-interact-lite

   
bird_interact_postgresql_full: پایگاه داده PostgreSQL برای bird-interact-full

   
bird_interact_eval: محیط ارزیابی برای هر دو a-Interact و c-Interact.
   
اکنون می‌توانید محیط ارزیابی را با اجرای دستور زیر راه‌اندازی کنید:
   `bash
   docker compose exec bird_interact_eval bash
   `
(اختیاری) محیط را به صورت دستی بسازید (اگر می‌خواهید تصاویر را از ابتدا بسازید): 
   
فایل‌های دامپ پایگاه داده را دانلود کنید 
      
bird-interact-lite. آن را از حالت فشرده خارج کرده و به نام env/postgre_table_dumps تغییر دهید.

      
bird-interact-full. آن را از حالت فشرده خارج کرده و به نام env/postgre_table_dumps_full تغییر دهید.

   
محیط را با اجرای docker-compose.build.yml به صورت دستی بسازید.

      
`bash
      cd env/
      docker compose -f docker-compose.build.yml build
      docker compose -f docker-compose.build.yml up -d
      `
(توصیه می‌شود) بررسی کنید که کانتینرهای پایگاه داده با موفقیت ساخته و اجرا شده‌اند.
لاگ‌های ساخت کانتینر را چاپ کنید تا مطمئن شوید پایگاه‌های داده بدون خطا ساخته شده‌اند:
   `bash 
   docker logs bird_interact_postgresql > build_bird_interact_postgresql.log 2>&1
   docker logs bird_interact_postgresql_full > build_bird_interact_postgresql_full.log 2>&1
   `
   اگر خطاهایی رخ دهند، "خطاها در هنگام وارد کردن رخ دادند:" در فایل‌های گزارش چاپ خواهد شد.
 بررسی کنید که کانتینرهای پایگاه داده در وضعیت مناسبی باشند.
   
   
از اسکریپت پایتون ارائه شده توسط ما برای بررسی متادیتای پایگاه داده استفاده کنید:
   `bash
   docker compose exec bird_interact_eval bash
   cd /app/env
   python check_db_metadata.py --host bird_interact_postgresql
   python check_db_metadata.py --host bird_interact_postgresql_full
   `
   
   نتایج مورد انتظار:
   
bird-interact-lite: 
     
📈 تعداد کل پایگاه‌های داده: ۱۸
     
📋 تعداد کل جداول: ۱۷۵
     
🔢 تعداد کل ستون‌ها: ۲۲۸۶
     
📈 میانگین تعداد ردیف در هر جدول: ۱٬۰۳۸.۴۸
     
💾 حجم کل: ۲۰۷.۱۵ مگابایت (تقریبی)
   
bird-interact-full: 
     
📈 تعداد کل پایگاه‌های داده: ۲۲
     
📋 تعداد کل جداول: ۲۴۴
     
🔢 تعداد کل ستون‌ها: ۲۰۱۱
     
📈 میانگین تعداد ردیف در هر جدول: ۱٬۱۲۱.۱۹
     
💾 حجم کل: ۲۷۲.۰۰ مگابایت (تقریبی)

📦 جزئیات مجموعه داده
توضیحات مجموعه داده
پایگاه داده: پایگاه داده کامل PostgreSQL را می‌توان از bird-interact-lite و bird-interact-full دانلود کرد.
data: هر نمونه داده شامل بخش‌های اصلی زیر است:
   
selected_database: نام پایگاه داده.  

   
query: پرسش کاربر بدون ابهام.  

   
amb_user_query: پرسش کاربر با ابهامات تزریق شده.

   
user_query_ambiguity: ابهامات تزریق شده در پرسش کاربر.

   
non_critical_ambiguity: ابهامات غیر بحرانی مانند ترتیب، محدودیت و غیره.

   
knowledge_ambiguity: ابهامات ایجاد شده توسط دانش‌های خارجی ماسک شده. 

   
sol_sql: راه‌حل SQL مرجع.  

   
preprocess_sql: کوئری‌های SQL که قبل از اجرای راه‌حل یا پیش‌بینی اجرا می‌شوند.  

   
clean_up_sql: کوئری‌های SQL که پس از اجرای تست برای بازگردانی تغییرات اعمال شده به پایگاه داده اجرا می‌شوند.  

   
test_cases: مجموعه‌ای از تست‌ها برای اعتبارسنجی SQL اصلاح شده پیش‌بینی شده.

   
follow_up: پرسش‌های پیگیری برچسب‌گذاری شده.

   
external_knowledge: دانش خارجی مرتبط با وظیفه خاص.
ارزیابی: کد ارزیابی در پوشه ./evaluation موجود است.

تدوین شده توسط: تیم BIRD و Google Cloud
مجوز: cc-by-sa-4.0
کارت مجموعه داده HuggingFace: bird-interact-lite
  
و bird-interact-full برای PostgreSQL؛ و mini-interact برای SQLite.
موارد استفاده از دیتاست
برای جلوگیری از نشت داده‌ها از طریق خزیدن خودکار، راه‌حل‌های GT و موارد تست را همراه با داده‌ها قرار نمی‌دهیم.
لطفاً برای دریافت داده‌های حقیقت پایه و موارد تست مربوط به دیتاست bird-interact-lite یا bird-interact-full، ایمیلی با عنوان [bird-interact-lite GT&Test Cases] یا [bird-interact-full GT&Test Cases] به آدرس bird.bench25@gmail.com ارسال نمایید تا اطلاعات به صورت خودکار برای شما ارسال گردد.
ترکیب داده‌های عمومی با حقیقت پایه و موارد تست
سپس از اسکریپت زیر برای ترکیب داده‌های عمومی با حقیقت پایه و موارد تست استفاده کنید:
نسخه کامل را به عنوان مثال در نظر بگیرید:
(1) اجرا کنید:

این کار یک فایل جدید در مسیر /path/to/bird_interact_data.jsonl با داده‌های ترکیبی ایجاد خواهد کرد.
(2) سپس داده‌های عمومی اصلی را با داده‌های ترکیبی جایگزین کنید:

برای نسخه‌های دیگر نیز همین کار را انجام دهید: bird-interact-lite، نسخه مینی و غیره. فقط مسیرهای صحیح را برای داده‌های عمومی، داده‌های حقیقت مبنا و داده‌های تست تنظیم کنید و سپس داده‌های عمومی را با داده‌های ترکیبی جایگزین نمایید.