| # Kimi-Audio-Evalkit |
|
|
| [English Version](README.md) |
|
|
| ## 介绍 |
|
|
| Kimi-Audio-Evalkit是一个为音频大模型评测设计的评测框架，基于Kimi-Audio-Evalkit，你可以快速实现自己的模型或数据集，并公平的与其他开源模型进行比对。 |
|
|
| 我们的工作[Kimi-Audio](https://github.com/MoonshotAI/Kimi-Audio-Evalkit)基于此框架评测。 |
|
|
| [Leaderboard](./LEADERBOARD.md)是目前的评测结果。 |
|
|
| ## 开始评测 |
|
|
| ### Step1: 获取代码 |
|
|
| ```bash |
| git clone https://github.com/MoonshotAI/Kimi-Audio-Evalkit.git |
| cd Kimi-Audio-Evalkit |
| git submodule update --init --recursive |
| ``` |
|
|
| ### Step2: 准备环境 |
|
|
| 你可以直接使用我们预先build好的镜像，如果你需要更新镜像环境，可以修改Dockerfile后重新构造 |
| ```bash |
| docker pull moonshotai/almevalkit:v0.4 |
| ``` |
| 通常情况你需要mount本地目录，并将其作为工作目录，以便评测结果在容器退出后仍然存在 |
| ```bash |
| docker run -it -v $(pwd):/app moonshotai/almevalkit:v0.4 bash |
| ``` |
|
|
| ### Step3: 获取数据集 |
|
|
| ALMEvalKit所用的大部分数据集都可以通过我们附带的工具下载，有些数据集不能全自动执行，具体请参阅[下载数据集](./data/README.md) |
| 对位于huggingface的数据集，我们很快将提供更直接的使用方式，请关注更新。 |
|
|
| ### Step4: 配置config.yaml |
| 你也许需要填写根目录下的config.yaml中的若干字段，帮助我们找到你的数据源。默认情况下，数据集会被下载到当前目录的data/downloaded_datasets下，如果你下载到了其他地方，请将根目录填入dataset_root字段。 |
| ```yaml |
| DATASETS: |
| dataset_root: "/path/to/your/dataset/root" |
| ``` |
|
|
| ### Step5: 评测 |
|
|
| run_audio.sh为评测入口，你可以通过`--help`取得帮助 |
| |
| 例如，我们希望跑Kimi-Audio在全部数据集上的结果： |
| ``` |
| bash run_audio.sh --model Kimi-Audio --data all --skip-eval |
| ``` |
| 默认情况下，推理结果文件、评测结果文件、指标报告文件将生成在当前目录的eval_results目录下，你可以通过传递--work-dir改变这一行为。 |
| |
| 使用--skip-eval可以让模型只推理，不评测，这样有助于保持你的GPU高效运转。 |
| 推理完毕后，你只需要重新运行一次，即可展开评测，你可以通过添加--reeval参数来强制对数据集重新评测，这不会触发重新推理，但会重新生成指标报告。 |
| |
| Note: 我们默认的LLM方式是gpt-4o-mini，你需要设定你自己的API KEY来启用。未来我们将支持更多评测模型。 |
| ``` |
| export OPENAI_API_KEY=your_api_key |
| bash run_audio.sh --model Kimi-Audio --data all --reeval |
| ``` |
| |
| 目前已经支持的模型、数据集和评测模型列表如下 |
| |
| **模型** |
| |
| - **Baichuan Series**: Baichuan-Audio-Base, Baichuan-Audio-Instruct |
| - **Qwen Series**: Qwen2-Audio-7B, Qwen2-Audio-7B-Instruct, Qwen2.5-Omni-7B |
| - **GLM Series**: GLM4-Voice |
| - **Others**: StepAudio, Kimi-Audio |
| |
| **数据集** |
| | 数据集类型 | 数据集 | |
| |-----------------|----------| |
| | ASR | LibriSpeech, Fleurs-zh, Fleurs-en, AISHELL-1, AISHELL-2, WenetSpeech | |
| | MQA | mmau-test-mini, openbookqa, mmsu, MELD, Nonspeech7k, TUT2017, VocalSound, CochlScene | |
| | OpenQA | alpacaeval_full, commoneval, advbench, ifeval | |
| | RefQA | ClothoAQA, sd-qa, OpenAudioBench | |
|
|
| - 数据集的类型、归属等更多信息，可以查看相关数据集的实现。 |
|
|
| ## 添加数据集 |
|
|
| 我们相信ALMEvalKit的最大价值不是复现某个已有结果，而是提供一种简单的机制帮助用户添加自己的数据集和模型，并能够与其他模型结果公平比较。 |
|
|
| 我们强烈建议首先阅读[数据集的定义](./almeval/datasets/base.py)了解我们如何对数据集分类，这将帮助你正确的设定新数据集的meta信息，使它们被更正确的使用。 |
|
|
| 要添加数据集，你需要写几行代码，为ALMEvalKit准备一个名为dataset_name.jsonl的jsonl文件。jsonl的每一行是一个json记录，我们要求每一行必须具有的字段是： |
| ``` |
| { |
| "index": int, # 一条数据的唯一标识 |
| "audio_path": str | list[str], # 音频位置 |
| "question": str, # 针对音频的问题或指令，例如"请将音频内容转写为文字"，如果你不需要此字段，请设为空 |
| "answer": str, # ground truth答案，如果你不需要此字段（如Open-QA），请设为空 |
| "subset": str, # 子数据，有时候一个数据集可以被切分为若干个子集，这些子集将被分别评估，独立汇报结果。如果你没有子数据集，填数据集名字即可 |
| } |
| |
| 对于Audio-QA类的数据集，我们要求额外增加一个"audio_content"字段，以文字形式写出内容，以便交给LLM评测模型评测答案是否正确。 |
| { |
| "index": int, # 一条数据的唯一标识 |
| "audio_path": str | list[str], # 音频位置 |
| "question": str, # 针对音频的问题或指令，例如"请将音频内容转写为文字"，如果你不需要此字段，请设为空 |
| "audio_content": str, # 音频的文本形式 |
| "answer": str, # ground truth答案，如果你不需要此字段（如Open-QA），请设为空 |
| "subset": str, # 子数据，有时候一个数据集可以被切分为若干个子集，这些子集将被分别评估，独立汇报结果。如果你没有子数据集，填数据集名字即可 |
| } |
| ``` |
| [下载数据集](./data/download_benchmark.py)表明了我们如何下载&处理数据，你可以拿来参考。 |
| |
| 完成此文件后，你可以将你的数据集添加到适当的类别下，一般而言，继承此类别的父类并填写一些字段后，你的数据集就可用了。例如： |
| ``` |
| class Vocalsound(AudioMQADataset): |
| DATASET_NAME = 'VocalSound' |
| DATASET_SERIES = 'VocalSound' |
| AUDIO_TYPE = 'AudioEvent' |
| ``` |
| 这表明，数据集vocalsound是一个MQA数据集（单选题），它所属的数据集系列是vocalsound，它的AUDIO_TYPE标记为"AudioEvent"，说明此数据集是与声音事件（非语音）有关的数据集，这将会在评测时影响一些模型的评测行为。 |
| |
| 如果你将其下载到数据集缓存目录下，现在你就可以在任意模型上评测此数据集了 |
| ```bash |
| bash run_audio.sh --model Kimi-Audio --data vocalsound |
| ``` |
| 如果你将此文件保存在了其他位置，请在config.yaml中告诉我们 |
| ```yaml |
| DATASETS: |
| dataset_root: "/path/to/your/dataset/root" |
| datasets: |
| #example: |
| example: "/path/to/your/dataset/example.jsonl" |
| Vocalsound: "/path/to/your/dataset/VocalSound.jsonl" |
| ``` |
| |
| ## 添加模型 |
| |
| 在ALMEvalKit评测你的模型也十分容易，你只需要实现generate_inner方法即可，此方法的签名是： |
|
|
| ``` |
| def generate_inner(self, msg:dict) -> (str, str) |
| ``` |
| **msg** 就是从数据集中的一条数据，它的格式是： |
| ```python |
| { |
| "index": int, # 即数据集中一条数据的index，见上 |
| "audio": list[str] # 大部分情况下长度是1，取audio[0]即可获得此条数据的音频 |
| "text": str # 即数据的"question"字段，可能为空 |
| "meta": dict # 数据集的meta信息，如audio_type, name，task等存在这里，如果数据集的一条数据有meta字段，也将会被吸入此字段中 |
| } |
| ``` |
|
|
| 此函数的返回是 prompt:str, result:str，prompt为实际送入模型推理的文本，result为模型推理结果。 |
|
|
| **注意** "实际送入模型推理的文本"不一定等于`msg['text']`，因为我们可以在运行时设定规则篡改它，通常我们会实现一个`get_prompt(msg) -> text`来做这件事。 |
|
|
| **添加一个模型的最好方式就是copy一个已经实现的模型照猫画虎** |
|
|
| ## Call for contribution |
|
|
| 我们希望社区在如下方面共建一个公平、高效、统一的音频大模型评测框架 |
|
|
| - 增加功能，修改bug，提高代码质量和易用性 |
| - 支持更多模型和数据集 |
| - 提高可读性，贡献examples和docs |
|
|
| 受限于我们所掌握的信息，我们无法为每个模型找到不同任务/数据集下的最佳prompt，我们也欢迎社区提供最佳实践，使得我们的leaderboard能够更加真实的反应模型的极限能力。 |
|
|
| 我们推荐使用[pre-commit](https://pre-commit.com/)来自动格式化你的代码，使你的代码规范与项目保持一致。 |
|
|
