src/web/manual/EvaluationManual_ZH.md

# VenusFactory 评估模块使用指南

## 1. 简介

VenusFactory 评估模块是一个强大的工具，允许您对训练好的蛋白质分析模型进行全面性能评估。通过该模块，您可以在各种数据集上测试模型的预测能力，获取详细的评估指标，并分析模型的优缺点。评估结果可以帮助您比较不同模型的性能，选择最适合特定任务的模型，以及指导进一步的模型改进。

评估模块支持评估多种模型的微调方案，您可以使用预定义的数据集或自定义数据集进行评估，并选择多种评估指标来全面了解模型性能。

## 2. 支持的评估指标

VenusFactory 提供多种评估指标，用于评估模型性能。根据问题类型的不同，适用的评估指标也有所不同。

| 简称 | 指标名称 | 适用问题类型 | 说明 | 优化方向 |
|---------|------|------------|------|---------|
| **Accuracy** | 准确率 (Accuracy) | 单标签/多标签分类 | 正确预测的样本比例，适用于平衡的数据集 | 越大越好 |
| **Recall** | 召回率 (Recall) | 单标签/多标签分类 | 正确识别出的正类比例，关注减少假阴性 | 越大越好 |
| **Precision** | 精确率 (Precision) | 单标签/多标签分类 | 正确预测为正类的比例，关注减少假阳性 | 越大越好 |
| **F1** | F1分数 (F1Score) | 单标签/多标签分类 | 精确率和召回率的调和平均，适用于不平衡的数据集 | 越大越好 |
| **MCC** | Matthews相关系数 (MatthewsCorrCoef) | 单标签/多标签分类 | 综合考虑所有混淆矩阵元素的指标，对不平衡数据集更公平 | 越大越好 |
| **AUROC** | ROC曲线下面积 (AUROC) | 单标签/多标签分类 | 评估不同阈值下的分类性能 | 越大越好 |
| **F1_max** | 最大F1分数 (F1ScoreMax) | 多标签分类 | 不同阈值下的最大F1值，适用于多标签分类 | 越大越好 |

| **Spearman_corr** | Spearman相关系数 (SpearmanCorrCoef) | 回归 | 评估预测值与真实值的单调关系，范围为[-1,1] | 越大越好 |
| **MSE** | 均方误差 (MeanSquaredError) | 回归 | 评估回归模型的预测误差 | 越小越好 |

## 3. 评估界面详解

评估界面分为几个主要部分，每个部分包含特定的配置选项。下面将详细介绍每个部分的功能和设置。

![Model_Dataset_Config](/img/Eval/Model_Dataset_Config.png)

### 3.1 模型和数据集配置

#### 模型路径和蛋白质语言模型选择
- **Model Path**：输入训练好的模型文件路径
  - 通常是训练过程中保存的模型文件（如 `ckpt/model.pt`）
  - 可以是相对路径或绝对路径
  - 确保路径正确，否则评估将无法正确启动

- **Protein Language Model**：从下拉菜单中选择一个预训练模型
  - 必须与训练模型时使用的预训练模型相同
  - 这将确保模型架构的一致性

#### 评估方法和池化方法
- **Evaluation Method**：根据模型架构选择方法
  - `freeze`：冻结预训练模型，只训练分类器
  - `full`：全参数微调，训练所有参数
  - `plm-lora`：使用LoRA (Low-Rank Adaptation)方法训练，减少参数量
  - `dora`：使用DoRA (Weight-Decomposed Low-Rank Adaptation)方法训练
  - `adalora`：使用AdaLoRA (Adaptive Low-Rank Adaptation)方法训练
  - `ia3`：使用IA³ (Infused Adapter by Inhibiting and Amplifying Inner Activations)方法训练
  - `plm-qlora`：使用QLoRA (Quantized Low-Rank Adaptation)方法训练，降低内存需求
  - `ses-adapter`：使用结构增强适配器训练，融合序列和结构信息
  - **必须与训练模型时使用的方法相同，否则将导致评估失败**

- **Pooling Method**：选择池化方法
  - `mean`：平均池化
    - 计算所有token表示的平均值
    - 计算效率高，适合大多数任务
  - `attention1d`：注意力池化
    - 使用注意力机制加权平均token表示
    - 可能提供更好的性能，但计算成本更高
  - `light_attention`：轻量级注意力池化
    - 注意力池化的简化版本
    - 平衡性能和计算效率
  - **必须与训练模型时使用的方法相同**

#### 数据集选择
- **Dataset Selection**：选择数据集来源
  - **Use Pre-defined Dataset**：使用系统预定义的数据集
    - **Evaluation Dataset**：从下拉菜单中选择一个数据集
    - 系统会自动加载数据集的问题类型、标签数量和评估指标
    - 适合快速评估和标准基准测试
  - **Use Custom Dataset**：使用自定义数据集 （具体详见训练模块使用指南中 `7.4 上传数据集到Hugging Fac` 部分）
    - **Custom Dataset Path**：输入Hugging Face数据集路径（格式：`用户名/数据集名`）
    - 需要手动设置问题类型、标签数量和评估指标
    - 适合评估模型在自定数据上的性能

#### 数据集预览
- **Preview Dataset**：点击此按钮预览所选数据集
  - 显示数据集统计信息：训练集、验证集和测试集的样本数量
  - 显示数据集样例：包括序列和标签
  - 帮助验证数据集是否正确加载
  - 可以查看数据格式和内容，确保与模型兼容

#### 问题类型和标签
- **Problem Type**：选择问题类型
  - `single_label_classification`：单标签分类问题
    - 每个样本只属于一个类别
    - 标签通常是整数值，表示类别索引
  - `multi_label_classification`：多标签分类问题
    - 每个样本可能属于多个类别
    - 标签通常是以逗号分隔的类别索引字符串
  - `regression`：回归问题
    - 预测连续值
    - 标签通常是浮点数
  - **必须与训练模型时使用的问题类型相同**

- **Number of Labels**：设置标签数量（分类问题）
  - 对于单标签分类，表示类别总数
  - 对于多标签分类，表示可能的标签总数
  - 对于回归问题，设为1
  - **必须与模型训练时使用的标签数量相同**

#### 评估指标
- **Metrics**：选择评估指标
  - 可以选择多个指标
  - 常用指标包括：`Accuracy,MCC,F1,Precision,Recall,AUROC,F1max,Spearman_corr,MSE`
  - 根据问题类型选择合适的指标：
    - 分类问题：`Accuracy,MCC,F1,Precision,Recall,AUROC`
    - 回归问题：`MSE,Spearman_corr`
  - 选择多个指标可以全面评估模型性能

### 3.2 结构序列配置（仅适用于ses-adapter方法）

- **Structure Sequence**：选择结构序列类型
  - `foldseek_seq`：使用FoldSeek生成的结构序列
    - 基于蛋白质三维结构生成的序列表示
    - 包含结构信息的编码
  - `ss8_seq`：使用8类二级结构序列
    - 表示蛋白质的二级结构元素（如α螺旋、β折叠等）
    - 提供蛋白质局部结构信息
  - 可以同时选择多种类型，增强结构信息的表示
  - **必须与训练模型时使用的结构序列类型相同**

### 3.3 批处理配置

- **Batch Processing Mode**：选择批处理模式
  - **Batch Size Mode**：固定批次大小
    - **Batch Size**：设置每批处理的样本数量，默认为16
    - 适合序列长度相近的数据集
    - 较大的批次可以加速评估，但需要更多内存
  - **Batch Token Mode**：固定Token数量
    - **Tokens per Batch**：设置每批处理的Token数量，默认为10000
    - 适用于序列长度变化大的数据集
    - 自动调整每批的样本数量，确保Token总数接近设定值
    - 有助于优化内存使用和处理效率

### 3.4 评估控制和输出


- **Preview Command**：预览将要执行的评估命令
  - 点击后显示完整的命令行参数
  - 可以帮助您理解评估过程中使用的具体参数
  - 用于验证所有设置是否正确

- **Start Evaluation**：开始评估过程
  - 点击后启动模型评估
  - 评估过程中会显示进度条和状态信息

- **Abort**：中止当前评估过程
  - 可以随时停止正在进行的评估
  - 适用于评估时间过长或发现设置错误的情况

- **Evaluation Status & Results**：显示评估进度和结果
  - 评估进度：当前阶段、进度百分比、已用时间、处理的样本数量
  - 评估结果：各项评估指标及其值
  - 以表格形式展示，清晰直观

- **Download CSV**：下载CSV格式的详细评估指标
  - 评估完成后可见
  - 包含所有计算的评估指标
  - 可用于进一步分析或与其他模型结果比较

## 4. 评估流程指南

以下是使用VenusFactory评估模块的完整流程指南，从模型准备到结果分析。

### 4.1 准备模型和数据集

1. **准备训练好的模型文件**
   - 确保您已经有一个通过训练模块生成的模型文件（如 `ckpt/model.pt`）
   - 记录训练时使用的预训练模型、训练方法和池化方法
   - 确保模型文件路径可访问

2. **选择评估数据集**
   - 可以使用与训练相同的数据集，评估模型在测试集上的性能
   - 也可以使用新的数据集，评估模型的泛化能力
   - 确保数据集格式与训练数据集兼容

### 4.2 配置评估参数

1. **设置模型和预训练模型**
   - 在**Model Path**中输入模型文件的路径
   - 在**Protein Language Model**下拉菜单中选择与训练时相同的预训练模型
   - 确保两者匹配，否则可能导致架构不兼容

2. **选择评估方法和池化方法**
   - 在**Evaluation Method**中选择与训练时相同的方法
   - 在**Pooling Method**中选择与训练时相同的池化方法
   - 这些设置必须与训练时一致，以确保正确加载模型权重

3. **选择数据集**
   - 如果使用预定义数据集：
     - 选择**Use Pre-defined Dataset**
     - 从下拉菜单中选择一个数据集
     - 系统会自动加载相关配置
   - 如果使用自定义数据集：
     - 选择**Use Custom Dataset**
     - 输入Hugging Face数据集路径（格式：`用户名/数据集名`）
     - 手动设置问题类型、标签数量和评估指标

4. **预览数据集**
   - 点击**Preview Dataset**按钮查看数据集统计和样例
   - 确认数据集格式是否正确
   - 查看样本数量和分布
   - 验证标签格式是否与问题类型匹配

5. **设置问题类型和标签**
   - 设置与训练时相同的**Problem Type**
   - 设置与训练时相同的**Number of Labels**
   - 这些设置必须与训练时一致，以确保模型输出层兼容

6. **选择评估指标**
   - 在**Metrics**中输入评估指标，用逗号分隔
   - 分类问题：建议使用`accuracy,mcc,f1,precision,recall,auroc`
   - 回归问题：建议使用`mse,spearman_corr`
   - 选择多个指标可以全面评估模型性能

7. **配置结构序列（如适用）**
   - 如果使用`ses-adapter`方法，选择与训练时相同的**Structure Sequence**类型
   - 可以选择`foldseek_seq`、`ss8_seq`或两者都选
   - 确保数据集中包含相应的结构序列字段

8. **设置批处理参数**
   - 选择**Batch Processing Mode**：
     - **Batch Size Mode**：适合序列长度相近的数据集
     - **Batch Token Mode**：适合序列长度变化大的数据集
   - 设置批次大小或令牌数量
     - 较大的批次可以加速评估，但需要更多内存
     - 如果遇到内存不足错误，尝试减小批次大小

### 4.3 预览和执行评估

1. **预览评估命令**
   - 点击**Preview Command**按钮查看评估命令
   - 检查所有参数是否正确设置
   - 确认命令中包含所有必要的参数
   - 这一步有助于发现潜在的配置错误

2. **开始评估**
   - 点击**Start Evaluation**按钮开始评估
   - 观察评估进度条，了解当前进度
   - 评估过程中可以查看已处理的样本数量和已用时间
   - 根据数据集大小和模型复杂度，评估可能需要几分钟到几小时不等

3. **监控评估过程**
   - 观察进度条和状态信息
   - 如果评估速度过慢，可以考虑增大批次大小
   - 如果遇到内存错误，可以减小批次大小

4. **中止评估（如需要）**
   - 如遇到错误或输入错误参数需中止评估，点击**Abort**按钮

### 4.4 分析评估结果

1. **查看评估指标**
   - 评估完成后，查看评估指标表格
   - 对于分类问题，关注`Accuracy`、`F1`、`Precision`、`Recall`、`MCC`等指标
   - 对于回归问题，关注`MSE`、`Spearman_corr`等指标
   - 分析各项指标，了解模型的优势和不足

2. **下载详细结果**
   - 点击**Download CSV**按钮下载详细评估结果
   - CSV文件包含所有计算的评估指标
   - 可以导入到Excel或其他工具中进行进一步分析
   - 便于与其他模型的结果进行比较

3. **结果解读与决策**
   - 根据评估结果，判断模型性能是否满足需求
   - 如果性能不理想，考虑调整训练参数或使用不同的模型架构