# 任务书：用 QLoRA 微调 Qwen2.5-7B-Instruct 回答 PubMedQA，比较微调前后效果

## 1. 背景

很多研究生想把开源大模型用到自己领域的数据上，最常见的做法是用 LoRA / QLoRA 在单张 GPU 上做指令微调。真正动手时会卡在：模型怎么下载、显存够不够、数据整理成什么格式、LLaMA-Factory 的配置怎么写、训练参数怎么设、训练完怎么评估、微调到底有没有用。

PubMedQA 是生物医学问答的标准基准：给出一篇 PubMed 摘要（去掉结论部分）和一个研究问题，回答 yes / no / maybe。它有专家标注集，公开基线多，适合用来检验微调是否真的带来提升。

本任务要求你从公开模型与数据开始，在租用的 GPU 上完成一套完整、可复现、能和已发表结果对照的微调与评估。

## 2. 研究问题

1. Qwen2.5-7B-Instruct 不微调（零样本）在 PubMedQA 专家标注测试集上的准确率和 macro-F1 是多少？
2. 用 QLoRA（4 bit）在训练集上微调后，准确率和 macro-F1 提升多少？三个类别（尤其是 maybe）各自的表现如何变化？
3. 提升是否稳定，不是随机波动？（至少给出置信区间；条件允许时比较不同随机种子或训练数据量）
4. 结果与已发表的 PubMedQA 结果（人类、BioBERT、GPT 系列、Med-PaLM 等）相比处于什么水平？差异来自哪里？
5. 模型在哪些问题上答错？错误主要是什么类型？

## 3. 模型与数据

- 模型：`Qwen/Qwen2.5-7B-Instruct`（Hugging Face，或 ModelScope 镜像），记录下载来源、版本（commit）与 SHA256。
- 数据：PubMedQA，官方仓库 https://github.com/pubmedqa/pubmedqa ，Hugging Face `qiaojin/PubMedQA`。
  - `pqa_labeled`：1,000 条专家标注。按官方划分使用：测试集 500 条只用于最终评估，不参与训练和调参。
  - `pqa_artificial`：约 21 万条自动生成标注，可选用来扩充训练数据（只有 yes/no），如果使用，说明抽取的数量与方法。
- 输入只用问题加摘要正文（不含 long answer / 结论），与官方 reasoning-required 设置一致。
- 拿到数据后先核对条数、标签分布，并确认训练与测试之间没有重复。

## 4. 训练与评估要求

1. **算力**：自行通过平台租用一台合适的 GPU 服务器（已授权按需租用），按平台租用算力指南估算显存、CPU、内存和磁盘，选择满足需求的配置并说明理由。一次只租一台。开始前确认 GPU 驱动和 CUDA 可用。
2. **框架**：使用 LLaMA-Factory（https://github.com/hiyouga/LLaMA-Factory ）完成 QLoRA 微调，记录版本；评估可以用 LLaMA-Factory 推理或 vLLM / transformers 自行实现，但微调前后必须用同一套提示词与解析规则。
3. **基线**：先评估未微调模型（零样本，必要时加少样本对照），答案解析规则写清楚，无法解析的输出如何计分要说明。
4. **微调**：QLoRA 4 bit，参数（lora rank、alpha、学习率、轮数、批大小、序列长度等）写明取值理由；保存 LoRA 适配器检查点。
5. **评估**：在 500 条测试集上报告准确率、macro-F1、各类别的精确率与召回率、混淆矩阵；用 bootstrap 给出 95% 置信区间。
6. **图表**：训练损失曲线、微调前后指标对比图、混淆矩阵（前后各一张）。
7. **错误分析**：挑出典型的错误样例（尤其 maybe 类），分析原因（问题本身模糊、摘要信息不足、模型偏向某一类等）。
8. **与已发表结果对照**：至少对照 PubMedQA 原论文的基线和人类表现，以及两到三个近年大模型的公开结果，说明评估设置的差异。可从以下开始：
   - PubMedQA 原论文：https://arxiv.org/abs/1909.06146
   - QLoRA 原论文：https://arxiv.org/abs/2305.14314
   - Med-PaLM 2：https://arxiv.org/abs/2305.09617

## 5. 交付物

所有文件放在工作区的 `qlora_pubmedqa/` 目录下：

| 文件或目录 | 内容 |
| --- | --- |
| `report.pdf` | 中文研究报告：背景、数据、方法与设置、结果、错误分析、与已发表研究的对照、局限性。正文中的每个数字都能在表格或日志中找到出处 |
| `figures/` | 训练曲线、指标对比图、混淆矩阵、错误样例，300 dpi PNG 并附 PDF |
| `tables/` | 总体指标表（含置信区间）、各类别指标表、文献对照表，xlsx 与 csv |
| `adapter/` | 微调得到的 LoRA 适配器（不需要保存合并后的完整模型） |
| `predictions/` | 微调前后在测试集上的逐条预测（问题 ID、原始输出、解析结果、标签） |
| `code/` | 数据准备、LLaMA-Factory 配置、训练、评估、出图脚本和一键复现入口；记录 Python、PyTorch、CUDA、LLaMA-Factory、transformers 版本 |
| `data_manifest.csv` | 模型与数据的来源、版本、大小、SHA256、下载时间，以及划分清单 |
| `methods_notes.md` | 中文操作说明，写给第一次做大模型微调的研究生：QLoRA 是什么、显存怎么估、模型下载与国内镜像、数据整理成 LLaMA-Factory 格式、配置文件逐项说明、常用参数的含义与取值、怎么判断过拟合、怎么评估、常见报错与解决办法 |
| `run_log.md` | 运行记录：每一步做了什么、用时、报错原文与解决办法、每个决策的理由；GPU 型号、所选配置与估算依据、租用起止时间 |
| `comparison.md` | 与已发表研究的对照表和差异解释 |

## 6. 工作方式

- 请独立完成全部步骤。遇到问题先自己查文档、尝试解决，并记录在 `run_log.md`；不要因为可以自行判断的问题停下来等待确认。只有在确实无法继续时才提问。
- 所有数字必须来自实际运行的输出，不得估计或编造。微调没有提升或结果与文献差距大时，如实报告并分析原因。
- 训练结果、适配器、预测和日志要同步回云电脑工作区后再结束 GPU。**全部完成后务必释放租用的 GPU 服务器，数据不需要保留**，并在 `run_log.md` 里写明释放时间。
- 保留全部中间结果。
- 完成后，在对话中用简短的中文总结主要结果，并列出交付物清单与路径。