BIRD-INTERACT 1.0

⚠️ اطلاعیه

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

📰 اخبار

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

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

• [2025-08-26] 📬 ما این هفته موارد حقیقت زمین و تست را به لیست ایمیل خود ارسال خواهیم کرد.

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

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

🧸 نمای کلی

BIRD-INTERACT، یک بنچمارک تعاملی تبدیل متن به 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

#### ۱. عملکرد c-Interact Text-to-SQL | رتبه | نام مدل | پاداش نرمال‌شده | هزینه متوسط (دلار)/وظیفه | سطح | |:----:|:-------------------|:-----------------:|:-------------------:|:------------------:| | 1 | Gemini-2.5-Pro | 20.92 | $0.04 | 🏆 چت عالی | | 2 | O3-Mini | 20.27 | $0.07 | 🏆 چت عالی | | 3 | Claude-Sonnet-4 | 18.35 | $0.29 | 💎 چت خوب | | 4 | Qwen-3-Coder-480B | 17.75 | $0.11 | 💎 چت خوب | | 5 | Deepseek-Chat-V3.1 | 15.15 | $0.12 | ✨ استاندارد | | 6 | Claude-Sonnet-3.7 | 13.87 | $0.29 | ✨ استاندارد | | 7 | GPT-5 | 12.58 | $0.08 | ⚪ پایه‌ای |

#### 2. عملکرد a-Interact Text-to-SQL | رتبه | نام مدل | پاداش نرمال‌شده | متوسط هزینه (دلار)/وظیفه | سطح | |:----:|:-------------------|:-----------------:|:-------------------:|:------------------------:| | 1 | GPT-5 | 25.52 | $0.24 | 🏆 تعامل عالی | | 2 | Claude-Sonnet-4 | 23.28 | $0.51 | 🏆 تعامل عالی | | 3 | Claude-Sonnet-3.7 | 17.45 | $0.60 | 💎 تعامل خوب | | 4 | Gemini-2.5-Pro | 17.33 | $0.22 | 💎 تعامل خوب | | 5 | O3-Mini | 16.43 | $0.06 | ✨ استاندارد | | 6 | Deepseek-Chat-V3.1 | 13.47 | $0.06 | ✨ استاندارد | | 7 | Qwen-3-Coder-480B | 10.58 | $0.07 | ⚪ پایه‌ای |

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

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

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

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

• کانتینرهای داکر مربوط به پایگاه داده 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
موارد استفاده از دیتاست
برای جلوگیری از نشت داده‌ها از طریق خزیدن خودکار، راه‌حل‌های 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، نسخه مینی و غیره. فقط مسیرهای صحیح را برای داده‌های عمومی، داده‌های حقیقت مبنا و داده‌های تست تنظیم کنید و سپس داده‌های عمومی را با داده‌های ترکیبی جایگزین نمایید.