BIRD-INTERACT 1.0

⚠️ اطلاعیه

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

📰 اخبار

• [۲۰۲۵-۱۱-۰۶] 🐛 رفع باگ و 🐳 به‌روزرسانی داکر: نسخه sqlglot به 26.16.4 ارتقا یافت تا باگی که باعث می‌شد تجزیه‌گر SQL نتواند SQL را برای شبیه‌ساز کاربر به‌درستی تجزیه کند، رفع شود. شما می‌توانید با اجرای دستور pip install sqlglot==26.16.4 در محیط bird_interact_eval این مشکل را رفع کنید. همچنین ایمیج bird_interact_eval نیز به‌روزرسانی شده و می‌توانید آن را مجدداً دریافت و کانتینر را بازسازی کنید.
• [۲۰۲۵-۱۰-۲۱] 🐳 به‌روزرسانی داکر: داکر محیط پایگاه‌داده کامل اضافه شد. همچنین سه ایمیج داکر (محیط پایه/کامل و محیط ارزیابی برای هر دو a-Interact و c-Interact) در Docker Hub قرار داده شده‌اند تا راه‌اندازی محیط راحت‌تر باشد. دیگر نیازی به دانلود دستی دامپ‌های پایگاه‌داده و ساخت ایمیج نیست!
• [۲۰۲۵-۱۰-۰۸] 📝 مقاله Bird-Interact ما اکنون به صورت عمومی در دسترس است!

• [۲۰۲۵-۰۸-۲۶] 🚀 با خوشحالی اعلام می‌کنیم که مجموعه BIRD-Interact-Full (600) منتشر شد!

• [۲۰۲۵-۰۸-۲۶] 📬 این هفته Ground Truth & Test cases را به لیست ایمیل ارسال خواهیم کرد.

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

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

🧸 مرور کلی

BIRD-INTERACT، یک بنچمارک تعاملی متن به SQL است که ارزیابی Text-to-SQL را از منظر تعاملات پویا بازآفرینی می‌کند. این محیط با ترکیب یک پایگاه دانش سلسله‌مراتبی، مستندات پایگاه داده و شبیه‌ساز کاربر مبتنی بر عملکرد، محیط‌های واقعی سازمانی را در عملیات کامل CRUD بازسازی می‌کند. دو حالت تست سختگیرانه ارائه می‌دهد: (1) تعامل مکالمه‌ای غیرفعال و (2) تعامل عاملانه فعال، شامل 600 وظیفه حاشیه‌نویسی شده مانند هوش تجاری (BI)، عملیات CRUD و غیره، که هر کدام با موارد تست اجرایی محافظت می‌شوند. ارزیابی‌های معمول بین 1,968 تا 5,496 نوبت تعامل بین مدل و شبیه‌ساز کاربر را ایجاد می‌کنند، در حالی که مدل‌های استنتاج پیشرفته فعلاً فقط ≈24% و ≈18% وظایف را حل می‌کنند که چالش‌برانگیز بودن این بنچمارک را نشان می‌دهد.

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

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 | 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 این قانون را ارضا می‌کند.

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

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