# BytevalKit-Emb

**Repository Path**: ByteDance/BytevalKit-Emb

## Basic Information

- **Project Name**: BytevalKit-Emb
- **Description**: BytevalKit-Emb is a modular embedding model evaluation framework that implements automated model performance assessment through standardized processes. The framework adopts a configuration-driven design and supports multiple task types and model architectures.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-14
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">⚡️BytevalKit-Emb: 一站式表征模型评测工具</h1>

<p align="center">
    <a href="https://github.com/bytedance/BytevalKit-Emb">
        <img alt="Build" src="https://img.shields.io/badge/BytevalKit Emb-🚀-blue">
    </a>
    <a href="https://github.com/bytedance/BytevalKit-Emb">
        <img alt="Build" src="https://img.shields.io/badge/贡献-欢迎-blue">
    </a>
    <a href="./LICENSE">
        <img alt="License" src="https://img.shields.io/badge/许可证-Apache%202.0-green">
    </a>
    <a href="https://github.com/bytedance/BytevalKit-Emb/releases">
        <img alt="Build" src="https://img.shields.io/badge/BytevalKit Emb-1.0.0-red">
    </a>
</p>

<h4 align="center">
    <p>
        <a href="#概述">概述</a> |
        <a href="#更新日志">更新日志</a> |
        <a href="#安装">安装</a> |
        <a href="#快速开始">快速开始</a> |
        <a href="#配置参数说明">配置说明</a> |
        <a href="#benchmark">Benchmark</a> |
        <a href="#系统架构">系统架构</a> |
        <a href="#许可证">许可证</a> |
        <a href="#联系我们">联系我们</a>
    <p>
</h4>

[English](README.md) | [中文](README_zh-CN.md)

## 概述

BytevalKit-Emb 是一个模块化的表征模型评测框架，通过标准化流程实现模型性能的自动化评估。框架采用配置驱动设计，支持多种任务类型和模型架构。

### 核心功能

- **多种类模型支持**：支持 GritLM/SentenceTransformers/GME 等多种模型调用，同时支持单模态/多模态模型
- **自动化评估流程**：完整的"数据集读取-模型调用-评测指标计算"自动化流程
- **评测方式扩充**：不仅支持MTEB、MMEB评测任务，还支持自定义Retrieval、Classification、Similarity Classification等评测任务
- **灵活配置系统**：基于 YAML 的配置系统，易于定制和扩展
- **可扩展、可复现**：可基于BaseModel、BaseTask快速支持新模型/评测任务；评测过程中完整记录Emb & 相关结果，评测结果可复现Debug

## 更新日志

- 🎉 **[2025.06.13]**：BytevalKit-Emb v1.0.0 首次开源发布
- 📚 **[2025.06.13]**：文档和教程现已上线

## 安装

### 从源码安装

克隆仓库并安装：

> **推荐 Python 版本**：Python 3.9以上

```bash
git clone https://github.com/bytedance/BytevalKit-Emb.git
cd BytevalKit-Emb
pip install -r requirements.txt
```

## 快速开始

更详细的使用说明，包括如何评估模型、添加自定义模型/数据集/评估指标等，请参考 [使用说明](./docs/usage_instrution_zh-CN.md)。

### 基本使用

启动评测任务：

```bash
python3 run.py --yaml-path={workspace}/configs/config.yaml
```
> 示例Yaml配置可参考 [示例Yaml配置](./demo/configs/mteb_classification_task.yaml)

### 配置参数说明
```yaml
DEFAULT:  # 任务级别配置
    task_name: eval_task_1  # 评测任务名
    work_dir: {workspace}/outputs  # 评测推理结果，指标结果等存放目录
DATASET:  # 数据集级别配置
    dataset_xxxx:
        type: mteb_classification  # 评测任务类型，可选 classification, mteb_classification, retrieval, similarity_classification
        name: IFlyTek  # 评测数据集名称
        data_dir: {workspace}/demo/datasets/mteb_classification/IFlyTek-classification  # 评测数据集地址
        data_type: parquet  # 数据集文件格式
        
        # 其他配置参数详见各个评测任务的说明

MODEL:  # 模型级别配置
    model_paraphrase-multilingual-MiniLM-L12-v2:
        type: sentence_transformer  # 模型类型，可选 sentence_transformer, gritlm
        name: paraphrase-multilingual-MiniLM-L12-v2  # 模型名称
        path_or_dir: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2  # 模型保存地址
        model_kwargs:  # 模型加载参数
            revision: "v1.1"
        preprocessors: []  # 推理前处理器
        worker_num: 20  # 推理并发数
```

## Benchmark

> 注意：为了表明我们的框架适用于MTEB、MMEB评测方式，我们使用开源模型在MTEB、MMEB的部分评测集进行框架验证，使用的评测集、评测逻辑来源于MTEB、MMEB评测脚本

> 以下仅为框架评测结果，模型无先后顺序

### MTEB-Classification

|Model                    | IFlyTek-classification | JDReview-classification | MultilingualSentiment-classification | OnlineShopping-classification | TNews-classification | waimai-classification |
|-------------------------|------------------------|-------------------------|--------------------------------------|-------------------------------|----------------------|-----------------------|
| xiaobu-embedding        | 49.29                  | 85.56                   | 76.83                                | 92.75                         | 26.01                | 88.1                  |
| xiaobu-embedding-v2     | 51.21                  | 88.47                   | 79.38                                | 94.5                          | 27.3                 | 88.85                 |
| Conan-embedding-v1      | 51.52                  | 90.07                   | 78.6                                 | 95                            | 27.5                 | 89.7                  |
| gte-base-zh             | 47.67                  | 85.83                   | 75.28                                | 93.8                          | 26.72                | 87.85                 |
| gte-large-zh            | 49.83                  | 88                      | 76.33                                | 91.75                         | 25.8                 | 88.05                 |
| gte-Qwen2-1.5B-instruct | 39.75                  | 80.49                   | 67.92                                | 87.6                          | 25.23                | 84.75                 |
| bge-large-zh-v1.5       | 48.21                  | 85.02                   | 74.15                                | 92.74                         | 26.08                | 86.7                  |


### MTEB-Similarity Classification

|Model                    | CMNLI | Ocnli |
|-------------------------|-------|-------|
| xiaobu-embedding        | 55.3  | 55.93 |
| xiaobu-embedding-v2     | 51.44 | 51.27 |
| Conan-embedding-v1      | 54.46 | 51.38 |
| gte-base-zh             | 63.04 | 60.8  |
| gte-large-zh            | 76.2  | 73.03 |
| gte-Qwen2-1.5B-instruct | 53.27 | 53.65 |
| bge-large-zh-v1.5       | 67.66 | 62.59 |

### MTEB-Retrieval(NDCG@10)

|                     | CmedqaRetrieval | CovidRetrieval | DuRetrieval | MedicalRetrieval | MMarcoRetrieval | T2Retrieval | VideoRetrieval |
|---------------------|-----------------|----------------|-------------|------------------|-----------------|-------------|----------------|
| xiaobu-embedding    | 44.47           | 87.75          | 86.81       | 63.19            | 78.39           | 86.22       | 73.17          |
| xiaobu-embedding-v2 | 47.38           | 89.5           | 89.68       | 67.98            | 82.26           | 85.59       | 80.08          |
| Conan-embedding-v1  | 47.78           | 91.23          | 88.79       | 67.13            | 82.27           | 83.79       | 80.29          |
| gte-base-zh         | 44.57           | 75.71          | 84.09       | 65.02            | 77.71           | 83.91       | 74.38          |
| gte-large-zh        | 43.42           | 88.44          | 85.65       | 62.81            | 77.52           | 82.95       | 73.01          |
| bge-large-zh-v1.5   | 41.81           | 73.03          | 88.76       | 57.35            | 78.77           | 84.29       | 70.89          |

### MMEB

|Model                     | ChartQA | DocVQA | ImageNet-1K | ImageNet-A | ImageNet-R | MSCOCO_t2i | ObjectNet | OK-VQA | VisDial |
|--------------------------|---------|--------|-------------|------------|------------|------------|-----------|--------|---------|
| gme-Qwen2-VL-2B-Instruct | 8.3     | 17.5   | 26.5        | 12.5       | 60.1       | 53.5       | 31.1      | 11.8   | 30.1    |
| gme-Qwen2-VL-7B-Instruct | 15.3    | 33.6   | 65.2        | 42.3       | 87.1       | 71.1       | 66.6      | 32.3   | 62.5    |

## 系统架构

### 架构设计

<div align="center">
    <img src="./docs/assets/architecture_zh-CN.png" />
</div>

## 贡献

该项目由BytevalKit团队开发，开发成员：

```
{Zirui Guo, Hanyu Li, Shenwei Huang}, Yaling Mou, Xianxian Ma, 
Ming Jiang, Haizhen Liao, Jingwei Sun, Binbin Xing

{*} Equal Contributions.
```

我们也感谢抖音应用算法团队的支持：

```
Jiefeng Long, Zhihe Wan, Zhenming Sun, Yongchao Liu, Xulei Lou, Shuang Zeng, Xing Lin, Chao Wang, 
Fubang Zhao, QingSong Liu, Song Chen, Xiao Liang, Yixing Chen, Mingyu Guo, Bolun Cai, 
Yi Lin, Junfeng Yao, Chao Feng, Jiao Ran
```

以及产品设计和Byteval平台侧提供的支持：

```
Ziyu Shi, Zhao Lin, Yang Li, Jing Yang, Zhen Wang, Guojun Ma
```

以及AI platform团队的成员:

```
Huiyu Yu, Lin Dong, Yong Zhang
```

我们欢迎各种形式的贡献！请查看我们的[贡献指南](CONTRIBUTING.md)了解详情。

## 引用

如果您在研究中使用了 BytevalKit-Emb，请考虑引用：

```bibtex
@misc{BytevalKit-Emb-2025,
  title={BytevalKit-Emb: 表征模型综合评测框架},
  author={BytevalKit},
  year={2025},
  howpublished={\url{https://github.com/bytedance/BytevalKit-Emb}}
}
```

## 许可证

BytevalKit-Emb 使用 [Apache License 2.0](LICENSE) 许可证。

## 联系我们

如果你有任何问题，欢迎随时与我们联系：BytevalKit@bytedance.com