BIRD-INTERACT 1.0

⚠️ Thông báo

👉 Chúng tôi đã cập nhật Hướng dẫn Nộp Bài, nơi đã hỗ trợ các scaffold tác nhân tùy chỉnh. Vui lòng xem chi tiết hướng dẫn nộp bài tại đây.

📰 Tin tức

• [2026-03-29] 🔥🔥🔥 BIRD-Interact-ADK: Chúng tôi phát hành BIRD-Interact-ADK, một triển khai dựa trên Google ADK với kiến trúc module 3-microservices (tác nhân, mô phỏng người dùng và môi trường DB). Dễ dàng thay thế tác nhân, mô phỏng người dùng hoặc môi trường DB của riêng bạn. Hỗ trợ thực thi song song và mọi nhà cung cấp LLM tương thích LiteLlm. Khuyến nghị sử dụng triển khai này cho nghiên cứu của bạn.
• [2026-02-08] 🔥🔥🔥 Bài báo Bird-Interact của chúng tôi đã được chấp nhận tại ICLR 2026 (Oral)! Hẹn gặp tại Rio 🇧🇷!
• [2025-11-06] 🐛 Sửa lỗi & 🐳 Cập nhật Docker: Cập nhật phiên bản sqlglot lên 26.16.4 để sửa lỗi trình phân tích SQL không thể phân tích SQL đúng cho mô phỏng người dùng. Bạn có thể sửa bằng cách cài lại pip install sqlglot==26.16.4 trong môi trường bird_interact_eval. Ảnh bird_interact_eval cũng đã được cập nhật, bạn cũng có thể pull về và tạo lại container bird_interact_eval.
• [2025-10-21] 🐳 Cập nhật Docker: Chúng tôi đã thêm docker cho Full DB Env. Và chúng tôi đã đẩy 3 ảnh docker (Base/Full DB Env và môi trường đánh giá cho cả a-Interact và c-Interact) lên Docker Hub để đơn giản hóa việc thiết lập môi trường. Không cần tải DB dumps hay build ảnh thủ công!
• [2025-10-08] 📝 Bài báo Bird-Interact của chúng tôi hiện đã công khai!

• [2025-08-26] 🚀 Chúng tôi vui mừng thông báo phát hành bộ BIRD-Interact-Full (600)!

• [2025-08-26] 📬 Chúng tôi sẽ gửi Ground Truth & Test cases tới danh sách email của mình trong tuần này.

• [2025-08-26] 💾 Ngoài ra, chúng tôi cũng đã phát hành phiên bản SQLite của LiveSQLBench-Lite để hỗ trợ nghiên cứu cục bộ dễ dàng hơn.

• [2025-08-22] Sửa lỗi: Trong mã Bird-Interact-Agent, chúng tôi đã sửa một lỗi khiến khi đánh giá SQL phase-2, câu lệnh SQL phase-1 đã lưu không thể thực thi thành công, dẫn đến tỷ lệ thành công của Phase-2 thấp hơn. Lỗi này chỉ ảnh hưởng đến những tác vụ mà SQL phase1 thực hiện các thao tác trên cơ sở dữ liệu, ví dụ như CREATE table, v.v.

🧸 Tổng quan

BIRD-INTERACT, một bộ chuẩn đánh giá chuyển đổi văn bản sang SQL tương tác, tái định hình việc đánh giá Text-to-SQL dưới góc nhìn của các tương tác động. Môi trường kết hợp cơ sở tri thức phân cấp, tài liệu cơ sở dữ liệu và trình mô phỏng người dùng theo chức năng để tái tạo bối cảnh doanh nghiệp thực tế trên đầy đủ các thao tác CRUD. Nó cung cấp hai chế độ kiểm thử nghiêm ngặt: (1) Tương tác hội thoại thụ động và (2) Tương tác đại lý chủ động, bao quát 600 tác vụ được chú thích gồm Business Intelligence (BI), thao tác CRUD, v.v., mỗi tác vụ đều có các trường hợp kiểm thử thực thi được. Các lần đánh giá điển hình kích hoạt từ 1.968 đến 5.496 lượt tương tác giữa mô hình và trình mô phỏng người dùng, trong khi các mô hình suy luận hiện đại hiện chỉ giải được ≈24% và ≈18% tác vụ, cho thấy độ khó của bộ chuẩn này.

✅ Hai chế độ đánh giá

BIRD-INTERACT hỗ trợ hai chế độ đánh giá như đã đề cập ở trên:

• c-Interact: Tương tác hội thoại là chế độ thụ động với luồng công việc cố định. Mã nguồn và thông tin chi tiết có tại bird_interact_conv.
• a-Interact: Tương tác đại lý là chế độ chủ động nhập vai, luồng công việc động và do mô hình dẫn dắt. Mã nguồn và thông tin chi tiết có tại bird_interact_agent.

🐣 Phiên bản nhẹ

Chúng tôi phát hành phiên bản nhẹ của BIRD-INTERACT, bird-interact-lite-exp, bao gồm 270 tác vụ thực tế chất lượng cao dành riêng cho PostgreSQL. Đây là điểm khởi đầu tốt để thử nghiệm nhanh.

🦜 Phiên bản đầy đủ

Phiên bản đầy đủ của BIRD-INTERACT, bird-interact-full, là bộ chuẩn toàn diện bao gồm 600 tác vụ cho PostgreSQL. Nó bao phủ đa dạng các thao tác SQL và truy vấn người dùng. Phiên bản đầy đủ sẽ ra mắt sớm.

Kết quả hiệu suất mô hình trên BIRD-INTERACT-FULL

#### 1. Hiệu suất c-Interact Text-to-SQL | Hạng | Tên Mô hình | Phần thưởng Chuẩn hóa | Chi phí TB (USD)/Nhiệm vụ | Cấp độ | |:----:|:--------------------|:---------------------:|:-------------------------:|:--------------------:| | 1 | Gemini-2.5-Pro | 20.92 | $0.04 | 🏆 Chat Xuất sắc | | 2 | O3-Mini | 20.27 | $0.07 | 🏆 Chat Xuất sắc | | 3 | Claude-Sonnet-4 | 18.35 | $0.29 | 💎 Chat Tốt | | 4 | Qwen-3-Coder-480B | 17.75 | $0.11 | 💎 Chat Tốt | | 5 | Deepseek-Chat-V3.1 | 15.15 | $0.12 | ✨ Tiêu chuẩn | | 6 | Claude-Sonnet-3.7 | 13.87 | $0.29 | ✨ Tiêu chuẩn | | 7 | GPT-5 | 12.58 | $0.08 | ⚪ Cơ bản |

#### 2. Hiệu suất a-Interact Text-to-SQL | Hạng | Tên Mô hình | Phần thưởng Chuẩn hóa | Chi phí TB (USD)/Nhiệm vụ | Cấp độ | |:----:|:--------------------|:---------------------:|:-------------------------:|:---------------------------:| | 1 | GPT-5 | 25.52 | $0.24 | 🏆 Tương tác Xuất sắc | | 2 | Claude-Sonnet-4 | 23.28 | $0.51 | 🏆 Tương tác Xuất sắc | | 3 | Claude-Sonnet-3.7 | 17.45 | $0.60 | 💎 Tương tác Tốt | | 4 | Gemini-2.5-Pro | 17.33 | $0.22 | 💎 Tương tác Tốt | | 5 | O3-Mini | 16.43 | $0.06 | ✨ Tiêu chuẩn | | 6 | Deepseek-Chat-V3.1 | 13.47 | $0.06 | ✨ Tiêu chuẩn | | 7 | Qwen-3-Coder-480B | 10.58 | $0.07 | ⚪ Cơ bản |

\ Tham số ngân sách: Ngân sách ban đầu/Ngân sách kiên nhẫn người dùng, được đo bằng đơn vị tiền ảo bird-coin*s . Xem thêm tại bird_interact_agent/README.md để biết chi tiết.

Tăng quy mô Thời gian Tương tác (ITS)

Tăng quy mô Thời gian Tương tác (ITS) là khả năng của mô hình liên tục nâng cao hiệu suất cuối cùng thông qua các lượt tương tác đa vòng. Khi hiệu suất tương tác này vượt qua hiệu suất lý tưởng hóa của mô hình trong một lượt đơn trên tác vụ đầy đủ, rõ ràng, chúng tôi nói rằng nó thỏa mãn định luật ITS. Khi sự kiên nhẫn của người dùng tăng và số lượt tương tác tích lũy, hiệu suất tiếp tục được cải thiện, chứng tỏ mô hình có thể duy trì giao tiếp hiệu quả qua đối thoại kéo dài. Hiện tại, chỉ claude-3-7-sonnet thỏa mãn định luật ITS.

Thiết lập môi trường

• Khởi chạy các container Docker cho cơ sở dữ liệu bird-interact-lite, cơ sở dữ liệu bird-interact-full và môi trường đánh giá:

   cd env
   docker compose pull 
   docker compose up -d
   ``
   Chờ vài phút để khởi tạo cơ sở dữ liệu.
  Bạn có thể theo dõi tiến trình xây dựng bằng cách:
  `bash
  docker compose logs -f --tail=100 bird_interact_postgresql_full # or bird_interact_postgresql for bird-interact-lite
  `
  Nếu hoàn thành, bạn sẽ thấy các bản ghi mà không có lỗi như sau:
  `bash
  bird_interact_postgresql_full  | 2025-10-28 17:58:30.413 HKT [1] LOG:  database system is ready to accept connection
  `
  
  Nếu bạn đã tạo các container trước đó và muốn tạo lại chúng, bạn có thể chạy lệnh sau:
  `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.
  `
   
   Điều này chạy 3 container sử dụng các ảnh dựng sẵn từ Docker Hub:
   
bird_interact_postgresql: Cơ sở dữ liệu PostgreSQL cho bird-interact-lite

   
bird_interact_postgresql_full: Cơ sở dữ liệu PostgreSQL cho bird-interact-full

   
bird_interact_eval: Môi trường đánh giá cho cả a-Interact và c-Interact.
   
Bây giờ, bạn có thể khởi động môi trường đánh giá bằng cách thực hiện lệnh sau:
   `bash
   docker compose exec bird_interact_eval bash
   `
(Tùy chọn) Tự xây dựng môi trường (nếu bạn muốn xây dựng các image từ đầu):
   
Tải về các file dump của cơ sở dữ liệu
      
bird-interact-lite. Giải nén và đổi tên thành env/postgre_table_dumps.

      
bird-interact-full. Giải nén và đổi tên thành env/postgre_table_dumps_full.

   
Tự xây dựng môi trường bằng cách chạy docker-compose.build.yml.
      
`bash
      cd env/
      docker compose -f docker-compose.build.yml build
      docker compose -f docker-compose.build.yml up -d
      `
(Khuyến nghị) Kiểm tra các container cơ sở dữ liệu đã được xây dựng và chạy thành công.
In nhật ký xây dựng container để đảm bảo rằng các cơ sở dữ liệu đã được xây dựng thành công mà không có lỗi:
   `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
   `
   Nếu xảy ra lỗi, "Đã xảy ra lỗi trong quá trình nhập:" sẽ được in ra trong các tập tin nhật ký.
 Kiểm tra xem các container cơ sở dữ liệu có đang hoạt động tốt không.
   
   
Sử dụng script Python do chúng tôi cung cấp để xác minh siêu dữ liệu cơ sở dữ liệu:
   `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
   `
   
   Kết quả mong đợi:
   
bird-interact-lite: 
     
📈 Tổng số CSDL: 18
     
📋 Tổng số Bảng: 175
     
🔢 Tổng số Cột: 2286
     
📈 Số dòng trung bình mỗi bảng: 1.038,48
     
💾 Tổng dung lượng: 207,15 MB (xấp xỉ)
   
bird-interact-full: 
     
📈 Tổng số CSDL: 22
     
📋 Tổng số Bảng: 244
     
🔢 Tổng số Cột: 2011
     
📈 Số dòng trung bình mỗi bảng: 1.121,19
     
💾 Tổng dung lượng: 272,00 MB (xấp xỉ)

📦 Chi tiết Bộ Dữ Liệu
Mô tả Bộ Dữ Liệu
CSDL: Toàn bộ cơ sở dữ liệu PostgreSQL có thể tải xuống từ bird-interact-lite và bird-interact-full.
data: Mỗi mẫu dữ liệu bao gồm các phần chính sau:
   
selected_database: Tên của cơ sở dữ liệu.  

   
query: Câu truy vấn người dùng không mơ hồ.  

   
amb_user_query: Câu truy vấn người dùng đã được tiêm nhiễu mơ hồ.

   
user_query_ambiguity: Các điểm mơ hồ được tiêm vào truy vấn người dùng.

   
non_critical_ambiguity: Các mơ hồ không quan trọng như order, limit, v.v.

   
knowledge_ambiguity: Các điểm mơ hồ do kiến thức bên ngoài bị che giấu tạo ra. 

   
sol_sql: Giải pháp SQL chuẩn xác.  

   
preprocess_sql: Các truy vấn SQL cần chạy trước khi thực thi giải pháp hoặc dự đoán.  

   
clean_up_sql: Các truy vấn SQL cần chạy sau khi kiểm thử để hoàn nguyên thay đổi trên CSDL.  

   
test_cases: Tập hợp các trường hợp kiểm thử để xác thực SQL dự đoán đã sửa.

   
follow_up: Các câu hỏi tiếp theo đã được gán nhãn.

   
external_knowledge: Kiến thức bên ngoài liên quan đến tác vụ cụ thể.
evaluation: Mã đánh giá có trong thư mục ./evaluation.

Được biên soạn bởi: Nhóm BIRD & Google Cloud
Giấy phép: cc-by-sa-4.0
Thẻ Bộ Dữ Liệu HuggingFace: bird-interact-lite
  
và bird-interact-full cho PostgreSQL; và mini-interact cho SQLite.
Sử dụng Bộ Dữ Liệu
Để tránh rò rỉ dữ liệu do tự động thu thập, chúng tôi không bao gồm các sql giải pháp GT và các trường hợp kiểm thử cùng với dữ liệu.
vui lòng gửi email tới bird.bench25@gmail.com với tiêu đề chứa thẻ [bird-interact-lite GT&Test Cases] hoặc [bird-interact-full GT&Test Cases] để nhận bộ dữ liệu ground truth và các trường hợp kiểm thử cho bộ dữ liệu bird-interact-lite hoặc bird-interact-full, sẽ được gửi tự động.
Kết hợp dữ liệu công khai với ground truth và các trường hợp kiểm thử
Sau đó sử dụng đoạn script sau để kết hợp dữ liệu công khai với ground truth và các trường hợp kiểm thử:
Lấy phiên bản đầy đủ làm ví dụ:
(1) Chạy:

Điều này sẽ tạo một tệp mới tại /path/to/bird_interact_data.jsonl với dữ liệu đã được kết hợp.
(2) Sau đó thay thế dữ liệu công khai gốc bằng dữ liệu đã kết hợp:

Tương tự cho các phiên bản khác: bird-interact-lite, phiên bản mini, v.v. Chỉ cần đặt đúng đường dẫn cho dữ liệu công khai, dữ liệu thực tế và các trường hợp kiểm thử, sau đó thay thế dữ liệu công khai bằng dữ liệu đã kết hợp.