src/web/manual/QAManual_ZH.md

# ProFactory 常见问题解答 (FAQ)

## 安装与环境配置问题

### Q1: 如何正确安装ProFactory？

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

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

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

1. 尝试单独安装报错的依赖：
   ```bash
   pip install 报错的库名
   ```

2. 如果是CUDA相关的库，确保您安装了与您的CUDA版本兼容的PyTorch版本：
   ```bash
   # 例如对于CUDA 11.7
   pip install torch==2.0.0+cu117 -f https://download.pytorch.org/whl/torch_stable.html
   ```

3. 对于某些特殊库，可能需要先安装系统依赖。例如在Ubuntu上：
   ```bash
   sudo apt-get update
   sudo apt-get install build-essential
   ```

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

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

1. 检查CUDA版本：
   ```bash
   nvidia-smi
   ```

2. 在Python中验证PyTorch是否能识别CUDA：
   ```python
   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. **数据或代码问题**：
   - 数据集中的异常值或错误格式导致处理卡住
   - 解决方法：检查数据集，先使用小数据子集测试流程