src/web/manual/QAManual_ZH.md

ProFactory 常见问题解答 (FAQ)

安装与环境配置问题

Q1: 如何正确安装ProFactory？

回答：你可以在根目录的README.md文件中找到安装的步骤。

Q2: 安装时报错"无法找到特定的依赖库"，如何解决？

回答：这种情况通常有几种解决方法：

1. 尝试单独安装报错的依赖：

   pip install 报错的库名
   

2. 如果是CUDA相关的库，确保您安装了与您的CUDA版本兼容的PyTorch版本：

   # 例如对于CUDA 11.7
   pip install torch==2.0.0+cu117 -f https://download.pytorch.org/whl/torch_stable.html
   

3. 对于某些特殊库，可能需要先安装系统依赖。例如在Ubuntu上：

   sudo apt-get update
   sudo apt-get install build-essential
   

Q3: 如何检查我的CUDA是否正确安装？

回答：您可以通过以下方式验证CUDA是否正确安装：

1. 检查CUDA版本：

   nvidia-smi
   

2. 在Python中验证PyTorch是否能识别CUDA：

   import torch
   print(torch.cuda.is_available())  # 应该返回True
   print(torch.cuda.device_count())  # 显示GPU数量
   print(torch.cuda.get_device_name(0))  # 显示GPU名称
   

3. 如果PyTorch不能识别CUDA，请确保安装了匹配的PyTorch和CUDA版本。

硬件与资源问题

Q4: 运行时出现"CUDA out of memory"错误，怎么解决？

回答：这个错误表示您的GPU显存不足。解决方法有：

1. 减小批量大小（batch size）：这是最直接有效的方法。在训练配置中将batch size减小一半或更多。

2. 使用更小的模型：选择参数更少的预训练模型，如从ProtBERT切换到ESM-1b等。

3. 启用梯度累积：增加gradient_accumulation_steps参数值，例如设为2或4，这样可以在不减小有效批量大小的情况下减少内存使用。

4. 使用混合精度训练：在训练选项中启用fp16选项，可以显著减少显存使用。

5. 减少序列最大长度：如果您的数据允许，可以减小max_seq_length参数。

Q5: 如何确定我应该使用多大的batch size？

回答：确定合适的batch size需要平衡内存使用和训练效果：

1. 从小开始，逐步增加：从较小的值（如4或8）开始，逐步增加直到内存接近极限。

2. 参考基准：对于常见的蛋白质模型，大多数研究使用16-64的batch size，但这取决于您的GPU内存和序列长度。

3. 监控训练过程：较大的batch size可能使每轮训练更稳定，但可能需要更高的学习率。

4. 显存不足时的经验法则：如果出现内存错误，首先尝试将batch size减半。

数据集问题

Q6: 如何准备自定义数据集？

回答：准备自定义数据集需要以下步骤：

1. 格式化数据：数据应组织成CSV文件，至少包含以下列：

   • sequence：蛋白质序列，使用标准氨基酸字母表示
   • 标签列：根据您的任务类型，可以是数值（回归）或类别（分类）

2. 分割数据：准备训练集、验证集和测试集，例如train.csv、validation.csv和test.csv。

3. 上传到Hugging Face：

   • 在Hugging Face上创建数据集仓库
   • 上传您的CSV文件
   • 在ProFactory中使用用户名/数据集名格式引用它

4. 创建数据集配置：配置应包含问题类型（回归或分类）、标签数量和评估指标等信息。

Q7: 导入我的数据集时显示格式错误，如何解决？

回答：常见的格式问题及其解决方案：

1. 列名不正确：确保CSV文件包含必要的列，特别是sequence列和标签列。

2. 序列格式问题：

   • 确保序列只包含有效的氨基酸字母（ACDEFGHIKLMNPQRSTVWY）
   • 移除序列中的空格、换行符或其他非法字符
   • 检查序列长度是否在合理范围内

3. 编码问题：确保CSV文件使用UTF-8编码保存。

4. CSV分隔符问题：确保文件使用正确的分隔符（通常是逗号）。您可以使用文本编辑器查看并修正。

5. 缺失值处理：确保数据中没有缺失值，或者适当处理缺失值。

Q8: 我的数据集很大，系统加载很慢或崩溃，怎么办？

回答：对于大型数据集，您可以：

1. 减小数据集规模：如果可能，先用数据子集测试您的方法。

2. 增加数据加载效率：

   • 使用batch_size参数控制每次加载的数据量
   • 启用数据缓存功能以避免重复加载
   • 预处理数据以减小文件大小（例如，移除不必要的列）

3. 数据集分片：将大型数据集分成多个小文件，逐个处理。

4. 增加系统资源：如果可能，增加RAM或使用具有更多内存的服务器。

训练问题

Q9: 训练过程中突然中断，如何恢复？

回答：处理训练中断的方法：

1. 检查检查点：系统会定期保存检查点（通常在ckpt目录下）。您可以从最近的检查点恢复：

   • 查找最后保存的模型文件（通常命名为checkpoint-X，其中X是步数）
   • 在训练选项中指定该检查点路径作为起始点

2. 使用断点恢复功能：在训练配置中启用断点恢复选项。

3. 保存更频繁的检查点：调整保存检查点的频率，例如每500步保存一次而不是默认的每1000步。

Q10: 训练速度很慢，如何加速？

回答：加速训练的方法：

1. 硬件方面：

   • 使用更强大的GPU
   • 使用多GPU训练（如果支持）
   • 确保数据存储在SSD而不是HDD上

2. 参数设置：

   • 使用混合精度训练（启用fp16选项）
   • 增加batch size（如果内存允许）
   • 减少最大序列长度（如果任务允许）
   • 减少验证频率（eval_steps参数）

3. 模型选择：

   • 选择较小的预训练模型
   • 使用参数高效的微调方法（如LoRA）

Q11: 训练时损失值不下降或出现NaN值，这是什么问题？

回答：这通常表示训练出现了问题：

1. 损失不下降的原因和解决方法：

   • 学习率过高：尝试减小学习率，例如从5e-5降到1e-5
   • 优化器问题：尝试不同的优化器，如从Adam切换到AdamW
   • 初始化问题：检查模型初始化设置
   • 数据问题：验证训练数据是否有异常值或标签错误

2. NaN值原因和解决方法：

   • 梯度爆炸：添加梯度裁剪，设置max_grad_norm参数
   • 学习率过高：大幅降低学习率
   • 数字不稳定性：使用混合精度训练时可能出现，尝试关闭fp16选项
   • 数据异常：检查输入数据中是否有极端值

Q12: 什么是过拟合，如何避免？

回答：过拟合是指模型在训练数据上表现很好，但在新数据上表现差。避免过拟合的方法：

1. 增加数据量：使用更多训练数据或数据增强技术。

2. 正则化方法：

   • 添加dropout（通常设置为0.1-0.3）
   • 使用权重衰减（weight decay）
   • 早停（early stopping）：当验证集性能不再提高时停止训练

3. 简化模型：

   • 使用更少的层或更小的隐藏维度
   • 冻结预训练模型的部分层（使用freeze方法）

4. 交叉验证：使用k折交叉验证来获得更稳健的模型。

评估问题

Q13: 如何解释评估指标？哪个指标最重要？

回答：不同任务关注不同指标：

1. 分类任务：

   • 准确率（Accuracy）：正确预测的比例，适用于平衡数据集
   • F1分数：准确率和召回率的调和平均，适用于不平衡数据集
   • MCC（Matthews相关系数）：综合衡量分类性能，对类别不平衡更稳健
   • AUROC（ROC曲线下面积）：衡量模型区分不同类别的能力

2. 回归任务：

   • MSE（均方误差）：预测值与实际值差异的平方和，越小越好
   • RMSE（均方根误差）：MSE的平方根，与原始数据单位相同
   • MAE（平均绝对误差）：预测值与实际值差异的绝对值平均
   • R²（决定系数）：衡量模型解释方差的比例，越接近1越好

3. 最重要的指标：取决于您的具体应用需求。例如，对于药物筛选，可能会更关注真阳性率；对于结构预测，可能会更关注RMSE。

Q14: 评估结果很差，应该怎么改进？

回答：改进模型性能的常见策略：

1. 数据质量：

   • 检查数据是否有错误或噪声
   • 增加训练样本数量
   • 确保训练集和测试集分布相似

2. 模型调整：

   • 尝试不同的预训练模型
   • 调整学习率、batch size等超参数
   • 使用不同的微调方法（全参数微调、LoRA等）

3. 特征工程：

   • 添加结构信息（如使用foldseek特征）
   • 考虑序列特性（如疏水性、电荷等）

4. 集成方法：

   • 训练多个模型并集成结果
   • 使用交叉验证获得更稳健的模型

Q15: 为什么我的模型在测试集上表现比验证集差很多？

回答：测试集性能下降的常见原因：

1. 数据分布偏移：

   • 训练集、验证集和测试集分布不一致
   • 测试集包含训练中未见过的蛋白质家族或特征

2. 过拟合：

   • 模型对验证集过拟合，因为验证集被用于模型选择
   • 增加正则化或减少训练轮数可能有帮助

3. 数据泄露：

   • 无意中将测试数据信息泄露到训练过程中
   • 确保数据分割在预处理前进行，避免交叉污染

4. 随机性：

   • 如果测试集较小，结果可能受随机性影响
   • 尝试使用不同的随机种子训练多个模型并平均结果

预测问题

Q16: 预测过程太慢，如何加速？

回答：加速预测的方法：

1. 批量预测：使用批量预测模式而不是单序列预测，这样可以更高效地利用GPU。

2. 减少计算：

   • 使用较小的模型或更高效的微调方法
   • 减少序列最大长度（如果可能）

3. 硬件优化：

   • 使用更快的GPU或CPU
   • 确保使用GPU而不是CPU进行预测

4. 模型优化：

   • 尝试模型量化（如int8量化）
   • 导出为ONNX格式可能提供更快的推理速度

Q17: 预测结果与预期相差很大，可能是什么原因？

回答：预测偏差的可能原因：

1. 数据不匹配：

   • 预测的序列与训练数据的分布不同
   • 序列长度、组成或结构特征有较大差异

2. 模型问题：

   • 模型训练不充分或过拟合
   • 选择了不适合任务的预训练模型

3. 参数配置：

   • 确保预测时使用的参数（如最大序列长度）与训练时一致
   • 检查是否使用了正确的问题类型（分类/回归）

4. 数据预处理：

   • 确保预测数据经过与训练数据相同的预处理步骤
   • 检查序列格式是否正确（标准氨基酸字母、无特殊字符）

Q18: 如何批量预测大量序列？

回答：高效批量预测的步骤：

1. 准备输入文件：

   • 创建包含所有序列的CSV文件
   • 文件必须包含sequence列
   • 可选地包含ID或其他标识符列

2. 使用批量预测功能：

   • 进入预测标签页
   • 选择"批量预测"模式
   • 上传序列文件
   • 设置适当的批量大小（通常16-32是良好平衡点）

3. 优化设置：

   • 增加batch size可提高吞吐量（如果内存允许）
   • 减少不必要的特征计算可加快处理速度

4. 结果处理：

   • 预测完成后，系统会生成包含原始序列和预测结果的CSV文件
   • 可以下载此文件进行进一步分析

模型与结果问题

Q19: 我应该选择哪种预训练模型？

回答：模型选择建议：

1. 对于一般任务：

   • ESM-2适用于多种蛋白质相关任务，平衡了性能和效率
   • ProtBERT在某些序列分类任务上表现出色

2. 考虑因素：

   • 数据量：数据少时，较小的模型可能更好（避免过拟合）
   • 序列长度：对于长序列，考虑支持更长上下文的模型
   • 计算资源：资源有限时，选择较小的模型或参数高效的方法
   • 任务类型：不同模型在不同任务上有各自优势

3. 建议策略：如果条件允许，可以尝试几种不同的模型，选择在验证集上表现最好的。

Q20: 如何解释训练过程中的损失曲线？

回答：损失曲线解读指南：

1. 理想曲线：

   • 训练损失和验证损失都平稳下降
   • 两条曲线最终趋于平稳并接近
   • 验证损失在最低点附近稳定

2. 常见模式及其含义：

   • 训练损失持续下降而验证损失上升：过拟合信号，考虑增加正则化
   • 两种损失都停滞在较高值：欠拟合，可能需要更复杂的模型或更长的训练
   • 曲线剧烈波动：学习率可能过高，考虑降低
   • 验证损失比训练损失低：可能是数据集划分问题或批归一化效应

3. 根据曲线调整：

   • 如果验证损失很早就停止改善，考虑早停
   • 如果训练损失下降很慢，尝试增加学习率
   • 如果曲线中有突然跳跃，检查数据问题或学习率调度

Q21: 如何保存和分享我的模型？

回答：模型保存和分享指南：

1. 本地保存：

   • 训练完成后，模型会自动保存在指定的输出目录
   • 完整的模型包括模型权重、配置文件和分词器信息

2. 重要文件：

   • pytorch_model.bin：模型权重
   • config.json：模型配置
   • special_tokens_map.json和tokenizer_config.json：分词器配置

3. 分享模型：

   • Hugging Face Hub：最方便的方式是上传到Hugging Face

     • 创建一个模型仓库
     • 上传您的模型文件
     • 在readme中添加模型描述和使用说明

   • 本地导出：也可以将模型文件夹压缩后分享

     • 确保包含所有必要文件
     • 提供环境要求和使用说明

4. 文档化：无论采用哪种方式分享，都应该提供：

   • 训练数据描述
   • 模型架构和参数
   • 性能指标
   • 使用示例

界面与操作问题

Q22: 界面加载很慢或崩溃，如何解决？

回答：界面问题的解决方法：

1. 浏览器相关：

   • 尝试使用不同的浏览器（Chrome通常兼容性最好）
   • 清除浏览器缓存和cookie
   • 关闭不必要的浏览器扩展

2. 资源问题：

   • 确保系统有足够的内存
   • 关闭其他占用资源的程序
   • 如果在远程服务器上运行，检查服务器负载

3. 网络问题：

   • 确保网络连接稳定
   • 如果通过SSH隧道使用，检查连接是否稳定

4. 重启服务：

   • 尝试重启Gradio服务
   • 在极端情况下，重启服务器

Q23: 为什么我的训练中途停止响应了？

回答：训练停止响应的可能原因和解决方法：

1. 资源耗尽：

   • 系统内存不足
   • GPU显存溢出
   • 解决方法：减小batch size，使用更高效的训练方法，或增加系统资源

2. 进程被终止：

   • 系统OOM（内存不足）杀手终止了进程
   • 服务器超时政策导致长时间运行的进程被终止
   • 解决方法：检查系统日志，使用screen或tmux等工具在后台运行，降低资源使用

3. 网络或界面问题：

   • 浏览器崩溃或网络断开
   • 解决方法：使用命令行运行训练，或确保网络连接稳定

4. 数据或代码问题：

   • 数据集中的异常值或错误格式导致处理卡住
   • 解决方法：检查数据集，先使用小数据子集测试流程