docs/ENVIRONMENTS.md

环境复现指引

本项目用到 三个互不兼容的 conda 环境。transformers 从 4.37 跨到 4.57，torch 从 2.1 跨到 2.5，不能合并成一个。

环境	python	角色	对应权重
SENTINEL_fix	3.10.19	数据生成 + LLaVA-v1.5 系训练	llava-v1.5-* 三个
LLaMA-Factory-SENTINEL	3.11.14	Qwen2-VL / Qwen2.5-VL 系训练	qwen2-vl-*、qwen2.5-vl-* 三个
eval	3.10.18	评测（lmms-eval + LLaVA 原生评测脚本）	—

每个环境有两份清单：

• env-<name>.yml —— conda env export，含 conda 层依赖，用它重建
• env-<name>-pip.txt —— pip freeze，纯 pip 视角，用于核对版本

---

1. SENTINEL_fix —— 数据生成 + LLaVA-v1.5 训练

关键版本：

python 3.10.19   torch 2.5.1        transformers 4.51.3
vllm 0.7.3       trl 0.13.0         peft 0.14.0
accelerate 1.1.0 deepspeed 0.15.4   flash_attn 2.7.3

这套版本与代码仓库根目录的 requirements.txt 完全对应（transformers / vllm / accelerate / deepspeed / trl / peft 六项逐一吻合），所以按仓库 README 的 Environment Setup 装即可，只需补两点：python 必须是 3.10、flash_attn 用 2.7.3。

conda create -n SENTINEL_fix python=3.10 -y
conda activate SENTINEL_fix
pip install -r requirements.txt
# flash-attn 见 §4

额外依赖（仓库 README 也有写）：

import nltk
nltk.download("wordnet"); nltk.download("punkt_tab")
nltk.download("cmudict"); nltk.download("averaged_perceptron_tagger_eng")

pip install -U pip setuptools wheel
pip install 'spacy[cuda12x]==3.8.0'
python -m spacy download en_core_web_md    # 生成训练数据用
python -m spacy download en_core_web_trf   # Object HalBench 评测用
pip install git+https://github.com/openai/CLIP.git   # YOLO 相关

---

2. LLaMA-Factory-SENTINEL —— Qwen 系训练

关键版本：

python 3.11.14   torch 2.5.1+cu124  transformers 4.57.1
llamafactory 0.9.5.dev0             trl 0.24.0    peft 0.17.1
accelerate 1.11.0                   deepspeed 0.15.4   flash_attn 2.7.4.post1

⚠️ llamafactory 0.9.5.dev0 是 dev 版，不是 PyPI 发行版——是从源码 pip install -e . 装的。重建时需要 clone 上游 LLaMA-Factory 并切到相应版本。

集成步骤（代码仓库的 llamafactory/README.md 有完整说明，这里只列要点）：

1. 按官方教程建环境，**环境名就叫 LLaMA-Factory-SENTINEL**（脚本里硬编码了这个名字）
2. 用本项目的 llamafactory/data 覆盖原框架的
3. 训练数据放 llamafactory/data/ours/
4. 只有三个文件与上游不同，改动都用 #! <-- ADD HERE START --> / #! <-- ADD HERE END --> 标注：
   • src/llamafactory/data/processor/pairwise.py
   • src/llamafactory/data/converter.py
   • src/llamafactory/data/parser.py
5. pip install deepspeed==0.15.4

---

3. eval —— 评测栈（最脆弱，优先按 yml 重建）

关键版本：

python 3.10.18   torch 2.1.2       transformers 4.37.2   ← 老版本，LLaVA-v1.5 原生要求
llava 1.2.2.post1                  lmms_eval 0.2.4
peft 0.9.0       accelerate 0.27.0 deepspeed 0.12.6      flash_attn 2.1.0

⚠️ 两个包是 editable 安装，指向本地源码树，光有 pip 清单装不出来：

包	指向	上游
llava	/home/yilin/LLaVA	github.com/haotian-liu/LLaVA
lmms_eval	/home/yilin/mmrlhf-eval	github.com/julyanghar/mmrlhf-eval（本人 fork）

重建时要先 clone 这两个仓库，再 pip install -e <path>。

⚠️ torch 2.1.2 + flash_attn 2.1.0 是 2024 年的组合，今天 pip 未必还能解出同样的依赖树。这个环境优先用 env-eval.yml 整体重建，不要逐个 pip install。

---

4. flash-attn 的坑（三个环境都涉及）

三个环境的 flash_attn 都是本地编译产物（flash_attn_2_cuda.cpython-3xx-x86_64-linux-gnu.so），conda env export / pip freeze 保住的只是版本号，不是编译结果。重装时：

• 官方 wheel 常滞后于 torch 版本，装不上就找社区预编译轮（如 mjun0812 的仓库）
• 本地 wheel 文件名不可改（pip 靠文件名解析 ABI tag，改了就装不上）
• 症状判断：import flash_attn 直接 undefined symbol = ABI 不匹配，不是缺依赖

SENTINEL_fix 用的那个 wheel 原本在 /data/yilin/SENTINEL/fix/：

flash_attn-2.7.3+cu12torch2.5cxx11abiFALSE-cp310-cp310-linux_x86_64.whl   (191 MB)

对应 cu12 + torch2.5 + cp310 + cxx11abiFALSE。如果归档里带了这个文件，直接 pip install <whl> 最省事。

---

5. 快速重建

conda env create -f env-SENTINEL_fix.yml
conda env create -f env-LLaMA-Factory-SENTINEL.yml
conda env create -f env-eval.yml

建完后核对关键版本：

for e in SENTINEL_fix LLaMA-Factory-SENTINEL eval; do
  echo "--- $e ---"
  conda run -n $e python -c "import torch,transformers;print(torch.__version__, transformers.__version__)"
done

⚠️ 注意：导出这些清单时发现 conda run -n <env> pip freeze 有坑——它可能不切换环境、导出当前 shell 的包列表。核对版本请直接用 <env>/bin/python -m pip freeze。