diff --git a/README.md b/README.md index 8519b43126efdcf5b212f116373174aa4deff50c..13a04eb1c8be7a3d451b8dff8fa745642fc3fea7 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,23 @@ -# AISBench大模型精度评测工具evaluate使用方法 +# AISBench大模型精度评测工具evaluate使用说明 ## 工具介绍 -### 工具概述 AISBench大模型精度评测工具evaluate（后简称evaluate工具）提供接口，用于全流程大模型评测以及生成式大模型结果多维分析。 ### 工具依赖 -``` -os: linux -python version: >3.6 -``` + +- OS：Linux +- Python版本：Python 3.7及以上版本 + ## 安装和卸载 ### 安装evaluate 1. 获取whl包`ais_bench_evaluate--py3-none-any.whl`, 用pip安装： - ``` + ```bash pip install ais_bench_evaluate--py3-none-any.whl --force-reinstall ``` 2. 输入`pip show ais_bench_evaluate`确认安装完成，命令行打屏如下： - ``` + ```bash Name: ais-bench-evaluate Version: Summary: ais_bench evaluate @@ -31,7 +30,7 @@ python version: >3.6 Required-by: ``` ### 卸载evaluate -如果要卸载评测工具evaluate，可以使用如下命令： +卸载evaluate工具命令示例如下： ```bash pip uninstall ais_bench_evaluate ``` @@ -46,31 +45,32 @@ from ais_bench.evaluate.interface import dataset_factory, measurement_factory #### 评测数据集类工厂 - 接口原型 -```python -dataset_instance = dataset_factory.get(dataset_name, dataset_path, shot) -``` + + ```python + dataset_instance = dataset_factory.get(dataset_name, dataset_path, shot) + ``` - 参数说明 -|参数名|入参类型|说明|是否必选| -|----|----|----|----| -|**dataset_name**|str|数据集名称，支持的数据集详见附录|是| -|**dataset_path**|str|数据集路径，不设置时会自动下载|否| -|**shot**|int|构造输入中的prompt数量，0 <= shot <= 5|否| + | 参数名 | 入参类型 | 说明 | 是否必选 | + | ------------ | -------- | ------------------------------------------------------------ | -------- | + | dataset_name | str | 数据集名称，支持的数据集详见“附录 > **支持的数据集**”。 | 是 | + | dataset_path | str | 数据集路径，不设置时会自动下载到evaluate安装路径下的dataset目录下。 | 否 | + | shot | int | 构造输入中的prompt数量，0 <= shot <= 5。 | 否 | #### 评测指标类工厂 - 接口原型 -```python -measurement_instance = measurement_factory.get(measurement_name, **kwargs) -``` + ```python + measurement_instance = measurement_factory.get(measurement_name, **kwargs) + ``` - 参数说明 -|参数名|入参类型|说明|是否必选| -|----|----|----|----| -|**measurement_name**|str|评测指标名称，支持的评测指标详见附录|是| -|**kwargs**| - |额外参数，详见附录|否| + | 参数名 | 入参类型 | 说明 | 是否必选 | + | ---------------- | -------- | ------------------------------------------------------- | -------- | + | measurement_name | str | 评测指标名称，支持的评测指标详见“附录 > **评测指标**”。 | 是 | + | kwargs | - | 额外参数，详见“附录 > **评测指标**”。 | 否 | ## 全流程评测使用方法（Evaluator类） ### 导入依赖包 @@ -79,30 +79,33 @@ from ais_bench.evaluate.interface import Evaluator ``` ### API使用介绍 #### Evaluator类 -- 类原型： -```python -class Evaluator(generate_func, dataset_instance, measurement_instance, rank=0): -``` +- 类原型 -- 初始化参数： + ```python + class Evaluator(generate_func, dataset_instance, measurement_instance, rank=0): + ``` +- 初始化参数 -|参数名|入参类型|说明|是否必选| -|----|----|----|----| -|**generate_func**|function object|封装了大模型推理能力的函数对象，输入自然语言，输出自然语言|是| -|**dataset_instance**|BaseDataset|评测数据集类实例|是| -|**measurement_instance**|BaseMeasurement|评测指标类实例|是| -|**rank**|int|多进程推理情况下进程的标号，只有在0号进程中对数据进行评测。|否| + | 参数名 | 入参类型 | 说明 | 是否必选 | + | -------------------- | --------------- | ------------------------------------------------------------ | -------- | + | generate_func | function object | 封装了大模型推理能力的函数对象，输入自然语言，输出自然语言。 | 是 | + | dataset_instance | BaseDataset | 评测数据集类实例。 | 是 | + | measurement_instance | BaseMeasurement | 评测指标类实例。 | 是 | + | rank | int | 多进程推理情况下进程的标号，只有在0号进程中对数据进行评测。 | 否 | #### evaluate（评测接口） -- 功能说明： -进行评测，打屏评测结果，输出评测结果 +- 功能说明 -- 函数原型： -```python -evaluate() -``` -- 返回值： -float, dict + 进行评测，打屏评测结果，输出评测结果。 + +- 函数原型 + + ```python + evaluate() + ``` +- 返回值 + + float, dict ## 生成式大模型结果多维分析使用方法（Filter类） @@ -113,57 +116,65 @@ from ais_bench.evaluate.interface import Filter ### API使用方法 #### Filter类 -- 类原型： +类原型 + ```python class Filter(): ``` #### add_measurement（添加评测指标接口） -- 功能说明： -添加需要用于评测的指标，支持的指标及额外参数详见附录。 +- 功能说明 -- 函数原型： -```python -add_measurement(measurement: str, **kwargs) -``` + 添加需要用于评测的指标，支持的指标及额外参数详见“附录 > **评测指标**”。 -- 返回值： -None +- 函数原型 + + ```python + add_measurement(measurement: str, **kwargs) + ``` +- 返回值 + + None #### do_measuring（执行评测接口） -- 功能说明： -用所有添加的评测的指标对传入的result_dict进行评测。 +- 功能说明 -- 函数原型： -```python -do_measuring(result_dict: dict): -``` + 用所有添加的评测的指标对传入的result_dict进行评测。 -- result_dict格式： +- 函数原型 -|key名|value类型|说明|是否必选| -|----|----|----|----| -|**target_output**|`List[str]`|标杆模型输出列表|是| -|**model_output**|`List[str]`|实际模型输出列表|是| -|**indexs**|`List[int]`|索引|是| + ```python + do_measuring(result_dict: dict): + ``` +- result_dict格式 -三个列表中的元素需要一一对应，列表长度需要一致。 + | key名 | value类型 | 说明 | 是否必选 | + | ------------- | ----------- | ------------------ | -------- | + | target_output | `List[str]` | 标杆模型输出列表。 | 是 | + | model_output | `List[str]` | 实际模型输出列表。 | 是 | + | indexs | `List[int]` | 索引。 | 是 | + 三个List中的元素需要一一对应，List长度需要一致。 -- 返回值： -None + + +- 返回值 + + None #### do_filtering（执行筛选接口） -- 功能说明： -对评测完的结果按照thresholds进行筛选，并且在out_dir下生成 `${pid}_${6位随机字符}_filtering_result.csv` 文件。可选参数thresholds为字典，key为评测指标名称，value为threshold。未配置或错误配置时使用默认threshold，详见附录。 +- 功能说明 -- 函数原型： -```python -do_filtering(out_dir: str, thresholds=None: dict): -``` + 对评测完的结果按照thresholds进行筛选，并且在out_dir下生成 `${pid}_${6位随机字符}_filtering_result.csv` 文件。可选参数thresholds为字典，key为评测指标名称，value为threshold。未配置或错误配置时使用默认threshold，详见附录 > **评测指标**"。 + +- 函数原型 -- 返回值： -pandas.dataframe + ```python + do_filtering(out_dir: str, thresholds=None: dict): + ``` +- 返回值 + + pandas.dataframe ## 附录 @@ -171,24 +182,25 @@ pandas.dataframe |评测数据集名称|说明| |----|----| -|ceval|一个用于基础模型评估的多层次多学科的中文评估套件| -|mmlu|大规模多任务语言理解数据集| -|gsm8k|小学数学题数据集| +|ceval|一个用于基础模型评估的多层次多学科的中文评估套件。| +|mmlu|大规模多任务语言理解数据集。| +|gsm8k|小学数学题数据集。| -### 评测指标细节 +### 评测指标 |评测指标名|说明|结果范围|额外参数|默认threshold(仅用于筛选功能)| |----|----|----|----|----| |accuracy|正确率|0，1|无|>=1| |edit-distance|编辑距离|[0, +∞)|无|<=5| -|bleu|机器翻译质量评估指标|[0, 1]|ngram: int，默认为1，可选：1，2，3，4|>=0.4| -|rouge|自动文本摘要评估指标|[0, 1]|rouge_type: str，默认为rouge-1，可选：rouge-1, rouge-2, rouge-l|>=0.4| -|distinct|实际模型输出的多样性得分|[0, 1]|ngram: int，默认为2，可选：1，2，3，4|>=0.6| +|bleu|机器翻译质量评估指标|[0, 1]|ngram：int，可取值：1，2，3，4，默认为1。|>=0.4| +|rouge|自动文本摘要评估指标|[0, 1]|rouge_type：str，可取值：rouge-1, rouge-2, rouge-l，默认为rouge-1。|>=0.4| +|distinct|实际模型输出的多样性得分|[0, 1]|ngram：int，可取值：1，2，3，4，默认为2。|>=0.6| |abnormal-string-rate|实际模型输出的异常字符率|[0, 1]|无|<=0.3| -|relative-distinct|相对多样性得分|[0, +∞)|ngram: int，默认为2，可选：1，2，3，4|>=0.8| +|relative-distinct|相对多样性得分|[0, +∞)|ngram：int，可取值：1，2，3，4，默认为2。|>=0.8| |relative-abnormal-string-rate|相对异常字符率|[0, +∞)|无|<=1.2| -### 参考样例 -* [全流程精度评测](sample/sample_evaluator.py) -* [生成式大模型结果多维分析](sample/sample_filter.py) \ No newline at end of file +### 参考样例 + +- [全流程精度评测](sample/sample_evaluator.py) +- [生成式大模型结果多维分析](sample/sample_filter.py)