agentscope-ai/auto-arena

Auto Arena Skill

End-to-end automated model comparison using the OpenJudge AutoArenaPipeline:

1. Generate queries — LLM creates diverse test queries from task description
2. Collect responses — query all target endpoints concurrently
3. Generate rubrics — LLM produces evaluation criteria from task + sample queries
4. Pairwise evaluation — judge model compares every model pair (with position-bias swap)
5. Analyze & rank — compute win rates, win matrix, and rankings
6. Report & charts — Markdown report + win-rate bar chart + optional matrix heatmap

Prerequisites

# Install OpenJudge
pip install py-openjudge

# Extra dependency for auto_arena (chart generation)
pip install matplotlib

Gather from user before running

| Info | Required? | Notes | |------|-----------|-------| | Task description | Yes | What the models/agents should do (set in config YAML) | | Target endpoints | Yes | At least 2 OpenAI-compatible endpoints to compare | | Judge endpoint | Yes | Strong model for pairwise evaluation (e.g. gpt-4, qwen-max) | | API keys | Yes | Env vars: OPENAI_API_KEY, DASHSCOPE_API_KEY, etc. | | Number of queries | No | Default: 20 | | Seed queries | No | Example queries to guide generation style | | System prompts | No | Per-endpoint system prompts | | Output directory | No | Default: ./evaluation_results | | Report language | No | "zh" (default) or "en" |

Quick start

CLI

# Run evaluation
python -m cookbooks.auto_arena --config config.yaml --save

# Use pre-generated queries
python -m cookbooks.auto_arena --config config.yaml \
  --queries_file queries.json --save

# Start fresh, ignore checkpoint
python -m cookbooks.auto_arena --config config.yaml --fresh --save

# Re-run only pairwise evaluation with new judge model
# (keeps queries, responses, and rubrics)
python -m cookbooks.auto_arena --config config.yaml --rerun-judge --save

Python API

import asyncio
from cookbooks.auto_arena.auto_arena_pipeline import AutoArenaPipeline

async def main():
    pipeline = AutoArenaPipeline.from_config("config.yaml")
    result = await pipeline.evaluate()

    print(f"Best model: {result.best_pipeline}")
    for rank, (model, win_rate) in enumerate(result.rankings, 1):
        print(f"{rank}. {model}: {win_rate:.1%}")

asyncio.run(main())

Minimal Python API (no config file)

import asyncio
from cookbooks.auto_arena.auto_arena_pipeline import AutoArenaPipeline
from cookbooks.auto_arena.schema import OpenAIEndpoint

async def main():
    pipeline = AutoArenaPipeline(
        task_description="Customer service chatbot for e-commerce",
        target_endpoints={
            "gpt4": OpenAIEndpoint(
                base_url="https://api.openai.com/v1",
                api_key="sk-...",
                model="gpt-4",
            ),
            "qwen": OpenAIEndpoint(
                base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                api_key="sk-...",
                model="qwen-max",
            ),
        },
        judge_endpoint=OpenAIEndpoint(
            base_url="https://api.openai.com/v1",
            api_key="sk-...",
            model="gpt-4",
        ),
        num_queries=20,
    )
    result = await pipeline.evaluate()
    print(f"Best: {result.best_pipeline}")

asyncio.run(main())

CLI options

| Flag | Default | Description | |------|---------|-------------| | --config | — | Path to YAML configuration file (required) | | --output_dir | config value | Override output directory | | --queries_file | — | Path to pre-generated queries JSON (skip generation) | | --save | False | Save results to file | | --fresh | False | Start fresh, ignore checkpoint | | --rerun-judge | False | Re-run pairwise evaluation only (keep queries/responses/rubrics) |

Minimal config file

task:
  description: "Academic GPT assistant for research and writing tasks"

target_endpoints:
  model_v1:
    base_url: "https://api.openai.com/v1"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4"
  model_v2:
    base_url: "https://api.openai.com/v1"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-3.5-turbo"

judge_endpoint:
  base_url: "https://api.openai.com/v1"
  api_key: "${OPENAI_API_KEY}"
  model: "gpt-4"

Full config reference

task

| Field | Required | Description | |-------|----------|-------------| | description | Yes | Clear description of the task models will be tested on | | scenario | No | Usage scenario for additional context |

target_endpoints.<name>

| Field | Default | Description | |-------|---------|-------------| | base_url | — | API base URL (required) | | api_key | — | API key, supports ${ENV_VAR} (required) | | model | — | Model name (required) | | system_prompt | — | System prompt for this endpoint | | extra_params | — | Extra API params (e.g. temperature, max_tokens) |

judge_endpoint

Same fields as target_endpoints.<name>. Use a strong model (e.g. gpt-4, qwen-max) with low temperature (~0.1) for consistent judgments.

query_generation

| Field | Default | Description | |-------|---------|-------------| | num_queries | 20 | Total number of queries to generate | | seed_queries | — | Example queries to guide generation | | categories | — | Query categories with weights for stratified generation | | endpoint | judge endpoint | Custom endpoint for query generation | | queries_per_call | 10 | Queries generated per API call (1–50) | | num_parallel_batches | 3 | Parallel generation batches | | temperature | 0.9 | Sampling temperature (0.0–2.0) | | top_p | 0.95 | Top-p sampling (0.0–1.0) | | max_similarity | 0.85 | Dedup similarity threshold (0.0–1.0) | | enable_evolution | false | Enable Evol-Instruct complexity evolution | | evolution_rounds | 1 | Evolution rounds (0–3) | | complexity_levels | ["constraints", "reasoning", "edge_cases"] | Evolution strategies |

evaluation

| Field | Default | Description | |-------|---------|-------------| | max_concurrency | 10 | Max concurrent API requests | | timeout | 60 | Request timeout in seconds | | retry_times | 3 | Retry attempts for failed requests |

output

| Field | Default | Description | |-------|---------|-------------| | output_dir | ./evaluation_results | Output directory | | save_queries | true | Save generated queries | | save_responses | true | Save model responses | | save_details | true | Save detailed results |

report

| Field | Default | Description | |-------|---------|-------------| | enabled | false | Enable Markdown report generation | | language | "zh" | Report language: "zh" or "en" | | include_examples | 3 | Examples per section (1–10) | | chart.enabled | true | Generate win-rate chart | | chart.orientation | "horizontal" | "horizontal" or "vertical" | | chart.show_values | true | Show values on bars | | chart.highlight_best | true | Highlight best model | | chart.matrix_enabled | false | Generate win-rate matrix heatmap | | chart.format | "png" | Chart format: "png", "svg", or "pdf" |

Interpreting results

Win rate: percentage of pairwise comparisons a model wins. Each pair is evaluated in both orders (original + swapped) to eliminate position bias.

Rankings example:

  1. gpt4_baseline       [################----] 80.0%
  2. qwen_candidate      [############--------] 60.0%
  3. llama_finetuned      [##########----------] 50.0%

Win matrix: win_matrix[A][B] = how often model A beats model B across all queries.

Checkpoint & resume

The pipeline saves progress after each step. Interrupted runs resume automatically:

• --fresh — ignore checkpoint, start from scratch
• --rerun-judge — re-run only the pairwise evaluation step (useful when switching judge models); keeps queries, responses, and rubrics intact
• Adding new endpoints to config triggers incremental response collection; existing responses are preserved

Output files

evaluation_results/
├── evaluation_results.json     # Rankings, win rates, win matrix
├── evaluation_report.md        # Detailed Markdown report (if enabled)
├── win_rate_chart.png          # Win-rate bar chart (if enabled)
├── win_rate_matrix.png         # Matrix heatmap (if matrix_enabled)
├── queries.json                # Generated test queries
├── responses.json              # All model responses
├── rubrics.json                # Generated evaluation rubrics
├── comparison_details.json     # Pairwise comparison details
└── checkpoint.json             # Pipeline checkpoint

API key by model

| Model prefix | Environment variable | |-------------|---------------------| | gpt-*, o1-*, o3-* | OPENAI_API_KEY | | claude-* | ANTHROPIC_API_KEY | | qwen-*, dashscope/* | DASHSCOPE_API_KEY | | deepseek-* | DEEPSEEK_API_KEY | | Custom endpoint | set api_key + base_url in config |

Additional resources

• Full config examples: cookbooks/auto_arena/examples/
• Documentation: Auto Arena Guide