Spaces:
Runtime error
Runtime error
| # 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. 评估界面详解 | |
| 评估界面分为几个主要部分，每个部分包含特定的配置选项。下面将详细介绍每个部分的功能和设置。 | |
|  | |
| ### 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. **结果解读与决策** | |
| - 根据评估结果，判断模型性能是否满足需求 | |
| - 如果性能不理想，考虑调整训练参数或使用不同的模型架构 |