README.md

# Qwen2.5-VL-3B-LlamaFactory 

## 项目简介

该项目旨在使用组件LLama-Factory基于COCO2017数据集对Qwen2.5-VL-3B-Instruct进行 LORA-SFT

---

## 环境部署

### 1. 拉取镜像

```bash
docker pull harbor.sourcefind.cn:5443/dcu/admin/base/vllm:0.9.2-ubuntu22.04-dtk25.04.2-1226-das1.7-py3.10-20251226
```

### 2. 创建容器

```bash
docker run -dit \
  --name Qwen2_5_SFT \
  --network=host \
  --ipc=host \
  --shm-size=256G \
  --group-add video \
  --cap-add=SYS_PTRACE \
  --device /dev/kfd \
  --device /dev/dri \
  -v /opt/hyhal:/opt/hyhal:ro \
  -v $(pwd):/workspace \
  -w /workspace \
  --privileged \
  -u root \
  --ulimit stack=-1:-1 \
  --ulimit memlock=-1:-1 \
  --security-opt seccomp=unconfined \
  harbor.sourcefind.cn:5443/dcu/admin/base/vllm:0.9.2-ubuntu22.04-dtk25.04.2-1226-das1.7-py3.10-20251226 \
  /bin/bash
```

进入容器
```bash
docker exec -it Qwen2_5_SFT bash
```

---

## 测试步骤

### 1. 拉取代码&安装

```bash
git clone http://developer.sourcefind.cn/codes/bw-bestperf/qwen2.5-vl-3b-llamafactory.git
cd qwen2.5-vl-3b-llamafactory
pip install -e ".[torch,metrics]" --no-build-isolation -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 2. 配置转换数据集

**需要将 COCO2017 数据集转为 llama-factory 可训练的 json 格式，整理为如下结构**

COCO2017数据集链接：https://opendatalab.com/OpenDataLab/COCO_2017 

```bash
├── coco2017
│   ├── annotations
│   │   ├── captions_train2017.json
│   │   ├── captions_val2017.json
│   ├── train2017
│   ├── val2017
│   ├── test2017
```

**将数据集转为image+json的 llamafactory 支持格式**

执行脚本 `scripts/convert_coco2017_captions.py` 生成 `data/coco_train2017_captions.jsonl`

```bash
# --coco-root COCO2017 数据集根目录
# --output 生成的 jsonl 训练文件，默认路径：./data/coco_train2017_captions.jsonl
# --prompt 多模态模型的 human prompt，默认：<image>\nDescribe the image.
python scripts/convert_coco2017_captions.py --coco-root /workspace/DL_DATA/COCO2017
```

转换后数据集格式如下：
```json
{
    "image": "images/001.jpg",
    "conversations": [
        {
            "from": "human",
            "value": "<image>\nDescribe the image."
        },
        {
            "from": "gpt",
            "value": "A red apple on a wooden table"
        }
    ]
}
```

**在 `/data/data_info.json` 注册数据集**
```json
"coco2017_train": {
    "file_name": "coco_train2017_captions.jsonl",
    "formatting": "sharegpt",
    "columns": {
      "messages": "conversations",
      "images": "image"
    }
  },
```



### 3. 下载模型

模型链接：https://modelscope.cn/models/Qwen/Qwen2.5-VL-3B-Instruct/summary


安装 ModelScope

```bash
pip install modelscope
```

下载所需模型

```bash
cd workspace
modelscope download --model Qwen/Qwen2.5-VL-3B-Instruct --local_dir ./Qwen2.5-VL-3B-Instruct
```

---

## SFT脚本（4卡）

脚本 `examples/train_lora/qwen2_5vl_deepspeed_lora_sft.sh`
```bash
#! /usr/bin/env bash
set -ex
DATESTR=`date +%Y%m%d-%H%M%S`
OUTPUT_DIR=outputs/qwen2.5-vl-3b-${DATESTR}
CACHE_DIR=cache
MASTER_PORT=$(shuf -n 1 -i 10000-65535)

export HIP_VISIBLE_DEVICES=0,1,2,3,4,5,6,7
export HSA_FORCE_FINE_GRAIN_PCIE=1
export NCCL_LAUNCH_MODE=GROUP
export TORCH_NCCL_TIMEOUT=3600000
export TORCH_DISTRIBUTED_DEFAULT_TIMEOUT=1800
export NCCL_MAX_NCHANNELS=16
export NCCL_MIN_NCHANNELS=16
export NCCL_P2P_LEVEL=SYS
export ROCBLAS_COMPUTETYPE_FP16R=0
export TOKENIZERS_PARALLELISM=false
# 可以通过设置环境变量临时屏蔽警告
export PYTHONWARNINGS="ignore"
mkdir -p $OUTPUT_DIR
deepspeed --num_gpus 4 --num_nodes 1 --master_port=$MASTER_PORT src/train.py \
    --stage sft \
    --do_train \
    --lora_rank 8 \
    --lora_alpha 8 \
    --lr_scheduler_type constant \
    --flash_attn fa2 \
    --lora_target all \
    --resize_vocab True \
    --optim adamw_torch \
    --model_name_or_path /workspace/Qwen2.5-VL-3B-Instruct \  # 指向下载的模型路径
    --dataset coco2017_train \
    --template qwen2_vl \
    --finetuning_type lora \
    --output_dir $OUTPUT_DIR \
    --overwrite_cache \
    --overwrite_output_dir True \
    --warmup_steps 0 \
    --max_grad_norm 0 \
    --weight_decay 0.1 \
    --ddp_timeout 120000000 \
    --per_device_train_batch_size 8 \
    --gradient_accumulation_steps 8 \
    --logging_steps 100 \
    --learning_rate 2e-5 \
    --num_train_epochs 1 \
    --max_samples 2560 \
    --plot_loss \
    --bf16 \
    --logging_dir /workspace/llama-factory/logs \
    --deepspeed examples/deepspeed/ds_z2_config.json \
    --dataloader_num_workers 32 2>&1 | tee -a ${OUTPUT_DIR}/train.log
```

启动指令

```bash
cd qwen2.5-vl-3b-llamafactory
bash ./examples/train_lora/qwen2_5vl_deepspeed_lora_sft.sh
```

---

## 贡献指南

欢迎对 qwen2.5-vl-3b-llamafactory 项目进行贡献！请遵循以下步骤：

1. Fork 本仓库，并新建分支进行功能开发或问题修复。
2. 提交规范的 commit 信息，描述清晰。
3. 提交 Pull Request，简述修改内容及目的。
4. 遵守项目代码规范和测试标准。
5. 参与代码评审，积极沟通改进方案。

---

## 许可证

本项目遵循 Apache 2.0 许可证，详见 [LICENSE](./LICENSE) 文件。

---

感谢您的关注与支持！如有问题，欢迎提交 Issue 或联系维护团队。