pertreason-sft

# Qwen3.5-9B × PertReasonQA：SFT 代码与数据交接 ## 1. 交接内容 本项目使用 **Qwen3.5-9B** 对 GPT 标注的细胞扰动响应数据进行监督微调，学习显式文字解释及表达变化预测。原始四组实验均已完成，各训练 2 epoch，无验证集、无测试过程，仅保存第 1、2 epoch 结束的权重。 本目录包含： - 两份可直接训练的 JSONL，以及生成它们所需的原始 GPT 预测、10K 原始问题和基础表达上下文。 - 当时实际使用的原始处理与训练脚本，以及仅调整路径/入口的可移植版本。 - 固定版本的 ms-swift 完整 Git 跟踪文件快照，不依赖原机器的仓库路径。 - 原始四组训练配置、完整日志、状态、checkpoint 元数据与外部权重清单。 - Python 依赖快照、已编译 FlashAttention wheel，以及相关环境检查记录。 **没有**基座权重、训练所得权重、Conda 环境、编译缓存、API 密钥或原始单细胞实验大文件。目录里的 checkpoint 子目录只有用于核验的元数据，不能直接用于推理。权重位置见第 7 节；换机器时需另外传输。 ## 2. 目录结构 ```text README.md MANIFEST.sha256 全部交接文件的 SHA-256，不包含清单自身 code/ prepare_data.py 可移植数据处理入口，无 API 请求 run_experiments.py 可移植八卡训练队列，支持 dry-run 和选择设置 original/ 当时实际运行的两份脚本，未改动 upstream/test_improved_cot.py 固定版本提示构造来源，不作为交接训练入口 diagnostics/ 线性注意力反向传播检查脚本 data/ gpt_terra_all_10000.jsonl 全量训练数据 gpt_terra_correct_5311.jsonl 预测与参考标签一致的训练数据 data_report.json 统计、策略、长度与原始文件哈希 source_manifest.jsonl 逐样本来源与正确性，不输入模型 source/ model_outputs/gpt-5.6-terra/predictions_10k.jsonl data/sampled_data/*.jsonl 8 个原始问题文件，合计 10K configs/original/ 四组真实配置和 ZeRO-2 配置，保留历史路径 results/ status.json 原训练队列完成状态 checkpoint_inventory.json 外部权重绝对路径、大小、epoch、step logs/ 四组完整训练日志 <setting>/ args、逐步指标及 checkpoint 元数据 environment_checks/ 原环境检查和 FlashAttention 编译记录 environment/ versions.json Python、全部包版本、仓库 commit hardware_snapshot.txt 交接时的硬件/CUDA 查询，非历史采样记录 requirements.snapshot.txt 去掉本地 wheel/源码路径的其余依赖精确版本 requirements.freeze.original.txt 原环境 pip freeze，仅供追溯 wheels/ FlashAttention 和 decord 的本地 wheel third_party/ms-swift/ 实际使用的框架源码快照，包含原许可证 scripts/verify_handoff.py 无 GPU 的交接校验脚本 docs/ 数据说明、原运行说明与可移植修改 diff ``` ## 3. 先验证，再使用 在本目录执行，校验只使用 Python 标准库，不会启动训练： ```bash python scripts/verify_handoff.py ``` 它校验文件哈希、10,000/5,311 样本数、教师输出一致性、正确子集筛选，以及历史四组训练完成状态。它**不验证生物学机制正确性、不重新测评模型，也不验证外部权重文件的完整性**。 交接包封存后新增文件不在原清单内；修改已有文件将导致校验失败。原始路径保留在历史报告中是有意设计，并不表示迁移后还必须访问这些路径。 ## 4. 数据如何构建与学习 ### 4.1 原始预测与参考答案 原始文件每行包含题目条件、`true_label`、GPT 的 `pred_label`、`reasoning`、`confidence` 等。参考标签来自原始问题的 `input.label`；预测标签与解释来自教师回答。原始调用记录原样保留供追溯，本项目无需再次调用教师 API。 - 全量数据：10,000 条，保留原始教师预测，**包括 4,689 条与参考标签不一致的预测**，没有改写为标准答案。 - 正确子集：5,311 条，筛选规则为 `pred_label.strip().lower() == true_label.strip().lower()`，未按置信度筛选。 - 标签一致率 53.11% 不是解释机制的正确率，也不是微调后模型的测评结果。 ### 4.2 模型的输入和输出 训练 JSONL 只包含两轮 `messages`： ```json {"messages":[{"role":"user","content":"原始 zero-shot 提示：扰动类型、细胞类型、扰动、目标基因、基础表达上下文等"},{"role":"assistant","content":"{\"reasoning\":\"教师解释\",\"prediction\":\"unchanged\",\"confidence\":0.74}"}]} ``` 上述只是结构示意，不是真实样本。 - 按 sample ID + 完整 input_data 严格关联原始问题，恢复基础表达上下文。 - 使用固定版本 zero-shot Improved CoT 提示，不将 `true_label`、`input_data.label`、split 标签或参考知识三元组输入模型。 - 输出 JSON 顺序为 `reasoning`、`prediction`、`confidence`，均属于助手监督内容；用户提示不计算训练 loss。 - 显式 `reasoning` 不等同于已验证的真实机制，也不是未提供的内部隐藏推理文本。 - 使用 Qwen3.5 模板核验，长度为 506–693 tokens，max_length=1024，原处理未截断、未丢弃样本。 这些样本原属 benchmark 测试划分，但已用于训练，因此不能再作为独立测试数据。科学性与字段说明见 `docs/DATA_NOTES.md`。 ## 5. 四组训练设置 | 设置名称 | 数据量 | 训练方式 | 学习率 | Epoch | 八卡优化步数 | |---|---:|---|---:|---:|---:| | `all10k_full` | 10,000 | 语言模型全参数，ZeRO-2 | 1e-5 | 2 | 626 | | `all10k_lora` | 10,000 | LoRA，八卡 DDP | 1e-4 | 2 | 626 | | `correct5311_full` | 5,311 | 语言模型全参数，ZeRO-2 | 1e-5 | 2 | 332 | | `correct5311_lora` | 5,311 | LoRA，八卡 DDP | 1e-4 | 2 | 332 | 共同参数： - 单机八卡；每卡 batch=2，梯度累积=2，有效全局 batch=32。 - BF16、FlashAttention、梯度检查点，`use_reentrant=false`；不 packing、不 padding-free。 - AdamW (`adamw_torch`)，weight_decay=0.01，max_grad_norm=1.0，cosine 调度，warmup_ratio=0.03。 - seed/data_seed=42；`split_dataset_ratio=0`，`eval_strategy=no`。 - `save_strategy=epoch`，`save_total_limit=2`，`save_only_model=true`。 - LoRA：rank=16、alpha=32、dropout=0.05、`target_modules=all-linear`。 - 文本任务下冻结视觉塔和视觉对齐部分；“全参数”指语言模型部分，不是整个多模态模型的每个参数。 - `enable_thinking=false`，使用显式解释 JSON；`loss_scale=ignore_empty_think` 排除空 think 前缀。 - **每组独立从相同基座加载，不继承上一组训练结果；四组依次运行，每组独占八卡。** ## 6. 环境与复现方式 ### 6.1 原环境版本 | 组件 | 原环境版本 | |---|---| | Python | 3.11.18 | | ms-swift | 4.7.0.dev0；commit `2286b03515bd3885bcd3a11b9dfe7fef0b02e25f` | | PyTorch | 2.10.0+cu128，运行时 CUDA 12.8 | | Transformers | 5.19.0 | | FlashAttention | 2.8.3.post1，本地源码编译 | | fla-core / TileLang | 0.6.0 / 0.1.15 | | Triton / DeepSpeed | 3.6.0 / 0.18.8 | | PEFT / Accelerate | 0.18.1 / 1.15.0 | | datasets / NumPy | 4.8.4 / 1.26.4 | | 系统 CUDA toolkit / 驱动 | 12.9 / 570.148.08，训练配置未改动这些系统组件 | 原运行使用八张约 80 GB 的 NVIDIA L20Y。交接时硬件查询另存为 `environment/hardware_snapshot.txt`。**本地 FlashAttention 编译日志包含 SM90 架构目标，因此随附 wheel 不是任意 GPU 都可用的通用二进制。** 接收端需检查 GPU 架构、Python、PyTorch/CUDA 与 ABI 兼容性；若不兼容应在目标 Conda 环境中重新编译相同版本，不能直接假定 wheel 可用。 **必须保留 `FLA_TILELANG=1`。** 原环境采用该后端完成 Qwen3.5 线性注意力的真实反向传播与训练；可移植训练入口自动设置此变量。不要只确认模型能前向加载就认定训练环境可用，也不要任意降级 Transformers。 ### 6.2 换服务器：先准备独立环境和基座 移动整个交接目录即可；运行入口会优先使用随包 ms-swift 源码，并自动解析本目录的数据位置，不需要保留 `/root/miniconda3/...` 的历史布局。 以下是与原环境相近的安装顺序，不是跨平台保证。仅在新建环境中执行，不要覆盖他人的现有训练环境： ```bash conda create -n qwen35-handoff python=3.11.18 -y conda activate qwen35-handoff cd /path/to/qwen35_9b_pertreasonqa_sft_20261029 python -m pip install torch==2.10.0 torchvision==0.25.0 \ --index-url https://download.pytorch.org/whl/cu128 python -m pip install -r environment/requirements.snapshot.txt python -m pip install --no-deps environment/wheels/decord-0.6.0-py3-none-manylinux2010_x86_64.whl python -m pip install --no-deps -e third_party/ms-swift ``` 在确认目标 GPU/Python/PyTorch 与随附 FlashAttention wheel 兼容之后，才执行： ```bash python -m pip install --no-deps \ environment/wheels/flash_attn-2.8.3.post1-cp311-cp311-linux_x86_64.whl ``` 否则，在目标环境安装构建依赖并源码编译；不要为此擅自替换系统 CUDA 或驱动： ```bash python -m pip install packaging ninja wheel FLASH_ATTENTION_FORCE_BUILD=TRUE MAX_JOBS=4 \ python -m pip install 'flash-attn==2.8.3.post1' --no-build-isolation ``` `requirements.snapshot.txt` 是原环境版本快照，包含 NVIDIA/Linux 专用和可选依赖，并非完整离线安装包。网络可达性、平台 wheel 和系统编译工具需要接收端自行满足；`requirements.freeze.original.txt` 含历史本地路径，仅供追溯，不应直接照装。 将基座完整放在可读位置后，以新的 `--model /path/to/Qwen3.5-9B` 执行第 6.2 节。训练入口默认离线，基座目录需包含完整配置、tokenizer 和权重，不会自动联网补下载缺失文件。首次编译会增加启动时间。 ### 6.3 重新生成数据（可选） 直接训练随附 JSONL 不需要重做处理。如果要核验整个处理过程： ```bash python code/prepare_data.py --model "$MODEL" \ --output-root "$PWD/rebuilt/rebuild_$(date -u +%Y%m%dT%H%M%SZ)" ``` 它读取随附原始数据与固定提示，使用真实模型 tokenizer 编码，不加载基座权重进行训练，也不发送教师 API 请求。输出位于指定目录的 `data/` 内；两份 JSONL 应与 `data/data_report.json` 中的 SHA-256 一致。报告中的绝对路径会随机器变化，不要求报告文件逐字节相同。 若要训练重建数据，给训练入口追加 `--data-dir /path/to/rebuilt/data`。 ### 6.4 可移植版本相对原始脚本的改动 原始脚本完整保留在 `code/original/`。`code/` 入口仅添加：模型/数据/输出路径参数、随包源码优先加载、八卡选择、设置选择、dry-run 和防止误覆盖的数据输出检查。原始超参数、提示、筛选规则、训练顺序和 checkpoint 校验不变。 差异记录见 `docs/portable_changes.diff`。这只是便于交接的工程修改，不代表已经在另一台机器重新完成全部四组训练。