BIRD-INTERACT 1.0

⚠️ 공지

👉 제출 가이드라인이 업데이트되었으며, 커스텀 에이전트 스캐폴드를 지원합니다. 자세한 제출 가이드라인은 여기에서 확인하실 수 있습니다.

📰 소식

• [2026-03-29] 🔥🔥🔥 BIRD-Interact-ADK: BIRD-Interact-ADK를 출시했습니다. Google ADK 기반으로, 모듈형 3-마이크로서비스(에이전트, 사용자 시뮬레이터, DB 환경) 아키텍처를 제공합니다. 본인만의 에이전트, 사용자 시뮬레이터, DB 환경을 쉽게 교체할 수 있습니다. 병렬 실행과 LiteLlm 호환 LLM 제공자를 모두 지원합니다. 연구에 이 구현체 사용을 권장합니다.
• [2026-02-08] 🔥🔥🔥 저희 Bird-Interact 논문이 ICLR 2026 (Oral)에 채택되었습니다! 리우에서 만나요 🇧🇷!
• [2025-11-06] 🐛 버그 수정 & 🐳 Docker 업데이트: 사용자 시뮬레이터의 SQL 파서를 올바르게 해석하지 못하는 버그를 해결하기 위해 sqlglot 버전을 26.16.4로 업데이트했습니다. bird_interact_eval 환경에서 pip install sqlglot==26.16.4로 재설치하시면 됩니다. bird_interact_eval 이미지를 업데이트했으니, 새로 이미지를 pull하고 컨테이너를 재생성해도 됩니다.
• [2025-10-21] 🐳 Docker 업데이트: Full DB Env용 도커 이미지를 추가했습니다. Base/Full DB Env 및 평가 환경(a-Interact와 c-Interact 모두 적용)용 3개 이미지를 Docker Hub에 업로드하였으니, DB 덤프를 수동으로 다운로드하거나 이미지를 직접 빌드하지 않아도 됩니다!
• [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 코드에서 phase-2 SQL 평가 시, 저장된 phase-1 SQL이 정상적으로 실행되지 않아 Phase-2 성공률이 낮아지는 버그를 수정했습니다. 이 버그는 phase1 sql이 데이터베이스에서 CREATE table 등 작업을 수행하는 과제에만 영향을 미칩니다.

🧸 개요

BIRD-INTERACT는 인터랙티브 텍스트-to-SQL 벤치마크로, 동적 상호작용의 관점에서 Text-to-SQL 평가를 재구성합니다. 이 환경은 계층적 지식베이스, 데이터베이스 문서, 함수 기반 사용자 시뮬레이터를 결합하여 실제 기업 환경을 완전한 CRUD 작업 전반에 걸쳐 재현합니다. 엄격한 두 가지 테스트 모드: (1) 수동 대화형 상호작용과 (2) 능동 Agentic 상호작용을 제공하며, BI, CRUD 등 600개의 주석이 달린 과제와 실행 가능한 테스트 케이스로 보호됩니다. 일반 평가에서는 모델과 사용자 시뮬레이터 간에 1,968~5,496회 상호작용 턴이 발생하며, 최신 추론 모델은 현재 과제의 약 24%와 약 18%만 해결하여 벤치마크의 난이도를 보여줍니다.

✅ 두 가지 평가 모드

BIRD-INTERACT는 위에서 언급한 두 가지 평가 모드를 지원합니다:

• c-Interact: 대화형 상호작용으로, 수동 모드이며 워크플로우가 고정되어 있습니다. 코드와 자세한 정보는 bird_interact_conv에서 확인할 수 있습니다.
• a-Interact: Agentic 상호작용으로, 모델이 주도하는 능동적이고 워크플로우가 동적입니다. 코드와 자세한 정보는 bird_interact_agent에서 확인할 수 있습니다.

🐣 라이트 버전

BIRD-INTERACT의 라이트 버전인 bird-interact-lite-exp를 공개합니다. 이 버전은 PostgreSQL을 위한 270개의 고품질 실제 과제를 포함하고 있습니다. 빠른 실험에 적합한 출발점입니다.

🦜 풀 버전

BIRD-INTERACT의 풀 버전인 bird-interact-full은 PostgreSQL을 위한 600개의 과제를 포함하는 종합 벤치마크입니다. 다양한 SQL 작업과 사용자 쿼리를 포괄합니다. 풀 버전은 곧 출시될 예정입니다.

BIRD-INTERACT-FULL에서의 모델 성능 결과

#### 1. c-Interact Text-to-SQL 성능 | 순위 | 모델명 | 정규화 보상 | 평균 비용 (USD)/작업 | 등급 | |:----:|:-------------------|:-----------------:|:-------------------:|:--------------------:| | 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 성능 | 순위 | 모델명 | 정규화 보상 | 평균 비용 (USD)/작업 | 등급 | |:----:|:-------------------|:-----------------:|:-------------------:|:--------------------------:| | 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*s 로 측정됩니다. 자세한 내용은 bird_interact_agent/README.md을 참조하세요.

상호작용 시간 스케일링(ITS)

상호작용 시간 스케일링(ITS)은 모델이 다회전 상호작용을 통해 최종 성능을 지속적으로 높일 수 있는 능력을 의미합니다. 이 상호작용 성능이 명확하게 지정된 단일 회차 작업에서 모델의 이상적 성능을 초과할 때, 해당 모델이 ITS 법칙을 만족한다고 합니다. 사용자의 인내심이 커지고 상호작용 횟수가 누적될수록 성능이 계속 향상되어, 모델이 장기간 대화에서도 효과적으로 소통할 수 있음을 보여줍니다. 현재로서는 claude-3-7-sonnet만이 ITS 법칙을 만족하는 것으로 확인되었습니다.

환경 설정

• bird-interact-lite 데이터베이스, bird-interact-full 데이터베이스, 평가 환경용 Docker 컨테이너를 실행하세요:

   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에서 미리 빌드된 이미지를 사용하여 3개의 컨테이너를 실행합니다:
   
bird_interact_postgresql: bird-interact-lite용 PostgreSQL 데이터베이스

   
bird_interact_postgresql_full: bird-interact-full용 PostgreSQL 데이터베이스

   
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
   `
   오류가 발생하면 "Errors occurred during import:"가 로그 파일에 출력됩니다.
 데이터베이스 컨테이너가 정상인지 확인하세요.
   
   
제공된 Python 스크립트를 사용하여 데이터베이스 메타데이터를 확인하세요:
   `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: 
     
📈 총 데이터베이스: 18
     
📋 총 테이블: 175
     
🔢 총 컬럼: 2286
     
📈 테이블당 평균 행 수: 1,038.48
     
💾 총 크기: 207.15 MB (대략)
   
bird-interact-full: 
     
📈 총 데이터베이스: 22
     
📋 총 테이블: 244
     
🔢 총 컬럼: 2011
     
📈 테이블당 평균 행 수: 1,121.19
     
💾 총 크기: 272.00 MB (대략)

📦 데이터셋 상세
데이터셋 설명
데이터베이스: 전체 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 데이터셋 카드: PostgreSQL용 bird-interact-lite
  
및 bird-interact-full; SQLite용 mini-interact
데이터셋 사용
데이터 유출을 방지하기 위해, GT 솔루션 SQL 및 테스트 케이스는 데이터와 함께 포함되어 있지 않습니다.
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, mini 버전 등. 공개 데이터와 정답 및 테스트 케이스의 경로만 올바르게 설정한 다음, 공개 데이터를 결합된 데이터로 교체하면 됩니다.