openbench Documentation

repository·main·Indexed 21 days ago

https://github.com/groq/openbench

A provider-agnostic, open-source evaluation infrastructure for language models. openbench allows developers to run standardized benchmarks across dozens of model providers, including Groq, OpenAI, Anthropic, and Google, as well as local providers like Ollama and vLLM. It features a CLI for running evaluations, an interactive UI for viewing results, and support for custom benchmark plugins and private evaluation scripts.

Tokens
55K
Snippets
145
Records
185
Agent score
73%

What's inside openbench

  1. Overview of openbench

    main
    openbench is an open-source, provider-agnostic framework designed for standardized and reproducible benchmarking of Large Language Models (LLMs). It allows developers to run industry-standard evaluation suites (30+ available) across various model providers to build trust in model performance through transparent and domain-relevant metrics.
  2. Explore the Benchmarks Catalog

    main

    The openbench project provides a variety of benchmarks to evaluate language models across different dimensions such as knowledge, reasoning, tool calling, and coding.

    • MMLU: Evaluates knowledge and reasoning across 57 academic subjects using multiple-choice questions.
    • GPQA Diamond: Graduate-level science evaluation (biology, chemistry, physics) using multiple-choice questions.
    • LiveMCPBench: Evaluates agentic capabilities, specifically how models navigate and utilize the Model Context Protocol (MCP) ecosystem.
    • SimpleQA: Measures short-form factuality using model-graded simple Q&A pairs.
    • Exercism: Evaluates code generation agent capabilities using real-world programming challenges across 5 languages.
    • GraphWalks: Tests long-context reasoning through multi-hop reasoning tasks on graphs (BFS and parent finding).
  3. How LiveMCPBench scoring works

    main

    LiveMCPBench utilizes the LiveMCPEval framework (an LLM-as-a-judge approach) to score models. The evaluation focuses on several key capabilities:

    • Tool Discovery: Ability to find and understand available MCP servers and tools.
    • Task Planning: Breaking down complex problems and selecting appropriate tools.
    • Execution & Orchestration: Correctly invoking tools and managing workflows.
    • Tool Usage Validation: Verifying the model relies on tool outputs rather than internal knowledge.
    • Task Completion: Successfully hitting the key points required by the task.
    • Adaptation & Learning: Dynamically discovering tools and iterating on approaches.
  4. Exercism Workspace and Task Structure

    main

    The Exercism benchmark provides agents with a sandboxed Docker environment containing a complete project workspace. Each task follows this structure:

    /workspace/{language}/{task_name}/
    ├── INSTRUCTIONS.md          # Exercise description and requirements
    ├── {source_files}           # Implementation files to modify
    └── {test_files}             # Test suite to verify solution

    Agent Workflow:

    1. Read INSTRUCTIONS.md.
    2. Navigate the file system.
    3. Analyze existing code and tests.
    4. Modify source files to implement the solution.
    5. Pass the automated test suite.
  5. Configure model providers and API keys

    main

    openbench is provider-agnostic and supports over 30 model providers via Inspect AI. To use a provider, set the corresponding environment variable.

    Common providers include:

    • Groq: GROQ_API_KEY (Model: groq/model-name)
    • OpenAI: OPENAI_API_KEY (Model: openai/model-name)
    • Anthropic: ANTHROPIC_API_KEY (Model: anthropic/model-name)
    • Google: GOOGLE_API_KEY (Model: google/model-name)
    • Ollama: No key required (Local) (Model: ollama/model-name)
    • vLLM: No key required (Local) (Model: vllm/model-name)

    Refer to the full list in the documentation or the provider table for specific environment variables like AI21_API_KEY, COHERE_API_KEY, or HF_TOKEN (for Hugging Face).

  6. Supported model providers and naming conventions

    main

    openbench supports over 15 model providers out of the box. When specifying models in your evaluations, use the provider/model-name format.

    Examples of supported providers and their model strings:

    • Groq: groq/llama-3.3-70b
    • OpenAI: openai/gpt-4o
    • Anthropic: anthropic/claude-3-5-sonnet
    • Google: google/gemini-2.5-pro
    • OpenRouter: openrouter/deepseek/deepseek-chat-v3.1

    Other supported providers include AWS Bedrock, Azure, Cohere, and Together.

    # Example model identifiers
    groq/llama-3.3-70b
    openai/gpt-4o
    anthropic/claude-3-5-sonnet
    google/gemini-2.5-pro
    openrouter/deepseek/deepseek-chat-v3.1
  7. Extend openbench with custom benchmark plugins

    main

    openbench supports a plugin system using Python entry points. This allows you to package benchmarks as independent Python packages and distribute them. Once installed via pip, they will automatically appear in bench list.

    To register a benchmark, add an entry point in your pyproject.toml:

    [project.entry-points."openbench.benchmarks"]
    my_benchmark = "my_pkg.metadata:get_benchmark_metadata"
  8. Understand MMLU scoring and metrics

    main

    MMLU scoring is based on accuracy, calculated as the percentage of questions answered correctly across all 57 subjects.

    Results include:

    • Overall Accuracy: A single percentage representing total performance.
    • Per-subject breakdowns: Detailed scores for individual domains (e.g., STEM, Humanities, Social Sciences) to help identify specific strengths and weaknesses.
  9. Configure openbench using multiple methods

    main

    openbench supports configuration through three methods, applied in the following order of precedence (highest to lowest):

    1. Command-Line Arguments: Pass flags directly to the bench command.
    2. Environment Variables: Set variables prefixed with BENCH_ in your shell.
    3. Configuration Files: Use .env files. These are automatically loaded if present in the current directory, or can be sourced manually using source .env.

    If a parameter is not provided via any of these methods, the system uses its internal default values.

    # 1. CLI Flag
    bench mmlu --max_tokens=10000 --temperature=0.5
    
    # 2. Environment Variable
    export BENCH_MAX_TOKENS=10000
    export BENCH_TEMPERATURE=0.5
    
    # 3. .env File
    # Create a .env file with:
    BENCH_MAX_TOKENS=10000
    BENCH_TEMPERATURE=0.5
    
    # Run (automatically loads if in current directory)
    bench eval mmlu
  10. Explore benchmark categories and tags

    main
    Benchmarks are organized by category (e.g., core, math, global-mmlu, domain-specific) and tags (e.g., multiple-choice, reasoning, coding, medical). This metadata allows you to understand the nature of the test and filter for specific capabilities like multilingual or long-context reasoning.
  11. Understand SciCode scoring metrics

    main

    SciCode evaluates generated code across several dimensions to provide a comprehensive view of model performance in scientific contexts:

    • Overall Success Rate: The percentage of problems solved correctly.
    • Domain-Specific Performance: Scores categorized by scientific field.
    • Correctness: Functional accuracy, algorithm implementation, and mathematical precision.
    • Code Quality: Readability, efficiency, and adherence to best practices.
    • Execution Success: The percentage of code that runs without errors.
    • Scientific Understanding: Assessment of domain knowledge, method selection, and parameter handling.
  12. GPQA Diamond benchmark overview and scoring

    main

    GPQA Diamond is a benchmark for testing deep scientific understanding and reasoning.

    Key Details

    • Scientific Domains: Biology (molecular biology, genetics, etc.), Chemistry (organic, physical, etc.), and Physics (quantum mechanics, thermodynamics, etc.).
    • Format: Multiple-choice questions with carefully crafted distractors.
    • Difficulty: Graduate-level; questions are 'Google-proof', meaning they require multi-step reasoning and contextual understanding rather than simple fact lookup.
    • Scoring: The primary metric is accuracy, representing the percentage of questions answered correctly.