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**。

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

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

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

```bash
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. 快速重建

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

建完后核对关键版本：

```bash
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`。