# VILA Dataset Usage Guide

## 当前可用的使用资料

### 1. 通用多模态数据集文档

**位置**: `scripts/multimodal/README.md`

这是通用的多模态训练文档，主要针对LLaVA数据集，但VILA可以使用相同的流程：

```bash
# 训练脚本
bash scripts/multimodal/run_finetune_multi_modal_stage2.sh
```

### 2. Qwen-VL 训练示例

**位置**: `examples/finetune_qwenvl.py`

这是VILA和ShareGPT4V实际使用的训练脚本。关键代码：

```python
# 第72行：使用custom_multi_modal backend加载数据集
dataset = Dataset(data_args, backend="custom_multi_modal")

# 第139-143行：使用DataCollatorForQwenVL进行批处理
data_collator = DataCollatorForQwenVL(
    processor=processor,
    tokenizer=model.tokenizer,
    bd_size=getattr(model_args, "bd_size", None) if model_args.mdm else None,
)
```

### 3. 数据集实现代码

**位置**: `src/lmflow/datasets/multi_modal_dataset.py`

- `CustomMultiModalDataset` 类（第157-270行）：数据集加载和标准化
- `DataCollatorForQwenVL` 类（第23-155行）：批处理和数据整理

### 4. 数据集加载入口

**位置**: `src/lmflow/datasets/dataset.py`

- 第130-137行：通过 `backend="custom_multi_modal"` 加载

## VILA数据集使用方法

### 基本使用步骤

1. **准备数据格式**

VILA数据集需要是JSON格式，每个样本包含：
```json
{
  "image": "path/to/image.jpg",  // 或 "image_path", "image_paths", "images"
  "conversations": [              // 或 "messages"
    {
      "from": "human",           // 或 "role": "user"/"human"
      "value": "用户的问题"       // 或 "text"/"content"
    },
    {
      "from": "gpt",             // 或 "role": "assistant"/"gpt"/"bot"
      "value": "助手的回答"
    }
  ]
}
```

2. **运行训练**

使用 `examples/finetune_qwenvl.py`：

```bash
python examples/finetune_qwenvl.py \
    --model_name_or_path Qwen/Qwen2.5-VL-3B-Instruct \
    --dataset_path /path/to/vila_dataset.json \
    --image_folder /path/to/images \
    --output_dir ./output_models/vila_finetuned \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 4 \
    --learning_rate 2e-5 \
    --num_train_epochs 3 \
    --bf16 True
```

### 关键参数说明

- `--dataset_path`: VILA数据集的JSON文件路径
- `--image_folder`: 图像文件所在的文件夹路径
- `--model_name_or_path`: 使用的模型（通常是Qwen2.5-VL系列）
- `backend="custom_multi_modal"`: 在代码中自动设置，无需手动指定

### 数据格式要求

**支持的图像字段**（按优先级）：
1. `image` (字符串)
2. `image_path` (字符串)
3. `image_paths` (列表，取第一个)
4. `images` (列表，取第一个)

**支持的对话字段**：
1. `conversations` (优先)
2. `messages`

**消息格式**：
- `from` 字段：`human`, `gpt`, `assistant`, `bot`, `user`
- `role` 字段：自动映射到 `human` 或 `gpt`
- 内容字段：`value`, `text`, `content`

## 注意事项

### 1. 图像添加限制

⚠️ **重要**：当前实现中，图像**只在第一个human消息中添加**。

如果VILA数据集需要在多个轮次中使用图像，可能需要修改 `CustomMultiModalDataset.__getitem__` 方法。

### 2. 图像路径处理

- 图像路径会通过 `osp.join(self.image_folder, data['image'])` 拼接
- 如果 `data['image']` 是绝对路径，需要确保路径正确
- 建议使用相对路径，相对于 `image_folder`

### 3. 数据验证

在加载数据时，会：
- 自动标准化数据格式
- 丢弃没有图像或对话的样本
- 打印保留/丢弃的样本数量

## 示例数据格式

### 单图像单轮对话
```json
{
  "image": "COCO_val2014_000000391895.jpg",
  "conversations": [
    {"from": "human", "value": "这张图片里有什么？"},
    {"from": "gpt", "value": "图片中有一个男人正在切一块披萨。"}
  ]
}
```

### 多轮对话（图像只在第一轮添加）
```json
{
  "image": "COCO_val2014_000000391895.jpg",
  "conversations": [
    {"from": "human", "value": "这张图片里有什么？"},
    {"from": "gpt", "value": "图片中有一个男人正在切一块披萨。"},
    {"from": "human", "value": "他在做什么？"},
    {"from": "gpt", "value": "他正在用刀切披萨。"}
  ]
}
```

## 相关文件位置

- **训练脚本**: `examples/finetune_qwenvl.py`
- **数据集类**: `src/lmflow/datasets/multi_modal_dataset.py`
- **数据集加载**: `src/lmflow/datasets/dataset.py`
- **训练管道**: `src/lmflow/pipeline/finetuner.py` (第484-489行)
- **多模态README**: `scripts/multimodal/README.md`

## 缺少的文档

目前项目中**没有专门针对VILA的使用文档**，只有：
- ✅ 通用的多模态训练文档（针对LLaVA）
- ✅ 代码实现（通用的CustomMultiModalDataset）
- ❌ VILA特定的使用示例
- ❌ VILA数据格式的详细说明
- ❌ VILA训练的最佳实践

## 建议

如果需要完善VILA的使用文档，建议添加：
1. VILA数据集的下载和准备说明
2. VILA特定的训练配置示例
3. VILA数据格式的详细说明
4. 常见问题和解决方案
