[ { "path": ".github/workflows/new_tasks.yml", "content": "name: Tasks Modified\n\non:\n push:\n branches:\n - 'main'\n pull_request:\n branches:\n - 'main'\n workflow_dispatch:\n\nenv:\n TQDM_DISABLE: \"1\"\n HF_HUB_DISABLE_PROGRESS_BARS: \"1\"\n\n# comment/edit out the above to stop/change the triggers\njobs:\n changed_files:\n runs-on: ubuntu-latest # windows-latest || macos-latest\n timeout-minutes: 120\n name: Scan for changed tasks\n steps:\n - name: checkout\n uses: actions/checkout@v6\n with:\n fetch-depth: 2 # OR \"2\" -> To retrieve the preceding commit.\n\n # Uses the tj-actions/changed-files action to check for changes.\n # The `files_yaml` input optionally takes a yaml string to specify filters,\n # and prepends the filter name to the standard output names.\n - name: Check task folders\n id: changed-tasks\n uses: tj-actions/changed-files@v47\n with:\n # tasks checks the tasks folder and api checks the api folder for changes\n files_yaml: |\n tasks:\n - lm_eval/tasks/**\n api:\n - lm_eval/api/**\n write_output_files: true\n\n # The next step is optional; the files are written to the workspace by default (above).\n # so it's just for debugging\n - name: Run Tests\n if: steps.changed-tasks.outputs.tasks_any_modified == 'true' || steps.changed-tasks.outputs.api_any_modified == 'true'\n run: |\n echo .github/outputs/tasks_all_changed_and_modified_files.txt >> 'GITHUB_ENV'\n echo \"One or more test file(s) has changed.\"\n echo \"List of all the files that have changed: ${{ steps.changed-tasks.outputs.tasks_all_modified_files }}\"\n\n - name: Install uv\n if: steps.changed-tasks.outputs.tasks_any_modified == 'true' || steps.changed-tasks.outputs.api_any_modified == 'true'\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n python-version: \"3.10\"\n activate-environment: true\n - name: Install dependencies\n if: steps.changed-tasks.outputs.tasks_any_modified == 'true' || steps.changed-tasks.outputs.api_any_modified == 'true'\n run: |\n uv pip install -e '.[dev,ifeval,unitxt,math,longbench,hf]' --extra-index-url https://download.pytorch.org/whl/cpu\n - name: Test with pytest\n # if new tasks are added, run tests on them\n if: steps.changed-tasks.outputs.tasks_any_modified == 'true'\n run: pytest -x -s -vv tests/test_tasks.py\n # if api is modified, run tests on it\n - name: Test more tasks with pytest\n env:\n API: true\n if: steps.changed-tasks.outputs.api_any_modified == 'true'\n run: pytest -x -s -vv -n=auto tests/test_tasks.py\n" }, { "path": ".github/workflows/publish.yml", "content": "name: Publish Python distribution to PyPI\n\non:\n push:\n tags:\n - '*'\n\njobs:\n build:\n name: Build distribution\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v6\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: \"3.x\"\n\n - name: Print version\n run: |\n # Extract version from pyproject.toml\n PYPROJECT_VERSION=$(grep 'version = ' pyproject.toml | head -1 | cut -d'\"' -f2)\n echo \"Version in pyproject.toml: $PYPROJECT_VERSION\"\n\n - name: Install pypa/build\n run: >-\n python3 -m\n pip install\n build\n --user\n - name: Build a binary wheel and a source tarball\n run: python3 -m build\n - name: Store the distribution packages\n uses: actions/upload-artifact@v7\n with:\n name: python-package-distributions\n path: dist/\n\n publish-to-pypi:\n name: >-\n Publish Python distribution to PyPI\n if: startsWith(github.ref, 'refs/tags/') # only publish to PyPI on tag pushes\n needs:\n - build\n runs-on: ubuntu-latest\n environment:\n name: pypi\n url: https://pypi.org/p/lm_eval\n permissions:\n id-token: write # IMPORTANT: mandatory for trusted publishing\n\n steps:\n - name: Download all the dists\n uses: actions/download-artifact@v8\n with:\n name: python-package-distributions\n path: dist/\n - name: Publish distribution to PyPI\n uses: pypa/gh-action-pypi-publish@release/v1\n\n publish-to-testpypi:\n name: Publish Python distribution to TestPyPI\n needs:\n - build\n runs-on: ubuntu-latest\n\n environment:\n name: testpypi\n url: https://test.pypi.org/p/lm_eval\n\n permissions:\n id-token: write # IMPORTANT: mandatory for trusted publishing\n\n steps:\n - name: Download all the dists\n uses: actions/download-artifact@v8\n with:\n name: python-package-distributions\n path: dist/\n - name: Publish distribution to TestPyPI\n uses: pypa/gh-action-pypi-publish@release/v1\n with:\n repository-url: https://test.pypi.org/legacy/\n" }, { "path": ".github/workflows/unit_tests.yml", "content": "# This workflow will install Python dependencies, run tests and lint with a variety of Python versions\n# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python\n# just comment out unwanted steps to turn off the test.\nname: Unit Tests\n\non:\n push:\n branches:\n - 'main'\n pull_request:\n branches:\n - 'main'\n workflow_dispatch:\n\nenv:\n TQDM_DISABLE: \"1\"\n HF_HUB_DISABLE_PROGRESS_BARS: \"1\"\n\n# Jobs run concurrently and steps run sequentially within a job.\n# jobs: linter and cpu_tests. Add more jobs/steps as required.\njobs:\n linter:\n name: Linters\n runs-on: ubuntu-latest\n timeout-minutes: 5\n\n steps:\n - name: Checkout Code\n uses: actions/checkout@v6\n with:\n fetch-depth: 0\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n python-version: \"3.10\"\n activate-environment: true\n - name: Install pip\n run: uv pip install pip\n - name: Pre-Commit\n env:\n SKIP: \"no-commit-to-branch,mypy\"\n uses: pre-commit/action@v3.0.1\n with:\n extra_args: --from-ref ${{ github.event.pull_request.base.sha || 'HEAD~1' }} --to-ref HEAD\n # Job 2\n testcpu:\n name: CPU Tests\n runs-on: ubuntu-latest\n strategy:\n fail-fast: true\n matrix:\n python-version: [\"3.10\", \"3.11\", \"3.12\"]\n timeout-minutes: 30\n steps:\n - name: Checkout Code\n uses: actions/checkout@v6\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n python-version: ${{ matrix.python-version }}\n activate-environment: true\n\n # Cache HuggingFace cache directory for CPU tests\n - name: Cache HuggingFace cache (CPU tests)\n uses: actions/cache@v5\n id: cache-hf-cpu\n with:\n path: ~/.cache/huggingface\n key: ${{ runner.os }}-hf-cache-cpu\n restore-keys: |\n ${{ runner.os }}-hf-cache-cpu\n\n - name: Install dependencies\n run: |\n uv pip install -e '.[dev,unitxt,hf]' --extra-index-url https://download.pytorch.org/whl/cpu\n uv pip install hf_xet\n\n - name: Test with pytest\n run: pytest -x --showlocals -s -vv -n=auto --ignore=tests/models/test_openvino.py --ignore=tests/models/test_hf_steered.py --ignore=tests/scripts/test_zeno_visualize.py\n\n # Save test artifacts\n - name: Archive test artifacts\n if: always() # Upload artifacts even if tests fail\n uses: actions/upload-artifact@v7\n with:\n name: output_testcpu${{ matrix.python-version }}\n path: |\n test_logs/*\n\n# testmodels:\n# name: External LM Tests\n# runs-on: ubuntu-latest\n# timeout-minutes: 30\n# steps:\n# - name: Checkout Code\n# uses: actions/checkout@v4\n# - name: Set up Python 3.9\n# uses: actions/setup-python@v5\n# with:\n# python-version: 3.9\n# cache: pip\n# cache-dependency-path: pyproject.toml\n#\n# # Cache HuggingFace cache directory for External LM tests\n# - name: Cache HuggingFace cache (External LM tests)\n# uses: actions/cache@v3\n# id: cache-hf-lm\n# with:\n# path: ~/.cache/huggingface\n# key: ${{ runner.os }}-hf-cache-external-lm\n# restore-keys: |\n# ${{ runner.os }}-hf-cache-external-lm\n#\n# - name: Install dependencies\n# run: |\n# python -m pip install --upgrade pip\n# pip install -e '.[dev,optimum,api]' --extra-index-url https://download.pytorch.org/whl/cpu\n# pip install -U transformers peft accelerate\n#\n# - name: Test with pytest\n# run: python -m pytest tests/models --showlocals -s -vv\n# continue-on-error: true # Continue workflow even if tests fail\n" }, { "path": ".gitignore", "content": "# macOS system files\n.DS_Store\n\n# Virtual environments\n.venv/\nvenv/\nENV/\nenv/\n*.env\n\n# Python bytecode and build artifacts\n__pycache__/\n*.py[cod]\n*.so\n*.egg-info/\nbuild/\ndist/\n\n# IDE & editor settings\n.vscode/\n.idea/\n\n# Jupyter\n.ipynb_checkpoints/\nprofile_default/\nipython_config.py\n\n# Output and data\noutput/\ndata/\ntemp/\ntest_logs/\n\n# Caching\nlm_eval/caching/.cache\nlm_cache/\n\n# Logging\n*.log\nlogs/\n\n# wandb experiment tracking\nwandb/\nexamples/wandb/\n\n# PyInstaller\n*.spec\n\n#uv\nuv.lock\n" }, { "path": ".pre-commit-config.yaml", "content": "# Ignore test linting to avoid conflicting changes to version stability.\nexclude: ^tests/testdata/\nrepos:\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v6.0.0\n hooks:\n - id: check-added-large-files\n - id: check-ast\n - id: fix-byte-order-marker\n - id: check-case-conflict\n - id: check-json\n - id: check-merge-conflict\n args: [ --assume-in-merge ]\n - id: check-symlinks\n - id: check-yaml\n args: [ \"--unsafe\" ]\n - id: destroyed-symlinks\n - id: detect-private-key\n - id: end-of-file-fixer\n - id: no-commit-to-branch\n always_run: false\n - id: requirements-txt-fixer\n - id: trailing-whitespace\n args: [ --markdown-linebreak-ext=md ]\n - id: fix-byte-order-marker\n exclude: docs/CNAME\n - id: mixed-line-ending\n args: [ --fix=lf ]\n - repo: https://github.com/astral-sh/ruff-pre-commit\n rev: v0.15.6\n hooks:\n # Run the linter.\n - id: ruff-check\n args: [ --fix ]\n # Run the formatter.\n - id: ruff-format\n - repo: https://github.com/codespell-project/codespell\n rev: v2.4.2\n hooks:\n - id: codespell\n exclude: >\n (?x)^(\n\n .*\\.json|ignore.txt|lm_eval/tasks/.*|.*yaml|.*\\.ipynb\n )$\n\n args: [ --check-filenames, --check-hidden, --ignore-words=ignore.txt ]\n - repo: https://github.com/jackdewinter/pymarkdown\n rev: v0.9.36\n hooks:\n - id: pymarkdown\n exclude: ^(lm_eval/tasks/.*|docs/footguns\\.md)$\n args: [ fix, -r ]\n" }, { "path": "CITATION.bib", "content": "@misc{eval-harness,\n author = {Gao, Leo and Tow, Jonathan and Abbasi, Baber and Biderman, Stella and Black, Sid and DiPofi, Anthony and Foster, Charles and Golding, Laurence and Hsu, Jeffrey and Le Noac'h, Alain and Li, Haonan and McDonell, Kyle and Muennighoff, Niklas and Ociepa, Chris and Phang, Jason and Reynolds, Laria and Schoelkopf, Hailey and Skowron, Aviya and Sutawika, Lintang and Tang, Eric and Thite, Anish and Wang, Ben and Wang, Kevin and Zou, Andy},\n title = {A framework for few-shot language model evaluation},\n month = 12,\n year = 2023,\n publisher = {Zenodo},\n version = {v0.4.0},\n doi = {10.5281/zenodo.10256836},\n url = {https://zenodo.org/records/10256836}\n}\n" }, { "path": "CODEOWNERS", "content": "* @baberabb\n* @0xSMT\n" }, { "path": "LICENSE.md", "content": "MIT License\n\nCopyright (c) 2020 EleutherAI\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "MANIFEST.in", "content": "recursive-include tests\n" }, { "path": "README.md", "content": "# Language Model Evaluation Harness\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10256836.svg)](https://doi.org/10.5281/zenodo.10256836)\n\n---\n\n## Latest News 📣\n- [2025/12] **CLI refactored** with subcommands (`run`, `ls`, `validate`) and YAML config file support via `--config`. See the [CLI Reference](./docs/interface.md) and [Configuration Guide](./docs/config_files.md).\n- [2025/12] **Lighter install**: Base package no longer includes `transformers`/`torch`. Install model backends separately: `pip install lm_eval[hf]`, `lm_eval[vllm]`, etc.\n- [2025/07] Added `think_end_token` arg to `hf` (token/str), `vllm` and `sglang` (str) for stripping CoT reasoning traces from models that support it.\n- [2025/03] Added support for steering HF models!\n- [2025/02] Added [SGLang](https://docs.sglang.ai/) support!\n- [2024/09] We are prototyping allowing users of LM Evaluation Harness to create and evaluate on text+image multimodal input, text output tasks, and have just added the `hf-multimodal` and `vllm-vlm` model types and `mmmu` task as a prototype feature. We welcome users to try out this in-progress feature and stress-test it for themselves, and suggest they check out [`lmms-eval`](https://github.com/EvolvingLMMs-Lab/lmms-eval), a wonderful project originally forking off of the lm-evaluation-harness, for a broader range of multimodal tasks, models, and features.\n- [2024/07] [API model](docs/API_guide.md) support has been updated and refactored, introducing support for batched and async requests, and making it significantly easier to customize and use for your own purposes. **To run Llama 405B, we recommend using VLLM's OpenAI-compliant API to host the model, and use the `local-completions` model type to evaluate the model.**\n- [2024/07] New Open LLM Leaderboard tasks have been added ! You can find them under the [leaderboard](lm_eval/tasks/leaderboard/README.md) task group.\n\n---\n\n## Announcement\n\n**A new v0.4.0 release of lm-evaluation-harness is available** !\n\nNew updates and features include:\n\n- **New Open LLM Leaderboard tasks have been added ! You can find them under the [leaderboard](lm_eval/tasks/leaderboard/README.md) task group.**\n- Internal refactoring\n- Config-based task creation and configuration\n- Easier import and sharing of externally-defined task config YAMLs\n- Support for Jinja2 prompt design, easy modification of prompts + prompt imports from Promptsource\n- More advanced configuration options, including output post-processing, answer extraction, and multiple LM generations per document, configurable fewshot settings, and more\n- Speedups and new modeling libraries supported, including: faster data-parallel HF model usage, vLLM support, MPS support with HuggingFace, and more\n- Logging and usability changes\n- New tasks including CoT BIG-Bench-Hard, Belebele, user-defined task groupings, and more\n\nPlease see our updated documentation pages in `docs/` for more details.\n\nDevelopment will be continuing on the `main` branch, and we encourage you to give us feedback on what features are desired and how to improve the library further, or ask questions, either in issues or PRs on GitHub, or in the [EleutherAI discord](https://discord.gg/eleutherai)!\n\n---\n\n## Overview\n\nThis project provides a unified framework to test generative language models on a large number of different evaluation tasks.\n\n**Features:**\n\n- Over 60 standard academic benchmarks for LLMs, with hundreds of subtasks and variants implemented.\n- Support for models loaded via [transformers](https://github.com/huggingface/transformers/) (including quantization via [GPTQModel](https://github.com/ModelCloud/GPTQModel) and [AutoGPTQ](https://github.com/PanQiWei/AutoGPTQ)), [GPT-NeoX](https://github.com/EleutherAI/gpt-neox), and [Megatron-DeepSpeed](https://github.com/microsoft/Megatron-DeepSpeed/), with a flexible tokenization-agnostic interface.\n- Support for fast and memory-efficient inference with [vLLM](https://github.com/vllm-project/vllm).\n- Support for commercial APIs including [OpenAI](https://openai.com), and [TextSynth](https://textsynth.com/).\n- Support for evaluation on adapters (e.g. LoRA) supported in [HuggingFace's PEFT library](https://github.com/huggingface/peft).\n- Support for local models and benchmarks.\n- Evaluation with publicly available prompts ensures reproducibility and comparability between papers.\n- Easy support for custom prompts and evaluation metrics.\n\nThe Language Model Evaluation Harness is the backend for 🤗 Hugging Face's popular [Open LLM Leaderboard](https://huggingface.co/spaces/HuggingFaceH4/open_llm_leaderboard), has been used in [hundreds of papers](https://scholar.google.com/scholar?oi=bibs&hl=en&authuser=2&cites=15052937328817631261,4097184744846514103,1520777361382155671,17476825572045927382,18443729326628441434,14801318227356878622,7890865700763267262,12854182577605049984,15641002901115500560,5104500764547628290), and is used internally by dozens of organizations including NVIDIA, Cohere, BigScience, BigCode, Nous Research, and Mosaic ML.\n\n## Install\n\nTo install the `lm-eval` package from the github repository, run:\n\n```bash\ngit clone --depth 1 https://github.com/EleutherAI/lm-evaluation-harness\ncd lm-evaluation-harness\npip install -e .\n```\n\n### Installing Model Backends\n\nThe base installation provides the core evaluation framework. **Model backends must be installed separately** using optional extras:\n\nFor HuggingFace transformers models:\n\n```bash\npip install \"lm_eval[hf]\"\n```\n\nFor vLLM inference:\n\n```bash\npip install \"lm_eval[vllm]\"\n```\n\nFor API-based models (OpenAI, Anthropic, etc.):\n\n```bash\npip install \"lm_eval[api]\"\n```\n\nMultiple backends can be installed together:\n\n```bash\npip install \"lm_eval[hf,vllm,api]\"\n```\n\nA detailed table of all optional extras is available at the end of this document.\n\n## Basic Usage\n\n### Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [CLI Reference](./docs/interface.md) | Command-line arguments and subcommands |\n| [Configuration Guide](./docs/config_files.md) | YAML config file format and examples |\n| [Python API](./docs/python-api.md) | Programmatic usage with `simple_evaluate()` |\n| [Task Guide](./lm_eval/tasks/README.md) | Available tasks and task configuration |\n\nUse `lm-eval -h` to see available options, or `lm-eval run -h` for evaluation options.\n\nList available tasks with:\n\n```bash\nlm-eval ls tasks\n```\n\n### Hugging Face `transformers`\n\n> [!Important]\n> To use the HuggingFace backend, first install: `pip install \"lm_eval[hf]\"`\n\nTo evaluate a model hosted on the [HuggingFace Hub](https://huggingface.co/models) (e.g. GPT-J-6B) on `hellaswag` you can use the following command (this assumes you are using a CUDA-compatible GPU):\n\n```bash\nlm_eval --model hf \\\n --model_args pretrained=EleutherAI/gpt-j-6B \\\n --tasks hellaswag \\\n --device cuda:0 \\\n --batch_size 8\n```\n\nAdditional arguments can be provided to the model constructor using the `--model_args` flag. Most notably, this supports the common practice of using the `revisions` feature on the Hub to store partially trained checkpoints, or to specify the datatype for running a model:\n\n```bash\nlm_eval --model hf \\\n --model_args pretrained=EleutherAI/pythia-160m,revision=step100000,dtype=\"float\" \\\n --tasks lambada_openai,hellaswag \\\n --device cuda:0 \\\n --batch_size 8\n```\n\nModels that are loaded via both `transformers.AutoModelForCausalLM` (autoregressive, decoder-only GPT style models) and `transformers.AutoModelForSeq2SeqLM` (such as encoder-decoder models like T5) in Huggingface are supported.\n\nBatch size selection can be automated by setting the ```--batch_size``` flag to ```auto```. This will perform automatic detection of the largest batch size that will fit on your device. On tasks where there is a large difference between the longest and shortest example, it can be helpful to periodically recompute the largest batch size, to gain a further speedup. To do this, append ```:N``` to above flag to automatically recompute the largest batch size ```N``` times. For example, to recompute the batch size 4 times, the command would be:\n\n```bash\nlm_eval --model hf \\\n --model_args pretrained=EleutherAI/pythia-160m,revision=step100000,dtype=\"float\" \\\n --tasks lambada_openai,hellaswag \\\n --device cuda:0 \\\n --batch_size auto:4\n```\n\n> [!Note]\n> Just like you can provide a local path to `transformers.AutoModel`, you can also provide a local path to `lm_eval` via `--model_args pretrained=/path/to/model`\n\n#### Evaluating GGUF Models\n\n`lm-eval` supports evaluating models in GGUF format using the Hugging Face (`hf`) backend. This allows you to use quantized models compatible with `transformers`, `AutoModel`, and llama.cpp conversions.\n\nTo evaluate a GGUF model, pass the path to the directory containing the model weights, the `gguf_file`, and optionally a separate `tokenizer` path using the `--model_args` flag.\n\n**🚨 Important Note:** \nIf no separate tokenizer is provided, Hugging Face will attempt to reconstruct the tokenizer from the GGUF file — this can take **hours** or even hang indefinitely. Passing a separate tokenizer avoids this issue and can reduce tokenizer loading time from hours to seconds.\n\n**✅ Recommended usage:**\n\n```bash\nlm_eval --model hf \\\n --model_args pretrained=/path/to/gguf_folder,gguf_file=model-name.gguf,tokenizer=/path/to/tokenizer \\\n --tasks hellaswag \\\n --device cuda:0 \\\n --batch_size 8\n```\n\n> [!Tip]\n> Ensure the tokenizer path points to a valid Hugging Face tokenizer directory (e.g., containing tokenizer_config.json, vocab.json, etc.).\n\n#### Multi-GPU Evaluation with Hugging Face `accelerate`\n\nWe support three main ways of using Hugging Face's [accelerate 🚀](https://github.com/huggingface/accelerate) library for multi-GPU evaluation.\n\nTo perform *data-parallel evaluation* (where each GPU loads a **separate full copy** of the model), we leverage the `accelerate` launcher as follows:\n\n```bash\naccelerate launch -m lm_eval --model hf \\\n --tasks lambada_openai,arc_easy \\\n --batch_size 16\n```\n\n(or via `accelerate launch --no-python lm_eval`).\n\nFor cases where your model can fit on a single GPU, this allows you to evaluate on K GPUs K times faster than on one.\n\n**WARNING**: This setup does not work with FSDP model sharding, so in `accelerate config` FSDP must be disabled, or the NO_SHARD FSDP option must be used.\n\nThe second way of using `accelerate` for multi-GPU evaluation is when your model is *too large to fit on a single GPU.*\n\nIn this setting, run the library *outside the `accelerate` launcher*, but passing `parallelize=True` to `--model_args` as follows:\n\n```bash\nlm_eval --model hf \\\n --tasks lambada_openai,arc_easy \\\n --model_args parallelize=True \\\n --batch_size 16\n```\n\nThis means that your model's weights will be split across all available GPUs.\n\nFor more advanced users or even larger models, we allow for the following arguments when `parallelize=True` as well:\n\n- `device_map_option`: How to split model weights across available GPUs. defaults to \"auto\".\n- `max_memory_per_gpu`: the max GPU memory to use per GPU in loading the model.\n- `max_cpu_memory`: the max amount of CPU memory to use when offloading the model weights to RAM.\n- `offload_folder`: a folder where model weights will be offloaded to disk if needed.\n\nThe third option is to use both at the same time. This will allow you to take advantage of both data parallelism and model sharding, and is especially useful for models that are too large to fit on a single GPU.\n\n```bash\naccelerate launch --multi_gpu --num_processes {nb_of_copies_of_your_model} \\\n -m lm_eval --model hf \\\n --tasks lambada_openai,arc_easy \\\n --model_args parallelize=True \\\n --batch_size 16\n```\n\nTo learn more about model parallelism and how to use it with the `accelerate` library, see the [accelerate documentation](https://huggingface.co/docs/transformers/v4.15.0/en/parallelism)\n\n**Warning: We do not natively support multi-node evaluation using the `hf` model type! Please reference [our GPT-NeoX library integration](https://github.com/EleutherAI/gpt-neox/blob/main/eval.py) for an example of code in which a custom multi-machine evaluation script is written.**\n\n**Note: we do not currently support multi-node evaluations natively, and advise using either an externally hosted server to run inference requests against, or creating a custom integration with your distributed framework [as is done for the GPT-NeoX library](https://github.com/EleutherAI/gpt-neox/blob/main/eval_tasks/eval_adapter.py).**\n\n### Steered Hugging Face `transformers` models\n\nTo evaluate a Hugging Face `transformers` model with steering vectors applied, specify the model type as `steered` and provide the path to either a PyTorch file containing pre-defined steering vectors, or a CSV file that specifies how to derive steering vectors from pretrained `sparsify` or `sae_lens` models (you will need to install the corresponding optional dependency for this method).\n\nSpecify pre-defined steering vectors:\n\n```python\nimport torch\n\nsteer_config = {\n \"layers.3\": {\n \"steering_vector\": torch.randn(1, 768),\n \"bias\": torch.randn(1, 768),\n \"steering_coefficient\": 1,\n \"action\": \"add\"\n },\n}\ntorch.save(steer_config, \"steer_config.pt\")\n```\n\nSpecify derived steering vectors:\n\n```python\nimport pandas as pd\n\npd.DataFrame({\n \"loader\": [\"sparsify\"],\n \"action\": [\"add\"],\n \"sparse_model\": [\"EleutherAI/sae-pythia-70m-32k\"],\n \"hookpoint\": [\"layers.3\"],\n \"feature_index\": [30],\n \"steering_coefficient\": [10.0],\n}).to_csv(\"steer_config.csv\", index=False)\n```\n\nRun the evaluation harness with steering vectors applied:\n\n```bash\nlm_eval --model steered \\\n --model_args pretrained=EleutherAI/pythia-160m,steer_path=steer_config.pt \\\n --tasks lambada_openai,hellaswag \\\n --device cuda:0 \\\n --batch_size 8\n```\n\n### NVIDIA `nemo` models\n\n[NVIDIA NeMo Framework](https://github.com/NVIDIA/NeMo) is a generative AI framework built for researchers and pytorch developers working on language models.\n\nTo evaluate a `nemo` model, start by installing NeMo following [the documentation](https://github.com/NVIDIA/NeMo?tab=readme-ov-file#installation). We highly recommended to use the NVIDIA PyTorch or NeMo container, especially if having issues installing Apex or any other dependencies (see [latest released containers](https://github.com/NVIDIA/NeMo/releases)). Please also install the lm evaluation harness library following the instructions in [the Install section](https://github.com/EleutherAI/lm-evaluation-harness/tree/main?tab=readme-ov-file#install).\n\nNeMo models can be obtained through [NVIDIA NGC Catalog](https://catalog.ngc.nvidia.com/models) or in [NVIDIA's Hugging Face page](https://huggingface.co/nvidia). In [NVIDIA NeMo Framework](https://github.com/NVIDIA/NeMo/tree/main/scripts/nlp_language_modeling) there are conversion scripts to convert the `hf` checkpoints of popular models like llama, falcon, mixtral or mpt to `nemo`.\n\nRun a `nemo` model on one GPU:\n\n```bash\nlm_eval --model nemo_lm \\\n --model_args path= \\\n --tasks hellaswag \\\n --batch_size 32\n```\n\nIt is recommended to unpack the `nemo` model to avoid the unpacking inside the docker container - it may overflow disk space. For that you can run:\n\n```bash\nmkdir MY_MODEL\ntar -xvf MY_MODEL.nemo -c MY_MODEL\n```\n\n#### Multi-GPU evaluation with NVIDIA `nemo` models\n\nBy default, only one GPU is used. But we do support either data replication or tensor/pipeline parallelism during evaluation, on one node.\n\n1) To enable data replication, set the `model_args` of `devices` to the number of data replicas to run. For example, the command to run 8 data replicas over 8 GPUs is:\n\n```bash\ntorchrun --nproc-per-node=8 --no-python lm_eval \\\n --model nemo_lm \\\n --model_args path=,devices=8 \\\n --tasks hellaswag \\\n --batch_size 32\n```\n\n1) To enable tensor and/or pipeline parallelism, set the `model_args` of `tensor_model_parallel_size` and/or `pipeline_model_parallel_size`. In addition, you also have to set up `devices` to be equal to the product of `tensor_model_parallel_size` and/or `pipeline_model_parallel_size`. For example, the command to use one node of 4 GPUs with tensor parallelism of 2 and pipeline parallelism of 2 is:\n\n```bash\ntorchrun --nproc-per-node=4 --no-python lm_eval \\\n --model nemo_lm \\\n --model_args path=,devices=4,tensor_model_parallel_size=2,pipeline_model_parallel_size=2 \\\n --tasks hellaswag \\\n --batch_size 32\n```\n\nNote that it is recommended to substitute the `python` command by `torchrun --nproc-per-node= --no-python` to facilitate loading the model into the GPUs. This is especially important for large checkpoints loaded into multiple GPUs.\n\nNot supported yet: multi-node evaluation and combinations of data replication with tensor or pipeline parallelism.\n\n### Megatron-LM models\n\n[Megatron-LM](https://github.com/NVIDIA/Megatron-LM) is NVIDIA's large-scale transformer training framework. This backend allows direct evaluation of Megatron-LM checkpoints without conversion.\n\n**Requirements:**\n- Megatron-LM must be installed or accessible via `MEGATRON_PATH` environment variable\n- PyTorch with CUDA support\n\n**Setup:**\n\n```bash\n# Set environment variable pointing to Megatron-LM installation\nexport MEGATRON_PATH=/path/to/Megatron-LM\n```\n\n**Basic usage (single GPU):**\n\n```bash\nlm_eval --model megatron_lm \\\n --model_args load=/path/to/checkpoint,tokenizer_type=HuggingFaceTokenizer,tokenizer_model=/path/to/tokenizer \\\n --tasks hellaswag \\\n --batch_size 1\n```\n\n**Supported checkpoint formats:**\n- Standard Megatron checkpoints (`model_optim_rng.pt`)\n- Distributed checkpoints (`.distcp` format, auto-detected)\n\n#### Parallelism Modes\n\nThe Megatron-LM backend supports the following parallelism modes:\n\n| Mode | Configuration | Description |\n|------|---------------|-------------|\n| Single GPU | `devices=1` (default) | Standard single GPU evaluation |\n| Data Parallelism | `devices>1, TP=1` | Each GPU has a full model replica, data is distributed |\n| Tensor Parallelism | `TP == devices` | Model layers are split across GPUs |\n| Expert Parallelism | `EP == devices, TP=1` | For MoE models, experts are distributed across GPUs |\n\n> [!Note]\n> - Pipeline Parallelism (PP > 1) is not currently supported.\n> - Expert Parallelism (EP) cannot be combined with Tensor Parallelism (TP).\n\n**Data Parallelism (4 GPUs, each with full model replica):**\n\n```bash\ntorchrun --nproc-per-node=4 -m lm_eval --model megatron_lm \\\n --model_args load=/path/to/checkpoint,tokenizer_model=/path/to/tokenizer,devices=4 \\\n --tasks hellaswag\n```\n\n**Tensor Parallelism (TP=2):**\n\n```bash\ntorchrun --nproc-per-node=2 -m lm_eval --model megatron_lm \\\n --model_args load=/path/to/checkpoint,tokenizer_model=/path/to/tokenizer,devices=2,tensor_model_parallel_size=2 \\\n --tasks hellaswag\n```\n\n**Expert Parallelism for MoE models (EP=4):**\n\n```bash\ntorchrun --nproc-per-node=4 -m lm_eval --model megatron_lm \\\n --model_args load=/path/to/moe_checkpoint,tokenizer_model=/path/to/tokenizer,devices=4,expert_model_parallel_size=4 \\\n --tasks hellaswag\n```\n\n**Using extra_args for additional Megatron options:**\n\n```bash\nlm_eval --model megatron_lm \\\n --model_args load=/path/to/checkpoint,tokenizer_model=/path/to/tokenizer,extra_args=\"--no-rope-fusion --trust-remote-code\" \\\n --tasks hellaswag\n```\n\n> [!Note]\n> The `--use-checkpoint-args` flag is enabled by default, which loads model architecture parameters from the checkpoint. For checkpoints converted via Megatron-Bridge, this typically includes all necessary model configuration.\n\n#### Multi-GPU evaluation with OpenVINO models\n\nPipeline parallelism during evaluation is supported with OpenVINO models\n\nTo enable pipeline parallelism, set the `model_args` of `pipeline_parallel`. In addition, you also have to set up `device` to value `HETERO:,` for example `HETERO:GPU.1,GPU.0` For example, the command to use pipeline parallelism of 2 is:\n\n```bash\nlm_eval --model openvino \\\n --tasks wikitext \\\n --model_args pretrained=,pipeline_parallel=True \\\n --device HETERO:GPU.1,GPU.0\n```\n\n### Tensor + Data Parallel and Optimized Inference with `vLLM`\n\nWe also support vLLM for faster inference on [supported model types](https://docs.vllm.ai/en/latest/models/supported_models.html), especially faster when splitting a model across multiple GPUs. For single-GPU or multi-GPU — tensor parallel, data parallel, or a combination of both — inference, for example:\n\n```bash\nlm_eval --model vllm \\\n --model_args pretrained={model_name},tensor_parallel_size={GPUs_per_model},dtype=auto,gpu_memory_utilization=0.8,data_parallel_size={model_replicas} \\\n --tasks lambada_openai \\\n --batch_size auto\n```\n\nTo use vllm, do `pip install \"lm_eval[vllm]\"`. For a full list of supported vLLM configurations, please reference our [vLLM integration](https://github.com/EleutherAI/lm-evaluation-harness/blob/e74ec966556253fbe3d8ecba9de675c77c075bce/lm_eval/models/vllm_causallms.py) and the vLLM documentation.\n\nvLLM occasionally differs in output from Huggingface. We treat Huggingface as the reference implementation and provide a [script](./scripts/model_comparator.py) for checking the validity of vllm results against HF.\n\n> [!Tip]\n> For fastest performance, we recommend using `--batch_size auto` for vLLM whenever possible, to leverage its continuous batching functionality!\n\n> [!Tip]\n> Passing `max_model_len=4096` or some other reasonable default to vLLM through model args may cause speedups or prevent out-of-memory errors when trying to use auto batch size, such as for Mistral-7B-v0.1 which defaults to a maximum length of 32k.\n\n### Tensor + Data Parallel and Fast Offline Batching Inference with `SGLang`\n\nWe support SGLang for efficient offline batch inference. Its **[Fast Backend Runtime](https://docs.sglang.ai/index.html)** delivers high performance through optimized memory management and parallel processing techniques. Key features include tensor parallelism, continuous batching, and support for various quantization methods (FP8/INT4/AWQ/GPTQ).\n\nTo use SGLang as the evaluation backend, please **install it in advance** via SGLang documents [here](https://docs.sglang.io/get_started/install.html#install-sglang).\n\n> [!Tip]\n> Due to the installing method of [`Flashinfer`](https://docs.flashinfer.ai/)-- a fast attention kernel library, we don't include the dependencies of `SGLang` within [pyproject.toml](pyproject.toml). Note that the `Flashinfer` also has some requirements on `torch` version.\n\nSGLang's server arguments are slightly different from other backends, see [here](https://docs.sglang.io/advanced_features/server_arguments.html) for more information. We provide an example of the usage here:\n\n```bash\nlm_eval --model sglang \\\n --model_args pretrained={model_name},dp_size={data_parallel_size},tp_size={tensor_parallel_size},dtype=auto \\\n --tasks gsm8k_cot \\\n --batch_size auto\n```\n\n> [!Tip]\n> When encountering out-of-memory (OOM) errors (especially for multiple-choice tasks), try these solutions:\n>\n> 1. Use a manual `batch_size`, rather than `auto`.\n> 2. Lower KV cache pool memory usage by adjusting `mem_fraction_static` - Add to your model arguments for example `--model_args pretrained=...,mem_fraction_static=0.7`.\n> 3. Increase tensor parallel size `tp_size` (if using multiple GPUs).\n\n### Windows ML\n\nWe support **Windows ML** for hardware-accelerated inference on Windows platforms. This enables evaluation on CPU, GPU, and **NPU (Neural Processing Unit)** devices.\n\nWindows ML?\nhttps://learn.microsoft.com/en-us/windows/ai/new-windows-ml/overview\n\nTo use Windows ML, install the required dependencies:\n\n```bash\npip install wasdk-Microsoft.Windows.AI.MachineLearning[all] wasdk-Microsoft.Windows.ApplicationModel.DynamicDependency.Bootstrap onnxruntime-windowsml onnxruntime-genai-winml\n```\n\nEvaluate an ONNX Runtime GenAI LLM on NPU/GPU/CPU on Windows:\n\n```bash\nlm_eval --model winml \\\n --model_args pretrained=/path/to/onnx/model \\\n --tasks mmlu \\\n --batch_size 1\n```\n\n> [!Note]\n> The Windows ML backend is ONLY for ONNX Runtime GenAI model format. Models targeting `transformers.js` won't work. You can verify this by finding the `genai_config.json` file in the model folder.\n\n> [!Note]\n> To run an ONNX Runtime GenAI model on the target device, you MUST convert the original model to that vendor and device type. Converted models won't work / work well on other vendor or device types. To learn more on model conversion, please visit [Microsoft AI Tool Kit](https://code.visualstudio.com/docs/intelligentapps/modelconversion)\n\n### Model APIs and Inference Servers\n\n> [!Important]\n> To use API-based models, first install: `pip install \"lm_eval[api]\"`\n\nOur library also supports the evaluation of models served via several commercial APIs, and we hope to implement support for the most commonly used performant local/self-hosted inference servers.\n\nTo call a hosted model, use:\n\n```bash\nexport OPENAI_API_KEY=YOUR_KEY_HERE\nlm_eval --model openai-completions \\\n --model_args model=davinci-002 \\\n --tasks lambada_openai,hellaswag\n```\n\nWe also support using your own local inference server with servers that mirror the OpenAI Completions and ChatCompletions APIs.\n\n```bash\nlm_eval --model local-completions --tasks gsm8k --model_args model=facebook/opt-125m,base_url=http://{yourip}:8000/v1/completions,num_concurrent=1,max_retries=3,tokenized_requests=False,batch_size=16\n```\n\nNote that for externally hosted models, configs such as `--device` which relate to where to place a local model should not be used and do not function. Just like you can use `--model_args` to pass arbitrary arguments to the model constructor for local models, you can use it to pass arbitrary arguments to the model API for hosted models. See the documentation of the hosting service for information on what arguments they support.\n\n| API or Inference Server | Implemented? | `--model ` name | Models supported: | Request Types: |\n|---------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|-----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|\n| OpenAI Completions | :heavy_check_mark: | `openai-completions`, `local-completions` | All OpenAI Completions API models | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| OpenAI ChatCompletions | :heavy_check_mark: | `openai-chat-completions`, `local-chat-completions` | [All ChatCompletions API models](https://platform.openai.com/docs/guides/gpt) | `generate_until` (no logprobs) |\n| Anthropic | :heavy_check_mark: | `anthropic` | [Supported Anthropic Engines](https://docs.anthropic.com/claude/reference/selecting-a-model) | `generate_until` (no logprobs) |\n| Anthropic Chat | :heavy_check_mark: | `anthropic-chat`, `anthropic-chat-completions` | [Supported Anthropic Engines](https://docs.anthropic.com/claude/docs/models-overview) | `generate_until` (no logprobs) |\n| Textsynth | :heavy_check_mark: | `textsynth` | [All supported engines](https://textsynth.com/documentation.html#engines) | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| Cohere | [:hourglass: - blocked on Cohere API bug](https://github.com/EleutherAI/lm-evaluation-harness/pull/395) | N/A | [All `cohere.generate()` engines](https://docs.cohere.com/docs/models) | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| [Llama.cpp](https://github.com/ggerganov/llama.cpp) (via [llama-cpp-python](https://github.com/abetlen/llama-cpp-python)) | :heavy_check_mark: | `gguf`, `ggml` | [All models supported by llama.cpp](https://github.com/ggerganov/llama.cpp) | `generate_until`, `loglikelihood`, (perplexity evaluation not yet implemented) |\n| vLLM | :heavy_check_mark: | `vllm` | [Most HF Causal Language Models](https://docs.vllm.ai/en/latest/models/supported_models.html) | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| Mamba | :heavy_check_mark: | `mamba_ssm` | [Mamba architecture Language Models via the `mamba_ssm` package](https://huggingface.co/state-spaces) | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| Huggingface Optimum (Causal LMs) | :heavy_check_mark: | `openvino` | Any decoder-only AutoModelForCausalLM converted with Huggingface Optimum into OpenVINO™ Intermediate Representation (IR) format | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| Huggingface Optimum-intel IPEX (Causal LMs) | :heavy_check_mark: | `ipex` | Any decoder-only AutoModelForCausalLM | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| Huggingface Optimum-habana (Causal LMs) | :heavy_check_mark: | `habana` | Any decoder-only AutoModelForCausalLM | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| Neuron via AWS Inf2 (Causal LMs) | :heavy_check_mark: | `neuronx` | Any decoder-only AutoModelForCausalLM supported to run on [huggingface-ami image for inferentia2](https://aws.amazon.com/marketplace/pp/prodview-gr3e6yiscria2) | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| NVIDIA NeMo | :heavy_check_mark: | `nemo_lm` | [All supported models](https://docs.nvidia.com/nemo-framework/user-guide/24.09/nemotoolkit/core/core.html#nemo-models) | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| NVIDIA Megatron-LM | :heavy_check_mark: | `megatron_lm` | [Megatron-LM GPT models](https://github.com/NVIDIA/Megatron-LM) (standard and distributed checkpoints) | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| Watsonx.ai | :heavy_check_mark: | `watsonx_llm` | [Supported Watsonx.ai Engines](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx) | `generate_until` `loglikelihood` |\n| Windows ML | :heavy_check_mark: | `winml` | [ONNX models in GenAI format](https://code.visualstudio.com/docs/intelligentapps/modelconversion) | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n| [Your local inference server!](docs/API_guide.md) | :heavy_check_mark: | `local-completions` or `local-chat-completions` | Support for OpenAI API-compatible servers, with easy customization for other APIs. | `generate_until`, `loglikelihood`, `loglikelihood_rolling` |\n\nModels which do not supply logits or logprobs can be used with tasks of type `generate_until` only, while local models, or APIs that supply logprobs/logits of their prompts, can be run on all task types: `generate_until`, `loglikelihood`, `loglikelihood_rolling`, and `multiple_choice`.\n\nFor more information on the different task `output_types` and model request types, see [our documentation](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/docs/model_guide.md#interface).\n\n> [!Note]\n> For best performance with closed chat model APIs such as Anthropic Claude 3 and GPT-4, we recommend carefully looking at a few sample outputs using `--limit 10` first to confirm answer extraction and scoring on generative tasks is performing as expected. providing `system=\"\"` within `--model_args` for anthropic-chat-completions, to instruct the model what format to respond in, may be useful.\n\n### Other Frameworks\n\nA number of other libraries contain scripts for calling the eval harness through their library. These include [GPT-NeoX](https://github.com/EleutherAI/gpt-neox/blob/main/eval_tasks/eval_adapter.py), [Megatron-DeepSpeed](https://github.com/microsoft/Megatron-DeepSpeed/blob/main/examples/MoE/readme_evalharness.md), and [mesh-transformer-jax](https://github.com/kingoflolz/mesh-transformer-jax/blob/master/eval_harness.py).\n\nTo create your own custom integration you can follow instructions from [this tutorial](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/docs/interface.md#external-library-usage).\n\n### Additional Features\n\n> [!Note]\n> For tasks unsuitable for direct evaluation — either due risks associated with executing untrusted code or complexities in the evaluation process — the `--predict_only` flag is available to obtain decoded generations for post-hoc evaluation.\n\nIf you have a Metal compatible Mac, you can run the eval harness using the MPS back-end by replacing `--device cuda:0` with `--device mps` (requires PyTorch version 2.1 or higher). **Note that the PyTorch MPS backend is still in early stages of development, so correctness issues or unsupported operations may exist. If you observe oddities in model performance on the MPS back-end, we recommend first checking that a forward pass of your model on `--device cpu` and `--device mps` match.**\n\n> [!Note]\n> You can inspect what the LM inputs look like by running the following command:\n>\n> ```bash\n> python write_out.py \\\n> --tasks \\\n> --num_fewshot 5 \\\n> --num_examples 10 \\\n> --output_base_path /path/to/output/folder\n> ```\n>\n> This will write out one text file for each task.\n\nTo verify the data integrity of the tasks you're performing in addition to running the tasks themselves, you can use the `--check_integrity` flag:\n\n```bash\nlm_eval --model openai \\\n --model_args engine=davinci-002 \\\n --tasks lambada_openai,hellaswag \\\n --check_integrity\n```\n\n## Advanced Usage Tips\n\nFor models loaded with the HuggingFace `transformers` library, any arguments provided via `--model_args` get passed to the relevant constructor directly. This means that anything you can do with `AutoModel` can be done with our library. For example, you can pass a local path via `pretrained=` or use models finetuned with [PEFT](https://github.com/huggingface/peft) by taking the call you would run to evaluate the base model and add `,peft=PATH` to the `model_args` argument:\n\n```bash\nlm_eval --model hf \\\n --model_args pretrained=EleutherAI/gpt-j-6b,parallelize=True,load_in_4bit=True,peft=nomic-ai/gpt4all-j-lora \\\n --tasks openbookqa,arc_easy,winogrande,hellaswag,arc_challenge,piqa,boolq \\\n --device cuda:0\n```\n\nModels provided as delta weights can be easily loaded using the Hugging Face transformers library. Within --model_args, set the delta argument to specify the delta weights, and use the pretrained argument to designate the relative base model to which they will be applied:\n\n```bash\nlm_eval --model hf \\\n --model_args pretrained=Ejafa/llama_7B,delta=lmsys/vicuna-7b-delta-v1.1 \\\n --tasks hellaswag\n```\n\nGPTQ quantized models can be loaded using [GPTQModel](https://github.com/ModelCloud/GPTQModel) (faster) or [AutoGPTQ](https://github.com/PanQiWei/AutoGPTQ)\n\nGPTQModel: add `,gptqmodel=True` to `model_args`\n\n```bash\nlm_eval --model hf \\\n --model_args pretrained=model-name-or-path,gptqmodel=True \\\n --tasks hellaswag\n```\n\nAutoGPTQ: add `,autogptq=True` to `model_args`:\n\n```bash\nlm_eval --model hf \\\n --model_args pretrained=model-name-or-path,autogptq=model.safetensors,gptq_use_triton=True \\\n --tasks hellaswag\n```\n\nWe support wildcards in task names, for example you can run all of the machine-translated lambada tasks via `--task lambada_openai_mt_*`.\n\n## Saving & Caching Results\n\nTo save evaluation results provide an `--output_path`. We also support logging model responses with the `--log_samples` flag for post-hoc analysis.\n\n> [!TIP]\n> Use `--use_cache ` to cache evaluation results and skip previously evaluated samples when resuming runs of the same (model, task) pairs. Note that caching is rank-dependent, so restart with the same GPU count if interrupted. You can also use --cache_requests to save dataset preprocessing steps for faster evaluation resumption.\n\nTo push results and samples to the Hugging Face Hub, first ensure an access token with write access is set in the `HF_TOKEN` environment variable. Then, use the `--hf_hub_log_args` flag to specify the organization, repository name, repository visibility, and whether to push results and samples to the Hub - [example dataset on the HF Hub](https://huggingface.co/datasets/KonradSzafer/lm-eval-results-demo). For instance:\n\n```bash\nlm_eval --model hf \\\n --model_args pretrained=model-name-or-path,autogptq=model.safetensors,gptq_use_triton=True \\\n --tasks hellaswag \\\n --log_samples \\\n --output_path results \\\n --hf_hub_log_args hub_results_org=EleutherAI,hub_repo_name=lm-eval-results,push_results_to_hub=True,push_samples_to_hub=True,public_repo=False \\\n```\n\nThis allows you to easily download the results and samples from the Hub, using:\n\n```python\nfrom datasets import load_dataset\n\nload_dataset(\"EleutherAI/lm-eval-results-private\", \"hellaswag\", \"latest\")\n```\n\nFor a full list of supported arguments, check out the [interface](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/docs/interface.md) guide in our documentation!\n\n## Visualizing Results\n\nYou can seamlessly visualize and analyze the results of your evaluation harness runs using both Weights & Biases (W&B) and Zeno.\n\n### Zeno\n\nYou can use [Zeno](https://zenoml.com) to visualize the results of your eval harness runs.\n\nFirst, head to [hub.zenoml.com](https://hub.zenoml.com) to create an account and get an API key [on your account page](https://hub.zenoml.com/account).\nAdd this key as an environment variable:\n\n```bash\nexport ZENO_API_KEY=[your api key]\n```\n\nYou'll also need to install the `lm_eval[zeno]` package extra.\n\nTo visualize the results, run the eval harness with the `log_samples` and `output_path` flags.\nWe expect `output_path` to contain multiple folders that represent individual model names.\nYou can thus run your evaluation on any number of tasks and models and upload all of the results as projects on Zeno.\n\n```bash\nlm_eval \\\n --model hf \\\n --model_args pretrained=EleutherAI/gpt-j-6B \\\n --tasks hellaswag \\\n --device cuda:0 \\\n --batch_size 8 \\\n --log_samples \\\n --output_path output/gpt-j-6B\n```\n\nThen, you can upload the resulting data using the `zeno_visualize` script:\n\n```bash\npython scripts/zeno_visualize.py \\\n --data_path output \\\n --project_name \"Eleuther Project\"\n```\n\nThis will use all subfolders in `data_path` as different models and upload all tasks within these model folders to Zeno.\nIf you run the eval harness on multiple tasks, the `project_name` will be used as a prefix and one project will be created per task.\n\nYou can find an example of this workflow in [examples/visualize-zeno.ipynb](examples/visualize-zeno.ipynb).\n\n### Weights and Biases\n\nWith the [Weights and Biases](https://wandb.ai/site) integration, you can now spend more time extracting deeper insights into your evaluation results. The integration is designed to streamline the process of logging and visualizing experiment results using the Weights & Biases (W&B) platform.\n\nThe integration provide functionalities\n\n- to automatically log the evaluation results,\n- log the samples as W&B Tables for easy visualization,\n- log the `results.json` file as an artifact for version control,\n- log the `_eval_samples.json` file if the samples are logged,\n- generate a comprehensive report for analysis and visualization with all the important metric,\n- log task and cli specific configs,\n- and more out of the box like the command used to run the evaluation, GPU/CPU counts, timestamp, etc.\n\nFirst you'll need to install the lm_eval[wandb] package extra. Do `pip install lm_eval[wandb]`.\n\nAuthenticate your machine with an your unique W&B token. Visit https://wandb.ai/authorize to get one. Do `wandb login` in your command line terminal.\n\nRun eval harness as usual with a `wandb_args` flag. Use this flag to provide arguments for initializing a wandb run ([wandb.init](https://docs.wandb.ai/ref/python/init)) as comma separated string arguments.\n\n```bash\nlm_eval \\\n --model hf \\\n --model_args pretrained=microsoft/phi-2,trust_remote_code=True \\\n --tasks hellaswag,mmlu_abstract_algebra \\\n --device cuda:0 \\\n --batch_size 8 \\\n --output_path output/phi-2 \\\n --limit 10 \\\n --wandb_args project=lm-eval-harness-integration \\\n --log_samples\n```\n\nIn the stdout, you will find the link to the W&B run page as well as link to the generated report. You can find an example of this workflow in [examples/visualize-wandb.ipynb](examples/visualize-wandb.ipynb), and an example of how to integrate it beyond the CLI.\n\n## Contributing\n\nCheck out our [open issues](https://github.com/EleutherAI/lm-evaluation-harness/issues) and feel free to submit pull requests!\n\nFor more information on the library and how everything fits together, see our [documentation pages](https://github.com/EleutherAI/lm-evaluation-harness/tree/main/docs).\n\nTo get started with development, first clone the repository and install the dev dependencies:\n\n```bash\ngit clone https://github.com/EleutherAI/lm-evaluation-harness\ncd lm-evaluation-harness\npip install -e \".[dev,hf]\"\n````\n\n### Implementing new tasks\n\nTo implement a new task in the eval harness, see [this guide](./docs/new_task_guide.md).\n\nIn general, we follow this priority list for addressing concerns about prompting and other eval details:\n\n1. If there is widespread agreement among people who train LLMs, use the agreed upon procedure.\n2. If there is a clear and unambiguous official implementation, use that procedure.\n3. If there is widespread agreement among people who evaluate LLMs, use the agreed upon procedure.\n4. If there are multiple common implementations but not universal or widespread agreement, use our preferred option among the common implementations. As before, prioritize choosing from among the implementations found in LLM training papers.\n\nThese are guidelines and not rules, and can be overruled in special circumstances.\n\nWe try to prioritize agreement with the procedures used by other groups to decrease the harm when people inevitably compare runs across different papers despite our discouragement of the practice. Historically, we also prioritized the implementation from [Language Models are Few Shot Learners](https://arxiv.org/abs/2005.14165) as our original goal was specifically to compare results with that paper.\n\n### Support\n\nThe best way to get support is to open an issue on this repo or join the [EleutherAI Discord server](https://discord.gg/eleutherai). The `#lm-thunderdome` channel is dedicated to developing this project and the `#release-discussion` channel is for receiving support for our releases. If you've used the library and have had a positive (or negative) experience, we'd love to hear from you!\n\n## Optional Extras\n\nExtras dependencies can be installed via `pip install -e \".[NAME]\"`\n\n### Model Backends\n\nThese extras install dependencies required to run specific model backends:\n\n| NAME | Description |\n|----------------|--------------------------------------------------|\n| hf | HuggingFace Transformers (torch, transformers, accelerate, peft) |\n| vllm | vLLM fast inference |\n| api | API models (OpenAI, Anthropic, local servers) |\n| gptq | AutoGPTQ quantized models |\n| gptqmodel | GPTQModel quantized models |\n| ibm_watsonx_ai | IBM watsonx.ai models |\n| ipex | Intel IPEX backend |\n| habana | Intel Gaudi backend |\n| optimum | Intel OpenVINO models |\n| neuronx | AWS Inferentia2 instances |\n| winml | Windows ML (ONNX Runtime GenAI) - CPU/GPU/NPU |\n| sparsify | Sparsify model steering |\n| sae_lens | SAELens model steering |\n\n### Task Dependencies\n\nThese extras install dependencies required for specific evaluation tasks:\n\n| NAME | Description |\n|----------------------|--------------------------------|\n| tasks | All task-specific dependencies |\n| acpbench | ACP Bench tasks |\n| audiolm_qwen | Qwen2 audio models |\n| ifeval | IFEval task |\n| japanese_leaderboard | Japanese LLM tasks |\n| longbench | LongBench tasks |\n| math | Math answer checking |\n| multilingual | Multilingual tokenizers |\n| ruler | RULER tasks |\n\n### Development & Utilities\n\n| NAME | Description |\n|---------------|--------------------------------|\n| dev | Linting & contributions |\n| hf_transfer | Speed up HF downloads |\n| sentencepiece | Sentencepiece tokenizer |\n| unitxt | Unitxt tasks |\n| wandb | Weights & Biases logging |\n| zeno | Zeno result visualization |\n\n## Cite as\n\n```text\n@misc{eval-harness,\n author = {Gao, Leo and Tow, Jonathan and Abbasi, Baber and Biderman, Stella and Black, Sid and DiPofi, Anthony and Foster, Charles and Golding, Laurence and Hsu, Jeffrey and Le Noac'h, Alain and Li, Haonan and McDonell, Kyle and Muennighoff, Niklas and Ociepa, Chris and Phang, Jason and Reynolds, Laria and Schoelkopf, Hailey and Skowron, Aviya and Sutawika, Lintang and Tang, Eric and Thite, Anish and Wang, Ben and Wang, Kevin and Zou, Andy},\n title = {The Language Model Evaluation Harness},\n month = 07,\n year = 2024,\n publisher = {Zenodo},\n version = {v0.4.3},\n doi = {10.5281/zenodo.12608602},\n url = {https://zenodo.org/records/12608602}\n}\n```\n" }, { "path": "docs/API_guide.md", "content": "# TemplateAPI Usage Guide\n\nThe `TemplateAPI` class is a versatile superclass designed to facilitate the integration of various API-based language models into the lm-evaluation-harness framework. This guide will explain how to use and extend the `TemplateAPI` class to implement your own API models. If your API implements the OpenAI API you can use the `local-completions` or the `local-chat-completions` (defined [here](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/models/openai_completions.py)) model types, which can also serve as examples of how to effectively subclass this template.\n\n## Overview\n\nThe `TemplateAPI` class provides a template for creating API-based model implementations. It handles common functionalities such as:\n\n- Tokenization (optional)\n- Batch processing\n- Caching\n- Retrying failed requests\n- Parsing API responses\n\nTo use this class, you typically need to subclass it and implement specific methods for your API.\n\n## Key Methods to Implement\n\nWhen subclassing `TemplateAPI`, you need to implement the following methods:\n\n1. `_create_payload`: Creates the JSON payload for API requests.\n2. `parse_logprobs`: Parses log probabilities from API responses.\n3. `parse_generations`: Parses generated text from API responses.\n\nOptional Properties:\n\n4. `header`: Returns the headers for the API request.\n5. `api_key`: Returns the API key for authentication (if required).\n\nYou may also need to override other methods or properties depending on your API's specific requirements.\n\n> [!NOTE]\n> Currently loglikelihood and MCQ based tasks (such as MMLU) are only supported for completion endpoints. Not for chat-completion — those that expect a list of dicts — endpoints! Completion APIs which support instruct tuned models can be evaluated with the `--apply_chat_template` option in order to simultaneously evaluate models using a chat template format while still being able to access the model logits needed for loglikelihood-based tasks.\n\n## TemplateAPI Arguments\n\nWhen initializing a `TemplateAPI` instance or a subclass, you can provide several arguments to customize its behavior. Here's a detailed explanation of some important arguments:\n\n- `model` or `pretrained` (str):\n - The name or identifier of the model to use.\n - `model` takes precedence over `pretrained` when both are provided.\n\n- `base_url` (str):\n - The base URL for the API endpoint.\n\n- `tokenizer` (str, optional):\n - The name or path of the tokenizer to use.\n - If not provided, it defaults to using the same tokenizer name as the model.\n\n- `num_concurrent` (int):\n - Number of concurrent requests to make to the API.\n - Useful for APIs that support parallel processing.\n - Default is 1 (sequential processing).\n\n- `timeout` (int, optional):\n - Timeout for API requests in seconds.\n - Default is 30.\n\n- `tokenized_requests` (bool):\n - Determines whether the input is pre-tokenized. Defaults to `True`.\n - Requests can be sent in either tokenized form (`list[list[int]]`) or as text (`list[str]`, or `str` for batch_size=1).\n - For loglikelihood-based tasks, prompts require tokenization to calculate the context length. If `False` prompts are decoded back to text before being sent to the API.\n - Not as important for `generate_until` tasks.\n - Ignored for chat formatted inputs (list[dict...]) or if tokenizer_backend is None.\n\n- `tokenizer_backend` (str, optional):\n - Required for loglikelihood-based or MCQ tasks.\n - Specifies the tokenizer library to use. Options are \"tiktoken\", \"huggingface\", or None.\n - Default is \"huggingface\".\n\n- `max_length` (int, optional):\n - Maximum length of input + output.\n - Default is 2048.\n\n- `max_retries` (int, optional):\n - Maximum number of retries for failed API requests.\n - Default is 3.\n\n- `max_gen_toks` (int, optional):\n - Maximum number of tokens to generate in completion tasks.\n - Default is 256 or set in task yaml.\n\n- `batch_size` (int or str, optional):\n - Number of requests to batch together (if the API supports batching).\n - Can be an integer or \"auto\" (which defaults to 1 for API models).\n - Default is 1.\n\n- `seed` (int, optional):\n - Random seed for reproducibility.\n - Default is 1234.\n\n- `add_bos_token` (bool, optional):\n - Whether to add the beginning-of-sequence token to inputs (when tokenizing).\n - Default is False.\n\n- `custom_prefix_token_id` (int, optional):\n - Custom token ID to use as a prefix for inputs.\n - If not provided, uses the model's default BOS or EOS token (if `add_bos_token` is True).\n\n- `verify_certificate` (bool, optional):\n - Whether to validate the certificate of the API endpoint (if HTTPS).\n - Default is True.\n\n- `header` (dict, optional):\n - Custom headers for API requests.\n - If not provided, uses `{\"Authorization\": f\"Bearer {self.api_key}\"}` by default.\n\nExample usage:\n\n```python\nclass MyAPIModel(TemplateAPI):\n def __init__(self, **kwargs):\n super().__init__(\n model=\"my-model\",\n base_url=\"https://api.mymodel.com/v1/completions\",\n tokenizer_backend=\"huggingface\",\n num_concurrent=5,\n max_retries=5,\n batch_size=10,\n **kwargs\n )\n\n # Implement other required methods...\n```\n\nWhen subclassing `TemplateAPI`, you can override these arguments in your `__init__` method to set default values specific to your API. You can also add additional (potentially user-specified) arguments as needed for your specific implementation.\n\n## Example Implementation: OpenAI API\n\nThe `OpenAICompletionsAPI` and `OpenAIChatCompletion` ([here](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/models/openai_completions.py) classes demonstrate how to implement API models using the `TemplateAPI` class. Here's a breakdown of the key components:\n\n### 1. Subclassing and Initialization\n\n```python\n@register_model(\"openai-completions\")\nclass OpenAICompletionsAPI(LocalCompletionsAPI):\n def __init__(\n self,\n base_url=\"https://api.openai.com/v1/completions\",\n tokenizer_backend=\"tiktoken\",\n **kwargs,\n ):\n super().__init__(\n base_url=base_url, tokenizer_backend=tokenizer_backend, **kwargs\n )\n```\n\n### 2. Implementing API Key Retrieval\n\n```python\n@cached_property\ndef api_key(self):\n key = os.environ.get(\"OPENAI_API_KEY\", None)\n if key is None:\n raise ValueError(\n \"API key not found. Please set the OPENAI_API_KEY environment variable.\"\n )\n return key\n```\n\n### 3. Creating the Payload\n\n```python\ndef _create_payload(\n self,\n messages: Union[List[List[int]], List[dict], List[str], str],\n generate=False,\n gen_kwargs: Optional[dict] = None,\n **kwargs,\n) -> dict:\n if generate:\n # ... (implementation for generation)\n else:\n # ... (implementation for log likelihood)\n```\n\n### 4. Parsing API Responses\n\n```python\n@staticmethod\ndef parse_logprobs(\n outputs: Union[Dict, List[Dict]],\n tokens: List[List[int]] = None,\n ctxlens: List[int] = None,\n **kwargs,\n) -> List[Tuple[float, bool]]:\n # ... (implementation)\n\n@staticmethod\ndef parse_generations(outputs: Union[Dict, List[Dict]], **kwargs) -> List[str]:\n # ... (implementation)\n```\n\nThe requests are initiated in the `model_call` or the `amodel_call` methods.\n\n## Implementing Your Own API Model\n\nTo implement your own API model:\n\n1. Subclass `TemplateAPI` or one of its subclasses (e.g., `LocalCompletionsAPI`).\n2. Override the `__init__` method if you need to set specific parameters.\n3. Implement the `_create_payload` and `header` methods to create the appropriate payload for your API.\n4. Implement the `parse_logprobs` and `parse_generations` methods to parse your API's responses.\n5. Override the `api_key` property if your API requires authentication.\n6. Override any other methods as necessary to match your API's behavior.\n\n## Best Practices\n\n1. Use the `@register_model` decorator to register your model with the framework (and import it in `lm_eval/models/__init__.py`!).\n2. Use environment variables for sensitive information like API keys.\n3. Properly handle batching and concurrent requests if supported by your API.\n" }, { "path": "docs/CONTRIBUTING.md", "content": "# Contributing to LM Evaluation Harness\n\nWelcome and thank you for your interest in the LM Evaluation Harness! We welcome contributions and feedback and appreciate your time spent with our library, and hope you find it useful!\n\n## Important Resources\n\nThere are several places information about LM Evaluation Harness is located:\n\n- Our [documentation pages](https://github.com/EleutherAI/lm-evaluation-harness/tree/main/docs)\n- We occasionally use [GitHub Milestones](https://github.com/EleutherAI/lm-evaluation-harness/milestones) to track progress toward specific near-term version releases.\n- We maintain a [Project Board](https://github.com/orgs/EleutherAI/projects/25) for tracking current work items and PRs, and for future roadmap items or feature requests.\n- Further discussion and support conversations are located in the #lm-thunderdome channel of the [EleutherAI discord](https://discord.gg/eleutherai).\n\n## Code Style\n\nLM Evaluation Harness uses [ruff](https://github.com/astral-sh/ruff) for linting via [pre-commit](https://pre-commit.com/).\n\nYou can install linters and dev tools via\n\n```pip install lm_eval[dev]``` or ```pip install -e \".[dev]\"```\n\nThen, run\n\n```pre-commit install```\n\nin order to ensure linters and other checks will be run upon committing.\n\n## Testing\n\nWe use [pytest](https://docs.pytest.org/en/latest/) for running unit tests. All library unit tests can be run via:\n\n```bash\npython -m pytest --showlocals -s -vv -n=auto --ignore=tests/models/test_openvino.py\n```\n\n## Verbose logging\n\nYou can enable verbose logging with the environment variable `LMEVAL_LOG_LEVEL=\"debug\"`.\n\n## Contributor License Agreement\n\nWe ask that new contributors agree to a Contributor License Agreement affirming that EleutherAI has the rights to use your contribution to our library.\nFirst-time pull requests will have a reply added by @CLAassistant containing instructions for how to confirm this, and we require it before merging your PR.\n\n## Contribution Best Practices\n\nWe recommend a few best practices to make your contributions or reported errors easier to assist with.\n\n**For Pull Requests:**\n\n- PRs should be titled descriptively, and be opened with a brief description of the scope and intent of the new contribution.\n- New features should have appropriate documentation added alongside them.\n- Aim for code maintainability, and minimize code copying.\n- If opening a task, try to share test results on the task using a publicly-available model, and if any public results are available on the task, compare to them.\n\n**For Feature Requests:**\n\n- Provide a short paragraph's worth of description. What is the feature you are requesting? What is its motivation, and an example use case of it? How does this differ from what is currently supported?\n\n**For Bug Reports**:\n\n- Provide a short description of the bug.\n- Provide a *reproducible example*--what is the command you run with our library that results in this error? Have you tried any other steps to resolve it?\n- Provide a *full error traceback* of the error that occurs, if applicable. A one-line error message or small screenshot snippet is unhelpful without the surrounding context.\n- Note what version of the codebase you are using, and any specifics of your environment and setup that may be relevant.\n\n**For Requesting New Tasks**:\n\n- Provide a 1-2 sentence description of what the task is and what it evaluates.\n- Provide a link to the paper introducing the task.\n- Provide a link to where the dataset can be found.\n- Provide a link to a paper containing results on an open-source model on the task, for use in comparisons and implementation validation.\n- If applicable, link to any codebase that has implemented the task (especially the original publication's codebase, if existent).\n\n## How Can I Get Involved?\n\nTo quickly get started, we maintain a list of good first issues, which can be found [on our project board](https://github.com/orgs/EleutherAI/projects/25/views/8) or by [filtering GH Issues](https://github.com/EleutherAI/lm-evaluation-harness/issues?q=is%3Aopen+label%3A%22good+first+issue%22+label%3A%22help+wanted%22). These are typically smaller code changes or self-contained features which can be added without extensive familiarity with library internals, and we recommend new contributors consider taking a stab at one of these first if they are feeling uncertain where to begin.\n\nThere are a number of distinct ways to contribute to LM Evaluation Harness, and all are extremely helpful! A sampling of ways to contribute include:\n\n- **Implementing and verifying new evaluation tasks**: Is there a task you'd like to see LM Evaluation Harness support? Consider opening an issue requesting it, or helping add it! Verifying and cross-checking task implementations with their original versions is also a very valuable form of assistance in ensuring standardized evaluation.\n- **Improving documentation** - Improvements to the documentation, or noting pain points / gaps in documentation, are helpful in order for us to improve the user experience of the library and clarity + coverage of documentation.\n- **Testing and devops** - We are very grateful for any assistance in adding tests for the library that can be run for new PRs, and other devops workflows.\n- **Adding new modeling / inference library integrations** - We hope to support a broad range of commonly-used inference libraries popular among the community, and welcome PRs for new integrations, so long as they are documented properly and maintainable.\n- **Proposing or Contributing New Features** - We want LM Evaluation Harness to support a broad range of evaluation usecases. If you have a feature that is not currently supported but desired, feel free to open an issue describing the feature and, if applicable, how you intend to implement it. We would be happy to give feedback on the cleanest way to implement new functionalities and are happy to coordinate with interested contributors via GH discussions or via discord.\n\nWe hope that this has been helpful, and appreciate your interest in contributing! Further questions can be directed to [our Discord](discord.gg/eleutherai).\n" }, { "path": "docs/README.md", "content": "# Eval Harness Documentation\n\nWelcome to the docs for the LM Evaluation Harness!\n\n## Table of Contents\n\n* To learn about the public interface of the library, as well as how to evaluate via the command line or as integrated into an external library, see the [Interface](./interface.md).\n* To learn how to add a new library, API, or model type to the library, as well as a quick explainer on the types of ways to evaluate an LM, see the [Model Guide](./model_guide.md).\n * For an extended description of how to extend the library to new model classes served over an API, see the [API Guide](./API_guide.md).\n* For a crash course on adding new tasks to the library, see our [New Task Guide](./new_task_guide.md).\n* To learn more about pushing the limits of task configuration that the Eval Harness supports, see the [Task Configuration Guide](./task_guide.md).\n" }, { "path": "docs/chat-template-readme.md", "content": "# Chat Template Delimiter Handling Update\n\n## Overview\n\nThis change modifies how delimiters are handled when applying chat templates in the request construction process for likelihood and multiple-choice based tasks. When `apply_chat_template` is set to `True`, the target delimiter is now set to an empty string instead of using the configured delimiter.\n\n## Background\n\nBy default, the system uses a target delimiter (typically a whitespace \" \") between the context and target text when constructing prompts. The full string is constructed as:\n\n```text\ndoc_to_text(doc) + target_delimiter + doc_to_target(doc)\n```\n\nWhile this worked well for base models where we wanted the model to predict a single whitespace followed by the answer, chat models have their own formatting conventions that handle spacing differently.\n\n## The Change\n\n- When `apply_chat_template=True`, the target delimiter is now empty (\"\") instead of the default whitespace\n- This prevents interference between chat template formatting and the default delimiter system\n- Particularly important for multiple choice tasks where the template itself handles spacing\n\n## Example\n\n```text\n# Before (with default delimiter \" \")\nQuestion: What color is the sky?\\nAnswer: blue\n\n# After\nQuestion: What color is the sky?\\nAnswer:blue\n```\n" }, { "path": "docs/config_files.md", "content": "# Configuration Guide\n\nThis guide explains how to use YAML configuration files with `lm-eval` to define reusable evaluation settings.\n\n## Overview\n\nInstead of passing many CLI arguments, you can define evaluation parameters in a YAML configuration file:\n\n```bash\n# Instead of:\nlm-eval run --model hf --model_args pretrained=gpt2,dtype=float32 --tasks hellaswag arc_easy --num_fewshot 5 --batch_size 8 --device cuda:0\n\n# Use:\nlm-eval run --config eval_config.yaml\n```\n\nCLI arguments override config file values, so you can set defaults in a config file and override specific settings:\n\n```bash\nlm-eval run --config eval_config.yaml --tasks mmlu --limit 100\n```\n\n## Quick Reference\n\nAll configuration keys correspond directly to CLI arguments. See the [CLI Reference](interface.md#lm-eval-run) for detailed descriptions of each option.\n\n## Config Schema\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `model` | string | `\"hf\"` | Model type/provider |\n| `model_args` | dict | `{}` | Model constructor arguments |\n| `tasks` | list/string | required | Tasks to evaluate |\n| `num_fewshot` | int/null | `null` | Few-shot example count |\n| `batch_size` | int/string | `1` | Batch size or \"auto\" |\n| `max_batch_size` | int/null | `null` | Max batch size for auto |\n| `device` | string/null | `\"cuda:0\"` | Device to use |\n| `limit` | float/null | `null` | Example limit per task |\n| `samples` | dict/null | `null` | Specific sample indices |\n| `use_cache` | string/null | `null` | Response cache path |\n| `cache_requests` | string/dict | `{}` | Request cache settings |\n| `output_path` | string/null | `null` | Results output path |\n| `log_samples` | bool | `false` | Save model I/O |\n| `predict_only` | bool | `false` | Skip metrics |\n| `apply_chat_template` | bool/string | `false` | Chat template |\n| `system_instruction` | string/null | `null` | System prompt |\n| `fewshot_as_multiturn` | bool/null | `null` | Multi-turn few-shot |\n| `include_path` | string/null | `null` | External tasks path |\n| `gen_kwargs` | dict | `{}` | Generation arguments |\n| `wandb_args` | dict | `{}` | W&B init arguments |\n| `hf_hub_log_args` | dict | `{}` | HF Hub logging |\n| `seed` | list/int | `[0,1234,1234,1234]` | Random seeds |\n| `trust_remote_code` | bool | `false` | Trust remote code |\n| `metadata` | dict | `{}` | Task metadata |\n\n---\n\n## Example\n\n```yaml\n# basic_eval.yaml\nmodel: hf\nmodel_args:\n pretrained: gpt2\n dtype: float32\n\ntasks:\n - hellaswag\n - arc_easy\n\nnum_fewshot: 0\nbatch_size: auto\ndevice: cuda:0\n\noutput_path: ./results/gpt2/\nlog_samples: true\n\nwandb_args:\n project: llm-evals\n name: mistral-7b-instruct\n tags:\n - mistral\n - instruct\n - production\n\nhf_hub_log_args:\n hub_results_org: my-org\n results_repo_name: llm-eval-results\n push_results_to_hub: true\n public_repo: false\n```\n\n---\n\n## Programmatic Usage\n\nFor loading config files in Python, see the [Python API Guide](python-api.md#using-evaluatorconfig).\n\n---\n\n## Validation\n\nValidate your configuration before running:\n\n```bash\n# Check that tasks exist\nlm-eval validate --tasks hellaswag,arc_easy\n\n# With external tasks\nlm-eval validate --tasks my_task --include_path /path/to/tasks\n```\n\n---\n\n## Tips\n\n1. **Start simple**: Begin with minimal config and add options as needed\n2. **Use CLI overrides**: Set defaults in config, override with CLI for experiments\n3. **Separate concerns**: Create different configs for different model families or task sets\n4. **Version control**: Commit config files alongside results for reproducibility\n5. **Use comments**: YAML supports `#` comments to document your choices\n" }, { "path": "docs/decontamination.md", "content": "# Decontamination\n\n## Usage\n\nThe provided directory should contain\nthe ngram files and info.json produced in \"Pile Ngram Generation\" further down.\n\n```bash\npython -m lm_eval \\\n --model gpt2 \\\n --device 0 \\\n --tasks sciq\n```\n\n## Background\n\nDownstream evaluations test model generalization, and are less useful when test set data also exists in the training set, referred to as leakage or contamination.\n\nFiltering your training set against the test set is a good first step, however this isn't always possible, as in the case of a new benchmark or one that wasn't considered prior to model training. When training set filtering isn't possible, it is useful to measure the impact of test set leakage by detecting the contaminated test examples and producing a clean version of the benchmark.\n\nThe basis for our decontamination procedure can be found in Appendix C of \"Language Models are Few-Shot Learners\". OpenAI defined a test document as contaminated if any N-gram overlap existed with any training document. They used a range of N values between 8 and 13 depending on dataset, while we just used 13 for simplicity.\n\n## Implementation\n\nContamination detection can be found in `lm_eval/decontaminate.py` with supporting code in `lm_eval/decontamination/`.\n\ndecontaminate.py does the following:\n\n1. Build dictionaries of all ngrams and their corresponding evaluation/document ids.\n2. Scan through sorted files containing training set n-grams.\n3. If a match is found, the corresponding evaluation/document combinations are marked as contaminated.\n\n`lm_eval/evaluator.py` can then produce a clean version of the benchmark by excluding the results of contaminated documents. For each metric, a clean version will be shown in the results with a \"decontaminate\" suffix.\n\nThis is disabled by default for new tasks, to support decontamination on a task override the \"should_decontaminate\" and \"doc_to_decontamination_query\" methods. For more details see the [task guide](task_guide.md).\n\n## Pile Ngram Generation\n\nThe relevant scripts can be found in `scripts/clean_training_data`, which also import from\n`lm_eval/decontamination/`\n\n1. git clone https://github.com/EleutherAI/lm-evaluation-harness.git\n2. pip install -r requirements.txt\n3. Download The Pile from [The Eye](https://the-eye.eu/public/AI/pile/train/)\n4. Place pile files in \"pile\" directory under \"lm-evaluation-harness\" (or create a symlink)\n5. Run generate_13_grams.\n\n```bash\nexport PYTHONHASHSEED=0\npython -m scripts/clean_training_data/generate_13_grams \\\n -dir path/to/working/directory \\\n -n 13 \\\n -buckets 500\n```\n\nTook approximately 4 days for us. We had the time to wait, but this could be scaled out by doing partial pile scans on multiple instances of this script and merging the relevant buckets. We fixed PYTHONHASHSEED to ensure reproducibility of bucket hashing in case you need to stop and start.\n\n6. Sort the generated 13-grams.\n\n```bash\npython -m scripts/clean_training_data/sort_13_gram_buckets \\\n -dir path/to/working/directory/output\n```\n\nTook approximately 5 days for us. You could speed this up by spreading the files around to different machines and running the sort script before gathering them together.\n\n7. Compress the sorted 13 grams files and place them together with info.json.\n\nThis step only takes a few hours.\n\n```bash\npython -m scripts/clean_training_data/compress_and_package \\\n -dir path/to/working/directory \\\n -output path/to/final/directory \\\n -procs 8\n```\n" }, { "path": "docs/footguns.md", "content": "# Common Pitfalls and Troubleshooting Guide\n\nThis document highlights common pitfalls and troubleshooting tips when using this library. We'll continue to add more tips as we discover them.\n\n## YAML Configuration Issues\n\n### Newline Characters in YAML (`\\n`)\n\n**Problem:** When specifying newline characters in YAML, they may be interpreted incorrectly depending on how you format them.\n\n```yaml\n# ❌ WRONG: Single quotes don't process escape sequences\ngeneration_kwargs:\n until: ['\\n'] # Gets parsed as the literal characters '\\' and 'n' i.e \"\\\\n\"\n\n```\n```yaml\n# ✅ RIGHT: Use double quotes for escape sequences\ngeneration_kwargs:\n until: [\"\\n\"] # Gets parsed as an actual newline character\n\n```\n\n**Solutions:**\n- Use double quotes for strings containing escape sequences\n- For multiline content, use YAML's block scalars (`|` or `>`)\n- When generating YAML programmatically, be careful with how template engines handle escape sequences\n\n### Quoting in YAML\n\n**When to use different types of quotes:**\n\n- **No quotes**: Simple values (numbers, booleans, alphanumeric strings without special characters)\n ```yaml\n simple_value: plain text\n number: 42\n\n ```\n\n- **Single quotes (')**:\n - Preserves literal values\n - Use when you need special characters to be treated literally\n - Escape single quotes by doubling them: `'It''s working'`\n ```yaml\n literal_string: 'The newline character \\n is not processed here'\n path: 'C:\\Users\\name' # Backslashes preserved\n\n ```\n\n- **Double quotes (\")**:\n - Processes escape sequences like `\\n`, `\\t`, etc.\n - Use for strings that need special characters interpreted\n - Escape double quotes with backslash: `\"He said \\\"Hello\\\"\"`\n ```yaml\n processed_string: \"First line\\nSecond line\" # Creates actual newline\n unicode: \"Copyright symbol: \\u00A9\" # Unicode character\n\n ```\n" }, { "path": "docs/interface.md", "content": "# User Guide\n\nThis document details the interface exposed by `lm-eval` and provides details on what flags are available to users.\n\n## Command-line Interface\n\nThe `lm-eval` CLI is organized into subcommands:\n\n| Command | Description |\n|---------|-------------|\n| `lm-eval run` | Run evaluations on language models |\n| `lm-eval ls` | List available tasks, groups, subtasks, or tags |\n| `lm-eval validate` | Validate task configurations |\n\nRun the library via the `lm-eval` entrypoint or `python -m lm_eval`.\n\nUse `-h` or `--help` to see available options:\n\n```bash\nlm-eval -h # Show all subcommands\nlm-eval run -h # Show options for run command\nlm-eval ls -h # Show options for list command\n```\n\n> **Legacy Compatibility**: The original single-command interface still works. Running `lm-eval --model hf --tasks hellaswag` automatically inserts the `run` subcommand.\n\n---\n\n## Quick Start\n\n```bash\n# List available tasks\nlm-eval ls tasks\n\n# Basic evaluation\nlm-eval run --model hf --model_args pretrained=gpt2 --tasks hellaswag\n\n# With few-shot examples\nlm-eval run --model hf --model_args pretrained=gpt2 --tasks arc_easy --num_fewshot 5\n\n# Save results and model outputs\nlm-eval run --model hf --model_args pretrained=gpt2 --tasks hellaswag --output_path ./results/ --log_samples\n\n# Use a config file\nlm-eval run --config eval_config.yaml\n```\n\n---\n\n## `lm-eval run`\n\nRun evaluations on language models.\n\n```bash\nlm-eval run --model --tasks [options]\n```\n\n### Quick Examples\n\n```bash\n# Basic evaluation with HuggingFace model\nlm-eval run --model hf --model_args pretrained=gpt2 dtype=float32 --tasks hellaswag\n\n# Multiple tasks with few-shot examples\nlm-eval run --model vllm --model_args pretrained=EleutherAI/gpt-j-6B --tasks arc_easy arc_challenge --num_fewshot 5\n\n# Custom generation parameters\nlm-eval run --model hf --model_args pretrained=gpt2 --tasks lambada --gen_kwargs temperature=0.8 top_p=0.95\n\n# Use a YAML configuration file\nlm-eval run --config my_config.yaml --tasks mmlu\n```\n\n### Model and Tasks\n\n| Argument | Short | Description |\n|----------|-------|-------------|\n| `--model` | `-M` | Model type/provider name (default: `hf`). See [supported models](https://github.com/EleutherAI/lm-evaluation-harness#model-apis-and-inference-servers). |\n| `--model_args` | `-a` | Model constructor arguments as `key=val key2=val2` or `key=val,key2=val2`. For HuggingFace models, see [`HFLM`](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/models/huggingface.py) for available arguments. |\n| `--tasks` | `-t` | Space or comma-separated list of task names or groups. Use `lm-eval ls tasks` to see available tasks. |\n| `--apply_chat_template` | | Apply chat template to prompts. Use without argument for default template, or specify template name. |\n| `--limit` | `-L` | Limit examples per task. Integer for count, float (0.0-1.0) for percentage. **For testing only.** |\n| `--use_cache` | `-c` | Path prefix for SQLite cache of model responses (e.g., `/path/to/cache_`). |\n\n### Evaluation Settings\n\n| Argument | Short | Description |\n|----------|-------|-------------|\n| `--num_fewshot` | `-f` | Number of few-shot examples in context. |\n| `--batch_size` | `-b` | Batch size: integer, `auto`, or `auto:N` to auto-tune N times (default: 1). |\n| `--max_batch_size` | | Maximum batch size when using `--batch_size auto`. |\n| `--device` | | Device to use: `cuda`, `cuda:0`, `cpu`, `mps` (default: `cuda`). |\n| `--gen_kwargs` | | Generation arguments as `key=val key2=val2`. Values parsed with `ast.literal_eval`. Example: `temperature=0.8 'stop=[\"\\n\\n\"]'` |\n\n### Data and Output\n\n| Argument | Short | Description |\n|----------|-------|-------------|\n| `--output_path` | `-o` | Output directory or JSON file for results. Required with `--log_samples`. |\n| `--log_samples` | `-s` | Save all model inputs/outputs for post-hoc analysis. |\n| `--samples` | `-E` | JSON mapping task names to sample indices, e.g., `'{\"task1\": [0,1,2]}'`. Incompatible with `--limit`. |\n\n### Caching and Performance\n\n| Argument | Description |\n|----------|-------------|\n| `--cache_requests` | Cache preprocessed prompts: `true`, `refresh`, or `delete`. Cached files stored in `lm_eval/cache/.cache` or path set by `LM_HARNESS_CACHE_PATH` env var. |\n| `--check_integrity` | Run task test suite validation before evaluation. |\n\n### Prompt Formatting\n\n| Argument | Description |\n|----------|-------------|\n| `--system_instruction` | Custom system instruction prepended to prompts. |\n| `--fewshot_as_multiturn` | Format few-shot examples as multi-turn conversation. Auto-enabled with `--apply_chat_template`. Set to `false` to disable. |\n\n### Task Management\n\n| Argument | Description |\n|----------|-------------|\n| `--include_path` | Additional directory containing external task YAML files. |\n\n### Logging and Tracking\n\n| Argument | Short | Description |\n|----------|-------|-------------|\n| `--verbosity` | `-v` | **(Deprecated)** Use `LMEVAL_LOG_LEVEL` env var instead. |\n| `--write_out` | `-w` | Print prompts for first few documents (for debugging). |\n| `--show_config` | | Display full task configuration after evaluation. |\n| `--wandb_args` | | Weights & Biases arguments as `key=val`. E.g., `project=my-project name=run-1`. |\n| `--wandb_config_args` | | Additional W&B config arguments. |\n| `--hf_hub_log_args` | | HuggingFace Hub logging arguments. See [HF Hub Logging](#huggingface-hub-logging). |\n\n### Advanced Options\n\n| Argument | Short | Description |\n|----------|-------|-------------|\n| `--predict_only` | `-x` | Save predictions only, skip metric computation. Implies `--log_samples`. |\n| `--seed` | | Random seeds as single integer or comma-separated list for `python,numpy,torch,fewshot`. Default: `0,1234,1234,1234`. Use `None` to skip. Example: `--seed 42` or `--seed 0,None,8,52`. |\n| `--trust_remote_code` | | Allow executing remote code from HuggingFace Hub. |\n| `--confirm_run_unsafe_code` | | Confirm understanding of risks for tasks executing arbitrary Python. |\n| `--metadata` | | JSON string passed to TaskConfig. Required for some tasks like RULER. Example: `--metadata '{\"max_seq_length\": 4096}'`. |\n\n### Configuration File\n\n| Argument | Short | Description |\n|----------|-------|-------------|\n| `--config` | `-C` | Path to YAML configuration file. CLI arguments override config file values. See [Configuration Files](config_files.md). |\n\n### HuggingFace Hub Logging\n\nThe `--hf_hub_log_args` argument accepts these keys:\n\n| Key | Description |\n|-----|-------------|\n| `hub_results_org` | Organization name on HF Hub. Defaults to token owner. |\n| `details_repo_name` | Repository name for detailed results. |\n| `results_repo_name` | Repository name for aggregated results. |\n| `push_results_to_hub` | `True`/`False` - push results to Hub. |\n| `push_samples_to_hub` | `True`/`False` - push samples to Hub. Requires `--log_samples`. |\n| `public_repo` | `True`/`False` - make repository public. |\n| `leaderboard_url` | URL to associated leaderboard. |\n| `point_of_contact` | Contact email for results dataset. |\n| `gated` | `True`/`False` - gate the details dataset. |\n\n---\n\n## `lm-eval ls`\n\nList available tasks, groups, subtasks, or tags.\n\n```bash\nlm-eval ls [tasks|groups|subtasks|tags] [--include_path DIR]\n```\n\n### Arguments\n\n| Argument | Description |\n|----------|-------------|\n| `tasks` | List all available tasks (groups, subtasks, and tags). |\n| `groups` | List only task groups (e.g., `mmlu`, `glue`, `superglue`). |\n| `subtasks` | List only individual subtasks (e.g., `mmlu_anatomy`, `hellaswag`). |\n| `tags` | List task tags (e.g., `reasoning`, `knowledge`). |\n| `--include_path` | Additional directory for external task definitions. |\n\n### Task Organization\n\n- **Groups**: Collections of related tasks with aggregated metrics across subtasks (e.g., `mmlu` contains 57 subtasks)\n- **Subtasks**: Individual evaluation tasks (e.g., `mmlu_anatomy`, `hellaswag`)\n- **Tags**: Categories for filtering tasks without aggregated metrics (e.g., `reasoning`, `language`)\n\n### Examples\n\n```bash\n# List all tasks\nlm-eval ls tasks\n\n# List only task groups\nlm-eval ls groups\n\n# Include external tasks\nlm-eval ls tasks --include_path /path/to/external/tasks\n```\n\n---\n\n## `lm-eval validate`\n\nValidate task configurations before running evaluations.\n\n```bash\nlm-eval validate --tasks [--include_path DIR]\n```\n\n### Arguments\n\n| Argument | Short | Description |\n|----------|-------|-------------|\n| `--tasks` | `-t` | **(Required)** Comma-separated list of task names to validate. |\n| `--include_path` | | Additional directory for external task definitions. |\n\n### Validation Checks\n\nThe validate command performs:\n\n- **Task existence**: Verifies all specified tasks are available\n- **Configuration syntax**: Checks YAML/JSON configuration files\n- **Dataset access**: Validates dataset paths and configurations\n- **Required fields**: Ensures all mandatory task parameters are present\n- **Metric definitions**: Verifies metric functions and aggregation methods\n- **Filter pipelines**: Validates filter chains and their parameters\n- **Template rendering**: Tests prompt templates with sample data\n\n### Examples\n\n```bash\n# Validate a single task\nlm-eval validate --tasks hellaswag\n\n# Validate multiple tasks\nlm-eval validate --tasks arc_easy,arc_challenge,hellaswag\n\n# Validate a task group\nlm-eval validate --tasks mmlu\n\n# Validate external tasks\nlm-eval validate --tasks my_custom_task --include_path ./custom_tasks\n```\n\n---\n\n## Python API\n\nFor programmatic usage, see the [Python API Guide](python-api.md).\n\n---\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `LMEVAL_LOG_LEVEL` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`). |\n| `LM_HARNESS_CACHE_PATH` | Path for cached requests (default: `lm_eval/cache/.cache`). |\n| `HF_TOKEN` | HuggingFace Hub token for private datasets/models. |\n| `TOKENIZERS_PARALLELISM` | Set to `false` to avoid tokenizer warnings (auto-set by CLI). |\n" }, { "path": "docs/model_guide.md", "content": "# New Model Guide\n\nThis guide may be of special interest to users who are using the library outside of the repository, via installing the library via pypi and calling `lm_eval.evaluator.evaluate()` to evaluate an existing model.\n\nIn order to properly evaluate a given LM, we require implementation of a wrapper class subclassing the `lm_eval.api.model.LM` class, that defines how the Evaluation Harness should interface with your model. This guide walks through how to write this `LM` subclass via adding it to the library!\n\n## Setup\n\nTo get started contributing, go ahead and fork the main repo, clone it, create a branch with the name of your model, and install the project requirements in your environment:\n\n```sh\n# After forking...\ngit clone https://github.com//lm-evaluation-harness.git\ncd lm-evaluation-harness\ngit checkout -b \npip install -e \".[dev]\"\n```\n\nNow, we'll create a new file where we'll be adding our model:\n\n```sh\ntouch lm_eval/models/.py\n```\n\n**Tip: this filename should not shadow package names! For example, naming your file `anthropic.py` is disallowed since the API's name on pypi is `anthropic`, but naming it `anthropic_llms.py` works with no problems.**\n\n## Interface\n\nAll models must subclass the `lm_eval.api.model.LM` class.\n\nThe LM class enforces a common interface via which we can extract responses from a model:\n\n```python\nclass MyCustomLM(LM):\n #...\n def loglikelihood(self, requests: list[Instance]) -> list[tuple[float, bool]]:\n #...\n\n\n def loglikelihood_rolling(self, requests: list[Instance]) -> list[tuple[float, bool]]:\n #...\n\n\n def generate_until(self, requests: list[Instance]) -> list[str]:\n #...\n #...\n```\n\nWhere `Instance` is a dataclass defined in [`lm_eval.api.instance`](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/api/instance.py) with property `args` of request-dependent type signature described below.\n\nWe support three types of requests, consisting of different interactions / measurements with an autoregressive LM.\n\nAll three request types take as input `requests` of type `list[Instance]` that have a matching `Instance.request_type` to the method name.\n\n- `generate_until`\n - Each request contains `Instance.args : Tuple[str, dict]` containing 1. an input string to the LM and 2. a dictionary of keyword arguments used to control generation parameters.\n - Using this input and these generation parameters, text will be sampled from the language model (typically until a maximum output length or specific stopping string sequences--for example, `{\"until\": [\"\\n\\n\", \".\"], \"max_gen_toks\": 128}`).\n - The generated output text from the model will then be returned.\n\n- `loglikelihood`\n - Each request contains `Instance.args : Tuple[str, str]` containing 1. an input string to the LM and 2. a target string on which the loglikelihood of the LM producing this target, conditioned on the input, will be returned.\n - Each request will have, as result, `(ll, is_greedy): Tuple[float, int]` returned, where `ll` is a floating point number representing the log probability of generating the target string conditioned on the input, and `is_greedy` being either the value `0` or `1`, with it being `1` if and only if the target string *would be generated by greedy sampling from the LM* (that is, if the target string is the *most likely* N-token string to be output by the LM given the input. )\n\n- `loglikelihood_rolling`\n - Each request contains `Instance.args : Tuple[str]`, which is an input string to the model whose *entire* loglikelihood, conditioned on purely the EOT token, will be calculated.\n - This is used to evaluate *perplexity* on a data distribution.\n - It should return `(ll,) : Tuple[float]` , a.k.a. solely the *loglikelihood* of producing each piece of text given no starting input.\n\nTo allow a model to be evaluated on all types of tasks, you will need to implement these three types of measurements (note that `loglikelihood_rolling` is a special case of `loglikelihood`). For a reference implementation, check out `lm_eval/models/huggingface.py` ! Additionally, check out `lm_eval.api.model.TemplateLM` for a class that abstracts away some commonly used functions across LM subclasses, or see if your model would lend itself well to subclassing the `lm_eval.models.huggingface.HFLM` class and overriding just the initialization or a couple methods!\n\n**Tip: be careful of indexing in loglikelihood!**\n\nLMs take in tokens in position `[0 1 2 ... N]` and output a probability distribution for token position `N+1`. We provide a simplified graphic here, excerpted from `huggingface.py`:\n\n```text\n# how this all works (illustrated on a causal decoder-only setup):\n# CTX CONT\n# inp 0 1 2 3|4 5 6 7 8 9 <- last token is deleted by inp[:, :-1]\n# model \\ \\\n# logits 1 2 3|4 5 6 7 8 9 <- the ctx half gets tossed out by the\n# cont_toks 4 5 6 7 8 9 [:, -len(continuation_enc):, :self.vocab_size] slice\n```\n\nThe final token of the target is not passed into the LM, because we want the LM's predictions *up to but not past* that final target token. For more information, check out https://github.com/EleutherAI/lm-evaluation-harness/issues/942 .\n\n## Registration\n\nCongrats on implementing your model! Now it's time to test it out.\n\nTo make your model usable via the command line interface to `lm-eval` using `python -m lm_eval`, you'll need to tell `lm-eval` what your model's name is.\n\nThis is done via a *decorator*, `lm_eval.api.registry.register_model`. Using `register_model()`, one can both tell the package what the model's name(s) to be used are when invoking it with `python -m lm_eval --model ` and alert `lm-eval` to the model's existence.\n\n```python\nfrom lm_eval.api.registry import register_model\n\n@register_model(\"\", \"\")\nclass MyCustomLM(LM):\n```\n\nUsing this decorator results in the class being added to an accounting of the usable LM types maintained internally to the library at `lm_eval.api.registry.MODEL_REGISTRY`. See `lm_eval.api.registry` for more detail on what sorts of registries and decorators exist in the library!\n\n**Tip: be sure to import your model in `lm_eval/models/__init__.py!`**\n\n## Testing\n\nWe also recommend that new model contributions be accompanied by short tests of their 3 core functionalities, at minimum. To see an example of such tests, look at https://github.com/EleutherAI/lm-evaluation-harness/blob/35bdecd379c0cefad6897e67db892f4a6026a128/tests/test_ggml.py .\n\n## Chat Templating\n\nMany models are fine-tuned with a [Chat Template](https://huggingface.co/docs/transformers/main/en/chat_templating) in order to enable back-and-forth interaction between a \"User\"'s queries and the model (often called \"Assistant\")'s responses. It can be desirable to evaluate fine-tuned models on evaluation tasks while wrapped in the conversational format they expect.\n\nIn order to make your model optionally compatible with a chat format, three additional methods must be implemented:\n\n```python\nclass MyCustomLM(LM):\n #...\n @property\n def tokenizer_name(self) -> str:\n \"\"\"\n Return the name of the model's tokenizer and/or the accompanying chat template.\n The returned string is used to cache requests.\n\n Returns:\n str: The name of the model's tokenizer and/or chat template.\n \"\"\"\n\n def chat_template(self, chat_template: Union[bool, str] = False) -> str:\n \"\"\"\n Get the appropriate chat template for the model based on the `chat_template` argument.\n\n This method returns the chat template string to build the prompt from a chat history.\n The chat template is saved in the evaluation results for reproducibility.\n Boolean arguments should be used with models that have only one chat template,\n while string arguments are used with models that have multiple chat templates.\n For the reference implementation, see HFLM class in `lm_eval.models.huggingface`.\n\n Args:\n chat_template (Union[bool, str]): Specifies whether to apply a chat template:\n - If False: Do not apply any chat template.\n - If True: Apply the default chat template.\n - If str: Apply the specified chat template by name.\n\n Returns:\n str: The selected chat template in Jinja format.\n \"\"\"\n\n def apply_chat_template(self, chat_history: List[Dict[str, str]]) -> str:\n \"\"\"\n Process a chat history to create a string that can be tokenized and input into the model.\n\n Args:\n chat_history (List[Dict[str, str]]): A list of dictionaries representing the chat history,\n where each dictionary has \"role\" and \"content\" keys.\n\n Returns:\n str: A string representing the chat history that can be tokenized and fed into the model.\n \"\"\"\n```\n\n- `apply_chat_template`\n - This method performs the bulk of the work required for chat-formatting.\n - As input, a `chat_history: List[Dict[str, str]]` is passed in. This is a transcript of a conversation of a form similar to\n\n ```text\n [\n {\"system\": },\n {\"user\": }\n {\"assistant\": },\n # ... more few-shot examples, potentially\n {\"user\": },\n ]\n ```\n\n which can then be converted into a string input.\n - The output is a string representing this conversation that can be fed into the model.\n - For example, this consists of simply calling `tokenizer.apply_chat_template` for HFLM--see the implementation there for reference.\n- `tokenizer_name`\n - LM Eval Harness supports [caching requests](https://github.com/EleutherAI/lm-evaluation-harness/blob/4902aaaf1f374682f95ac25fe2e13b23faddc91a/lm_eval/__main__.py#L140) that are sent to a model, for faster setup when repeating an already-performed evaluation.\n - However, we don't want to use the cache of chat transcripts rendered using one chat template or system prompt to send to a model with a different template! So, we use this `lm.tokenizer_name` string to distinguish caches for a given model (and chat template) from one another.\n- `chat_template`\n - Chat templates are typically provided as a Jinja template string or a string formatted with str.format to include user and assistant messages in a single prompt. This template string is saved in the evaluation results to ensure reproducibility.\n\nIf not implemented for a given model type, the flags `--apply_chat_template` , `--fewshot_as_multiturn`, and `--system_instruction` cannot be used.\n\n## Other\n\n**Pro tip**: In order to make the Evaluation Harness overestimate total runtimes rather than underestimate it, HuggingFace models come in-built with the ability to provide responses on data points in *descending order by total input length* via `lm_eval.utils.Reorderer`. Take a look at `lm_eval.models.hf_causal.HFLM` to see how this is done, and see if you can implement it in your own model!\n\n## Conclusion\n\nAfter reading this guide, you should be able to add new model APIs or implementations to the Eval Harness library!\n" }, { "path": "docs/new_task_guide.md", "content": "# New Task Guide\n\n`lm-evaluation-harness` is a framework that strives to support a wide range of zero- and few-shot evaluation tasks on autoregressive language models (LMs).\n\nThis documentation page provides a walkthrough to get started creating your own task, in `lm-eval` versions v0.4.0 and later.\n\nA more interactive tutorial is available as a Jupyter notebook [here](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/examples/lm-eval-overview.ipynb).\n\n## Setup\n\nIf you haven't already, go ahead and fork the main repo, clone it, create a branch with the name of your task, and install the project requirements in your environment:\n\n```sh\n# After forking...\ngit clone https://github.com//lm-evaluation-harness.git\ncd lm-evaluation-harness\ngit checkout -b \npip install -e \".[dev]\"\n```\n\nIn this document, we'll walk through the basics of implementing a static benchmark evaluation in two formats: a *generative* task which requires sampling text from a model, such as [`gsm8k`](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/tasks/gsm8k/gsm8k.yaml), and a *discriminative*, or *multiple choice*, task where the model picks the most likely of several fixed answer choices, such as [`sciq`](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/tasks/sciq/sciq.yaml).\n\n## Creating a YAML file\n\nTo implement a new standard task, we'll need to write a YAML file which configures our task logic. We start by making a new empty YAML file. This file can have any name, but we recommend placing it in a subfolder of `lm_eval/tasks` titled by the dataset or task's shorthand name: for example,\n\n```sh\ntouch lm_eval/tasks//.yaml\n```\n\nOr, copy the template subfolder we provide from `templates/new_yaml_task`:\n\n```sh\ncp -r templates/new_yaml_task lm_eval/tasks/\n```\n\nand rename the folders and YAML file(s) as desired.\n\n### Selecting and configuring a dataset\n\nAll data downloading and management is handled through the HuggingFace (**HF**) [`datasets`](https://github.com/huggingface/datasets) API. So, the first thing you should do is check to see if your task's dataset is already provided in their catalog [here](https://huggingface.co/datasets). If it's not in there, please consider adding it to their Hub to make it accessible to a wider user base by following their [new dataset guide](https://github.com/huggingface/datasets/blob/main/ADD_NEW_DATASET.md)\n.\n> [!TIP]\n> To test your task, we recommend using verbose logging using `export LMEVAL_LOG_LEVEL=\"DEBUG\"` in your shell before running the evaluation script. This will help you debug any issues that may arise.\nOnce you have a HuggingFace dataset prepared for your task, we want to assign our new YAML to use this dataset:\n\n```yaml\ndataset_path: ... # the name of the dataset on the HF Hub.\ndataset_name: ... # the dataset configuration to use. Leave `null` if your dataset does not require a config to be passed. See https://huggingface.co/docs/datasets/load_hub#configurations for more info.\ndataset_kwargs: null # any extra keyword arguments that should be passed to the dataset constructor, e.g. `data_dir`.\n```\n\nNext, we'd like to tell our task what the dataset's train, validation, and test splits are named, if they exist:\n\n```yaml\ntraining_split: \nvalidation_split: \ntest_split: \n```\n\nTests will run on the `test_split` if it is available, and otherwise evaluate on the `validation_split`.\n\nWe can also specify from which split the task should retrieve few-shot examples via:\n\n```yaml\nfewshot_split: \n```\n\nor by hardcoding them, either using the following in the yaml file:\n\n```yaml\nfewshot_config:\n sampler: first_n\n samples: [\n {},\n {},\n ]\n```\n\nThe full `fewshot_config` supports the following fields:\n\n```yaml\nfewshot_config:\n sampler: default # Sampling strategy: \"default\" (random) or \"first_n\"\n split: train # Dataset split to draw fewshot examples from (overrides fewshot_split)\n samples: [...] # Hardcoded list of fewshot examples, or a callable returning them\n doc_to_text: \"...\" # Override doc_to_text for fewshot examples only\n doc_to_target: \"...\" # Override doc_to_target for fewshot examples only\n doc_to_choice: \"...\" # Override doc_to_choice for fewshot examples only\n gen_prefix: \"Answer:\" # Prefix for assistant response in fewshot examples\n fewshot_delimiter: \"\\n\\n\" # Delimiter between fewshot examples\n target_delimiter: \" \" # Delimiter between question and answer\n```\n\nAll fields are optional. If not specified, they inherit from the parent `TaskConfig`. This allows you to format fewshot examples differently from the evaluation examples — useful when your fewshot source has different field names or requires different formatting.\n\nYou can also hardcode fewshot examples by adding the function `list_fewshot_samples` in the associated utils.py file:\n\n```python\ndef list_fewshot_samples() -> list[dict]:\n return [{}, {}]\n```\n\nSee `lm_eval/tasks/minerva_math/minerva_math_algebra.yaml` for an example of the latter, and `lm_eval/tasks/gsm8k/gsm8k-cot.yaml` for an example of the former.\n\nIn this case, each sample must contain the same fields as the samples in the above sets--for example, if `doc_to_text` expects an `input` field when rendering input prompts, these provided samples must include an `input` key.\n\nIf neither above options are not set, we will default to train/validation/test sets, in that order.\n\nFinally, our dataset may not be already in the exact format we want. Maybe we have to strip whitespace and special characters via a regex from our dataset's \"question\" field! Or maybe we just want to rename its columns to match a convention we'll be using for our prompts.\n\nLet's create a python file in the directory where we're writing our YAML file:\n\n```bash\ntouch lm_eval/tasks//utils.py\n```\n\nNow, in `utils.py` we'll write a function to process each split of our dataset (the following example is drawn from [the `hellaswag` task](../lm_eval/tasks/hellaswag/utils.py)):\n\n```python\ndef process_docs(dataset: datasets.Dataset) -> datasets.Dataset:\n def _process_doc(doc):\n ctx = doc[\"ctx_a\"] + \" \" + doc[\"ctx_b\"].capitalize()\n out_doc = {\n \"query\": preprocess(doc[\"activity_label\"] + \": \" + ctx),\n \"choices\": [preprocess(ending) for ending in doc[\"endings\"]],\n \"gold\": int(doc[\"label\"]),\n }\n return out_doc\n\n return dataset.map(_process_doc)\n```\n\nNow, in our YAML config file we'll use the `!function` constructor, and tell the config where our imported Python function will come from. At runtime, before doing anything else we will preprocess our dataset according to this function!\n\n```yaml\nprocess_docs: !function utils.process_docs\n```\n\n### Using Local Datasets\n\nTo load a local dataset for evaluation, you can specify data files in the `dataset_kwargs` field, such as the following for JSON files:\n\n```yaml\ndataset_path: json\ndataset_name: null\ndataset_kwargs:\n data_files: /path/to/my/json\n```\n\nOr with files already split into separate directories:\n\n```yaml\ndataset_path: arrow\ndataset_kwargs:\n data_files:\n train: /path/to/arrow/train/data-00000-of-00001.arrow\n validation: /path/to/arrow/validation/data-00000-of-00001.arrow\n```\n\nAlternatively, if you have previously downloaded a dataset from huggingface hub (using `save_to_disk()`) and wish to use the local files, you will need to use `data_dir` under `dataset_kwargs` to point to where the directory is.\n\n```yaml\ndataset_path: hellaswag\ndataset_kwargs:\n data_dir: hellaswag_local/\n```\n\nYou can also set `dataset_path` as a directory path in your local system. This will assume that there is a loading script with the same name as the directory. [See datasets docs](https://huggingface.co/docs/datasets/loading#local-loading-script).\n\n## Writing a Prompt Template\n\nThe next thing we need to do is decide what format to use when presenting the data to the LM. This is our **prompt**, where we'll define both an input and output format.\n\nTo write a prompt, users will use `doc_to_text`, `doc_to_target`, and `doc_to_choice` (Optional when certain conditions are met).\n\n`doc_to_text` defines the input string a model will be given while `doc_to_target` and `doc_to_choice` will be used to generate the target text. `doc_to_target` can be either a text string that refers to the target string or an integer that refers to the index of the correct label. When it is set as an index, `doc_to_choice` must also be set with the appropriate list of possible choice strings.\n\n### Basic prompts\n\nIf a dataset is straightforward enough, users can enter the feature name directly. This assumes that no preprocessing is required. For example in [Swag](https://github.com/EleutherAI/lm-evaluation-harness/blob/1710b42d52d0f327cb0eb3cb1bfbbeca992836ca/lm_eval/tasks/swag/swag.yaml#L10-L11), `doc_to_text` and `doc_to_target` given the name of one of the feature each.\n\n```yaml\ndoc_to_text: startphrase\ndoc_to_target: label\n```\n\nHard-coding is also possible as is the case in [SciQ](https://github.com/EleutherAI/lm-evaluation-harness/blob/1710b42d52d0f327cb0eb3cb1bfbbeca992836ca/lm_eval/tasks/sciq/sciq.yaml#L11).\n\n```yaml\ndoc_to_target: 3\n```\n\n`doc_to_choice` can be directly given a list of text as option (See [Toxigen](https://github.com/EleutherAI/lm-evaluation-harness/blob/1710b42d52d0f327cb0eb3cb1bfbbeca992836ca/lm_eval/tasks/toxigen/toxigen.yaml#L11))\n\n```yaml\ndoc_to_choice: ['No', 'Yes']\n```\n\nif a dataset feature is already a list, you can set the name of the feature as `doc_to_choice` (See [Hellaswag](https://github.com/EleutherAI/lm-evaluation-harness/blob/e0eda4d3ffa10e5f65e0976161cd134bec61983a/lm_eval/tasks/hellaswag/hellaswag.yaml#L13))\n\n```yaml\ndoc_to_choice: choices\n```\n\n### Writing a prompt with Jinja 2\n\nWe support the [Jinja 2](https://jinja.palletsprojects.com/en/3.1.x/) templating language for writing prompts. In practice, this means you can take your dataset's columns and do many basic string manipulations to place each document into prompted format.\n\nTake for example the dataset `super_glue/boolq`. As input, we'd like to use the features `passage` and `question` and string them together so that for a sample line `doc`, the model sees something in the format of:\n\n```text\ndoc[\"passage\"]\nQuestion: doc[\"question\"]?\nAnswer:\n```\n\nWe do this by [writing](https://github.com/EleutherAI/lm-evaluation-harness/blob/1710b42d52d0f327cb0eb3cb1bfbbeca992836ca/lm_eval/tasks/super_glue/boolq/default.yaml#L9C1-L9C61)\n\n```yaml\ndoc_to_text: \"{{passage}}\\nQuestion: {{question}}?\\nAnswer:\"\n```\n\nSuch that `{{passage}}` will be replaced by `doc[\"passage\"]` and `{{question}}` with `doc[\"question\"]` when rendering the prompt template.\n\nOur intended output is for the model to predict a single whitespace, and then the answer to the question. We do this via:\n\n```yaml\ndoc_to_target: \"{{answer}}\"\n```\n\n#### Multiple choice format\n\nFor tasks which are multiple choice (a fixed, finite set of label words per each document) and evaluated via comparing loglikelihoods of all label words (the `multiple_choice` task output type) we enforce a particular convention on prompt format.\n\n> [!WARNING]\n> We add `target_delimiter` between input and target which defaults to \" \", such that the full input-output string is `doc_to_text(doc) + target_delimiter + doc_to_target(doc)`. `doc_to_text` and `doc_to_target` should not contain trailing right or left whitespace, respectively. For multiple choice the target will be each choice index concatenated with the delimiter.\n\nAn annotated example in the case of SciQ is as follows:\n\n```yaml\ndoc_to_text: \"{{support.lstrip()}}\\nQuestion: {{question}}\\nAnswer:\" # This is the input portion of the prompt for this doc. It will have \" {{choice}}\" appended to it as target for each choice in answer_choices.\ndoc_to_target: 3 # this contains the index into the answer choice list of the correct answer.\ndoc_to_choice: \"{{[distractor1, distractor2, distractor3, correct_answer]}}\"\n```\n\nTask implementers are thus able to decide what the answer choices should be for a document, and what prompt format to use.\n\nThe label index can also be sourced from a feature directly. For example in `superglue/boolq`, the label index if defined in the feature `label`. We can set `doc_to_target` as simply `label`. The options or verbalizers can be written in the form of a list `[\"no\", \"yes\"]` that will correspond to the label index.\n\n```yaml\ndoc_to_text: \"{{passage}}\\nQuestion: {{question}}?\\nAnswer:\"\ndoc_to_target: label\ndoc_to_choice: [\"no\", \"yes\"]\n```\n\n### Using Python Functions for Prompts\n\nThere may be cases where the prompt we want to implement is easier expressed in Python instead of Jinja 2. For this, we can use Python helper functions that are defined in the YAML config. It should be noted that the function script must be in the same directory as the yaml.\n\nA good example is WikiText that requires a lot of regex rules to clean the samples.\n\n```python\ndef wikitext_detokenizer(doc):\n string = doc[\"page\"]\n # contractions\n string = string.replace(\"s '\", \"s'\")\n string = re.sub(r\"/' [0-9]/\", r\"/'[0-9]/\", string)\n ...\n string = string.replace(\" 's\", \"'s\")\n\n return string\n```\n\nWe can load this function in `doc_to_target` by using a `!function` operator after `doc_to_target` and followed by `.`. In the file [wikitext.yaml](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/tasks/wikitext/wikitext.yaml) we write:\n\n```yaml\ndoc_to_target: !function preprocess_wikitext.wikitext_detokenizer\n```\n\n### Importing a Prompt from Promptsource\n\n[Promptsource](https://github.com/bigscience-workshop/promptsource/tree/main/promptsource) is a great repository for crowdsourced prompts for many datasets. We can load these prompts easily by using the `use_prompt` argument and filling it with the format `\"promptsource:\"`. To use this, `doc_to_text` and `doc_to_target` should be left undefined. This will fetch the template of the dataset defined in the YAML file.\n\nFor example, For Super Glue BoolQ, if we want to use the prompt template `GPT-3 Style` we can add this to the YAML file.\n\n```yaml\nuse_prompt: \"promptsource:GPT-3 Style\"\n```\n\nIf you would like to run evaluation on all prompt templates, you can simply call it this way.\n\n```yaml\nuse_prompt: \"promptsource:*\"\n```\n\n### Setting metrics\n\nYou're almost done! Now we need to choose how to score our task.\n\n- *If this is a multiple choice task:* do you just want to check your model's accuracy in choosing the correct answer choice?\n- *If this is a generation task:* do you just want to check how often your model outputs *exactly the ground-truth output string provided*?\n\nIf the answer to the above is no: you'll need to record what scoring metrics to use! Metrics can be listed in the following format:\n\n```yaml\nmetric_list:\n - metric: \n aggregation: \n higher_is_better: \n - metric: !function script.function\n aggregation: ...\n higher_is_better: ...\n```\n\n`aggregation` and `higher_is_better` can optionally be left out to default to the manually-set defaults if using a natively supported metric, otherwise it must be defined explicitly (for example, when using a custom metric implemented as a function).\n\nFor a full list of natively supported metrics and aggregation functions see [`docs/task_guide.md`](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/docs/task_guide.md). All metrics supported in [HuggingFace Evaluate](https://github.com/huggingface/evaluate/tree/main/metrics) can also be used, and will be loaded if a given metric name is not one natively supported in `lm-eval` or `hf_evaluate` is set to `true`.\n\n### Optional, More Advanced Setup\n\nSome tasks may require more advanced processing logic than is described in this guide.\n\nAs a heuristic check:\n\n- Does your task require generating multiple free-form outputs per input document?\n- Does your task require complex, multi-step post-processing of generated model outputs?\n- Does your task require subsetting documents on the fly based on their content?\n- Do you expect to compute metrics after applying multiple such processing steps on your model outputs?\n- Does your task rely on metrics that need a custom implementation?\n\nFor more detail on the task system and advanced features, see [`docs/task_guide.md`](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/docs/task_guide.md). If none of the above sounds like they apply to your task, it's time to continue onto checking your task performance!\n\n### Task name + tags (registering a task)\n\nTo test a task conveniently, it helps to *register* the task--that is, to give it a name and make the `lm-eval` library aware it exists!\n\nIf you're writing your YAML file inside the `lm_eval/tasks` folder, you just need to give your task a name! You can do this inside your YAML file:\n\n```yaml\ntask: \n```\n\nIncluding a task name is mandatory.\n\nIt is often also convenient to label your task with several `tag` values, though this field is optional:\n\n```yaml\ntag:\n - tag1\n - tag2\n```\n\nThis will add your task to the `tag1` and `tag2` tags, enabling people to know how to categorize your task, and if desired run all tasks in one of these groups at once, your task along with them.\n\nIf your task is not in the `lm_eval/tasks` folder, you'll need to tell the Eval Harness where to look for YAML files.\n\nYou can do this via the `--include_path` argument in `__main__.py`. This command will be used to initialize the `TaskManager` object which you can also use for your custom scripts.\n\n```python\ntask_manager = TaskManager(args.verbosity, include_path=args.include_path)\n```\n\nPassing `--tasks /path/to/yaml/file` is also accepted.\n\n### Advanced Group Configs\n\nWhile `tag` values are helpful when you want to be able to quickly and conveniently run a set of related tasks via `--tasks my_tag_name`, often, we wish to implement more complex logic. For example, the MMLU benchmark contains 57 *subtasks* that must all be *averaged* together in order to report a final 'MMLU score'.\n\nGroupings of tasks might also use particular variants of a task--for example, we might want to default to evaluating a task as 5-shot when called as part of a given grouping, but not have a preference for number of shots when evaluating it as a standalone.\n\nWe implement this via **groups**, which are distinct from tags. Groups can be implemented via *group config* YAML files, which are laid out similarly but slightly differently to tasks' YAML configs.\n\nThe most basic form of group can be defined via a YAML config similar to the following:\n\n```yaml\ngroup: nli_tasks\ntask:\n - cb\n - anli_r1\n - rte\nmetadata:\n version: 1.0\n```\n\nThis will behave almost identically to a `tag` that includes these 3 tasks, but with one key distinction: we'll print the `nli_tasks` group as a row (with no associated metrics) in our table of outputs, and visually show that these 3 tasks appear under its subheader.\n\nNow, let's assume we actually want to report an aggregate score for `nli_tasks`. We would instead use a YAML config like the following:\n\n```yaml\ngroup: nli_tasks\ntask:\n - cb\n - anli_r1\n - rte\naggregate_metric_list:\n - metric: acc\n aggregation: mean\n weight_by_size: true # defaults to `true`. Set this to `false` to do a \"macro\" average (taking each subtask's average accuracy, and summing those accuracies and dividing by 3)--by default we do a \"micro\" average (retain all subtasks' per-document accuracies, and take the mean over all documents' accuracies to get our aggregate mean).\nmetadata:\n version: 1.0\n```\n\nSimilar to our `metric_list` for listing out the metrics we want to calculate for a given task, we use an `aggregate_metric_list` field to specify which metric name to aggregate across subtasks, what aggregation function to use, and whether we should micro- or macro- average these metrics. See [./task_guide.md](./task_guide.md) for a full list of related sub-keys.\n\n**[!Tip]: currently, we predominantly only support the aggregation of group metrics that use `mean` (either micro- or macro- averaged) over their subtasks. If you require even more complex aggregation rules, you may want to perform aggregation offline.**\n\nGroup configs can be fairly complex! We can do various operations, such as defining new subtask(s) inline in our group YAML, overriding an existing task's specific config value, or nesting existing groups within our\n\nFor example, let's build a config for evaluating MMLU and a few natural language inference tasks. For MMLU, we can write the name for the benchmark as a subtask written under `task`. You can configure the parameters such as `num_fewshot`. If the task being configured is a group such as `mmlu` or `super_glue`, the parameter set will be applied to all of the subtasks.\n\n```yaml\ngroup: nli_and_mmlu\ntask:\n - group: nli_tasks\n task:\n - cb\n - anli_r1\n - rte\n aggregate_metric_list:\n - metric: acc\n aggregation: mean\n higher_is_better: true\n - task: mmlu\n num_fewshot: 2\n```\n\n### Configuring python classes\n\nThere can be occasions when yaml-based tasks cannot accommodate how a task is handled. LM-Eval supports the manually implementing tasks as was previously done before `0.4.x`. To register the task, you can simply make a yaml with the name of the task in `task` and the class object in `class` using the `!function` prefix.\n\n```yaml\ntask: squadv2\nclass: !function task.SQuAD2\n```\n\nThis also applies to building group configurations with subtasks that are python classes.\n\n```yaml\ngroup: scrolls\ntask:\n - task: scrolls_qasper\n class: !function task.Qasper\n - task: scrolls_quality\n class: !function task.QuALITY\n - task: scrolls_narrativeqa\n class: !function task.NarrativeQA\n ...\n```\n\nYou can also pass a custom argument to your class by accepting `config` in the custom class constructor.\nHere's how to do it:\n\n```yaml\ntask: 20_newsgroups\nclass: !function task.Unitxt\nrecipe: card=cards.20_newsgroups,template=templates.classification.multi_class.title\n```\n\nIn this example, `recipe` is the custom argument for the `Unitxt` class.\n\n## Beautifying Table Display\n\nTo avoid conflict, each task needs to be registered with a unique name. Because of this, slight variations of task are still counted as unique tasks and need to be named uniquely. This could be done by appending an additional naming that may refer to the variation such as in MMLU where the template used to evaluated for flan are differentiated from the default by the prefix `mmlu_flan_*`. Printing the full task names can easily clutter the results table at the end of the evaluation especially when you have a long list of tasks or are using a benchmark that comprises of many tasks. To make it more legible, you can use `task_alias` and `group_alias` to provide an alternative task name and group name that will be printed. For example in `mmlu_abstract_algebra.yaml` we set `task_alias` to `abstract_algebra`. In group configs, a `group_alias` for a group can also be set.\n\n```yaml\n\"dataset_name\": \"abstract_algebra\"\n\"description\": \"The following are multiple choice questions (with answers) about abstract\\\n \\ algebra.\\n\\n\"\n\"include\": \"_default_template_yaml\"\n\"task\": \"mmlu_abstract_algebra\"\n\"task_alias\": \"abstract_algebra\"\n```\n\n## Checking validity\n\nAfter registering your task, you can now check on your data downloading and verify that the few-shot samples look as intended. Run the following command with your desired args:\n\n```bash\npython -m scripts.write_out \\\n --output_base_path \\\n --tasks \\\n --sets \\\n --num_fewshot K \\\n --num_examples N \\\n```\n\nOpen the file specified at the `--output_base_path ` and ensure it passes\na simple eye test.\n\n## Versioning\n\nOne key feature in LM Evaluation Harness is the ability to version tasks and groups--that is, mark them with a specific version number that can be bumped whenever a breaking change is made.\n\nThis version info can be provided by adding the following to your new task or group config file:\n\n```yaml\nmetadata:\n version: 0\n```\n\nNow, whenever a change needs to be made to your task in the future, please increase the version number by 1 so that users can differentiate the different task iterations and versions.\n\nIf you are incrementing a task's version, please also consider adding a changelog to the task's README.md noting the date, PR number, what version you have updated to, and a one-liner describing the change.\n\nfor example,\n\n- \\[Dec 25, 2023\\] (PR #999) Version 0.0 -> 1.0: Fixed a bug with answer extraction that led to underestimated performance.\n\n## Checking performance + equivalence\n\nIt's now time to check models' performance on your task! In the evaluation harness, we intend to support a wide range of evaluation tasks and setups, but prioritize the inclusion of already-proven benchmarks following the precise evaluation setups in the literature where possible.\n\nTo enable this, we provide a checklist that should be completed when contributing a new task, to enable accurate book-keeping and to ensure that tasks added to the library are well-tested and, where applicable, precedented.\n\n### Task Validity Checklist\n\nThe checklist is the following:\n\nFor adding novel benchmarks/datasets to the library:\n\n- [ ] Is the task an existing benchmark in the literature?\n - [ ] Have you referenced the original paper that introduced the task?\n - [ ] If yes, does the original paper provide a reference implementation? If so, have you checked against the reference implementation and documented how to run such a test?\n\nIf other tasks on this dataset are already supported:\n\n- [ ] Is the \"Main\" variant of this task clearly denoted?\n- [ ] Have you provided a short sentence in a README on what each new variant adds / evaluates?\n- [ ] Have you noted which, if any, published evaluation setups are matched by this variant?\n\nIt is recommended to include a filled-out copy of this checklist in the README.md for the subfolder you are creating, if you have created a new subfolder in `lm_eval/tasks`.\n\n**Finally, please add a short description of your task(s), along with a link to its subfolder in lm_eval/tasks, to [`lm_eval/tasks/README.md`](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/tasks/README.md) so that users can discover your task in the library, and follow the link to your README for more information about the variants supported, their task names, and the original source of the dataset and/or evaluation setup.**\n\n## Submitting your task\n\nYou're all set! Now push your work and make a pull request to the `main` branch! Thanks for the contribution :). If there are any questions, please leave a message in the `#lm-thunderdome` channel on the EAI discord!\n" }, { "path": "docs/python-api.md", "content": "# Python API\n\nThis guide covers programmatic usage of the evaluation harness in Python scripts and applications.\n\n## Overview\n\nThe library provides three main ways to run evaluations programmatically:\n\n| Function | Use Case |\n|----------|----------|\n| `simple_evaluate()` | Most common - accepts model name strings or LM objects |\n| `EvaluatorConfig` | Config-based - load settings from YAML or dataclass |\n| `evaluate()` | Low-level - full control over task dictionaries |\n\n---\n\n## Quick Start\n\nThe simplest way to run an evaluation:\n\n```python\nimport lm_eval\n\nresults = lm_eval.simple_evaluate(\n model=\"hf\",\n model_args=\"pretrained=gpt2\",\n tasks=[\"hellaswag\"],\n)\n\nprint(results[\"results\"])\n```\n\n---\n\n## Using `simple_evaluate()`\n\nThe `simple_evaluate()` function is the recommended entry point for most use cases.\n\n### Basic Usage\n\n```python\nimport lm_eval\n\nresults = lm_eval.simple_evaluate(\n model=\"hf\",\n model_args=\"pretrained=gpt2,dtype=float32\",\n tasks=[\"hellaswag\", \"arc_easy\"],\n num_fewshot=5,\n batch_size=8,\n device=\"cuda:0\",\n)\n```\n\n### With a Pre-initialized Model\n\n```python\nimport lm_eval\nfrom lm_eval.models.huggingface import HFLM\n\n# Initialize model separately\nlm = HFLM(pretrained=\"gpt2\", batch_size=16)\n\nresults = lm_eval.simple_evaluate(\n model=lm,\n tasks=[\"hellaswag\"],\n num_fewshot=0,\n)\n```\n\n### With External Tasks\n\n```python\nimport lm_eval\nfrom lm_eval.tasks import TaskManager\n\n# Include custom task definitions\ntask_manager = TaskManager(include_path=\"/path/to/custom/tasks\")\n\nresults = lm_eval.simple_evaluate(\n model=\"hf\",\n model_args=\"pretrained=gpt2\",\n tasks=[\"my_custom_task\"],\n task_manager=task_manager,\n)\n```\n\n### Common Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `model` | str or LM | Model name (e.g., \"hf\", \"vllm\") or LM instance |\n| `model_args` | str or dict | Model constructor arguments |\n| `tasks` | list[str] | Task names to evaluate |\n| `num_fewshot` | int | Number of few-shot examples |\n| `batch_size` | int or str | Batch size or \"auto\" |\n| `device` | str | Device (cuda, cpu, mps) |\n| `limit` | int or float | Limit examples per task |\n| `log_samples` | bool | Save model inputs/outputs |\n| `task_manager` | TaskManager | For external tasks |\n| `gen_kwargs` | dict | Generation arguments |\n| `apply_chat_template` | bool or str | Use chat template |\n| `system_instruction` | str | System prompt |\n| `fewshot_as_multiturn` | bool | Multi-turn few-shot |\n\nSee [`lm_eval/evaluator.py`](../lm_eval/evaluator.py) for the complete parameter list.\n\n### Return Value\n\n`simple_evaluate()` returns a dictionary with:\n\n```python\n{\n \"results\": {\n \"task_name\": {\n \"metric_name\": value,\n \"metric_name,stderr\": stderr_value,\n }\n },\n \"configs\": {...}, # Task configurations\n \"versions\": {...}, # Task versions\n \"n-shot\": {...}, # Few-shot counts\n \"higher_is_better\": {...},\n \"n-samples\": {...},\n \"samples\": {...}, # If log_samples=True\n}\n```\n\n---\n\n## Using `EvaluatorConfig`\n\nThe `EvaluatorConfig` class provides a structured way to manage evaluation settings.\n\n### From YAML File\n\n```python\nfrom lm_eval.config.evaluate_config import EvaluatorConfig\nimport lm_eval\n\n# Load configuration from YAML\nconfig = EvaluatorConfig.from_config(\"eval_config.yaml\")\n\n# Process tasks\ntask_manager = config.process_tasks()\n\n# Run evaluation\nresults = lm_eval.simple_evaluate(\n model=config.model,\n model_args=config.model_args,\n tasks=config.tasks,\n num_fewshot=config.num_fewshot,\n batch_size=config.batch_size,\n device=config.device,\n task_manager=task_manager,\n log_samples=config.log_samples,\n gen_kwargs=config.gen_kwargs,\n apply_chat_template=config.apply_chat_template,\n system_instruction=config.system_instruction,\n)\n```\n\n### Direct Instantiation\n\n```python\nfrom lm_eval.config.evaluate_config import EvaluatorConfig\n\nconfig = EvaluatorConfig(\n model=\"hf\",\n model_args={\"pretrained\": \"gpt2\", \"dtype\": \"float32\"},\n tasks=[\"hellaswag\", \"arc_easy\"],\n num_fewshot=5,\n batch_size=8,\n device=\"cuda:0\",\n output_path=\"./results/\",\n log_samples=True,\n)\n\n# Validate and process\ntask_manager = config.process_tasks()\n```\n\n### Config Fields\n\nSee the [Configuration Guide](config_files.md#config-schema) for all available fields.\n\n---\n\n## Using `evaluate()`\n\nThe `evaluate()` function provides lower-level control, accepting pre-built task dictionaries.\n\n### With Custom Task Objects\n\n```python\nimport lm_eval\nfrom lm_eval.tasks import TaskManager, get_task_dict\nfrom lm_eval.models.huggingface import HFLM\n\n# Initialize model\nlm = HFLM(pretrained=\"gpt2\", batch_size=16)\n\n# Build task dictionary\ntask_manager = TaskManager(include_path=\"/path/to/custom/tasks\")\ntask_dict = get_task_dict(\n [\"hellaswag\", \"my_custom_task\"],\n task_manager\n)\n\n# Run evaluation\nresults = lm_eval.evaluate(\n lm=lm,\n task_dict=task_dict,\n num_fewshot=5,\n limit=100,\n)\n```\n\n### Mixed Task Sources\n\n```python\nfrom lm_eval.tasks import get_task_dict\n\n# Combine different task sources\ntask_dict = get_task_dict(\n [\n \"mmlu\", # Stock task name\n \"my_custom_task\", # From include_path\n {\"task\": \"inline_task\", ...}, # Inline config dict\n ],\n task_manager\n)\n```\n\n---\n\n## Custom Models\n\nTo evaluate a custom model, create a subclass of `lm_eval.api.model.LM`:\n\n```python\nfrom lm_eval.api.model import LM\n\nclass MyCustomLM(LM):\n def __init__(self, model, batch_size=1):\n super().__init__()\n self.model = model\n self._batch_size = batch_size\n\n def loglikelihood(self, requests):\n # Return list of (logprob, is_greedy) tuples\n ...\n\n def generate_until(self, requests):\n # Return list of generated strings\n ...\n\n def loglikelihood_rolling(self, requests):\n # Return list of (logprob, is_greedy) tuples\n ...\n\n @property\n def batch_size(self):\n return self._batch_size\n```\n\nThen use it with `simple_evaluate()`:\n\n```python\nmy_model = load_my_model()\nlm = MyCustomLM(model=my_model, batch_size=16)\n\nresults = lm_eval.simple_evaluate(\n model=lm,\n tasks=[\"hellaswag\"],\n)\n```\n\nFor detailed guidance on implementing custom models, see the [Model Guide](model_guide.md).\n\n---\n\n## Logging\n\nConfigure logging for debugging:\n\n```python\nfrom lm_eval.utils import setup_logging\n\n# Set log level\nsetup_logging(\"DEBUG\") # DEBUG, INFO, WARNING, ERROR\n\n# Or use environment variable\nimport os\nos.environ[\"LMEVAL_LOG_LEVEL\"] = \"DEBUG\"\n```\n\n---\n\n## Examples\n\n### Batch Evaluation of Multiple Models\n\n```python\nimport lm_eval\n\nmodels = [\n \"gpt2\",\n \"gpt2-medium\",\n \"gpt2-large\",\n]\n\nall_results = {}\nfor model_name in models:\n results = lm_eval.simple_evaluate(\n model=\"hf\",\n model_args=f\"pretrained={model_name}\",\n tasks=[\"hellaswag\"],\n batch_size=\"auto\",\n )\n all_results[model_name] = results[\"results\"]\n```\n\n### Save and Load Results\n\n```python\nimport json\nimport lm_eval\nfrom lm_eval.utils import handle_non_serializable\n\nresults = lm_eval.simple_evaluate(\n model=\"hf\",\n model_args=\"pretrained=gpt2\",\n tasks=[\"hellaswag\"],\n)\n\n# Save results\nwith open(\"results.json\", \"w\") as f:\n json.dump(results, f, default=handle_non_serializable, indent=2)\n```\n" }, { "path": "docs/task_guide.md", "content": "# Task Configuration\n\nThe `lm-evaluation-harness` is meant to be an extensible and flexible framework within which many different evaluation tasks can be defined. All tasks in the new version of the harness are built around a YAML configuration file format.\n\nThese YAML configuration files, along with the current codebase commit hash, are intended to be shareable such that providing the YAML config enables another researcher to precisely replicate the evaluation setup used by another, in the case that the prompt or setup differs from standard `lm-eval` task implementations.\n\nWhile adding a standard evaluation task on a new dataset can be occasionally as simple as swapping out a Hugging Face dataset path in an existing file, more specialized evaluation setups also exist. Here we'll provide a crash course on the more advanced logic implementable in YAML form available to users.\n\nIf your intended task relies on features beyond what is described in this guide, we'd love to hear about it! Feel free to open an issue describing the scenario on Github, create a PR to the project with a proposed implementation, or ask in the `#lm-thunderdome` channel on the EleutherAI discord.\n\n## Configurations\n\nTasks are configured via the `TaskConfig` object. Below, we describe all fields usable within the object, and their role in defining a task.\n\n### Parameters\n\nTask naming + registration:\n\n- **task** (`str`, defaults to None) — name of the task.\n- **task_alias** (`str`, defaults to None) - Alias of the task name that will be printed in the final table results.\n- **tag** (`str`, *optional*) — name of the task tags(s) a task belongs to. Enables one to run all tasks with a specified tag name at once.\n\nDataset configuration options:\n\n- **dataset_path** (`str`) — The name of the dataset as listed by HF in the datasets Hub.\n- **dataset_name** (`str`, *optional*, defaults to None) — The name of what HF calls a “data instance” or sub-task of the benchmark. If your task does not contain any data instances, just leave this to default to None. (If you're familiar with the HF `datasets.load_dataset` function, these are just the first 2 arguments to it.)\n- **dataset_kwargs** (`dict`, *optional*) — Auxiliary arguments that `datasets.load_dataset` accepts. This can be used to specify arguments such as `data_files` or `data_dir` if you want to use local datafiles such as json or csv.\n- **custom_dataset** (`Callable`, *optional) - A function that returns a `dict[str, datasets.Dataset]` (, dataset) object. This can be used to load a dataset from a custom source or to preprocess the dataset in a way that is not supported by the `datasets` library. Will have access to `metadata` field if defined (from config and passed to TaskManager), and `model_args` from runtime (if using `evaluate`).\n- **training_split** (`str`, *optional*) — Split in the dataset to use as the training split.\n- **validation_split** (`str`, *optional*) — Split in the dataset to use as the validation split.\n- **test_split** (`str`, *optional*) — Split in the dataset to use as the test split.\n- **fewshot_split** (`str`, *optional*) — Split in the dataset to draw few-shot exemplars from. assert that this not None if num_fewshot > 0.\n- **process_docs** (`Callable`, *optional*) — Optionally define a function to apply to each HF dataset split, to preprocess all documents before being fed into prompt template rendering or other evaluation steps. Can be used to rename dataset columns, or to process documents into a format closer to the expected format expected by a prompt template.\n\nPrompting / in-context formatting options:\n\n- **use_prompt** (`str`, *optional*) — Name of prompt in promptsource to use. if defined, will overwrite doc_to_text, doc_to_target, and doc_to_choice.\n- **description** (`str`, *optional*) — An optional prepended Jinja2 template or string which will be prepended to the few-shot examples passed into the model, often describing the task or providing instructions to a model, such as `\"The following are questions (with answers) about {{subject}}.\\n\\n\"`. No delimiters or spacing are inserted between the description and the first few-shot example.\n- **doc_to_text** (`Union[Callable, str]`, *optional*) — Jinja2 template, string, or function to process a sample into the appropriate input for the model.\n- **doc_to_target** (`Union[Callable, str]`, *optional*) — Jinja2 template, string, or function to process a sample into the appropriate target output for the model. For multiple choice tasks, this should return an index into the answer choice list of the correct answer.\n- **doc_to_choice** (`Union[Callable, str]`, *optional*) — Jinja2 template, string, or function to process a sample into a list of possible string choices for `multiple_choice` tasks. Left undefined for `generate_until` tasks.\n- **fewshot_delimiter** (`str`, *optional*, defaults to \"\\n\\n\") — String to insert between few-shot examples.\n- **target_delimiter** (`str`, *optional*, defaults to `\" \"`) — String to insert between input and target output for the datapoint being tested.\n- **gen_prefix** (`str`, *optional*) — String to append after the <|assistant|> token. For example, if the task is to generate a question, the gen_prefix could be \"The answer is: \" to prompt the model to generate an answer to the question. If not using a chat template then this string will be appended to the end of the prompt.\n\nRuntime configuration options:\n\n- **num_fewshot** (`int`, *optional*, defaults to 0) — Number of few-shot examples before the input.\n- **batch_size** (`int`, *optional*, defaults to 1) — Batch size.\n\nScoring details:\n\n- **metric_list** (`str`, *optional*, defaults to None) — A list of metrics to use for evaluation. See docs for expected format.\n- **output_type** (`str`, *optional*, defaults to \"generate_until\") — Selects the type of model output for the given task. Options are `generate_until`, `loglikelihood`, `loglikelihood_rolling`, and `multiple_choice`.\n- **generation_kwargs** (`dict`, *optional*) — Auxiliary arguments for the `generate` function from HF transformers library. Advanced keyword arguments may not be supported for non-HF LM classes.\n- **repeats** (`int`, *optional*, defaults to 1) — Number of repeated runs through model for each sample. Can be used for cases such as self-consistency.\n- **filter_list** (`Union[str, list]`, *optional*) — List of filters to postprocess model outputs. See below for further detail on the filter API.\n- **should_decontaminate** (`bool`, *optional*, defaults to False) - Whether to decontaminate or not.\n- **doc_to_decontamination_query** (`str`, *optional*) — Query for decontamination if `should_decontaminate` is True. If `should_decontaminate` is True but `doc_to_decontamination_query` is `None`, `doc_to_decontamination_query` will follow `doc_to_text`.\n\nOther:\n\n- **metadata** (`dict`, *optional*) — An optional field where arbitrary metadata can be passed. Most tasks should include a `version` key in this field that is used to denote the version of the yaml config. Other special metadata keys are: `num_fewshot`, to override the printed `n-shot` table column for a task. Will also be passed to the `custom_dataset` function if defined.\n\n## Filters\n\nA key component of the `lm-evaluation-harness` library is the `Filter` object. In a typical evaluation run of the harness, we take the formatted inputs and run them through our LM, with the appropriate output type (greedy or free-form generation, or loglikelihood-based comparative scoring).\n\nAfter getting scores or output text from our LM on each `Instance` or document in the dataset, we then need to feed these responses into a metric or scoring function to return scores to a user.\n\nHowever, certain tasks may require more complex behavior than directly turning over model outputs to a metric function. For example, we may want to post-process our output text by truncating it or extracting a model's answer, we may want to ensemble over multiple \"takes\" on a different document, et cetera.\n\n**Detailed Aside**:\nWe do such post-processing by operating on *responses*, which are stored after running an LM on an `Instance` from the task in `Instance.resps`.\n\n`resps` is a `List[str]` for each instance, and we pass a `List[List[]]` to our filters that is a list of `[instance.resps for instance in instances]`.\n\nOur filters, after completing a pipeline, must return a `List[]` which we then unpack and store each element of in `Instance.filtered_resps` for the corresponding instance. Thus, we take as input a list of returns from our model for each doc, and must return a return from our model *without it being wrapped in a list* for each doc.\n**End Aside**\n\nA full list of supported filter operations can be found in `lm_eval/filters/__init__.py`. Contributions of new filter types are welcome!\n\n### Multiple Filter Pipelines\n\nTasks need not be limited to a single filter pipeline. We enable users to run multiple, distinct, filter pipelines on *the same model outputs* generated in one run on a task.\n\nAs a case study, let's look at an implementation of solving the Gsm8k math word problem benchmark in `lm_eval/tasks/gsm8k/gsm8k-cot-self-consistency.yaml`. Here, we are emulating the setup used by [Self-Consistency Improves Chain of Thought Prompting](https://arxiv.org/abs/2203.11171), in which evaluation is performed by generating N chain-of-thought outputs from a model via temperature-based sampling, then selecting the answers output by the model at the end of the chains of thought, then majority voting across all those numeric answers.\n\nWithin our YAML file:\n\n```yaml\n...\nrepeats: 64\nfilter_list:\n - name: \"score-first\"\n filter:\n - function: \"regex\"\n regex_pattern: \"The answer is (\\\\-?[0-9\\\\.\\\\,]*[0-9]+)\"\n - function: \"take_first\"\n - name: \"maj@64\"\n filter:\n - function: \"regex\"\n regex_pattern: \"The answer is (\\\\-?[0-9\\\\.\\\\,]*[0-9]+)\"\n - function: \"majority_vote\"\n - function: \"take_first\"\n - name: \"maj@8\"\n filter:\n - function: \"take_first_k\"\n k: 8\n - function: \"regex\"\n regex_pattern: \"The answer is (\\\\-?[0-9\\\\.\\\\,]*[0-9]+)\"\n - function: \"majority_vote\"\n - function: \"take_first\"\n```\n\nWe are able to provide multiple different filter pipelines, each with their own name and list of filters to apply in sequence.\n\nOur first filter pipeline implements\n\n- applying a regex to the model generations (extracting the number within the phrase \"The answer is (number)\")\n- selecting only the first out of the 64 model answers\n\nThen scoring this single answer.\n\n```yaml\n- name: \"score-first\"\n filter:\n - function: \"regex\"\n regex_pattern: \"The answer is (\\\\-?[0-9\\\\.\\\\,]*[0-9]+)\"\n - function: \"take_first\"\n```\n\nOur second filter pipeline, \"maj@64\", does majority voting across all 64 answers via:\n\n- applying the same regex to all responses, to get the numerical answer from the model for each of the 64 responses per problem\n- applying majority voting to all responses, which then returns a length-1 `[]` list for each\n- taking the first element of this length-1 list, to then score the sole response `` for each document.\n\n```yaml\n- name: \"maj@64\"\n filter:\n - function: \"regex\"\n regex_pattern: \"The answer is (\\\\-?[0-9\\\\.\\\\,]*[0-9]+)\"\n - function: \"majority_vote\"\n - function: \"take_first\"\n```\n\nOur final filter pipeline, \"maj@8\", does majority voting across the first 8 of the model's responses per document via:\n\n- subsetting the len-64 list of responses `[answer1, answer2, ..., answer64]` to `[answer1, answer2, ..., answer8]` for each document\n- performing the same sequence of filters on these new sets of 8 responses, for each document.\n\n```yaml\n- name: \"maj@8\"\n filter:\n - function: \"take_first_k\"\n k: 8\n - function: \"regex\"\n regex_pattern: \"The answer is (\\\\-?[0-9\\\\.\\\\,]*[0-9]+)\"\n - function: \"majority_vote\"\n - function: \"take_first\"\n```\n\nThus, given the 64 responses from our LM on each document, we can report metrics on these responses in these 3 different ways, as defined by our filter pipelines.\n\n### Adding a custom filter\n\nJust like adding a custom model with `register_model` decorator one is able to do the same with filters, for example\n\n```python\nfrom lm_eval.api.filter import Filter\nfrom lm_eval.api.registry import register_filter\n\n@register_filter(\"new_filter\")\nclass NewFilter(Filter)\n ...\n```\n\n## Embedded Python Code\n\nUse can use python functions for certain arguments by using the `!function` operator after the argument name followed by `.`. This feature can be used for the following arguments:\n\n1. `doc_to_text`\n2. `doc_to_target`\n3. `doc_to_choice`\n4. `aggregation` for a `metric` in `metric_list`\n\n## (No Longer Recommended) Direct `Task` Subclassing\n\nThe prior implementation method of new tasks was to subclass `Task`. While we intend to migrate all tasks to the new YAML implementation option going forward, it remains possible to subclass the Task class and implement custom logic. For more information, see `docs/task_guide.md` in v0.3.0 of the `lm-evaluation-harness`.\n\n## Including a Base YAML\n\nYou can base a YAML on another YAML file as a template. This can be handy when you need to just change the prompt for `doc_to_text` but keep the rest the same or change `filters` to compare which is better. Simply use `include` in the YAML file and write the name of the template you want to base from. This assumes that the base template is in the same directory. Otherwise, You will need to define the full path.\n\n```yaml\ninclude: \n...\n```\n\nYou can find an example of how to use this feature at [gsm8k-cot-self-consistency.yaml](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/tasks/gsm8k/gsm8k-cot-self-consistency.yaml) where it is based off [gsm8k-cot.yaml](https://github.com/EleutherAI/lm-evaluation-harness/blob/main/lm_eval/tasks/gsm8k/gsm8k-cot.yaml)\n\n## Passing Arguments to Metrics\n\nMetrics can be defined in the `metric_list` argument when building the YAML config. Multiple metrics can be listed along with any auxiliary arguments. For example, setting the [`exact_match` metric](https://github.com/huggingface/evaluate/tree/main/metrics/exact_match), auxiliary arguments such as `ignore_case`, `ignore_punctuation`, `regexes_to_ignore` can be listed as well. They will be added to the metric function as `kwargs`. Some metrics have predefined values for `aggregation` and `higher_is_better` so listing the metric name only can be sufficient.\n\n```yaml\nmetric_list:\n - metric: acc\n - metric: exact_match\n aggregation: mean\n higher_is_better: true\n ignore_case: true\n ignore_punctuation: false\n regexes_to_ignore:\n - \",\"\n - \"\\\\$\"\n```\n\n### Natively Supported Metrics\n\nHere we list all metrics currently supported natively in `lm-eval`:\n\nMetrics:\n\n- `acc` (accuracy)\n- `acc_norm` (length-normalized accuracy)\n- `acc_mutual_info` (baseline loglikelihood - normalized accuracy)\n- `perplexity`\n- `word_perplexity` (perplexity per word)\n- `byte_perplexity` (perplexity per byte)\n- `bits_per_byte`\n- `matthews_corrcoef` (Matthews correlation coefficient)\n- `f1` (F1 score)\n- `bleu`\n- `chrf`\n- `ter`\n\nAggregation functions:\n\n- `mean`\n- `median`\n- `perplexity`\n- `weighted_perplexity`\n- `bits_per_byte`\n\n### Adding a Multiple Choice Metric\n\nAdding a multiple choice metric has a few steps. To get it working you need to:\n\n1. register a metric function\n2. register an aggregation function\n3. update the `Task` definition to make sure the correct arguments are passed\n\nThe default metric and aggregation functions are in `lm_eval/api/metrics.py`, and you can add a function there if it's for general use. The metrics are towards the bottom of the file and look like this:\n\n```python\n@register_metric(\n metric=\"mcc\",\n higher_is_better=True,\n output_type=\"multiple_choice\",\n aggregation=\"matthews_corrcoef\",\n)\ndef mcc_fn(items): # This is a passthrough function\n return items\n```\n\nNote that many of these are passthrough functions, and for multiple choice (at least) this function is never actually called.\n\nAggregation functions are defined towards the top of the file, here's an example:\n\n```python\n@register_aggregation(\"matthews_corrcoef\")\ndef matthews_corrcoef(items):\n unzipped_list = list(zip(*items))\n golds = unzipped_list[0]\n preds = unzipped_list[1]\n return sklearn.metrics.matthews_corrcoef(golds, preds)\n```\n\nThis function returns a single numeric value. The input is defined in `Task.process_results` in `lm_eval/api/task.py`. There's a section that looks like this:\n\n```python\nresult_dict = {\n **({\"acc\": acc} if \"acc\" in use_metric else {}),\n **({\"f1\": (gold, pred)} if \"f1\" in use_metric else {}),\n **({\"mcc\": (gold, pred)} if \"mcc\" in use_metric else {}),\n **({\"acc_norm\": acc_norm} if \"acc_norm\" in use_metric else {}),\n **({\"exact_match\": exact_match} if \"exact_match\" in use_metric else {}),\n}\n```\n\nThe value here determines the input to the aggregation function, though the name used matches the metric function. These metrics all have simple needs and just need the accuracy or gold and predicted values, but immediately below this there are examples of metrics with more complicated needs you can use as reference.\n\n## Good Reference Tasks\n\nContributing a new task can be daunting! Luckily, much of the work has often been done for you in a different, similarly evaluated task. Good examples of task implementations to study include:\n\nMultiple choice tasks:\n\n- SciQ (`lm_eval/tasks/sciq/sciq.yaml`)\n\nCorpus perplexity evaluations:\n\n- Wikitext (`lm_eval/tasks/wikitext/wikitext.yaml`)\n\nGenerative tasks:\n\n- GSM8k (`lm_eval/tasks/gsm8k/gsm8k.yaml`)\n\nTasks using complex filtering:\n\n- GSM8k with CoT (+ with Self-Consistency): (`lm_eval/tasks/gsm8k/gsm8k-cot.yaml` ; `lm_eval/tasks/gsm8k/gsm8k-cot-self-consistency.yaml`)\n\n# Group Configuration\n\nWhen evaluating a language model, it is not unusual to test across a number of tasks that may not be related to one another in order to assess a variety of capabilities. To this end, it may be cumbersome to have to list the set of tasks or add a new group name to each yaml of each individual task.\n\nTo solve this, we can create a **group** yaml config. This is a config that contains the names of the tasks that should be included in a particular group. The config consists of two main keys: a `group` key which denotes the name of the group (as it would be called from the command line, e.g. `mmlu`) and a `task` key which is where we can list the tasks. The tasks listed in `task` are the task names that have been registered. A good example of a group yaml config can be found at [../lm_eval/tasks/mmlu/default/_mmlu.yaml]. See also the [New Task Guide](./new_task_guide.md) for a more in-depth and tutorial-esque explanation of how to write complex GroupConfigs.\n\n## Configurations\n\nGroups are configured via the `GroupConfig` object. Below, we describe all fields usable within the object, and their role in defining a task.\n\n### Parameters\n\n- **group** (`str`, defaults to `None`) — name of the group. Used to invoke it from the command line.\n- **group_alias** (`str`, defaults to `None`) - Alternative name for the group that will be printed in the table output.\n- **task** (`Union[str, list]`, defaults to `None`) - List of tasks that constitute the group.\n- **aggregate_metric_list** (`list`, defaults to `None`) - similar to `metric_list` in TaskConfigs, provide a list of configurations for metrics that should be aggregated across subtasks. Leaving empty will result in no aggregation being performed for this group. Keys for each list entry are:\n - `metric: str` - the name of the metric to aggregate over (all subtasks must report a metric holding this name.)\n - `aggregation: str` - what aggregation function to apply to aggregate these per-subtask metrics. **currently, only `mean` is supported.**\n - `weight_by_size: bool = True` whether to perform micro- averaging (`True`) or macro- (`False`) averaging of subtasks' accuracy scores when reporting the group's metric. MMLU, for example, averages over per-document accuracies (the *micro average*), resulting in the same accuracy as if one simply concatenated all 57 subjects into a single dataset and evaluated accuracy on that dataset.\n - `filter_list: Union[str, List[str]] = \"none\"` - what filter keys one should match on to aggregate results. For example, if trying to aggregate over the `exact_match` metric using `strict-match` filter for `bbh_cot_zeroshot`, then set this to be `filter_list: \"strict-match\"`. \n- **metadata** (`dict`, *optional*) - As with TaskConfigs, a field where extra config metadata can be passed. set the `num_fewshot` key within this to override the printed n_shot value in a results table for your group, for example.\n" }, { "path": "examples/lm-eval-overview.ipynb", "content": "{\n \"cells\": [\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {\n \"id\": \"Qw83KAePAhaS\"\n },\n \"source\": [\n \"# Releasing LM-Evaluation-Harness v0.4.0\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {\n \"id\": \"Z7k2vq1iAdqr\"\n },\n \"source\": [\n \"With the vast amount of work done in the field today, it helps to have a tool that people can use easily to share their results and use to check others to ensure reported numbers are valid. The LM Evaluation Harness is one such tool the community has used extensively. We want to continue to support the community and with that in mind, we’re excited to announce a major update on the LM Evaluation Harness to further our goal for open and accessible AI research.\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {\n \"id\": \"0gDoM0AJAvEc\"\n },\n \"source\": [\n \"Our refactor stems from our desires to make the following believed best practices easier to carry out. \\n\",\n \"\\n\",\n \"1. Never copy results from other papers\\n\",\n \"2. Always share your exact prompts\\n\",\n \"3. Always provide model outputs\\n\",\n \"4. Qualitatively review a small batch of outputs before running evaluation jobs at scale\\n\",\n \"\\n\",\n \"We also wanted to make the library a better experience to use and to contribute or design evaluations within. New features in the new release that serve this purpose include:\\n\",\n \"\\n\",\n \"1. Faster Evaluation Runtimes (accelerated data-parallel inference with HF Transformers + Accelerate, and commonly used or faster inference libraries such as vLLM and Llama-CPP)\\n\",\n \"2. Easier addition and sharing of new tasks (YAML-based task config formats, allowing single-file sharing of custom tasks)\\n\",\n \"3. More configurability, for more advanced workflows and easier operation with modifying prompts\\n\",\n \"4. Better logging of data at runtime and post-hoc\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {\n \"id\": \"nnwsOpjda_YW\"\n },\n \"source\": [\n \"In this notebook we will be going through a short tutorial on how things work.\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {\n \"id\": \"zAov81vTbL2K\"\n },\n \"source\": [\n \"## Install LM-Eval\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": 1,\n \"metadata\": {\n \"colab\": {\n \"base_uri\": \"https://localhost:8080/\"\n },\n \"id\": \"8hiosGzq_qZg\",\n \"outputId\": \"6ab73e5e-1f54-417e-a388-07e0d870b132\"\n },\n \"outputs\": [\n {\n \"name\": \"stdout\",\n \"output_type\": \"stream\",\n \"text\": [\n \"Collecting git+https://github.com/EleutherAI/lm-evaluation-harness.git@big-refactor\\n\",\n \" Cloning https://github.com/EleutherAI/lm-evaluation-harness.git (to revision big-refactor) to /tmp/pip-req-build-tnssql5s\\n\",\n \" Running command git clone --filter=blob:none --quiet https://github.com/EleutherAI/lm-evaluation-harness.git /tmp/pip-req-build-tnssql5s\\n\",\n \" Running command git checkout -b big-refactor --track origin/big-refactor\\n\",\n \" Switched to a new branch 'big-refactor'\\n\",\n \" Branch 'big-refactor' set up to track remote branch 'big-refactor' from 'origin'.\\n\",\n \" Resolved https://github.com/EleutherAI/lm-evaluation-harness.git to commit 42f486ee49b65926a444cb0620870a39a5b4b0a8\\n\",\n \" Installing build dependencies ... \\u001b[?25l\\u001b[?25hdone\\n\",\n \" Getting requirements to build wheel ... \\u001b[?25l\\u001b[?25hdone\\n\",\n \" Preparing metadata (pyproject.toml) ... \\u001b[?25l\\u001b[?25hdone\\n\",\n \"Collecting accelerate>=0.21.0 (from lm-eval==1.0.0)\\n\",\n \" Downloading accelerate-0.24.1-py3-none-any.whl (261 kB)\\n\",\n \"\\u001b[2K \\u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\u001b[0m \\u001b[32m261.4/261.4 kB\\u001b[0m \\u001b[31m4.1 MB/s\\u001b[0m eta \\u001b[36m0:00:00\\u001b[0m\\n\",\n \"\\u001b[?25hCollecting evaluate (from lm-eval==1.0.0)\\n\",\n \" Downloading evaluate-0.4.1-py3-none-any.whl (84 kB)\\n\",\n \"\\u001b[2K \\u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\u001b[0m \\u001b[32m84.1/84.1 kB\\u001b[0m \\u001b[31m5.9 MB/s\\u001b[0m eta \\u001b[36m0:00:00\\u001b[0m\\n\",\n \"\\u001b[?25hCollecting datasets>=2.0.0 (from lm-eval==1.0.0)\\n\",\n \" Downloading datasets-2.15.0-py3-none-any.whl (521 kB)\\n\",\n \"\\u001b[2K \\u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\u001b[0m \\u001b[32m521.2/521.2 kB\\u001b[0m \\u001b[31m9.5 MB/s\\u001b[0m eta \\u001b[36m0:00:00\\u001b[0m\\n\",\n \"\\u001b[?25hCollecting jsonlines (from lm-eval==1.0.0)\\n\",\n \" Downloading jsonlines-4.0.0-py3-none-any.whl (8.7 kB)\\n\",\n \"Requirement already satisfied: numexpr in /usr/local/lib/python3.10/dist-packages (from lm-eval==1.0.0) (2.8.7)\\n\",\n \"Collecting peft>=0.2.0 (from lm-eval==1.0.0)\\n\",\n \" Downloading peft-0.6.2-py3-none-any.whl (174 kB)\\n\",\n \"\\u001b[2K \\u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\u001b[0m \\u001b[32m174.7/174.7 kB\\u001b[0m \\u001b[31m7.2 MB/s\\u001b[0m eta \\u001b[36m0:00:00\\u001b[0m\\n\",\n \"\\u001b[?25hCollecting pybind11>=2.6.2 (from lm-eval==1.0.0)\\n\",\n \" Downloading pybind11-2.11.1-py3-none-any.whl (227 kB)\\n\",\n \"\\u001b[2K \\u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\u001b[0m \\u001b[32m227.7/227.7 kB\\u001b[0m \\u001b[31m12.9 MB/s\\u001b[0m eta \\u001b[36m0:00:00\\u001b[0m\\n\",\n \"\\u001b[?25hCollecting pytablewriter (from lm-eval==1.0.0)\\n\",\n \" Downloading pytablewriter-1.2.0-py3-none-any.whl (111 kB)\\n\",\n \"\\u001b[2K \\u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\u001b[0m \\u001b[32m111.1/111.1 kB\\u001b[0m \\u001b[31m8.3 MB/s\\u001b[0m eta \\u001b[36m0:00:00\\u001b[0m\\n\",\n \"\\u001b[?25hCollecting rouge-score>=0.0.4 (from lm-eval==1.0.0)\\n\",\n \" Downloading rouge_score-0.1.2.tar.gz (17 kB)\\n\",\n \" Preparing metadata (setup.py) ... \\u001b[?25l\\u001b[?25hdone\\n\",\n \"Collecting sacrebleu>=1.5.0 (from lm-eval==1.0.0)\\n\",\n \" Downloading sacrebleu-2.3.2-py3-none-any.whl (119 kB)\\n\",\n \"\\u001b[2K \\u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\u001b[0m \\u001b[32m119.7/119.7 kB\\u001b[0m \\u001b[31m8.7 MB/s\\u001b[0m eta \\u001b[36m0:00:00\\u001b[0m\\n\",\n \"\\u001b[?25hRequirement already satisfied: scikit-learn>=0.24.1 in /usr/local/lib/python3.10/dist-packages (from lm-eval==1.0.0) (1.2.2)\\n\",\n \"Collecting sqlitedict (from lm-eval==1.0.0)\\n\",\n \" Downloading sqlitedict-2.1.0.tar.gz (21 kB)\\n\",\n \" Preparing metadata (setup.py) ... \\u001b[?25l\\u001b[?25hdone\\n\",\n \"Requirement already satisfied: torch>=1.8 in /usr/local/lib/python3.10/dist-packages (from lm-eval==1.0.0) (2.1.0+cu118)\\n\",\n \"Collecting tqdm-multiprocess (from lm-eval==1.0.0)\\n\",\n \" Downloading tqdm_multiprocess-0.0.11-py3-none-any.whl (9.8 kB)\\n\",\n \"Requirement already satisfied: transformers>=4.1 in /usr/local/lib/python3.10/dist-packages (from lm-eval==1.0.0) (4.35.2)\\n\",\n \"Collecting zstandard (from lm-eval==1.0.0)\\n\",\n \" Downloading zstandard-0.22.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.4 MB)\\n\",\n \"\\u001b[2K \\u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\u001b[0m \\u001b[32m5.4/5.4 MB\\u001b[0m \\u001b[31m29.2 MB/s\\u001b[0m eta \\u001b[36m0:00:00\\u001b[0m\\n\",\n \"\\u001b[?25hRequirement already satisfied: numpy>=1.17 in /usr/local/lib/python3.10/dist-packages (from accelerate>=0.21.0->lm-eval==1.0.0) (1.23.5)\\n\",\n \"Requirement already satisfied: packaging>=20.0 in /usr/local/lib/python3.10/dist-packages (from accelerate>=0.21.0->lm-eval==1.0.0) (23.2)\\n\",\n \"Requirement already satisfied: psutil in /usr/local/lib/python3.10/dist-packages (from accelerate>=0.21.0->lm-eval==1.0.0) (5.9.5)\\n\",\n \"Requirement already satisfied: pyyaml in /usr/local/lib/python3.10/dist-packages (from accelerate>=0.21.0->lm-eval==1.0.0) (6.0.1)\\n\",\n \"Requirement already satisfied: huggingface-hub in /usr/local/lib/python3.10/dist-packages (from accelerate>=0.21.0->lm-eval==1.0.0) (0.19.4)\\n\",\n \"Requirement already satisfied: pyarrow>=8.0.0 in /usr/local/lib/python3.10/dist-packages (from datasets>=2.0.0->lm-eval==1.0.0) (9.0.0)\\n\",\n \"Collecting pyarrow-hotfix (from datasets>=2.0.0->lm-eval==1.0.0)\\n\",\n \" Downloading pyarrow_hotfix-0.6-py3-none-any.whl (7.9 kB)\\n\",\n \"Collecting dill<0.3.8,>=0.3.0 (from datasets>=2.0.0->lm-eval==1.0.0)\\n\",\n \" Downloading dill-0.3.7-py3-none-any.whl (115 kB)\\n\",\n \"\\u001b[2K \\u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\u001b[0m \\u001b[32m115.3/115.3 kB\\u001b[0m \\u001b[31m14.4 MB/s\\u001b[0m eta \\u001b[36m0:00:00\\u001b[0m\\n\",\n \"\\u001b[?25hRequirement already satisfied: pandas in /usr/local/lib/python3.10/dist-packages (from datasets>=2.0.0->lm-eval==1.0.0) (1.5.3)\\n\",\n \"Requirement already satisfied: requests>=2.19.0 in /usr/local/lib/python3.10/dist-packages (from datasets>=2.0.0->lm-eval==1.0.0) (2.31.0)\\n\",\n \"Requirement already satisfied: tqdm>=4.62.1 in /usr/local/lib/python3.10/dist-packages (from datasets>=2.0.0->lm-eval==1.0.0) (4.66.1)\\n\",\n \"Requirement already satisfied: xxhash in /usr/local/lib/python3.10/dist-packages (from datasets>=2.0.0->lm-eval==1.0.0) (3.4.1)\\n\",\n \"Collecting multiprocess (from datasets>=2.0.0->lm-eval==1.0.0)\\n\",\n \" Downloading multiprocess-0.70.15-py310-none-any.whl (134 kB)\\n\",\n \"\\u001b[2K \\u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\u001b[0m \\u001b[32m134.8/134.8 kB\\u001b[0m \\u001b[31m19.9 MB/s\\u001b[0m eta \\u001b[36m0:00:00\\u001b[0m\\n\",\n \"\\u001b[?25hRequirement already satisfied: fsspec[http]<=2023.10.0,>=2023.1.0 in /usr/local/lib/python3.10/dist-packages (from datasets>=2.0.0->lm-eval==1.0.0) (2023.6.0)\\n\",\n \"Requirement already satisfied: aiohttp in /usr/local/lib/python3.10/dist-packages (from datasets>=2.0.0->lm-eval==1.0.0) (3.8.6)\\n\",\n \"Collecting responses<0.19 (from evaluate->lm-eval==1.0.0)\\n\",\n \" Downloading responses-0.18.0-py3-none-any.whl (38 kB)\\n\",\n \"Requirement already satisfied: safetensors in /usr/local/lib/python3.10/dist-packages (from peft>=0.2.0->lm-eval==1.0.0) (0.4.0)\\n\",\n \"Requirement already satisfied: absl-py in /usr/local/lib/python3.10/dist-packages (from rouge-score>=0.0.4->lm-eval==1.0.0) (1.4.0)\\n\",\n \"Requirement already satisfied: nltk in /usr/local/lib/python3.10/dist-packages (from rouge-score>=0.0.4->lm-eval==1.0.0) (3.8.1)\\n\",\n \"Requirement already satisfied: six>=1.14.0 in /usr/local/lib/python3.10/dist-packages (from rouge-score>=0.0.4->lm-eval==1.0.0) (1.16.0)\\n\",\n \"Collecting portalocker (from sacrebleu>=1.5.0->lm-eval==1.0.0)\\n\",\n \" Downloading portalocker-2.8.2-py3-none-any.whl (17 kB)\\n\",\n \"Requirement already satisfied: regex in /usr/local/lib/python3.10/dist-packages (from sacrebleu>=1.5.0->lm-eval==1.0.0) (2023.6.3)\\n\",\n \"Requirement already satisfied: tabulate>=0.8.9 in /usr/local/lib/python3.10/dist-packages (from sacrebleu>=1.5.0->lm-eval==1.0.0) (0.9.0)\\n\",\n \"Collecting colorama (from sacrebleu>=1.5.0->lm-eval==1.0.0)\\n\",\n \" Downloading colorama-0.4.6-py2.py3-none-any.whl (25 kB)\\n\",\n \"Requirement already satisfied: lxml in /usr/local/lib/python3.10/dist-packages (from sacrebleu>=1.5.0->lm-eval==1.0.0) (4.9.3)\\n\",\n \"Requirement already satisfied: scipy>=1.3.2 in /usr/local/lib/python3.10/dist-packages (from scikit-learn>=0.24.1->lm-eval==1.0.0) (1.11.3)\\n\",\n \"Requirement already satisfied: joblib>=1.1.1 in /usr/local/lib/python3.10/dist-packages (from scikit-learn>=0.24.1->lm-eval==1.0.0) (1.3.2)\\n\",\n \"Requirement already satisfied: threadpoolctl>=2.0.0 in /usr/local/lib/python3.10/dist-packages (from scikit-learn>=0.24.1->lm-eval==1.0.0) (3.2.0)\\n\",\n \"Requirement already satisfied: filelock in /usr/local/lib/python3.10/dist-packages (from torch>=1.8->lm-eval==1.0.0) (3.13.1)\\n\",\n \"Requirement already satisfied: typing-extensions in /usr/local/lib/python3.10/dist-packages (from torch>=1.8->lm-eval==1.0.0) (4.5.0)\\n\",\n \"Requirement already satisfied: sympy in /usr/local/lib/python3.10/dist-packages (from torch>=1.8->lm-eval==1.0.0) (1.12)\\n\",\n \"Requirement already satisfied: networkx in /usr/local/lib/python3.10/dist-packages (from torch>=1.8->lm-eval==1.0.0) (3.2.1)\\n\",\n \"Requirement already satisfied: jinja2 in /usr/local/lib/python3.10/dist-packages (from torch>=1.8->lm-eval==1.0.0) (3.1.2)\\n\",\n \"Requirement already satisfied: triton==2.1.0 in /usr/local/lib/python3.10/dist-packages (from torch>=1.8->lm-eval==1.0.0) (2.1.0)\\n\",\n \"Requirement already satisfied: tokenizers<0.19,>=0.14 in /usr/local/lib/python3.10/dist-packages (from transformers>=4.1->lm-eval==1.0.0) (0.15.0)\\n\",\n \"Requirement already satisfied: attrs>=19.2.0 in /usr/local/lib/python3.10/dist-packages (from jsonlines->lm-eval==1.0.0) (23.1.0)\\n\",\n \"Requirement already satisfied: setuptools>=38.3.0 in /usr/local/lib/python3.10/dist-packages (from pytablewriter->lm-eval==1.0.0) (67.7.2)\\n\",\n \"Collecting DataProperty<2,>=1.0.1 (from pytablewriter->lm-eval==1.0.0)\\n\",\n \" Downloading DataProperty-1.0.1-py3-none-any.whl (27 kB)\\n\",\n \"Collecting mbstrdecoder<2,>=1.0.0 (from pytablewriter->lm-eval==1.0.0)\\n\",\n \" Downloading mbstrdecoder-1.1.3-py3-none-any.whl (7.8 kB)\\n\",\n \"Collecting pathvalidate<4,>=2.3.0 (from pytablewriter->lm-eval==1.0.0)\\n\",\n \" Downloading pathvalidate-3.2.0-py3-none-any.whl (23 kB)\\n\",\n \"Collecting tabledata<2,>=1.3.1 (from pytablewriter->lm-eval==1.0.0)\\n\",\n \" Downloading tabledata-1.3.3-py3-none-any.whl (11 kB)\\n\",\n \"Collecting tcolorpy<1,>=0.0.5 (from pytablewriter->lm-eval==1.0.0)\\n\",\n \" Downloading tcolorpy-0.1.4-py3-none-any.whl (7.9 kB)\\n\",\n \"Collecting typepy[datetime]<2,>=1.3.2 (from pytablewriter->lm-eval==1.0.0)\\n\",\n \" Downloading typepy-1.3.2-py3-none-any.whl (31 kB)\\n\",\n \"Requirement already satisfied: charset-normalizer<4.0,>=2.0 in /usr/local/lib/python3.10/dist-packages (from aiohttp->datasets>=2.0.0->lm-eval==1.0.0) (3.3.2)\\n\",\n \"Requirement already satisfied: multidict<7.0,>=4.5 in /usr/local/lib/python3.10/dist-packages (from aiohttp->datasets>=2.0.0->lm-eval==1.0.0) (6.0.4)\\n\",\n \"Requirement already satisfied: async-timeout<5.0,>=4.0.0a3 in /usr/local/lib/python3.10/dist-packages (from aiohttp->datasets>=2.0.0->lm-eval==1.0.0) (4.0.3)\\n\",\n \"Requirement already satisfied: yarl<2.0,>=1.0 in /usr/local/lib/python3.10/dist-packages (from aiohttp->datasets>=2.0.0->lm-eval==1.0.0) (1.9.2)\\n\",\n \"Requirement already satisfied: frozenlist>=1.1.1 in /usr/local/lib/python3.10/dist-packages (from aiohttp->datasets>=2.0.0->lm-eval==1.0.0) (1.4.0)\\n\",\n \"Requirement already satisfied: aiosignal>=1.1.2 in /usr/local/lib/python3.10/dist-packages (from aiohttp->datasets>=2.0.0->lm-eval==1.0.0) (1.3.1)\\n\",\n \"Requirement already satisfied: chardet<6,>=3.0.4 in /usr/local/lib/python3.10/dist-packages (from mbstrdecoder<2,>=1.0.0->pytablewriter->lm-eval==1.0.0) (5.2.0)\\n\",\n \"Requirement already satisfied: idna<4,>=2.5 in /usr/local/lib/python3.10/dist-packages (from requests>=2.19.0->datasets>=2.0.0->lm-eval==1.0.0) (3.4)\\n\",\n \"Requirement already satisfied: urllib3<3,>=1.21.1 in /usr/local/lib/python3.10/dist-packages (from requests>=2.19.0->datasets>=2.0.0->lm-eval==1.0.0) (2.0.7)\\n\",\n \"Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.10/dist-packages (from requests>=2.19.0->datasets>=2.0.0->lm-eval==1.0.0) (2023.7.22)\\n\",\n \"Requirement already satisfied: python-dateutil<3.0.0,>=2.8.0 in /usr/local/lib/python3.10/dist-packages (from typepy[datetime]<2,>=1.3.2->pytablewriter->lm-eval==1.0.0) (2.8.2)\\n\",\n \"Requirement already satisfied: pytz>=2018.9 in /usr/local/lib/python3.10/dist-packages (from typepy[datetime]<2,>=1.3.2->pytablewriter->lm-eval==1.0.0) (2023.3.post1)\\n\",\n \"Requirement already satisfied: MarkupSafe>=2.0 in /usr/local/lib/python3.10/dist-packages (from jinja2->torch>=1.8->lm-eval==1.0.0) (2.1.3)\\n\",\n \"Requirement already satisfied: click in /usr/local/lib/python3.10/dist-packages (from nltk->rouge-score>=0.0.4->lm-eval==1.0.0) (8.1.7)\\n\",\n \"Requirement already satisfied: mpmath>=0.19 in /usr/local/lib/python3.10/dist-packages (from sympy->torch>=1.8->lm-eval==1.0.0) (1.3.0)\\n\",\n \"Building wheels for collected packages: lm-eval, rouge-score, sqlitedict\\n\",\n \" Building wheel for lm-eval (pyproject.toml) ... \\u001b[?25l\\u001b[?25hdone\\n\",\n \" Created wheel for lm-eval: filename=lm_eval-1.0.0-py3-none-any.whl size=994254 sha256=88356155b19f2891981ecef948326ad6ce8ca40a6009378410ec20d0e225995a\\n\",\n \" Stored in directory: /tmp/pip-ephem-wheel-cache-9v6ye7h3/wheels/17/01/26/599c0779e9858a70a73fa8a306699b5b9a868f820c225457b0\\n\",\n \" Building wheel for rouge-score (setup.py) ... \\u001b[?25l\\u001b[?25hdone\\n\",\n \" Created wheel for rouge-score: filename=rouge_score-0.1.2-py3-none-any.whl size=24933 sha256=6bb0d44e4881972c43ce194e7cb65233d309758cb15f0dec54590d3d2efcfc36\\n\",\n \" Stored in directory: /root/.cache/pip/wheels/5f/dd/89/461065a73be61a532ff8599a28e9beef17985c9e9c31e541b4\\n\",\n \" Building wheel for sqlitedict (setup.py) ... \\u001b[?25l\\u001b[?25hdone\\n\",\n \" Created wheel for sqlitedict: filename=sqlitedict-2.1.0-py3-none-any.whl size=16863 sha256=5747f7dd73ddf3d8fbcebf51b5e4f718fabe1e94bccdf16d2f22a2e65ee7fdf4\\n\",\n \" Stored in directory: /root/.cache/pip/wheels/79/d6/e7/304e0e6cb2221022c26d8161f7c23cd4f259a9e41e8bbcfabd\\n\",\n \"Successfully built lm-eval rouge-score sqlitedict\\n\",\n \"Installing collected packages: sqlitedict, zstandard, tcolorpy, pybind11, pyarrow-hotfix, portalocker, pathvalidate, mbstrdecoder, jsonlines, dill, colorama, typepy, tqdm-multiprocess, sacrebleu, rouge-score, responses, multiprocess, accelerate, datasets, DataProperty, tabledata, peft, evaluate, pytablewriter, lm-eval\\n\",\n \"Successfully installed DataProperty-1.0.1 accelerate-0.24.1 colorama-0.4.6 datasets-2.15.0 dill-0.3.7 evaluate-0.4.1 jsonlines-4.0.0 lm-eval-1.0.0 mbstrdecoder-1.1.3 multiprocess-0.70.15 pathvalidate-3.2.0 peft-0.6.2 portalocker-2.8.2 pyarrow-hotfix-0.6 pybind11-2.11.1 pytablewriter-1.2.0 responses-0.18.0 rouge-score-0.1.2 sacrebleu-2.3.2 sqlitedict-2.1.0 tabledata-1.3.3 tcolorpy-0.1.4 tqdm-multiprocess-0.0.11 typepy-1.3.2 zstandard-0.22.0\\n\"\n ]\n }\n ],\n \"source\": [\n \"# Install LM-Eval\\n\",\n \"!pip install git+https://github.com/EleutherAI/lm-evaluation-harness.git\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": 2,\n \"metadata\": {\n \"colab\": {\n \"base_uri\": \"https://localhost:8080/\",\n \"height\": 0,\n \"referenced_widgets\": [\n \"a1d3a8aa016544a78e8821c8f6199e06\",\n \"f61ed33fad754146bdd2ac9db1ba1c48\",\n \"bfa0af6aeff344c6845e1080a878e92e\",\n \"fd1ad9e0367d4004aae853b91c3a7617\",\n \"6b2d90209ec14230b3d58a74ac9b83bf\",\n \"a73f357065d34d7baf0453ae4a8d75e2\",\n \"46f521b73fd943c081c648fd873ebc0a\",\n \"7c5689bc13684db8a22681f41863dddd\",\n \"48763b6233374554ae76035c0483066f\",\n \"4986a21eb560448fa79f4b25cde48951\",\n \"aed3acd2f2d74003b44079c333a0698e\"\n ]\n },\n \"id\": \"uyO5MaKkZyah\",\n \"outputId\": \"d46e8096-5086-4e49-967e-ea33d4a2a335\"\n },\n \"outputs\": [\n {\n \"data\": {\n \"application/vnd.jupyter.widget-view+json\": {\n \"model_id\": \"a1d3a8aa016544a78e8821c8f6199e06\",\n \"version_major\": 2,\n \"version_minor\": 0\n },\n \"text/plain\": [\n \"Downloading builder script: 0%| | 0.00/5.67k [00:00\\n\",\n \"\\n\",\n \"\\n\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": 5,\n \"metadata\": {\n \"id\": \"fthNg3ywO-kA\"\n },\n \"outputs\": [],\n \"source\": [\n \"YAML_cola_string = \\\"\\\"\\\"\\n\",\n \"tag: yes_or_no_tasks\\n\",\n \"task: demo_cola\\n\",\n \"dataset_path: glue\\n\",\n \"dataset_name: cola\\n\",\n \"output_type: multiple_choice\\n\",\n \"training_split: train\\n\",\n \"validation_split: validation\\n\",\n \"doc_to_text: \\\"{{sentence}}\\\\nQuestion: Does this sentence make sense?\\\\nAnswer:\\\"\\n\",\n \"doc_to_target: label\\n\",\n \"doc_to_choice: [\\\"no\\\", \\\"yes\\\"]\\n\",\n \"should_decontaminate: true\\n\",\n \"doc_to_decontamination_query: sentence\\n\",\n \"metric_list:\\n\",\n \" - metric: acc\\n\",\n \"\\\"\\\"\\\"\\n\",\n \"with open(\\\"cola.yaml\\\", \\\"w\\\") as f:\\n\",\n \" f.write(YAML_cola_string)\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"metadata\": {\n \"id\": \"XceRKCuuDtbn\"\n },\n \"outputs\": [],\n \"source\": \"# !accelerate launch --no_python\\n%env LMEVAL_LOG_LEVEL=DEBUG\\n!lm_eval \\\\\\n --model hf \\\\\\n --model_args pretrained=EleutherAI/pythia-2.8b \\\\\\n --include_path ./ \\\\\\n --tasks yes_or_no_tasks \\\\\\n --limit 10 \\\\\\n --output output/yes_or_no_tasks/ \\\\\\n --log_samples\"\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {\n \"id\": \"XceRKCuuDtbn\"\n },\n \"source\": [\n \"## Edit Prompt Templates Quickly\\n\",\n \"\\n\",\n \"The following is a yaml made to evaluate the specific subtask of `high_school_geography` from MMLU. It uses the standard prompt where the we choose the letters from the options with most likelihood as the model's prediction.\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": 7,\n \"metadata\": {\n \"id\": \"GTFvdt9kSlBG\"\n },\n \"outputs\": [],\n \"source\": [\n \"YAML_mmlu_geo_string = \\\"\\\"\\\"\\n\",\n \"task: demo_mmlu_high_school_geography\\n\",\n \"dataset_path: cais/mmlu\\n\",\n \"dataset_name: high_school_geography\\n\",\n \"description: \\\"The following are multiple choice questions (with answers) about high school geography.\\\\n\\\\n\\\"\\n\",\n \"test_split: test\\n\",\n \"fewshot_split: dev\\n\",\n \"fewshot_config:\\n\",\n \" sampler: first_n\\n\",\n \"output_type: multiple_choice\\n\",\n \"doc_to_text: \\\"{{question.strip()}}\\\\nA. {{choices[0]}}\\\\nB. {{choices[1]}}\\\\nC. {{choices[2]}}\\\\nD. {{choices[3]}}\\\\nAnswer:\\\"\\n\",\n \"doc_to_choice: [\\\"A\\\", \\\"B\\\", \\\"C\\\", \\\"D\\\"]\\n\",\n \"doc_to_target: answer\\n\",\n \"metric_list:\\n\",\n \" - metric: acc\\n\",\n \" aggregation: mean\\n\",\n \" higher_is_better: true\\n\",\n \" - metric: acc_norm\\n\",\n \" aggregation: mean\\n\",\n \" higher_is_better: true\\n\",\n \"\\\"\\\"\\\"\\n\",\n \"with open(\\\"mmlu_high_school_geography.yaml\\\", \\\"w\\\") as f:\\n\",\n \" f.write(YAML_mmlu_geo_string)\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"metadata\": {\n \"id\": \"jyKOfCsKb-xy\"\n },\n \"outputs\": [],\n \"source\": \"# !accelerate launch --no_python\\n%env LMEVAL_LOG_LEVEL=DEBUG\\n!lm_eval \\\\\\n --model hf \\\\\\n --model_args pretrained=EleutherAI/pythia-2.8b \\\\\\n --include_path ./ \\\\\\n --tasks demo_mmlu_high_school_geography \\\\\\n --limit 10 \\\\\\n --output output/mmlu_high_school_geography/ \\\\\\n --log_samples\"\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {\n \"id\": \"jyKOfCsKb-xy\"\n },\n \"source\": [\n \"We could also evaluate this task in a different way. For example, instead of observing the loglikelihood of the letters, we can instead evaluate on the choices themselves as the continuation. This is done by simply changing `doc_to_choice` from a list of letters to the corresponding `choices` field from the HF dataset. We write `\\\"{{choices}}\\\"` so that the string field is interpreted as jinja string that acquires the list from the HF dataset directly.\\n\",\n \"\\n\",\n \"Another convenient feature here is since we're only modifying the `doc_to_choice` and the rest of config is the same as the task above, we can use the above configuration as a template by using `include: mmlu_high_school_geography.yaml` to load the config from that file. We'll need to add a unique task name as to not colide with the existing yaml config we're including. For this case we'll simply name this one `mmlu_high_school_geography_continuation`. `doc_to_text` is added here just for sake of clarity.\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": 9,\n \"metadata\": {\n \"id\": \"lqElwU54TaK-\"\n },\n \"outputs\": [],\n \"source\": [\n \"YAML_mmlu_geo_string = \\\"\\\"\\\"\\n\",\n \"include: mmlu_high_school_geography.yaml\\n\",\n \"task: demo_mmlu_high_school_geography_continuation\\n\",\n \"doc_to_text: \\\"{{question.strip()}}\\\\nA. {{choices[0]}}\\\\nB. {{choices[1]}}\\\\nC. {{choices[2]}}\\\\nD. {{choices[3]}}\\\\nAnswer:\\\"\\n\",\n \"doc_to_choice: \\\"{{choices}}\\\"\\n\",\n \"\\\"\\\"\\\"\\n\",\n \"with open(\\\"mmlu_high_school_geography_continuation.yaml\\\", \\\"w\\\") as f:\\n\",\n \" f.write(YAML_mmlu_geo_string)\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"metadata\": {\n \"id\": \"-_CVnDirdy7j\"\n },\n \"outputs\": [],\n \"source\": \"# !accelerate launch --no_python\\n%env LMEVAL_LOG_LEVEL=DEBUG\\n!lm_eval \\\\\\n --model hf \\\\\\n --model_args pretrained=EleutherAI/pythia-2.8b \\\\\\n --include_path ./ \\\\\\n --tasks demo_mmlu_high_school_geography_continuation \\\\\\n --limit 10 \\\\\\n --output output/mmlu_high_school_geography_continuation/ \\\\\\n --log_samples\"\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {\n \"id\": \"-_CVnDirdy7j\"\n },\n \"source\": [\n \"If we take a look at the samples, we can see that it is in fact evaluating the continuation based on the choices rather than the letters.\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": 11,\n \"metadata\": {\n \"id\": \"duBDqC6PAdjL\"\n },\n \"outputs\": [\n {\n \"data\": {\n \"application/javascript\": \"\\n ((filepath) => {{\\n if (!google.colab.kernel.accessAllowed) {{\\n return;\\n }}\\n google.colab.files.view(filepath);\\n }})(\\\"/content/output/mmlu_high_school_geography_continuation/pretrained__EleutherAI__pythia-2.8b_demo_mmlu_high_school_geography_continuation.jsonl\\\")\",\n \"text/plain\": [\n \"\"\n ]\n },\n \"metadata\": {},\n \"output_type\": \"display_data\"\n }\n ],\n \"source\": [\n \"from google.colab import files\\n\",\n \"\\n\",\n \"\\n\",\n \"files.view(\\n\",\n \" \\\"output/mmlu_high_school_geography_continuation/pretrained__EleutherAI__pythia-2.8b_demo_mmlu_high_school_geography_continuation.jsonl\\\"\\n\",\n \")\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {\n \"id\": \"6p0-KPwAgK5j\"\n },\n \"source\": [\n \"## Closer Look at YAML Fields\\n\",\n \"\\n\",\n \"To prepare a task we can simply fill in a YAML config with the relevant information.\\n\",\n \"\\n\",\n \"`output_type`\\n\",\n \"The current provided evaluation types comprise of the following:\\n\",\n \"1. `loglikelihood`: Evaluates the loglikelihood of a continuation, conditioned on some input string.\\n\",\n \"2. `loglikelihood_rolling`: evaluate the loglikelihood of producing a string, conditioned on the empty string. (Used for perplexity evaluations)\\n\",\n \"3. `multiple_choice`: Evaluates loglikelihood among the a number of choices predicted by the model.\\n\",\n \"4. `greedy_until`: Model outputs greedy generation (can be configured to to use beam search and other generation-related parameters)\\n\",\n \"\\n\",\n \"The core prompt revolves around 3 fields.\\n\",\n \"1. `doc_to_text`: Denotes the prompt template that will be used as input to the model.\\n\",\n \"2. `doc_to_choice`: Available choices that will be used as continuation for the model. This is used when the `output_type` is `multiple_choice`, and otherwise can be left as `None`.\\n\",\n \"3. `doc_to_target`: When `output_type` is `multiple_choice`, this can be an index that corresponds to the correct answer, or the answer string itself (must be a subset of `doc_to_choice`). For other tasks, this is expected to be a string. You can fill this field with a feature name from the HF dataset so long as the resulting feature follows the conditioned described.\\n\",\n \"\\n\",\n \"These three fields can be expressed as strings, column names from the source dataset, or as Jinja2 templates that can use fields from the source dataset as variables.\\n\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {\n \"id\": \"6p0-KPwAgK5j\"\n },\n \"source\": [\n \"## What if Jinja is not Sufficient?\\n\",\n \"\\n\",\n \"There can be times where the Jinja2 templating language is not enough to make the prompt we had in mind. There are a few ways to circumvent this limitation:\\n\",\n \"\\n\",\n \"1. Use `!function` operator for the prompt-related fields to pass a python function that takes as input the dataset row, and will output the prompt template component.\\n\",\n \"2. Perform a transformation on the dataset beforehand.\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {},\n \"source\": [\n \"Below, we show an example of using `!function` to create `doc_to_text` from a python function:\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": 12,\n \"metadata\": {\n \"colab\": {\n \"base_uri\": \"https://localhost:8080/\"\n },\n \"id\": \"DYZ5c0JhR1lJ\",\n \"outputId\": \"ca945235-fb9e-4f17-8bfa-78e7d6ec1490\"\n },\n \"outputs\": [\n {\n \"name\": \"stdout\",\n \"output_type\": \"stream\",\n \"text\": [\n \"2023-11-29:11:59:08,312 INFO [utils.py:160] NumExpr defaulting to 2 threads.\\n\",\n \"2023-11-29 11:59:09.348327: E tensorflow/compiler/xla/stream_executor/cuda/cuda_dnn.cc:9342] Unable to register cuDNN factory: Attempting to register factory for plugin cuDNN when one has already been registered\\n\",\n \"2023-11-29 11:59:09.348387: E tensorflow/compiler/xla/stream_executor/cuda/cuda_fft.cc:609] Unable to register cuFFT factory: Attempting to register factory for plugin cuFFT when one has already been registered\\n\",\n \"2023-11-29 11:59:09.348421: E tensorflow/compiler/xla/stream_executor/cuda/cuda_blas.cc:1518] Unable to register cuBLAS factory: Attempting to register factory for plugin cuBLAS when one has already been registered\\n\",\n \"2023-11-29 11:59:10.573752: W tensorflow/compiler/tf2tensorrt/utils/py_utils.cc:38] TF-TRT Warning: Could not find TensorRT\\n\",\n \"2023-11-29:11:59:14,044 INFO [__main__.py:132] Verbosity set to INFO\\n\",\n \"2023-11-29:11:59:23,654 WARNING [__main__.py:138] --limit SHOULD ONLY BE USED FOR TESTING.REAL METRICS SHOULD NOT BE COMPUTED USING LIMIT.\\n\",\n \"2023-11-29:11:59:23,654 INFO [__main__.py:143] Including path: ./\\n\",\n \"2023-11-29:11:59:23,678 INFO [__main__.py:205] Selected Tasks: ['demo_mmlu_high_school_geography_function_prompt']\\n\",\n \"2023-11-29:11:59:23,679 WARNING [evaluator.py:93] generation_kwargs specified through cli, these settings will be used over set parameters in yaml tasks.\\n\",\n \"2023-11-29:11:59:23,708 INFO [huggingface.py:120] Using device 'cuda'\\n\",\n \"2023-11-29:11:59:44,516 INFO [task.py:355] Building contexts for task on rank 0...\\n\",\n \"2023-11-29:11:59:44,524 INFO [evaluator.py:319] Running loglikelihood requests\\n\",\n \"100% 40/40 [00:02<00:00, 15.41it/s]\\n\",\n \"fatal: not a git repository (or any of the parent directories): .git\\n\",\n \"hf (pretrained=EleutherAI/pythia-2.8b), gen_kwargs: (), limit: 10.0, num_fewshot: None, batch_size: 1\\n\",\n \"| Tasks |Version|Filter|n-shot| Metric |Value| |Stderr|\\n\",\n \"|-----------------------------------------------|-------|------|-----:|--------|----:|---|-----:|\\n\",\n \"|demo_mmlu_high_school_geography_function_prompt|Yaml |none | 0|acc | 0.1|± |0.1000|\\n\",\n \"| | |none | 0|acc_norm| 0.2|± |0.1333|\\n\",\n \"\\n\"\n ]\n }\n ],\n \"source\": [\n \"YAML_mmlu_geo_string = \\\"\\\"\\\"\\n\",\n \"include: mmlu_high_school_geography.yaml\\n\",\n \"task: demo_mmlu_high_school_geography_function_prompt\\n\",\n \"doc_to_text: !function utils.doc_to_text\\n\",\n \"doc_to_choice: \\\"{{choices}}\\\"\\n\",\n \"\\\"\\\"\\\"\\n\",\n \"with open(\\\"demo_mmlu_high_school_geography_function_prompt.yaml\\\", \\\"w\\\") as f:\\n\",\n \" f.write(YAML_mmlu_geo_string)\\n\",\n \"\\n\",\n \"DOC_TO_TEXT = \\\"\\\"\\\"\\n\",\n \"def doc_to_text(x):\\n\",\n \" question = x[\\\"question\\\"].strip()\\n\",\n \" choices = x[\\\"choices\\\"]\\n\",\n \" option_a = choices[0]\\n\",\n \" option_b = choices[1]\\n\",\n \" option_c = choices[2]\\n\",\n \" option_d = choices[3]\\n\",\n \" return f\\\"{question}\\\\\\\\nA. {option_a}\\\\\\\\nB. {option_b}\\\\\\\\nC. {option_c}\\\\\\\\nD. {option_d}\\\\\\\\nAnswer:\\\"\\n\",\n \"\\\"\\\"\\\"\\n\",\n \"with open(\\\"utils.py\\\", \\\"w\\\") as f:\\n\",\n \" f.write(DOC_TO_TEXT)\\n\",\n \"\\n\",\n \"!lm_eval \\\\\\n\",\n \" --model hf \\\\\\n\",\n \" --model_args pretrained=EleutherAI/pythia-2.8b \\\\\\n\",\n \" --include_path ./ \\\\\\n\",\n \" --tasks demo_mmlu_high_school_geography_function_prompt \\\\\\n\",\n \" --limit 10 \\\\\\n\",\n \" --output output/demo_mmlu_high_school_geography_function_prompt/ \\\\\\n\",\n \" --log_samples\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {},\n \"source\": [\n \"Next, we'll also show how to do this via preprocessing the dataset as necessary using the `process_docs` config field:\\n\",\n \"\\n\",\n \"We will write a function that will modify each document in our evaluation dataset's split to add a field that is suitable for us to use in `doc_to_text`.\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"metadata\": {},\n \"outputs\": [],\n \"source\": [\n \"YAML_mmlu_geo_string = \\\"\\\"\\\"\\n\",\n \"include: mmlu_high_school_geography.yaml\\n\",\n \"task: demo_mmlu_high_school_geography_function_prompt_2\\n\",\n \"process_docs: !function utils_process_docs.process_docs\\n\",\n \"doc_to_text: \\\"{{input}}\\\"\\n\",\n \"doc_to_choice: \\\"{{choices}}\\\"\\n\",\n \"\\\"\\\"\\\"\\n\",\n \"with open(\\\"demo_mmlu_high_school_geography_process_docs.yaml\\\", \\\"w\\\") as f:\\n\",\n \" f.write(YAML_mmlu_geo_string)\\n\",\n \"\\n\",\n \"DOC_TO_TEXT = \\\"\\\"\\\"\\n\",\n \"def process_docs(dataset):\\n\",\n \" def _process_doc(x):\\n\",\n \" question = x[\\\"question\\\"].strip()\\n\",\n \" choices = x[\\\"choices\\\"]\\n\",\n \" option_a = choices[0]\\n\",\n \" option_b = choices[1]\\n\",\n \" option_c = choices[2]\\n\",\n \" option_d = choices[3]\\n\",\n \" doc[\\\"input\\\"] = f\\\"{question}\\\\\\\\nA. {option_a}\\\\\\\\nB. {option_b}\\\\\\\\nC. {option_c}\\\\\\\\nD. {option_d}\\\\\\\\nAnswer:\\\"\\n\",\n \" return out_doc\\n\",\n \"\\n\",\n \" return dataset.map(_process_doc)\\n\",\n \"\\\"\\\"\\\"\\n\",\n \"\\n\",\n \"with open(\\\"utils_process_docs.py\\\", \\\"w\\\") as f:\\n\",\n \" f.write(DOC_TO_TEXT)\\n\",\n \"\\n\",\n \"!lm_eval \\\\\\n\",\n \" --model hf \\\\\\n\",\n \" --model_args pretrained=EleutherAI/pythia-2.8b \\\\\\n\",\n \" --include_path ./ \\\\\\n\",\n \" --tasks demo_mmlu_high_school_geography_function_prompt_2 \\\\\\n\",\n \" --limit 10 \\\\\\n\",\n \" --output output/demo_mmlu_high_school_geography_function_prompt_2/ \\\\\\n\",\n \" --log_samples\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {},\n \"source\": [\n \"We hope that this explainer gives you a sense of what can be done with and how to work with LM-Evaluation-Harnes v0.4.0 ! \\n\",\n \"\\n\",\n \"For more information, check out our documentation pages in the `docs/` folder, and if you have questions, please raise them in GitHub issues, or in #lm-thunderdome or #release-discussion on the EleutherAI discord server.\"\n ]\n }\n ],\n \"metadata\": {\n \"accelerator\": \"GPU\",\n \"colab\": {\n \"collapsed_sections\": [\n \"zAov81vTbL2K\"\n ],\n \"gpuType\": \"T4\",\n \"provenance\": []\n },\n \"kernelspec\": {\n \"display_name\": \"Python 3\",\n \"name\": \"python3\"\n },\n \"language_info\": {\n \"name\": \"python\"\n },\n \"widgets\": {\n \"application/vnd.jupyter.widget-state+json\": {\n \"state\": {\n \"46f521b73fd943c081c648fd873ebc0a\": {\n \"model_module\": \"@jupyter-widgets/controls\",\n \"model_module_version\": \"1.5.0\",\n \"model_name\": \"DescriptionStyleModel\",\n \"state\": {\n \"_model_module\": \"@jupyter-widgets/controls\",\n \"_model_module_version\": \"1.5.0\",\n \"_model_name\": \"DescriptionStyleModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/base\",\n \"_view_module_version\": \"1.2.0\",\n \"_view_name\": \"StyleView\",\n \"description_width\": \"\"\n }\n },\n \"48763b6233374554ae76035c0483066f\": {\n \"model_module\": \"@jupyter-widgets/controls\",\n \"model_module_version\": \"1.5.0\",\n \"model_name\": \"ProgressStyleModel\",\n \"state\": {\n \"_model_module\": \"@jupyter-widgets/controls\",\n \"_model_module_version\": \"1.5.0\",\n \"_model_name\": \"ProgressStyleModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/base\",\n \"_view_module_version\": \"1.2.0\",\n \"_view_name\": \"StyleView\",\n \"bar_color\": null,\n \"description_width\": \"\"\n }\n },\n \"4986a21eb560448fa79f4b25cde48951\": {\n \"model_module\": \"@jupyter-widgets/base\",\n \"model_module_version\": \"1.2.0\",\n \"model_name\": \"LayoutModel\",\n \"state\": {\n \"_model_module\": \"@jupyter-widgets/base\",\n \"_model_module_version\": \"1.2.0\",\n \"_model_name\": \"LayoutModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/base\",\n \"_view_module_version\": \"1.2.0\",\n \"_view_name\": \"LayoutView\",\n \"align_content\": null,\n \"align_items\": null,\n \"align_self\": null,\n \"border\": null,\n \"bottom\": null,\n \"display\": null,\n \"flex\": null,\n \"flex_flow\": null,\n \"grid_area\": null,\n \"grid_auto_columns\": null,\n \"grid_auto_flow\": null,\n \"grid_auto_rows\": null,\n \"grid_column\": null,\n \"grid_gap\": null,\n \"grid_row\": null,\n \"grid_template_areas\": null,\n \"grid_template_columns\": null,\n \"grid_template_rows\": null,\n \"height\": null,\n \"justify_content\": null,\n \"justify_items\": null,\n \"left\": null,\n \"margin\": null,\n \"max_height\": null,\n \"max_width\": null,\n \"min_height\": null,\n \"min_width\": null,\n \"object_fit\": null,\n \"object_position\": null,\n \"order\": null,\n \"overflow\": null,\n \"overflow_x\": null,\n \"overflow_y\": null,\n \"padding\": null,\n \"right\": null,\n \"top\": null,\n \"visibility\": null,\n \"width\": null\n }\n },\n \"6b2d90209ec14230b3d58a74ac9b83bf\": {\n \"model_module\": \"@jupyter-widgets/base\",\n \"model_module_version\": \"1.2.0\",\n \"model_name\": \"LayoutModel\",\n \"state\": {\n \"_model_module\": \"@jupyter-widgets/base\",\n \"_model_module_version\": \"1.2.0\",\n \"_model_name\": \"LayoutModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/base\",\n \"_view_module_version\": \"1.2.0\",\n \"_view_name\": \"LayoutView\",\n \"align_content\": null,\n \"align_items\": null,\n \"align_self\": null,\n \"border\": null,\n \"bottom\": null,\n \"display\": null,\n \"flex\": null,\n \"flex_flow\": null,\n \"grid_area\": null,\n \"grid_auto_columns\": null,\n \"grid_auto_flow\": null,\n \"grid_auto_rows\": null,\n \"grid_column\": null,\n \"grid_gap\": null,\n \"grid_row\": null,\n \"grid_template_areas\": null,\n \"grid_template_columns\": null,\n \"grid_template_rows\": null,\n \"height\": null,\n \"justify_content\": null,\n \"justify_items\": null,\n \"left\": null,\n \"margin\": null,\n \"max_height\": null,\n \"max_width\": null,\n \"min_height\": null,\n \"min_width\": null,\n \"object_fit\": null,\n \"object_position\": null,\n \"order\": null,\n \"overflow\": null,\n \"overflow_x\": null,\n \"overflow_y\": null,\n \"padding\": null,\n \"right\": null,\n \"top\": null,\n \"visibility\": null,\n \"width\": null\n }\n },\n \"7c5689bc13684db8a22681f41863dddd\": {\n \"model_module\": \"@jupyter-widgets/base\",\n \"model_module_version\": \"1.2.0\",\n \"model_name\": \"LayoutModel\",\n \"state\": {\n \"_model_module\": \"@jupyter-widgets/base\",\n \"_model_module_version\": \"1.2.0\",\n \"_model_name\": \"LayoutModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/base\",\n \"_view_module_version\": \"1.2.0\",\n \"_view_name\": \"LayoutView\",\n \"align_content\": null,\n \"align_items\": null,\n \"align_self\": null,\n \"border\": null,\n \"bottom\": null,\n \"display\": null,\n \"flex\": null,\n \"flex_flow\": null,\n \"grid_area\": null,\n \"grid_auto_columns\": null,\n \"grid_auto_flow\": null,\n \"grid_auto_rows\": null,\n \"grid_column\": null,\n \"grid_gap\": null,\n \"grid_row\": null,\n \"grid_template_areas\": null,\n \"grid_template_columns\": null,\n \"grid_template_rows\": null,\n \"height\": null,\n \"justify_content\": null,\n \"justify_items\": null,\n \"left\": null,\n \"margin\": null,\n \"max_height\": null,\n \"max_width\": null,\n \"min_height\": null,\n \"min_width\": null,\n \"object_fit\": null,\n \"object_position\": null,\n \"order\": null,\n \"overflow\": null,\n \"overflow_x\": null,\n \"overflow_y\": null,\n \"padding\": null,\n \"right\": null,\n \"top\": null,\n \"visibility\": null,\n \"width\": null\n }\n },\n \"a1d3a8aa016544a78e8821c8f6199e06\": {\n \"model_module\": \"@jupyter-widgets/controls\",\n \"model_module_version\": \"1.5.0\",\n \"model_name\": \"HBoxModel\",\n \"state\": {\n \"_dom_classes\": [],\n \"_model_module\": \"@jupyter-widgets/controls\",\n \"_model_module_version\": \"1.5.0\",\n \"_model_name\": \"HBoxModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/controls\",\n \"_view_module_version\": \"1.5.0\",\n \"_view_name\": \"HBoxView\",\n \"box_style\": \"\",\n \"children\": [\n \"IPY_MODEL_f61ed33fad754146bdd2ac9db1ba1c48\",\n \"IPY_MODEL_bfa0af6aeff344c6845e1080a878e92e\",\n \"IPY_MODEL_fd1ad9e0367d4004aae853b91c3a7617\"\n ],\n \"layout\": \"IPY_MODEL_6b2d90209ec14230b3d58a74ac9b83bf\"\n }\n },\n \"a73f357065d34d7baf0453ae4a8d75e2\": {\n \"model_module\": \"@jupyter-widgets/base\",\n \"model_module_version\": \"1.2.0\",\n \"model_name\": \"LayoutModel\",\n \"state\": {\n \"_model_module\": \"@jupyter-widgets/base\",\n \"_model_module_version\": \"1.2.0\",\n \"_model_name\": \"LayoutModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/base\",\n \"_view_module_version\": \"1.2.0\",\n \"_view_name\": \"LayoutView\",\n \"align_content\": null,\n \"align_items\": null,\n \"align_self\": null,\n \"border\": null,\n \"bottom\": null,\n \"display\": null,\n \"flex\": null,\n \"flex_flow\": null,\n \"grid_area\": null,\n \"grid_auto_columns\": null,\n \"grid_auto_flow\": null,\n \"grid_auto_rows\": null,\n \"grid_column\": null,\n \"grid_gap\": null,\n \"grid_row\": null,\n \"grid_template_areas\": null,\n \"grid_template_columns\": null,\n \"grid_template_rows\": null,\n \"height\": null,\n \"justify_content\": null,\n \"justify_items\": null,\n \"left\": null,\n \"margin\": null,\n \"max_height\": null,\n \"max_width\": null,\n \"min_height\": null,\n \"min_width\": null,\n \"object_fit\": null,\n \"object_position\": null,\n \"order\": null,\n \"overflow\": null,\n \"overflow_x\": null,\n \"overflow_y\": null,\n \"padding\": null,\n \"right\": null,\n \"top\": null,\n \"visibility\": null,\n \"width\": null\n }\n },\n \"aed3acd2f2d74003b44079c333a0698e\": {\n \"model_module\": \"@jupyter-widgets/controls\",\n \"model_module_version\": \"1.5.0\",\n \"model_name\": \"DescriptionStyleModel\",\n \"state\": {\n \"_model_module\": \"@jupyter-widgets/controls\",\n \"_model_module_version\": \"1.5.0\",\n \"_model_name\": \"DescriptionStyleModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/base\",\n \"_view_module_version\": \"1.2.0\",\n \"_view_name\": \"StyleView\",\n \"description_width\": \"\"\n }\n },\n \"bfa0af6aeff344c6845e1080a878e92e\": {\n \"model_module\": \"@jupyter-widgets/controls\",\n \"model_module_version\": \"1.5.0\",\n \"model_name\": \"FloatProgressModel\",\n \"state\": {\n \"_dom_classes\": [],\n \"_model_module\": \"@jupyter-widgets/controls\",\n \"_model_module_version\": \"1.5.0\",\n \"_model_name\": \"FloatProgressModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/controls\",\n \"_view_module_version\": \"1.5.0\",\n \"_view_name\": \"ProgressView\",\n \"bar_style\": \"success\",\n \"description\": \"\",\n \"description_tooltip\": null,\n \"layout\": \"IPY_MODEL_7c5689bc13684db8a22681f41863dddd\",\n \"max\": 5669,\n \"min\": 0,\n \"orientation\": \"horizontal\",\n \"style\": \"IPY_MODEL_48763b6233374554ae76035c0483066f\",\n \"value\": 5669\n }\n },\n \"f61ed33fad754146bdd2ac9db1ba1c48\": {\n \"model_module\": \"@jupyter-widgets/controls\",\n \"model_module_version\": \"1.5.0\",\n \"model_name\": \"HTMLModel\",\n \"state\": {\n \"_dom_classes\": [],\n \"_model_module\": \"@jupyter-widgets/controls\",\n \"_model_module_version\": \"1.5.0\",\n \"_model_name\": \"HTMLModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/controls\",\n \"_view_module_version\": \"1.5.0\",\n \"_view_name\": \"HTMLView\",\n \"description\": \"\",\n \"description_tooltip\": null,\n \"layout\": \"IPY_MODEL_a73f357065d34d7baf0453ae4a8d75e2\",\n \"placeholder\": \"​\",\n \"style\": \"IPY_MODEL_46f521b73fd943c081c648fd873ebc0a\",\n \"value\": \"Downloading builder script: 100%\"\n }\n },\n \"fd1ad9e0367d4004aae853b91c3a7617\": {\n \"model_module\": \"@jupyter-widgets/controls\",\n \"model_module_version\": \"1.5.0\",\n \"model_name\": \"HTMLModel\",\n \"state\": {\n \"_dom_classes\": [],\n \"_model_module\": \"@jupyter-widgets/controls\",\n \"_model_module_version\": \"1.5.0\",\n \"_model_name\": \"HTMLModel\",\n \"_view_count\": null,\n \"_view_module\": \"@jupyter-widgets/controls\",\n \"_view_module_version\": \"1.5.0\",\n \"_view_name\": \"HTMLView\",\n \"description\": \"\",\n \"description_tooltip\": null,\n \"layout\": \"IPY_MODEL_4986a21eb560448fa79f4b25cde48951\",\n \"placeholder\": \"​\",\n \"style\": \"IPY_MODEL_aed3acd2f2d74003b44079c333a0698e\",\n \"value\": \" 5.67k/5.67k [00:00<00:00, 205kB/s]\"\n }\n }\n },\n \"version_major\": 2,\n \"version_minor\": 0\n }\n }\n },\n \"nbformat\": 4,\n \"nbformat_minor\": 0\n}\n" }, { "path": "examples/transformer-lens.py", "content": "import warnings\n\nimport torch\nimport torch.nn as nn\nfrom transformer_lens import HookedTransformer\nfrom transformers import AutoConfig\n\nfrom lm_eval import evaluator\nfrom lm_eval.models.huggingface import HFLM\n\n\ndef evaluate_lm_eval(lens_model: HookedTransformer, tasks: list[str], **kwargs):\n class HFLikeModelAdapter(nn.Module):\n \"\"\"Adapts HookedTransformer to match the HuggingFace interface expected by lm-eval\"\"\"\n\n def __init__(self, model: HookedTransformer):\n super().__init__()\n self.model = model\n self.tokenizer = model.tokenizer\n self.config = AutoConfig.from_pretrained(model.cfg.tokenizer_name)\n self.device = model.cfg.device\n self.tie_weights = lambda: self\n\n def forward(self, input_ids=None, attention_mask=None, **kwargs):\n output = self.model(input_ids, attention_mask=attention_mask, **kwargs)\n # Make sure output has the expected .logits attribute\n if not hasattr(output, \"logits\"):\n if isinstance(output, torch.Tensor):\n output.logits = output\n return output\n\n # Only delegate specific attributes we know we need\n def to(self, *args, **kwargs):\n return self.model.to(*args, **kwargs)\n\n def eval(self):\n self.model.eval()\n return self\n\n def train(self, mode=True):\n self.model.train(mode)\n return self\n\n model = HFLikeModelAdapter(lens_model)\n warnings.filterwarnings(\"ignore\", message=\"Failed to get model SHA for\")\n results = evaluator.simple_evaluate(\n model=HFLM(pretrained=model, tokenizer=model.tokenizer),\n tasks=tasks,\n verbosity=\"WARNING\",\n **kwargs,\n )\n return results\n\n\nif __name__ == \"__main__\":\n # Load base model\n model = HookedTransformer.from_pretrained(\"pythia-70m\")\n res = evaluate_lm_eval(model, tasks=[\"arc_easy\"])\n print(res[\"results\"])\n" }, { "path": "examples/visualize-wandb.ipynb", "content": "{\n \"cells\": [\n {\n \"cell_type\": \"markdown\",\n \"id\": \"fc477b96-adee-4829-a9d7-a5eb990df358\",\n \"metadata\": {},\n \"source\": [\n \"# Visualizing Results in Weights and Biases\\n\",\n \"\\n\",\n \"With the Weights and Biases integration, you can now spend more time extracting deeper insights into your evaluation results. The integration is designed to streamline the process of logging and visualizing experiment results using the Weights & Biases (W&B) platform.\\n\",\n \"\\n\",\n \"The integration provide functionalities\\n\",\n \"\\n\",\n \"- to automatically log the evaluation results,\\n\",\n \"- log the samples as W&B Tables for easy visualization,\\n\",\n \"- log the `results.json` file as an artifact for version control,\\n\",\n \"- log the `_eval_samples.json` file if the samples are logged,\\n\",\n \"- generate a comprehensive report for analysis and visualization with all the important metric,\\n\",\n \"- log task and cli configs,\\n\",\n \"- and more out of the box like the command used to run the evaluation, GPU/CPU counts, timestamp, etc.\\n\",\n \"\\n\",\n \"The integration is super easy to use with the eval harness. Let's see how!\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"id\": \"3851439a-bff4-41f2-bf21-1b3d8704913b\",\n \"metadata\": {\n \"scrolled\": true\n },\n \"outputs\": [],\n \"source\": [\n \"# Install this project if you did not already have it.\\n\",\n \"# This is all that is needed to be installed to start using Weights and Biases\\n\",\n \"\\n\",\n \"!pip -qq install -e ..[wandb]\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"id\": \"8507fd7e-3b99-4a92-89fa-9eaada74ba91\",\n \"metadata\": {},\n \"source\": [\n \"# Run the Eval Harness\\n\",\n \"\\n\",\n \"Run the eval harness as usual with a `wandb_args` flag. This flag is used to provide arguments for initializing a wandb run ([wandb.init](https://docs.wandb.ai/ref/python/init)) as comma separated string arguments.\\n\",\n \"\\n\",\n \"If `wandb_args` flag is used, the metrics and all other goodness will be automatically logged to Weights and Biases. In the stdout, you will find the link to the W&B run page as well as link to the generated report.\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"id\": \"eec5866e-f01e-42f8-8803-9d77472ef991\",\n \"metadata\": {},\n \"source\": [\n \"## Set your API Key\\n\",\n \"\\n\",\n \"Before you can use W&B, you need to authenticate your machine with an authentication key. Visit https://wandb.ai/authorize to get one.\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"id\": \"d824d163-71a9-4313-935d-f1d56397841c\",\n \"metadata\": {},\n \"outputs\": [],\n \"source\": [\n \"import wandb\\n\",\n \"\\n\",\n \"\\n\",\n \"wandb.login()\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"id\": \"124e4a34-1547-4bed-bc09-db012bacbda6\",\n \"metadata\": {},\n \"source\": [\n \"> Note that if you are using command line you can simply authenticate your machine by doing `wandb login` in your terminal. For more info check out the [documentation](https://docs.wandb.ai/quickstart#2-log-in-to-wb).\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"id\": \"abc6f6b6-179a-4aff-ada9-f380fb74df6e\",\n \"metadata\": {},\n \"source\": [\n \"## Run and log to W&B\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"id\": \"bd0a8130-a97b-451a-acd2-3f9885b88643\",\n \"metadata\": {},\n \"outputs\": [],\n \"source\": [\n \"!lm_eval \\\\\\n\",\n \" --model hf \\\\\\n\",\n \" --model_args pretrained=microsoft/phi-2,trust_remote_code=True \\\\\\n\",\n \" --tasks hellaswag,mmlu_abstract_algebra \\\\\\n\",\n \" --device cuda:0 \\\\\\n\",\n \" --batch_size 8 \\\\\\n\",\n \" --output_path output/phi-2 \\\\\\n\",\n \" --limit 10 \\\\\\n\",\n \" --wandb_args project=lm-eval-harness-integration \\\\\\n\",\n \" --log_samples\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"id\": \"e974cabdbe70b667\",\n \"metadata\": {},\n \"source\": []\n },\n {\n \"cell_type\": \"markdown\",\n \"id\": \"5178ca9445b844e4\",\n \"metadata\": {},\n \"source\": [\n \"W&B can also be initialized programmatically for use outside the CLI to parse and log the results.\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"id\": \"c6a421b2cf3ddac5\",\n \"metadata\": {},\n \"outputs\": [],\n \"source\": [\n \"import lm_eval\\n\",\n \"from lm_eval.loggers import WandbLogger\\n\",\n \"\\n\",\n \"\\n\",\n \"results = lm_eval.simple_evaluate(\\n\",\n \" model=\\\"hf\\\",\\n\",\n \" model_args=\\\"pretrained=microsoft/phi-2,trust_remote_code=True\\\",\\n\",\n \" tasks=\\\"hellaswag,mmlu_abstract_algebra\\\",\\n\",\n \" log_samples=True,\\n\",\n \")\\n\",\n \"\\n\",\n \"wandb_logger = WandbLogger(\\n\",\n \" project=\\\"lm-eval-harness-integration\\\", job_type=\\\"eval\\\"\\n\",\n \") # or empty if wandb.init(...) already called before\\n\",\n \"wandb_logger.post_init(results)\\n\",\n \"wandb_logger.log_eval_result()\\n\",\n \"wandb_logger.log_eval_samples(results[\\\"samples\\\"]) # if log_samples\"\n ]\n }\n ],\n \"metadata\": {\n \"kernelspec\": {\n \"display_name\": \"Python 3 (ipykernel)\",\n \"language\": \"python\",\n \"name\": \"python3\"\n },\n \"language_info\": {\n \"codemirror_mode\": {\n \"name\": \"ipython\",\n \"version\": 3\n },\n \"file_extension\": \".py\",\n \"mimetype\": \"text/x-python\",\n \"name\": \"python\",\n \"nbconvert_exporter\": \"python\",\n \"pygments_lexer\": \"ipython3\",\n \"version\": \"3.10.12\"\n }\n },\n \"nbformat\": 4,\n \"nbformat_minor\": 5\n}\n" }, { "path": "examples/visualize-zeno.ipynb", "content": "{\n \"cells\": [\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {},\n \"source\": [\n \"# Visualizing Results in Zeno\\n\",\n \"\\n\",\n \"Benchmarking your models is the first step towards making sure your model performs well.\\n\",\n \"However, looking at the data behind the benchmark, slicing the data into subsets, and comparing models on individual instances can help you even more in evaluating and quantifying the behavior of your AI system.\\n\",\n \"\\n\",\n \"All of this can be done in [Zeno](https://zenoml.com)!\\n\",\n \"Zeno is super easy to use with the eval harness, let's explore how you can easily upload and visualize your eval results.\\n\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"metadata\": {},\n \"outputs\": [],\n \"source\": [\n \"# Install this project if you did not already do that. This is all that needs to be installed for you to be able to visualize your data in Zeno!\\n\",\n \"!pip install -e ..\\n\",\n \"!pip install -e ..[zeno]\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {},\n \"source\": [\n \"# Run the Eval Harness\\n\",\n \"\\n\",\n \"To visualize the results, run the eval harness with the `log_samples` and `output_path` flags. We expect `output_path` to contain multiple folders that represent individual model names. You can thus run your evaluation on any number of tasks and models and upload all of the results as projects on Zeno.\\n\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"metadata\": {},\n \"outputs\": [],\n \"source\": [\n \"!lm_eval \\\\\\n\",\n \" --model hf \\\\\\n\",\n \" --model_args pretrained=EleutherAI/gpt-neo-2.7B \\\\\\n\",\n \" --tasks hellaswag,wikitext \\\\\\n\",\n \" --batch_size 8 \\\\\\n\",\n \" --device mps \\\\\\n\",\n \" --log_samples \\\\\\n\",\n \" --output_path output/gpt-neo-2.7B \\\\\\n\",\n \" --limit 10\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {},\n \"source\": [\n \"# Set your API Key\\n\",\n \"\\n\",\n \"This is so you can be authenticated with Zeno.\\n\",\n \"If you don't already have a Zeno account, first create an account on [Zeno Hub](https://hub.zenoml.com).\\n\",\n \"After logging in to Zeno Hub, generate your API key by clicking on your profile at the bottom left to navigate to your account page.\\n\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"metadata\": {},\n \"outputs\": [],\n \"source\": [\n \"%env ZENO_API_KEY=YOUR_API_KEY\"\n ]\n },\n {\n \"cell_type\": \"markdown\",\n \"metadata\": {},\n \"source\": [\n \"# Visualize Eval Results\\n\",\n \"\\n\",\n \"You can now use the `zeno_visualize` script to upload the results to Zeno.\\n\",\n \"\\n\",\n \"This will use all subfolders in `data_path` as different models and upload all tasks within these model folders to Zeno. If you run the eval harness on multiple tasks, the `project_name` will be used as a prefix and one project will be created per task.\\n\"\n ]\n },\n {\n \"cell_type\": \"code\",\n \"execution_count\": null,\n \"metadata\": {},\n \"outputs\": [],\n \"source\": [\n \"!python ../scripts/zeno_visualize.py --data_path output --project_name \\\"Zeno Upload Test\\\"\"\n ]\n }\n ],\n \"metadata\": {\n \"kernelspec\": {\n \"display_name\": \"zeno_projects\",\n \"language\": \"python\",\n \"name\": \"python3\"\n },\n \"language_info\": {\n \"codemirror_mode\": {\n \"name\": \"ipython\",\n \"version\": 3\n },\n \"file_extension\": \".py\",\n \"mimetype\": \"text/x-python\",\n \"name\": \"python\",\n \"nbconvert_exporter\": \"python\",\n \"pygments_lexer\": \"ipython3\",\n \"version\": \"3.10.11\"\n }\n },\n \"nbformat\": 4,\n \"nbformat_minor\": 2\n}\n" }, { "path": "ignore.txt", "content": "ROUGE\nrouge\nnin\nmaka\nmor\nte\nond\nextraversion\n" }, { "path": "lm_eval/__init__.py", "content": "import importlib.metadata\nimport logging\nimport os\nfrom importlib.util import find_spec\n\n\n__version__ = importlib.metadata.version(\"lm_eval\")\n\n\n# Enable high-performance transfers\nos.environ.setdefault(\"HF_XET_HIGH_PERFORMANCE\", \"1\") # huggingface_hub >= 0.32.0\nif find_spec(\"hf_transfer\") is not None:\n os.environ.setdefault(\"HF_HUB_ENABLE_HF_TRANSFER\", \"1\") # legacy hf_transfer\n\n\n# Lazy-load .evaluator module to improve CLI startup\ndef __getattr__(name):\n if name == \"evaluate\":\n from .evaluator import evaluate\n\n return evaluate\n elif name == \"simple_evaluate\":\n from .evaluator import simple_evaluate\n\n return simple_evaluate\n raise AttributeError(f\"module {__name__!r} has no attribute {name!r}\")\n\n\n__all__ = [\"evaluate\", \"simple_evaluate\", \"__version__\"]\n" }, { "path": "lm_eval/__main__.py", "content": "from lm_eval._cli import HarnessCLI\nfrom lm_eval.utils import setup_logging\n\n\ndef cli_evaluate() -> None:\n \"\"\"Main CLI entry point.\"\"\"\n setup_logging()\n parser = HarnessCLI()\n args = parser.parse_args()\n parser.execute(args)\n\n\nif __name__ == \"__main__\":\n cli_evaluate()\n" }, { "path": "lm_eval/_cli/__init__.py", "content": "\"\"\"\nCLI subcommands to run from the terminal.\n\"\"\"\n\nfrom .harness import HarnessCLI\n\n\n__all__ = [\"HarnessCLI\"]\n" }, { "path": "lm_eval/_cli/harness.py", "content": "import argparse\nimport sys\nimport textwrap\n\nfrom lm_eval._cli.ls import List\nfrom lm_eval._cli.run import Run\nfrom lm_eval._cli.validate import Validate\n\n\nclass HarnessCLI:\n \"\"\"Main CLI parser that manages all subcommands.\"\"\"\n\n def __init__(self):\n self._parser = argparse.ArgumentParser(\n prog=\"lm-eval\",\n description=\"Language Model Evaluation Harness\",\n epilog=textwrap.dedent(\"\"\"\n quick start:\n # Basic evaluation\n lm-eval run --model hf --model_args pretrained=gpt2 --tasks hellaswag\n\n # List available tasks\n lm-eval ls tasks\n\n # Validate task configurations\n lm-eval validate --tasks hellaswag,arc_easy\n\n legacy compatibility:\n The harness maintains backward compatibility with the original interface.\n If no command is specified, 'run' is automatically inserted:\n\n lm-eval --model hf --tasks hellaswag # Equivalent to 'lm-eval run --model hf --tasks hellaswag'\n\n For documentation, visit: https://github.com/EleutherAI/lm-evaluation-harness/blob/main/docs/interface.md\n \"\"\"),\n formatter_class=argparse.RawDescriptionHelpFormatter,\n )\n self._parser.set_defaults(func=lambda args: self._parser.print_help())\n self._subparsers = self._parser.add_subparsers(\n dest=\"command\", help=\"Available commands\", metavar=\"COMMAND\"\n )\n Run.create(self._subparsers)\n List.create(self._subparsers)\n Validate.create(self._subparsers)\n\n def parse_args(self) -> argparse.Namespace:\n \"\"\"Parse arguments using the main parser.\"\"\"\n if len(sys.argv) > 2 and sys.argv[1] not in self._subparsers.choices:\n # Backward compatibility: arguments provided but no valid subcommand - insert 'run'\n # TODO: add warning\n sys.argv.insert(1, \"run\")\n elif len(sys.argv) == 2 and \"run\" in sys.argv:\n # if only 'run' is specified, ensure it is treated as a subcommand\n self._subparsers.choices[\"run\"].print_help()\n sys.exit(0)\n return self._parser.parse_args()\n\n def execute(self, args: argparse.Namespace) -> None:\n \"\"\"Main execution method that handles subcommands and legacy support.\"\"\"\n args.func(args)\n" }, { "path": "lm_eval/_cli/ls.py", "content": "import argparse\nimport textwrap\n\nfrom lm_eval._cli.subcommand import SubCommand\n\n\nclass List(SubCommand):\n \"\"\"Command for listing available tasks.\"\"\"\n\n def __init__(self, subparsers: argparse._SubParsersAction, *args, **kwargs):\n # Create and configure the parser\n super().__init__(*args, **kwargs)\n self._parser = subparsers.add_parser(\n \"ls\",\n help=\"List available tasks, groups, subtasks, or tags\",\n description=\"List available tasks, groups, subtasks, or tags from the evaluation harness.\",\n usage=\"lm-eval list [tasks|groups|subtasks|tags] [--include_path DIR]\",\n epilog=textwrap.dedent(\"\"\"\n examples:\n # List all available tasks (includes groups, subtasks, and tags)\n $ lm-eval ls tasks\n\n # List only task groups (like 'mmlu', 'glue', 'superglue')\n $ lm-eval ls groups\n\n # List only individual subtasks (like 'mmlu_abstract_algebra')\n $ lm-eval ls subtasks\n\n # Include external task definitions\n $ lm-eval ls tasks --include_path /path/to/external/tasks\n\n # List tasks from multiple external paths\n $ lm-eval ls tasks --include_path \"/path/to/tasks1:/path/to/tasks2\"\n\n organization:\n • Groups: Collections of tasks with aggregated metric across subtasks (e.g., 'mmlu')\n • Subtasks: Individual evaluation tasks (e.g., 'mmlu_anatomy', 'hellaswag')\n • Tags: Similar to groups but no aggregate metric (e.g., 'reasoning', 'knowledge', 'language')\n • External Tasks: Custom tasks defined in external directories\n\n evaluation usage:\n After listing tasks, use them with the run command!\n\n For more information tasks configs are defined in https://github.com/EleutherAI/lm-evaluation-harness/tree/main/lm_eval/tasks\n \"\"\"),\n formatter_class=argparse.RawDescriptionHelpFormatter,\n )\n self._add_args()\n self._parser.set_defaults(func=self._execute)\n\n def _add_args(self) -> None:\n self._parser.add_argument(\n \"what\",\n choices=[\"tasks\", \"groups\", \"subtasks\", \"tags\"],\n nargs=\"?\",\n help=\"What to list: tasks (all), groups, subtasks, or tags\",\n )\n self._parser.add_argument(\n \"--include_path\",\n type=str,\n default=None,\n metavar=\"DIR\",\n help=\"Additional path to include if there are external tasks.\",\n )\n\n def _execute(self, args: argparse.Namespace) -> None:\n \"\"\"Execute the list command.\"\"\"\n from lm_eval.tasks import TaskManager\n\n task_manager = TaskManager(include_path=args.include_path)\n\n if args.what == \"tasks\":\n print(task_manager.list_all_tasks())\n elif args.what == \"groups\":\n print(task_manager.list_all_tasks(list_subtasks=False, list_tags=False))\n elif args.what == \"subtasks\":\n print(task_manager.list_all_tasks(list_groups=False, list_tags=False))\n elif args.what == \"tags\":\n print(task_manager.list_all_tasks(list_groups=False, list_subtasks=False))\n elif args.what is None:\n self._parser.print_help()\n" }, { "path": "lm_eval/_cli/run.py", "content": "import argparse\nimport json\nimport logging\nimport os\nimport textwrap\nfrom functools import partial\n\nfrom lm_eval._cli.subcommand import SubCommand\nfrom lm_eval._cli.utils import (\n MergeDictAction,\n SplitArgs,\n _int_or_none_list_arg_type,\n request_caching_arg_to_dict,\n try_parse_json,\n)\n\n\nclass Run(SubCommand):\n \"\"\"Command for running language model evaluation.\"\"\"\n\n def __init__(self, subparsers: argparse._SubParsersAction, *args, **kwargs):\n super().__init__(*args, **kwargs)\n self._parser = subparsers.add_parser(\n \"run\",\n help=\"Run the evaluation harness on specified tasks\",\n description=\"Evaluate language models on various benchmarks and tasks.\",\n usage=\"lm-eval run --model --tasks --model_args [options]\",\n epilog=textwrap.dedent(\"\"\"\n examples:\n # Basic evaluation with HuggingFace model\n $ lm-eval run --model hf --model_args pretrained=gpt2 dtype=float32 --tasks hellaswag\n\n # Evaluate on multiple tasks with few-shot examples\n $ lm-eval run --model vllm --model_args pretrained=EleutherAI/gpt-j-6B --tasks arc_easy arc_challenge --num_fewshot 5\n\n # Evaluation with custom generation parameters\n $ lm-eval run --model hf --model_args pretrained=gpt2 --tasks lambada --gen_kwargs temperature=0.8 top_p=0.95 'stop=[\"\\\\n\\\\n\"]'\n\n # Use configuration file\n $ lm-eval run --config my_config.yaml --tasks mmlu\n\n For more information, see: https://github.com/EleutherAI/lm-evaluation-harness\n \"\"\"),\n formatter_class=argparse.RawDescriptionHelpFormatter,\n )\n self._add_args()\n self._parser.set_defaults(func=self._execute)\n\n def _add_args(self) -> None:\n self._parser = self._parser\n\n # Defaults are set in config/evaluate_config.py\n config_group = self._parser.add_argument_group(\"configuration\")\n config_group.add_argument(\n \"--config\",\n \"-C\",\n default=None,\n type=str,\n metavar=\"\",\n help=\"Set initial arguments from YAML config\",\n )\n\n # Model and Tasks\n model_group = self._parser.add_argument_group(\"model and tasks\")\n model_group.add_argument(\n \"--tasks\",\n \"-t\",\n default=None,\n nargs=\"+\",\n metavar=\"\",\n action=SplitArgs,\n help=textwrap.dedent(\"\"\"\n Space (or comma-separated) list of task names or groupings.\n Use 'lm-eval list tasks' to see all available tasks.\n \"\"\").strip(),\n )\n model_group.add_argument(\n \"--model\",\n \"-M\",\n type=str,\n default=None,\n metavar=\"\",\n help=\"Model name (default: hf)\",\n )\n model_group.add_argument(\n \"--model_args\",\n \"-a\",\n default=None,\n nargs=\"+\",\n action=MergeDictAction,\n metavar=\"\",\n help=\"Model arguments as 'key=val,key2=val2' or `key=val` `key2=val2`\",\n )\n model_group.add_argument(\n \"--apply_chat_template\",\n type=str,\n nargs=\"?\",\n const=True,\n default=argparse.SUPPRESS,\n metavar=\"