MCP LLM Bm V3

🚀 TAU2-Bench (OpenRouter)

τ²-bench 기반 Multi-Turn Tool-Use 에이전트 벤치마크 - 5개 LLM 모델 평가 파이프라인

📋 TL;DR (3분 요약)

1. API 키 설정     →  cp .env.example .env && 키 입력
2. 450회 평가 실행  →  cd tau2-bench && ./run_quick_450.sh
3. 결과 확인       →  results/latest/전체_요약/TAU2_전체요약_latest.xlsx

🎯 τ²-bench란?

벤치마크 유형

핵심 철학

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   ❌ "정답 텍스트를 맞히는가?"                                       │
│                                                                     │
│   ✅ "에이전트가 도구를 사용해 DB를 변경하고 과업을 완수하는가?"      │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

3자 대화 구조

┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│   Agent     │◀─────▶│    User     │       │    Tool     │
│   (LLM)     │       │ (Simulator) │       │    (API)    │
└──────┬──────┘       └─────────────┘       └──────▲──────┘
       │                                           │
       │            tool_call 요청                 │
       └───────────────────────────────────────────┘

대화 흐름 예시

Turn 1  🤖 Agent  : "안녕하세요, 무엇을 도와드릴까요?"
        ↓
Turn 2  👤 User   : "주문 W2378156 반품하고 싶어요"
        ↓
Turn 3  🤖 Agent  : [TOOL_CALL: get_order_details]
        ↓
Turn 4  🔧 Tool   : {order_id: "#W2378156", status: "delivered"}
        ↓
Turn 5  🤖 Agent  : [TOOL_CALL: process_return]
        ↓
Turn 6  🔧 Tool   : {success: true, refund: 150.00}
        ↓
Turn 7  🤖 Agent  : "반품 완료! $150 환불됩니다."
        ↓
Turn 8  👤 User   : "감사합니다!" → [STOP]

대화 통계 (실제 데이터)

다른 벤치마크와 비교

| 벤치마크 | 턴 | Tool | User Sim | 평가 대상 | |----------|:--:|:----:|:--------:|-----------| | τ²-bench | Multi | ✅ | ✅ | Agent 행동 | | MMLU | Single | ❌ | ❌ | 지식 | | HumanEval | Single | ❌ | ❌ | 코드 생성 | | MT-Bench | Multi | ❌ | ❌ | 대화 품질 | | ToolBench | Multi | ✅ | ❌ | 도구 사용 |

📁 프로젝트 구조

TAU2-Bench/
├── README.md                    ← 이 파일
├── .env                         ← API 키 (gitignore)
│
└── tau2-bench/                  ← 업스트림 벤치마크
    ├── README.md                ← 공식 문서 (영어)
    ├── EXCEL_GUIDE.md           ← 엑셀 보고서 가이드
    │
    ├── run_quick_450.sh         ← ⭐ 450회 평가 스크립트
    ├── generate_excel_report.py ← 엑셀 생성기
    │
    └── results/latest/          ← 결과 (gitignore)
        ├── 전체_요약/
        └── 모델별/

⚡ 빠른 시작

Step 1: API 키 설정

cp .env.example .env
# .env 파일 열고 OPENROUTER_API_KEY 입력

Step 2: 450회 Quick 평가

cd tau2-bench
./run_quick_450.sh

Step 3: 결과 확인

📊 평가 도메인

📦 데이터셋 구조

디렉토리 레이아웃

data/tau2/
├── domains/
│   ├── retail/
│   │   ├── tasks.json          ← 평가 태스크 (115개+)
│   │   ├── db.json             ← 상품/주문/유저 DB (83K+ lines)
│   │   ├── policy.md           ← 에이전트 정책 문서
│   │   └── split_tasks.json    ← base/test 분할
│   │
│   ├── airline/
│   │   ├── tasks.json          ← 평가 태스크
│   │   ├── db.json             ← 예약/비행편 DB
│   │   ├── policy.md           ← 항공 정책 문서
│   │   └── split_tasks.json
│   │
│   └── telecom/
│       ├── tasks.json          ← 기본 태스크
│       ├── tasks_full.json     ← 전체 태스크
│       ├── main_policy.md      ← 메인 정책
│       ├── tech_support_*.md   ← 기술 지원 워크플로우
│       ├── db.toml             ← 계정 DB
│       └── workflows/          ← 문제해결 플로우차트
│
├── user_simulator/
│   └── simulation_guidelines.md    ← 시뮬레이션 가이드라인
│
└── results/final/                  ← 공식 결과 JSON

도메인별 데이터 비교

Task JSON 구조

{
  "id": "0",
  "description": {
    "purpose": "테스트 목적",
    "relevant_policies": "관련 정책",
    "notes": "추가 노트"
  },
  "user_scenario": {
    "persona": null,
    "instructions": {
      "task_instructions": "세부 행동 지침",
      "domain": "retail | airline | telecom",
      "reason_for_call": "고객이 전화한 이유",
      "known_info": "고객이 알고 있는 정보",
      "unknown_info": "고객이 모르는 정보"
    }
  },
  "initial_state": null,
  "evaluation_criteria": {
    "actions": [...],           // 예상 Tool 호출 목록
    "communicate_info": [...],  // 전달해야 할 정보
    "env_assertions": [...],    // 환경 상태 검증
    "nl_assertions": [...]      // 자연어 검증
  }
}

User Instructions 필드 설명

Evaluation Criteria 필드 설명

Trajectory (실행 결과) JSON 구조

{
  "timestamp": "2025-06-05T15:33:58.840015",
  "info": {
    "num_trials": 4,
    "max_steps": 200,
    "user_info": { "llm": "gpt-4.1-2025-04-14", ... },
    "agent_info": { "llm": "gpt-4.1-2025-04-14", ... },
    "environment_info": { "domain_name": "retail", "policy": "...", ... }
  },
  "tasks": [
    {
      "id": "0",
      "user_scenario": { ... },
      "evaluation_criteria": { ... },
      "trials": [
        {
          "messages": [...],     // 전체 대화 기록
          "reward": 1.0,         // 최종 점수
          "reward_breakdown": {  // 항목별 점수
            "DB": 1.0,
            "COMMUNICATE": 1.0,
            "ACTION": 1.0
          }
        }
      ]
    }
  ]
}

🔄 평가 프로세스

시스템 아키텍처 흐름도

[ 입력 데이터 ] ─────────┐
(Task + Tools + User)    │
                         ▼
[ 평가 대상 모델 ] ─────── (OpenRouter API 호출)
(Agent Response 생성)    │
                         ▼
[ User Simulator ] ────── (LLM이 고객 역할 수행)
(Multi-Turn 대화 진행)   │
                         ▼
[ Tool Execution ] ────── (API 호출 → DB 상태 변경)
(실제 환경에서 실행)     │
                         ▼
[ 결과 검증 ] ─────────── (GT와 비교)
(DB Hash + Actions)      │
                         ▼
[ 점수 산출 ] ─────────── (JSON 저장 및 Excel 리포트 생성)

📈 채점 기준 (Reward Breakdown)

Pass/Fail 판정 기준

점수 계산 공식

Reward = RB_DB × RB_COMMUNICATE × RB_ACTION × RB_ENV_ASSERTION

┌─────────────────────────────────────────────────────┐
│  PASS: Reward == 1.0  (모든 항목 통과)              │
│  FAIL: Reward  32B 예상과 달리 32B가 더 높은 점수 | 크기보다 Tool-use 튜닝이 중요 |

---

## 💡 용도별 모델 추천

| 용도 | 추천 모델 | 이유 |
|------|----------|------|
| **Agent 역할 (Tool 호출 중심)** | Qwen3-32B | 전체 Pass Rate 40.0%로 최고, 도메인별 균형 |
| **Retail 도메인 특화** | Qwen3-Next-80B | Retail 50.0%로 단일 도메인 최고 |
| **경량화 환경** | Qwen3-14B | 14B 크기에서 25.6% 달성, ENV_ASSERTION 81.8% |
| **균형 잡힌 성능** | Qwen3-32B | 모든 도메인에서 30% 이상 유지 |

---

## 📌 핵심 인사이트

┌─────────────────────────────────────────────────────────────────────┐ │ 💡 핵심 발견 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 1. DB 불일치가 모든 모델의 #1 실패 원인 │ │ → Tool Call 파라미터 오류 or 호출 순서 오류 │ │ │ │ 2. 파라미터 수 ≠ 성능 │ │ → 70B, 80B 모델이 32B 모델보다 저조 │ │ → Tool-use 특화 튜닝 여부가 더 중요 │ │ │ │ 3. 도메인별 난이도 차이 │ │ → Retail: 직관적 (교환/반품) - 상대적 쉬움 │ │ → Telecom: 복잡한 상태 관리 - 가장 어려움 │ │ │ │ 4. Qwen 계열이 전반적으로 우수 │ │ → Tool-Use에 최적화된 학습 데이터 추정 │ │ → 32B가 가성비 최고, 14B도 경량 대비 준수 │ │ │ │ 5. COMMUNICATE는 대부분 통과 (75~87%) │ │ → 정보 전달 자체는 잘 하지만 DB 변경에서 실패 │ │ │ └─────────────────────────────────────────────────────────────────────┘

---

## 🔧 핵심 스크립트 실행 가이드

### 📋 스크립트 목록

| 파일 | 용도 | 위치 |
|------|------|------|
| `run_quick_450.sh` | ⭐ 450회 평가 (Quick) | `tau2-bench/` |
| `run_evaluation.sh` | Full 평가 (P@k) | `tau2-bench/` |
| `generate_reports.py` | 리포트 생성 엔트리 | `tau2-bench/` |
| `generate_excel_report.py` | 엑셀 보고서 생성 | `tau2-bench/` |

---

### 1️⃣ 평가 실행: `run_quick_450.sh`

cd tau2-bench ./run_quick_450.sh

| 옵션 | 기본값 | 설명 |
|------|--------|------|
| `NUM_TASKS` | 30 | 도메인당 태스크 수 |
| `NUM_TRIALS` | 1 | 태스크당 반복 수 |
| `MAX_CONCURRENCY` | 3 | 동시 실행 수 |
| `FORCE` | 0 | 1이면 기존 결과 삭제 |
| `DELAY_SEC` | 1 | 호출 간 딜레이(초) |

예시: 기존 결과 삭제 후 재실행

FORCE=1 ./run_quick_450.sh

예시: 동시 실행 수 줄이기 (503 에러 대응)

MAX_CONCURRENCY=1 DELAY_SEC=2 ./run_quick_450.sh

---

### 2️⃣ 리포트 생성: `generate_reports.py`

cd tau2-bench python3 generate_reports.py \ --results-root results/latest \ --input-dir results/latest/simulations \ --prune

| 옵션 | 설명 |
|------|------|
| `--results-root` | 결과 저장 루트 디렉토리 |
| `--input-dir` | 시뮬레이션 JSON 디렉토리 |
| `--prune` | 기존 파일 정리 후 생성 |

**출력:**
- `results/latest/전체_요약/TAU2_전체요약_latest.xlsx`
- `results/latest/모델별//TAU2__latest.xlsx`

---

### 3️⃣ 엑셀 직접 생성: `generate_excel_report.py`

cd tau2-bench python3 generate_excel_report.py \ --input-dir results/latest/simulations \ --output results/latest/전체_요약/TAU2_전체요약_latest.xlsx

| 옵션 | 설명 |
|------|------|
| `--input-dir` | 시뮬레이션 JSON 디렉토리 |
| `--output` | 출력 엑셀 파일 경로 |

---

### 4️⃣ tau2 CLI 명령어

설치 확인

tau2 check-data

1개 태스크 테스트 (연결 확인)

tau2 run \ --domain retail \ --agent-llm openrouter/qwen/qwen3-32b \ --user-llm openrouter/qwen/qwen3-32b \ --num-tasks 1 \ --num-trials 1

특정 모델 Full 평가

tau2 run \ --domain retail \ --agent-llm openrouter/qwen/qwen3-32b \ --user-llm openrouter/qwen/qwen3-32b \ --num-trials 4 \ --task-split base \ --save-to qwen3-32b_retail

결과 뷰어

tau2 view

도메인 문서 확인

tau2 domain retail

| 명령어 | 용도 |
|--------|------|
| `tau2 check-data` | 데이터 경로 확인 |
| `tau2 run` | 평가 실행 |
| `tau2 view` | 결과 뷰어 |
| `tau2 domain ` | 도메인 API 문서 |
| `tau2 play` | 인터랙티브 모드 |

---

### 5️⃣ 실행 흐름 요약

┌─────────────────────────────────────────────────────────────────────┐ │ 실행 흐름 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 1. 평가 실행 │ │ ./run_quick_450.sh │ │ ↓ │ │ tau2 run (5개 모델 × 3개 도메인) │ │ ↓ │ │ data/simulations/*.json 생성 │ │ │ │ 2. 리포트 생성 │ │ python3 generate_reports.py │ │ ↓ │ │ generate_excel_report.py 호출 │ │ ↓ │ │ results/latest/전체_요약/TAU2_전체요약_latest.xlsx │ │ │ │ 3. 결과 확인 │ │ 엑셀 파일 열기 → 요약/런/턴 시트 확인 │ │ │ └─────────────────────────────────────────────────────────────────────┘

---

## 🛠️ 트러블슈팅

| 증상 | 원인 | 해결 |
|------|------|------|
| HTTP 503 | Provider 가용성 | 재시도, 시간대 변경 |
| HTTP 422 | Tool schema 오류 | LiteLLM 업데이트 |
| RB_ACTION=0 | 툴 호출 실패 | 툴 args 확인 |

---

## 📝 코드 실행 경로

tau2 run (CLI) ↓ src/tau2/run.py → Orchestrator.run() ↓ ┌─────────────────────────────────────────┐ │ Orchestrator │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Agent │←→│ User │←→│ Env │ │ │ │ (LLM) │ │ (LLM) │ │ (Tools) │ │ │ └─────────┘ └─────────┘ └─────────┘ │ └─────────────────────────────────────────┘ ↓ src/tau2/utils/llm_utils.py → litellm.completion() ↓ OpenRouter API

---

## ✅ 빠른 점검

- [ ] `echo $OPENROUTER_API_KEY` → 키 출력 확인
- [ ] `tau2 check-data` → 데이터 경로 확인
- [ ] `tau2 run --num-tasks 1` → 1개 태스크 성공

---

## 📚 참고 문서

| 문서 | 위치 | 내용 |
|------|------|------|
| 공식 README | `tau2-bench/README.md` | 설치/CLI |
| 엑셀 가이드 | `tau2-bench/EXCEL_GUIDE.md` | 보고서 해석 |

---

**[📖 공식 문서](tau2-bench/README.md)** · **[📊 엑셀 가이드](tau2-bench/EXCEL_GUIDE.md)** · **[🏆 Leaderboard](https://taubench.com)**